flexpa/sero

Modern JavaScript modules for FHIR

NOTICE THIS REPOSITORY IS UNMAINTAINED AND PRESENTED HERE FOR EDUCATIONAL PURPOSES ONLY.

Modern JavaScript modules for FHIR

• 🏍️ SMART Auth and CDS Hooks implemented as Fastify plugins
• 🔥 Modern JavaScript (ES2020 and TypeScript)
• 📖 Open source license

Requires Node.JS >= 14

Sponsored by Automate Medical

Features

• 🏎️ Ultra fast cds-hooks and smart-auth implementations as Fastify plugins
• 💯 TypeScript support via @types/fhir
• ⚛️ ESM and CommonJS module support for ease of use
• ⚗️ Experimental Client and REST modules
• 🧪 Tested with Epic and Corrohealth at HL7 FHIR Connectathon 28 and with Humana and MITRE at 2021 CARIN Digital Insurance Card public testing event

Getting started

• docs.sero.run
• Start a CDS Hooks API
• Start a SMART on FHIR App
• Reference manual
• How to build in health the easy way

License

Copyright 2021 Automate Medical Inc

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

sero's Issues

Support Da Vinci CRD Payer implementation

The Da Vinci CRD (Coverage Requirements Discovery) workflow deserves attention. The fact that it has a Payer involved is particularly interesting. The Payer side of the implementation involves creating CDS Services. Can we make a complete example?

• Can we conform to Da Vinci CRD http://hl7.org/fhir/us/davinci-crd/?
• Do we need to actually do anything or can we just make examples instead?
• Probably need to do something because the spec makes extensive use of the extensions keyword to load in extra stuff...
• Touchstone has conformance tests for this, so any PR should contain conformance results: conformance against this specifically: https://touchstone.aegis.net/touchstone/testsetup?name=CDSHSandbox-DaVinci-CDSH1-0-FR4-0-1-Test--All
• Formal spec is located here: http://hl7.org/fhir/us/davinci-crd/2019May/hooks.html

This issue can be closed either because it's determined that there's too much effort or if we have a working example that is publishable.

---

Update: new goal

• Publish a working example at https://docs.sero.run/overview/examples/davinci-crd and in the examples directory

CDS Service Response flow conformance

https://cds-hooks.hl7.org/ballots/2020Sep/#cds-service-response

The Service Response has two components:

1. Cards
2. SystemActions

For successful responses, CDS Services SHALL respond with a 200 HTTP response with an object containing a cards array and optionally a systemActions array as described below.

The Card class we expose allows a developer to scaffold a response. We need to ensure that Card:

• Supports easy creation for all attributes in the spec
• Supports easily adding Suggestions and related Actions to a response (these likely deserve their own class)
• Support for Link

SystemActions don't currently have a class. Successfully solving this issue should consider an approach to dealing with these as well.

Finally, this issue should ship with a complete end to end rich example.

Docker failure in GoodRx Example

@XinhaoGeUW is going to document the failure message and investigate further

Write "Humana Hematology Specialist" example

Fix broken actions state

• We can actually use engines and .npmrc in Sero since it's a library that's consumed
• We should ensure Node >= 14 because of the Crypto lib
• Our actions should run on all major node LTS versions after 14 (so, now including 16)
• Existing PRs should be able to be retested

Feedback endpoint support

Actions being accepted, declined, or ignored by a CDS client are important metrics that services can use to improve. CDS hooks 1.1 implements feedback, or a way to POST feedback to a CDS service with information on how an action was taken on the client.

Implementing feedback in Sero would allow a client to POST (POST {baseUrl}/cds-services/{serviceId}/feedback) feedback for every service on a server made with Sero.

Remove SMART authorization module redirectUri default when the redirectUri is not present

When building with the SMART auth module, there are instances where the default redurectUri, which is set to http://localhost:8080${redirectPath}, becomes the recurectUri when it shouldn't. Better behavior for this would be to remove this default and throw an error if the redirectUri is not provided properly when the module is initialized in a new project.

In short, the default behavior of the module should be to throw an error if the redirectUri is not provided instead of providing a default redirectUri.

Plan to have a CDS Service live during the connectathon that we test according to the track details @mseckykoebel - broadly something to do

Write "Connect to a FHIR API" guide

CARIN Connectathon Participation

Main event page.

CARIN is hosting a connectathon on Nov 11 with 2 tracks. I want us to participate in both.

1. CARIN BlueButton track - this is our existing payer API, we can take our existing project that consumes Sero's smart-auth module
2. CARIN Digital Insurance Card - this is the working group I've been a part of, it just has some specific Coverage resources we can request but is otherwise sort of like an extension to the BlueButton IG

