@proveanything/smartlinks 1.9.21 → 1.9.23

package/dist/types/appObjects.d.ts

@@ -284,6 +284,150 @@ export interface ThreadListQueryParams extends ListQueryParams {
     tag?: string;
     contactId?: string;
 }
+/**
+ * Facet clause within a RecordScope.
+ * Values within a single clause are ORed; multiple clauses are ANDed.
+ */
+export interface ScopeFacetClause {
+    /** Facet key, e.g. "tier", "region" */
+    key: string;
+    /** One or more values that satisfy this clause (OR semantics) */
+    valueKeys: string[];
+}
+/**
+ * Structured scope definition for a record.
+ * Describes the audience/context the record applies to.
+ * An empty object `{}` means universal (no restrictions).
+ */
+export interface RecordScope {
+    productId?: string;
+    variantId?: string;
+    proofId?: string;
+    batchId?: string;
+    /**
+     * Arbitrary facet clauses.
+     * Clauses are ANDed together; valueKeys within a clause are ORed.
+     */
+    facets?: ScopeFacetClause[];
+}
+/**
+ * Runtime context passed to the match endpoint.
+ * Describes the caller or item being evaluated against record scopes.
+ */
+export interface RecordTarget {
+    productId?: string;
+    variantId?: string;
+    proofId?: string;
+    batchId?: string;
+    /**
+     * Facet values the caller possesses, keyed by facet key.
+     * A scope clause is satisfied if ANY of the clause's valueKeys appears here.
+     */
+    facets?: Record<string, string[]>;
+}
+/**
+ * Request body for the bulk-upsert endpoint.
+ */
+export interface BulkUpsertItem {
+    /** Required — logical identifier used as the upsert key */
+    ref: string;
+    recordType?: string;
+    customId?: string;
+    sourceSystem?: string;
+    startsAt?: string | null;
+    expiresAt?: string | null;
+    status?: string | null;
+    scope?: RecordScope;
+    data?: Record<string, unknown> | null;
+    metadata?: Record<string, unknown> | null;
+}
+/**
+ * Response from the bulk-upsert endpoint.
+ */
+export interface BulkUpsertResult {
+    saved: number;
+    failed: number;
+    results: Array<{
+        index: number;
+        status: 'created';
+        id: string;
+        ref: string;
+        created: true;
+    } | {
+        index: number;
+        status: 'updated';
+        id: string;
+        ref: string;
+        created: false;
+    } | {
+        index: number;
+        status: 'error';
+        error: string;
+    }>;
+}
+/**
+ * Response from the bulk-delete endpoint.
+ */
+export interface BulkDeleteResult {
+    deleted: number;
+}
+/**
+ * Response from the match endpoint.
+ */
+export interface MatchResult {
+    /** Matched records ordered by specificity descending (most specific first) */
+    records: AppRecord[];
+    /**
+     * Only present when strategy is 'best'.
+     * The single highest-specificity record per recordType.
+     */
+    best?: Record<string, AppRecord>;
+}
+/**
+ * Request body for the upsert endpoint.
+ */
+export interface UpsertRecordInput {
+    /** Required — used as the lookup key */
+    ref: string;
+    recordType?: string;
+    customId?: string;
+    sourceSystem?: string;
+    startsAt?: string | null;
+    expiresAt?: string | null;
+    status?: string | null;
+    scope?: RecordScope;
+    data?: Record<string, unknown> | null;
+    metadata?: Record<string, unknown> | null;
+}
+/**
+ * Response from the upsert endpoint — includes AppRecord plus a created flag.
+ */
+export interface UpsertRecordResponse extends AppRecord {
+    /** true if the record was newly created, false if updated */
+    created: boolean;
+}
+/**
+ * Request body for the match endpoint.
+ */
+export interface MatchRecordsInput {
+    /** Required — describes the runtime context to match against */
+    target: RecordTarget;
+    /**
+     * 'all'  — return all matching records (default)
+     * 'best' — return the highest-specificity record per recordType
+     */
+    strategy?: 'all' | 'best';
+    /** Limit to a specific recordType */
+    recordType?: string;
+    /** Maximum records to return. Default 100, max 1000. */
+    limit?: number;
+    /** Include records whose startsAt is in the future. Default false. */
+    includeScheduled?: boolean;
+    /** Include records whose expiresAt is in the past. Default false. */
+    includeExpired?: boolean;
+    /** Evaluate scheduling relative to this ISO 8601 timestamp. Defaults to now. */
+    at?: string;
+}
 /**
  * App Record object
  */
