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

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,29 @@
+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 — the claim-set id from the tap (NOT a per-tap virtual id). */
+    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.4  |  Generated: 2026-09-14T15:08:56.614Z
 
 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
@@ -8535,6 +8536,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 +10812,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

@@ -62,30 +62,47 @@ The stamp target is configurable — the number lives wherever you'll read it:
 | `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. |
 
-## 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 — where the number is stamped
+    "field":   "raffleNumber",      // the property written on the target
+    "productId": "wristbands-2026", // counter scope (optional; else collection-wide)
+    "start":   1                    // first number (optional, default 1)
+  }
 }
-// → { "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.
+## Call it (the widget)
 
-## Status
+Your widget calls one bounded, public endpoint on tap. It passes only the **subject id** —
+never the target/field:
 
-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.
+```
+POST /api/v1/public/collection/:collectionId/sequence/allocate
+{ "appId": "raffle-app", "sequenceId": "raffle", "subjectId": "<claim set id>" }
+→ { "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.
+- **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/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.4  |  Generated: 2026-09-14T15:08:56.614Z
 
 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
@@ -8535,6 +8536,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 +10812,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

@@ -62,30 +62,47 @@ The stamp target is configurable — the number lives wherever you'll read it:
 | `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. |
 
-## 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 — where the number is stamped
+    "field":   "raffleNumber",      // the property written on the target
+    "productId": "wristbands-2026", // counter scope (optional; else collection-wide)
+    "start":   1                    // first number (optional, default 1)
+  }
 }
-// → { "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.
+## Call it (the widget)
 
-## Status
+Your widget calls one bounded, public endpoint on tap. It passes only the **subject id** —
+never the target/field:
 
-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.
+```
+POST /api/v1/public/collection/:collectionId/sequence/allocate
+{ "appId": "raffle-app", "sequenceId": "raffle", "subjectId": "<claim set id>" }
+→ { "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.
+- **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.4",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",