@proveanything/smartlinks 1.9.22 → 1.10.0

package/dist/docs/app-objects.md

@@ -432,7 +432,7 @@ const productComments = await app.threads.list(collectionId, appId, {
 
 ## Records
 
-**Records** are the most flexible object type — use them for structured data with time-based lifecycles, hierarchies, or custom schemas.
+**Records** are the most flexible object type — use them for structured data with time-based lifecycles, hierarchies, or custom schemas. Records also support **structured scoping** — each record can declare which products, variants, batches, proofs, or facet values it applies to, and the platform can match records against a runtime context.
 
 ### When to Use Records
 
@@ -444,15 +444,279 @@ const productComments = await app.threads.list(collectionId, appId, {
 - **Usage logs** — record product usage metrics
 - **Audit trails** — immutable logs of actions
 - **Loyalty points** — track points earned/redeemed
+- **Per-product / per-facet configuration** — scoped data that varies by product axis (see [records-admin-pattern.md](records-admin-pattern.md))
 
 ### Key Features
 
 - **Record types** — `recordType` field for categorization (required)
 - **Time windows** — `startsAt` and `expiresAt` for time-based data
+- **Scoped targeting** — `scope` object restricts which products/variants/facets the record applies to
+- **Specificity scoring** — `specificity` enables "best match" resolution across multiple scoped records
 - **Parent linking** — attach to products, proofs, contacts, etc.
 - **Author tracking** — `authorId` + `authorType`
 - **Status lifecycle** — custom statuses (default `'active'`)
-- **References** — optional `ref` field for external IDs
+- **References** — optional `ref` field for external IDs; auto-derived from scope if omitted
+
+### Scoped Records
+
+Every record has a `scope` object. An empty scope (`{}`) means the record is universal — it applies everywhere. A populated scope restricts which context the record applies to.
+
+```typescript
+import { app } from '@proveanything/smartlinks';
+
+// A nutrition record scoped to a specific product
+await app.records.create(collectionId, appId, {
+  recordType: 'nutrition',
+  scope: { productId: 'prod_abc' },
+  data: { calories: 250, protein: 12.5 },
+}, true);
+
+// A nutrition record for a specific variant, overriding the product-level record
+await app.records.create(collectionId, appId, {
+  recordType: 'nutrition',
+  scope: { productId: 'prod_abc', variantId: 'var_500ml' },
+  data: { calories: 260, protein: 12.5 },
+}, true);
+
+// A record scoped to a facet value (applies to all products with tier=gold)
+await app.records.create(collectionId, appId, {
+  recordType: 'loyalty_promo',
+  scope: {
+    facets: [{ key: 'tier', valueKeys: ['gold', 'platinum'] }]
+  },
+  data: { discountPercent: 15 },
+}, true);
+```
+
+The `ref` field is derived automatically when `scope` is provided and `ref` is omitted:
+
+```
+scope: { productId: 'prod_abc' }           → ref: 'product:prod_abc'
+scope: { productId: 'prod_abc', variantId: 'var_x' } → ref: 'product:prod_abc/variant:var_x'
+scope: {}                                  → ref: '' (universal)
+```
+
+#### Specificity scores
+
+When multiple scoped records match a context, they are ordered by `specificity`. Higher = more specific:
+
+| Scope element | Points |
+|---------------|--------|
+| `proofId` | +1000 |
+| `batchId` | +500 |
+| `variantId` | +250 |
+| `productId` | +100 |
+| Per facet clause | +10 |
+| Per facet value key | +1 |
+
+### Matching Records Against a Context
+
+Use `app.records.match()` to find records whose scope is satisfied by a runtime target:
+
+```typescript
+// Find all nutrition records that apply for this product + facet context
+const { records } = await app.records.match(collectionId, appId, {
+  target: {
+    productId: 'prod_abc',
+    facets: { tier: ['gold'] },
+  },
+  recordType: 'nutrition',
+}, true);
+// records is ordered by specificity descending — most specific first
+// each record carries a `matchedAt` field indicating which scope dimension matched
+
+// Or use strategy: 'best' to get the single winner per recordType
+const { best } = await app.records.match(collectionId, appId, {
+  target: { productId: 'prod_abc', variantId: 'var_500ml' },
+  strategy: 'best',
+}, true);
+// best.nutrition → the highest-specificity nutrition record for this context
+```
+
+Facet matching rules:
+- Multiple `facets` clauses are **ANDed** — all must be satisfied
+- Values within a single clause are **ORed** — any matching value satisfies it
+- A record with no facet clauses is satisfied by any target
+
+#### `matchedAt` — match attribution
+
+Every record in the response includes a `matchedAt` field indicating **which scope dimension caused the match**. Use it to render attribution labels without inspecting scope fields:
+
+```typescript
+const { records } = await app.records.match(collectionId, appId, { target, recordType: 'nutrition' }, true);
+
+for (const record of records) {
+  switch (record.matchedAt) {
+    case 'proof':     /* "Scan-specific" */     break;
+    case 'batch':     /* "Batch-specific" */    break;
+    case 'variant':   /* "Size-specific" */     break;
+    case 'product':   /* "Inherited from product" */ break;
+    case 'facet':     /* "Tier-specific" */     break;
+    case 'universal': /* "Default" */           break;
+  }
+}
+```
+
+Precedence follows specificity order: `proof > batch > variant > product > facet > universal`.
+
+#### React — `useResolvedRecord`
+
+For React consumers, the `useResolvedRecord` hook in `@proveanything/smartlinks-utils-ui` wraps `records.match()` and returns the best-matching record with loading and error states. The raw `records.match()` API exists for non-React consumers and custom resolution logic.
+
+### Upsert
+
+Create-or-update a record by `ref` in a single call:
+
+```typescript
+const { created } = await app.records.upsert(collectionId, appId, {
+  ref: 'product:prod_abc',
+  recordType: 'nutrition',
+  scope: { productId: 'prod_abc' },
+  data: { calories: 250, protein: 12.5 },
+});
+// created: true if new, false if updated
+```
+
+### Bulk Operations
+
+Upsert or delete large sets of records efficiently:
+
+```typescript
+// Bulk upsert up to 500 records in one transaction
+const result = await app.records.bulkUpsert(collectionId, appId, [
+  { ref: 'product:prod_abc', recordType: 'nutrition', scope: { productId: 'prod_abc' }, data: { calories: 250 } },
+  { ref: 'product:prod_xyz', recordType: 'nutrition', scope: { productId: 'prod_xyz' }, data: { calories: 180 } },
+]);
+// result: { saved: 2, failed: 0, results: [...] }
+
+// Bulk delete by explicit refs
+await app.records.bulkDelete(collectionId, appId, {
+  refs: ['product:prod_abc', 'product:prod_xyz'],
+  recordType: 'nutrition',
+});
+
+// Bulk delete by scope anchor (all records under a product)
+await app.records.bulkDelete(collectionId, appId, {
+  scope: { productId: 'prod_abc' },
+});
+```
+
+### Soft-Delete Semantics
+
+`delete` and `bulkDelete` **soft-delete** records: the row is retained with a non-null `deletedAt` and excluded from all queries by default. Records are **recoverable indefinitely** — there is no expiry on `deletedAt`.
+
+```typescript
+// Single-record restore
+const restored = await app.records.restore(collectionId, appId, recordId);
+
+// List including deleted records (admin only)
+const all = await app.records.list(collectionId, appId, {
+  recordType: 'nutrition',
+  includeDeleted: true,
+}, true);
+// all.data includes records with non-null deletedAt
+```
+
+`bulkDelete` is fully reversible: rows survive with their IDs intact. Restore individually via `restore`, or re-write via `bulkUpsert` (which will find the existing row by `ref` and update it, clearing `deletedAt` in the process).
+
+### Text Search
+
+The `q` parameter on `GET /records` performs a **case-insensitive substring match** (`ILIKE`) on `data->>'label'`. It works on both admin and public list endpoints today:
+
+```typescript
+const results = await app.records.list(collectionId, appId, {
+  recordType: 'product',
+  q: 'premium',
+}, true);
+// returns records where data.label contains 'premium' (case-insensitive)
+```
+
+> `q` is not a full-text index and does not return ranked results. For ranked relevance search over large corpora, use the Elasticsearch integration.
+
+### External ID / ETL Workflow
+
+`customId` and `sourceSystem` provide a stable external key pair for loading records from external systems (CMS, ERP, PIM, etc.):
+
+- Both fields are **indexed** via a composite index on `(sourceSystem, customIdNormalized)`.
+- `customId` is **filterable** on `GET /records?customId=x&sourceSystem=y`.
+- The pair is **not unique** — the same external ID can exist across different `recordType` values by design (a CMS slug can appear in both a `content` and a `nutrition` record).
+- `upsert` currently keys on `ref`, not `customId`. The recommended ETL pattern is to derive a stable `ref` from the external ID and pass `customId` alongside:
+
+```typescript
+// Idiomatic ETL upsert: ref is derived from the external key, customId carries it too
+await app.records.upsert(collectionId, appId, {
+  ref: `cms:${slug}`,          // stable find-or-create key
+  customId: slug,
+  sourceSystem: 'contentful',
+  recordType: 'content_page',
+  scope: { productId },
+  data: { title, body },
+});
+// upsert finds-or-creates by ref deterministically,
+// customId is stored for later reverse-lookup via ?customId=&sourceSystem=
+```
+
+### Counts by Record Type
+
+`aggregate()` returns counts grouped by `record_type` in a single round-trip — no separate endpoint needed:
+
+```typescript
+const stats = await app.records.aggregate(collectionId, appId, {
+  groupBy: ['record_type'],
+  metrics: ['count'],
+  // Optionally narrow the corpus:
+  filters: { status: 'active' },
+}, true);
+// stats.groups → [{ record_type: 'nutrition', count: 42 }, { record_type: 'loyalty_promo', count: 7 }, ...]
+// Ordered by count descending
+```
+
+You can also combine with other filters:
+
+```typescript
+// Counts per type for a specific product
+await app.records.aggregate(collectionId, appId, {
+  groupBy: ['record_type'],
+  metrics: ['count'],
+  filters: { product_id: 'prod_abc' },
+}, true);
+```
+
+### Canonical Ref Format
+
+The `ref` field is **server-derived** when you provide a `scope` and omit `ref`. Clients should never construct ref strings manually. The authoritative grammar is slash-joined:
+
+```
+[facet:{key}={val1}+{val2}/][product:{productId}/][variant:{variantId}/][batch:{batchId}/][proof:{proofId}]
+```
+
+Examples:
+
+| Scope | Derived ref |
+|-------|-------------|
+| `{ productId: 'prod_abc' }` | `product:prod_abc` |
+| `{ productId: 'prod_abc', variantId: 'var_500ml' }` | `product:prod_abc/variant:var_500ml` |
+| `{ batchId: 'batch_q1' }` | `batch:batch_q1` |
+| `{ facets: [{ key: 'tier', valueKeys: ['gold'] }] }` | `facet:tier=gold` |
+| `{}` | `''` (universal) |
+
+`parseRef` / `buildRef` in `data/refs.ts` should be used for **display and URL round-tripping only**, never as upsert keys. For ETL use cases, set an explicit `ref` using a stable external key (see [External ID / ETL Workflow](#external-id--etl-workflow)).
+
+`startsAt` and `expiresAt` control record active windows. The list and match endpoints respect scheduling by default (only returning currently-active records). Override with:
+
+```typescript
+// Include future records and expired records
+await app.records.list(collectionId, appId, {
+  includeScheduled: true,
+  includeExpired: true,
+}, true);
+
+// Preview what records will be active at a future point in time
+await app.records.match(collectionId, appId, {
+  target: { productId: 'prod_abc' },
+  at: '2026-06-01T00:00:00Z',
+}, true);
+```
 
 ### Example: Product Registration
 

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

@@ -30,7 +30,7 @@ Without a shared pattern, every app reinvents:
 - 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.
+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/smartlinks-utils-ui` (see the [companion guide](ui-utils.md)) can stay simple.
 
 ---
 
@@ -71,20 +71,35 @@ variant:<productId>:<variantId>
 batch:<productId>:<batchId>
 proof:<proofId>
 facet:<facetKey>:<valueKey>
-default
+''                             (universal / collection-wide fallback)
 ```
 
 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.
+- `''` (empty ref) is the **universal** record — one per `(app, recordType)` with no scope restrictions; the collection-wide 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.
 
+### Writing records
+
+When creating or upserting a record, send a structured **`RecordScope`** — the server derives `ref` from it:
+
+```ts
+await app.records.upsert(collectionId, appId, {
+  recordType: 'nutrition',
+  scope: { productId: 'prod_abc', variantId: 'var_500ml' }, // server → ref: 'product:prod_abc/variant:var_500ml'
+  data: { calories: 260 },
+});
+```
+
+- `ref` is for **display, URL routing, and resolution output only** — never construct one to use as an upsert key.
+- `customId` / `sourceSystem` are for external references (filterable via `list()`) but are **not unique** — the same external ID can exist across `recordType` values. Do not upsert on `customId` either.
+
 ---
 
 ## 4. Resolution order (REQUIRED)
@@ -92,7 +107,7 @@ If a new axis appears (e.g. `region:eu`), pick a new prefix and document it. Nev
 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
+proof → batch → variant → product → facet(*) → universal
 ```
 
 `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.
@@ -208,7 +223,7 @@ If you are using `<RecordsAdminShell>`, the bulk actions menu is included and wi
 
 ## 9. CSV import / export
 
-Adopt this column shape across all records-based apps:
+If your app exposes CSV import/export, use this column shape so files round-trip across apps:
 
 ```
 scope,scopeRef,<field1>,<field2>,...
@@ -220,18 +235,22 @@ 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.
+
+#### If you ship CSV
+
+- 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`):
+To keep widgets consistent across apps, expose one hook per record type (from `@proveanything/smartlinks-utils-ui`):
 
 ```ts
 import { useResolvedRecord } from '@proveanything/smartlinks-utils-ui/records-admin';
 
 const { data, source, isLoading } = useResolvedRecord({
+  SL,
   appId,
   recordType: 'nutrition',
   // any combination of these — the hook walks the chain:
@@ -239,13 +258,13 @@ const { data, source, isLoading } = useResolvedRecord({
 });
 ```
 
-`source` is one of `'proof' | 'batch' | 'variant' | 'product' | 'facet' | 'default' | null`. UI can show a badge ("Showing batch-specific values") when useful.
+`source` is one of `'proof' | 'batch' | 'variant' | 'product' | 'facet' | 'universal' | 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.
+All admin shells emit these events. The `<RecordsAdminShell>` from `@proveanything/smartlinks-utils-ui` wires them automatically using `interactions.appendEvent` from the SDK — apps don't call this themselves.
 
 | Event                  | Props                                                |
 |------------------------|------------------------------------------------------|
@@ -278,11 +297,11 @@ All admin shells emit these events. The `<RecordsAdminShell>` from `@proveanythi
 
 ## Appendix A — `ref` parser reference
 
-This is the canonical implementation. Copy it into your app or import from `@proveanything/ui-utils/records`.
+This is the canonical implementation. Copy it into your app or import from `@proveanything/smartlinks-utils-ui/records-admin`.
 
 ```ts
 type ParsedRef =
-  | { kind: 'default' }
+  | { kind: 'universal' }
   | { kind: 'product'; productId: string }
   | { kind: 'variant'; productId: string; variantId: string }
   | { kind: 'batch';   productId: string; batchId: string }
@@ -291,7 +310,7 @@ type ParsedRef =
 
 export const buildRef = (p: ParsedRef): string => {
   switch (p.kind) {
-    case 'default': return 'default';
+    case 'universal': return '';
     case 'product': return `product:${p.productId}`;
     case 'variant': return `variant:${p.productId}:${p.variantId}`;
     case 'batch':   return `batch:${p.productId}:${p.batchId}`;
@@ -301,7 +320,7 @@ export const buildRef = (p: ParsedRef): string => {
 };
 
 export const parseRef = (ref: string): ParsedRef | null => {
-  if (ref === 'default') return { kind: 'default' };
+  if (!ref) return { kind: 'universal' };
   const [head, ...rest] = ref.split(':');
   switch (head) {
     case 'product': return rest.length === 1 ? { kind: 'product', productId: rest[0] } : null;

package/dist/docs/ui-utils.md

@@ -82,7 +82,7 @@ import * as SL from '@proveanything/smartlinks';
   scopes={['facet', 'product', 'variant', 'batch']}
   contextScope={{ productId, variantId, batchId }}   // from iframe URL — optional
   defaultData={() => ({})}
-  csvSchema={{ columns: [/* ... */] }}
+  csvSchema={{ columns: [/* ... */] }}  // optional — omit to disable CSV import/export
   renderEditor={(ctx) => <NutritionForm ctx={ctx} />}
   renderPreview={({ resolved }) => <pre>{JSON.stringify(resolved, null, 2)}</pre>}
 />
@@ -97,7 +97,7 @@ import * as SL from '@proveanything/smartlinks';
 - **Collection-aware tabs**: calls `collection.get` and hides Variants / Batches tabs unless `collection.variants` / `collection.batches` are true — no flicker
 - **Server-side pagination** via `useInfiniteQuery` — handles thousands of products with a "Load more" button
 - **Context-aware**: pass `contextScope` from your iframe URL (`productId` / `variantId` / `batchId`) and the browser is constrained to that subtree with the right tab auto-selected
-- **CSV import / export** with a schema you define; failed rows come back as an annotated CSV
+- **CSV import / export** (optional — provide `csvSchema` to enable); failed rows come back as an annotated CSV
 - **Bulk actions menu** (apply-to-many, copy-from, clear) via `bulkUpsert` / `bulkDelete`
 - **Telemetry hook** (`onTelemetry`) emits typed events for save, delete, scope change, CSV import/export, bulk apply
 - **i18n strings** fully overridable
@@ -136,7 +136,7 @@ const { data, source, isLoading } = useResolvedRecord({
   batchId,     // optional
   proofId,     // optional
 });
-// source: 'proof' | 'batch' | 'variant' | 'product' | 'facet' | 'default' | null
+// source: 'proof' | 'batch' | 'variant' | 'product' | 'facet' | 'universal' | null
 ```
 
 Walks the resolution chain defined in [records-admin-pattern.md §4](records-admin-pattern.md#4-resolution-order-required). Use this on the **public widget side** to read the correct value for a given context.