@@ -293,9 +437,11 @@ export interface AppRecord {
     collectionId: string;
     appId: string;
     visibility: Visibility;
-    recordType: string;
+    recordType: string | null;
     ref: string | null;
-    status: string;
+    customId: string | null;
+    sourceSystem: string | null;
+    status: string | null;
     productId: string | null;
     proofId: string | null;
     contactId: string | null;
@@ -308,9 +454,20 @@ export interface AppRecord {
     startsAt: string | null;
     expiresAt: string | null;
     deletedAt: string | null;
+    /**
+     * Structured scope definition. Empty object means universal.
+     * Platform-canonicalized on write (keys sorted, valueKeys deduplicated).
+     */
+    scope: RecordScope;
+    /**
+     * Numeric specificity score computed from scope.
+     * Higher = more specific. 0 = universal scope.
+     */
+    specificity: number;
     data: Record<string, unknown>;
     owner: Record<string, unknown>;
     admin: Record<string, unknown>;
+    metadata: Record<string, unknown> | null;
 }
 /**
  * Input for creating a new record
@@ -329,9 +486,14 @@ export interface CreateRecordInput {
     parentId?: string;
     startsAt?: string;
     expiresAt?: string;
+    /** Structured scope. Canonicalized on write; ref derived if not supplied. */
+    scope?: RecordScope;
+    customId?: string;
+    sourceSystem?: string;
     data?: Record<string, unknown>;
     owner?: Record<string, unknown>;
     admin?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
 }
 /**
  * Input for updating a record
@@ -346,6 +508,11 @@ export interface UpdateRecordInput {
     recordType?: string;
     startsAt?: string;
     expiresAt?: string;
+    /** Updating scope recomputes specificity and ref. */
+    scope?: RecordScope;
+    customId?: string;
+    sourceSystem?: string;
+    metadata?: Record<string, unknown>;
 }
 /**
  * Query parameters for listing records
@@ -353,12 +520,33 @@ export interface UpdateRecordInput {
 export interface RecordListQueryParams extends ListQueryParams {
     recordType?: string;
     ref?: string;
+    /** Filter records whose ref starts with this value */
+    refPrefix?: string;
+    customId?: string;
+    sourceSystem?: string;
+    status?: string;
     proofId?: string;
+    productId?: string;
+    /** Filter by scope.variantId (JSONB lookup) */
+    variantId?: string;
+    /** Filter by scope.batchId (JSONB lookup) */
+    batchId?: string;
+    /** Full-text filter on data.label (case-insensitive substring) */
+    q?: string;
     authorId?: string;
     parentType?: string;
     parentId?: string;
     startsAt?: string;
     expiresAt?: string;
