JavaScript client / API reference

API reference

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 integrations use two: requestCheckin and — only if you want the FHIR mapping — buildCheckinBundle. For explanation rather than signatures, start with Getting started.

Run a check-in

Almost every integration is one of these two calls.

requestCheckinAsk, await, get the validated response. Throws CheckinFlowError if the flow doesn't complete. runCheckinThe same flow, reported as a status instead of thrown — branch on completed / declined / unsupported / error. CheckinFlowErrorCarries the outcome, so a decline can fall back gracefully. CheckinOptionsMediator and key-custody options for either call. CheckinOutcomeStatus, the request as sent, the response, and the failing stage if any.

Build a request

Build a request inline, or name one for reuse.

buildRequestComplete a request from purpose + items; fills in protocol boilerplate and validates. registerScenarioName a request so other surfaces can refer to it. resolveScenarioLook a registered scenario back up. resolveRequestNormalize any accepted request input into a full request object. SCENARIOSThe demo scenarios that ship with the library. CheckinRequestInitThe inline shape: purpose, items, optional id and fhirVersions. CheckinRequestInputAnything the API accepts: inline init, full request, or { scenario }. ScenarioA named request plus its label and description.

Run without a platform wallet

Credential getters — the function the flow calls to get the wallet's answer — that let it run in any browser, or in a test.

createWebWalletCredentialGetterHand the request to a wallet web app in a tab — a real consent screen. createMockWalletCredentialGetterAnswer instantly — either with fabricated data or with exactly the data your test pins, per item. WalletDeclinedErrorThrown when the person declines or closes the wallet. WebWalletOptionsWallet URL, tab vs popup, timeout. detectDcApiSupportWhether this browser can reach a platform wallet — checked before any prompt. DcApiSupportSupported, or unsupported with a reason to show. WebWalletCredentialThe credential shape a web wallet posts back. WebWalletResponseMessageThe approve / decline / error message a web wallet sends. WEB_WALLET_READY_MESSAGE_TYPEpostMessage type: the wallet is ready for a request. WEB_WALLET_REQUEST_MESSAGE_TYPEpostMessage type: here is the request. WEB_WALLET_RESPONSE_MESSAGE_TYPEpostMessage type: here is the answer.

Configure responding wallets

State which wallets may answer; the library resolves that into a list your page renders, and turns the one the person picks back into a credential getter.

resolveRespondersTurn a policy (platform? which web wallets? mock? which leads?) into the concrete options, with the unavailable ones and the default marked. credentialGetterForThe credential getter for the responder the person picked — pass it straight to requestCheckin. ResponderPolicyWhat this relying party accepts — platform, a web-wallet list or URL, mock — and which one is the default. ResponderOne renderable option: id, name, description, icon, whether it works here, and whether it is the default. loadWalletRegistryResolve a wallet list from an inline array, an object, or a URL. validateWalletRegistryShape-check a registry before trusting it. findWalletLook a registry entry up by id. DEMO_WALLET_REGISTRYThe built-in list of one: this project's demo wallet. WalletRegistryA list of web wallets, plus where it came from. WebWalletEntryOne wallet: id, name, walletUrl, and presentation details.

Hand off to the patient's phone

A kiosk or front-desk screen mints the request and shows a QR; the phone asks its wallet and sends the sealed answer back. You supply the mailbox.

createHandoffEverything a kiosk passes to runCheckin: an authority for the hand-off page's origin, and a getCredential that posts, shows the QR, and waits. createHandoffCredentialGetterJust the getCredential half, if you build the authority yourself. fetchHandoffPhone side, step one: pick the request up and recover what it asks for. answerHandoffPhone side, step two: ask the wallet (or any credential getter) and send the sealed credential — or a decline — back. handoffUrlForThe URL the QR code carries: the hand-off page plus the session id. sessionIdFromHashRead that session id back on the phone. HandoffMailboxThe seam you implement: post / fetch / answer / waitForAnswer, over any transport both devices reach. HandoffEnvelopeWhat the kiosk posts: the navigator argument, the hand-off origin, and an expiry. HandoffAnswerWhat the phone posts back: the credential, or a decline. HandoffOptionsMailbox, hand-off URL, the QR callback, TTL.

Build a wallet (the responder side)

What the demo wallet uses; useful if you're implementing one.

