@proveanything/smartlinks 2.0.54 → 2.0.55

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -10,7 +10,6 @@ export { auth } from "./auth.js";
10
10
  export { form } from "./form.js";
11
11
  export { authKit } from "./authKit.js";
12
12
  export { claimSet } from "./claimSet.js";
13
- export { sequence } from "./sequence.js";
14
13
  export { crate } from "./crate.js";
15
14
  export { batch } from "./batch.js";
16
15
  export { variant } from "./variant.js";
package/dist/api/index.js CHANGED
@@ -12,7 +12,6 @@ export { auth } from "./auth.js";
12
12
  export { form } from "./form.js";
13
13
  export { authKit } from "./authKit.js";
14
14
  export { claimSet } from "./claimSet.js";
15
- export { sequence } from "./sequence.js";
16
15
  export { crate } from "./crate.js";
17
16
  export { batch } from "./batch.js";
18
17
  export { variant } from "./variant.js";
@@ -1,6 +1,6 @@
1
1
  # Smartlinks API Summary
2
2
 
3
- Version: 2.0.54 | Generated: 2026-10-12T17:51:26.609Z
3
+ Version: 2.0.55 | Generated: 2026-10-12T20:04:55.294Z
4
4
 
5
5
  This is a concise summary of all available API functions and types.
6
6
 
@@ -154,7 +154,6 @@ The Smartlinks SDK is organized into the following namespaces:
154
154
  - **realtime** - Functions for realtime operations
155
155
  - **research** - Functions for research operations
156
156
  - **secrets** - Functions for secrets operations
157
- - **sequence** - Functions for sequence operations
158
157
  - **tags** - Functions for tags operations
159
158
  - **template** - Functions for template operations
160
159
  - **translations** - Functions for translations operations
@@ -9869,26 +9868,6 @@ interface AppSecretOptions {
9869
9868
  }
9870
9869
  ```
9871
9870
 
9872
- ### sequence (api)
9873
-
9874
- **AllocateSequenceInput** (interface)
9875
- ```typescript
9876
- interface AllocateSequenceInput {
9877
- appId: string
9878
- sequenceId: string
9879
- subjectId: string
9880
- productId?: string
9881
- }
9882
- ```
9883
-
9884
- **AllocatedSequence** (interface)
9885
- ```typescript
9886
- interface AllocatedSequence {
9887
- number: number
9888
- isNew: boolean
9889
- }
9890
- ```
9891
-
9892
9871
  ### conditions (utils)
9893
9872
 
9894
9873
  **BaseCondition** (interface)
@@ -12251,11 +12230,6 @@ Soft-delete a secret. DELETE /secrets/:ref
12251
12230
  id: string,
12252
12231
  query: { limit?: number; offset?: number } = {}) → `Promise<SegmentRecipientsResponse>`
12253
12232
 
12254
- ### sequence
12255
-
12256
- **allocate**(collectionId: string, input: AllocateSequenceInput) → `Promise<AllocatedSequence>`
12257
- 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, }) `ctx.sl.counters.next()` + `ctx.sl.appRecords.claim()` (docs/server-functions.md).
12258
-
12259
12233
  ### sessions
12260
12234
 
12261
12235
  **stats**(collectionId: string) → `Promise<SessionStatistics>`
@@ -93,7 +93,6 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
93
93
  | **Container Tracking** | `docs/container-tracking.md` | Physical/logical **item** container groupings — *not* app containers (see containers.md) |
94
94
  | **Lots** | `docs/lots.md` | Cross-SKU production "Lot" entity |
95
95
  | **Loyalty** | `docs/loyalty.md` | Points, members, earning rules |
96
- | **Sequences** | `docs/sequences.md` | RETIRING — number things in your own server function: `ctx.sl.counters` + `appRecords.claim` (server-functions.md) |
97
96
  | **Integrations** | `docs/integrations.md` | Inbound/outbound external-system integration flows |
98
97
  | **Item Context** | `docs/item-context.md` | The `itemContext` container prop (serial / NFC authenticity context) |
99
98
  | **Native Facade** | `docs/native-facade.md` | `host.native` / `SL.native` device-capability facade |
package/dist/openapi.yaml CHANGED
@@ -30958,28 +30958,3 @@ components:
30958
30958
  properties:
30959
30959
  appId:
30960
30960
  type: string
30961
- AllocateSequenceInput:
30962
- type: object
30963
- properties:
30964
- appId:
30965
- type: string
30966
- sequenceId:
30967
- type: string
30968
- subjectId:
30969
- type: string
30970
- productId:
30971
- type: string
30972
- required:
30973
- - appId
30974
- - sequenceId
30975
- - subjectId
30976
- AllocatedSequence:
30977
- type: object
30978
- properties:
30979
- number:
30980
- type: number
30981
- isNew:
30982
- type: boolean
30983
- required:
30984
- - number
30985
- - isNew
@@ -1,6 +1,6 @@
1
1
  # Smartlinks API Summary
2
2
 
3
- Version: 2.0.54 | Generated: 2026-10-12T17:51:26.609Z
3
+ Version: 2.0.55 | Generated: 2026-10-12T20:04:55.294Z
4
4
 
5
5
  This is a concise summary of all available API functions and types.
6
6
 
@@ -154,7 +154,6 @@ The Smartlinks SDK is organized into the following namespaces:
154
154
  - **realtime** - Functions for realtime operations
155
155
  - **research** - Functions for research operations
156
156
  - **secrets** - Functions for secrets operations
157
- - **sequence** - Functions for sequence operations
158
157
  - **tags** - Functions for tags operations
159
158
  - **template** - Functions for template operations
160
159
  - **translations** - Functions for translations operations
@@ -9869,26 +9868,6 @@ interface AppSecretOptions {
9869
9868
  }
9870
9869
  ```
