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

package/dist/api/index.d.ts

@@ -10,6 +10,7 @@ export { auth } from "./auth";
 export { form } from "./form";
 export { authKit } from "./authKit";
 export { claimSet } from "./claimSet";
+export { sequence } from "./sequence";
 export { crate } from "./crate";
 export { batch } from "./batch";
 export { variant } from "./variant";

package/dist/api/index.js

@@ -12,6 +12,7 @@ export { auth } from "./auth";
 export { form } from "./form";
 export { authKit } from "./authKit";
 export { claimSet } from "./claimSet";
+export { sequence } from "./sequence";
 export { crate } from "./crate";
 export { batch } from "./batch";
 export { variant } from "./variant";

package/dist/api/sequence.d.ts

@@ -0,0 +1,35 @@
+export interface AllocateSequenceInput {
+    /** The app that owns the sequence config. */
+    appId: string;
+    /** The configured sequence id — the key of data.sequenceConfigs on the app config. */
+    sequenceId: string;
+    /**
+     * 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;
+}
+export interface AllocatedSequence {
+    /** The allocated (or already-held) number. */
+    number: number;
+    /** True when this call allocated a new number; false when the subject already had one. */
+    isNew: boolean;
+}
+export declare namespace sequence {
+    /**
+     * Allocate (or return the existing) sequence number for a subject. Idempotent — safe to
+     * call on load (auto-enter) and on a button tap; a subject that already has a number gets
+     * it back with `isNew: false`.
+     *
+     * @example
+     *   const { number, isNew } = await sequence.allocate(collectionId, {
+     *     appId: 'raffle-app', sequenceId: 'raffle', subjectId: claimSetId,
+     *   })
+     */
+    function allocate(collectionId: string, input: AllocateSequenceInput): Promise<AllocatedSequence>;
+}

package/dist/api/sequence.js

@@ -0,0 +1,26 @@
+// src/api/sequence.ts
+//
+// Sequences — allocate a guaranteed-unique, monotonic number (raffle tickets, "Nth to
+// claim", queue positions) and stamp it onto a record. The sequence (counter key, target,
+// field, scope) is configured server-side in app config (data.sequenceConfigs[sequenceId]);
+// this call supplies only the subject and is idempotent — a re-tap returns the same number.
+// See docs/sequences.md.
+import { post } from "../http";
+export var sequence;
+(function (sequence) {
+    const base = (collectionId) => `/public/collection/${encodeURIComponent(collectionId)}/sequence`;
+    /**
+     * Allocate (or return the existing) sequence number for a subject. Idempotent — safe to
+     * call on load (auto-enter) and on a button tap; a subject that already has a number gets
+     * it back with `isNew: false`.
+     *
+     * @example
+     *   const { number, isNew } = await sequence.allocate(collectionId, {
+     *     appId: 'raffle-app', sequenceId: 'raffle', subjectId: claimSetId,
+     *   })
+     */
+    async function allocate(collectionId, input) {
+        return post(`${base(collectionId)}/allocate`, input);
+    }
+    sequence.allocate = allocate;
+})(sequence || (sequence = {}));

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.0-alpha.3  |  Generated: 2026-09-14T14:38:59.597Z
+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.
 
@@ -150,6 +150,7 @@ The Smartlinks SDK is organized into the following namespaces:
 - **realtime** - Functions for realtime operations
 - **research** - Functions for research operations
 - **secrets** - Functions for secrets operations
+- **sequence** - Functions for sequence operations
 - **tags** - Functions for tags operations
 - **template** - Functions for template operations
 - **translations** - Functions for translations operations
@@ -158,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.
 
