@proveanything/smartlinks 1.10.1 → 1.10.3

package/dist/types/appObjects.d.ts

@@ -310,32 +310,6 @@ export interface FacetRule {
      */
     all: FacetRuleClause[];
 }
-/**
- * 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.
@@ -346,8 +320,10 @@ export interface RecordTarget {
     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.
+     * Facet assignments for the product (e.g. `{ brand: ['samsung'], type: ['tv'] }`).
+     * Used exclusively to match FacetRule records via GIN-indexed containment check.
+     * Does NOT filter legacy scope.facets arrays (that system is removed in SDK 1.12).
+     * Omit to exclude rule records from results.
      */
     facets?: Record<string, string[]>;
 }
@@ -358,15 +334,18 @@ export interface BulkUpsertItem {
     /** Required — logical identifier used as the upsert key */
     ref: string;
     recordType?: string;
-    customId?: string;
-    sourceSystem?: string;
+    productId?: string | null;
+    variantId?: string | null;
+    batchId?: string | null;
+    proofId?: string | null;
+    customId?: string | null;
+    sourceSystem?: string | null;
     startsAt?: string | null;
     expiresAt?: string | null;
     status?: string | null;
-    scope?: RecordScope;
     data?: Record<string, unknown> | null;
     metadata?: Record<string, unknown> | null;
-    /** Facet rule (rule records only). Mutually exclusive with scope. */
+    /** Facet rule (rule records only). Mutually exclusive with anchor IDs. */
     facetRule?: FacetRule | null;
 }
 /**
@@ -409,56 +388,42 @@ export type BulkDeleteInput = {
     recordType?: string;
     scope?: never;
 } | {
-    scope: Omit<RecordScope, 'facets'>;
+    scope: {
+        productId?: string;
+        variantId?: string;
+        batchId?: string;
+        proofId?: string;
+    };
     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.
+ * Precedence (highest first): rule > proof > batch > variant > product > facet > collection > universal.
  */
-export type MatchedAt = 'proof' | 'batch' | 'variant' | 'product' | 'rule' | 'facet' | 'collection' | 'universal';
+export type MatchedAt = 'rule' | 'proof' | 'batch' | 'variant' | 'product' | '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.
+ * Entry in `match()` results — the record fields plus resolution metadata.
+ * Extends AppRecord so all record fields are directly accessible.
  */
-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;
+export interface MatchEntry extends 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'.
-     */
+    /** 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: MatchEntry[];
-    /**
-     * Only present when strategy is 'best'.
-     * The single highest-specificity record per recordType.
-     */
-    best?: Record<string, MatchEntry>;
+    data: MatchEntry[];
+    /** Total count of matched records */
+    total: number;
+    /** Strategy used for this result */
+    strategy: 'all' | 'best';
 }
 /**
  * Request body for the upsert endpoint.
@@ -467,15 +432,18 @@ export interface UpsertRecordInput {
     /** Required — used as the lookup key */
     ref: string;
     recordType?: string;
-    customId?: string;
-    sourceSystem?: string;
+    productId?: string | null;
+    variantId?: string | null;
+    batchId?: string | null;
+    proofId?: string | null;
+    customId?: string | null;
+    sourceSystem?: string | null;
     startsAt?: string | null;
     expiresAt?: string | null;
     status?: string | null;
-    scope?: RecordScope;
     data?: Record<string, unknown> | null;
     metadata?: Record<string, unknown> | null;
-    /** Facet rule (rule records only). Mutually exclusive with scope. */
+    /** Facet rule (rule records only). Mutually exclusive with anchor IDs. */
     facetRule?: FacetRule | null;
 }
 /**
@@ -518,12 +486,18 @@ export interface AppRecord {
     visibility: Visibility;
     recordType: string | null;
     ref: string | null;
+    scopeType: string | null;
+    scopeId: string | null;
     customId: string | null;
+    customIdNormalized: string | null;
     sourceSystem: string | null;
     status: string | null;
-    /** @deprecated use scope.productId instead */
+    /** Flat anchor IDs. null = wildcard (matches any value). */
     productId: string | null;
-    /** @deprecated use scope.proofId instead */
+    /** Flat anchor ID, promoted from scope.variantId in SDK 1.12. */
+    variantId: string | null;
+    /** Flat anchor ID, promoted from scope.batchId in SDK 1.12. */
+    batchId: string | null;
     proofId: string | null;
     contactId: string | null;
     authorId: string | null;
@@ -536,21 +510,17 @@ export interface AppRecord {
     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.
+     * Numeric specificity score. Server-computed from anchor IDs and facetRule.
+     * Higher = more specific. 0 = universal (no anchors, no rule).
      */
     specificity: number;
     /**
      * Facet rule for rule records (ref starts with "rule:").
-     * null on all other record types. Mutually exclusive with scope.
-     * SDK 1.10.
+     * null on all other record types. Mutually exclusive with anchor IDs.
      */
     facetRule: FacetRule | null;
+    /** Singleton cardinality key. Server-assigned; opaque to clients. SDK 1.11. */
+    singletonKey: string | null;
     data: Record<string, unknown>;
     owner: Record<string, unknown>;
     admin: Record<string, unknown>;
@@ -560,28 +530,35 @@ export interface AppRecord {
  * Input for creating a new record
  */
 export interface CreateRecordInput {
-    recordType: string;
+    recordType?: string;
     visibility?: Visibility;
     ref?: string;
     status?: string;
-    productId?: string;
-    proofId?: string;
+    productId?: string | null;
+    variantId?: string | null;
+    batchId?: string | null;
+    proofId?: string | null;
     contactId?: string;
     authorId?: string;
     authorType?: string;
     parentType?: string;
     parentId?: string;
-    startsAt?: string;
-    expiresAt?: string;
-    /** Structured scope. Canonicalized on write; ref derived if not supplied. */
-    scope?: RecordScope;
-    customId?: string;
-    sourceSystem?: string;
+    startsAt?: string | null;
+    expiresAt?: string | null;
+    scopeType?: string | null;
+    scopeId?: string | null;
+    customId?: string | null;
+    sourceSystem?: string | null;
+    /**
+     * Opt-in singleton cardinality. When set, the server upserts rather than
+     * inserting a duplicate. Values: 'collection' | 'product' | 'variant' | 'batch' | 'proof'
+     */
+    singletonPer?: string;
     data?: Record<string, unknown>;
     owner?: Record<string, unknown>;
     admin?: Record<string, unknown>;
     metadata?: Record<string, unknown>;
-    /** Facet rule (rule records only). Mutually exclusive with scope. */
+    /** Facet rule (rule records only). Mutually exclusive with anchor IDs. */
     facetRule?: FacetRule | null;
 }
 /**
@@ -595,14 +572,18 @@ export interface UpdateRecordInput {
     visibility?: Visibility;
     ref?: string;
     recordType?: string;
-    startsAt?: string;
-    expiresAt?: string;
-    /** Updating scope recomputes specificity and ref. */
-    scope?: RecordScope;
-    customId?: string;
-    sourceSystem?: string;
+    productId?: string | null;
+    variantId?: string | null;
+    batchId?: string | null;
+    proofId?: string | null;
+    startsAt?: string | null;
+    expiresAt?: string | null;
+    scopeType?: string | null;
+    scopeId?: string | null;
+    customId?: string | null;
+    sourceSystem?: string | null;
     metadata?: Record<string, unknown>;
-    /** Facet rule (rule records only). Mutually exclusive with scope. Send null to clear. */
+    /** Set/clear facet rule. Send null to remove. */
     facetRule?: FacetRule | null;
 }
 /**
@@ -616,9 +597,9 @@ export interface RecordListQueryParams extends ListQueryParams {
     customId?: string;
     sourceSystem?: string;
     proofId?: string;
-    /** Filter by scope.variantId (JSONB lookup) */
+    /** Filter by variantId (indexed flat column) */
     variantId?: string;
-    /** Filter by scope.batchId (JSONB lookup) */
+    /** Filter by batchId (indexed flat column) */
     batchId?: string;
     /** Full-text filter on data.label (case-insensitive substring) */
     q?: string;
@@ -675,16 +656,28 @@ export interface ResolveAllParams {
  * 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;
+    /** Every applicable record sorted by precedence (most-specific first). Each appears at most once. */
+    records: ResolveAllEntry[];
+    /** Total count of returned records. */
+    total: number;
+    /** The context echoed back from the request (for verification). */
+    context: ResolveAllContext;
+    /** true if the result was capped at the safety limit. */
+    truncated: boolean;
+}
+export interface ResolveAllEntry {
+    record: AppRecord;
+    matchedAt: MatchedAt;
+    specificity: number;
+    matchedRule?: FacetRule;
+    matchedClauseCount?: number;
+}
+export interface ResolveAllContext {
+    productId?: string;
+    variantId?: string;
+    batchId?: string;
+    proofId?: string;
+    facets?: Record<string, string[]>;
 }
 /**
  * Request body for the preview-rule endpoint.
@@ -692,17 +685,25 @@ export interface ResolveAllResult {
 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. */
+    /** Filter to a specific record type for context. */
+    recordType?: string;
+    /** Max matching products to return in sample. Default 50, 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;
+    /** Sample of products whose facet assignments satisfy the rule. */
+    matchingProducts: Array<{
+        productId: string;
+        name?: string;
+        facets: Record<string, string[]>;
+    }>;
+    /** Total products in the collection matching the rule. */
+    total: number;
+    /** Server-canonicalized rule (sorted keys, deduped values) — for display. */
+    rule: FacetRule;
 }
 /**
  * Response from case related endpoint

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.10.1  |  Generated: 2026-04-25T15:35:27.893Z
+Version: 1.10.3  |  Generated: 2026-04-27T10:04:40.477Z
 
 This is a concise summary of all available API functions and types.
 
@@ -1901,27 +1901,6 @@ interface FacetRule {
 }
 ```
 
-**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 {
@@ -1929,8 +1908,10 @@ interface RecordTarget {
   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.
+  * Facet assignments for the product (e.g. `{ brand: ['samsung'], type: ['tv'] }`).
+  * Used exclusively to match FacetRule records via GIN-indexed containment check.
+  * Does NOT filter legacy scope.facets arrays (that system is removed in SDK 1.12).
+  * Omit to exclude rule records from results.
   facets?: Record<string, string[]>
 }
 ```
@@ -1940,12 +1921,15 @@ interface RecordTarget {
 interface BulkUpsertItem {
   ref: string
   recordType?: string
-  customId?: string
-  sourceSystem?: string
+  productId?: string | null
+  variantId?: string | null
+  batchId?: string | null
+  proofId?: string | null
+  customId?: string | null
+  sourceSystem?: string | null
   startsAt?: string | null
   expiresAt?: string | null
   status?: string | null
-  scope?: RecordScope
   data?: Record<string, unknown> | null
   metadata?: Record<string, unknown> | null
   facetRule?: FacetRule | null
@@ -1972,26 +1956,12 @@ 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: MatchEntry[]
-  * Only present when strategy is 'best'.
-  * The single highest-specificity record per recordType.
-  best?: Record<string, MatchEntry>
+  data: MatchEntry[]
+  total: number
+  strategy: 'all' | 'best'
 }
 ```
 
@@ -2000,12 +1970,15 @@ interface MatchResult {
 interface UpsertRecordInput {
   ref: string
   recordType?: string
-  customId?: string
-  sourceSystem?: string
+  productId?: string | null
+  variantId?: string | null
+  batchId?: string | null
+  proofId?: string | null
+  customId?: string | null
+  sourceSystem?: string | null
   startsAt?: string | null
   expiresAt?: string | null
   status?: string | null
-  scope?: RecordScope
   data?: Record<string, unknown> | null
   metadata?: Record<string, unknown> | null
   facetRule?: FacetRule | null
@@ -2037,10 +2010,15 @@ interface AppRecord {
   visibility: Visibility
   recordType: string | null
   ref: string | null
+  scopeType: string | null
+  scopeId: string | null
   customId: string | null
+  customIdNormalized: string | null
   sourceSystem: string | null
   status: string | null
   productId: string | null
+  variantId: string | null
+  batchId: string | null
   proofId: string | null
   contactId: string | null
   authorId: string | null
@@ -2052,16 +2030,13 @@ 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.
+  * Numeric specificity score. Server-computed from anchor IDs and facetRule.
+  * Higher = more specific. 0 = universal (no anchors, no rule).
   specificity: number
   * Facet rule for rule records (ref starts with "rule:").
-  * null on all other record types. Mutually exclusive with scope.
-  * SDK 1.10.
+  * null on all other record types. Mutually exclusive with anchor IDs.
   facetRule: FacetRule | null
+  singletonKey: string | null
   data: Record<string, unknown>
   owner: Record<string, unknown>
   admin: Record<string, unknown> // admin only
@@ -2072,25 +2047,31 @@ interface AppRecord {
 **CreateRecordInput** (interface)
 ```typescript
 interface CreateRecordInput {
-  recordType: string
-  visibility?: Visibility // default 'owner'
-  ref?: string             // derived from scope if omitted and scope provided
-  status?: string // default 'active'
-  productId?: string
-  proofId?: string
+  recordType?: string
+  visibility?: Visibility
+  ref?: string
+  status?: string
+  productId?: string | null
+  variantId?: string | null
+  batchId?: string | null
+  proofId?: string | null
   contactId?: string
   authorId?: string
   authorType?: string
   parentType?: string
   parentId?: string
-  startsAt?: string // ISO 8601
-  expiresAt?: string
-  scope?: RecordScope
-  customId?: string
-  sourceSystem?: string
+  startsAt?: string | null
+  expiresAt?: string | null
+  scopeType?: string | null
+  scopeId?: string | null
+  customId?: string | null
+  sourceSystem?: string | null
+  * Opt-in singleton cardinality. When set, the server upserts rather than
+  * inserting a duplicate. Values: 'collection' | 'product' | 'variant' | 'batch' | 'proof'
+  singletonPer?: string
   data?: Record<string, unknown>
   owner?: Record<string, unknown>
-  admin?: Record<string, unknown> // admin only
+  admin?: Record<string, unknown>
   metadata?: Record<string, unknown>
   facetRule?: FacetRule | null
 }
@@ -2106,11 +2087,16 @@ interface UpdateRecordInput {
   visibility?: Visibility
   ref?: string
   recordType?: string
-  startsAt?: string
-  expiresAt?: string
-  scope?: RecordScope
-  customId?: string
-  sourceSystem?: string
+  productId?: string | null
+  variantId?: string | null
+  batchId?: string | null
+  proofId?: string | null
+  startsAt?: string | null
+  expiresAt?: string | null
+  scopeType?: string | null
+  scopeId?: string | null
+  customId?: string | null
+  sourceSystem?: string | null
   metadata?: Record<string, unknown>
   facetRule?: FacetRule | null
 }
@@ -2141,12 +2127,32 @@ interface ResolveAllParams {
 **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
+  records: ResolveAllEntry[]
+  total: number
+  context: ResolveAllContext
+  truncated: boolean
+}
+```
+
+**ResolveAllEntry** (interface)
+```typescript
+interface ResolveAllEntry {
+  record: AppRecord
+  matchedAt: MatchedAt
+  specificity: number
+  matchedRule?: FacetRule
+  matchedClauseCount?: number
+}
+```
+
+**ResolveAllContext** (interface)
+```typescript
+interface ResolveAllContext {
+  productId?: string
+  variantId?: string
+  batchId?: string
+  proofId?: string
+  facets?: Record<string, string[]>
 }
 ```
 
@@ -2154,6 +2160,7 @@ interface ResolveAllResult {
 ```typescript
 interface PreviewRuleParams {
   facetRule: FacetRule
+  recordType?: string
   limit?: number
 }
 ```
@@ -2161,8 +2168,9 @@ interface PreviewRuleParams {
 **PreviewRuleResult** (interface)
 ```typescript
 interface PreviewRuleResult {
-  sampleProductIds: string[]
-  totalMatches: number
+  matchingProducts: Array<{ productId: string; name?: string; facets: Record<string, string[]> }>
+  total: number
+  rule: FacetRule
 }
 ```