@dejadex/web 0.0.0-stage → 0.1.1

package/dist/lease/verify.js

@@ -0,0 +1,235 @@
+/**
+ * Lease verification on the device: an Ed25519 compact JWS (RFC 7515,
+ * `alg: EdDSA` per RFC 8037), `typ: dejadex-lease+jwt`, checked against the
+ * public keys the host embeds. Mirrors `service/src/leases/jws.ts` check for
+ * check, in the same order:
+ *
+ *   structure → header → signature (over the raw bytes) → claims shape →
+ *   time → origin → domains
+ *
+ * Nothing in an unsigned payload is looked at before the signature holds, and
+ * the algorithm comes from this code, never from the token.
+ *
+ * Signature: WebCrypto Ed25519 where the browser has it (Chrome 137+, Safari
+ * 17+, Firefox 129+, Node 22); elsewhere `@noble/ed25519` (MIT, audited,
+ * zero dependencies), loaded only then.
+ *
+ * The browser is untrusted: this check keeps an honest host from running on a
+ * lease it should not, and bounds what a dishonest one gets. The service
+ * checks every lease again.
+ */
+import { ScannerError } from '../errors.js';
+export const LEASE_ALG = 'EdDSA';
+export const LEASE_TYP = 'dejadex-lease+jwt';
+export const MAX_LEASE_TTL_SECONDS = 86_400;
+export const DEFAULT_CLOCK_SKEW_SECONDS = 60;
+const SCANNER_CODE = {
+    LEASE_MALFORMED: 'LEASE_INVALID',
+    LEASE_BAD_SIGNATURE: 'LEASE_INVALID',
+    LEASE_NOT_YET_VALID: 'LEASE_INVALID',
+    LEASE_EXPIRED: 'LEASE_EXPIRED',
+    LEASE_ORIGIN_NOT_ALLOWED: 'ORIGIN_NOT_ALLOWED',
+    LEASE_DOMAIN_NOT_ALLOWED: 'DOMAIN_NOT_ALLOWED',
+};
+export class LeaseVerificationError extends ScannerError {
+    reason;
+    constructor(reason, message) {
+        super(SCANNER_CODE[reason], `${reason}: ${message}`);
+        this.reason = reason;
+    }
+}
+const fail = (reason, message) => {
+    throw new LeaseVerificationError(reason, message);
+};
+const malformed = (why) => fail('LEASE_MALFORMED', `malformed lease: ${why}`);
+const B64URL = /^[A-Za-z0-9_-]*$/;
+/** Strict unpadded base64url: one decoding and one encoding per string, or null. */
+export function base64urlDecodeStrict(s) {
+    if (!B64URL.test(s) || s.length % 4 === 1)
+        return null;
+    const b64 = s.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat((4 - (s.length % 4)) % 4);
+    let bin;
+    try {
+        bin = atob(b64);
+    }
+    catch {
+        return null;
+    }
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    // Non-zero trailing bits decode like the canonical form; re-encoding exposes them.
+    if (base64urlEncode(out) !== s)
+        return null;
+    return out;
+}
+export function base64urlEncode(bytes) {
+    let bin = '';
+    for (const b of bytes)
+        bin += String.fromCharCode(b);
+    return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function jsonObject(bytes) {
+    let value;
+    try {
+        value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+    }
+    catch {
+        return null;
+    }
+    return typeof value === 'object' && value !== null && !Array.isArray(value) ? value : null;
+}
+function decodeHeader(segment) {
+    const bytes = base64urlDecodeStrict(segment);
+    if (bytes === null || bytes.length === 0)
+        return malformed('header is not base64url');
+    const header = jsonObject(bytes);
+    if (header === null)
+        return malformed('header is not a JSON object');
+    if (header.alg !== LEASE_ALG)
+        return malformed(`unsupported alg ${JSON.stringify(header.alg)}`);
+    if (header.typ !== LEASE_TYP)
+        return malformed(`unexpected typ ${JSON.stringify(header.typ)}`);
+    if ('crit' in header)
+        return malformed('crit header not supported');
+    for (const key of Object.keys(header)) {
+        if (key !== 'alg' && key !== 'typ' && key !== 'kid')
+            return malformed(`unexpected header parameter ${key}`);
+    }
+    if (header.kid !== undefined && (typeof header.kid !== 'string' || header.kid.length === 0))
+        return malformed('kid must be a non-empty string');
+    return header.kid === undefined ? {} : { kid: header.kid };
+}
+const nonEmpty = (v) => typeof v === 'string' && v.length > 0;
+const stringArray = (v) => Array.isArray(v) && v.length > 0 && v.every(nonEmpty);
+const unixSeconds = (v) => Number.isSafeInteger(v) && v >= 0;
+function toClaims(raw) {
+    const { iss, sub, uid, jti, origins, domains, modelVersion, indexVersion, allowance, iat, exp } = raw;
+    if (!nonEmpty(iss))
+        return malformed('iss');
+    if (!nonEmpty(sub))
+        return malformed('sub');
+    if (!nonEmpty(uid))
+        return malformed('uid');
+    if (!nonEmpty(jti))
+        return malformed('jti');
+    if (!stringArray(origins))
+        return malformed('origins');
+    if (!stringArray(domains))
+        return malformed('domains');
+    if (!nonEmpty(modelVersion))
+        return malformed('modelVersion');
+    if (!nonEmpty(indexVersion))
+        return malformed('indexVersion');
+    if (!Number.isSafeInteger(allowance) || allowance <= 0)
+        return malformed('allowance');
+    if (!unixSeconds(iat))
+        return malformed('iat');
+    if (!unixSeconds(exp))
+        return malformed('exp');
+    if (exp <= iat)
+        return malformed('exp must be after iat');
+    if (exp - iat > MAX_LEASE_TTL_SECONDS)
+        return malformed('lifetime exceeds 24 h');
+    return { iss, sub, uid, jti, origins: [...origins], domains: [...domains], modelVersion, indexVersion, allowance: allowance, iat, exp };
+}
+/** The encoding of the Ed25519 base point: a key every implementation must accept. */
+const BASE_POINT = new Uint8Array([0x58, ...new Array(31).fill(0x66)]);
+let webCryptoEd25519 = null;
+/** Whether this runtime's WebCrypto does Ed25519, probed once with a known-good key. */
+export function hasWebCryptoEd25519() {
+    webCryptoEd25519 ??= (async () => {
+        const subtle = globalThis.crypto?.subtle;
+        if (!subtle)
+            return false;
+        try {
+            await subtle.importKey('raw', BASE_POINT, { name: 'Ed25519' }, false, ['verify']);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    })();
+    return webCryptoEd25519;
+}
+/** WebCrypto Ed25519 when the runtime has it, else `@noble/ed25519`. Any error is "does not verify". */
+export const defaultEd25519Verify = async (publicKey, message, signature) => {
+    try {
+        if (await hasWebCryptoEd25519()) {
+            const subtle = globalThis.crypto.subtle;
+            const key = await subtle.importKey('raw', publicKey, { name: 'Ed25519' }, false, ['verify']);
+            return await subtle.verify({ name: 'Ed25519' }, key, signature, message);
+        }
+        return await nobleEd25519Verify(publicKey, message, signature);
+    }
+    catch {
+        return false;
+    }
+};
+/** The fallback on its own, for runtimes without WebCrypto Ed25519 (and its tests). */
+export const nobleEd25519Verify = async (publicKey, message, signature) => {
+    const noble = await import('@noble/ed25519');
+    try {
+        return await noble.verifyAsync(signature, message, publicKey);
+    }
+    catch {
+        return false;
+    }
+};
+/** Verifies `token` and returns the lease, or throws a `LeaseVerificationError`. */
+export async function verifyLease(token, options) {
+    if (typeof token !== 'string')
+        return malformed('token is not a string');
+    const parts = token.split('.');
+    if (parts.length !== 3)
+        return malformed('expected three dot-separated segments');
+    const [headerB64 = '', payloadB64 = '', signatureB64 = ''] = parts;
+    const header = decodeHeader(headerB64);
+    const payload = base64urlDecodeStrict(payloadB64);
+    if (payload === null || payload.length === 0)
+        return malformed('payload is not base64url');
+    const signature = base64urlDecodeStrict(signatureB64);
+    if (signature === null)
+        return malformed('signature is not base64url');
+    if (signature.length !== 64)
+        return fail('LEASE_BAD_SIGNATURE', 'signature has the wrong length');
+    const keys = options.publicKeys.filter((k) => header.kid === undefined || k.kid === undefined || k.kid === header.kid);
+    if (keys.length === 0)
+        return fail('LEASE_BAD_SIGNATURE', header.kid ? `no public key with kid ${header.kid}` : 'no public key');
+    const message = new TextEncoder().encode(`${headerB64}.${payloadB64}`);
+    const verify = options.verify ?? defaultEd25519Verify;
+    let valid = false;
+    for (const key of keys) {
+        if ((key.kty !== undefined && key.kty !== 'OKP') || (key.crv !== undefined && key.crv !== 'Ed25519'))
+            continue;
+        if ((key.alg !== undefined && key.alg !== LEASE_ALG) || (key.use !== undefined && key.use !== 'sig'))
+            continue;
+        const raw = base64urlDecodeStrict(key.x);
+        if (raw === null || raw.length !== 32)
+            continue;
+        if (await verify(raw, message, signature)) {
+            valid = true;
+            break;
+        }
+    }
+    if (!valid)
+        return fail('LEASE_BAD_SIGNATURE', 'signature does not verify');
+    const raw = jsonObject(payload);
+    if (raw === null)
+        return malformed('payload is not a JSON object');
+    const claims = toClaims(raw);
+    const now = options.now ?? Math.floor(Date.now() / 1000);
+    const skew = options.clockSkewSeconds ?? DEFAULT_CLOCK_SKEW_SECONDS;
+    if (now >= claims.exp)
+        return fail('LEASE_EXPIRED', `lease expired at ${claims.exp}`);
+    if (claims.iat > now + skew)
+        return fail('LEASE_NOT_YET_VALID', `lease issued at ${claims.iat}, in the future`);
+    if (options.origin !== null && !claims.origins.includes(options.origin)) {
+        return fail('LEASE_ORIGIN_NOT_ALLOWED', `origin ${options.origin} is not allowed by this lease`);
+    }
+    const missing = options.domains.filter((d) => !claims.domains.includes(d));
+    if (missing.length > 0)
+        return fail('LEASE_DOMAIN_NOT_ALLOWED', `domains not granted: ${missing.join(', ')}`);
+    return { token, claims };
+}
+//# sourceMappingURL=verify.js.map

package/dist/lease/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../../src/lease/verify.ts"],"names":[],"mappings":"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"}

package/dist/scanner.d.ts

@@ -0,0 +1,10 @@
+import type { Scanner, ScannerOptions } from './types.js';
+/**
+ * Creates a scanner. Options are checked now, so a misconfigured host fails
+ * at the call site rather than at the first frame.
+ *
+ * STUB: the pipeline (openspec/changes/web-sdk-pipeline) is not built yet.
+ * `start` and `identify` reject with `NOT_IMPLEMENTED`; the shape is final.
+ */
+export declare function createScanner(options: ScannerOptions): Scanner;
+//# sourceMappingURL=scanner.d.ts.map

package/dist/scanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scanner.d.ts","sourceRoot":"","sources":["../src/scanner.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAc,OAAO,EAAE,cAAc,EAA6B,MAAM,YAAY,CAAA;AAIhG;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CA4B9D"}

package/dist/scanner.js

@@ -0,0 +1,58 @@
+import { ScannerError } from './errors.js';
+const DOMAIN_CODE = /^[a-z][a-z0-9]*_[a-z]{2}$/;
+/**
+ * Creates a scanner. Options are checked now, so a misconfigured host fails
+ * at the call site rather than at the first frame.
+ *
+ * STUB: the pipeline (openspec/changes/web-sdk-pipeline) is not built yet.
+ * `start` and `identify` reject with `NOT_IMPLEMENTED`; the shape is final.
+ */
+export function createScanner(options) {
+    validate(options);
+    let state = 'idle';
+    const notYet = (what) => Promise.reject(new ScannerError('NOT_IMPLEMENTED', `${what} is not implemented yet`));
+    return {
+        get state() {
+            return state;
+        },
+        get tier() {
+            return null;
+        },
+        start() {
+            if (state === 'destroyed')
+                return Promise.reject(new ScannerError('INVALID_OPTIONS', 'scanner was destroyed'));
+            return notYet('live scanning');
+        },
+        stop() {
+            if (state === 'running')
+                state = 'stopped';
+        },
+        identify() {
+            return notYet('snapshot identification');
+        },
+        async destroy() {
+            state = 'destroyed';
+        },
+    };
+}
+function validate(options) {
+    const fail = (message) => {
+        throw new ScannerError('INVALID_OPTIONS', message);
+    };
+    if (typeof options?.getLease !== 'function')
+        fail('getLease must be a function');
+    if (typeof options.reportUsage !== 'function')
+        fail('reportUsage must be a function');
+    if (typeof options.onTracks !== 'function')
+        fail('onTracks must be a function');
+    if (!Array.isArray(options.domains) || options.domains.length === 0)
+        fail('domains must list at least one domain');
+    for (const d of options.domains) {
+        if (typeof d !== 'string' || !DOMAIN_CODE.test(d))
+            fail(`not a domain code: ${String(d)}`);
+    }
+    const tiers = ['auto', 'live_full', 'live_reduced', 'snapshot'];
+    if (options.tier !== undefined && !tiers.includes(options.tier))
+        fail(`unknown tier: ${String(options.tier)}`);
+}
+//# sourceMappingURL=scanner.js.map

package/dist/scanner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scanner.js","sourceRoot":"","sources":["../src/scanner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAG1C,MAAM,WAAW,GAAG,2BAA2B,CAAA;AAE/C;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,OAAuB;IACnD,QAAQ,CAAC,OAAO,CAAC,CAAA;IAEjB,IAAI,KAAK,GAAiB,MAAM,CAAA;IAChC,MAAM,MAAM,GAAG,CAAC,IAAY,EAAE,EAAE,CAC9B,OAAO,CAAC,MAAM,CAAC,IAAI,YAAY,CAAC,iBAAiB,EAAE,GAAG,IAAI,yBAAyB,CAAC,CAAC,CAAA;IAEvF,OAAO;QACL,IAAI,KAAK;YACP,OAAO,KAAK,CAAA;QACd,CAAC;QACD,IAAI,IAAI;YACN,OAAO,IAAI,CAAA;QACb,CAAC;QACD,KAAK;YACH,IAAI,KAAK,KAAK,WAAW;gBAAE,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,YAAY,CAAC,iBAAiB,EAAE,uBAAuB,CAAC,CAAC,CAAA;YAC9G,OAAO,MAAM,CAAC,eAAe,CAAC,CAAA;QAChC,CAAC;QACD,IAAI;YACF,IAAI,KAAK,KAAK,SAAS;gBAAE,KAAK,GAAG,SAAS,CAAA;QAC5C,CAAC;QACD,QAAQ;YACN,OAAO,MAAM,CAAC,yBAAyB,CAAC,CAAA;QAC1C,CAAC;QACD,KAAK,CAAC,OAAO;YACX,KAAK,GAAG,WAAW,CAAA;QACrB,CAAC;KACF,CAAA;AACH,CAAC;AAED,SAAS,QAAQ,CAAC,OAAuB;IACvC,MAAM,IAAI,GAAG,CAAC,OAAe,EAAS,EAAE;QACtC,MAAM,IAAI,YAAY,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAAA;IACpD,CAAC,CAAA;IACD,IAAI,OAAO,OAAO,EAAE,QAAQ,KAAK,UAAU;QAAE,IAAI,CAAC,6BAA6B,CAAC,CAAA;IAChF,IAAI,OAAO,OAAO,CAAC,WAAW,KAAK,UAAU;QAAE,IAAI,CAAC,gCAAgC,CAAC,CAAA;IACrF,IAAI,OAAO,OAAO,CAAC,QAAQ,KAAK,UAAU;QAAE,IAAI,CAAC,6BAA6B,CAAC,CAAA;IAC/E,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,IAAI,CAAC,uCAAuC,CAAC,CAAA;IAClH,KAAK,MAAM,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QAChC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC;YAAE,IAAI,CAAC,sBAAsB,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;IAC5F,CAAC;IACD,MAAM,KAAK,GAAuB,CAAC,MAAM,EAAE,WAAW,EAAE,cAAc,EAAE,UAAU,CAAC,CAAA;IACnF,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,IAAI,CAAC,iBAAiB,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;AAChH,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,180 @@
+/**
+ * The SDK's public types. These are the contract the first client tenant (and
+ * every later one) builds against, so they are settled before the pipeline
+ * behind them exists: see openspec/changes/web-sdk-pipeline and
+ * openspec/changes/lease-licensing for the behaviour each field promises.
+ */
+import type { Homography, Quad } from './geometry/homography.js';
+/**
+ * A catalogue domain: one franchise in one language, and one index shard.
+ * Codes are neutral by rule (`tcg01_en`, `tcg01_ja`, `tcg02_en`, …); a
+ * franchise name never appears in one.
+ */
+export type DomainCode = string;
+/** A print's platform-owned id. Opaque to clients; map through `externalIds`. */
+export type PrintId = string;
+/**
+ * Ids of the same print in third-party catalogues, keyed by source
+ * (e.g. `{ tcgdex: "<set>-<number>" }`). A client maps its own ids through
+ * the source it already uses.
+ */
+export type ExternalIds = Readonly<Record<string, string>>;
+/** A finish of a print, e.g. `normal`, `holo`, `reverse_holo`, `first_edition`. Domain-defined. */
+export type VariantCode = string;
+/** What the device can sustain, chosen at start-up (`auto`) or forced by the host. */
+export type DeviceTier = 'live_full' | 'live_reduced' | 'snapshot';
+/** The claims of a lease, as the service signs them. Times are Unix seconds. */
+export interface LeaseClaims {
+    /** The issuing service. */
+    readonly iss: string;
+    /** The tenant the lease bills to. */
+    readonly sub: string;
+    /** The tenant's end user, hashed by the service; never the client's raw id. */
+    readonly uid: string;
+    /** This lease's id; usage reports and renewals name it. */
+    readonly jti: string;
+    /** Page origins the lease runs on, exact `scheme://host[:port]` matches. */
+    readonly origins: readonly string[];
+    /** Index shards the lease unlocks. */
+    readonly domains: readonly DomainCode[];
+    /** The embedding model version; locked to `indexVersion`. */
+    readonly modelVersion: string;
+    readonly indexVersion: string;
+    /** Identifications this lease permits before it must be renewed. */
+    readonly allowance: number;
+    readonly iat: number;
+    readonly exp: number;
+}
+/** A verified lease: the compact JWS the client's backend handed over, and its claims. */
+export interface Lease {
+    readonly token: string;
+    readonly claims: LeaseClaims;
+}
+/** What the SDK asks the host for when it needs a lease. */
+export interface LeaseRequest {
+    /** The lease being renewed, or null for the first one on this device. */
+    readonly previousLeaseId: string | null;
+    /**
+     * The last usage sequence number already accepted by `reportUsage` for the
+     * previous lease. The service refuses a renewal whose previous lease has
+     * unreported usage.
+     */
+    readonly usageReportedThrough: number | null;
+}
+/** What the host's backend returns from the service's `POST /v1/leases`, passed through as is. */
+export interface LeaseGrant {
+    /** The signed lease, compact JWS. */
+    readonly token: string;
+    /** Signed URL of the manifest that lists model and index files for this lease. */
+    readonly manifestUrl: string;
+}
+/** One of the top-K guesses for a track. */
+export interface Candidate {
+    readonly printId: PrintId;
+    readonly externalIds: ExternalIds;
+    /** Cosine similarity to the reference embedding, in [-1, 1]. */
+    readonly score: number;
+}
+/**
+ * One physical card the SDK is following, as of the latest processed frame.
+ *
+ * `printId` is null until the track is confirmed, and stays null when the
+ * crop matched nothing above the threshold (`status: 'unknown'`): the
+ * catalogue is closed, so a miss is reported as a miss with its best guesses,
+ * never as a near neighbour.
+ */
+export interface TrackResult {
+    /** Stable for as long as the card stays tracked. */
+    readonly trackId: number;
+    readonly status: 'pending' | 'confirmed' | 'unknown';
+    /** Corners in the source frame's pixel space (y down): TL, TR, BR, BL of the card. The host maps them to its own layout (e.g. object-fit: cover) before drawing. */
+    readonly quad: Quad;
+    /** Unit card rectangle → `quad`; `toCssMatrix3d` turns it into a transform. */
+    readonly homography: Homography;
+    readonly domain: DomainCode | null;
+    readonly printId: PrintId | null;
+    readonly externalIds: ExternalIds;
+    /** Null when the variant is unresolved: the host shows a picker, never a guess. */
+    readonly variant: VariantCode | null;
+    /** In [0, 1]; the SDK's own calibrated belief in `printId`. */
+    readonly confidence: number;
+    /** The top-K candidates (K = 5), best first, including the chosen one. */
+    readonly alternates: readonly Candidate[];
+}
+/**
+ * What one scan session counted under one lease since its previous report.
+ *
+ * The billing unit is a distinct card per scan session: a card is charged the
+ * first time it is identified in a session, by whichever side identified it,
+ * and never again in that session however often it is seen. Misses, "not a
+ * card" answers and retries are never charged. See openspec/changes/
+ * lease-licensing, usage-metering.
+ */
+export interface UsageReport {
+    /** Unique per report, so a report sent twice is counted once. */
+    readonly reportId: string;
+    /** The lease's `jti`. */
+    readonly leaseId: string;
+    /** Per lease, from 1, up by exactly 1 per report; renewals name the last one accepted. */
+    readonly seq: number;
+    /** The scan session: random, at least 128 bits, one per scanner session. */
+    readonly sessionId: string;
+    /** Cards first identified in this session since its previous report, excluding any the service counted. */
+    readonly distinctCards: number;
+    /** Those cards' print ids, so the service can charge each at most once per session. */
+    readonly cardIds?: readonly PrintId[];
+    /** Identify attempts behind this report, retries and "not a card" answers included. Informational, never charged. */
+    readonly calls?: number;
+    /** Device clock, Unix milliseconds. Informational; the service orders by `seq`. */
+    readonly at?: number;
+}
+/** A batch the SDK hands to `reportUsage`, flushed from its IndexedDB queue. */
+export interface UsageBatch {
+    /** A random per-install id (not a fingerprint), for monthly active devices. */
+    readonly deviceId: string;
+    /** May be empty: one batch per lease used is delivered even with nothing to report. */
+    readonly reports: readonly UsageReport[];
+}
+/** Where live frames come from. */
+export type FrameSourceInput = MediaStream | HTMLVideoElement;
+export interface ScannerOptions {
+    /**
+     * Obtain a lease. The host calls its own backend, which calls the service's
+     * `POST /v1/leases` with the tenant's secret key; the secret never reaches
+     * the browser. Called at start and before the current lease runs out.
+     */
+    getLease(request: LeaseRequest): Promise<LeaseGrant>;
+    /**
+     * Deliver queued usage. The host's backend forwards it to `POST /v1/usage`.
+     * Resolve only once it is accepted; a rejection leaves the batch queued.
+     */
+    reportUsage(batch: UsageBatch): Promise<void>;
+    /** The domains to search; each must be granted by the lease. */
+    readonly domains: readonly DomainCode[];
+    /** Every processed frame's tracks, on the main thread. */
+    onTracks(tracks: readonly TrackResult[]): void;
+    /** Errors the host should know about (lease, device, downloads). */
+    onError?(error: Error): void;
+    /** Force a tier, or let the SDK pick from the device's capabilities. Default `auto`. */
+    readonly tier?: DeviceTier | 'auto';
+    /**
+     * The scan session usage is charged by (each distinct card once per session).
+     * Give one per visit to the host's scanner; default: a new random id per scanner.
+     */
+    readonly sessionId?: string;
+}
+export type ScannerState = 'idle' | 'starting' | 'running' | 'stopped' | 'failed' | 'destroyed';
+export interface Scanner {
+    readonly state: ScannerState;
+    /** The tier in use, once started. */
+    readonly tier: DeviceTier | null;
+    /** Live mode: follow and identify every card in `source`. */
+    start(source: FrameSourceInput): Promise<void>;
+    /** Pause live mode; tracks are dropped, caches are kept. */
+    stop(): void;
+    /** Snapshot mode: identify every card in one image. */
+    identify(image: ImageBitmap | Blob): Promise<readonly TrackResult[]>;
+    /** Release the Worker, the sessions and the camera hooks. */
+    destroy(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/usage/meter.d.ts

@@ -0,0 +1,83 @@
+/**
+ * What an identification costs: one per distinct card per scan session
+ * (lease-licensing, usage-metering).
+ *
+ * A session is one visit to a host's scanner (the host's `session` id, or the
+ * identifier's own). Within it, the first confident `card` answer for a
+ * `cardId` is charged once; the same card again in the session is free, and
+ * so are `not_a_card` answers, answers that are not confident (the host asks
+ * the user instead of asserting), and `retry` calls.
+ *
+ * A server answer that carries an `identificationId` was charged by the
+ * service itself: it adds no card to the report, but still marks the card as
+ * seen in the session and still counts toward the lease's allowance.
+ *
+ * Every call is tallied in the `UsageStore` before its answer reaches the
+ * host. `drain` seals the open tallies into `UsageReport`s and hands them to
+ * the host in batches; a batch leaves the store only once the host's delivery
+ * resolves.
+ */
+import type { LeaseClaims, LeaseRequest, UsageBatch } from '../types.js';
+import type { IdentifyPurpose, IdentifyResult } from '../identify/types.js';
+import { type UsageStore } from './store.js';
+/** Reports per batch handed to the host. */
+export declare const MAX_BATCH_REPORTS = 500;
+export interface MeterOptions {
+    readonly store: UsageStore;
+    readonly now?: () => number;
+    readonly newId?: () => string;
+}
+export interface MeterInput {
+    readonly lease: LeaseClaims;
+    readonly session: string;
+    readonly purpose: IdentifyPurpose | undefined;
+    readonly results: readonly IdentifyResult[];
+}
+export interface DrainResult {
+    /** Reports delivered by this drain. */
+    readonly delivered: number;
+    /** Reports and open tallies still queued. */
+    readonly pending: number;
+}
+export interface RecordResult {
+    /** Cards this call charged on the device (first seen in the session, not counted by the service). */
+    readonly charged: readonly string[];
+    /** Cards the service had already charged (`identificationId`). */
+    readonly serverCharged: number;
+}
+export declare class UsageMeter {
+    private readonly store;
+    private readonly now;
+    private readonly newId;
+    /** session → card ids already charged (by either side) in it. */
+    private readonly seen;
+    /** lease id → cards charged under it on this page (device + service). */
+    private readonly used;
+    private chain;
+    constructor(options: MeterOptions);
+    /** Cards charged under `leaseId` on this page so far. */
+    usedUnder(leaseId: string): number;
+    /** Whether the lease's allowance is used up. */
+    exhausted(lease: LeaseClaims): boolean;
+    /** Tallies one call's answers; resolves once the tally is stored. */
+    record(input: MeterInput): Promise<RecordResult>;
+    /**
+     * Seals the open tallies and hands the queued reports to `deliver` in
+     * batches of at most 500, oldest first. Each batch is removed once `deliver`
+     * resolves; a rejection stops the drain, leaves that batch queued, and is
+     * rethrown.
+     */
+    drain(deliver: (batch: UsageBatch) => Promise<void>): Promise<DrainResult>;
+    pending(): Promise<number>;
+    /**
+     * Makes sure the lease gets at least one report, even if nothing is ever
+     * identified under it: the service renews a lease only once the previous
+     * one has reported (an empty report counts).
+     */
+    touch(leaseId: string, session: string): Promise<void>;
+    /** What the host's lease request carries about the lease being renewed. */
+    leaseRequest(previousLeaseId: string | null): Promise<LeaseRequest>;
+    private sessionSet;
+    private serial;
+}
+//# sourceMappingURL=meter.d.ts.map

package/dist/usage/meter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meter.d.ts","sourceRoot":"","sources":["../../src/usage/meter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxE,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC3E,OAAO,EAAY,KAAK,UAAU,EAAE,MAAM,YAAY,CAAA;AAEtD,4CAA4C;AAC5C,eAAO,MAAM,iBAAiB,MAAM,CAAA;AAIpC,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,MAAM,CAAA;CAC9B;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAA;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,SAAS,CAAA;IAC7C,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAA;CAC5C;AAED,MAAM,WAAW,WAAW;IAC1B,uCAAuC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,qGAAqG;IACrG,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,kEAAkE;IAClE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAC/B;AAED,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAY;IAClC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAc;IAClC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IACpC,iEAAiE;IACjE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiC;IACtD,yEAAyE;IACzE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA4B;IACjD,OAAO,CAAC,KAAK,CAAsC;gBAEvC,OAAO,EAAE,YAAY;IAMjC,yDAAyD;IACzD,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAIlC,gDAAgD;IAChD,SAAS,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO;IAItC,qEAAqE;IACrE,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,YAAY,CAAC;IAqBhD;;;;;OAKG;IACG,KAAK,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC;IAgBhF,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;IAI1B;;;;OAIG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAItD,2EAA2E;IACrE,YAAY,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC;IAOzE,OAAO,CAAC,UAAU;IAalB,OAAO,CAAC,MAAM;CAKf"}