@smart-health-checkin/client

In this section

Classes

CheckinError

An error with a code. Wallet transports throw it (a custom wallet can too), and runCheckin reports its code in a failed result.

Extends

Error

Constructors

Constructor

new CheckinError(
   code, 
   message, 
   options?): CheckinError;

Defined in: src/core/errors.ts:27

Parameters

Parameter	Type
`code`	`CheckinErrorCode`
`message`	`string`
`options`	{ `check?`: `string`; }
`options.check?`	`string`

Returns

CheckinError

Overrides

Error.constructor

Properties

check?

readonly optional check?: string;

Defined in: src/core/errors.ts:26

For invalid-response: which check failed, when known.

code

readonly code: CheckinErrorCode;

Defined in: src/core/errors.ts:24

CheckinResponse

Defined in: src/core/response.ts:48

A validated response, with lookups by the item ids in your request. A completed runCheckin result carries one as response.

Constructors

Constructor

new CheckinResponse(
   validation, 
   request, 
   cards?): CheckinResponse;

Defined in: src/core/response.ts:60

From a successful validateResponseAgainstRequest; runCheckin builds it for you.

Parameters

Parameter	Type	Default value	Description
`validation`	{ `artifacts`: `ArtifactCheck`[]; `items`: `ItemOutcome`[]; `ok`: `true`; `usableArtifacts`: `SmartArtifact`[]; `value`: `SmartCheckinResponse`; }	`undefined`	-
`validation.artifacts`	`ArtifactCheck`[]	`undefined`	-
`validation.items`	`ItemOutcome`[]	`undefined`	One entry per status row's item id (without a request) or per request item (with one).
`validation.ok`	`true`	`undefined`	-
`validation.usableArtifacts`	`SmartArtifact`[]	`undefined`	The Artifacts that passed every check, in response order.
`validation.value`	`SmartCheckinResponse`	`undefined`	The response exactly as received.
`request`	`SmartCheckinRequest`	`undefined`	-
`cards`	readonly `HealthCard`[]	`[]`	-

Returns

CheckinResponse

Properties

json

readonly json: SmartCheckinResponse;

Defined in: src/core/response.ts:50

The response as received.

request

readonly request: SmartCheckinRequest;

Defined in: src/core/response.ts:52

The request it answers.

Methods

artifacts()

artifacts(itemId): SmartArtifact[];

Defined in: src/core/response.ts:94

The usable artifacts that fulfill the item. An artifact fulfilling several items is returned for each.

Parameters

Parameter	Type
`itemId`	`string`

Returns

SmartArtifact[]

disregarded()

disregarded(): {
  artifact: unknown;
  id?: string;
  index: number;
  problems: ValidationIssue[];
}[];

Defined in: src/core/response.ts:99

Artifacts set aside because they failed a check ([XV-4]), with the reasons.

Returns

{ artifact: unknown; id?: string; index: number; problems: ValidationIssue[]; }[]

entries()

entries(itemId): ResourceEntry[];

Defined in: src/core/response.ts:111

The item's resources with where each came from. Lists every health card's resources, accepted or not.

Parameters

Parameter	Type
`itemId`	`string`

Returns

ResourceEntry[]

form()

form(itemId): FhirResource | undefined;

Defined in: src/core/response.ts:149

The QuestionnaireResponse for a form item.

Parameters

Parameter	Type
`itemId`	`string`

Returns

FhirResource | undefined

healthCards()

healthCards(itemId): HealthCard[];

Defined in: src/core/response.ts:106

Every SMART Health Card for the item, with its trust result, accepted or not.

Parameters

Parameter	Type
`itemId`	`string`

Returns

HealthCard[]

items()

items(): {
  artifacts: SmartArtifact[];
  id: string;
  message?: string;
  problems: ValidationIssue[];
  status?:   | "fulfilled"
     | "partial"
     | "unavailable"
     | "declined"
     | "unsupported"
     | "error";
  title: string;
}[];

Defined in: src/core/response.ts:79

Every requested item with its status, usable artifacts, and any problems, in request order.

Returns

{ artifacts: SmartArtifact[]; id: string; message?: string; problems: ValidationIssue[]; status?: | "fulfilled" | "partial" | "unavailable" | "declined" | "unsupported" | "error"; title: string; }[]

resolve()

resolve(entry, reference): FhirResource | undefined;

Defined in: src/core/response.ts:157

Follow a reference from an entry within its own Bundle or card: urn:uuid:… and other fullUrls, resource:N in a card, or Type/id.

Parameters

Parameter	Type
`entry`	`ResourceEntry`
`reference`	`string`

Returns

FhirResource | undefined

resources()

