@proveanything/smartlinks 2.1.11 → 2.1.12

package/dist/api/claimSet.d.ts

@@ -117,7 +117,8 @@ export declare namespace claimSet {
         /** Record the chip a phone just programmed with this code. */
         function recordTag(scope: ClaimSetScope, claimSetId: string, rangeId: string, code: string, params: {
             uid: string;
-            data?: Record<string, unknown>;
+            data?: Record<string, unknown>; /** A plain (NTAG 21x) tag's write password, kept with the tag */
+            password?: string;
         }): Promise<{
             tag: ClaimSetRangeTag;
             range: ClaimSetRange;

package/dist/api/partner.d.ts

@@ -1,4 +1,4 @@
-import { Partner, PartnerClaimSet, CreatePartnerClaimSetRequest } from "../types/index.js";
+import { Partner, PartnerClaimSet, CreatePartnerClaimSetRequest, PartnerTagHit } from "../types/index.js";
 /**
  * Partners: organisations above collections (FanConnect, Zenith Coins, …) that own NFC claim sets and
  * assign their tags into collections their people administer. Partners and their members are set up by
@@ -16,4 +16,9 @@ export declare namespace partner {
     function getClaimSet(partnerId: string, claimSetId: string): Promise<PartnerClaimSet>;
     /** A new claim set for the partner, on one of its tap domains (owners and admins). */
     function createClaimSet(partnerId: string, params: CreatePartnerClaimSetRequest): Promise<PartnerClaimSet>;
+    /** Find a tag across the partner's sets by its chip UID (8 or 14 hex) or its code (printed or bare). Never returns keys. */
+    function lookupTags(partnerId: string, query: {
+        uid?: string;
+        code?: string;
+    }): Promise<PartnerTagHit[]>;
 }

package/dist/api/partner.js

@@ -32,4 +32,14 @@ export var partner;
         return post(`/admin/partner/${encodeURIComponent(partnerId)}/claimSet`, params);
     }
     partner.createClaimSet = createClaimSet;
+    /** Find a tag across the partner's sets by its chip UID (8 or 14 hex) or its code (printed or bare). Never returns keys. */
+    async function lookupTags(partnerId, query) {
+        const q = new URLSearchParams();
+        if (query.uid)
+            q.set('uid', query.uid);
+        if (query.code)
+            q.set('code', query.code);
+        return request(`/admin/partner/${encodeURIComponent(partnerId)}/tags/lookup?${q}`);
+    }
+    partner.lookupTags = lookupTags;
 })(partner || (partner = {}));

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.1.11  |  Generated: 2026-11-08T09:25:58.482Z
+Version: 2.1.12  |  Generated: 2026-11-08T14:30:42.034Z
 
 This is a concise summary of all available API functions and types.
 