parseWalletRequestRecover the check-in request from a navigator.credentials.get argument. sealWalletResponseSign and HPKE-seal a response, bound to the verifier's origin. fabricateResponseDemo data for a request, honouring per-item consent. ParsedWalletRequestThe request plus the raw DeviceRequest and encryptionInfo bytes. MockWalletOptionsPer-item specs, a fallback, or a responder function for full control. MockItemSpecWhat to return for one item: FHIR, a health card, or a status like declined; alsoFulfills lets one artifact answer several items. MockItemSpecsOne spec, or a list — several artifacts for one item. DEMO_HEALTH_CARD_JWSA structurally real, unsigned SMART Health Card (deflated payload, one Patient and one Coverage) for demos and tests. buildMockResponseBuild a response from a per-item spec without going through the wire layer — handy in unit tests.

Key custody

Where the verifier's ephemeral key lives. Browser-local by default, and that is the design.

createBrowserLocalAuthorityEphemeral single-use key in the page — the default, and the intended one. createServerAuthorityClient for a server that holds the keys, when the page deliberately shouldn't. VerifierAuthorityThe seam itself, if you want to implement your own. PreparedCredentialRequestHandle plus the argument to pass to the browser. CredentialCompletionWhat an authority returns: the opened response, or handledByServer when the server kept it. PresentationContextThe origin the response was bound to, and the raw DeviceResponse for audit. extractDcapiResponsePull the protocol payload out of a browser credential object.

The wire layer

What an authority is made of — for a server that holds the key, in this language. Most pages never call these.

buildOrgIsoMdocRequestMint the HPKE keypair and build the navigator argument for a request and an origin. buildDcapiSessionTranscriptThe session transcript the wallet will have bound its answer to: encryptionInfo plus the asking page's origin. openWalletResponseHPKE-open a sealed response with the private key and that transcript. verifyDeviceResponseSignaturesIssuer signature, device signature, and MSO digests — the checks a browser-local authority runs.

Validate and inspect

The checks the library already runs — exported so you can run them yourself.

validateSmartCheckinRequestShape-check an untrusted request. validateSmartCheckinResponseShape-check an untrusted response. validateResponseAgainstRequestCross-check a response against the request that asked for it. ValidationResultOk with a typed value, or an error string.

Protocol model

The wire types, if you're reading or constructing payloads directly.

SmartCheckinRequestThe request as it goes over the wire. SmartCheckinRequestItemOne requested thing: title, selector, accepted formats. SmartCheckinContentSelectorselection.fhir or form.fhir. SmartCheckinResponseArtifacts plus per-item status. SmartArtifactOne returned artifact: FHIR JSON or a SMART Health Card. SmartArtifactBaseFields common to every artifact. SmartCheckinItemStatusfulfilled / partial / unavailable / declined / unsupported / error. SmartHealthCheckinAcceptedMediaTypeThe media types an item may accept. FhirCanonicalA canonical URL, optionally with |version. FhirProfileCollectionRefA profile family or IG canonical. FhirResourceTypeA FHIR resource type name. FhirVersione.g. "4.0.1". PROTOCOL_IDThe Digital Credentials API protocol identifier. MDOC_DOC_TYPEThe registered mdoc docType. MDOC_NAMESPACEThe registered mdoc namespace. SMART_REQUEST_INFO_KEYWhere the request rides inside the mdoc request. SMART_RESPONSE_ELEMENT_IDThe element the response comes back in. OrgIsoMdocNavigatorArgumentThe exact object passed to navigator.credentials.get. DcapiMdocResponseThe sealed response envelope.

Write FHIR (optional module)

Imported separately from @smart-health-checkin/client/fhir — nothing in the check-in path depends on it.

buildCheckinBundleMap a response to a transaction Bundle with Provenance. Pure — no network. postCheckinBundleSend it, in transaction or individual mode, with your own fetch if you like. CheckinBundleThe entries and the assembled Bundle. CheckinBundleEntryOne resource, its fullUrl, and the artifact it came from. CheckinBundleContextPatient and appointment references to stamp — never guessed. PostModetransaction (default) or individual. PostResultWhat was sent and what the server said. FetchLikeThe fetch signature, so you can inject auth. CHECKIN_REQUEST_ID_SYSTEMIdentifier system for the check-in request id in Provenance. CHECKIN_APPOINTMENT_SYSTEMIdentifier system for the appointment context.