@proveanything/smartlinks 1.9.23 → 1.10.1

package/dist/types/appObjects.d.ts

@@ -284,6 +284,32 @@ export interface ThreadListQueryParams extends ListQueryParams {
     tag?: string;
     contactId?: string;
 }
+/**
+ * A single clause in a FacetRule. Tests one facet key against one or more values (OR semantics).
+ */
+export interface FacetRuleClause {
+    /**
+     * Facet key this clause tests, e.g. "brand", "type", "bread-type".
+     * Must reference a defined facet on the collection.
+     */
+    facetKey: string;
+    /**
+     * One or more facet value keys that satisfy the clause (OR semantics).
+     * At least one value required. Server deduplicates and sorts.
+     */
+    anyOf: string[];
+}
+/**
+ * Multi-clause boolean facet rule: AND across clauses, OR within each clause's anyOf.
+ * Mutually exclusive with `scope` on a record.
+ */
+export interface FacetRule {
+    /**
+     * All clauses must be satisfied (AND semantics).
+     * Must be non-empty; no duplicate facetKey entries.
+     */
+    all: FacetRuleClause[];
+}
 /**
  * Facet clause within a RecordScope.
  * Values within a single clause are ORed; multiple clauses are ANDed.
@@ -340,6 +366,8 @@ export interface BulkUpsertItem {
     scope?: RecordScope;
     data?: Record<string, unknown> | null;
     metadata?: Record<string, unknown> | null;
+    /** Facet rule (rule records only). Mutually exclusive with scope. */
+    facetRule?: FacetRule | null;
 }
 /**
  * Response from the bulk-upsert endpoint.
@@ -371,17 +399,66 @@ export interface BulkUpsertResult {
 export interface BulkDeleteResult {
     deleted: number;
 }
+/**
+ * Input for the bulk-delete endpoint.
+ * Use **refs mode** to delete explicit records by ref,
+ * or **scope mode** to delete all records anchored to a scope.
+ */
+export type BulkDeleteInput = {
+    refs: string[];
+    recordType?: string;
+    scope?: never;
+} | {
+    scope: Omit<RecordScope, 'facets'>;
+    recordType?: string;
+    refs?: never;
+};
+/**
+ * Which resolution tier caused a record to be selected in `match()` or `resolveAll()`.
+ * Precedence (highest first): proof > batch > variant > product > rule > facet > collection > universal.
+ */
+export type MatchedAt = 'proof' | 'batch' | 'variant' | 'product' | 'rule' | 'facet' | 'collection' | 'universal';
+/**
+ * An AppRecord augmented with `matchedAt` — present only on records returned
+ * by the `match` endpoint. Use this to display attribution such as
+ * "Inherited from product" or "Batch-specific" without inspecting scope fields.
+ */
+export interface MatchedRecord extends AppRecord {
+    /**
+     * The most specific scope dimension that caused this record to match.
+     * 'universal' means the record has an empty scope and matches all contexts.
+     */
+    matchedAt: MatchedAt;
+}
+/**
+ * An entry in `match()` or `resolveAll()` results — the record plus resolution metadata.
+ */
+export interface MatchEntry {
+    /** The matched record. */
+    record: AppRecord;
+    /** Which resolution tier caused this record to be selected. */
+    matchedAt: MatchedAt;
+    /** The rule that fired. Present only when matchedAt === 'rule'. */
+    matchedRule?: FacetRule;
+    /**
+     * Number of clauses in the rule that fired.
+     * Present only when matchedAt === 'rule'.
+     */
+    matchedClauseCount?: number;
+    /** Numeric specificity score. Higher = more specific. */
+    specificity: number;
+}
 /**
  * Response from the match endpoint.
  */
 export interface MatchResult {
     /** Matched records ordered by specificity descending (most specific first) */
-    records: AppRecord[];
+    records: MatchEntry[];
     /**
      * Only present when strategy is 'best'.
      * The single highest-specificity record per recordType.
      */
-    best?: Record<string, AppRecord>;
+    best?: Record<string, MatchEntry>;
 }
 /**
  * Request body for the upsert endpoint.
@@ -398,6 +475,8 @@ export interface UpsertRecordInput {
     scope?: RecordScope;
     data?: Record<string, unknown> | null;
     metadata?: Record<string, unknown> | null;
+    /** Facet rule (rule records only). Mutually exclusive with scope. */
+    facetRule?: FacetRule | null;
 }
 /**
  * Response from the upsert endpoint — includes AppRecord plus a created flag.
@@ -442,7 +521,9 @@ export interface AppRecord {
     customId: string | null;
     sourceSystem: string | null;
     status: string | null;
+    /** @deprecated use scope.productId instead */
     productId: string | null;
+    /** @deprecated use scope.proofId instead */
     proofId: string | null;
     contactId: string | null;
     authorId: string | null;
@@ -464,6 +545,12 @@ export interface AppRecord {
      * Higher = more specific. 0 = universal scope.
      */
     specificity: number;
+    /**
+     * Facet rule for rule records (ref starts with "rule:").
+     * null on all other record types. Mutually exclusive with scope.
+     * SDK 1.10.
+     */
+    facetRule: FacetRule | null;
     data: Record<string, unknown>;
     owner: Record<string, unknown>;
     admin: Record<string, unknown>;
@@ -494,6 +581,8 @@ export interface CreateRecordInput {
     owner?: Record<string, unknown>;
     admin?: Record<string, unknown>;
     metadata?: Record<string, unknown>;
+    /** Facet rule (rule records only). Mutually exclusive with scope. */
+    facetRule?: FacetRule | null;
 }
 /**
  * Input for updating a record
@@ -513,6 +602,8 @@ export interface UpdateRecordInput {
     customId?: string;
     sourceSystem?: string;
     metadata?: Record<string, unknown>;
+    /** Facet rule (rule records only). Mutually exclusive with scope. Send null to clear. */
+    facetRule?: FacetRule | null;
 }
 /**
  * Query parameters for listing records
@@ -524,9 +615,7 @@ export interface RecordListQueryParams extends ListQueryParams {
     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) */
@@ -548,6 +637,72 @@ export interface RecordListQueryParams extends ListQueryParams {
      */
     at?: string;
     contactId?: string;
+    /** Include soft-deleted records (non-null deletedAt). Admin only. Default false. */
+    includeDeleted?: boolean;
+}
+/**
+ * Request body for the resolve-all endpoint.
+ * Returns every applicable record for a product context across all tiers.
+ */
+export interface ResolveAllParams {
+    /** Product context to evaluate records against. */
+    context: {
+        productId?: string;
+        variantId?: string;
+        batchId?: string;
+        proofId?: string;
+        /**
+         * Facet assignments for the product — used for both legacy facet-ref matching
+         * and facetRule evaluation.
+         * e.g. { "brand": "samsung", "type": ["tv", "laptop"] }
+         */
+        facets?: Record<string, string | string[]>;
+    };
+    /** Limit to a specific record type. Omit to return all types. */
+    recordType?: string;
+    /** Only return records belonging to these tiers. */
+    tiers?: Array<'proof' | 'batch' | 'variant' | 'product' | 'rule' | 'facet' | 'collection'>;
+    /** Safety cap. Default 500, max 5000. */
+    limit?: number;
+    /** Point-in-time for scheduling evaluation (ISO 8601). Defaults to now. */
+    at?: string;
+    /** Include records whose startsAt is in the future. Default false. */
+    includeScheduled?: boolean;
+    /** Include records whose expiresAt is in the past. Default false. */
+    includeExpired?: boolean;
+}
+/**
+ * Response from the resolve-all endpoint.
+ */
+export interface ResolveAllResult {
+    /**
+     * Every applicable record for the given product context, sorted by precedence
+     * (most-specific first). Each record appears at most once.
+     */
+    records: MatchEntry[];
+    /**
+     * true if the result was truncated at the safety cap.
+     * Default cap: 500 records. Use `limit` to raise it (max 5000).
+     */
+    truncated?: boolean;
+}
+/**
+ * Request body for the preview-rule endpoint.
+ */
+export interface PreviewRuleParams {
+    /** The facet rule to evaluate (same validation as on record create). */
+    facetRule: FacetRule;
+    /** Max product IDs to return. Default 20, max 200. */
+    limit?: number;
+}
+/**
+ * Response from the preview-rule endpoint.
+ */
+export interface PreviewRuleResult {
+    /** A sample of product IDs whose facet assignments satisfy the rule. */
+    sampleProductIds: string[];
+    /** Total products in the collection matching the rule (may exceed sampleProductIds.length). */
+    totalMatches: number;
 }
 /**
  * Response from case related endpoint

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.9.23  |  Generated: 2026-04-25T12:36:26.919Z
+Version: 1.10.1  |  Generated: 2026-04-25T15:35:27.893Z
 
 This is a concise summary of all available API functions and types.
 
@@ -1880,6 +1880,27 @@ interface ReplyInput {
 }
 ```
 
+**FacetRuleClause** (interface)
+```typescript
+interface FacetRuleClause {
+  * Facet key this clause tests, e.g. "brand", "type", "bread-type".
+  * Must reference a defined facet on the collection.
+  facetKey: string
+  * One or more facet value keys that satisfy the clause (OR semantics).
+  * At least one value required. Server deduplicates and sorts.
+  anyOf: string[]
+}
+```
+
+**FacetRule** (interface)
+```typescript
+interface FacetRule {
+  * All clauses must be satisfied (AND semantics).
+  * Must be non-empty; no duplicate facetKey entries.
+  all: FacetRuleClause[]
+}
+```
+
 **ScopeFacetClause** (interface)
 ```typescript
 interface ScopeFacetClause {
@@ -1927,6 +1948,7 @@ interface BulkUpsertItem {
   scope?: RecordScope
   data?: Record<string, unknown> | null
   metadata?: Record<string, unknown> | null
+  facetRule?: FacetRule | null
 }
 ```
 
@@ -1950,13 +1972,26 @@ interface BulkDeleteResult {
 }
 ```
 
+**MatchEntry** (interface)
+```typescript
+interface MatchEntry {
+  record: AppRecord
+  matchedAt: MatchedAt
+  matchedRule?: FacetRule
+  * Number of clauses in the rule that fired.
+  * Present only when matchedAt === 'rule'.
+  matchedClauseCount?: number
+  specificity: number
+}
+```
+
 **MatchResult** (interface)
 ```typescript
 interface MatchResult {
-  records: AppRecord[]
+  records: MatchEntry[]
   * Only present when strategy is 'best'.
   * The single highest-specificity record per recordType.
-  best?: Record<string, AppRecord>
+  best?: Record<string, MatchEntry>
 }
 ```
 
@@ -1973,6 +2008,7 @@ interface UpsertRecordInput {
   scope?: RecordScope
   data?: Record<string, unknown> | null
   metadata?: Record<string, unknown> | null
+  facetRule?: FacetRule | null
 }
 ```
 
@@ -2004,8 +2040,8 @@ interface AppRecord {
   customId: string | null
   sourceSystem: string | null
   status: string | null
-  productId: string | null  // @deprecated — use scope.productId
-  proofId: string | null    // @deprecated — use scope.proofId
+  productId: string | null
+  proofId: string | null
   contactId: string | null
   authorId: string | null
   authorType: string
@@ -2022,6 +2058,10 @@ interface AppRecord {
   * Numeric specificity score computed from scope.
   * Higher = more specific. 0 = universal scope.
   specificity: number
+  * Facet rule for rule records (ref starts with "rule:").
+  * null on all other record types. Mutually exclusive with scope.
+  * SDK 1.10.
+  facetRule: FacetRule | null
   data: Record<string, unknown>
   owner: Record<string, unknown>
   admin: Record<string, unknown> // admin only
@@ -2052,6 +2092,7 @@ interface CreateRecordInput {
   owner?: Record<string, unknown>
   admin?: Record<string, unknown> // admin only
   metadata?: Record<string, unknown>
+  facetRule?: FacetRule | null
 }
 ```
 
@@ -2071,6 +2112,57 @@ interface UpdateRecordInput {
   customId?: string
   sourceSystem?: string
   metadata?: Record<string, unknown>
+  facetRule?: FacetRule | null
+}
+```
+
+**ResolveAllParams** (interface)
+```typescript
+interface ResolveAllParams {
+  context: {
+  productId?: string
+  variantId?: string
+  batchId?: string
+  proofId?: string
+  * Facet assignments for the product — used for both legacy facet-ref matching
+  * and facetRule evaluation.
+  * e.g. { "brand": "samsung", "type": ["tv", "laptop"] }
+  facets?: Record<string, string | string[]>
+  }
+  recordType?: string
+  tiers?: Array<'proof' | 'batch' | 'variant' | 'product' | 'rule' | 'facet' | 'collection'>
+  limit?: number
+  at?: string
+  includeScheduled?: boolean
+  includeExpired?: boolean
+}
+```
+
+**ResolveAllResult** (interface)
+```typescript
+interface ResolveAllResult {
+  * Every applicable record for the given product context, sorted by precedence
+  * (most-specific first). Each record appears at most once.
+  records: MatchEntry[]
+  * true if the result was truncated at the safety cap.
+  * Default cap: 500 records. Use `limit` to raise it (max 5000).
+  truncated?: boolean
+}
+```
+
+**PreviewRuleParams** (interface)
+```typescript
+interface PreviewRuleParams {
+  facetRule: FacetRule
+  limit?: number
+}
+```
+
+**PreviewRuleResult** (interface)
+```typescript
+interface PreviewRuleResult {
+  sampleProductIds: string[]
+  totalMatches: number
 }
 ```
 
@@ -2138,6 +2230,10 @@ interface PublicCreateBranch {
 
 **CallerRole** = `'admin' | 'owner' | 'public'`
 
+**BulkDeleteInput** = ``
+
+**MatchedAt** = ``
+
 ### asset
 
 **Asset** (interface)
@@ -7299,9 +7395,20 @@ Upsert up to 500 records in a single transaction. Each row is individually error
 
 **bulkDelete**(collectionId: string,
     appId: string,
-    input: { refs: string[]; recordType?: string } | { scope: Omit<RecordScope, 'facets'>; recordType?: string }) → `Promise<BulkDeleteResult>`
+    input: BulkDeleteInput) → `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' }, }); ```
 
+**resolveAll**(collectionId: string,
+    appId: string,
+    input: ResolveAllParams,
+    admin: boolean = false) → `Promise<ResolveAllResult>`
+Resolve every applicable record for a product context in one call. Returns records across all tiers (proof, batch, variant, product, rule, facet, collection) deduplicated and sorted by specificity descending. POST /records/resolve-all
+
+**previewRule**(collectionId: string,
+    appId: string,
+    input: PreviewRuleParams) → `Promise<PreviewRuleResult>`
+Preview which products in the collection match a given facetRule. Admin only. Use for live "matches N products" feedback while authoring a rule. POST /records/preview-rule
+
 ### app.threads
 
 Conversation-oriented app objects for comments, discussions, Q&A, and reply-driven experiences.

package/docs/app-objects.md

@@ -523,6 +523,7 @@ const { records } = await app.records.match(collectionId, appId, {
   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, {
@@ -537,6 +538,101 @@ Facet matching rules:
 - 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 entry of records) {
+  switch (entry.matchedAt) {
+    case 'proof':      /* "Scan-specific" */          break;
+    case 'batch':      /* "Batch-specific" */         break;
+    case 'variant':    /* "Size-specific" */          break;
+    case 'product':    /* "Inherited from product" */ break;
+    case 'rule':       /* "Matches rule" */           break;
+    case 'facet':      /* "Tier-specific" */          break;
+    case 'collection': /* "Collection default" */     break;
+    case 'universal':  /* "Default" */                break;
+  }
+}
+```
+
+Precedence follows: `proof > batch > variant > product > rule > facet > collection > 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.
+
+### Facet-Rule Records
+
+A record can declare a **multi-clause boolean rule** (`facetRule`) describing which products it applies to, instead of a single `scope.facets` entry. The rule is AND across facet keys, OR within values of each key:
+
+```typescript
+// Create a record that matches all Samsung TVs and laptops
+await app.records.create(collectionId, appId, {
+  recordType: 'warranty',
+  facetRule: {
+    all: [
+      { facetKey: 'brand', anyOf: ['samsung'] },
+      { facetKey: 'type',  anyOf: ['tv', 'laptop'] },
+    ],
+  },
+  data: { warrantyYears: 2 },
+}, true);
+```
+
+`facetRule` is **mutually exclusive with `scope`**. A record has either a structured scope or a facetRule, never both. The server assigns `ref: 'rule:<ulid>'` automatically.
+
+Specificity for rule records: `Σ (50 + clause.anyOf.length)` across all clauses. A 2-clause rule with 1 value each scores `(50+1)+(50+1) = 102`, which ranks above a plain product-scoped record (100) in `resolveAll()` results.
+
+Use `records.previewRule()` to see which products a rule would match before creating it:
+
+```typescript
+const { sampleProductIds, totalMatches } = await app.records.previewRule(collectionId, appId, {
+  facetRule: {
+    all: [{ facetKey: 'brand', anyOf: ['samsung'] }],
+  },
+});
+// totalMatches: 42, sampleProductIds: ['prod_001', 'prod_002', ...]
+```
+
+### Resolve All
+
+Use `app.records.resolveAll()` to fetch **every applicable record for a product context** in one request—across all tiers (proof, batch, variant, product, rule, facet, collection defaults), deduplicated and sorted by specificity:
+
+```typescript
+// All records that apply to this product context (admin)
+const { records, truncated } = await app.records.resolveAll(collectionId, appId, {
+  context: {
+    productId: 'prod_001',
+    facets: { brand: 'samsung', type: 'tv' },
+  },
+  recordType: 'warranty',
+}, true);
+
+for (const entry of records) {
+  console.log(entry.matchedAt, entry.specificity, entry.record.id);
+  if (entry.matchedAt === 'rule') {
+    console.log('rule fired:', entry.matchedRule, 'clauses:', entry.matchedClauseCount);
+  }
+}
+
+// Public endpoint — visibility-filtered (admin records excluded)
+const { records: publicRecords } = await app.records.resolveAll(collectionId, appId, {
+  context: { productId: 'prod_001', facets: { brand: 'samsung' } },
+}, false);
+
+// Filter to specific tiers
+const { records: ruleRecords } = await app.records.resolveAll(collectionId, appId, {
+  context: { productId: 'prod_001', facets: { brand: 'samsung', type: 'tv' } },
+  tiers: ['product', 'rule', 'collection'],
+}, true);
+```
+
+`truncated: true` means the result hit the safety cap (default 500). Raise it with `limit` (max 5000).
+
 ### Upsert
 
 Create-or-update a record by `ref` in a single call:
@@ -575,13 +671,106 @@ await app.records.bulkDelete(collectionId, appId, {
 });
 ```
 
-### Restore a Soft-Deleted Record
+### 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
 ```
 
-### Scheduling Filters
+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: