@proveanything/smartlinks 1.10.0 → 1.10.1

package/dist/api/appObjects.d.ts

@@ -1,4 +1,4 @@
-import type { AppCase, CreateCaseInput, UpdateCaseInput, AppendHistoryInput, CaseSummaryRequest, CaseSummaryResponse, CaseListQueryParams, AppThread, CreateThreadInput, UpdateThreadInput, ReplyInput, ThreadListQueryParams, AppRecord, CreateRecordInput, CreateRecordResponse, UpdateRecordInput, UpsertRecordInput, UpsertRecordResponse, MatchRecordsInput, MatchResult, BulkUpsertItem, BulkUpsertResult, BulkDeleteResult, BulkDeleteInput, RecordListQueryParams, PaginatedResponse, AggregateRequest, AggregateResponse, RelatedResponse } from '../types/appObjects';
+import type { AppCase, CreateCaseInput, UpdateCaseInput, AppendHistoryInput, CaseSummaryRequest, CaseSummaryResponse, CaseListQueryParams, AppThread, CreateThreadInput, UpdateThreadInput, ReplyInput, ThreadListQueryParams, AppRecord, CreateRecordInput, CreateRecordResponse, UpdateRecordInput, UpsertRecordInput, UpsertRecordResponse, MatchRecordsInput, MatchResult, BulkUpsertItem, BulkUpsertResult, BulkDeleteResult, BulkDeleteInput, RecordListQueryParams, ResolveAllParams, ResolveAllResult, PreviewRuleParams, PreviewRuleResult, PaginatedResponse, AggregateRequest, AggregateResponse, RelatedResponse } from '../types/appObjects';
 export declare namespace app {
     namespace cases {
         /**
@@ -239,5 +239,20 @@ export declare namespace app {
          * ```
          */
         function bulkDelete(collectionId: string, appId: string, input: BulkDeleteInput): Promise<BulkDeleteResult>;
+        /**
+         * 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
+         *
+         * @param admin - false for public (visibility-filtered), true for admin (all records)
+         */
+        function resolveAll(collectionId: string, appId: string, input: ResolveAllParams, admin?: boolean): Promise<ResolveAllResult>;
+        /**
+         * 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
+         */
+        function previewRule(collectionId: string, appId: string, input: PreviewRuleParams): Promise<PreviewRuleResult>;
     }
 }

package/dist/api/appObjects.js

@@ -378,6 +378,29 @@ export var app;
             return post(path, input);
         }
         records_1.bulkDelete = bulkDelete;
+        /**
+         * 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
+         *
+         * @param admin - false for public (visibility-filtered), true for admin (all records)
+         */
+        async function resolveAll(collectionId, appId, input, admin = false) {
+            const path = `${basePath(collectionId, appId, admin)}/resolve-all`;
+            return post(path, input);
+        }
+        records_1.resolveAll = resolveAll;
+        /**
+         * 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
+         */
+        async function previewRule(collectionId, appId, input) {
+            const path = `${basePath(collectionId, appId, true)}/preview-rule`;
+            return post(path, input);
+        }
+        records_1.previewRule = previewRule;
     })(records = app.records || (app.records = {}));
 })(app || (app = {})); // end namespace app
 // ==================== HELPERS ====================

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.10.0  |  Generated: 2026-04-25T13:26:09.113Z
+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: MatchedRecord[]
+  records: MatchEntry[]
   * Only present when strategy is 'best'.
   * The single highest-specificity record per recordType.
-  best?: Record<string, MatchedRecord>
+  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
 }
 ```
 
@@ -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
 }
 ```
 