@@ -5894,6 +5894,17 @@ interface PartnerClaimSet {
 }
 ```
 
+**PartnerTagHit** (interface)
+```typescript
+interface PartnerTagHit {
+  namespace: string
+  claimSetId: string
+  set: PartnerClaimSet | null
+  tag: ClaimSetRangeTag & { url: string | null }
+  range: ClaimSetRange | null
+}
+```
+
 **CreatePartnerClaimSetRequest** (interface)
 ```typescript
 interface CreatePartnerClaimSetRequest {
@@ -9330,6 +9341,8 @@ interface NfcValidateRequest {
   claimSetId: string
   codeId: string
   mirror?: string
+  d?: string
+  c?: string
   userId?: string
 }
 ```
@@ -12327,21 +12340,9 @@ The range's tags in index order, a page at a time (keys: owners/admins only).
 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<`
+      params: { uid: string; data?: Record<string, unknown>; /** A plain (NTAG 21x) → `void`
 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>`
@@ -13270,6 +13271,9 @@ 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).
 
+**lookupTags**(partnerId: string, query: { uid?: string; code?: string }) → `Promise<PartnerTagHit[]>`
+Find a tag across the partner's sets by its chip UID (8 or 14 hex) or its code (printed or bare). Never returns keys.
+
 ### podcast
 
 **generate**(collectionId: string,

package/dist/docs/tag-ranges.md

@@ -1,75 +1,77 @@
-# 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.
+# 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 })` (add `password` for a plain tag's write password).
+
+To find where a chip or code went, `partner.lookupTags(partner.id, { uid })` or `{ code }` searches every set the partner owns and returns each hit's set, tag and range, never a key.
+
+## 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/dist/openapi.yaml

@@ -9141,6 +9141,45 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /admin/partner/{partnerId}/tags/lookup:
+    get:
+      tags:
+        - partner
+      summary: "Find a tag across the partner's sets by its chip UID (8 or 14 hex) or its code (printed or bare)."
+      operationId: partner_lookupTags
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: partnerId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: uid
+          in: query
+          required: false
+          schema:
+            type: string
+        - name: code
+          in: query
+          required: false
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/PartnerTagHit"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
   /authKit/{authKitId}/config:
     get:
       tags:
@@ -26120,6 +26159,25 @@ components:
         - codes
         - deleted
         - createdAt
+    PartnerTagHit:
+      type: object
+      properties:
+        namespace:
+          type: string
+        claimSetId:
+          type: string
+        set:
+          $ref: "#/components/schemas/PartnerClaimSet"
+        tag:
+          $ref: "#/components/schemas/ClaimSetRangeTag"
+        range:
+          $ref: "#/components/schemas/ClaimSetRange"
+      required:
+        - namespace
+        - claimSetId
+        - set
+        - tag
+        - range
     CreatePartnerClaimSetRequest:
       type: object
       properties:
@@ -31324,6 +31382,10 @@ components:
           type: string
         mirror:
           type: string
+        d:
+          type: string
+        c:
+          type: string
         userId:
           type: string
       required:

package/dist/types/claimSet.d.ts

@@ -301,6 +301,16 @@ export interface PartnerClaimSet {
     deleted: boolean;
     createdAt: string | null;
 }
+/** One hit from partner.lookupTags */
+export interface PartnerTagHit {
+    namespace: string;
+    claimSetId: string;
+    set: PartnerClaimSet | null;
+    tag: ClaimSetRangeTag & {
+        url: string | null;
+    };
+    range: ClaimSetRange | null;
+}
 export interface CreatePartnerClaimSetRequest {
     name: string;
     tagType: ClaimSetTagType;

package/dist/types/nfc.d.ts

@@ -14,6 +14,10 @@ export interface NfcValidateRequest {
     claimSetId: string;
     codeId: string;
     mirror?: string;
+    /** NTAG 424 DNA: the encrypted PICC block from the tag's URL (`?p=`, 32 hex) */
+    d?: string;
+    /** NTAG 424 DNA: the tag's SDM MAC from its URL (`&c=`, 16 hex). Verified by the server when present; always forward it. */
+    c?: string;
     userId?: string;
 }
 export interface NfcValidateResponse {

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.1.11  |  Generated: 2026-11-08T09:25:58.482Z
+Version: 2.1.12  |  Generated: 2026-11-08T14:30:42.034Z
 
 This is a concise summary of all available API functions and types.
 
@@ -5894,6 +5894,17 @@ interface PartnerClaimSet {
 }
 ```
 
+**PartnerTagHit** (interface)
+```typescript
+interface PartnerTagHit {
+  namespace: string
+  claimSetId: string
+  set: PartnerClaimSet | null
+  tag: ClaimSetRangeTag & { url: string | null }
+  range: ClaimSetRange | null
+}
+```
+
 **CreatePartnerClaimSetRequest** (interface)
 ```typescript
 interface CreatePartnerClaimSetRequest {
@@ -9330,6 +9341,8 @@ interface NfcValidateRequest {
   claimSetId: string
   codeId: string
   mirror?: string
+  d?: string
+  c?: string
   userId?: string
 }
 ```
@@ -12327,21 +12340,9 @@ The range's tags in index order, a page at a time (keys: owners/admins only).
 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<`
+      params: { uid: string; data?: Record<string, unknown>; /** A plain (NTAG 21x) → `void`
 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>`
@@ -13270,6 +13271,9 @@ 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).
 
+**lookupTags**(partnerId: string, query: { uid?: string; code?: string }) → `Promise<PartnerTagHit[]>`
+Find a tag across the partner's sets by its chip UID (8 or 14 hex) or its code (printed or bare). Never returns keys.
+
 ### podcast
 
 **generate**(collectionId: string,

package/docs/tag-ranges.md

@@ -1,75 +1,77 @@
-# 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.
+# 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 })` (add `password` for a plain tag's write password).
+
+To find where a chip or code went, `partner.lookupTags(partner.id, { uid })` or `{ code }` searches every set the partner owns and returns each hit's set, tag and range, never a key.
+
+## 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/openapi.yaml

@@ -9141,6 +9141,45 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /admin/partner/{partnerId}/tags/lookup:
+    get:
+      tags:
+        - partner
+      summary: "Find a tag across the partner's sets by its chip UID (8 or 14 hex) or its code (printed or bare)."
+      operationId: partner_lookupTags
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: partnerId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: uid
+          in: query
+          required: false
+          schema:
+            type: string
+        - name: code
+          in: query
+          required: false
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/PartnerTagHit"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
   /authKit/{authKitId}/config:
     get:
       tags:
@@ -26120,6 +26159,25 @@ components:
         - codes
         - deleted
         - createdAt
+    PartnerTagHit:
+      type: object
+      properties:
+        namespace:
+          type: string
+        claimSetId:
+          type: string
+        set:
+          $ref: "#/components/schemas/PartnerClaimSet"
+        tag:
+          $ref: "#/components/schemas/ClaimSetRangeTag"
+        range:
+          $ref: "#/components/schemas/ClaimSetRange"
+      required:
+        - namespace
+        - claimSetId
+        - set
+        - tag
+        - range
     CreatePartnerClaimSetRequest:
       type: object
       properties:
@@ -31324,6 +31382,10 @@ components:
           type: string
         mirror:
           type: string
+        d:
+          type: string
+        c:
+          type: string
         userId:
           type: string
       required:

package/package.json

@@ -1,87 +1,87 @@
-{
-  "name": "@proveanything/smartlinks",
-  "version": "2.1.11",
-  "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
-  "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "default": "./dist/index.js"
-    },
-    "./testing": {
-      "types": "./dist/testing/index.d.ts",
-      "import": "./dist/testing/index.js",
-      "default": "./dist/testing/index.js"
-    },
-    "./*": {
-      "types": "./dist/*.d.ts",
-      "import": "./dist/*.js",
-      "default": "./dist/*.js"
-    },
-    "./baseline.css": "./dist/baseline.css",
-    "./baseline.classes.json": "./dist/baseline.classes.json",
-    "./theme.css": "./dist/theme.css",
-    "./theme-boot.js": "./dist/theme-boot.js",
-    "./package.json": "./package.json"
-  },
-  "bin": {
-    "smartlinks-register-release": "scripts/register-release.mjs",
-    "smartlinks-publish": "scripts/publish.mjs",
-    "smartlinks-doctor": "scripts/doctor.mjs",
-    "smartlinks-headless": "scripts/headless-check.mjs"
-  },
-  "files": [
-    "dist/",
-    "docs/",
-    "scripts/register-release.mjs",
-    "scripts/publish.mjs",
-    "scripts/doctor.mjs",
-    "scripts/headless-check.mjs",
-    "scripts/lib/",
-    "openapi.yaml",
-    "README.md"
-  ],
-  "scripts": {
-    "test": "node test/run.cjs",
-    "build": "tsc && node scripts/fix-esm-extensions.mjs && node generate-api-summary.cjs && node generate-openapi.cjs && node scripts/copy-docs-to-dist.cjs && node scripts/build-baseline.mjs",
-    "docs": "typedoc",
-    "docs:summary": "node generate-api-summary.cjs",
-    "docs:openapi": "node generate-openapi.cjs",
-    "docs:openapi:lint": "npx --yes @redocly/cli@latest lint openapi.yaml",
-    "docs:openapi:check": "node generate-openapi.cjs && npx --yes @redocly/cli@latest lint openapi.yaml",
-    "build:docs": "tsc build-docs.ts --outDir dist && node dist/build-docs.js",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "smartlinks",
-    "api",
-    "authentication",
-    "traceability",
-    "blockchain",
-    "typescript",
-    "sdk"
-  ],
-  "author": "Glenn Shoosmith",
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  },
-  "dependencies": {
-    "cross-fetch": "^3.1.5",
-    "es-module-lexer": "^1.7.0"
-  },
-  "devDependencies": {
-    "ts-node": "^10.9.1",
-    "typedoc": "^0.25.13",
-    "typedoc-plugin-markdown": "^3.17.1",
-    "typescript": "^4.9.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Prove-Anything/smartlinks.git"
-  },
-  "homepage": "https://smartlinks.app"
-}
+{
+  "name": "@proveanything/smartlinks",
+  "version": "2.1.12",
+  "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js",
+      "default": "./dist/testing/index.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
+    },
+    "./baseline.css": "./dist/baseline.css",
+    "./baseline.classes.json": "./dist/baseline.classes.json",
+    "./theme.css": "./dist/theme.css",
+    "./theme-boot.js": "./dist/theme-boot.js",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "smartlinks-register-release": "scripts/register-release.mjs",
+    "smartlinks-publish": "scripts/publish.mjs",
+    "smartlinks-doctor": "scripts/doctor.mjs",
+    "smartlinks-headless": "scripts/headless-check.mjs"
+  },
+  "files": [
+    "dist/",
+    "docs/",
+    "scripts/register-release.mjs",
+    "scripts/publish.mjs",
+    "scripts/doctor.mjs",
+    "scripts/headless-check.mjs",
+    "scripts/lib/",
+    "openapi.yaml",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node test/run.cjs",
+    "build": "tsc && node scripts/fix-esm-extensions.mjs && node generate-api-summary.cjs && node generate-openapi.cjs && node scripts/copy-docs-to-dist.cjs && node scripts/build-baseline.mjs",
+    "docs": "typedoc",
+    "docs:summary": "node generate-api-summary.cjs",
+    "docs:openapi": "node generate-openapi.cjs",
+    "docs:openapi:lint": "npx --yes @redocly/cli@latest lint openapi.yaml",
+    "docs:openapi:check": "node generate-openapi.cjs && npx --yes @redocly/cli@latest lint openapi.yaml",
+    "build:docs": "tsc build-docs.ts --outDir dist && node dist/build-docs.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "smartlinks",
+    "api",
+    "authentication",
+    "traceability",
+    "blockchain",
+    "typescript",
+    "sdk"
+  ],
+  "author": "Glenn Shoosmith",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "cross-fetch": "^3.1.5",
+    "es-module-lexer": "^1.7.0"
+  },
+  "devDependencies": {
+    "ts-node": "^10.9.1",
+    "typedoc": "^0.25.13",
+    "typedoc-plugin-markdown": "^3.17.1",
+    "typescript": "^4.9.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Prove-Anything/smartlinks.git"
+  },
+  "homepage": "https://smartlinks.app"
+}