@proveanything/smartlinks 1.9.20 → 1.9.22

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.9.20  |  Generated: 2026-04-17T10:13:30.466Z
+Version: 1.9.22  |  Generated: 2026-04-25T11:11:00.344Z
 
 This is a concise summary of all available API functions and types.
 
@@ -2994,6 +2994,8 @@ interface Collection {
   secondaryColor?: string
   portalUrl?: string // URL for the collection's portal (if applicable)
   allowAutoGenerateClaims?: boolean
+  variants: boolean // does this collection support variants?
+  batches: boolean // does this collection support batches?
   defaultAuthKitId: string // default auth kit for this collection, used for auth
 }
 ```

package/dist/docs/app-manifest.md

@@ -95,7 +95,20 @@ The manifest is loaded automatically by the platform for every collection page.
     { "title": "Home",     "path": "/" },
     { "title": "Gallery",  "path": "/gallery" },
     { "title": "Settings", "path": "/settings", "params": { "tab": "advanced" } }
-  ]
+  ],
+
+  "records": {
+    "nutrition": {
+      "scopes": ["product", "facet", "batch"],
+      "defaultScope": "facet",
+      "label": "Nutrition info"
+    },
+    "cooking_steps": {
+      "scopes": ["product", "facet"],
+      "defaultScope": "product",
+      "label": "Cooking steps"
+    }
+  }
 }
 ```
 
@@ -188,6 +201,30 @@ See the [Deep Link Discovery guide](deep-link-discovery.md) for the full dual-so
 | `path` | string | ❌ | Hash route within the app (defaults to `"/"` if omitted) |
 | `params` | object | ❌ | App-specific query params appended to the URL — do **not** include platform params (`collectionId`, `productId`, etc.) |
 
+#### `records`
+
+Declares which `app.records` record types the app stores, and which scopes each type supports. Required for any app that follows the [Records-Based Admin Pattern](records-admin-pattern.md). Omit if the app does not use scoped records.
+
+The platform and the `<RecordsAdminShell>` from `@proveanything/ui-utils` read this block to render only the relevant tabs and affordances.
+
+```json
+"records": {
+  "<recordType>": {
+    "scopes": ["product", "facet", "batch"],
+    "defaultScope": "facet",
+    "label": "Human-readable label"
+  }
+}
+```
+
+| Field          | Type     | Required | Description |
+|----------------|----------|----------|-------------|
+| `scopes`       | string[] | ✅ | Allowed scope kinds in resolution order. Valid values: `"product"`, `"variant"`, `"batch"`, `"facet"`, `"proof"`, `"default"`. |
+| `defaultScope` | string   | ✅ | The scope the "Create new" button targets in the admin shell. Must be one of the declared `scopes`. |
+| `label`        | string   | ✅ | Human-readable label for the record type, used in headings and tabs. |
+
+An app may declare multiple record types under different keys (e.g. `"nutrition"` and `"cooking_steps"`).
+
 #### `executor`
 
 Declares the executor bundle — a standalone JS library for programmatic configuration, server-side SEO, and LLM content generation. Omit if the app has no executor.

package/dist/docs/auth-kit.md