resources(itemId, options?): FhirResource[];

Defined in: src/core/response.ts:141

FHIR resources for the item, from Bundles and from health cards the trust configuration accepts, optionally only one resource type.

Parameters

Parameter	Type
`itemId`	`string`
`options`	{ `type?`: `string`; }
`options.type?`	`string`

Returns

FhirResource[]

status()

status(itemId): 
  | "fulfilled"
  | "partial"
  | "unavailable"
  | "declined"
  | "unsupported"
  | "error"
  | undefined;

Defined in: src/core/response.ts:74

The item's status: "fulfilled", "partial", "declined", "unavailable", "unsupported", or "error"; undefined when the response has no valid status for it ([XV-3]).

Parameters

Parameter	Type
`itemId`	`string`

Returns

toJSON()

toJSON(): SmartCheckinResponse;

Defined in: src/core/response.ts:166

The same plain JSON as json, so JSON.stringify(response) gives the response as received.

Returns

SmartCheckinResponse

WalletDeclinedError

Defined in: src/core/errors.ts:39

Thrown by a wallet transport when the patient closes the wallet or says no. runCheckin turns it into a declined result, not a failure.

Extends

Error

Constructors

Constructor

new WalletDeclinedError(message?): WalletDeclinedError;

Defined in: src/core/errors.ts:40

Parameters

Parameter	Type	Default value
`message`	`string`	`"the patient declined in the wallet"`

Returns

WalletDeclinedError

Overrides

Error.constructor

Type Aliases

CheckinErrorCode

type CheckinErrorCode = 
  | "unsupported"
  | "blocked"
  | "timeout"
  | "wallet-error"
  | "invalid-response"
  | "server";

Defined in: src/core/errors.ts:5

How a check-in can fail. Every failure carries one of these codes, so pages branch on the code instead of matching message text.

CheckinOptions

type CheckinOptions = {
  fetch?: typeof fetch;
  healthCards?: HealthCardTrust;
  keys?:   | "browser"
     | {
     server: string;
   }
     | KeyCustody;
  session?: WalletSession;
  signal?: AbortSignal;
  wallet?: Wallet;
};

Defined in: src/core/run.ts:28

Options for runCheckin and wallet.start.

Properties

fetch?

optional fetch?: typeof fetch;

Defined in: src/core/run.ts:40

Used to fetch health-card issuer keys and directories.

healthCards?

optional healthCards?: HealthCardTrust;

Defined in: src/core/run.ts:36

Trust for SMART Health Cards in the response; defaults to configureHealthCardTrust.

keys?

optional keys?: 
  | "browser"
  | {
  server: string;
}
  | KeyCustody;

Defined in: src/core/run.ts:34

Where the key that opens the response lives: "browser" (default, a fresh key in the page), { server } for server-held keys, or your own KeyCustody.

session?

optional session?: WalletSession;

Defined in: src/core/run.ts:32

A session already opened with wallet.open(), for example by the picker in pick mode.

signal?

optional signal?: AbortSignal;

Defined in: src/core/run.ts:38

