BiomPIN History SDK

This is the legacy history helper for existing integrations. For new work, use the Browser SDK, which includes public retrieval, sharing, identity context, and history. Follow its migration guide before replacing this script.

The legacy BiomPinSDK manages local history and identity context only. Your application makes processing and retrieval requests separately.

Load the SDK

Script tag

You can include the SDK directly from any running BiomAPI instance:

<script src="https://biomapi.com/static/js/biompin-sdk.js"></script>

The hosted script follows the current deployment. Versioned static paths serve only the deployed release; they are not a permanent archive.

Module side-effect import

import './biompin-sdk.js';

const { history, context } = window.BiomPinSDK;

---

Manage local history (BiomPinSDK.history)

The history module stores recently processed or retrieved BiomPINs in localStorage:

Create options

const store = window.BiomPinSDK.history.create({
  storageKey: 'biompin_history', // LocalStorage key
  maxEntries: 250,               // Max number of entries to keep
  storage: window.localStorage   // Storage interface (for testing)
});

If browser storage is unavailable or blocked, the store does not save entries. BiomPIN processing and retrieval continue to work, but history remains empty.

Entry schema

History entries have the following flat structure:

{
  pin: "alpha-beta-123456",
  biompin: "alpha-beta-123456",
  patient_name: "SD",
  patient_id: "SYN-001",
  expires_at: "2026-10-06T10:00:00Z",
  db_id: "db-instance-uuid",
  added_at: 1788602400000,
  accessed_at: "2026-09-05T10:00:00.000Z"
}

Methods

• add({ dbId, pin, patientName, patientId, expiresAt }): Formats and stores an entry. Removes duplicates by PIN and enforces the capacity limit.
• list(): Returns stored entries, newest first.
• search(query): Case-insensitive search on patient name, patient ID, or PIN.
• pruneExpired(): Removes expired entries and returns kept entries.
• pruneDbIdMismatch(currentDbId): Removes entries where the stored database ID differs from currentDbId, including older entries with no db_id.
• clearOne(pin): Deletes a single history entry by PIN.
• clearAll(): Removes all history entries.

---

Patient identity context (BiomPinSDK.context)

The context module passes initials and ID in a URL fragment (#biomctx=...). Ordinary HTTP requests omit the fragment, but it is reversible and readable by page scripts or anyone receiving the complete link. See identity-context privacy.

Methods

• encode({ patientName, patientId }): Encodes patient identifiers into a URL-safe, base64url-encoded JSON string.
• decodeFromLocation(location): Extracts and decodes the #biomctx=... fragment from a browser location or URL object. Returns { patientName, patientId } or null.
• fromResponse(apiResponse): Parses identity context from a standard BiomAPI JSON response.
• buildUrl(pin, identityContext): Builds a relative BiomPIN path /pin/... including the #biomctx fragment.
• buildCalculatorUrl(baseUrl, pin, identityContext): Builds an absolute target URL for an external calculator with a ?biompin=... query parameter and #biomctx fragment. Pass a base URL without an existing hash fragment.
• merge(pin, response, identityContext, historyEntries): Changes the supplied API response to restore patient name and ID. It checks identityContext first, then local history entries that match the PIN.