@proveanything/smartlinks 2.1.8 → 2.1.11

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.1.8  |  Generated: 2026-11-02T13:05:01.425Z
+Version: 2.1.11  |  Generated: 2026-11-08T09:25:58.482Z
 
 This is a concise summary of all available API functions and types.
 
@@ -153,6 +153,7 @@ The Smartlinks SDK is organized into the following namespaces:
 - **lots** - Functions for lots operations
 - **navigation** - Functions for navigation operations
 - **order** - Functions for order operations
+- **partner** - Functions for partner operations
 - **products** - Functions for products operations
 - **realtime** - Functions for realtime operations
 - **research** - Functions for research operations
@@ -186,17 +187,17 @@ The release channel explicitly set for this app build (initializeApi({ appChanne
 **setAppChannel**(channel: string | undefined) → `void`
 Set (or clear) the release channel SL.functions calls target.
 
-**initializeApi**(options: {
-  baseURL: string
-  apiKey?: string
-  bearerToken?: string
-  proxyMode?: boolean
-  ngrokSkipBrowserWarning?: boolean
-  extraHeaders?: Record<string, string>
-  /**
-   * Declares the host platform. Set to `'native'` on native/Capacitor hosts to opt into
-   * AuthKit refresh tokens — the SDK then sends `X-Client-Platform: native` on every
-   * request, so login endpoints return `refreshToken`/`refreshTokenExpiresAt` and a
+**initializeApi**(options: {
+  baseURL: string
+  apiKey?: string
+  bearerToken?: string
+  proxyMode?: boolean
+  ngrokSkipBrowserWarning?: boolean
+  extraHeaders?: Record<string, string>
+  /**
+   * Declares the host platform. Set to `'native'` on native/Capacitor hosts to opt into
+   * AuthKit refresh tokens — the SDK then sends `X-Client-Platform: native` on every
+   * request, so login endpoints return `refreshToken`/`refreshTokenExpiresAt` and a
    * short-lived access token. Omit (or `'web'`) → `void`
 Call this once (e.g. at app startup) to configure baseURL/auth.
 
@@ -227,56 +228,56 @@ Returns true if initializeApi() has been called at least once. Useful for guards
 **hasAuthCredentials**() → `boolean`
 Returns true if the SDK currently has any auth credential set (bearer token or API key). Use this as a cheap pre-flight check before calling endpoints that require authentication, to avoid issuing a network request that you already know will return a 401. ```ts if (hasAuthCredentials()) { const account = await auth.getAccount() } ```
 
-**configureSdkCache**(options: {
-  enabled?: boolean
-  ttlMs?: number
-  maxEntries?: number
-  persistence?: 'none' | 'indexeddb'
-  persistenceTtlMs?: number
-  serveStaleOnOffline?: boolean
-  clearOnPageLoad?: boolean
+**configureSdkCache**(options: {
+  enabled?: boolean
+  ttlMs?: number
+  maxEntries?: number
+  persistence?: 'none' | 'indexeddb'
+  persistenceTtlMs?: number
+  serveStaleOnOffline?: boolean
+  clearOnPageLoad?: boolean
 }) → `void`
 Configure the SDK's built-in in-memory GET cache. The cache is transparent — it sits inside the HTTP layer and requires no changes to your existing API calls. All GET requests benefit automatically. Per-resource rules (collections/products → 1 h, proofs → 30 s, etc.) override this value. in-memory only (`'none'`, default). Ignored in Node.js. fallback, from the original fetch time (default: 7 days). `SmartlinksOfflineError` with stale data instead of propagating the network error. caches on page load/refresh. IndexedDB persists for offline. ```ts // Enable IndexedDB persistence for offline support configureSdkCache({ persistence: 'indexeddb' }) // Disable cache entirely in test environments configureSdkCache({ enabled: false }) // Keep caches across page refreshes (not recommended for production) configureSdkCache({ clearOnPageLoad: false }) ```
 
 **invalidateCache**(urlPattern?: string, options?: InvalidateCacheOptions) → `void`
 Manually invalidate entries in the SDK's GET cache. Note: the GET cache is **in-memory, per page load** (with an optional L2 IndexedDB layer when persistence is enabled) — it does not persist across reloads unless you opt into persistence, so it rarely needs disabling "for correctness". *contains* this string is removed). With `{ exact: true }`, matches the path precisely. Omit to wipe the entire cache. ```ts invalidateCache()                                  // clear everything invalidateCache('/collection/abc123')              // that collection AND everything under it invalidateCache('/collection/abc123', { exact: true }) // ONLY that collection entry invalidateCache('/products/')                      // all canonical plural product responses ```
 
-**proxyUploadFormData**(path: string,
-  formData: FormData,
+**proxyUploadFormData**(path: string,
+  formData: FormData,
   onProgress?: (percent: number) → `void`
 Upload a FormData payload via proxy with progress events using chunked postMessage. Parent is expected to implement the counterpart protocol.
 
 **request**(path: string) → `Promise<T>`
 Internal helper that performs a GET request to `${baseURL}${path}`, injecting headers for apiKey or bearerToken if present. Cache pipeline (when caching is not skipped): L1 hit  → return from memory (no I/O) L2 hit  → return from IndexedDB, promote to L1 (no network) Miss    → fetch from network, store in L1 + L2 Offline → serve stale L2 entry via SmartlinksOfflineError (if persistence enabled) Concurrent identical GETs share one in-flight promise (deduplication). Node-safe: IndexedDB calls are no-ops when IDB is unavailable.
 
-**post**(path: string,
-  body: any,
+**post**(path: string,
+  body: any,
   extraHeaders?: Record<string, string>) → `Promise<T>`
 Internal helper that performs a POST request to `${baseURL}${path}`, injecting headers for apiKey or bearerToken if present. If body is FormData, Content-Type is not set. Returns the parsed JSON as T, or throws an Error.
 
-**put**(path: string,
-  body: any,
+**put**(path: string,
+  body: any,
   extraHeaders?: Record<string, string>) → `Promise<T>`
 Internal helper that performs a PUT request to `${baseURL}${path}`, injecting headers for apiKey or bearerToken if present. If body is FormData, Content-Type is not set. Returns the parsed JSON as T, or throws an Error.
 
-**patch**(path: string,
-  body: any,
+**patch**(path: string,
+  body: any,
   extraHeaders?: Record<string, string>) → `Promise<T>`
 Internal helper that performs a PATCH request to `${baseURL}${path}`, injecting headers for apiKey or bearerToken if present. If body is FormData, Content-Type is not set. Returns the parsed JSON as T, or throws an Error.
 
-**requestWithOptions**(path: string,
+**requestWithOptions**(path: string,
   options: RequestInit) → `Promise<T>`
 Internal helper that performs a request to `${baseURL}${path}` with custom options, injecting headers for apiKey or bearerToken if present. Returns the parsed JSON as T, or throws an Error.
 
-**requestStream**(path: string,
-  options?: {
-    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
-    body?: any
-    headers?: Record<string, string>
+**requestStream**(path: string,
+  options?: {
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+    body?: any
+    headers?: Record<string, string>
   }) → `Promise<AsyncIterable<T>>`
 Internal helper that performs a streaming request using the shared auth and proxy transport. The response is expected to be `text/event-stream` with JSON payloads in `data:` frames.
 
-**del**(path: string,
+**del**(path: string,
   extraHeaders?: Record<string, string>) → `Promise<T>`
 Internal helper that performs a DELETE request to `${baseURL}${path}`, injecting headers for apiKey or bearerToken if present. Returns the parsed JSON as T, or throws an Error.
 
@@ -5731,6 +5732,188 @@ interface CreateClaimSetTagResponse {
 }
 ```
 
+**ClaimSetRange** (interface)
+```typescript
+interface ClaimSetRange {
+  id: string
+  claimSetId: string
+  namespace: string
+  name: string
+  notes: string | null
+  startIndex: number
+  endIndex: number
+  quantity: number
+  tagType: ClaimSetTagType
+  fulfilment: 'printer' | 'sidekick'
+  stage: 'minting' | 'minted' | 'sent' | 'received'
+  status: ClaimSetRangeStatus
+  intendedCollectionId: string | null
+  intendedProductId: string | null
+  intendedBatchId: string | null
+  manufacturer: string | null
+  orderRef: string | null
+  counts: { programmed: number; assigned: number; claimed: number }
+  sentAt: string | null
+  receivedAt: string | null
+  createdBy: string | null
+  createdAt: string
+  updatedAt: string
+}
+```
+
+**CreateClaimSetRangeRequest** (interface)
+```typescript
+interface CreateClaimSetRangeRequest {
+  name: string
+  quantity: number
+  intendedCollectionId?: string
+  intendedProductId?: string
+  intendedBatchId?: string
+  fulfilment?: 'printer' | 'sidekick'
+  notes?: string
+  manufacturer?: string
+  orderRef?: string
+}
+```
+
+**UpdateClaimSetRangeRequest** (interface)
+```typescript
+interface UpdateClaimSetRangeRequest {
+  name?: string
+  notes?: string | null
+  manufacturer?: string | null
+  orderRef?: string | null
+  fulfilment?: 'printer' | 'sidekick'
+  stage?: 'minted' | 'sent' | 'received'
+}
+```
+
+**ClaimSetRangeTag** (interface)
+```typescript
+interface ClaimSetRangeTag {
+  code: string
+  printed: string
+  index: number
+  uid: string | null
+  key?: string
+  collectionId: string | null
+  productId: string | null
+  batchId: string | null
+  proofId: string | null
+  programmedAt: string | null
+  scans: number
+}
+```
+
+**ClaimSetRangeTagsPage** (interface)
+```typescript
+interface ClaimSetRangeTagsPage {
+  tags: ClaimSetRangeTag[]
+  next: number | null
+}
+```
+
+**ImportClaimSetRangeUidsRequest** (interface)
+```typescript
+interface ImportClaimSetRangeUidsRequest {
+  csv?: string
+  rows?: Array<Record<string, string | number>>
+  commit?: boolean
+}
+```
+
+**ImportClaimSetRangeUidsResponse** (interface)
+```typescript
+interface ImportClaimSetRangeUidsResponse {
+  summary: { rows: number; ok: number; unchanged: number; problems: number; notInFile: number; committed: boolean }
+  rows: Array<{ line: number; code: string; index: number | null; uid: string; result: ClaimSetImportResult; message?: string }>
+  range: ClaimSetRange
+}
+```
+
+**AssignClaimSetRangeRequest** (interface)
+```typescript
+interface AssignClaimSetRangeRequest {
+  collectionId?: string
+  productId?: string
+  batchId?: string
+  start?: number
+  end?: number
+  clear?: boolean
+  data?: Record<string, unknown>
+}
+```
+
+**AssignClaimSetRangeResponse** (interface)
+```typescript
+interface AssignClaimSetRangeResponse {
+  changed: number
+  skipped: Array<{ code: string; index: number; reason: 'other_range' | 'has_proof' | 'assigned_elsewhere'; collectionId?: string }>
+  range: ClaimSetRange
+}
+```
+
+**ClaimSetRangeFile** (interface)
+```typescript
+interface ClaimSetRangeFile {
+  filename: string
+  contentType: string
+  csv?: string
+  base64?: string
+  markdown?: string
+}
+```
+
+**Partner** (interface)
+```typescript
+interface Partner {
+  id: string
+  name: string
+  status: 'active' | 'suspended'
+  tapDomains: string[]
+  features: Record<string, boolean>
+  role?: 'owner' | 'admin' | 'assigner'
+  members?: Array<{ userId: string; role: 'owner' | 'admin' | 'assigner'; grantedBy: string | null; grantedAt: string }>
+  createdAt: string
+  updatedAt: string
+}
+```
+
+**PartnerClaimSet** (interface)
+```typescript
+interface PartnerClaimSet {
+  id: string
+  namespace: string
+  name: string | null
+  tagType: ClaimSetTagType
+  tapDomain: string
+  owner: { type: 'platform' | 'partner' | 'collection' | 'user'; id: string | null }
+  codes: number
+  deleted: boolean
+  createdAt: string | null
+}
+```
+
+**CreatePartnerClaimSetRequest** (interface)
+```typescript
+interface CreatePartnerClaimSetRequest {
+  name: string
+  tagType: ClaimSetTagType
+  tapDomain?: string
+}
+```
+
+**ClaimSetScope** (type)
+```typescript
+type ClaimSetScope = { collectionId: string }
+```
+
+**ClaimSetTagType** = `'ntag424' | 'ntag21x' | 'qr'`
+
+**ClaimSetRangeStatus** = `'minting' | 'minted' | 'sent' | 'received' | 'assigned'`
+
+**ClaimSetImportResult** = ``
+
 ### collection
 
 **Collection** (interface)
@@ -12119,6 +12302,46 @@ Assign claims to codes or ranges within a collection.
 **updateClaimData**(collectionId: string, data: UpdateClaimDataRequest) → `Promise<any>`
 Update claim data for a claim set (collection-scoped).
 
+### claimSet.ranges
+
+**list**(scope: ClaimSetScope, claimSetId: string) → `Promise<ClaimSetRange[]>`
+The ranges in a set, lowest index first.
+
+**create**(scope: ClaimSetScope, claimSetId: string, params: CreateClaimSetRangeRequest) → `Promise<ClaimSetRange>`
+Reserve the set's next indexes and mint a code (and, for NTAG 424, a key) for each.
+
+**get**(scope: ClaimSetScope, claimSetId: string, rangeId: string) → `Promise<ClaimSetRange>`
+One range, with its counts refreshed.
+
+**update**(scope: ClaimSetScope, claimSetId: string, rangeId: string, params: UpdateClaimSetRangeRequest) → `Promise<ClaimSetRange>`
+Name, notes, order details, or a stage move (sent to the printer, received).
+
+**resume**(scope: ClaimSetScope, claimSetId: string, rangeId: string) → `Promise<ClaimSetRange>`
+Finish minting a range that was interrupted.
+
+**tags**(scope: ClaimSetScope, claimSetId: string, rangeId: string,
+      options: { from?: number; limit?: number; keys?: boolean } = {}) → `Promise<ClaimSetRangeTagsPage>`
+The range's tags in index order, a page at a time (keys: owners/admins only).
+
+**next**(scope: ClaimSetScope, claimSetId: string, rangeId: string) → `Promise<ClaimSetRangeNextTag>`
+The next tag to program on a phone (lowest index without a chip), with its URL and key.
+
+**recordTag**(scope: ClaimSetScope, claimSetId: string, rangeId: string, code: string,
+      params: { uid: string; data?: Record<string, unknown> }) → `Promise<`
+Record the chip a phone just programmed with this code.
+
+**exportFile**(scope: ClaimSetScope, claimSetId: string, rangeId: string) → `Promise<ClaimSetRangeFile>`
+The printer file (CSV text in `csv`). Carries the tags' keys: don't keep it around.
+
+**instructions**(scope: ClaimSetScope, claimSetId: string, rangeId: string, format: 'pdf' | 'md' = 'pdf') → `Promise<ClaimSetRangeFile>`
+The manufacturer's instruction sheet: PDF (base64) or Markdown.
+
+**importUids**(scope: ClaimSetScope, claimSetId: string, rangeId: string, params: ImportClaimSetRangeUidsRequest) → `Promise<ImportClaimSetRangeUidsResponse>`
+The manufacturer's file back: check it (commit false), then write the chip UIDs (commit true).
+
+**assign**(scope: ClaimSetScope, claimSetId: string, rangeId: string, params: AssignClaimSetRangeRequest) → `Promise<AssignClaimSetRangeResponse>`
+Point the range (or from–to within it) at a collection / product / batch, or clear it.
+
 ### collection
 
 **get**(collectionId: string, admin?: boolean) → `Promise<CollectionResponse>`
@@ -13030,6 +13253,23 @@ Get individual order items for a specific product. Returns all matching items wi
     params?: GetOrderIdsParams) → `Promise<GetOrderIdsResponse>`
 Get unique order IDs containing items for a specific product. Lightweight query that only returns order IDs, not full order objects. ```typescript // Get order IDs for a product const productOrders = await order.getOrderIdsByAttribute( 'coll_123', 'productId', 'prod_789', { limit: 500 } ) ```
 
+### partner
+
+**list**() → `Promise<Partner[]>`
+The partners you belong to, with your role in each. Empty for everyone else.
+
+**get**(partnerId: string) → `Promise<Partner>`
+One partner (owners also see its members).
+
+**claimSets**(partnerId: string) → `Promise<PartnerClaimSet[]>`
+The partner's claim sets.
+
+**getClaimSet**(partnerId: string, claimSetId: string) → `Promise<PartnerClaimSet>`
+One of the partner's claim sets.
+
+**createClaimSet**(partnerId: string, params: CreatePartnerClaimSetRequest) → `Promise<PartnerClaimSet>`
+A new claim set for the partner, on one of its tap domains (owners and admins).
+
 ### podcast
 
 **generate**(collectionId: string,

package/docs/tag-ranges.md

@@ -0,0 +1,75 @@
+# NFC tag ranges and partners
+
+For partners and enterprise clients who run their own tag programmes: mint a batch of tags, send them
+to a manufacturer with instructions, get the chip UIDs back, then put the tags to work for a client or
+product. Ordinary business collections don't use this.
+
+## The words
+
+| Word | Means |
+|---|---|
+| **Claim set** | A pool of codes on one tap domain and one tag type (NTAG 424 DNA, NTAG 213/215/216, or QR). Most partners need one. |
+| **Range** | A named, contiguous block of tags inside a set: "Tap to donate - February", 100 tags, indexes 201-300. |
+| **Index** | A tag's place in its set. Ranges never overlap and indexes are never reused. |
+| **Partner** | An organisation above collections that owns sets and assigns their tags into collections its people administer. Set up by SmartLinks staff. |
+
+## Who can do what
+
+`scope` is `{ partnerId }` for a partner's sets, or `{ collectionId }` for a collection's own sets.
+
+| Role | Can |
+|---|---|
+| Partner owner / admin, or a collection admin | Make sets, mint ranges, download the printer file and instructions, import UIDs, program tags, assign |
+| Partner assigner | See ranges and tags (never keys), assign |
+
+Assigning always needs you to be an admin of the collection the tags go to.
+
+## The flow
+
+```ts
+import { partner, claimSet } from '@proveanything/smartlinks'
+
+const [p] = await partner.list()                       // the partners you belong to
+const scope = { partnerId: p.id }
+const [set] = await partner.claimSets(p.id)            // or partner.createClaimSet(p.id, { name, tagType: 'ntag424', tapDomain })
+
+// 1. Mint
+const range = await claimSet.ranges.create(scope, set.id, { name: 'Tap to donate - February', quantity: 100 })
+
+// 2. Send to print: the CSV (carries each tag's key) and the instruction sheet
+const file = await claimSet.ranges.exportFile(scope, set.id, range.id)          // { filename, csv }
+const sheet = await claimSet.ranges.instructions(scope, set.id, range.id, 'pdf') // { filename, base64 }
+await claimSet.ranges.update(scope, set.id, range.id, { stage: 'sent', manufacturer: 'Print Co', orderRef: 'PO-123' })
+
+// 3. Receive: the manufacturer sends back the same file with UID filled in
+const check = await claimSet.ranges.importUids(scope, set.id, range.id, { csv: returnedCsv })
+// check.rows: ok / index_mismatch / bad_uid / uid_in_use / … ; nothing written yet
+await claimSet.ranges.importUids(scope, set.id, range.id, { csv: returnedCsv, commit: true })
+
+// 4. Assign all of it, or from-to
+await claimSet.ranges.assign(scope, set.id, range.id, { collectionId: 'reading-fc', productId: 'scarf', start: 201, end: 250 })
+```
+
+**Programming on a phone instead of a manufacturer** (Sidekick): `ranges.next()` gives the lowest
+tag without a chip, with its URL and key; write it, then `ranges.recordTag(scope, set.id, range.id, code, { uid })`.
+
+## The printer file
+
+One row per tag, in index order. The manufacturer fills in `UID` and sends the same file back; rows are
+matched by `Code`, and `Index` is checked.
+
+| Tag type | Columns |
+|---|---|
+| NTAG 424 DNA | `Index, Code, URL, PiccOffset, Key, UID` |
+| NTAG 213/215/216 | `Index, Code, URL, MirrorOffset, MirrorPage, MirrorByte, UID` |
+| QR | `Index, Code, URL` |
+
+`URL` is `https://{tap domain}/t/{set}/{code}` plus the placeholder the chip fills on every read
+(`?p=` + 32 zeros for 424 SUN, `?m=00000000000000x000000` for the 21x UID and counter mirror). The
+offsets are byte positions in the NDEF data, assuming the `https://` URI prefix code and a short record.
+
+## Notes
+
+- Range responses are never cached by the SDK: tags change as they're programmed and several carry keys.
+- A tag bound to a proof (minted or claimed) is never moved or cleared by `assign`; it's reported in `skipped`.
+- `status` is the stage (`minted`, `sent`, `received`), or `assigned` once every tag is assigned.

package/docs/theme-tokens.md

@@ -99,6 +99,14 @@ renders correctly even against a host that sets none of them.
 
 Dark mode is a *theme* (a different value-set), not a separate token set — the host swaps the values.
 
+- **Host:** in dark mode, send a dark value-set — in the iframe address (`#slt=` with `theme: "dark"`, and the
+  legacy `theme=` payload with `m: "d"`) or on the mount root. Sending only the hook (`dark=1`, `.dark`)
+  leaves the app to guess.
+- **App:** `theme.css` has dark fallbacks under `.dark` / `[data-theme="dark"]`, so an app built on it stays
+  readable even when a host sends the hook and no values. An app with its own CSS variables should do the
+  same: a light fallback at the root, a dark one under the hook — never a light colour that also stands
+  in for dark.
+
 ---
 
 ## 3. Theme value-sets (what the AI emits, what the lookbook stores)