Abort to stop waiting (closes a web wallet's tab); the check-in ends as declined.

wallet?

optional wallet?: Wallet;

Defined in: src/core/run.ts:30

Which wallet to ask. Defaults to the phone's own wallet.

CheckinRequestInit

type CheckinRequestInit = {
  fhirVersions?: ReadonlyArray<string>;
  id?: string;
  items: ReadonlyArray<SmartCheckinRequestItem>;
  purpose?: string;
};

Defined in: src/core/request.ts:4

Everything a request needs except what the library fills in.

Properties

fhirVersions?

optional fhirVersions?: ReadonlyArray<string>;

Defined in: src/core/request.ts:10

Defaults to ["4.0.1"].

id?

optional id?: string;

Defined in: src/core/request.ts:6

Defaults to a random UUID.

items

items: ReadonlyArray<SmartCheckinRequestItem>;

Defined in: src/core/request.ts:11

purpose?

optional purpose?: string;

Defined in: src/core/request.ts:8

Shown to the patient by some wallets.

CheckinRequestInput

type CheckinRequestInput = 
  | SmartCheckinRequest
  | CheckinRequestInit;

Defined in: src/core/request.ts:15

What runCheckin accepts: a complete request, or the parts to build one from.

CheckinResult

type CheckinResult = 
  | {
  request: SmartCheckinRequest;
  response: CheckinResponse;
  status: "completed";
  wallet: Wallet;
  warnings: CheckinWarning[];
}
  | {
  request: SmartCheckinRequest;
  serverReference?: string;
  status: "kept-on-server";
  wallet: Wallet;
}
  | {
  request: SmartCheckinRequest;
  status: "declined";
  wallet: Wallet;
}
  | {
  error: {
     check?: string;
     code: CheckinErrorCode;
     message: string;
  };
  request: SmartCheckinRequest;
  status: "failed";
  wallet: Wallet;
};

Defined in: src/core/run.ts:44

How a check-in ended: completed, kept-on-server, declined, or failed.

Union Members

Type Literal

{
  request: SmartCheckinRequest;
  response: CheckinResponse;
  status: "completed";
  wallet: Wallet;
  warnings: CheckinWarning[];
}

request

request: SmartCheckinRequest;

response

response: CheckinResponse;

The validated response.

status

status: "completed";

wallet

wallet: Wallet;

warnings

warnings: CheckinWarning[];

Transport and signature problems that didn't stop the check-in: a receiver continues past them and reports them (spec §2, [RCV-1]). Empty when everything checked out.

Type Literal

{
  request: SmartCheckinRequest;
  serverReference?: string;
  status: "kept-on-server";
  wallet: Wallet;
}

request

request: SmartCheckinRequest;

serverReference?

optional serverReference?: string;

The server's handle for what it stored (an encounter id, a queue entry), if it returned one.

status

status: "kept-on-server";

Server key custody kept the data; the page gets only a handle.

wallet

wallet: Wallet;

Type Literal

{
  request: SmartCheckinRequest;
  status: "declined";
  wallet: Wallet;
}

Type Literal

{
  error: {
     check?: string;
     code: CheckinErrorCode;
     message: string;
  };
  request: SmartCheckinRequest;
  status: "failed";
  wallet: Wallet;
}

CredentialCompletion

type CredentialCompletion = 
  | {
  handledByServer?: false;
  presentation: PresentationContext;
  smartResponse: SmartCheckinResponse;
  warnings?: CheckinWarning[];
}
  | {
  handledByServer: true;
  presentation?: PresentationContext;
  reference?: string;
};

Defined in: src/browser/index.ts:72

The result of opening a wallet response. Two shapes, because there are two reasons to hold keys on a server:

smartResponse — the server opened and verified it and hands the data back, so the page can still prefill forms. Key custody and an audit point, without giving up the in-page workflow.
handledByServer — the server keeps the data; the page learns only that it succeeded. For deployments where the page must not hold PHI. In-page prefill is not possible in this mode, by construction.

Union Members

Type Literal

{
  handledByServer?: false;
  presentation: PresentationContext;
  smartResponse: SmartCheckinResponse;
  warnings?: CheckinWarning[];
}

handledByServer?

optional handledByServer?: false;

presentation

presentation: PresentationContext;

smartResponse

smartResponse: SmartCheckinResponse;

Opened and wire-checked; the caller still cross-checks it against the request.

warnings?

optional warnings?: CheckinWarning[];

Transport and signature findings that didn't stop the check-in (spec §2, [RCV-1]).

Type Literal

{
  handledByServer: true;
  presentation?: PresentationContext;
  reference?: string;
}

handledByServer

handledByServer: true;

presentation?

optional presentation?: PresentationContext;

reference?

optional reference?: string;

Optional server-side handle for what it stored (an encounter id, a queue entry).

DcApiSupport

type DcApiSupport = 
  | {
  state: "supported";
}
  | {
  reason: string;
  state: "unsupported";
};

Defined in: src/browser/index.ts:22

Whether this browser has the Digital Credentials API; when not, reason says why.

FhirResource

type FhirResource = {
[key: string]: unknown;
  resourceType: string;
};

Defined in: src/core/response.ts:25

Indexable

[key: string]: unknown

Properties

resourceType

resourceType: string;

Defined in: src/core/response.ts:25

HealthCard

type HealthCard = {
  accepted: boolean;
  bundle?: {
     entry?: {
        fullUrl?: string;
        resource?: Record<string, unknown>;
     }[];
     resourceType: "Bundle";
  };
  fulfills: ReadonlyArray<string>;
  issuer?: string;
  jws: string;
  reason?: string;
  trusted: boolean;
  valid: boolean;
};

Defined in: src/core/health-cards.ts:39

A SMART Health Card from a response, with the result of checking it.

Properties

accepted

accepted: boolean;

Defined in: src/core/health-cards.ts:57

Included by resources() under the configured accept.

bundle?

optional bundle?: {
  entry?: {
     fullUrl?: string;
     resource?: Record<string, unknown>;
  }[];
  resourceType: "Bundle";
};

Defined in: src/core/health-cards.ts:47

The card's FHIR Bundle (vc.credentialSubject.fhirBundle), when it could be decoded.

entry?

optional entry?: {
  fullUrl?: string;
  resource?: Record<string, unknown>;
}[];

resourceType

resourceType: "Bundle";

fulfills

fulfills: ReadonlyArray<string>;

Defined in: src/core/health-cards.ts:41

The item ids the card's artifact fulfills.

issuer?

optional issuer?: string;

Defined in: src/core/health-cards.ts:45

The issuer URL from the payload, when it could be decoded.

jws

jws: string;

Defined in: src/core/health-cards.ts:43

The compact JWS as received.

reason?

optional reason?: string;

Defined in: src/core/health-cards.ts:59

Why it isn't valid or trusted, when it isn't.

trusted

trusted: boolean;

Defined in: src/core/health-cards.ts:55

The issuer is trusted by the configuration.

valid

valid: boolean;

Defined in: src/core/health-cards.ts:53

The signature verified against the issuer's key. False when it didn't, and also when it wasn't checked: under accept: "trusted" an untrusted issuer's keys aren't fetched.

HealthCardTrust

type HealthCardTrust = {
  accept?: "trusted" | "any-valid" | "everything";
  directory?: "vci" | string;
  issuers?: ReadonlyArray<string>;
  keys?: Readonly<Record<string, {
     keys: ReadonlyArray<JsonWebKey & {
        kid?: string;
     }>;
  }>>;
};

Defined in: src/core/health-cards.ts:19

Which SMART Health Card issuers to trust, and which cards resources() includes.

Properties

accept?

optional accept?: "trusted" | "any-valid" | "everything";

Defined in: src/core/health-cards.ts:35

Which cards resources() includes: "trusted" (default) only cards from a trusted issuer with a valid signature; "any-valid" any card whose signature verifies against its own issuer's published keys; "everything" invalid cards too. Every card is always listed by healthCards(). Under "trusted", an untrusted issuer's keys are never fetched, so its cards are reported with valid: false and a reason saying the issuer isn't trusted.

directory?

optional directory?: "vci" | string;

Defined in: src/core/health-cards.ts:21

An issuer directory: "vci", or the URL of a file shaped like the VCI directory.

issuers?

optional issuers?: ReadonlyArray<string>;

Defined in: src/core/health-cards.ts:23

Issuer URLs to trust, in addition to any directory.

keys?

optional keys?: Readonly<Record<string, {
  keys: ReadonlyArray<JsonWebKey & {
     kid?: string;
  }>;
}>>;

Defined in: src/core/health-cards.ts:25

Keys to trust without fetching, by issuer URL.

ItemStatus

type ItemStatus = SmartCheckinItemStatus["status"];

Defined in: src/core/response.ts:28

An item's status in a response: fulfilled, partial, unavailable, declined, unsupported, or error.

KeyCustody

type KeyCustody = {
  kind: string;
  completeCredentialRequest: Promise<CredentialCompletion>;
  prepareCredentialRequest: Promise<PreparedCredentialRequest>;
};

Defined in: src/browser/index.ts:136

Where the key that opens a wallet's response lives: the keys option of runCheckin. The default, "browser", makes a single-use key in the page for each check-in. { server: "/checkin-api" } keeps it on your server, behind the two calls below (the "Going to production" guide explains when that's worth it). To call a different API, or to send a bearer token instead of the page's cookies, implement this type yourself.

