@proveanything/smartlinks 2.1.11 → 2.1.13

package/dist/api/authKit.d.ts

@@ -1,4 +1,4 @@
-import type { AuthLoginResponse, AppleLoginOptions, RefreshResponse, LogoutResponse, PhoneSendCodeResponse, PhoneVerifyResponse, PasswordResetRequestResponse, VerifyResetTokenResponse, PasswordResetCompleteResponse, EmailVerificationActionResponse, EmailVerifyTokenResponse, AuthKitConfig, AuthKitConfigInput, AuthKitSetIdentityResponse, AuthKitInviteRequest, AuthKitInviteResponse, MagicLinkSendResponse, MagicLinkVerifyResponse, UserProfile, UpdateProfileResponse, ProfileUpdateData, SuccessResponse, SendWhatsAppRequest, SendWhatsAppResponse, ExchangeWhatsAppSessionResponse, VerifyWhatsAppResponse, WhatsAppStatusResponse, SendSmsVerifyRequest, SendSmsVerifyResponse, VerifySmsResponse, UpsertContactRequest, UpsertContactResponse, MfaChallengeSendResponse, MfaFinalizeResponse, MfaEnrollSendResponse, MfaTotpEnrollResponse, MfaEnrolledResponse, MfaFactor, MfaFactorsResponse, TrustedDevice } from "../types/authKit.js";
+import type { AuthLoginResponse, AppleLoginOptions, MicrosoftLoginOptions, RefreshResponse, LogoutResponse, PhoneSendCodeResponse, PhoneVerifyResponse, PasswordResetRequestResponse, VerifyResetTokenResponse, PasswordResetCompleteResponse, EmailVerificationActionResponse, EmailVerifyTokenResponse, AuthKitConfig, AuthKitConfigInput, AuthKitSetIdentityResponse, AuthKitInviteRequest, AuthKitInviteResponse, MagicLinkSendResponse, MagicLinkVerifyResponse, UserProfile, UpdateProfileResponse, ProfileUpdateData, SuccessResponse, SendWhatsAppRequest, SendWhatsAppResponse, ExchangeWhatsAppSessionResponse, VerifyWhatsAppResponse, WhatsAppStatusResponse, SendSmsVerifyRequest, SendSmsVerifyResponse, VerifySmsResponse, UpsertContactRequest, UpsertContactResponse, MfaChallengeSendResponse, MfaFinalizeResponse, MfaEnrollSendResponse, MfaTotpEnrollResponse, MfaEnrolledResponse, MfaFactor, MfaFactorsResponse, TrustedDevice } from "../types/authKit.js";
 /**
  * Namespace containing helper functions for the new AuthKit API.
  * Legacy collection-based authKit helpers retained (marked as *Legacy*).
@@ -93,6 +93,22 @@ export declare namespace authKit {
      * @see AppleLoginOptions
      */
     function appleLogin(clientId: string, identityToken: string, opts?: AppleLoginOptions): Promise<AuthLoginResponse>;
