Kill the Clipboard - SMART Health Cards Library - v1.0.0
    Preparing search index...

    Class SHL

    Immutable SHL class representing a SMART Health Link payload and URI.

    This class handles the SHL "pointer" - the payload containing url, key, flags, etc. It provides methods to generate SHL URIs and access payload properties. Use SHLManifestBuilder to manage the manifest and files referenced by this SHL.

    SMART Health Links enable secure sharing of health data through encrypted links. The SHL contains a manifest URL and encryption key, allowing recipients to fetch and decrypt the shared health information.

    // Generate a new SHL
    const shl = SHL.generate({
      baseManifestURL: 'https://shl.example.org/manifests/',
      manifestPath: '/manifest.json',
      expirationDate: new Date('2024-12-31'),
      flag: 'P',
      label: 'COVID-19 Vaccination Record'
    });

    // Generate the SHL URI
    const uri = shl.toURI();
    console.log(uri); // shlink:/eyJ1cmwiOi...
    Index

    Accessors

    exp expirationDate flag id isDirectFile isLongTerm key label payload requiresPasscode url version

    Methods

    asQR fromPayload generate parse toURI

    Accessors

    • get exp(): undefined | number

      Get the expiration date as Unix timestamp if set.

      Returns the expiration time in seconds since Unix epoch (1970-01-01), suitable for use in the SHL payload exp field.

      Returns undefined | number

      Unix timestamp in seconds, or undefined if no expiration set

    • get expirationDate(): undefined | Date

      Get the expiration date as a Date object if set.

      Returns undefined | Date

      Date object representing expiration time, or undefined if no expiration set

    • get flag(): undefined | SHLFlag

      Get the SHL flags if set.

      Returns the flag string indicating SHL capabilities.

      Returns undefined | SHLFlag

      Flag string, or undefined if no flags set

    • get id(): undefined | string

      Get the server-generated ID for database if set.

      Returns the optional ID that can be used by server implementations to identify this SHL in the DB.

      Returns undefined | string

      Server-generated ID string, or undefined if no ID was provided

    • get isDirectFile(): boolean

      Check if this SHL is a direct-file link (bypasses manifest).

      Returns true if the SHL has the 'U' flag, indicating that the url points directly to a single encrypted file retrievable via GET.

      Returns boolean

    • get isLongTerm(): boolean

      Check if this SHL supports long-term access with updates.

      Returns true if the SHL has the 'L' flag, indicating that clients may poll the manifest URL for updates over time.

      Returns boolean

      True if long-term access is supported, false otherwise

    • get key(): string

      Get the base64url-encoded encryption key for files.

      Returns the 256-bit symmetric encryption key used for JWE file encryption, encoded as base64url (always 43 characters).

      Returns string

      Base64url-encoded encryption key (43 characters)

    • get label(): undefined | string

      Get the human-readable label if set.

      Returns the optional short description of the shared data. Maximum length is 80 characters as per SHL specification.

      Returns undefined | string

      Label string, or undefined if no label set

    • get payload(): SHLPayloadV1

      Get the complete SHL payload object for serialization.

      Returns the payload structure that gets base64url-encoded in the SHL URI. Includes all fields: url, key, version, and optional exp, flag, label.

      Returns SHLPayloadV1

      SHL payload object conforming to v1 specification

    • get requiresPasscode(): boolean

      Check if this SHL requires a passcode for access.

      Returns true if the SHL has the 'P' flag, indicating that a passcode must be provided when fetching the manifest.

      Returns boolean

      True if passcode is required, false otherwise

    • get version(): 1

      Get the SHL payload version.

      Always returns 1 for the current SMART Health Links v1 specification.

      Returns 1

      Version number (always 1)

    Methods

    • Generate a QR code as a Data URL for the SHL URI.

      Creates a QR code image encoded as a base64 Data URL that can be used directly in HTML img tags or displayed in applications.

      Parameters

      • Optionalparams: SHLQREncodeParams

        Optional QR code generation options. The object can contain:

        • viewerURL: URL of the SHL viewer to prefix the QR code like https://example.org/viewer#shlink:/... (default: no URL)
        • width: Width of the QR code image in pixels (default: 256)
        • margin: Margin around the QR code in modules (default: 1)
        • errorCorrectionLevel: Error correction level 'L', 'M', 'Q', or 'H' (default: 'M', per spec)
        • color: Color options for dark and light modules

      Returns Promise<string>

      Promise that resolves to a Data URL string

      const shl = SHL.generate({
        baseManifestURL: 'https://shl.example.org',
        manifestPath: '/manifest.json'
      });

      const qrCodeDataURL = await shl.asQR();
      // Use in HTML: <img src={qrCodeDataURL} alt="SHL QR Code" />

      // With custom options
      const customQR = await shl.asQR({
        width: 512,
        errorCorrectionLevel: 'H',
        color: { dark: '#000000', light: '#FFFFFF' }
      });

    • Static factory method to create an SHL from a parsed payload.

      This method is used internally by SHLViewer to reconstruct SHL objects from parsed SHL URIs. It does not generate new keys or paths, but uses the provided values from an existing payload.

      Parameters

      • payload: SHLPayloadV1

        Validated SHL payload from a parsed URI

      • Optionalid: string

        Optional server-generated ID for database

      Returns SHL

      SHL instance reconstructed from the payload

    • Create an immutable SHL representing a SMART Health Link payload and URI.

      The SHL payload contains a cryptographically secure manifest URL and encryption key. The manifest URL is constructed as: ${baseManifestURL}/${entropy}/${manifestPath} where entropy is a 32-byte base64url string (43 chars). The encryption key is a separate 32-byte base64url string (43 chars) placed in the SHL payload key.

      Parameters

      • params: {
            baseManifestURL: string;
            expirationDate?: Date;
            flag?: SHLFlag;
            id?: string;
            label?: string;
            manifestPath?: string;
        }
        • baseManifestURL: string

          Base URL for constructing manifest URLs (e.g., 'https://shl.example.org/manifests/')

        • OptionalexpirationDate?: Date

          Optional expiration date for the SHL. When set, fills the exp field in the SHL payload with Unix timestamp.

        • Optionalflag?: SHLFlag

          Optional flag for the SHL (see SHLFlag)

        • Optionalid?: string

          Optional server-generated ID for database.

        • Optionallabel?: string

          Optional short description of the shared data. Maximum 80 characters.

        • OptionalmanifestPath?: string

          Optional manifestPath for constructing manifest URLs (e.g., '/manifest.json')

      Returns SHL

      New SHL instance with generated full manifest URL and encryption key

      SHLFormatError When label exceeds 80 characters

      // SHL with server-generated ID and passcode protection
      const shl = SHL.generate({
        id: 'server-generated-uuid',
        baseManifestURL: 'https://shl.example.org',
        manifestPath: '/manifest.json',
        expirationDate: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000), // 30 days
        flag: 'P',
        label: 'Lab Results - Valid for 30 days'
      });

    • Static method to parse a SHL URI into an SHL object.

      Handles both bare SHL URIs and viewer-prefixed URIs:

      • shlink:/eyJ1cmwiOi4uLn0 (bare)
      • https://viewer.example/#shlink:/eyJ1cmwiOi4uLn0 (viewer-prefixed)

      Validates URI format, decodes base64url payload, parses JSON, and validates payload structure according to SHL specification.

      Parameters

      • shlinkURI: string

        SHL URI to parse

      Returns SHL

      SHL instance with parsed payload data

      SHLFormatError When URI format is invalid, payload cannot be decoded, or payload structure is invalid

    • Generate the SHL URI following the SMART Health Links specification.

      Creates a shlink:/ URI with base64url-encoded JSON payload containing the manifest URL, encryption key, and optional metadata (expiration, flags, label).

      Returns string

      SHL URI string in format shlink:/<base64url-encoded-payload>

      // SHL with expiration and passcode protection
      const shl = SHL.generate({
        baseManifestURL: 'https://shl.example.org',
        manifestPath: '/manifest.json',
        expirationDate: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000), // 30 days
        flag: 'P',
        label: 'Lab Results - Valid for 30 days'
      });
      // Generate the SHL URI
      const uri = shl.toURI();
      // Returns: shlink:/eyJ1cmwiOiJodHRwczovL3NobC5leGFtcGxlLm9yZy9tYW5pZmVzdHMvLi4uXCIsXCJrZXlcIjpcIi4uLlwiLFwidlwiOjF9

    Settings

    Member Visibility

    On This Page

    Accessors
    Methods