9871
9870
 
9872
- ### sequence (api)
9873
-
9874
- **AllocateSequenceInput** (interface)
9875
- ```typescript
9876
- interface AllocateSequenceInput {
9877
- appId: string
9878
- sequenceId: string
9879
- subjectId: string
9880
- productId?: string
9881
- }
9882
- ```
9883
-
9884
- **AllocatedSequence** (interface)
9885
- ```typescript
9886
- interface AllocatedSequence {
9887
- number: number
9888
- isNew: boolean
9889
- }
9890
- ```
9891
-
9892
9871
  ### conditions (utils)
9893
9872
 
9894
9873
  **BaseCondition** (interface)
@@ -12251,11 +12230,6 @@ Soft-delete a secret. DELETE /secrets/:ref
12251
12230
  id: string,
12252
12231
  query: { limit?: number; offset?: number } = {}) → `Promise<SegmentRecipientsResponse>`
12253
12232
 
12254
- ### sequence
12255
-
12256
- **allocate**(collectionId: string, input: AllocateSequenceInput) → `Promise<AllocatedSequence>`
12257
- 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, }) `ctx.sl.counters.next()` + `ctx.sl.appRecords.claim()` (docs/server-functions.md).
12258
-
12259
12233
  ### sessions
12260
12234
 
12261
12235
  **stats**(collectionId: string) → `Promise<SessionStatistics>`
package/docs/overview.md CHANGED
@@ -93,7 +93,6 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
93
93
  | **Container Tracking** | `docs/container-tracking.md` | Physical/logical **item** container groupings — *not* app containers (see containers.md) |
94
94
  | **Lots** | `docs/lots.md` | Cross-SKU production "Lot" entity |
95
95
  | **Loyalty** | `docs/loyalty.md` | Points, members, earning rules |
96
- | **Sequences** | `docs/sequences.md` | RETIRING — number things in your own server function: `ctx.sl.counters` + `appRecords.claim` (server-functions.md) |
97
96
  | **Integrations** | `docs/integrations.md` | Inbound/outbound external-system integration flows |
98
97
  | **Item Context** | `docs/item-context.md` | The `itemContext` container prop (serial / NFC authenticity context) |
99
98
  | **Native Facade** | `docs/native-facade.md` | `host.native` / `SL.native` device-capability facade |
package/openapi.yaml CHANGED
@@ -30958,28 +30958,3 @@ components:
30958
30958
  properties:
30959
30959
  appId:
30960
30960
  type: string
30961
- AllocateSequenceInput:
30962
- type: object
30963
- properties:
30964
- appId:
30965
- type: string
30966
- sequenceId:
30967
- type: string
30968
- subjectId:
30969
- type: string
30970
- productId:
30971
- type: string
30972
- required:
30973
- - appId
30974
- - sequenceId
30975
- - subjectId
30976
- AllocatedSequence:
30977
- type: object
30978
- properties:
30979
- number:
30980
- type: number
30981
- isNew:
30982
- type: boolean
30983
- required:
30984
- - number
30985
- - isNew
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@proveanything/smartlinks",
3
- "version": "2.0.54",
3
+ "version": "2.0.55",
4
4
  "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -1,38 +0,0 @@
