@proveanything/smartlinks 1.9.20 → 1.9.21

package/docs/records-admin-pattern.md

@@ -0,0 +1,324 @@
+# 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/ui-utils/records`) 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/ui-utils/records` so every app behaves identically:
+
+```ts
+import { resolveRecord } from '@proveanything/ui-utils/records';
+
+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 SDK does **not** expose a `collection.variantsEnabled` flag, by design. Whether a product has variants/batches is an **emergent** property: it has them iff someone created some.
+
+The standard probe pattern:
+
+```ts
+import { variant, batch } from '@proveanything/smartlinks';
+
+const [variants, batches] = await Promise.all([
+  variant.list(collectionId, productId).catch(() => []),
+  batch.list(collectionId, productId).catch(() => []),
+]);
+
+// scopeConfig is the parsed manifest records entry for this recordType
+// e.g. manifest.records?.nutrition → { scopes: ['product', 'facet', 'batch'], ... }
+const showVariantTab = variants.length > 0 || scopeConfig?.scopes.includes('variant') === true;
+const showBatchTab   = batches.length  > 0 || scopeConfig?.scopes.includes('batch') === true;
+```
+
+Rules:
+
+1. If the app **declares** support for the scope, always offer "Add variant" / "Add batch" affordances even when the list is empty.
+2. If the app does **not** declare support, hide the tab entirely even if some exist (another app created them).
+3. Cache list results per `(collectionId, productId)` with a short TTL — the shell will hit them often.
+
+---
+
+## 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/ui-utils` 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).           |
+
+The SDK does not currently expose a bulk write endpoint for records. Implement these by fanning out individual `app.records.create` / `app.records.update` calls with bounded concurrency (e.g. 10 in-flight at a time):
+
+```ts
+import { app } from '@proveanything/smartlinks';
+
+// fan-out with concurrency cap
+const chunks = chunkArray(targetRefs, 10);
+for (const chunk of chunks) {
+  await Promise.all(
+    chunk.map((ref) =>
+      app.records.update(collectionId, appId, refToRecordId(ref), { data: payload }, true)
+    )
+  );
+}
+```
+
+If you are writing to **hundreds** of records at once, **flag it** to the platform team — a batch endpoint should be added rather than saturating the API from the browser.
+
+---
+
+## 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/ui-utils/records';
+
+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 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/ui-utils`.
+- [ ] Replace bespoke public hook with `useResolvedRecord`.
+- [ ] Remove any "is variants enabled?" config — probe 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;
+  }
+};
+```

package/docs/ui-utils.md