@@ -8535,6 +8542,26 @@ type VerifyTokenResponse = {
 }
 ```
 
+### sequence (api)
+
+**AllocateSequenceInput** (interface)
+```typescript
+interface AllocateSequenceInput {
+  appId: string
+  sequenceId: string
+  subjectId: string
+  productId?: string
+}
+```
+
+**AllocatedSequence** (interface)
+```typescript
+interface AllocatedSequence {
+  number: number
+  isNew: boolean
+}
+```
+
 ### conditions (utils)
 
 **BaseCondition** (interface)
@@ -10791,6 +10818,11 @@ Soft-delete a secret. DELETE /secrets/:ref
     id: string,
     query: { limit?: number; offset?: number } = {}) → `Promise<SegmentRecipientsResponse>`
 
+### sequence
+
+**allocate**(collectionId: string, input: AllocateSequenceInput) → `Promise<AllocatedSequence>`
+Allocate (or return the existing) sequence number for a subject. Idempotent — safe to call on load (auto-enter) and on a button tap; a subject that already has a number gets it back with `isNew: false`. const { number, isNew } = await sequence.allocate(collectionId, { appId: 'raffle-app', sequenceId: 'raffle', subjectId: claimSetId, })
+
 ### sessions
 
 **stats**(collectionId: string) → `Promise<SessionStatistics>`

package/dist/docs/sequences.md

@@ -45,47 +45,75 @@ 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. |
 
-## Worked example — a free raffle on NFC wristbands
+## Configure the sequence (once, server-side)
 
-Everyone taps a wristband and hits **Enter the raffle**. Each tap allocates the next number
-and writes it onto that wristband's claim set — fast, unique, no proof mint:
+You define the sequence **in your app config**, under `data.sequenceConfigs`. This is what
+makes the public endpoint safe: the target/field/scope are set by you, not the caller.
 
 ```jsonc
-// allocate-and-stamp (conceptual shape)
+// app config: data.sequenceConfigs
 {
-  "appId":     "raffle-app",
-  "productId": "wristbands-2026",     // the counter's scope
-  "key":       "raffle:2026-cup",     // the named sequence
-  "start":     1,
-  "subjectId": "<claim set id>",      // STABLE identity — re-taps collapse to one number
-  "target":    "claimSet",
-  "field":     "raffleNumber"
+  "raffle": {
+    "key":     "raffle:2026-cup",   // the named counter (data.sequences.<key>)
+    "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)
+  }
 }
-// → { "number": 42, "isNew": true }   (re-tap → { "number": 42, "isNew": false })
 ```
 
-Drawing the winner needs no separate ledger either — query the claim sets (or proofs) where
-`raffleNumber` is set; that field is your entry list, in allocation order.
+> **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.
 
-## Status
+## Call it (the widget)
 
-The allocator + stamping run server-side today. The **public "enter" action** an app widget
-calls on tap (and its SDK wrapper) is being wired in the 2.0.0-alpha line — this doc is the
-contract it will expose.
+Your widget calls one bounded, public endpoint on tap. It passes only the **subject id** —
+never the target/field:
+
+```
+POST /api/v1/public/collection/:collectionId/sequence/allocate
+{ "appId": "liveWidgets", "sequenceId": "raffle", "subjectId": "23-oOkf8o" }
+→ { "number": 42, "isNew": true }        // re-tap → { "number": 42, "isNew": false }
+```
+
+- **`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."
+- **Refresh:** just read the `raffleNumber` field back off the claim set (or proof) — it's the
+  ledger. Or call allocate again; you'll get the same number with `isNew: false`.
+
+Errors: `404 SEQUENCE_NOT_FOUND` (not configured), `404 CLAIMSET_NOT_FOUND` (bad subject),
+`400 BAD_REQUEST` (missing fields).
+
+## Drawing the winner
+
+No separate ledger — query the claim sets (or proofs) where `raffleNumber` is set; that field
+is your entry list, in allocation order.

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/dist/openapi.yaml

@@ -27897,3 +27897,28 @@ components:
           additionalProperties: true
       required:
         - valid
+    AllocateSequenceInput:
+      type: object
+      properties:
+        appId:
+          type: string
+        sequenceId:
+          type: string
+        subjectId:
+          type: string
+        productId:
+          type: string
+      required:
+        - appId
+        - sequenceId
+        - subjectId
+    AllocatedSequence:
+      type: object
+      properties:
+        number:
+          type: number
+        isNew:
+          type: boolean
+      required:
+        - number
+        - isNew

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.0-alpha.3  |  Generated: 2026-09-14T14:38:59.597Z
+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.
 
@@ -150,6 +150,7 @@ The Smartlinks SDK is organized into the following namespaces:
 - **realtime** - Functions for realtime operations
 - **research** - Functions for research operations
 - **secrets** - Functions for secrets operations
+- **sequence** - Functions for sequence operations
 - **tags** - Functions for tags operations
 - **template** - Functions for template operations
 - **translations** - Functions for translations operations
@@ -158,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.
 