1
- export interface AllocateSequenceInput {
2
- /** The app that owns the sequence config. */
3
- appId: string;
4
- /** The configured sequence id — the key of data.sequenceConfigs on the app config. */
5
- sequenceId: string;
6
- /**
7
- * The STABLE subject identity. For a `claimSet` sequence, pass the tap's virtual-proof id
8
- * `<claimSetId>-<code>` (e.g. "23-oOkf8o") for a per-wristband raffle — the code is the tag's
9
- * permanent id, so re-taps of the same wristband return the same number; the number is stamped
10
- * on that code's doc and surfaces in `tagData`. Pass a bare claim-set id for one number per
11
- * group. Never a value that changes per tap.
12
- */
13
- subjectId: string;
14
- /** Optional product scope, when the sequence config is scoped per product. */
15
- productId?: string;
16
- }
17
- export interface AllocatedSequence {
18
- /** The allocated (or already-held) number. */
19
- number: number;
20
- /** True when this call allocated a new number; false when the subject already had one. */
21
- isNew: boolean;
22
- }
23
- export declare namespace sequence {
24
- /**
25
- * Allocate (or return the existing) sequence number for a subject. Idempotent — safe to
26
- * call on load (auto-enter) and on a button tap; a subject that already has a number gets
27
- * it back with `isNew: false`.
28
- *
29
- * @example
30
- * const { number, isNew } = await sequence.allocate(collectionId, {
31
- * appId: 'raffle-app', sequenceId: 'raffle', subjectId: claimSetId,
32
- * })
33
- *
34
- * @deprecated Being removed. Number things in your app's own server function with
35
- * `ctx.sl.counters.next()` + `ctx.sl.appRecords.claim()` (docs/server-functions.md).
36
- */
37
- function allocate(collectionId: string, input: AllocateSequenceInput): Promise<AllocatedSequence>;
38
- }
@@ -1,29 +0,0 @@
1
- // src/api/sequence.ts
2
- //
3
- // Sequences — allocate a guaranteed-unique, monotonic number (raffle tickets, "Nth to
4
- // claim", queue positions) and stamp it onto a record. The sequence (counter key, target,
5
- // field, scope) is configured server-side in app config (data.sequenceConfigs[sequenceId]);
6
- // this call supplies only the subject and is idempotent — a re-tap returns the same number.
7
- // See docs/sequences.md.
8
- import { post } from "../http.js";
9
- export var sequence;
10
- (function (sequence) {
11
- const base = (collectionId) => `/public/collection/${encodeURIComponent(collectionId)}/sequence`;
12
- /**
13
- * Allocate (or return the existing) sequence number for a subject. Idempotent — safe to
14
- * call on load (auto-enter) and on a button tap; a subject that already has a number gets
15
- * it back with `isNew: false`.
16
- *
17
- * @example
18
- * const { number, isNew } = await sequence.allocate(collectionId, {
19
- * appId: 'raffle-app', sequenceId: 'raffle', subjectId: claimSetId,
20
- * })
21
- *
22
- * @deprecated Being removed. Number things in your app's own server function with
23
- * `ctx.sl.counters.next()` + `ctx.sl.appRecords.claim()` (docs/server-functions.md).
24
- */
25
- async function allocate(collectionId, input) {
26
- return post(`${base(collectionId)}/allocate`, input);
27
- }
28
- sequence.allocate = allocate;
29
- })(sequence || (sequence = {}));
@@ -1,125 +0,0 @@
1
- # Sequences & claim-order allocation
2
-
3
- > **Retiring — don't build on this.** `SL.sequence.allocate` is being removed. Number things in your
4
- > app's own server function instead: `ctx.sl.counters.next()` for the next number and
5
- > `ctx.sl.appRecords.claim()` to key it to a tag/person and make sure no number is ever held twice —
6
- > see server-functions.md → "Uniqueness, numbering and people". (The counter here lived inside the
7
- > app config doc, where an admin save could rewind it.)
8
-
9
- > **SmartLinks SDK 2.x** (current `latest`). Install `@proveanything/smartlinks@^2`.
10
-
11
- A **sequence** hands out a guaranteed-unique, monotonic number — `1, 2, 3, …` — and stamps it
12
- onto a record. It's the primitive behind raffle tickets, "you're the Nth to claim", queue
13
- positions, and limited-edition numbering: cases where you need *the next number*, exactly
14
- once per subject, even with a whole room (or stadium) acting at the same instant.
15
-
16
- ## The model: allocate, then stamp — and the target is the ledger
17
-
18
- Two steps, one call:
19
-
20
- 1. **Allocate** — get the next number from an **atomic counter**. The counter lives inside
21
- your **app-config** doc at `data.sequences.<key>`, so it's scoped exactly like your other
22
- app config (per collection / product / variant / batch) and needs no dedicated storage.
23
- It's incremented in a single statement, so 250 simultaneous taps each get a distinct
24
- number in microseconds — never two the same.
25
- 2. **Stamp** — write that number onto the **subject's own record** (a claim set, a proof, or
26
- an app record). **That record is the ledger** — there's no separate bookkeeping table.
27
- Next time you read the subject, the number is just there.
28
-
29
- Because the target is the ledger, allocation is **idempotent**: on a re-tap we read the
30
- subject first and return the number it already has, rather than allocating a second one.
31
-
32
- ## Guarantees
33
-
34
- - **Unique + monotonic** — the counter is an atomic increment, never a read-modify-write, so
35
- there are no duplicates and no lost updates under load.
36
- - **Idempotent per subject** — one number per subject; a re-tap returns the same number.
37
- - **Concurrency-safe at scale** — the only shared hot spot is the one counter row (Postgres
38
- serializes it); the stamp is per-subject (its own record), so the model holds from 250 in a
39
- room to 60,000 in a stadium. A concurrent double-tap on the *same* subject at worst skips
40
- one number (a harmless gap) — never puts two numbers on one person.
41
-
42
- ## Scoping
43
-
44
- - **Counter scope** — the app-config doc it lives on: collection-wide, or per product /
45
- variant / batch. All wristbands mapped to one product? Scope the counter to that product.
46
- - **`key`** — a name within that doc (e.g. `raffle:2026-cup`), so one config doc can hold
47
- several independent sequences.
48
- - **`start`** — the first number (default `1`); use it to reserve a block (start at `51` and
49
- tell people it's `1`, or just filter `< N` at draw time).
50
-
51
- ## Idempotency subject — use a *stable* id
52
-
53
- The number is deduped by the **subject id** you pass, so it must be the **stable** identity:
54
- - **Virtual-proof id `<claimSetId>-<code>`** (e.g. `23-oOkf8o`) — the right key for a
55
- per-wristband raffle. The `code` is the physical tag's permanent id, so a re-tap of the same
56
- wristband resolves to the same code doc → same number. The virtual proof record is transient,
57
- but the **code** inside its id is stable — that's what the sink keys on (it splits the id and
58
- uses only `<claimSetId>` + `<code>`).
59
- - **Bare claim-set id** — when one number per *group* is intended.
60
- - The authenticated **user/contact** — if they sign in / claim.
61
-
62
- Do **not** key on the transient part of a per-tap identity (a freshly-minted virtual proof
63
- record) — key on the stable **code**, which is exactly what the `<claimSetId>-<code>` subject
64
- carries.
65
-
66
- ## Where the number is stored (the sink)
67
-
68
- The stamp target is configurable — the number lives wherever you'll read it:
69
-
70
- | Target | Subject id | Use |
71
- |---|---|---|
72
- | `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. |
73
- | `proof` | the proof id | A minted proof (value or attestation) — when the number should travel with the proof. |
74
- | `appRecord` | the record id | A structured app record — for queryable, per-app data. |
75
-
76
- ## Configure the sequence (once, server-side)
77
-
78
- You define the sequence **in your app config**, under `data.sequenceConfigs`. This is what
79
- makes the public endpoint safe: the target/field/scope are set by you, not the caller.
80
-
81
- ```jsonc
82
- // app config: data.sequenceConfigs
83
- {
84
- "raffle": {
85
- "key": "raffle:2026-cup", // the named counter (data.sequences.<key>)
86
- "target": "claimSet", // claimSet | proof | appRecord — the ledger domain
87
- "field": "raffleNumber", // the property written on the target (comes back in tagData)
88
- "start": 1 // first number (optional, default 1)
89
- // no productId → one collection-wide counter (all wristbands share the sequence)
90
- }
91
- }
92
- ```
93
-
94
- > **Per-wristband raffle.** Keep `target: "claimSet"` and pass the tap's virtual-proof id
95
- > (`<claimSetId>-<code>`) as the subject — the sink writes the individual tag's **code** doc, so
96
- > each wristband gets its own number and it surfaces in `tagData` on the next tap. Pass a bare
97
- > claim-set id instead only if you want one number for the whole group.
98
-
99
- ## Call it (the widget)
100
-
101
- Your widget calls one bounded, public endpoint on tap. It passes only the **subject id** —
102
- never the target/field:
103
-
104
- ```
105
- POST /api/v1/public/collection/:collectionId/sequence/allocate
106
- { "appId": "liveWidgets", "sequenceId": "raffle", "subjectId": "23-oOkf8o" }
107
- → { "number": 42, "isNew": true } // re-tap → { "number": 42, "isNew": false }
108
- ```
109
-
110
- - **`subjectId`** is the STABLE identity. For `claimCode` it's the virtual-proof id
111
- `<claimSetId>-<code>` (e.g. `23-oOkf8o`) straight off the tap — re-taps of the same wristband
112
- collapse to one number. (For `claimSet` it's the claim-set id.)
113
- - **Idempotent**, so both your flows are the *same call*:
114
- - **Auto:** on load, call allocate → get your number (existing or freshly minted).
115
- - **Button:** click → animate → same call → "Your raffle number is 42."
116
- - **Refresh:** just read the `raffleNumber` field back off the claim set (or proof) — it's the
117
- ledger. Or call allocate again; you'll get the same number with `isNew: false`.
118
-
119
- Errors: `404 SEQUENCE_NOT_FOUND` (not configured), `404 CLAIMSET_NOT_FOUND` (bad subject),
120
- `400 BAD_REQUEST` (missing fields).
121
-
122
- ## Drawing the winner
123
-
124
- No separate ledger — query the claim sets (or proofs) where `raffleNumber` is set; that field
125
- is your entry list, in allocation order.
package/docs/sequences.md DELETED
@@ -1,125 +0,0 @@
1
- # Sequences & claim-order allocation
2
-
3
- > **Retiring — don't build on this.** `SL.sequence.allocate` is being removed. Number things in your
4
- > app's own server function instead: `ctx.sl.counters.next()` for the next number and
5
- > `ctx.sl.appRecords.claim()` to key it to a tag/person and make sure no number is ever held twice —
6
- > see server-functions.md → "Uniqueness, numbering and people". (The counter here lived inside the
7
- > app config doc, where an admin save could rewind it.)
8
-
9
- > **SmartLinks SDK 2.x** (current `latest`). Install `@proveanything/smartlinks@^2`.
10
-
11
- A **sequence** hands out a guaranteed-unique, monotonic number — `1, 2, 3, …` — and stamps it
12
- onto a record. It's the primitive behind raffle tickets, "you're the Nth to claim", queue
13
- positions, and limited-edition numbering: cases where you need *the next number*, exactly
14
- once per subject, even with a whole room (or stadium) acting at the same instant.
15
-
16
- ## The model: allocate, then stamp — and the target is the ledger
17
-
18
- Two steps, one call:
19
-
20
- 1. **Allocate** — get the next number from an **atomic counter**. The counter lives inside
21
- your **app-config** doc at `data.sequences.<key>`, so it's scoped exactly like your other
22
- app config (per collection / product / variant / batch) and needs no dedicated storage.
23
- It's incremented in a single statement, so 250 simultaneous taps each get a distinct
24
- number in microseconds — never two the same.
25
- 2. **Stamp** — write that number onto the **subject's own record** (a claim set, a proof, or
26
- an app record). **That record is the ledger** — there's no separate bookkeeping table.
27
- Next time you read the subject, the number is just there.
28
-
29
- Because the target is the ledger, allocation is **idempotent**: on a re-tap we read the
30
- subject first and return the number it already has, rather than allocating a second one.
31
-
32
- ## Guarantees
33
-
34
- - **Unique + monotonic** — the counter is an atomic increment, never a read-modify-write, so
35
- there are no duplicates and no lost updates under load.
36
- - **Idempotent per subject** — one number per subject; a re-tap returns the same number.
37
- - **Concurrency-safe at scale** — the only shared hot spot is the one counter row (Postgres
38
- serializes it); the stamp is per-subject (its own record), so the model holds from 250 in a
39
- room to 60,000 in a stadium. A concurrent double-tap on the *same* subject at worst skips
40
- one number (a harmless gap) — never puts two numbers on one person.
41
-
42
- ## Scoping
43
-
44
- - **Counter scope** — the app-config doc it lives on: collection-wide, or per product /
45
- variant / batch. All wristbands mapped to one product? Scope the counter to that product.
46
- - **`key`** — a name within that doc (e.g. `raffle:2026-cup`), so one config doc can hold
47
- several independent sequences.
48
- - **`start`** — the first number (default `1`); use it to reserve a block (start at `51` and
49
- tell people it's `1`, or just filter `< N` at draw time).
50
-
51
- ## Idempotency subject — use a *stable* id
52
-
53
- The number is deduped by the **subject id** you pass, so it must be the **stable** identity:
54
- - **Virtual-proof id `<claimSetId>-<code>`** (e.g. `23-oOkf8o`) — the right key for a
55
- per-wristband raffle. The `code` is the physical tag's permanent id, so a re-tap of the same
56
- wristband resolves to the same code doc → same number. The virtual proof record is transient,
57
- but the **code** inside its id is stable — that's what the sink keys on (it splits the id and
58
- uses only `<claimSetId>` + `<code>`).
59
- - **Bare claim-set id** — when one number per *group* is intended.
60
- - The authenticated **user/contact** — if they sign in / claim.
61
-
62
- Do **not** key on the transient part of a per-tap identity (a freshly-minted virtual proof
63
- record) — key on the stable **code**, which is exactly what the `<claimSetId>-<code>` subject
64
- carries.
65
-
66
- ## Where the number is stored (the sink)
67
-
68
- The stamp target is configurable — the number lives wherever you'll read it:
69
-
70
- | Target | Subject id | Use |
71
- |---|---|---|
72
- | `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. |
73
- | `proof` | the proof id | A minted proof (value or attestation) — when the number should travel with the proof. |
74
- | `appRecord` | the record id | A structured app record — for queryable, per-app data. |
75
-
76
- ## Configure the sequence (once, server-side)
77
-
78
- You define the sequence **in your app config**, under `data.sequenceConfigs`. This is what
79
- makes the public endpoint safe: the target/field/scope are set by you, not the caller.
80
-
81
- ```jsonc
82
- // app config: data.sequenceConfigs
83
- {
84
- "raffle": {
85
- "key": "raffle:2026-cup", // the named counter (data.sequences.<key>)
86
- "target": "claimSet", // claimSet | proof | appRecord — the ledger domain
87
- "field": "raffleNumber", // the property written on the target (comes back in tagData)
88
- "start": 1 // first number (optional, default 1)
89
- // no productId → one collection-wide counter (all wristbands share the sequence)
90
- }
91
- }
92
- ```
93
-
94
- > **Per-wristband raffle.** Keep `target: "claimSet"` and pass the tap's virtual-proof id
95
- > (`<claimSetId>-<code>`) as the subject — the sink writes the individual tag's **code** doc, so
96
- > each wristband gets its own number and it surfaces in `tagData` on the next tap. Pass a bare
97
- > claim-set id instead only if you want one number for the whole group.
98
-
99
- ## Call it (the widget)
100
-
101
- Your widget calls one bounded, public endpoint on tap. It passes only the **subject id** —
102
- never the target/field:
103
-
104
- ```
105
- POST /api/v1/public/collection/:collectionId/sequence/allocate
106
- { "appId": "liveWidgets", "sequenceId": "raffle", "subjectId": "23-oOkf8o" }
107
- → { "number": 42, "isNew": true } // re-tap → { "number": 42, "isNew": false }
108
- ```
109
-
110
- - **`subjectId`** is the STABLE identity. For `claimCode` it's the virtual-proof id
111
- `<claimSetId>-<code>` (e.g. `23-oOkf8o`) straight off the tap — re-taps of the same wristband
112
- collapse to one number. (For `claimSet` it's the claim-set id.)
113
- - **Idempotent**, so both your flows are the *same call*:
114
- - **Auto:** on load, call allocate → get your number (existing or freshly minted).
115
- - **Button:** click → animate → same call → "Your raffle number is 42."
116
- - **Refresh:** just read the `raffleNumber` field back off the claim set (or proof) — it's the
117
- ledger. Or call allocate again; you'll get the same number with `isNew: false`.
118
-
119
- Errors: `404 SEQUENCE_NOT_FOUND` (not configured), `404 CLAIMSET_NOT_FOUND` (bad subject),
120
- `400 BAD_REQUEST` (missing fields).
121
-
122
- ## Drawing the winner
123
-
124
- No separate ledger — query the claim sets (or proofs) where `raffleNumber` is set; that field
125
- is your entry list, in allocation order.