@@ -0,0 +1,162 @@
+# SmartLinks Auth Kit (`@proveanything/smartlinks` — `authKit` namespace)
+
+> End-user authentication flows for SmartLinks microapps. Covers email/password, magic links, phone OTP, Google OAuth, profile management, and password/email change flows.
+>
+> **This is part of the core SDK** — no separate install required. Import from `@proveanything/smartlinks`.
+
+---
+
+## What is Auth Kit for?
+
+Auth Kit is the **end-user identity layer** for microapps that need users to sign in. It is distinct from the admin/platform authentication (Bearer tokens) used to call admin endpoints.
+
+Use Auth Kit when:
+- Your app has a login/register screen for end users (not collection admins)
+- You need to gate features behind a verified user identity
+- You want to store user-specific data with the `userAppData` API (see [app-data-storage.md](app-data-storage.md))
+
+Do **not** use Auth Kit for:
+- Admin-side API calls (those use Bearer tokens set by the platform shell)
+- Claiming proofs (see proof claiming methods)
+
+---
+
+## Setup: creating an Auth Kit client
+
+Each app requires an Auth Kit configuration, created by a collection admin:
+
+```ts
+// Admin setup (one-time, done in admin console)
+import { authKit } from '@proveanything/smartlinks';
+
+// Returns an authKitId to store in your app config
+const config = await authKit.create(collectionId, {
+  name: 'My App Auth',
+  loginMethods: ['email', 'google', 'magic_link'],
+  redirectUrl: 'https://myapp.example.com/auth/callback',
+});
+```
+
+---
+
+## Key flows
+
+### Email / password
+
+```ts
+import { authKit } from '@proveanything/smartlinks';
+
+// Register
+const session = await authKit.register(clientId, {
+  email: 'user@example.com',
+  password: 'securePassword123',
+  displayName: 'Alice',
+});
+
+// Login
+const session = await authKit.login(clientId, 'user@example.com', 'securePassword123');
+
+// session.token — store this; pass to initializeApi for subsequent calls
+```
+
+### Magic link (passwordless email)
+
+```ts
+await authKit.sendMagicLink(clientId, {
+  email: 'user@example.com',
+  redirectUrl: 'https://myapp.example.com/auth/verify',
+});
+
+// On callback page, extract token from URL and verify
+const session = await authKit.verifyMagicLink(clientId, tokenFromUrl);
+```
+
+### Phone OTP
+
+```ts
+await authKit.sendPhoneCode(clientId, '+61400000000');
+const session = await authKit.verifyPhoneCode(clientId, '+61400000000', '123456');
+```
+
+### Google OAuth
+
+```ts
+// After Google sign-in, pass the id_token to Auth Kit
+const session = await authKit.googleLogin(clientId, googleIdToken);
+```
+
+---
+
+## Profile management
+
+```ts
+import { authKit } from '@proveanything/smartlinks';
+
+// Get current user's profile
+const profile = await authKit.getProfile(clientId);
+
+// Update profile
+await authKit.updateProfile(clientId, { displayName: 'Alice B.', avatarUrl: '...' });
+
+// Change password
+await authKit.changePassword(clientId, 'currentPass', 'newPass');
+
+// Change email (triggers verification)
+await authKit.changeEmail(clientId, 'newemail@example.com', 'password', redirectUrl);
+
+// Delete account
+await authKit.deleteAccount(clientId, 'password', 'DELETE');
+```
+
+---
+
+## Email verification
+
+Auth Kit can send and verify email addresses after registration:
+
+```ts
+await authKit.sendEmailVerification(clientId, {
+  userId,
+  email: 'user@example.com',
+  redirectUrl: 'https://myapp.example.com/auth/verified',
+});
+
+// On callback page
+await authKit.verifyEmail(clientId, tokenFromUrl);
+```
+
+---
+
+## Password reset
+
+```ts
+await authKit.requestPasswordReset(clientId, {
+  email: 'user@example.com',
+  redirectUrl: 'https://myapp.example.com/auth/reset',
+  clientName: 'My App',
+});
+
+// On reset page — verify token is still valid before showing the form
+await authKit.verifyResetToken(clientId, tokenFromUrl);
+
+// Complete reset
+await authKit.completePasswordReset(clientId, tokenFromUrl, 'newSecurePassword');
+```
+
+---
+
+## Relationship to other parts of the SDK
+
+| Concern | Where it lives |
+|---------|---------------|
+| End-user sign-in / register | `authKit` namespace (this doc) |
+| Admin Bearer token auth | Platform shell — not set by your app |
+| Per-user data storage | `userAppData` namespace — see [app-data-storage.md](app-data-storage.md) |
+| User identity in analytics | `userId` field on `analytics` and `interactions` calls |
+
+---
+
+## Further reading
+
+- [app-data-storage.md](app-data-storage.md) — storing user-specific data after login
+- [app-manifest.md](app-manifest.md) — `app.admin.json` setup questions for configuring `clientId`

package/dist/docs/forms.md