The server's two calls

Both are POST with JSON bodies, sent with the page's cookies (credentials: "include"). Nothing between the page and the wallet changes.

Prepare: POST {server}/credential-requests with { "request": SmartCheckinRequest }. The server:

decides what to ask for. It may build its own request and ignore the page's, so a compromised page can't widen what is asked;
builds the wire request with a fresh key, using buildOrgIsoMdocRequest(request, { origin }) from /wire or the same steps in its own language, with the page's origin taken from its own configuration, never from the request body;
stores the key, the request, the origin, the user's session, and an expiry under a handle of at least 128 random bits;
replies { "handle": string, "navigatorArgument": {...} }.

Rate-limit this call: each one makes a key and a record.

Complete: POST {server}/credential-requests/{handle}/complete with { "credential": <what the wallet returned> }. The server:

rejects a handle that is unknown, expired, already used, or from another session;
opens and checks the credential with openWalletCredential and then checkDeviceResponse from /wire, keeping their warnings;
checks the SMART response against the request it stored, with validateResponseAgainstRequest from /model, never against anything the page sent;
deletes the key;
replies with a CredentialCompletion: { smartResponse, presentation, warnings } to hand the data to the page, or { "handledByServer": true, "reference"?: string } to keep it, in which case runCheckin resolves with status "kept-on-server".