@@ -8535,6 +8542,26 @@ type VerifyTokenResponse = {
 }
 ```
 
+### sequence (api)
+
+**AllocateSequenceInput** (interface)
+```typescript
+interface AllocateSequenceInput {
+  appId: string
+  sequenceId: string
+  subjectId: string
+  productId?: string
+}
+```
+
+**AllocatedSequence** (interface)
+```typescript
+interface AllocatedSequence {
+  number: number
+  isNew: boolean
+}
+```
+
 ### conditions (utils)
 
 **BaseCondition** (interface)
@@ -10791,6 +10818,11 @@ Soft-delete a secret. DELETE /secrets/:ref
     id: string,
     query: { limit?: number; offset?: number } = {}) → `Promise<SegmentRecipientsResponse>`
 
+### sequence
+
+**allocate**(collectionId: string, input: AllocateSequenceInput) → `Promise<AllocatedSequence>`
+Allocate (or return the existing) sequence number for a subject. Idempotent — safe to call on load (auto-enter) and on a button tap; a subject that already has a number gets it back with `isNew: false`. const { number, isNew } = await sequence.allocate(collectionId, { appId: 'raffle-app', sequenceId: 'raffle', subjectId: claimSetId, })
+
 ### sessions
 
 **stats**(collectionId: string) → `Promise<SessionStatistics>`

package/docs/sequences.md

@@ -45,47 +45,75 @@ 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. |
 
-## Worked example — a free raffle on NFC wristbands
+## Configure the sequence (once, server-side)
 
-Everyone taps a wristband and hits **Enter the raffle**. Each tap allocates the next number
-and writes it onto that wristband's claim set — fast, unique, no proof mint:
+You define the sequence **in your app config**, under `data.sequenceConfigs`. This is what
+makes the public endpoint safe: the target/field/scope are set by you, not the caller.
 
 ```jsonc
-// allocate-and-stamp (conceptual shape)
+// app config: data.sequenceConfigs
 {
-  "appId":     "raffle-app",
-  "productId": "wristbands-2026",     // the counter's scope
-  "key":       "raffle:2026-cup",     // the named sequence
-  "start":     1,
-  "subjectId": "<claim set id>",      // STABLE identity — re-taps collapse to one number
-  "target":    "claimSet",
-  "field":     "raffleNumber"
+  "raffle": {
+    "key":     "raffle:2026-cup",   // the named counter (data.sequences.<key>)
+    "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)
+  }
 }
-// → { "number": 42, "isNew": true }   (re-tap → { "number": 42, "isNew": false })
 ```
 
-Drawing the winner needs no separate ledger either — query the claim sets (or proofs) where
-`raffleNumber` is set; that field is your entry list, in allocation order.
+> **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.
 
-## Status
+## Call it (the widget)
 
-The allocator + stamping run server-side today. The **public "enter" action** an app widget
-calls on tap (and its SDK wrapper) is being wired in the 2.0.0-alpha line — this doc is the
-contract it will expose.
+Your widget calls one bounded, public endpoint on tap. It passes only the **subject id** —
+never the target/field:
+
+```
+POST /api/v1/public/collection/:collectionId/sequence/allocate
+{ "appId": "liveWidgets", "sequenceId": "raffle", "subjectId": "23-oOkf8o" }
+→ { "number": 42, "isNew": true }        // re-tap → { "number": 42, "isNew": false }
+```
+
+- **`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."
+- **Refresh:** just read the `raffleNumber` field back off the claim set (or proof) — it's the
+  ledger. Or call allocate again; you'll get the same number with `isNew: false`.
+
+Errors: `404 SEQUENCE_NOT_FOUND` (not configured), `404 CLAIMSET_NOT_FOUND` (bad subject),
+`400 BAD_REQUEST` (missing fields).
+
+## Drawing the winner
+
+No separate ledger — query the claim sets (or proofs) where `raffleNumber` is set; that field
+is your entry list, in allocation order.

package/openapi.yaml

@@ -27897,3 +27897,28 @@ components:
           additionalProperties: true
       required:
         - valid
+    AllocateSequenceInput:
+      type: object
+      properties:
+        appId:
+          type: string
+        sequenceId:
+          type: string
+        subjectId:
+          type: string
+        productId:
+          type: string
+      required:
+        - appId
+        - sequenceId
+        - subjectId
+    AllocatedSequence:
+      type: object
+      properties:
+        number:
+          type: number
+        isNew:
+          type: boolean
+      required:
+        - number
+        - isNew

package/package.json

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