README
SMART Client for NodeJS
High-level API
In this mode you create a framework-specific API that is easier to use. Currently, we have adapters for Express and HAPI. Pull requests are welcome for other frameworks. Here is how to use that:
const smart = require("smart-client/adapters/express")(options);
// or
const smart = require("smart-client/adapters/hapi")(options);
Then just use the smart.authorize
or other methods as described in their manuals:
Low-level API
In this mode you start by creating one configuration (options
) object and one
storage
object (that implements The storage interface)
and pass those as parameters for the functions as shown below.
authorize(request, response, options, storage)
This function should be called when you have a request to an URL with
launch
and iss
parameters or alternatively a fhirServiceUrl
parameter.
When you launch your app from outside (from an EHR or a test launcher like
https://launch.smarthealthit.org), your launchUri
endpoint will be called
with launch
and iss
parameters. Than you can use this function to initiate
the launch sequence. An express example might look like this:
const smart = require("smart-client");
// ...
app.get("/launch", (req, res) => smart.authorize(req, res, options, storage));
completeAuth(request, storage)
The login function above will redirect the browser to the authorization endpoint
of the SMART server. Depending on the requested scopes, the user might be asked
to select a patient or practitioner, authorize the app and so on. Eventually, the
user will be redirected back to your site at your options.redirectUri
. At that
point you should have received a code that needs to be exchanged for an access
token. To do so, you can use the completeAuth
function like so (express example):
const smart = require("smart-client");
// ...
app.get("/redirect", (req, res) => {
smart.completeAuth(req, storage)
.then(client => client.request("/Patient"))
.then(result => res.json(result.data))
.catch(error => res.status(500).send(error.stack));
})
Configuration Options
The following options are supported:
clientId
- string, required - The Client ID that you were given after registering your app with the authorization server.redirectUri
- string, required - The location to redirect to, once the user have authorized the launch.serverUrl
- string, optional - The base URL of the Fhir server. If you specify this in your options you will be able to call your launchUri endpoint without any parameters and it will initiate a standalone launch sequence against this server. You can also pass afhirServiceUrl
query parameter to your launchUri endpoint which will take precedence over the config option value. Finally, if your launch endpoint is called withiss
andlaunch
parameters (which will happen when launched from EHR),iss
will become the used server and thefhirServiceUrl
url parameter (if any) and theserverUrl
option (if any) will be ignored.scope
- string, optional - Space-separated list of scopes as described in http://docs.smarthealthit.org/authorization/scopes-and-launch-context/. Strictly speaking, this is option is not required but you will typically want access to certain resources and the scope should be used to request that access.clientSecret
- string, optional If you registered your app as confidential client you should have been given aclientSecret
that you have to set here.getStorage(request)
- function, optional A function that will return a custom storage object. See The storage interface below for details.
Use these options while creating a SMART api:
const smart = require("smart-client/adapters/express")({
scope : "openid profile offline_access",
redirectUri: "/",
clientId : "my-client-id"
});
// ...
or you just pass them to functions if you prefer the low-level api:
const smart = require("smart-client");
const options = {
scope : "openid profile offline_access",
redirectUri: "/",
clientId : "my-client-id"
};
smart.authorize(req, res, options, storage)
// ...
Contribution and development
This library is written in typescript and the framework adapters are written in pure JavaScript. For best development experience you might want to have a few terminals running (cd
into the project folder first):
npm run build:watch
- will watch TS files for changes and automatically re-build the JS versions in /lib.npm run test:watch
- will run tests on any change so that if you introduce an issue you will know immediately.npm start
- will run the node example on http://localhost:3000npm run start:express
- will run the express example on http://localhost:3000. You will have to docd examples/express && npm i
when you run this for the first time.npm run start:hapi
- will run the HAPI example on http://localhost:3000. You will have to docd examples/hapi && npm i
when you run this for the first time.
npm run build
ornpm test
if you want to build or test on demand instead of in watch mode.
Debugging
This library uses the debug
module to log specific SMART information. In development mode you might want to enable that before starting a server like so:
DEBUG=smart npm run start:express