@@ -2140,7 +2232,7 @@ interface PublicCreateBranch {
 
 **BulkDeleteInput** = ``
 
-**MatchedAtLevel** = ``
+**MatchedAt** = ``
 
 ### asset
 
@@ -7306,6 +7398,17 @@ Upsert up to 500 records in a single transaction. Each row is individually error
     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/dist/docs/app-objects.md

@@ -545,24 +545,94 @@ Every record in the response includes a `matchedAt` field indicating **which sco
 ```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;
+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 specificity order: `proof > batch > variant > product > facet > universal`.
+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:

package/dist/openapi.yaml

@@ -12404,6 +12404,90 @@ paths:
           application/json:
             schema:
               $ref: "#/components/schemas/MatchRecordsInput"
+  /{zone}/collection/{collectionId}/app/{appId}/records/preview-rule:
+    post:
+      tags:
+        - records
+      summary: Preview which products in the collection match a given facetRule.
+      operationId: records_previewRule
+      security: []
+      parameters:
+        - name: zone
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: appId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PreviewRuleResult"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/PreviewRuleParams"
+  /{zone}/collection/{collectionId}/app/{appId}/records/resolve-all:
+    post:
+      tags:
+        - records
+      summary: Resolve every applicable record for a product context in one call.
+      operationId: records_resolveAll
+      security: []
+      parameters:
+        - name: zone
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: appId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ResolveAllResult"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ResolveAllParams"
   /{zone}/collection/{collectionId}/app/{appId}/records/upsert:
     post:
       tags:
@@ -15514,6 +15598,27 @@ components:
           type: string
         contactId:
           type: string
+    FacetRuleClause:
+      type: object
+      properties:
+        facetKey:
+          type: string
+        anyOf:
+          type: array
+          items:
+            type: string
+      required:
+        - facetKey
+        - anyOf
+    FacetRule:
+      type: object
+      properties:
+        all:
+          type: array
+          items:
+            $ref: "#/components/schemas/FacetRuleClause"
+      required:
+        - all
     ScopeFacetClause:
       type: object
       properties:
@@ -15583,6 +15688,8 @@ components:
         metadata:
           type: object
           additionalProperties: true
+        facetRule:
+          $ref: "#/components/schemas/FacetRule"
       required:
         - ref
     BulkUpsertResult:
@@ -15610,20 +15717,37 @@ components:
       type: object
       properties:
         matchedAt:
-          $ref: "#/components/schemas/MatchedAtLevel"
+          $ref: "#/components/schemas/MatchedAt"
+      required:
+        - matchedAt
+    MatchEntry:
+      type: object
+      properties:
+        record:
+          $ref: "#/components/schemas/AppRecord"
+        matchedAt:
+          $ref: "#/components/schemas/MatchedAt"
+        matchedRule:
+          $ref: "#/components/schemas/FacetRule"
+        matchedClauseCount:
+          type: number
+        specificity:
+          type: number
       required:
+        - record
         - matchedAt
+        - specificity
     MatchResult:
       type: object
       properties:
         records:
           type: array
           items:
-            $ref: "#/components/schemas/MatchedRecord"
+            $ref: "#/components/schemas/MatchEntry"
         best:
           type: object
           additionalProperties:
-            $ref: "#/components/schemas/MatchedRecord"
+            $ref: "#/components/schemas/MatchEntry"
       required:
         - records
     UpsertRecordInput:
@@ -15651,6 +15775,8 @@ components:
         metadata:
           type: object
           additionalProperties: true
+        facetRule:
+          $ref: "#/components/schemas/FacetRule"
       required:
         - ref
     UpsertRecordResponse:
@@ -15733,6 +15859,8 @@ components:
           $ref: "#/components/schemas/RecordScope"
         specificity:
           type: number
+        facetRule:
+          $ref: "#/components/schemas/FacetRule"
         data:
           type: object
           additionalProperties: true
@@ -15770,6 +15898,7 @@ components:
         - deletedAt
         - scope
         - specificity
+        - facetRule
         - data
         - owner
         - admin
@@ -15821,6 +15950,8 @@ components:
         metadata:
           type: object
           additionalProperties: true
+        facetRule:
+          $ref: "#/components/schemas/FacetRule"
       required:
         - recordType
     UpdateRecordInput:
@@ -15856,6 +15987,8 @@ components:
         metadata:
           type: object
           additionalProperties: true
+        facetRule:
+          $ref: "#/components/schemas/FacetRule"
     RecordListQueryParams:
       type: object
       properties:
@@ -15897,6 +16030,83 @@ components:
           type: string
         includeDeleted:
           type: boolean
+    ResolveAllParams:
+      type: object
+      properties:
+        context:
+          type: object
+          additionalProperties: true
+        productId:
+          type: string
+        variantId:
+          type: string
+        batchId:
+          type: string
+        proofId:
+          type: string
+        facets:
+          type: object
+          additionalProperties:
+            type: array
+            items:
+              type: object
+              additionalProperties: true
+        recordType:
+          type: string
+        tiers:
+          type: array
+          items:
+            type: string
+            enum:
+              - proof
+              - batch
+              - variant
+              - product
+              - rule
+              - facet
+              - collection
+        limit:
+          type: number
+        at:
+          type: string
+        includeScheduled:
+          type: boolean
+        includeExpired:
+          type: boolean
+      required:
+        - context
+    ResolveAllResult:
+      type: object
+      properties:
+        records:
+          type: array
+          items:
+            $ref: "#/components/schemas/MatchEntry"
+        truncated:
+          type: boolean
+      required:
+        - records
+    PreviewRuleParams:
+      type: object
+      properties:
+        facetRule:
+          $ref: "#/components/schemas/FacetRule"
+        limit:
+          type: number
+      required:
+        - facetRule
+    PreviewRuleResult:
+      type: object
+      properties:
+        sampleProductIds:
+          type: array
+          items:
+            type: string
+        totalMatches:
+          type: number
+      required:
+        - sampleProductIds
+        - totalMatches
     RelatedResponse:
       type: object
       properties: