@proveanything/smartlinks 2.0.0-alpha.4 → 2.0.0-alpha.5

package/dist/api/sequence.d.ts

@@ -3,7 +3,13 @@ export interface AllocateSequenceInput {
     appId: string;
     /** The configured sequence id — the key of data.sequenceConfigs on the app config. */
     sequenceId: string;
-    /** The STABLE subject identity — the claim-set id from the tap (NOT a per-tap virtual id). */
+    /**
+     * The STABLE subject identity. For a `claimSet` sequence, pass the tap's virtual-proof id
+     * `<claimSetId>-<code>` (e.g. "23-oOkf8o") for a per-wristband raffle — the code is the tag's
+     * permanent id, so re-taps of the same wristband return the same number; the number is stamped
+     * on that code's doc and surfaces in `tagData`. Pass a bare claim-set id for one number per
+     * group. Never a value that changes per tap.
+     */
     subjectId: string;
     /** Optional product scope, when the sequence config is scoped per product. */
     productId?: string;

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.0-alpha.4  |  Generated: 2026-09-14T15:08:56.614Z
+Version: 2.0.0-alpha.5  |  Generated: 2026-09-14T19:49:23.024Z
 
 This is a concise summary of all available API functions and types.
 
@@ -159,6 +159,12 @@ The Smartlinks SDK is organized into the following namespaces:
 
 Core HTTP functions for API configuration and communication:
 
+**getHttpCacheDiagnostics**() → `void`
+Snapshot of cache counters + current keys. Call from the console via `window.__slHttpDiag()`.
+
+**resetHttpCacheDiagnostics**() → `void`
+Reset the diagnostics counters (does not touch the cache itself).
+
 **isProxyEnabled**() → `boolean`
 Return whether proxy mode is currently enabled.
 

package/dist/docs/sequences.md

@@ -45,22 +45,27 @@ subject first and return the number it already has, rather than allocating a sec
 ## Idempotency subject — use a *stable* id
 
 The number is deduped by the **subject id** you pass, so it must be the **stable** identity:
-- **Claim set id** (the wristband's permanent record) — the right key when people aren't
-  logged in. A re-tap resolves to the same claim set → same number.
+- **Virtual-proof id `<claimSetId>-<code>`** (e.g. `23-oOkf8o`) — the right key for a
+  per-wristband raffle. The `code` is the physical tag's permanent id, so a re-tap of the same
+  wristband resolves to the same code doc → same number. The virtual proof record is transient,
+  but the **code** inside its id is stable — that's what the sink keys on (it splits the id and
+  uses only `<claimSetId>` + `<code>`).
+- **Bare claim-set id** — when one number per *group* is intended.
 - The authenticated **user/contact** — if they sign in / claim.
 
-Do **not** key on a value that changes per interaction (e.g. a virtual proof id minted fresh
-on each tap) — that would let one person take several numbers.
+Do **not** key on the transient part of a per-tap identity (a freshly-minted virtual proof
+record) — key on the stable **code**, which is exactly what the `<claimSetId>-<code>` subject
+carries.
 
 ## Where the number is stored (the sink)
 
 The stamp target is configurable — the number lives wherever you'll read it:
 
-| Target | Use |
-|---|---|
-| `claimSet` | The Firestore wristband record — fast, no proof mint on the hot path. |
-| `proof` | A minted proof (value or attestation) — when the number should travel with the proof. |
-| `appRecord` | A structured app record — for queryable, per-app data. |
+| Target | Subject id | Use |
+|---|---|---|
+| `claimSet` | the virtual-proof id `<claimSetId>-<code>` (e.g. `23-oOkf8o`) **or** a bare `<claimSetId>` | The Firestore claim-set world. **The subject decides the exact doc:** a `<claimSetId>-<code>` id stamps the individual **code** doc (per-wristband — rides back as `tagData` on the next tap, every wristband its own number); a bare id stamps the whole **set** doc (one shared value). Claim-set ids are hyphen-free, so a hyphen unambiguously means the per-code form. |
+| `proof` | the proof id | A minted proof (value or attestation) — when the number should travel with the proof. |
+| `appRecord` | the record id | A structured app record — for queryable, per-app data. |
 
 ## Configure the sequence (once, server-side)
 
@@ -72,14 +77,19 @@ makes the public endpoint safe: the target/field/scope are set by you, not the c
 {
   "raffle": {
     "key":     "raffle:2026-cup",   // the named counter (data.sequences.<key>)
-    "target":  "claimSet",          // claimSet | proof | appRecord — where the number is stamped
-    "field":   "raffleNumber",      // the property written on the target
-    "productId": "wristbands-2026", // counter scope (optional; else collection-wide)
+    "target":  "claimSet",          // claimSet | proof | appRecord — the ledger domain
+    "field":   "raffleNumber",      // the property written on the target (comes back in tagData)
     "start":   1                    // first number (optional, default 1)
+    // no productId → one collection-wide counter (all wristbands share the sequence)
   }
 }
 ```
 
+> **Per-wristband raffle.** Keep `target: "claimSet"` and pass the tap's virtual-proof id
+> (`<claimSetId>-<code>`) as the subject — the sink writes the individual tag's **code** doc, so
+> each wristband gets its own number and it surfaces in `tagData` on the next tap. Pass a bare
+> claim-set id instead only if you want one number for the whole group.
+
 ## Call it (the widget)
 
 Your widget calls one bounded, public endpoint on tap. It passes only the **subject id** —
@@ -87,12 +97,13 @@ never the target/field:
 
 ```
 POST /api/v1/public/collection/:collectionId/sequence/allocate
-{ "appId": "raffle-app", "sequenceId": "raffle", "subjectId": "<claim set id>" }
+{ "appId": "liveWidgets", "sequenceId": "raffle", "subjectId": "23-oOkf8o" }
 → { "number": 42, "isNew": true }        // re-tap → { "number": 42, "isNew": false }
 ```
 
-- **`subjectId`** is the STABLE identity — the claim-set id from the tap. Re-taps collapse to
-  one number.
+- **`subjectId`** is the STABLE identity. For `claimCode` it's the virtual-proof id
+  `<claimSetId>-<code>` (e.g. `23-oOkf8o`) straight off the tap — re-taps of the same wristband
+  collapse to one number. (For `claimSet` it's the claim-set id.)
 - **Idempotent**, so both your flows are the *same call*:
   - **Auto:** on load, call allocate → get your number (existing or freshly minted).
   - **Button:** click → animate → same call → "Your raffle number is 42."

package/dist/http.d.ts

@@ -1,3 +1,23 @@
+/** Snapshot of cache counters + current keys. Call from the console via `window.__slHttpDiag()`. */
+export declare function getHttpCacheDiagnostics(): {
+    size: number;
+    keys: string[];
+    inflight: string[];
+    cacheEnabled: boolean;
+    cacheDefaultTtlMs: number;
+    cachePersistence: "none" | "indexeddb";
+    cacheClearOnPageLoad: boolean;
+    l1Hits: number;
+    inflightDedups: number;
+    l2Hits: number;
+    networkFetches: number;
+    skips: number;
+    clears: number;
+    lastClearReason: string | null;
+    lastClearAt: number;
+};
+/** Reset the diagnostics counters (does not touch the cache itself). */
+export declare function resetHttpCacheDiagnostics(): void;
 type Logger = {
     debug?: (...args: any[]) => void;
     info?: (...args: any[]) => void;

package/dist/http.js

@@ -79,6 +79,68 @@ const TOKEN_STORAGE_KEY = 'sl:token';
 let cachePersistenceTtlMs = 7 * 24 * 60 * 60000;
 /** When true (default), serve stale L2 data via SmartlinksOfflineError on network failure. */
 let cacheServeStaleOnOffline = true;
+const httpCacheStats = {
+    l1Hits: 0, inflightDedups: 0, l2Hits: 0, networkFetches: 0, skips: 0,
+    clears: 0, lastClearReason: null, lastClearAt: 0,
+};
+function httpDebugEnabled() {
+    var _a;
+    try {
+        if (typeof window !== 'undefined') {
+            if (window.__SL_HTTP_DEBUG__)
+                return true;
+            // URL opt-in so boot-time GETs can be traced on a deployed app without any
+            // code change: just append ?__slhttpdebug=1 (or &…) to the page URL and reload.
+            if (/[?&]__slhttpdebug=1\b/.test(((_a = window.location) === null || _a === void 0 ? void 0 : _a.search) || ''))
+                return true;
+        }
+    }
+    catch (_b) { }
+    return !!logger;
+}
+function httpDebug(...args) {
+    if (!httpDebugEnabled())
+        return;
+    try {
+        (console.info || console.log).call(console, '[sl-http]', ...args);
+    }
+    catch (_a) { }
+}
+/**
+ * Single choke-point for wiping the in-memory GET cache. Routing every clear
+ * through here means each one is counted and logged with a reason — so a test
+ * run shows exactly which cache clears fired and why (e.g. token change on a
+ * public page that should never have cleared).
+ */
+function clearHttpCache(reason) {
+    httpCacheStats.clears++;
+    httpCacheStats.lastClearReason = reason;
+    httpCacheStats.lastClearAt = Date.now();
+    httpDebug('cache CLEAR', { reason, hadEntries: httpCache.size });
+    httpCache.clear();
+}
+/** Snapshot of cache counters + current keys. Call from the console via `window.__slHttpDiag()`. */
+export function getHttpCacheDiagnostics() {
+    const keys = [...httpCache.keys()];
+    return Object.assign(Object.assign({}, httpCacheStats), { size: httpCache.size, keys, inflight: [...httpCache.entries()].filter(([, v]) => v.promise).map(([k]) => k), cacheEnabled, cacheDefaultTtlMs, cachePersistence, cacheClearOnPageLoad });
+}
+/** Reset the diagnostics counters (does not touch the cache itself). */
+export function resetHttpCacheDiagnostics() {
+    httpCacheStats.l1Hits = 0;
+    httpCacheStats.inflightDedups = 0;
+    httpCacheStats.l2Hits = 0;
+    httpCacheStats.networkFetches = 0;
+    httpCacheStats.skips = 0;
+    httpCacheStats.clears = 0;
+    httpCacheStats.lastClearReason = null;
+    httpCacheStats.lastClearAt = 0;
+}
+// Expose on window for zero-wiring console access after a build.
+try {
+    if (typeof window !== 'undefined')
+        window.__slHttpDiag = getHttpCacheDiagnostics;
+}
+catch (_a) { }
 /**
  * Per-resource TTL overrides — checked in order, first match wins.
  *
@@ -143,7 +205,7 @@ function evictLruIfNeeded() {
 function clearSessionCachesOnPageLoad() {
     if (typeof window === 'undefined')
         return; // Node.js environment
-    httpCache.clear();
+    clearHttpCache('pageLoad session reset');
     try {
         if (typeof sessionStorage !== 'undefined') {
             const sessionKeys = Object.keys(sessionStorage).filter(k => k.startsWith('smartlinks:cache:'));
@@ -421,7 +483,7 @@ export function initializeApi(options) {
     // Clear both cache tiers on forced re-initialization so stale data
     // from the previous configuration cannot bleed through.
     if (options.force) {
-        httpCache.clear();
+        clearHttpCache('initializeApi(force)');
         idbClear().catch(() => { });
     }
     logger = options.logger;
@@ -468,7 +530,7 @@ export function setBearerToken(token) {
             catch (_b) { }
         }
     }
-    httpCache.clear();
+    clearHttpCache(`setBearerToken(${token ? 'set' : 'cleared'})`);
     if (cachePersistence !== 'none')
         idbClear().catch(() => { });
 }
@@ -492,7 +554,7 @@ export function setGrantToken(token) {
     if (token === grantToken)
         return;
     grantToken = token;
-    httpCache.clear();
+    clearHttpCache(`setGrantToken(${token ? 'set' : 'cleared'})`);
     if (cachePersistence !== 'none')
         idbClear().catch(() => { });
 }
@@ -612,7 +674,7 @@ export function configureSdkCache(options) {
  */
 export function invalidateCache(urlPattern) {
     if (!urlPattern) {
-        httpCache.clear();
+        clearHttpCache('invalidateCache(all)');
         if (cachePersistence !== 'none')
             idbClear().catch(() => { });
         return;
@@ -1094,19 +1156,28 @@ export async function request(path) {
     const skipCache = shouldSkipCache(path);
     const cacheKey = buildCacheKey(path);
     const ttl = skipCache ? 0 : getTtlForPath(path);
+    if (skipCache) {
+        httpCacheStats.skips++;
+        httpDebug('GET skip-cache', { path });
+    }
     if (!skipCache) {
         // 1. L1 hit — return from memory immediately
         const l1 = getHttpCacheHit(cacheKey, ttl);
         if (l1 !== null) {
+            httpCacheStats.l1Hits++;
+            httpDebug('GET L1 hit', { path, ttlMs: ttl });
             logDebug('[smartlinks] GET cache hit (L1)', { path });
             return l1;
         }
         // 2. In-flight deduplication — share an already-pending promise
         const inflight = httpCache.get(cacheKey);
         if (inflight === null || inflight === void 0 ? void 0 : inflight.promise) {
+            httpCacheStats.inflightDedups++;
+            httpDebug('GET in-flight dedup', { path });
             logDebug('[smartlinks] GET in-flight dedup', { path });
             return inflight.promise;
         }
+        httpDebug('GET MISS → will fetch', { path, ttlMs: ttl, cacheKey });
     }
     // 3. Build the fetch promise.
     //    The IIFE starts synchronously until its first `await`, then the outer
@@ -1117,6 +1188,8 @@ export async function request(path) {
         if (!skipCache && cachePersistence !== 'none') {
             const l2 = await idbGet(cacheKey);
             if (l2 && Date.now() - l2.timestamp <= ttl) {
+                httpCacheStats.l2Hits++;
+                httpDebug('GET L2 hit', { path });
                 logDebug('[smartlinks] GET cache hit (L2)', { path });
                 setHttpCacheEntry(cacheKey, l2.data);
                 return l2.data;
@@ -1124,6 +1197,8 @@ export async function request(path) {
         }
         // 3b. Network fetch
         try {
+            httpCacheStats.networkFetches++;
+            httpDebug('GET NETWORK fetch', { path, skipCache, ttlMs: ttl });
             let data;
             if (proxyMode) {
                 logDebug('[smartlinks] GET via proxy', { path });

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { initializeApi, isInitialized, hasAuthCredentials, configureSdkCache, invalidateCache, request, post, put, patch, del, sendCustomProxyMessage, getApiHeaders, isProxyEnabled, setBearerToken, getBearerToken, setGrantToken, getGrantToken } from "./http";
+export { initializeApi, isInitialized, hasAuthCredentials, configureSdkCache, invalidateCache, getHttpCacheDiagnostics, resetHttpCacheDiagnostics, request, post, put, patch, del, sendCustomProxyMessage, getApiHeaders, isProxyEnabled, setBearerToken, getBearerToken, setGrantToken, getGrantToken } from "./http";
 export * from "./api";
 export * from "./types";
 export { iframe } from "./iframe";

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/index.ts
 // Top-level entrypoint of the npm package. Re-export initializeApi + all namespaces.
-export { initializeApi, isInitialized, hasAuthCredentials, configureSdkCache, invalidateCache, request, post, put, patch, del, sendCustomProxyMessage, getApiHeaders, isProxyEnabled, setBearerToken, getBearerToken, setGrantToken, getGrantToken } from "./http";
+export { initializeApi, isInitialized, hasAuthCredentials, configureSdkCache, invalidateCache, getHttpCacheDiagnostics, resetHttpCacheDiagnostics, request, post, put, patch, del, sendCustomProxyMessage, getApiHeaders, isProxyEnabled, setBearerToken, getBearerToken, setGrantToken, getGrantToken } from "./http";
 export * from "./api";
 export * from "./types";
 // Iframe namespace

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.0-alpha.4  |  Generated: 2026-09-14T15:08:56.614Z
+Version: 2.0.0-alpha.5  |  Generated: 2026-09-14T19:49:23.024Z
 
 This is a concise summary of all available API functions and types.
 
@@ -159,6 +159,12 @@ The Smartlinks SDK is organized into the following namespaces:
 
 Core HTTP functions for API configuration and communication:
 
+**getHttpCacheDiagnostics**() → `void`
+Snapshot of cache counters + current keys. Call from the console via `window.__slHttpDiag()`.
+
+**resetHttpCacheDiagnostics**() → `void`
+Reset the diagnostics counters (does not touch the cache itself).
+
 **isProxyEnabled**() → `boolean`
 Return whether proxy mode is currently enabled.
 

package/docs/sequences.md

@@ -45,22 +45,27 @@ subject first and return the number it already has, rather than allocating a sec
 ## Idempotency subject — use a *stable* id
 
 The number is deduped by the **subject id** you pass, so it must be the **stable** identity:
-- **Claim set id** (the wristband's permanent record) — the right key when people aren't
-  logged in. A re-tap resolves to the same claim set → same number.
+- **Virtual-proof id `<claimSetId>-<code>`** (e.g. `23-oOkf8o`) — the right key for a
+  per-wristband raffle. The `code` is the physical tag's permanent id, so a re-tap of the same
+  wristband resolves to the same code doc → same number. The virtual proof record is transient,
+  but the **code** inside its id is stable — that's what the sink keys on (it splits the id and
+  uses only `<claimSetId>` + `<code>`).
+- **Bare claim-set id** — when one number per *group* is intended.
 - The authenticated **user/contact** — if they sign in / claim.
 
-Do **not** key on a value that changes per interaction (e.g. a virtual proof id minted fresh
-on each tap) — that would let one person take several numbers.
+Do **not** key on the transient part of a per-tap identity (a freshly-minted virtual proof
+record) — key on the stable **code**, which is exactly what the `<claimSetId>-<code>` subject
+carries.
 
 ## Where the number is stored (the sink)
 
 The stamp target is configurable — the number lives wherever you'll read it:
 
-| Target | Use |
-|---|---|
-| `claimSet` | The Firestore wristband record — fast, no proof mint on the hot path. |
-| `proof` | A minted proof (value or attestation) — when the number should travel with the proof. |
-| `appRecord` | A structured app record — for queryable, per-app data. |
+| Target | Subject id | Use |
+|---|---|---|
+| `claimSet` | the virtual-proof id `<claimSetId>-<code>` (e.g. `23-oOkf8o`) **or** a bare `<claimSetId>` | The Firestore claim-set world. **The subject decides the exact doc:** a `<claimSetId>-<code>` id stamps the individual **code** doc (per-wristband — rides back as `tagData` on the next tap, every wristband its own number); a bare id stamps the whole **set** doc (one shared value). Claim-set ids are hyphen-free, so a hyphen unambiguously means the per-code form. |
+| `proof` | the proof id | A minted proof (value or attestation) — when the number should travel with the proof. |
+| `appRecord` | the record id | A structured app record — for queryable, per-app data. |
 
 ## Configure the sequence (once, server-side)
 
@@ -72,14 +77,19 @@ makes the public endpoint safe: the target/field/scope are set by you, not the c
 {
   "raffle": {
     "key":     "raffle:2026-cup",   // the named counter (data.sequences.<key>)
-    "target":  "claimSet",          // claimSet | proof | appRecord — where the number is stamped
-    "field":   "raffleNumber",      // the property written on the target
-    "productId": "wristbands-2026", // counter scope (optional; else collection-wide)
+    "target":  "claimSet",          // claimSet | proof | appRecord — the ledger domain
+    "field":   "raffleNumber",      // the property written on the target (comes back in tagData)
     "start":   1                    // first number (optional, default 1)
+    // no productId → one collection-wide counter (all wristbands share the sequence)
   }
 }
 ```
 
+> **Per-wristband raffle.** Keep `target: "claimSet"` and pass the tap's virtual-proof id
+> (`<claimSetId>-<code>`) as the subject — the sink writes the individual tag's **code** doc, so
+> each wristband gets its own number and it surfaces in `tagData` on the next tap. Pass a bare
+> claim-set id instead only if you want one number for the whole group.
+
 ## Call it (the widget)
 
 Your widget calls one bounded, public endpoint on tap. It passes only the **subject id** —
@@ -87,12 +97,13 @@ never the target/field:
 
 ```
 POST /api/v1/public/collection/:collectionId/sequence/allocate
-{ "appId": "raffle-app", "sequenceId": "raffle", "subjectId": "<claim set id>" }
+{ "appId": "liveWidgets", "sequenceId": "raffle", "subjectId": "23-oOkf8o" }
 → { "number": 42, "isNew": true }        // re-tap → { "number": 42, "isNew": false }
 ```
 
-- **`subjectId`** is the STABLE identity — the claim-set id from the tap. Re-taps collapse to
-  one number.
+- **`subjectId`** is the STABLE identity. For `claimCode` it's the virtual-proof id
+  `<claimSetId>-<code>` (e.g. `23-oOkf8o`) straight off the tap — re-taps of the same wristband
+  collapse to one number. (For `claimSet` it's the claim-set id.)
 - **Idempotent**, so both your flows are the *same call*:
   - **Auto:** on load, call allocate → get your number (existing or freshly minted).
   - **Button:** click → animate → same call → "Your raffle number is 42."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "2.0.0-alpha.4",
+  "version": "2.0.0-alpha.5",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",