Any HTTP error from either call ends the check-in as failed with code server. For a server in another language, the spec's conformance fixtures include a real capture with a published test key.

Properties

kind

kind: string;

Defined in: src/browser/index.ts:137

Methods

completeCredentialRequest()

completeCredentialRequest(input): Promise<CredentialCompletion>;

Defined in: src/browser/index.ts:139

Parameters

Parameter	Type
`input`	{ `credential`: `unknown`; `handle`: `string`; }
`input.credential`	`unknown`
`input.handle`	`string`

Returns

Promise<CredentialCompletion>

prepareCredentialRequest()

prepareCredentialRequest(input): Promise<PreparedCredentialRequest>;

Defined in: src/browser/index.ts:138

Parameters

Parameter	Type
`input`	{ `request`: `SmartCheckinRequest`; }
`input.request`	`SmartCheckinRequest`

Returns

Promise<PreparedCredentialRequest>

PreparedCredentialRequest

type PreparedCredentialRequest = {
  handle: string;
  navigatorArgument: OrgIsoMdocNavigatorArgument;
};

Defined in: src/browser/index.ts:48

Properties

handle

handle: string;

Defined in: src/browser/index.ts:50

Opaque handle for completing the request with the same key custody.

navigatorArgument

navigatorArgument: OrgIsoMdocNavigatorArgument;

Defined in: src/browser/index.ts:52

Pass to navigator.credentials.get(...).

PresentationContext

type PresentationContext = {
  deviceResponseHex?: string;
  origin: string;
};

Defined in: src/browser/index.ts:55

Properties

deviceResponseHex?

optional deviceResponseHex?: string;

Defined in: src/browser/index.ts:58

DeviceResponse bytes, for audit or debugging.

origin

origin: string;

Defined in: src/browser/index.ts:56

ResourceEntry

type ResourceEntry = {
  artifactId: string;
  card?: HealthCard;
  fullUrl?: string;
  resource: FhirResource;
  source: "bundle" | "health-card";
};

Defined in: src/core/response.ts:31

A resource from a response, with where it came from.

Properties

artifactId

artifactId: string;

Defined in: src/core/response.ts:37

The artifact this came from.

card?

optional card?: HealthCard;

Defined in: src/core/response.ts:39

For resources from a health card: the card, with its trust result.

fullUrl?

optional fullUrl?: string;

Defined in: src/core/response.ts:41

The resource's fullUrl in its Bundle, for resolving references.

resource

resource: FhirResource;

Defined in: src/core/response.ts:33

The FHIR resource.

source

source: "bundle" | "health-card";

Defined in: src/core/response.ts:35

Whether it came from a FHIR Bundle or resource, or from a SMART Health Card.

SmartArtifact

type SmartArtifact = 
  | SmartArtifactBase & {
  mediaType: "application/smart-health-card";
  value: {
     verifiableCredential: ReadonlyArray<string>;
  };
}
  | SmartArtifactBase & {
  fhirVersion: FhirVersion;
  mediaType: "application/fhir+json";
  value: unknown;
};

Defined in: src/model/types.ts:83

SmartCheckinContentSelector

type SmartCheckinContentSelector = 
  | {
  kind: "selection.fhir";
  profiles?: ReadonlyArray<FhirCanonical>;
  profilesFrom?: ReadonlyArray<FhirProfileCollectionRef>;
  resourceTypes?: ReadonlyArray<FhirResourceType>;
}
  | {
  kind: "form.fhir";
  questionnaire?: unknown;
  questionnaireCanonical?: FhirCanonical;
};

Defined in: src/model/types.ts:19

What data an item means: existing records (selection.fhir, spec §5.4.1) or a form for the patient to fill in (form.fhir, spec §5.4.2).

Union Members

Type Literal

{
  kind: "selection.fhir";
  profiles?: ReadonlyArray<FhirCanonical>;
  profilesFrom?: ReadonlyArray<FhirProfileCollectionRef>;
  resourceTypes?: ReadonlyArray<FhirResourceType>;
}

kind

kind: "selection.fhir";

profiles?

optional profiles?: ReadonlyArray<FhirCanonical>;

Records with these exact profiles; url|version asks for that version only.

profilesFrom?

optional profilesFrom?: ReadonlyArray<FhirProfileCollectionRef>;

Records with any profile from these implementation guides.

resourceTypes?

optional resourceTypes?: ReadonlyArray<FhirResourceType>;

Records of these resource types; also narrows profiles and profilesFrom.

Type Literal

{
  kind: "form.fhir";
  questionnaire?: unknown;
  questionnaireCanonical?: FhirCanonical;
}

kind

kind: "form.fhir";

questionnaire?

optional questionnaire?: unknown;

