@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.
- package/dist/api/index.d.ts +0 -1
- package/dist/api/index.js +0 -1
- package/dist/docs/API_SUMMARY.md +1 -27
- package/dist/docs/overview.md +0 -1
- package/dist/openapi.yaml +0 -25
- package/docs/API_SUMMARY.md +1 -27
- package/docs/overview.md +0 -1
- package/openapi.yaml +0 -25
- package/package.json +1 -1
- package/dist/api/sequence.d.ts +0 -38
- package/dist/api/sequence.js +0 -29
- package/dist/docs/sequences.md +0 -125
- package/docs/sequences.md +0 -125
package/dist/api/index.d.ts
CHANGED
|
@@ -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";
|
package/dist/docs/API_SUMMARY.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Smartlinks API Summary
|
|
2
2
|
|
|
3
|
-
Version: 2.0.
|
|
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/dist/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/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
|
package/docs/API_SUMMARY.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Smartlinks API Summary
|
|
2
2
|
|
|
3
|
-
Version: 2.0.
|
|
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
package/dist/api/sequence.d.ts
DELETED
|
@@ -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
|
-
}
|
package/dist/api/sequence.js
DELETED
|
@@ -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 = {}));
|
package/dist/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.
|
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.
|