@@ -0,0 +1,113 @@
+# SmartLinks Forms
+
+> Platform-managed form definitions and submissions. Covers the `form` data API (core SDK) and the `@proveanything/ui-forms` React package for schema-driven form UIs.
+
+---
+
+## Two layers
+
+| Layer | Package | What it does |
+|-------|---------|--------------|
+| **Forms data API** | `@proveanything/smartlinks` (`form` namespace) | CRUD for form definitions; stores submission schema |
+| **Forms UI** | `@proveanything/ui-forms` | React components that render a form definition, validate input, and submit |
+
+You can use the data API without the UI package (e.g. in an executor), but the UI package requires both.
+
+---
+
+## Forms data API (`form` namespace)
+
+The `form` namespace in the core SDK manages **form definitions** — the schema that describes fields, validation rules, and submission behaviour. This is an admin-side API.
+
+```ts
+import { form } from '@proveanything/smartlinks';
+
+// List all forms in a collection
+const forms = await form.list(collectionId, /* admin= */ true);
+
+// Get a specific form
+const myForm = await form.get(collectionId, formId);
+
+// Create a form (admin)
+const created = await form.create(collectionId, {
+  name: 'Warranty Registration',
+  fields: [
+    { id: 'name',    type: 'text',  label: 'Full name',       required: true },
+    { id: 'email',   type: 'email', label: 'Email address',   required: true },
+    { id: 'serial',  type: 'text',  label: 'Serial number',   required: true },
+    { id: 'receipt', type: 'file',  label: 'Proof of purchase' },
+  ],
+});
+
+// Update a form (admin)
+await form.update(collectionId, formId, { name: 'Warranty Registration v2' });
+
+// Delete a form (admin)
+await form.remove(collectionId, formId);
+```
+
+Form definitions are stored per-collection and referenced by `formId`.
+
+---
+
+## Forms UI (`@proveanything/ui-forms`)
+
+`@proveanything/ui-forms` provides React components that consume a form definition from the API and render a complete, accessible, validated form.
+
+Install: `npm install @proveanything/ui-forms`
+
+### Rendering a form
+
+```tsx
+import { SmartForm } from '@proveanything/ui-forms';
+
+// Fetches the form definition and renders it
+<SmartForm
+  collectionId={collectionId}
+  formId={formId}
+  onSubmit={async (values) => {
+    // handle submission — e.g. create an app.records entry or send via comms
+  }}
+/>
+```
+
+### Headless usage
+
+```tsx
+import { useFormDefinition, FormRenderer } from '@proveanything/ui-forms';
+
+const { fields, isLoading } = useFormDefinition(collectionId, formId);
+
+// Render fields yourself using the definition
+```
+
+---
+
+## Common patterns
+
+### Warranty / registration forms
+
+Define the form in `app.admin.json` setup or via the admin API. On the public widget, render with `<SmartForm>` and on submit create an `app.records` entry:
+
+```ts
+onSubmit={async (values) => {
+  await app.records.create(collectionId, appId, {
+    recordType: 'warranty_registration',
+    ref: `proof:${proofId}`,
+    data: values,
+  });
+}}
+```
+
+### Competition / feedback forms
+
+Same pattern — use `<SmartForm>` for capture and write to `app.records` or trigger an `interactions.appendEvent` on submit.
+
+---
+
+## Further reading
+
+- [app-objects.md](app-objects.md) — `app.records` for storing submissions
+- [app-data-storage.md](app-data-storage.md) — choosing the right storage model
+- [interactions.md](interactions.md) — firing events on form submission
+- [comms.md](comms.md) — sending confirmation emails after submission

package/dist/docs/overview.md

@@ -64,6 +64,10 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **Liquid Templates** | `docs/liquid-templates.md` | Dynamic content rendering with LiquidJS |
 | **Iframe Responder** | `docs/iframe-responder.md` | Iframe communication and proxy mode internals |
 | **AI Guide Template** | `docs/ai-guide-template.md` | Template for creating `public/ai-guide.md` — customise per app |
+| **Forms** | `docs/forms.md` | Form definitions, schema-driven rendering, submission patterns |
+| **Auth Kit** | `docs/auth-kit.md` | End-user sign-in: email/password, magic links, phone OTP, Google OAuth |
+| **Records Admin Pattern** | `docs/records-admin-pattern.md` | Standard pattern for per-product/facet/variant/batch admin UIs |
+| **UI Utils** | `docs/ui-utils.md` | `@proveanything/smartlinks-utils-ui` — React shells, hooks, and primitives for records-based apps |
 
 ---
 

package/dist/docs/records-admin-pattern.md