+    /**
+     * Sign in with Microsoft — work or school accounts from any organisation, and personal Microsoft
+     * accounts — via a Microsoft ID token (public). Mirrors {@link appleLogin}: on success the bearer
+     * token is stored and the cache invalidated.
+     *
+     * Get the ID token from Microsoft's sign-in (response_type `id_token`, scope `openid profile email`)
+     * against the app in the public config's `microsoftClientId`. A site on its own domain can't be a
+     * registered address of that app, so the SmartLinks sign-in UI opens SmartLinks' Microsoft sign-in
+     * page in a popup, which calls this with `opts.returnOrigin` and hands the result back.
+     *
+     * Notable error codes: `MISSING_MICROSOFT_TOKEN` (400), `MICROSOFT_AUTH_NOT_CONFIGURED` (400),
+     * `INVALID_MICROSOFT_TOKEN` (401), `MICROSOFT_ORIGIN_NOT_ALLOWED` (403), `NOT_IN_ORGANISATION` (403 —
+     * the login setup's {@link AuthKitAccess} rule), `ACCOUNT_EXISTS_UNVERIFIED` (409),
+     * `MICROSOFT_AUTH_FAILED` (500). Gated by step-up MFA like every sign-in.
+     */
+    function microsoftLogin(clientId: string, idToken: string, opts?: MicrosoftLoginOptions): Promise<AuthLoginResponse>;
     /**
      * Exchange a refresh token for a fresh access token (public — the refresh token IS
      * the credential). **Native sessions only**; refresh tokens are issued only when the

package/dist/api/authKit.js

@@ -139,6 +139,30 @@ export var authKit;
         return res;
     }
     authKit.appleLogin = appleLogin;
+    /**
+     * Sign in with Microsoft — work or school accounts from any organisation, and personal Microsoft
+     * accounts — via a Microsoft ID token (public). Mirrors {@link appleLogin}: on success the bearer
+     * token is stored and the cache invalidated.
+     *
+     * Get the ID token from Microsoft's sign-in (response_type `id_token`, scope `openid profile email`)
+     * against the app in the public config's `microsoftClientId`. A site on its own domain can't be a
+     * registered address of that app, so the SmartLinks sign-in UI opens SmartLinks' Microsoft sign-in
+     * page in a popup, which calls this with `opts.returnOrigin` and hands the result back.
+     *
+     * Notable error codes: `MISSING_MICROSOFT_TOKEN` (400), `MICROSOFT_AUTH_NOT_CONFIGURED` (400),
+     * `INVALID_MICROSOFT_TOKEN` (401), `MICROSOFT_ORIGIN_NOT_ALLOWED` (403), `NOT_IN_ORGANISATION` (403 —
+     * the login setup's {@link AuthKitAccess} rule), `ACCOUNT_EXISTS_UNVERIFIED` (409),
+     * `MICROSOFT_AUTH_FAILED` (500). Gated by step-up MFA like every sign-in.
+     */
+    async function microsoftLogin(clientId, idToken, opts) {
+        const res = await post(`/authkit/${encodeURIComponent(clientId)}/auth/microsoft`, Object.assign({ idToken }, opts));
+        if (res.token) {
+            setBearerToken(res.token);
+            invalidateCache();
+        }
+        return res;
+    }
+    authKit.microsoftLogin = microsoftLogin;
     /* ===================================
      * Native session refresh (public)
      * =================================== */

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.13  |  Generated: 2026-11-09T11:51:55.948Z
 
 This is a concise summary of all available API functions and types.
 