The Questionnaire itself, inline, so the wallet needn't fetch it.

questionnaireCanonical?

optional questionnaireCanonical?: FhirCanonical;

The Questionnaire's canonical URL, |version included; the QuestionnaireResponse echoes it exactly.

SmartCheckinItemStatus

type SmartCheckinItemStatus = {
  item: string;
  message?: string;
  status:   | "fulfilled"
     | "partial"
     | "unavailable"
     | "declined"
     | "unsupported"
     | "error";
};

Defined in: src/model/types.ts:68

What the wallet says happened to one item.

Properties

item

item: string;

Defined in: src/model/types.ts:70

The item's id.

message?

optional message?: string;

Defined in: src/model/types.ts:74

The wallet's explanation, if it gave one.

status

status: 
  | "fulfilled"
  | "partial"
  | "unavailable"
  | "declined"
  | "unsupported"
  | "error";

Defined in: src/model/types.ts:72

What happened to the item.

SmartCheckinRequest

type SmartCheckinRequest = {
  fhirVersions?: ReadonlyArray<FhirVersion>;
  id: string;
  items: ReadonlyArray<SmartCheckinRequestItem>;
  purpose?: string;
  type: "smart-health-checkin-request";
  version: "1";
};

Defined in: src/model/types.ts:54

A complete check-in request (spec §5). checkinRequest builds one from { purpose, items }.

Properties

fhirVersions?

optional fhirVersions?: ReadonlyArray<FhirVersion>;

Defined in: src/model/types.ts:62

The FHIR versions you can read.

id

id: string;

Defined in: src/model/types.ts:58

A unique id for this request; the response's requestId repeats it.

items

items: ReadonlyArray<SmartCheckinRequestItem>;

Defined in: src/model/types.ts:64

What you're asking for.

purpose?

optional purpose?: string;

Defined in: src/model/types.ts:60

One line the patient sees at the top.

type

type: "smart-health-checkin-request";

Defined in: src/model/types.ts:55

version

version: "1";

Defined in: src/model/types.ts:56

SmartCheckinRequestItem

type SmartCheckinRequestItem = {
  accept: ReadonlyArray<SmartHealthCheckinAcceptedMediaType>;
  content: SmartCheckinContentSelector;
  id: string;
  required?: boolean;
  summary?: string;
  title: string;
};

Defined in: src/model/types.ts:38

One thing the request asks for.

Properties

accept

accept: ReadonlyArray<SmartHealthCheckinAcceptedMediaType>;

Defined in: src/model/types.ts:50

The formats you can process, most preferred first.

content

content: SmartCheckinContentSelector;

Defined in: src/model/types.ts:48

What data you mean: records or a form.

id

id: string;

Defined in: src/model/types.ts:40

Your name for the item; look the answer up by it, as in response.resources(id).

required?

optional required?: boolean;

Defined in: src/model/types.ts:46

How much the item matters to you. Advice only: the patient can always decline.

summary?

optional summary?: string;

Defined in: src/model/types.ts:44

One line on why you need it.

title

title: string;

Defined in: src/model/types.ts:42

What the patient sees, such as "Insurance card".

SmartCheckinResponse

type SmartCheckinResponse = {
  artifacts: ReadonlyArray<SmartArtifact>;
  requestId: string;
  requestStatus: ReadonlyArray<SmartCheckinItemStatus>;
  type: "smart-health-checkin-response";
  version: "1";
};

Defined in: src/model/types.ts:95

A wallet's answer, as it arrives after decryption (spec §6). CheckinResponse wraps it with lookups.

Properties

artifacts

artifacts: ReadonlyArray<SmartArtifact>;

Defined in: src/model/types.ts:101

The data: FHIR resources and SMART Health Cards, each naming the items it fulfills.

requestId

requestId: string;

Defined in: src/model/types.ts:99

The id of the request this answers.

requestStatus

requestStatus: ReadonlyArray<SmartCheckinItemStatus>;

Defined in: src/model/types.ts:103

One status per item.

type

type: "smart-health-checkin-response";

Defined in: src/model/types.ts:96

version

version: "1";

Defined in: src/model/types.ts:97

Wallet

type Wallet = {
  available: boolean;
  description?: string;
  entry?: WebWalletEntry;
  homepage?: string;
  iconUrl?: string;
  id: string;
  keys?: KeyCustody;
  kind: "platform" | "web" | "handoff" | "mock" | "custom";
  name: string;
  unavailableReason?: string;
  open: WalletSession;
  start: Promise<CheckinResult>;
};

Defined in: src/core/wallets.ts:35