@@ -0,0 +1,315 @@
+# SmartLinks Records-Based Admin Pattern
+
+> Canonical guide for building admin UIs in microapps that store **per-product**, **per-facet**, **per-variant** or **per-batch** data.
+>
+> Audience: microapp developers (nutrition, allergy, ingredients, cooking-guide, warranty, provenance, …).
+>
+> Status: **standard** — new admin apps in this category MUST follow this contract. Existing apps SHOULD migrate.
+
+---
+
+## 1. Why a shared pattern?
+
+Many SmartLinks microapps store **structured data that varies along one or more product axes**:
+
+| App              | Varies by                                      |
+|------------------|------------------------------------------------|
+| Nutrition        | product, facet (bread type, region), batch     |
+| Allergy          | product, facet (recipe family)                 |
+| Ingredients      | product, variant (size), batch (production run)|
+| Cooking guide    | product, facet (cut of meat)                   |
+| Warranty         | product, variant, batch                        |
+| Provenance       | batch                                          |
+
+Without a shared pattern, every app reinvents:
+
+- the left-rail "browse + select" list
+- the per-axis precedence rules
+- the inheritance/override UI
+- the "no data yet" empty state
+- CSV import/export
+- bulk operations
+
+The result is drift: each app feels different and admins have to re-learn the model. This guide locks the model down at the SDK level so the matching UI primitives in `@proveanything/ui-utils` (see the [companion guide](ui-utils.md)) can stay simple.
+
+---
+
+## 2. Storage model: `app.records`
+
+**Do not** stuff per-axis data into `appConfiguration.products[productId]`. Use `app.records` (recordType-keyed) so that data is queryable, paginatable and survives schema changes.
+
+```ts
+import { app } from '@proveanything/smartlinks';
+
+await app.records.create(collectionId, appId, {
+  recordType: 'nutrition',          // app-defined, stable
+  ref: 'product:prod_abc',           // see §3
+  data: { /* domain payload */ },
+}, /* admin= */ true);
+```
+
+Each record has:
+
+| Field        | Purpose                                                     |
+|--------------|-------------------------------------------------------------|
+| `recordType` | Namespaces records inside the app. One app may have several (`nutrition`, `cooking_steps`). |
+| `ref`        | Encodes the **scope** of the record. See §3.                |
+| `data`       | The domain payload. Free-form per app.                      |
+| `meta`       | Reserved for system fields (timestamps, author).            |
+
+> **Rule:** `(appId, recordType, ref)` is unique. Treat it as the natural key.
+
+---
+
+## 3. The `ref` convention (REQUIRED)
+
+`ref` is a colon-delimited string that encodes which scope a record applies to. Standardising it is what makes the shared admin shell possible.
+
+```
+product:<productId>
+variant:<productId>:<variantId>
+batch:<productId>:<batchId>
+proof:<proofId>
+facet:<facetKey>:<valueKey>
+default
+```
+
+Notes:
+
+- Variants and batches are **always nested under a product** in the SDK, so their refs include `productId`.
+- `facet:` refs are **collection-wide** — facets cross products by design.
+- `default` is a single record per (app, recordType) used as the global fallback.
+- Refs are opaque to the SDK. Apps parse them. A helper module (`@proveanything/smartlinks-utils-ui/records-admin`) exports `parseRef`/`buildRef` so all apps agree on syntax. See Appendix A for the full implementation.
+
+### Adding scopes later
+
+If a new axis appears (e.g. `region:eu`), pick a new prefix and document it. Never reuse a prefix with different semantics.
+
+---
+
+## 4. Resolution order (REQUIRED)
+
+When the **public** side of an app needs "the data that applies to this proof / product / context", it walks the chain from most-specific to least-specific and returns the first match:
+
+```
+proof → batch → variant → product → facet(*) → default
+```
+
+`facet(*)` means: walk every facet attached to the product in a deterministic order (alphabetical by `facetKey`, then `valueKey`) and use the first matching facet record.
+
+> **Rule:** Resolution is **first-match-wins, not merge**. If you need field-level merging, build it on top with explicit `inheritsFrom` markers in the payload — but the default for shared infra is whole-record replacement, because it is far easier to reason about.
+
+The canonical resolver lives in `@proveanything/smartlinks-utils-ui/records-admin` so every app behaves identically:
+
+```ts
+import { resolveRecord } from '@proveanything/smartlinks-utils-ui/records-admin';
+
+const resolved = await resolveRecord({
+  appId,
+  recordType: 'nutrition',
+  scope: { collectionId, productId, variantId, batchId, proofId },
+});
+// → { record, source: 'variant' | 'product' | 'facet' | … } | null
+```
+
+Apps that only support a subset of scopes pass `supportedScopes: ['product', 'facet']` and the resolver skips the rest.
+
+---
+
+## 5. Scope capabilities (declared per app)
+
+An app declares which scopes it accepts records for in `app.manifest.json`. This drives the admin UI and avoids dead tabs:
+
+```json
+// app.manifest.json (extension)
+{
+  "records": {
+    "nutrition": {
+      "scopes": ["product", "facet", "batch"],
+      "defaultScope": "facet",
+      "label": "Nutrition info"
+    }
+  }
+}
+```
+
+| Field          | Meaning                                                        |
+|----------------|----------------------------------------------------------------|
+| `scopes`       | Allowed scope kinds, in **resolution order**.                  |
+| `defaultScope` | Where the "Create new" button lands in the admin shell.        |
+| `label`        | Human-readable label for the record type (used in headings).   |
+
+The shared admin shell reads this manifest entry and renders only the relevant tabs. Apps don't hard-code tab lists.
+
+See [app-manifest.md](app-manifest.md) for the full schema reference.
+
+---
+
+## 6. Discovering whether variants / batches are in use
+
+The `Collection` object exposes top-level `variants: boolean` and `batches: boolean` flags that indicate whether the collection has these features enabled. Read them directly rather than probing by listing:
+
+```ts
+import { appConfiguration } from '@proveanything/smartlinks';
+
+const collection = await appConfiguration.getCollection(collectionId);
+
+const showVariantTab = collection.variants && scopeConfig?.scopes.includes('variant') === true;
+const showBatchTab   = collection.batches  && scopeConfig?.scopes.includes('batch') === true;
+```
+
+`scopeConfig` is the parsed manifest `records` entry for this `recordType` — e.g. `manifest.records?.nutrition`.
+
+Rules:
+
+1. If the collection has the feature **and** the app **declares** support for the scope, show the tab and offer "Add variant" / "Add batch" affordances.
+2. If the app does **not** declare support, hide the tab entirely even if `collection.variants` is true (another app created them).
+3. If the collection does not have the feature enabled, hide the tab even if the app declares support.
+
+---
+
+## 7. Inheritance & overrides
+
+Because resolution is first-match-wins, the admin UI must make inheritance **visible**:
+
+- When editing a **variant** record, show the **product** record as the inherited baseline.
+- Each field in the editor displays a small **↩ "Inherited"** marker when its value matches the parent and **● "Override"** when it differs.
+- A row-level "Reset to inherited" action removes the override (deletes the record at the current scope if all overrides are reset).
+
+Apps don't have to implement this themselves — the `<RecordEditor>` primitive in `@proveanything/smartlinks-utils-ui` does it given the resolved parent payload.
+
+---
+
+## 8. Bulk operations
+
+Standard verbs every shell should expose:
+
+| Verb              | Behaviour                                                            |
+|-------------------|----------------------------------------------------------------------|
+| **Apply to many** | Take the current record's payload, write it to N selected products / variants. |
+| **Copy from**     | Pick a source scope, copy its payload to the current scope.          |
+| **Clear**         | Delete records at the current scope (children unaffected).           |
+
+Use the `bulkUpsert` / `bulkDelete` helpers from `@proveanything/smartlinks-utils-ui/records-admin`, which handle batching and error collection for you:
+
+```ts
+import { bulkUpsert, bulkDelete } from '@proveanything/smartlinks-utils-ui/records-admin';
+
+// Apply current payload to many refs
+await bulkUpsert({ SL, collectionId, appId, recordType, refs: targetRefs, data: payload });
+
+// Clear records at selected refs
+await bulkDelete({ SL, collectionId, appId, recordType, refs: targetRefs });
+```
+
+If you are using `<RecordsAdminShell>`, the bulk actions menu is included and wired automatically via the `onTelemetry` hook — you don't call these directly unless you're building a custom shell.
+
+---
+
+## 9. CSV import / export
+
+Adopt this column shape across all records-based apps:
+
+```
+scope,scopeRef,<field1>,<field2>,...
+product,prod_abc,250,12.5,...
+variant,prod_abc/var_500ml,260,12.5,...
+batch,prod_abc/B-2024-03,255,12.5,...
+facet,bread_type/sourdough,240,11.0,...
+```
+
+- `scope` is the kind; `scopeRef` is the human-readable reference (the shell maps it to the canonical `ref`).
+- Validation errors return a downloadable annotated CSV with an `error` column appended.
+- Round-tripping (export → reimport unchanged) MUST be a no-op.
+
+---
+
+## 10. Public-side hook contract
+
+To keep widgets consistent across apps, expose one hook per record type (implemented in `@proveanything/ui-utils`):
+
+```ts
+import { useResolvedRecord } from '@proveanything/smartlinks-utils-ui/records-admin';
+
+const { data, source, isLoading } = useResolvedRecord({
+  appId,
+  recordType: 'nutrition',
+  // any combination of these — the hook walks the chain:
+  collectionId, productId, variantId, batchId, proofId,
+});
+```
+
+`source` is one of `'proof' | 'batch' | 'variant' | 'product' | 'facet' | 'default' | null`. UI can show a badge ("Showing batch-specific values") when useful.
+
+---
+
+## 11. Telemetry
+
+All admin shells emit these events. The `<RecordsAdminShell>` from `@proveanything/ui-utils` wires them automatically using `interactions.appendEvent` from the SDK — apps don't call this themselves.
+
+| Event                  | Props                                                |
+|------------------------|------------------------------------------------------|
+| `record.opened`        | `appId, recordType, ref, source`                     |
+| `record.saved`         | `appId, recordType, ref, fieldsChanged`              |
+| `record.deleted`       | `appId, recordType, ref`                             |
+| `record.bulkApplied`   | `appId, recordType, sourceRef, targetCount`          |
+| `record.imported`      | `appId, recordType, rows, errors`                    |
+
+---
+
+## 12. Required reading for app authors
+
+1. This document.
+2. The companion **[UI utils guide](ui-utils.md)** — explains the React primitives (`<RecordsAdminShell>`, `useResolvedRecord`, etc.) that implement this pattern.
+3. [PRODUCT_FACETS_SDK.md](PRODUCT_FACETS_SDK.md) — facet model.
+4. [app-data-storage.md](app-data-storage.md) — `app.records` surface.
+
+## 13. Migration checklist for existing apps
+
+- [ ] Stop writing per-product data into `appConfiguration`.
+- [ ] Move to `app.records` with `recordType` + `ref`.
+- [ ] Adopt the `ref` syntax in §3.
+- [ ] Add a `records` block to `app.manifest.json`.
+- [ ] Replace bespoke admin browser with `<RecordsAdminShell>` from `@proveanything/smartlinks-utils-ui`.
+- [ ] Replace bespoke public hook with `useResolvedRecord`.
+- [ ] Remove any "is variants enabled?" config — use `collection.variants` / `collection.batches` flags instead (§6).
+
+---
+
+## Appendix A — `ref` parser reference
+
+This is the canonical implementation. Copy it into your app or import from `@proveanything/ui-utils/records`.
+
+```ts
+type ParsedRef =
+  | { kind: 'default' }
+  | { kind: 'product'; productId: string }
+  | { kind: 'variant'; productId: string; variantId: string }
+  | { kind: 'batch';   productId: string; batchId: string }
+  | { kind: 'proof';   proofId: string }
+  | { kind: 'facet';   facetKey: string; valueKey: string };
+
+export const buildRef = (p: ParsedRef): string => {
+  switch (p.kind) {
+    case 'default': return 'default';
+    case 'product': return `product:${p.productId}`;
+    case 'variant': return `variant:${p.productId}:${p.variantId}`;
+    case 'batch':   return `batch:${p.productId}:${p.batchId}`;
+    case 'proof':   return `proof:${p.proofId}`;
+    case 'facet':   return `facet:${p.facetKey}:${p.valueKey}`;
+  }
+};
+
+export const parseRef = (ref: string): ParsedRef | null => {
+  if (ref === 'default') return { kind: 'default' };
+  const [head, ...rest] = ref.split(':');
+  switch (head) {
+    case 'product': return rest.length === 1 ? { kind: 'product', productId: rest[0] } : null;
+    case 'variant': return rest.length === 2 ? { kind: 'variant', productId: rest[0], variantId: rest[1] } : null;
+    case 'batch':   return rest.length === 2 ? { kind: 'batch',   productId: rest[0], batchId:   rest[1] } : null;
+    case 'proof':   return rest.length === 1 ? { kind: 'proof',   proofId:   rest[0] } : null;
+    case 'facet':   return rest.length >= 2  ? { kind: 'facet',   facetKey:  rest[0], valueKey:  rest.slice(1).join(':') } : null;
+    default: return null;
+  }
+};
+```