(1) happens in the morning EST and (2) happens in the afternoon EST. Here are some goals for both sessions:

BlueButton participation (@mseckykoebel )

• Sign up as a client participant
• Review the track details/scenario (ignore the refresh token parts)
• Review in advance if there are any pre-event instructions from the groups attending as servers (see the sign up form), i.e. registering a client app somewhere
• Have a branch that we can test some of the scenario with (baseline minimum is that we just test the sign in part -- the people who are attending as servers are identity providers -- and ignore the rest, but bonus if we do something more).
• Optional: if we have Fly deploys working for sandbox, we can probably spin up another fly deploy just for the connectathon

Digital Insurance Card participation (@jdjkelly )

• Sign up as a client participant
• Review the track details/scenario (ignore the refresh token parts)
• Have a branch that we can test retrieving Coverage requests from

Support for NodeJS 12.7+ package exports

Since we've started to consume the library for real in examples, we've discovered that importing the modules is kind of awkward:

import { Service, Card, NoDecisionResponse, Hooks } from "@sero.run/sero/dist/cds-hooks";

Goal

Make it so that it's (skipping the 'dist')

import { Service, Card, NoDecisionResponse, Hooks } from "@sero.run/sero/cds-hooks";

Apparently we can just list the major modules we want to be easily usable (cds-hooks, rest, http, etc) in exports in package.json: https://nodejs.org/api/packages.html#packages_exports

Using the package.json "exports" field, which should be supported by Webpack in a near future (see this issue), but has already been supported by Node since Node 12 LTS following the Bare Module Specifier Resolution proposal:

https://stackoverflow.com/questions/44345257/import-from-subfolder-of-npm-package

Patient access APIs

In order to test using Sero to access patient access APIs, we need to register for a number of the new access programs.

This issue tracks our registration progress.

🚧 = unknown
🧱 = blocked
⏳ = waiting on them
✅ = done and ready
❌ = done and doesn't exist

Entity	Registered	Sandbox Creds?	Prod Creds?	Notes
Humana	🧱	✅	🧱	They erased the account somehow?
United Healthcare/Optum	🧱	🚧	🚧	Privacy + Terms Urls needed
Aetna	✅	✅	🚧
Cigna	✅	✅	🚧
Clover	🧱	🚧	🚧	Privacy + Terms Urls needed
Alignment	⏳	🚧	🚧
Anthem	🚧	🚧	🚧
CareSource	🧱	🚧	🚧	Need to email [email protected]
UPMC Health Plan	🚧	🚧	🚧
Blue Cross of Idaho	🧱	🚧	🚧	Registration redirects to login - need to email [email protected]
Devoted	🚧	🚧	🚧	https://api.prod.devoted.com/fhir/metadata
Blue Cross & Blue Shield Kansas	⏳	🚧	🚧	Waiting on approval

🧱'ers:

• Public privacy policy URL
• Public terms of service URL

1Up Sandbox

• Lists a number of endpoints https://1up.health/payer-fhir-endpoint-directory
• Supposed support: https://docs.oneupdocs.com/docs/start/cms-patient-access-rule-for-developers/health-plan-endpoints

CMS Compliance Tracker

• http://cmscompliancetracker.com

Add README for getAccessTokenFromClientCredentialFlow

Add relevant README info to sero/src/smart-auth/README.md for new getAccessTokenFromClientCredentialFlow API created by #165

Write "Links and advanced service with FHIR" example

Similar to #48, #49, and #52. Towards #36. In this example, we introduce links, and more advanced FHIR queries in prefetch (mainly different kinds of observations).

• Isolate the links and advanced service with FHIR example.
• Write a descriptive guide to go along with it.
  • Have to expose the local dev server so CDS hooks can see it
• Successfully modularize the library (required in order to finish isolation task) for consumption in a default ES6/Node LTS project + a default TypeScript/Node LTS project.

Fix broken jest test on the full patient-view example