@@ -0,0 +1,127 @@
+# SmartLinks UI Utils (`@proveanything/ui-utils`)
+
+> Companion module to the SmartLinks SDK. Provides React primitives, hooks, and admin shells for building consistent microapp UIs.
+>
+> Package: `@proveanything/ui-utils`  
+> Install: `npm install @proveanything/ui-utils`
+
+---
+
+## What is this module for?
+
+`@proveanything/ui-utils` sits on top of `@proveanything/smartlinks`. The core SDK handles data — authentication, records, configurations, interactions. This module handles **UI** — the shared React components, hooks, and shell primitives that translate SDK data into consistent admin and public interfaces.
+
+**When do you need it?**
+
+- You are building an admin UI for a records-based microapp (see [records-admin-pattern.md](records-admin-pattern.md))
+- You want the standard inheritance/override editor for scoped records
+- You need the `useResolvedRecord` hook on the public widget side
+- You are using `parseRef` / `buildRef` for the standard `ref` convention
+
+You do **not** need it for apps that only use `appConfiguration`, basic widgets without scoped data, or executor bundles.
+
+---
+
+## Key exports
+
+### Records admin shell
+
+```tsx
+import { RecordsAdminShell } from '@proveanything/ui-utils';
+
+// Drop-in admin interface for any records-based app.
+// Reads the app's manifest `records` block to determine tabs and scopes.
+<RecordsAdminShell
+  collectionId={collectionId}
+  appId={appId}
+  recordType="nutrition"
+  renderForm={(record, parentRecord) => <NutritionForm record={record} parent={parentRecord} />}
+/>
+```
+
+`RecordsAdminShell` handles: left-rail product/scope browsing, variant/batch tab discovery, the "New record" button, inheritance markers, bulk operations, CSV import/export, and telemetry events. Your app only provides the domain form.
+
+### Record editor primitive
+
+```tsx
+import { RecordEditor } from '@proveanything/ui-utils';
+
+// Lower-level editor with inheritance diffing. Use when you need
+// custom layout but still want the inherited/override markers.
+<RecordEditor
+  record={variantRecord}
+  parentRecord={productRecord}
+  fields={nutritionFields}
+  onSave={(data) => app.records.update(collectionId, appId, record.id, { data }, true)}
+/>
+```
+
+### `useResolvedRecord` hook
+
+```ts
+import { useResolvedRecord } from '@proveanything/ui-utils/records';
+
+const { data, source, isLoading } = useResolvedRecord({
+  appId,
+  recordType: 'nutrition',
+  collectionId,
+  productId,
+  variantId,   // optional
+  batchId,     // optional
+  proofId,     // optional
+});
+// source: 'proof' | 'batch' | 'variant' | 'product' | 'facet' | 'default' | null
+```
+
+Walks the resolution chain defined in [records-admin-pattern.md §4](records-admin-pattern.md#4-resolution-order-required) and returns the first matching record plus its source scope.
+
+### `resolveRecord` function
+
+```ts
+import { resolveRecord } from '@proveanything/ui-utils/records';
+
+// Async, non-hook version for executors and server-side logic.
+const resolved = await resolveRecord({
+  appId,
+  recordType: 'nutrition',
+  scope: { collectionId, productId, variantId, batchId, proofId },
+  supportedScopes: ['product', 'facet'], // optional — skip unsupported scopes
+});
+// → { record: AppRecord, source: string } | null
+```
+
+### `parseRef` / `buildRef` utilities
+
+```ts
+import { parseRef, buildRef } from '@proveanything/ui-utils/records';
+
+const parsed = parseRef('variant:prod_abc:var_500ml');
+// → { kind: 'variant', productId: 'prod_abc', variantId: 'var_500ml' }
+
+const ref = buildRef({ kind: 'facet', facetKey: 'bread_type', valueKey: 'sourdough' });
+// → 'facet:bread_type:sourdough'
+```
+
+See [records-admin-pattern.md Appendix A](records-admin-pattern.md#appendix-a--ref-parser-reference) for the full `ParsedRef` type and standalone implementation.
+
+---
+
+## Relationship to the core SDK
+
+```
+@proveanything/smartlinks       ← data layer (records, config, interactions, …)
+        ↑
+@proveanything/ui-utils         ← UI layer (components, hooks, admin shells)
+        ↑
+your microapp                   ← domain logic and custom forms
+```
+
+`ui-utils` imports from `@proveanything/smartlinks` internally. You should install both packages, but only import directly from each for their respective concerns — don't reach into `ui-utils` for SDK data primitives.
+
+---
+
+## Further reading
+
+- [records-admin-pattern.md](records-admin-pattern.md) — the data contract that `RecordsAdminShell` implements
+- [building-react-components.md](building-react-components.md) — dual-mode rendering rules that apply to all ui-utils components
+- [app-manifest.md](app-manifest.md) — the `records` manifest block that drives tab generation

package/openapi.yaml

@@ -17134,6 +17134,10 @@ components:
           type: string
         allowAutoGenerateClaims:
           type: boolean
+        variants:
+          type: boolean
+        batches:
+          type: boolean
         defaultAuthKitId:
           type: string
       required:
@@ -17159,6 +17163,8 @@ components:
         - supported
         - roles
         - shortId
+        - variants
+        - batches
         - defaultAuthKitId
     AppConfig:
       type: object

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "1.9.20",
+  "version": "1.9.21",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",