One way a patient can answer: the phone's own wallet, a web wallet, a kiosk hand-off, a mock, or your own. Get them from wallets(), platformWallet(), webWallet(), handoffWallet(), mockWallet(), or customWallet().

Properties

available

available: boolean;

Defined in: src/core/wallets.ts:49

False when this browser can't use it; unavailableReason says why.

description?

optional description?: string;

Defined in: src/core/wallets.ts:43

A short line to show under the name.

entry?

optional entry?: WebWalletEntry;

Defined in: src/core/wallets.ts:53

The registry entry, for web wallets.

homepage?

optional homepage?: string;

Defined in: src/core/wallets.ts:47

The wallet's own website, for a "learn more" link.

iconUrl?

optional iconUrl?: string;

Defined in: src/core/wallets.ts:45

An icon to show beside the name; a data: URL when it came from a registry that inlines icons.

id

id: string;

Defined in: src/core/wallets.ts:37

"platform", a registry id, "handoff", "mock", or your own.

keys?

optional keys?: KeyCustody;

Defined in: src/core/wallets.ts:55

Key custody this wallet needs (a kiosk hand-off binds to the hand-off page's origin). Used unless the caller passes keys.

kind

kind: "platform" | "web" | "handoff" | "mock" | "custom";

Defined in: src/core/wallets.ts:39

What sort of wallet it is, for a UI that shows kinds differently.

name

name: string;

Defined in: src/core/wallets.ts:41

The name to show the patient.

unavailableReason?

optional unavailableReason?: string;

Defined in: src/core/wallets.ts:51

Why available is false, in words for a developer (for example, no Digital Credentials API in this browser).

Methods

open()

open(): WalletSession;

Defined in: src/core/wallets.ts:57

Connect to the wallet. Synchronous; call inside the click.

Returns

WalletSession

start()

start(request, options?): Promise<CheckinResult>;

Defined in: src/core/wallets.ts:59

Run a check-in with this wallet. Call inside the click.

Parameters

Parameter	Type
`request`	`CheckinRequestInput`
`options?`	`Omit`<`CheckinOptions`, `"wallet"` \| `"session"`>

Returns

Promise<CheckinResult>

WalletRegistry

type WalletRegistry = {
  source?: string;
  wallets: WebWalletEntry[];
};

Defined in: src/model/registry.ts:31

Properties

source?

optional source?: string;

Defined in: src/model/registry.ts:33

Free-form label for where this list came from.

wallets

wallets: WebWalletEntry[];

Defined in: src/model/registry.ts:34

WalletSession

type WalletSession = {
  cancel: void;
  getCredential: Promise<unknown>;
};

Defined in: src/core/wallets.ts:23

A connection to a wallet, opened inside the click.

Methods

cancel()

cancel(): void;

Defined in: src/core/wallets.ts:27

Stop waiting: closes a web wallet's tab. The check-in then ends as declined.

Returns

void

getCredential()

getCredential(navigatorArgument): Promise<unknown>;

Defined in: src/core/wallets.ts:25

Send the Digital Credentials API argument; resolves with the wallet's credential.

Parameters

Parameter	Type
`navigatorArgument`	`unknown`

Returns

Promise<unknown>

WalletsOptions

type WalletsOptions = {
  extra?: ReadonlyArray<Wallet>;
  fetch?: typeof fetch;
  includeUnavailable?: boolean;
  platform?: boolean;
  registry?:   | string
     | WalletRegistry
     | WebWalletEntry[];
};

Defined in: src/core/wallets.ts:132

Options for wallets(): which wallets a page offers.

Properties

extra?

optional extra?: ReadonlyArray<Wallet>;

Defined in: src/core/wallets.ts:138

More wallets to offer after the registry's, such as handoffWallet(...) or mockWallet().

fetch?

optional fetch?: typeof fetch;

Defined in: src/core/wallets.ts:142

Used to load a registry given as a URL. Defaults to the global fetch.

includeUnavailable?

optional includeUnavailable?: boolean;

Defined in: src/core/wallets.ts:140

Keep wallets this browser can't use in the list, marked unavailable.

platform?

optional platform?: boolean;

Defined in: src/core/wallets.ts:134

Offer the phone's own wallet (default true). Listed only when this browser can reach it, unless includeUnavailable.

registry?

optional registry?: 
  | string
  | WalletRegistry
  | WebWalletEntry[];

Defined in: src/core/wallets.ts:136

Web wallets: a registry URL, a registry, or a list of entries. None by default.

WebWalletEntry

type WebWalletEntry = {
  description?: string;
  homepage?: string;
  iconUrl?: string;
  id: string;
  name: string;
  target?: "tab" | "popup";
  walletUrl: string;
};

Defined in: src/model/registry.ts:14

Properties

description?

optional description?: string;

Defined in: src/model/registry.ts:22

One line for a picker menu.

homepage?

optional homepage?: string;

Defined in: src/model/registry.ts:26

Where to learn about or install the wallet.

iconUrl?

optional iconUrl?: string;

Defined in: src/model/registry.ts:24

Icon for a picker. Prefer a data: URL: loading a remote icon tells the wallet's server someone is on your page.

id

id: string;

Defined in: src/model/registry.ts:16

Stable identifier used in URLs, storage, and telemetry.

name

name: string;

Defined in: src/model/registry.ts:18

What the person sees: "Demo wallet".

target?

optional target?: "tab" | "popup";

Defined in: src/model/registry.ts:28

Open in a tab (default) or a popup window.

walletUrl

walletUrl: string;

Defined in: src/model/registry.ts:20

The page that answers check-in requests.

Variables

VCI_DIRECTORY_URL

const VCI_DIRECTORY_URL: "https://raw.githubusercontent.com/the-commons-project/vci-directory/main/vci-issuers.json" = "https://raw.githubusercontent.com/the-commons-project/vci-directory/main/vci-issuers.json";

Defined in: src/core/health-cards.ts:15

The public list of SMART Health Card issuers maintained by the VCI coalition.

Functions

checkinRequest()

function checkinRequest(init): SmartCheckinRequest;

Defined in: src/core/request.ts:21

Build and validate a request. type and version are fixed by the spec, id defaults to a UUID, fhirVersions to ["4.0.1"]. Throws on an invalid request.

Parameters

Parameter	Type
`init`	`CheckinRequestInit`

Returns

SmartCheckinRequest

configureHealthCardTrust()

function configureHealthCardTrust(trust): void;

Defined in: src/core/health-cards.ts:79

Set the trust used for every check-in that doesn't pass its own.

Parameters

Parameter	Type
`trust`	`HealthCardTrust`

Returns

void

customWallet()

function customWallet(init): Wallet;

Defined in: src/core/wallets.ts:116

Wrap any transport as a wallet: for experiments, tests, and new kinds of wallet.

Parameters

Parameter	Type	Description
`init`	{ `available?`: `boolean`; `description?`: `string`; `iconUrl?`: `string`; `id`: `string`; `keys?`: `KeyCustody`; `kind?`: `"platform"` \| `"web"` \| `"handoff"` \| `"mock"` \| `"custom"`; `name`: `string`; `open`: () => `WalletSession`; `unavailableReason?`: `string`; }	-
`init.available?`	`boolean`	-
`init.description?`	`string`	-
`init.iconUrl?`	`string`	-
`init.id`	`string`	-
`init.keys?`	`KeyCustody`	-
`init.kind?`	`"platform"` \| `"web"` \| `"handoff"` \| `"mock"` \| `"custom"`	-
`init.name`	`string`	-
`init.open`	() => `WalletSession`	Called inside the click. Return how to reach the wallet.
`init.unavailableReason?`	`string`	-

Returns

Wallet

detectDcApiSupport()

function detectDcApiSupport(): DcApiSupport;

Defined in: src/browser/index.ts:27

Whether this browser can reach the phone's own wallet through the Digital Credentials API. platformWallet() uses it for available.

Returns

DcApiSupport

healthCardTrust()

function healthCardTrust(): HealthCardTrust;

Defined in: src/core/health-cards.ts:84

The trust currently configured.

Returns

HealthCardTrust

platformWallet()

function platformWallet(): Wallet;

Defined in: src/core/wallets.ts:76

The phone's own wallet, through the browser's Digital Credentials API.

Returns

Wallet

runCheckin()

function runCheckin(input, options?): Promise<CheckinResult>;

Defined in: src/core/run.ts:78

Run a check-in and report what happened. Never throws for an ordinary outcome (declined, failed); throws only for a malformed request.

Parameters

Parameter	Type
`input`	`CheckinRequestInput`
`options`	`CheckinOptions`

Returns

Promise<CheckinResult>

wallets()

function wallets(options?): Promise<Wallet[]>;

Defined in: src/core/wallets.ts:150

The wallets a page offers, in order: the platform wallet, the registry's web wallets in registry order, then extra. Throws if a registry can't be loaded or is malformed.

Parameters

Parameter	Type
`options`	`WalletsOptions`

Returns

Promise<Wallet[]>

webWallet()

function webWallet(entry): Wallet;

Defined in: src/core/wallets.ts:95

A web wallet from a registry entry. Opens in a tab (or a popup, if the entry says so).

Parameters

Parameter	Type
`entry`	`WebWalletEntry`

Returns

Wallet