+    /** Include records where startsAt is in the future. Default false. */
+    includeScheduled?: boolean;
+    /** Include records where expiresAt is in the past. Default false. */
+    includeExpired?: boolean;
+    /**
+     * Evaluate scheduling relative to this ISO 8601 timestamp.
+     * Defaults to now.
+     */
+    at?: string;
     contactId?: string;
 }
 /**

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.9.21  |  Generated: 2026-04-25T10:48:10.932Z
+Version: 1.9.23  |  Generated: 2026-04-25T12:36:26.919Z
 
 This is a concise summary of all available API functions and types.
 
@@ -1880,6 +1880,117 @@ interface ReplyInput {
 }
 ```
 
+**ScopeFacetClause** (interface)
+```typescript
+interface ScopeFacetClause {
+  key: string
+  valueKeys: string[]
+}
+```
+
+**RecordScope** (interface)
+```typescript
+interface RecordScope {
+  productId?: string
+  variantId?: string
+  proofId?: string
+  batchId?: string
+  * Arbitrary facet clauses.
+  * Clauses are ANDed together; valueKeys within a clause are ORed.
+  facets?: ScopeFacetClause[]
+}
+```
+
+**RecordTarget** (interface)
+```typescript
+interface RecordTarget {
+  productId?: string
+  variantId?: string
+  proofId?: string
+  batchId?: string
+  * Facet values the caller possesses, keyed by facet key.
+  * A scope clause is satisfied if ANY of the clause's valueKeys appears here.
+  facets?: Record<string, string[]>
+}
+```
+
+**BulkUpsertItem** (interface)
+```typescript
+interface BulkUpsertItem {
+  ref: string
+  recordType?: string
+  customId?: string
+  sourceSystem?: string
+  startsAt?: string | null
+  expiresAt?: string | null
+  status?: string | null
+  scope?: RecordScope
+  data?: Record<string, unknown> | null
+  metadata?: Record<string, unknown> | null
+}
+```
+
+**BulkUpsertResult** (interface)
+```typescript
+interface BulkUpsertResult {
+  saved: number
+  failed: number
+  results: Array<
+  | { index: number; status: 'created'; id: string; ref: string; created: true }
+  | { index: number; status: 'updated'; id: string; ref: string; created: false }
+  | { index: number; status: 'error'; error: string }
+  >
+}
+```
+
+**BulkDeleteResult** (interface)
+```typescript
+interface BulkDeleteResult {
+  deleted: number
+}
+```
+
+**MatchResult** (interface)
+```typescript
+interface MatchResult {
+  records: AppRecord[]
+  * Only present when strategy is 'best'.
+  * The single highest-specificity record per recordType.
+  best?: Record<string, AppRecord>
+}
+```
+
+**UpsertRecordInput** (interface)
+```typescript
+interface UpsertRecordInput {
+  ref: string
+  recordType?: string
+  customId?: string
+  sourceSystem?: string
+  startsAt?: string | null
+  expiresAt?: string | null
+  status?: string | null
+  scope?: RecordScope
+  data?: Record<string, unknown> | null
+  metadata?: Record<string, unknown> | null
+}
+```
+
+**MatchRecordsInput** (interface)
+```typescript
+interface MatchRecordsInput {
+  target: RecordTarget
+  * 'all'  — return all matching records (default)
+  * 'best' — return the highest-specificity record per recordType
+  strategy?: 'all' | 'best'
+  recordType?: string
+  limit?: number
+  includeScheduled?: boolean
+  includeExpired?: boolean
+  at?: string
+}
+```
+
 **AppRecord** (interface)
 ```typescript
 interface AppRecord {
@@ -1888,11 +1999,13 @@ interface AppRecord {
   collectionId: string
   appId: string
   visibility: Visibility
-  recordType: string
+  recordType: string | null
   ref: string | null
-  status: string // default 'active'
-  productId: string | null
-  proofId: string | null
+  customId: string | null
+  sourceSystem: string | null
+  status: string | null
+  productId: string | null  // @deprecated — use scope.productId
+  proofId: string | null    // @deprecated — use scope.proofId
   contactId: string | null
   authorId: string | null
   authorType: string
@@ -1903,9 +2016,16 @@ interface AppRecord {
   startsAt: string | null
   expiresAt: string | null
   deletedAt: string | null // admin only
+  * Structured scope definition. Empty object means universal.
+  * Platform-canonicalized on write (keys sorted, valueKeys deduplicated).
+  scope: RecordScope
+  * Numeric specificity score computed from scope.
+  * Higher = more specific. 0 = universal scope.
+  specificity: number
   data: Record<string, unknown>
   owner: Record<string, unknown>
   admin: Record<string, unknown> // admin only
+  metadata: Record<string, unknown> | null
 }
 ```
 
@@ -1914,7 +2034,7 @@ interface AppRecord {
 interface CreateRecordInput {
   recordType: string
   visibility?: Visibility // default 'owner'
-  ref?: string
+  ref?: string             // derived from scope if omitted and scope provided
   status?: string // default 'active'
   productId?: string
   proofId?: string
@@ -1925,9 +2045,13 @@ interface CreateRecordInput {
   parentId?: string
   startsAt?: string // ISO 8601
   expiresAt?: string
+  scope?: RecordScope
+  customId?: string
+  sourceSystem?: string
   data?: Record<string, unknown>
   owner?: Record<string, unknown>
   admin?: Record<string, unknown> // admin only
+  metadata?: Record<string, unknown>
 }
 ```
 
@@ -1943,6 +2067,10 @@ interface UpdateRecordInput {
   recordType?: string
   startsAt?: string
   expiresAt?: string
+  scope?: RecordScope
+  customId?: string
+  sourceSystem?: string
+  metadata?: Record<string, unknown>
 }
 ```
 
@@ -7148,6 +7276,32 @@ Soft delete a record DELETE /records/:recordId
     admin: boolean = false) → `Promise<AggregateResponse>`
 Get aggregate statistics for records POST /records/aggregate
 
+**restore**(collectionId: string,
+    appId: string,
+    recordId: string) → `Promise<AppRecord>`
+Restore a soft-deleted record. POST /records/:recordId/restore (admin only)
+
+**upsert**(collectionId: string,
+    appId: string,
+    input: UpsertRecordInput) → `Promise<UpsertRecordResponse>`
+Upsert a record by ref — creates if no record with that ref exists, otherwise updates. Scope, specificity, and ref are canonicalized on write. POST /records/upsert (admin only)
+
+**match**(collectionId: string,
+    appId: string,
+    input: MatchRecordsInput,
+    admin: boolean = false) → `Promise<MatchResult>`
+Match records against a runtime target scope. Returns records whose scope is satisfied by the target, ordered by specificity descending (most specific first). POST /records/match ```ts const { records, best } = await app.records.match(collectionId, appId, { target: { productId: 'prod_abc', facets: { tier: ['gold'] } }, strategy: 'best', recordType: 'nutrition', }, true); // best.nutrition → the single highest-specificity nutrition record ```
+
+**bulkUpsert**(collectionId: string,
+    appId: string,
+    records: BulkUpsertItem[]) → `Promise<BulkUpsertResult>`
+Upsert up to 500 records in a single transaction. Each row is individually error-isolated — a failure on one row does not abort the others. POST /records/bulk-upsert (admin only)
+
+**bulkDelete**(collectionId: string,
+    appId: string,
+    input: { refs: string[]; recordType?: string } | { scope: Omit<RecordScope, 'facets'>; recordType?: string }) → `Promise<BulkDeleteResult>`
+Soft-delete records in bulk. Supports two modes: - **refs mode**: explicit list of refs (max 1000) - **scope mode**: delete by scope anchor (productId / variantId / etc.) POST /records/bulk-delete (admin only) ```ts // Refs mode await app.records.bulkDelete(collectionId, appId, { refs: ['product:prod_abc', 'product:prod_xyz'], recordType: 'nutrition', }); // Scope mode await app.records.bulkDelete(collectionId, appId, { scope: { productId: 'prod_abc' }, }); ```
+
 ### app.threads
 
 Conversation-oriented app objects for comments, discussions, Q&A, and reply-driven experiences.

package/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,160 @@ 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
+
+// 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
+
+### 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' },
+});
+```
+
+### Restore a Soft-Deleted Record
+
+```typescript
+const restored = await app.records.restore(collectionId, appId, recordId);
+```
+
+### Scheduling Filters
+
+`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/docs/overview.md

@@ -67,7 +67,7 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **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/ui-utils` — React shells, hooks, and primitives for records-based apps |
+| **UI Utils** | `docs/ui-utils.md` | `@proveanything/smartlinks-utils-ui` — React shells, hooks, and primitives for records-based apps |
 
 ---