@proveanything/smartlinks 2.1.8 → 2.1.11

package/dist/docs/tag-ranges.md

@@ -0,0 +1,75 @@
+# NFC tag ranges and partners
+
+For partners and enterprise clients who run their own tag programmes: mint a batch of tags, send them
+to a manufacturer with instructions, get the chip UIDs back, then put the tags to work for a client or
+product. Ordinary business collections don't use this.
+
+## The words
+
+| Word | Means |
+|---|---|
+| **Claim set** | A pool of codes on one tap domain and one tag type (NTAG 424 DNA, NTAG 213/215/216, or QR). Most partners need one. |
+| **Range** | A named, contiguous block of tags inside a set: "Tap to donate - February", 100 tags, indexes 201-300. |
+| **Index** | A tag's place in its set. Ranges never overlap and indexes are never reused. |
+| **Partner** | An organisation above collections that owns sets and assigns their tags into collections its people administer. Set up by SmartLinks staff. |
+
+## Who can do what
+
+`scope` is `{ partnerId }` for a partner's sets, or `{ collectionId }` for a collection's own sets.
+
+| Role | Can |
+|---|---|
+| Partner owner / admin, or a collection admin | Make sets, mint ranges, download the printer file and instructions, import UIDs, program tags, assign |
+| Partner assigner | See ranges and tags (never keys), assign |
+
+Assigning always needs you to be an admin of the collection the tags go to.
+
+## The flow
+
+```ts
+import { partner, claimSet } from '@proveanything/smartlinks'
+
+const [p] = await partner.list()                       // the partners you belong to
+const scope = { partnerId: p.id }
+const [set] = await partner.claimSets(p.id)            // or partner.createClaimSet(p.id, { name, tagType: 'ntag424', tapDomain })
+
+// 1. Mint
+const range = await claimSet.ranges.create(scope, set.id, { name: 'Tap to donate - February', quantity: 100 })
+
+// 2. Send to print: the CSV (carries each tag's key) and the instruction sheet
+const file = await claimSet.ranges.exportFile(scope, set.id, range.id)          // { filename, csv }
+const sheet = await claimSet.ranges.instructions(scope, set.id, range.id, 'pdf') // { filename, base64 }
+await claimSet.ranges.update(scope, set.id, range.id, { stage: 'sent', manufacturer: 'Print Co', orderRef: 'PO-123' })
+
+// 3. Receive: the manufacturer sends back the same file with UID filled in
+const check = await claimSet.ranges.importUids(scope, set.id, range.id, { csv: returnedCsv })
+// check.rows: ok / index_mismatch / bad_uid / uid_in_use / … ; nothing written yet
+await claimSet.ranges.importUids(scope, set.id, range.id, { csv: returnedCsv, commit: true })
+
+// 4. Assign all of it, or from-to
+await claimSet.ranges.assign(scope, set.id, range.id, { collectionId: 'reading-fc', productId: 'scarf', start: 201, end: 250 })
+```
+
+**Programming on a phone instead of a manufacturer** (Sidekick): `ranges.next()` gives the lowest
+tag without a chip, with its URL and key; write it, then `ranges.recordTag(scope, set.id, range.id, code, { uid })`.
+
+## The printer file
+
+One row per tag, in index order. The manufacturer fills in `UID` and sends the same file back; rows are
+matched by `Code`, and `Index` is checked.
+
+| Tag type | Columns |
+|---|---|
+| NTAG 424 DNA | `Index, Code, URL, PiccOffset, Key, UID` |
+| NTAG 213/215/216 | `Index, Code, URL, MirrorOffset, MirrorPage, MirrorByte, UID` |
+| QR | `Index, Code, URL` |
+
+`URL` is `https://{tap domain}/t/{set}/{code}` plus the placeholder the chip fills on every read
+(`?p=` + 32 zeros for 424 SUN, `?m=00000000000000x000000` for the 21x UID and counter mirror). The
+offsets are byte positions in the NDEF data, assuming the `https://` URI prefix code and a short record.
+
+## Notes
+
+- Range responses are never cached by the SDK: tags change as they're programmed and several carry keys.
+- A tag bound to a proof (minted or claimed) is never moved or cleared by `assign`; it's reported in `skipped`.
+- `status` is the stage (`minted`, `sent`, `received`), or `assigned` once every tag is assigned.

package/dist/docs/theme-tokens.md

@@ -99,6 +99,14 @@ renders correctly even against a host that sets none of them.
 
 Dark mode is a *theme* (a different value-set), not a separate token set — the host swaps the values.
 
