API reference

In this section

Every export, grouped by what you'd be doing. Signatures and types are generated from the source, so they can't drift; this page is checked at build time to make sure nothing is missing from it.

Most EHR pages use the picker element, or runCheckin and CheckinResponse. For explanation rather than signatures, start with the Overview.

Run a check-in

One call. Give it a request, and a wallet if the patient chose one.

import … from "@smart-health-checkin/client"

runCheckinAsk a wallet, verify the answer, and report completed, declined, or failed. Call it inside the click. CheckinResultWhat runCheckin returns: the status, the request, the wallet, and the response or the error. CheckinOptionsThe wallet, key custody, health-card trust, and an AbortSignal. checkinRequestBuild and validate a request from a purpose and items. CheckinRequestInitThe parts of a request you write; the rest is filled in. CheckinRequestInputA complete request or a CheckinRequestInit.

Offer wallets

Every way a patient can answer is a Wallet. Start one inside the click.

import … from "@smart-health-checkin/client"

walletsThe wallets a page offers: the phone's own, a registry's web wallets, and any extras. WalletOne way to answer, with start() and open(). WalletsOptionsRegistry, platform on or off, extra wallets. platformWalletThe phone's own wallet, through the Digital Credentials API. webWalletA web wallet from a registry entry. customWalletWrap any transport as a wallet. WalletSessionAn opened connection to a wallet: getCredential and cancel. detectDcApiSupportWhether this browser has the Digital Credentials API. DcApiSupportSupported, or unsupported with a reason. WalletRegistryThe wallets.json format. WebWalletEntryOne web wallet in a registry.

Read the response

The full JSON as received, plus lookups by request item.

import … from "@smart-health-checkin/client"

CheckinResponsejson, status(item), resources(item), form(item), healthCards(item), entries(item), items(). FhirResourceA FHIR resource as returned. ResourceEntryA resource with where it came from: a Bundle or a health card, and the card's trust. ItemStatusfulfilled, partial, declined, unavailable, unsupported, or error.

SMART Health Card trust

Cards are verified before the page sees the response, against trust you set once.

import … from "@smart-health-checkin/client"

configureHealthCardTrustTrust a directory, issuers, or keys; accept any valid card, or everything, for testing. healthCardTrustThe trust currently configured. HealthCardTrustdirectory, issuers, keys, and accept. HealthCardOne card: issuer, Bundle, valid, trusted, accepted, and why not. VCI_DIRECTORY_URLWhere the VCI issuer directory lives.

Errors and key custody

Failures carry a code. Keys stay in the page unless you put them on a server.

import … from "@smart-health-checkin/client"

CheckinErrorAn error with a code; wallet transports throw it. CheckinErrorCodeunsupported, blocked, timeout, wallet-error, invalid-response, server. WalletDeclinedErrorThrown by a transport when the patient says no; runCheckin reports declined. KeyCustodyWhere the verifier key lives, for server-held keys. PreparedCredentialRequestWhat key custody returns from prepare. CredentialCompletionWhat key custody returns from complete. PresentationContextThe origin and DeviceResponse bytes, for audit.

Protocol types

The request and response as the spec defines them.

import … from "@smart-health-checkin/client"

SmartCheckinRequestA complete request. SmartCheckinRequestItemOne item: id, title, content, accept. SmartCheckinContentSelectorselection.fhir or form.fhir. SmartCheckinResponseThe response: artifacts and requestStatus. SmartArtifactOne artifact and the items it fulfills. SmartCheckinItemStatusOne item's status.

The picker element

A drop-in . Importing the module registers it.

import … from "@smart-health-checkin/client/ui"

SmartCheckinPickerThe element's class: request, wallets, strings, checkinOptions, setOutcome, reset. defineCheckinPickerRegister it under another tag name. PickerOutcomeHow a pick-mode check-in ended, for setOutcome. DEFAULT_STRINGSEvery piece of text it shows, to override or translate. PickerStringsThe shape of the strings. PICKER_CSSIts stylesheet, with every --smart-checkin-* variable. STARBURST_SVGThe SMART mark, inline. STARBURST_ICON_URLThe SMART mark as a data: URL, for a registry iconUrl.

React

The same picker as a component, and a hook for your own buttons.

import … from "@smart-health-checkin/client/react"

CheckinPicker as a component with callbacks. CheckinPickerPropsIts props. useCheckinThe wallets to offer and start(wallet), for your own UI.

Picker logic

What the picker element is built on, for your own picker UI.