• Test is failing on master right now (https://github.com/Automate-Medical/sero/actions/runs/1005461407)
• UUID changes between requests
• Need a generic solution, since this will come up a lot
• If we use crypto/randomUUID (which we should since it's stdlib now in Node 14+) we need a way to mock it maybe? Alternatively, we can mock the constructor or something...

Should help developers understand they are not running the minimum required node

Goal

• Enforce major version of Node LTS (v14.17.x) as a minimum required version in project
• We can do this with package.json somehow

@jamais-vu encountered this in setup leading to an error about missing the randomUUID function from the crypto lib because it was added in 14.17. As long as we pin ourselves to the LTS version of the runtime, I think it's fine to have a pretty high version req)

Export * from each module in index.ts

Goal

• Use export * from path and update any examples

This is somewhat of a compromise.

Background

tldr;

	Native ESM Modules	TypeScript compiler support?	Submodule-style path imports
package.json#export	✓	X	✓
export * from path	✓	✓	X

I had committed an exports configuration to package.json that was designed to deliver this:

import { CDSHooks } from "@sero.run/sero"
import { Service } from "@sero.run/sero/cds-hooks"

The idea is that the exports key can be used to define additional entry points into the module beyond what is defined by "main".

  "exports": {
    "./cds-hooks": "./dist/cds-hooks/index.js",
    "./http": "./dist/http/index.js",
    "./rest": "./dist/rest/index.js"
  }

It turns out that even though package.json#exports landed in Node LTS, TypeScript compiler still doesn't support it.. When it does, this should absolutely be the approach we take.

So, instead for 0.1.0 we are going to have this:

import { CDSHooks } from "@sero.run/sero"
const { Service } from CDSHooks

This involves exporting all of the module instead of just the default function (current behaviour) for each of the submodules (CDSHooks, Http, Rest etc). This means we won't have nice submodule-style path imports but I think that's okay for now. The alternative is adding another compiler to do a pass on the project like RollUp or Webpack - and there's a lot of long term complexity that I think is better to avoid as long as possible.

Participate in Connectathon 28

Connectathon 28 is happening Sep 13-15

Goal is to participate in the CDS Hooks WG and be able to say that Epic or Cerner or some other large company successfully consumed our service

• @TH33765 to register 2 tickets
• Sign up (and also use as a way to anticipate participation) for the CDS Hooks WG at https://bit.ly/cds-hooks-connectathon-tracking
• Subscribe to the Zulip stream https://chat.fhir.org/#narrow/stream/179159-cds-hooks
• Participate in any CDS Hooks WG specific kickoff calls (happening Sep 9 now)
• Plan to have a CDS Service live during the connectathon that we test according to the track details @mseckykoebel - broadly something to do (#77)
• Update docs.sero.run with any documentation changes to existing docs from changes to the lib created by participation @mseckykoebel
• We will need to finish to participate successfully #7 (this is assigned to me)

Separately, we should treat this Connectathon as an opportunity to launch Sero

• Have a Substack post ready to go about it
• Say that we are participating with Epic, Cerner, etc on different plaforms
• Maybe a video we try to push
• Do a version 0.1.0 release and complete the 0.1.0 Launch milestone

Quickstart for Devs

This issue builds on #28 #31 #9 but incorporates some new ideas and is related to the 0.1.0 Launch milestone. Part of the goal of 0.1.0 is to have a first great dev documentation experience.

We are going to use Gitbook to create a "guide oriented" version of the reference manual (the old docs.sero.run will live at manual.sero.run or ref.sero.run as a reference manual built from the code whereas the new docs.sero.run will be the guide/gitbook written introduction to the project).

Goal

Completing this Issue means having written content for the sections listed below and addressing the additional tasks. Some of the content (i.e. SMART on FHIR) has a dependency on Sero building support for that. Writing content will require, in general, ensuring that concepts are digestible with supporting information. The task here is to have written narrative that matches the quality of any code example. They re-enforce each other.

• Installing Sero Speedrun (#43)
• User Guides
  • Start a CDS Hooks API (#36), and (maybe) Start a SMART on FHIR App
  • #69
• Example Projects
  • #48
  • #67
  • TBD/other contributions

This issue will also require:

• Restructuring the examples directory so that each subfolder is a "complete" guide/code example whose folder name matches the name of the guide above (i.e. examples/goodrx-cds-price-comparison) - there shouldn't be anything left in examples root other than folders and these should roughly map 1 to 1 with the links above (start-a-cds-hooks-api etc)
• Each example should have its own dependencies (i.e. npm init each subfolder, guides can even use something that's not javascript - each example/guide is isolated)
• Each example should consume sero through npm instead of through a link to src - this will probably break some things because the published version doesn't 100% work correctly

Dependencies

TBD

Set up sero.run domain

• Config automate-medical/infrastructure project for it
• Existing infrastructure needs to be ported, Go Daddy NameServers need to be carefully updated and need to sync records between AWS accounts
• Use docs subdomain for docs build + gh pages?

Client pagination breaks

If you make enough requests with Sero's AsyncGenerator search implementation, it will eventually throw a stack too deep exception.

Support Da Vinci PDex implementation

Da Vinci PDex (Payer Data Exchange) is another project run by the Da Vinci WG similar to what was described in #12

PDex tries to solve data exchange between payers and providers. When a member visits a new provider for the first time, PDex makes it easy for the payer/health plan to provide the doctor's office/provider with a member's clinical history. PDex is a parallel development to CARIN's Consumer Directed Payer Data Exchange:

The CARIN Consumer Directed Payer Data Exchange IG (CARIN IG for Blue Button®) defines how Claims and Encounter Data are to be provided; This DaVinci Payer Data Exchange IG (PDex) and the US Core IG define how Clinical Data is to be provided.

Member initiated exchange flows use SMART

This IG provides a mechanism for Member-authorized exchange of their Health History:

• From an old Health Plan to a new Health Plan
• From their Health Plan to a third-party application of the member’s choice.

The authorization method uses the OAuth 2.0 protocol to issue a token to an authorized application or service. The authorized application can then use the token to enable interaction with the FHIR REST API.

Provider initiated exchange flows use CDS Hooks + SMART

http://hl7.org/fhir/us/davinci-pdex/CDS-Hooks.html

We should investigate:

• Support for PDex requirements in CDS Service
• Touchstone/conformance testing
• CARIN vs PDex member flow/adoption?

Support the "Trusting CDS Clients" spec requirements

The spec suggests that authorization header is a requirement for every single client to service call: https://cds-hooks.hl7.org/ballots/2020Sep/#trusting-cds-clients

Each time a CDS Client transmits a request to a CDS Service, the request MUST include an Authorization header presenting the JWT as a “Bearer” token:

Authorization: Bearer {{JWT}}

Note that this is for every single CDS Service call, whether that be a Discovery call, a single CDS Service invocation, or multiple exchanges relating to a single service. Also note that mutual TLS MAY be used alongside JSON web tokens to establish trust of the CDS Client by the CDS Service.

The CDS Client MUST use its private key to digitally sign the JWT, using the JSON Web Signatures (rfc7515) standard.

We need to have a clear way to handle registering clients. What is reasonable? We don't have a storage/persistence layer yet so we could make use of configuration files.

Other considerations:

• Will the CDS Hooks authorization flow be separate from all other authorization flows?

Add scope validation and allow it to change

• Make TS validate something about the scopes
• Make the runtime validate it (at config and at route level?)
• Allow the passing of scopes dynamically to the authUrl function
• Prototype SMART Auth v2 Scopes

New readme

We need a new readme that better describes the project, progress, and goals. Open issue for help with PR against README.md that has:

• Simpler definition/goal for the project that is closer to the four features it has (1. cds hooks plugin for fastify, 2. rest plugin for fastify, 3. smart auth plugin for fastify, and 4. a client)
• Examples/use cases links
• Will be used to later update docs.sero.run
• Point sero.run to the new readme at this repo so we can finally use the link (@jdjkelly)
• Get a logo for the project (@jdjkelly )

CDS hooks client flows and scenarios

When working on Sero examples for CDS hooks, different client flows and scenarios begin to emerge that utilize suggestions and links that might involve some extra functionality. A basic example:

• if I hook into patient-view and the hook request prefetch contains more than one patient name in the return body, a suggestion from CDS hooks could be to remove one of the names. This could involve adding in some extra functionality.
• another one could be suggesting a deletion of a patients record if they have not made an appointment in a number of years.
• even suggesting to mark the patient as deceased.
• more examples will emerge as more work is done on the other hooks

This might involve the addition of some helper functions/a class that helps process data in a specific way. In all this saves developers some time needing to worry about edge cases with implementing smart apps.

Remove Global Type import behavior for SMART/CDS/FHIR

Is your feature request related to a problem? Please describe.
We silently inject fhir3, fhir4, CDSHooks etc into global TypeSpace. I think it's confusing and we should just import instead.

Arguably, sero should just export its own complete TypeScript definitions for these too (i.e. we shouldn't import @types/fhir - somewhat conflicted.

Describe the solution you'd like
First, just stop globally importing and fix all of the places that breaks.

Then, solve the TS export/declarations export issue.

Automatically build docs site

• Use github workflow to run the npm run docs command on the gh-pages branch every time a merge to master happens
• Commit the outcome somehow?
• Probably lots of easy examples for this

Configure protected branches

• Master should not be pushable etc
• Enforce build but not test requirements on PRs? Enforce both?

Write "Getting started - mirror current time with CDS hooks" example

Similar to #48. Also added to #35. Towards #36.

• Successfully merge #46.
• Isolate the get current time example in examples.
• Write a descriptive guide to go along with it.
  • Have to expose the local dev server so CDS hooks can see it
• Successfully modularize the library (required in order to finish isolation task) for consumption in a default ES6/Node LTS project + a default TypeScript/Node LTS project.

Update docs to support new SmartAuthProvider generic

Write the "Installing Sero Speedrun" page

Goal

Just write the most basic possible installation instructions as a library and as a module dev/library developer (running the example today)

Pages deploy is running against open PRs

See example: https://github.com/Automate-Medical/sero/pull/20/checks?check_run_id=3042526671

When we open new PRs against master, the pages deploy workflow is running. It should only run when we merge into master.

GoodRx as an example CDS Service

GoodRx is a large, popular online pharmacy search tool for consumers. It helps people find the lowest cost drugs they need.

Doctors should have pricing information instantly available when they make medication decisions. Identifying cheaper generics available during an encounter can have meaningful impacts on patient care quality. We are going to build an example of using Sero + GoodRx API to do this as a CDS Service available to any EHR supporting CDS Hooks.

Goal

Create a working example of a CDS Service for the order-select or order-sign hooks, which returns Cards (+ Suggestions?) that contain drug pricing information + anything else we can get that's interesting, when the doctor is prescribing some sort of medication

Use the GoodRx Compare Price to get the pricing data

The example should consume Sero as a library - initially it can exist in the local stage for the project in the example folder but ultimately completing this issue will require solving #2 and having this example live in a separate repo (so that we can prove the use case of npm i @sero.run/sero

Dependencies

• We need an API key from GoodRx (I've requested one)
• GoodRx Compare Price API
• order-select and order-sign examples with medications
• #2

Node 16 LTS

On October 26th Node 16 becomes the active LTS, we should track this version.

Sero has a few places where we will need to upgrade the required node version but we shouldn't have any breakages.

• Change package.json reference
• Change references in Github actions
• @types/node

Write "GoodRx CDS Price Comparison" example

Goal

• Successfully isolate the GoodRx example in examples
• Write a descriptive guide and record a video of the GoodRx example
• Successfully modularize the library (required in order to finish isolation task) for consumption in a default ES6/Node LTS project + a default TypeScript/Node LTS project

Deploy our own CDS Hooks Sandbox

Goal

• To have a working copy of the CDS Hooks Sandbox at cds.sero.run
• To have an in-memory R4 FHIR server available for use inside of it (solves a major public issue)
• We can use the examples from the guides and examples at a live URL for use in the Sandbox

Probably makes sense to try to deploy this with Dockerfile. May also make sense to contribute changes back upstream.

Add ESLint automation

Serverless/Lambda examples

• Using http module
• Should be able to mimic the other fastify-serverless examples in the wild
• Probably should just stay as an example, not involve src changes
• Helpful potentially for deployment story

man.sero.run isn't building

There's something wrong with the build/deploy steps for the deploy to pages action

Automate npm package publishing

• Initially we'll just publish @sero.run/sero
• Maybe it makes sense to publish the modules individually as well, but that's later
• Don't worry about it being functional in terms of it being consumable for real (as CommonJS or etc) - just ensure that it publishes the build
• Probably a github workflow solution

Write the "Start a CDS Hooks API" guide

As described in #35, we are going to write a guide called Start a CDS Hooks API.

The goal here to organize a "beginner to intermediate" tutorial from the examples we've been developing and to organize it into a single folder in the project and a page on the docs site. See also the detail in #35 about re-arranging the example folder.

Some food for thought:

• The example/guide should start with very simple - introduce how to make a Service, what is a Service anyways?
• Service should do as little as possible initially, patient-view - just echo back something like the current time, not even read patient data, but introduce the idea of returning Cards
• The next step of the guide should expose ideas in prefetch/context and use a slightly more complex example of using patient data/echoing patient data
• The next (last?) step should show an example with suggestions/actions?

Lastly, and this is true for the way I am writing the GoodRx example, I think the content in examples/start-a-cds-hooks-api should more or less contain each of the "steps" above in a separate file, and each file can have written notes as code comments. Then I would just aggregate all of those code comments and example snippets up into the written guide. I think that's just probably an easy approach.

Let's use this issue to organize the work to date/immediate future around. @mseckykoebel thoughts on this at #35?

Write "Prefetch and context" example

Similar to #49. Also added to #35. Towards #36. In this example, we introduce prefetch and context, and use logica to make a service that returns a suggestion card based on a prefetch template condition.

• Isolate the get prefetch and context example in examples.
• Write a descriptive guide to go along with it.
  • Have to expose the local dev server so CDS hooks can see it
• Successfully modularize the library (required in order to finish isolation task) for consumption in a default ES6/Node LTS project + a default TypeScript/Node LTS project.