+- **Host:** in dark mode, send a dark value-set — in the iframe address (`#slt=` with `theme: "dark"`, and the
+  legacy `theme=` payload with `m: "d"`) or on the mount root. Sending only the hook (`dark=1`, `.dark`)
+  leaves the app to guess.
+- **App:** `theme.css` has dark fallbacks under `.dark` / `[data-theme="dark"]`, so an app built on it stays
+  readable even when a host sends the hook and no values. An app with its own CSS variables should do the
+  same: a light fallback at the root, a dark one under the hook — never a light colour that also stands
+  in for dark.
+
 ---
 
 ## 3. Theme value-sets (what the AI emits, what the lookbook stores)

package/dist/http.js

@@ -219,6 +219,9 @@ function shouldSkipCache(path) {
     // Bookings change by the second (places left, busy times, a booking's status) — never serve them stale.
     if (/\/app\/[^/]+\/bookings(\/|\?|$)/i.test(path))
         return true;
+    // Tag ranges change as tags are programmed, and carry the tags' keys — never cached, never persisted.
+    if (/\/claimSet\/[^/]+\/ranges(\/|\?|$)/i.test(path))
+        return true;
     return false;
 }
 /** Evict the oldest (LRU) entry when the cache is at capacity. */

package/dist/idbConnection.d.ts

@@ -0,0 +1,14 @@
+export interface IdbConnection {
+    /** The open connection, opening one if needed. */
+    open(): Promise<IDBDatabase>;
+    /** Forget the current connection so the next call re-opens. */
+    drop(closed?: IDBDatabase): void;
+    /**
+     * Run one transaction against the object store. If the connection is
+     * closed, re-open it and try once more. Errors from `body` are not retried.
+     */
+    run<T>(mode: IDBTransactionMode, body: (store: IDBObjectStore, tx: IDBTransaction) => T | Promise<T>): Promise<T>;
+}
+/** True for the error a transaction throws on a connection the browser closed. */
+export declare function isClosedConnectionError(error: unknown): boolean;
+export declare function createIdbConnection(dbName: string, storeName: string, version?: number): IdbConnection;

package/dist/idbConnection.js

@@ -0,0 +1,91 @@
+// src/idbConnection.ts
+// Shared IndexedDB connection handling for the SDK's caches.
+//
+// The browser may close an IndexedDB connection behind our back: iOS Safari
+// does it when the tab goes to the background, and any browser does it on
+// storage eviction or a version change. A transaction on a closed connection
+// throws "The database connection is closing", so a cache that keeps one
+// connection for the life of the page silently stops working after that.
+//
+// createIdbConnection() forgets a connection the browser closes and re-opens
+// on the next call; run() retries a transaction once when the connection
+// turns out to be closed.
+/** True for the error a transaction throws on a connection the browser closed. */
+export function isClosedConnectionError(error) {
+    const e = error;
+    if (!e)
+        return false;
+    if (e.name === 'InvalidStateError')
+        return true;
+    const msg = String(e.message || '');
+    return /connection is closing|database connection|closed/i.test(msg);
+}
+export function createIdbConnection(dbName, storeName, version = 1) {
+    let db = null;
+    let opening = null;
+    const drop = (closed) => {
+        // A newer connection may already have replaced the one that closed.
+        if (closed && db && db !== closed)
+            return;
+        db = null;
+        opening = null;
+    };
+    const open = () => {
+        if (db)
+            return Promise.resolve(db);
+        if (opening)
+            return opening;
+        opening = new Promise((resolve, reject) => {
+            try {
+                const req = indexedDB.open(dbName, version);
+                req.onupgradeneeded = (event) => {
+                    const upgrading = event.target.result;
+                    if (!upgrading.objectStoreNames.contains(storeName)) {
+                        upgrading.createObjectStore(storeName);
+                    }
+                };
+                req.onsuccess = () => {
+                    const opened = req.result;
+                    opened.onclose = () => drop(opened);
+                    opened.onversionchange = () => {
+                        opened.close();
+                        drop(opened);
+                    };
+                    db = opened;
+                    resolve(opened);
+                };
+                req.onerror = () => {
+                    opening = null;
+                    reject(req.error);
+                };
+                req.onblocked = () => {
+                    opening = null;
+                    reject(new Error(`[smartlinks] IndexedDB open blocked (${dbName})`));
+                };
+            }
+            catch (err) {
+                opening = null;
+                reject(err);
+            }
+        });
+        return opening;
+    };
+    const run = async (mode, body) => {
+        for (let attempt = 0;; attempt++) {
+            const current = await open();
+            let tx;
+            try {
+                tx = current.transaction(storeName, mode);
+            }
+            catch (err) {
+                if (attempt === 0 && isClosedConnectionError(err)) {
+                    drop(current);
+                    continue;
+                }
+                throw err;
+            }
+            return await body(tx.objectStore(storeName), tx);
+        }
+    };
+    return { open, drop, run };
+}