import … from "@smart-health-checkin/client/picker"

arrangeWalletsWhat leads, what's listed, and what's behind "more". ArrangeOptionsInline limits, a preferred wallet. ArrangedWalletsprimary, inline, more, all. rememberChoiceRemember the wallet used on this site. recallChoiceThe remembered wallet, if any. forgetChoiceForget it. monogramA letter and color for a wallet without an icon.

Build a wallet

The protocol and matching rules. The consent screen is yours.

import … from "@smart-health-checkin/client/wallet"

serveWebWalletThe web wallet's side of the hand-off: one call. ServeWebWalletOptionsonRequest and onInvalidRequest. WebWalletRequestContextThe request and the EHR's origin, from the browser. WebWalletAnswerA response to seal, a sealed credential, declined, or an error. selectsDoes a resource answer a selection.fhir item? selectEntriesThe entries that answer it, plus what they reference. SelectionContentA selection.fhir selector. MatchableEntryA Bundle entry to match. MatchableResourceA resource to match. parseWalletRequestRead the SMART request from the Digital Credentials API argument, with warnings. ParsedWalletRequestThe request, items to answer unsupported, warnings, and the wire pieces needed to answer. WalletRequestErrorThrown where spec §8.4 says not to respond; carries the requirement id. checkWalletResponseWhat a Verifier would object to in a response, before sending it. declineAllThe response for a patient who reviewed and declined everything. sealWalletResponseSign and encrypt a response for the EHR's origin; optionally check it first. buildSignedDeviceResponseThe signed mdoc DeviceResponse, for wallets that seal it themselves. recipientJwkFromEncryptionInfoThe EHR's public key from encryptionInfo. WEB_WALLET_READY_MESSAGE_TYPEThe ready message type. WEB_WALLET_REQUEST_MESSAGE_TYPEThe request message type. WEB_WALLET_RESPONSE_MESSAGE_TYPEThe response message type. WebWalletResponseMessageThe response message. WebWalletCredentialThe credential inside an approved response.

Kiosk hand-off

A screen with no wallet hands the request to the patient's phone.

import … from "@smart-health-checkin/client/handoff"

handoffWalletThe kiosk's "use your phone" option, as a wallet. HandoffOptionsMailbox, hand-off page, and onWaiting for the QR code. HandoffMailboxThe mailbox you provide. HandoffEnvelopeWhat the kiosk posts. HandoffAnswerWhat the phone posts back. fetchHandoffPhone side: pick the request up. answerHandoffPhone side: ask a wallet and send its answer back. handoffUrlForThe URL the QR code carries. sessionIdFromHashThe session id on the hand-off page.

Testing

Check-ins without a real wallet. Never offer these to patients.

import … from "@smart-health-checkin/client/testing"

mockWalletA wallet that answers at once with the data you specify, or made-up data. MockWalletOptionsPer-item answers and a fallback. MockItemSpecData, a health card, or a status for one item. MockItemSpecsOne spec or several for an item. buildMockResponseThe response the mock would send, without the wire layer. fabricateResponseMade-up data for any request. DEMO_HEALTH_CARD_JWSA demo health card (not validly signed). DEMO_WALLET_REGISTRYThis project's demo web wallet.

Write FHIR

Optional: map a response into a FHIR transaction for your server.

import … from "@smart-health-checkin/client/fhir"

buildCheckinBundleBuild a transaction Bundle from a response. postCheckinBundlePost it to a FHIR server. CheckinBundleThe Bundle and its entries. CheckinBundleEntryOne entry. CheckinBundleContextThe patient and appointment to link to. PostModetransaction or individual. PostResultWhat the server returned. FetchLikeA fetch you supply. CHECKIN_REQUEST_ID_SYSTEMIdentifier system for the request id. CHECKIN_APPOINTMENT_SYSTEMIdentifier system for the appointment.

Model and wire

Types and validators, and the protocol bytes. See their reference pages.

import … from "@smart-health-checkin/client/model"

parseSmartCheckinRequestParse and validate request JSON text, rejecting duplicate members. parseSmartCheckinResponseParse and validate response JSON text, optionally against its request. validateSmartCheckinRequestValidate a request; lists items a Wallet can't process. validateSmartCheckinResponseValidate a response on its own. validateResponseAgainstRequestCross-check a response against its request, record by record. validateWalletRegistryValidate a wallets.json. loadWalletRegistryFetch and validate a wallets.json.
Full generated pages: checkin · ui · react · picker · wallet · handoff · fhir · testing · model · wire