@@ -4624,6 +4624,24 @@ interface LogoutResponse {
 }
 ```
 
+**MicrosoftLoginOptions** (interface)
+```typescript
+interface MicrosoftLoginOptions {
+  returnOrigin?: string
+  trustedDeviceToken?: string
+}
+```
+
+**AuthKitAccess** (interface)
+```typescript
+interface AuthKitAccess {
+  mode: 'anyone' | 'organisation'
+  domains?: string[]
+  emails?: string[]
+  microsoftTenants?: Record<string, string>
+}
+```
+
 **AppleLoginOptions** (interface)
 ```typescript
 interface AppleLoginOptions {
@@ -4953,6 +4971,8 @@ interface AuthKitConfig {
   collectionIds?: string[]
   identity?: AuthKitIdentity
   signUp?: 'open' | 'invite'
+  access?: AuthKitAccess
+  microsoftClientId?: string
 }
 ```
 
@@ -5894,6 +5914,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 +9361,8 @@ interface NfcValidateRequest {
   claimSetId: string
   codeId: string
   mirror?: string
+  d?: string
+  c?: string
   userId?: string
 }
 ```
@@ -11924,6 +11957,9 @@ Sign in with LinkedIn (OpenID Connect) via a server-side authorization code (pub
 **appleLogin**(clientId: string, identityToken: string, opts?: AppleLoginOptions) → `Promise<AuthLoginResponse>`
 Sign in with Apple via an Apple identity token (public). Mirrors {@link googleLogin}. On success the returned bearer token is stored automatically and the cache is invalidated. Notable error codes (thrown as `SmartlinksApiError`, read via `err.errorCode`): - `MISSING_APPLE_TOKEN` (400), `APPLE_AUTH_NOT_CONFIGURED` (400), `INVALID_APPLE_TOKEN` (401), `APPLE_AUTH_FAILED` (500) - `ACCOUNT_EXISTS_UNVERIFIED` (409) — an unverified account already owns this email; the server refuses to silently link. `err.details.requiresEmailVerification` is `true`. Recoverable: the user should sign in with their password (or reset it), then link Apple from settings. **The same 409 can now come back from {@link googleLogin}** under the shared verified-to-verified linking policy. Gated by step-up MFA — see {@link login} for the `MFA_REQUIRED` error shape. Pass `opts.trustedDeviceToken` to skip the challenge on a recognized device.
 
+**microsoftLogin**(clientId: string, idToken: string, opts?: MicrosoftLoginOptions) → `Promise<AuthLoginResponse>`
+Sign in with Microsoft — work or school accounts from any organisation, and personal Microsoft accounts — via a Microsoft ID token (public). Mirrors {@link appleLogin}: on success the bearer token is stored and the cache invalidated. Get the ID token from Microsoft's sign-in (response_type `id_token`, scope `openid profile email`) against the app in the public config's `microsoftClientId`. A site on its own domain can't be a registered address of that app, so the SmartLinks sign-in UI opens SmartLinks' Microsoft sign-in page in a popup, which calls this with `opts.returnOrigin` and hands the result back. Notable error codes: `MISSING_MICROSOFT_TOKEN` (400), `MICROSOFT_AUTH_NOT_CONFIGURED` (400), `INVALID_MICROSOFT_TOKEN` (401), `MICROSOFT_ORIGIN_NOT_ALLOWED` (403), `NOT_IN_ORGANISATION` (403 — the login setup's {@link AuthKitAccess} rule), `ACCOUNT_EXISTS_UNVERIFIED` (409), `MICROSOFT_AUTH_FAILED` (500). Gated by step-up MFA like every sign-in.
+
 **refreshToken**(clientId: string, refreshToken: string) → `Promise<RefreshResponse>`
 Exchange a refresh token for a fresh access token (public — the refresh token IS the credential). **Native sessions only**; refresh tokens are issued only when the host opted in via `initializeApi({ platform: 'native' })`. On success the new access token is stored automatically (`setBearerToken`). The returned `refreshToken` is **rotated** — the caller must persist it and discard the old one before refreshing again. ⚠️ **Single-use, no retry, serialize calls.** This method issues exactly one request and never retries: replaying a consumed refresh token triggers `REFRESH_TOKEN_REUSE_DETECTED` (the whole session family is revoked). The caller is responsible for ensuring only one refresh is in flight at a time (e.g. across tabs or resume events). Errors (thrown as `SmartlinksApiError`, read via `err.errorCode`): `MISSING_REFRESH_TOKEN` (400), `INVALID_REFRESH_TOKEN` (401), `REFRESH_TOKEN_REUSE_DETECTED` (401) — the last two mean a hard logout.
 
@@ -12327,21 +12363,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 +13294,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/auth-kit.md

@@ -259,6 +259,56 @@ try {
 > ⚠️ This is a behaviour change for `googleLogin`, which previously merged silently in
 > this case. Handle the 409 for both methods.
 
+### Sign in with Microsoft
+
+Work or school accounts from **any** organisation, and personal Microsoft accounts (Outlook, Hotmail,
+Live). Add `'microsoft'` to `enabledProviders` — that's all: SmartLinks' own Microsoft app serves every
+organisation, so neither you nor your users' IT registers anything.
+
+```ts
+const session = await authKit.microsoftLogin(clientId, microsoftIdToken, { returnOrigin });
+```
+
+- **In the SmartLinks sign-in UI** the Microsoft button opens SmartLinks' Microsoft sign-in page
+  (`https://smartlinks.app/apps/account/stable/microsoft-proxy.html`) in a popup — the one address
+  registered with Microsoft — which signs in and hands the session back to your site. Your site must be
+  one of the login setup's own (its collections' domains or site addresses, or `allowedRedirectDomains`),
+  else `MICROSOFT_ORIGIN_NOT_ALLOWED` (403).
+- **Your own UI:** get an ID token from Microsoft (`response_type=id_token`, scope `openid profile email`,
+  authority `https://login.microsoftonline.com/common`) for the app in the public config's
+  `microsoftClientId`, and pass it here.
+- **Some companies' IT approves new apps for their staff.** The first person from such a company sees
+  "needs admin approval"; their IT approves SmartLinks once for the organisation and everyone can sign in.
+- **Your own name on Microsoft's screen (optional):** register your own *multitenant* app in Microsoft
+  Entra (Supported account types: any organisation + personal accounts; Web redirect URI as above, with
+  "ID tokens" ticked; token configuration: optional claim `xms_edov` on the ID token) and set its
+  Application (client) ID as `microsoftClientId`.
+- A Microsoft account's email is trusted only when Microsoft vouches that its organisation owns the
+  domain (or for personal accounts): an organisation can give its users any address. Linking to an
+  existing account by email follows the same verified-to-verified rule as Google and Apple.
+
+### Who can sign in (`access`)
+
+Restrict a login setup to one organisation — no keys, no IT:
+
+```ts
+await authKit.update(collectionId, clientId, {
+  access: { mode: 'organisation', domains: ['acme.com'], emails: ['contractor@gmail.com'] },
+});
+```
+
+- Someone is from acme.com when their **verified** email is at acme.com, they're one of `emails`, or they
+  signed in with Microsoft from acme's own Microsoft organisation (looked up from the domain when you
+  save — `microsoftTenants` is filled in for you).
+- Checked on **every** sign-in method each time a session is issued: everyone else gets
+  `NOT_IN_ORGANISATION` (403) with a message naming the domain. Tighten the rule and people already in
+  are refused from their next sign-in.
+- `register` refuses outside addresses before making anything, and never signs an unverified address
+  straight in (even in `immediate` mode) — it must be verified first.
+- Phone-only and WhatsApp-only accounts have no email to prove an organisation, so they can't get in.
+- The public config (`load`) returns `access: { mode, domains }` so your page can say who it's for; the
+  `emails` list is never public. `{ mode: 'anyone' }` (or no `access`) lets everyone in, as before.
+
 ### Refresh tokens (native sessions)
 
 Native/Capacitor hosts can hold long-lived sessions via refresh tokens. Opt in **once**

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:
@@ -9602,6 +9641,38 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /authkit/{clientId}/auth/microsoft:
+    post:
+      tags:
+        - authKit
+      summary: authKit.microsoftLogin
+      operationId: authKit_microsoftLogin
+      security: []
+      parameters:
+        - name: clientId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AuthLoginResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/MicrosoftLoginOptions"
   /authkit/{clientId}/auth/phone/send-code:
     post:
       tags:
@@ -23894,6 +23965,35 @@ components:
           additionalProperties: true
       required:
         - success
+    MicrosoftLoginOptions:
+      type: object
+      properties:
+        returnOrigin:
+          type: string
+        trustedDeviceToken:
+          type: string
+    AuthKitAccess:
+      type: object
+      properties:
+        mode:
+          type: string
+          enum:
+            - anyone
+            - organisation
+        domains:
+          type: array
+          items:
+            type: string
+        emails:
+          type: array
+          items:
+            type: string
+        microsoftTenants:
+          type: object
+          additionalProperties:
+            type: string
+      required:
+        - mode
     AppleLoginOptions:
       type: object
       properties:
@@ -24410,6 +24510,10 @@ components:
           enum:
             - open
             - invite
+        access:
+          $ref: "#/components/schemas/AuthKitAccess"
+        microsoftClientId:
+          type: string
       required:
         - id
     AuthKitInviteRequest:
@@ -24542,6 +24646,7 @@ components:
         - ACCOUNT_EXISTS_UNVERIFIED
         - APPLE_AUTH_FAILED
         - SIGN_UP_CLOSED
+        - NOT_IN_ORGANISATION
     MfaFactor:
       type: string
       enum:
@@ -26120,6 +26225,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 +31448,10 @@ components:
           type: string
         mirror:
           type: string
+        d:
+          type: string
+        c:
+          type: string
         userId:
           type: string
       required: