@proveanything/smartlinks 1.10.0 → 1.10.2

package/dist/types/appObjects.d.ts

@@ -285,30 +285,30 @@ export interface ThreadListQueryParams extends ListQueryParams {
     contactId?: string;
 }
 /**
- * Facet clause within a RecordScope.
- * Values within a single clause are ORed; multiple clauses are ANDed.
+ * A single clause in a FacetRule. Tests one facet key against one or more values (OR semantics).
  */
-export interface ScopeFacetClause {
-    /** Facet key, e.g. "tier", "region" */
-    key: string;
-    /** One or more values that satisfy this clause (OR semantics) */
-    valueKeys: string[];
+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[];
 }
 /**
- * Structured scope definition for a record.
- * Describes the audience/context the record applies to.
- * An empty object `{}` means universal (no restrictions).
+ * Multi-clause boolean facet rule: AND across clauses, OR within each clause's anyOf.
+ * Mutually exclusive with `scope` on a record.
  */
-export interface RecordScope {
-    productId?: string;
-    variantId?: string;
-    proofId?: string;
-    batchId?: string;
+export interface FacetRule {
     /**
-     * Arbitrary facet clauses.
-     * Clauses are ANDed together; valueKeys within a clause are ORed.
+     * All clauses must be satisfied (AND semantics).
+     * Must be non-empty; no duplicate facetKey entries.
      */
-    facets?: ScopeFacetClause[];
+    all: FacetRuleClause[];
 }
 /**
  * Runtime context passed to the match endpoint.
@@ -320,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[]>;
 }
@@ -332,14 +334,19 @@ 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 anchor IDs. */
+    facetRule?: FacetRule | null;
 }
 /**
  * Response from the bulk-upsert endpoint.
@@ -381,38 +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;
 };
 /**
- * Indicates which scope dimension caused a record to match during `match()`.
- * Follows specificity order: proof > batch > variant > product > facet > universal.
+ * Which resolution tier caused a record to be selected in `match()` or `resolveAll()`.
+ * Precedence (highest first): rule > proof > batch > variant > product > facet > collection > universal.
  */
-export type MatchedAtLevel = 'proof' | 'batch' | 'variant' | 'product' | 'facet' | '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: MatchedAtLevel;
+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'. */
+    matchedClauseCount?: number;
 }
 /**
  * Response from the match endpoint.
  */
 export interface MatchResult {
     /** Matched records ordered by specificity descending (most specific first) */
-    records: MatchedRecord[];
-    /**
-     * Only present when strategy is 'best'.
-     * The single highest-specificity record per recordType.
-     */
-    best?: Record<string, MatchedRecord>;
+    data: MatchEntry[];
+    /** Total count of matched records */
+    total: number;
+    /** Strategy used for this result */
+    strategy: 'all' | 'best';
 }
 /**
  * Request body for the upsert endpoint.
@@ -421,14 +432,19 @@ 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 anchor IDs. */
+    facetRule?: FacetRule | null;
 }
 /**
  * Response from the upsert endpoint — includes AppRecord plus a created flag.
@@ -470,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;
@@ -488,15 +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).
+     * Numeric specificity score. Server-computed from anchor IDs and facetRule.
+     * Higher = more specific. 0 = universal (no anchors, no rule).
      */
-    scope: RecordScope;
+    specificity: number;
     /**
-     * Numeric specificity score computed from scope.
-     * Higher = more specific. 0 = universal scope.
+     * Facet rule for rule records (ref starts with "rule:").
+     * null on all other record types. Mutually exclusive with anchor IDs.
      */
-    specificity: number;
+    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>;
@@ -506,27 +530,36 @@ 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 anchor IDs. */
+    facetRule?: FacetRule | null;
 }
 /**
  * Input for updating a record
@@ -539,13 +572,19 @@ 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>;
+    /** Set/clear facet rule. Send null to remove. */
+    facetRule?: FacetRule | null;
 }
 /**
  * Query parameters for listing records
@@ -558,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;
@@ -582,6 +621,90 @@ export interface RecordListQueryParams extends ListQueryParams {
     /** 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 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.
+ */
+export interface PreviewRuleParams {
+    /** The facet rule to evaluate (same validation as on record create). */
+    facetRule: FacetRule;
+    /** 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 {
+    /** 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
  */