@proveanything/smartlinks 1.9.22 → 1.10.0

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, 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, PaginatedResponse, AggregateRequest, AggregateResponse, RelatedResponse } from '../types/appObjects';
 export declare namespace app {
     namespace cases {
         /**
@@ -179,5 +179,65 @@ export declare namespace app {
          * POST /records/aggregate
          */
         function aggregate(collectionId: string, appId: string, request: AggregateRequest, admin?: boolean): Promise<AggregateResponse>;
+        /**
+         * Restore a soft-deleted record.
+         * POST /records/:recordId/restore (admin only)
+         */
+        function restore(collectionId: string, appId: string, recordId: string): Promise<AppRecord>;
+        /**
+         * 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)
+         */
+        function upsert(collectionId: string, appId: string, input: UpsertRecordInput): Promise<UpsertRecordResponse>;
+        /**
+         * 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
+         *
+         * @param admin - false for public endpoint (visibility-filtered), true for admin
+         *
+         * @example
+         * ```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
+         * ```
+         */
+        function match(collectionId: string, appId: string, input: MatchRecordsInput, admin?: boolean): Promise<MatchResult>;
+        /**
+         * 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)
+         */
+        function bulkUpsert(collectionId: string, appId: string, records: BulkUpsertItem[]): Promise<BulkUpsertResult>;
+        /**
+         * 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)
+         *
+         * @example
+         * ```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' },
+         * });
+         * ```
+         */
+        function bulkDelete(collectionId: string, appId: string, input: BulkDeleteInput): Promise<BulkDeleteResult>;
     }
 }

package/dist/api/appObjects.js

@@ -176,7 +176,7 @@ export var app;
     })(threads = app.threads || (app.threads = {}));
     // ==================== RECORDS ====================
     let records;
-    (function (records) {
+    (function (records_1) {
         /**
          * Build the base path for records endpoints
          */
@@ -199,7 +199,7 @@ export var app;
             const path = basePath(collectionId, appId, admin);
             return post(path, input);
         }
-        records.create = create;
+        records_1.create = create;
         /**
          * List records with optional query parameters
          * GET /records
@@ -209,7 +209,7 @@ export var app;
             const queryParams = params ? buildQueryString(params) : '';
             return request(`${path}${queryParams}`);
         }
-        records.list = list;
+        records_1.list = list;
         /**
          * Get a single record by ID
          * GET /records/:recordId
@@ -218,7 +218,7 @@ export var app;
             const path = `${basePath(collectionId, appId, admin)}/${encodeURIComponent(recordId)}`;
             return request(path);
         }
-        records.get = get;
+        records_1.get = get;
         /**
          * Update a record
          * PATCH /records/:recordId
@@ -228,7 +228,7 @@ export var app;
             const path = `${basePath(collectionId, appId, admin)}/${encodeURIComponent(recordId)}`;
             return patch(path, input);
         }
-        records.update = update;
+        records_1.update = update;
         /**
          * Amend the `data` zone of a record using an anonymous edit token.
          * PATCH /records/:recordId  (public endpoint, no auth)
@@ -279,7 +279,7 @@ export var app;
             const path = `${basePath(collectionId, appId, false)}/${encodeURIComponent(recordId)}`;
             return patch(path, { data }, { 'X-Edit-Token': editToken });
         }
-        records.updateWithToken = updateWithToken;
+        records_1.updateWithToken = updateWithToken;
         /**
          * Soft delete a record
          * DELETE /records/:recordId
@@ -288,7 +288,7 @@ export var app;
             const path = `${basePath(collectionId, appId, admin)}/${encodeURIComponent(recordId)}`;
             return del(path);
         }
-        records.remove = remove;
+        records_1.remove = remove;
         /**
          * Get aggregate statistics for records
          * POST /records/aggregate
@@ -297,7 +297,87 @@ export var app;
             const path = `${basePath(collectionId, appId, admin)}/aggregate`;
             return post(path, request);
         }
-        records.aggregate = aggregate;
+        records_1.aggregate = aggregate;
+        /**
+         * Restore a soft-deleted record.
+         * POST /records/:recordId/restore (admin only)
+         */
+        async function restore(collectionId, appId, recordId) {
+            const path = `${basePath(collectionId, appId, true)}/${encodeURIComponent(recordId)}/restore`;
+            return post(path, {});
+        }
+        records_1.restore = restore;
+        /**
+         * 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)
+         */
+        async function upsert(collectionId, appId, input) {
+            const path = `${basePath(collectionId, appId, true)}/upsert`;
+            return post(path, input);
+        }
+        records_1.upsert = upsert;
+        /**
+         * 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
+         *
+         * @param admin - false for public endpoint (visibility-filtered), true for admin
+         *
+         * @example
+         * ```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
+         * ```
+         */
+        async function match(collectionId, appId, input, admin = false) {
+            const path = `${basePath(collectionId, appId, admin)}/match`;
+            return post(path, input);
+        }
+        records_1.match = match;
+        /**
+         * 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)
+         */
+        async function bulkUpsert(collectionId, appId, records) {
+            const path = `${basePath(collectionId, appId, true)}/bulk-upsert`;
+            return post(path, { records });
+        }
+        records_1.bulkUpsert = bulkUpsert;
+        /**
+         * 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)
+         *
+         * @example
+         * ```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' },
+         * });
+         * ```
+         */
+        async function bulkDelete(collectionId, appId, input) {
+            const path = `${basePath(collectionId, appId, true)}/bulk-delete`;
+            return post(path, input);
+        }
+        records_1.bulkDelete = bulkDelete;
     })(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.9.22  |  Generated: 2026-04-25T11:11:00.344Z
+Version: 1.10.0  |  Generated: 2026-04-25T13:26:09.113Z
 
 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: MatchedRecord[]
+  * Only present when strategy is 'best'.
+  * The single highest-specificity record per recordType.
+  best?: Record<string, MatchedRecord>
+}
+```
+
+**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,9 +1999,11 @@ interface AppRecord {
   collectionId: string
   appId: string
   visibility: Visibility
-  recordType: string
+  recordType: string | null
   ref: string | null
-  status: string // default 'active'
+  customId: string | null
+  sourceSystem: string | null
+  status: string | null
   productId: string | null
   proofId: string | null
   contactId: string | null
@@ -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>
 }
 ```
 
@@ -2010,6 +2138,10 @@ interface PublicCreateBranch {
 
 **CallerRole** = `'admin' | 'owner' | 'public'`
 
+**BulkDeleteInput** = ``
+
+**MatchedAtLevel** = ``
+
 ### asset
 
 **Asset** (interface)
@@ -7148,6 +7280,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: 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' }, }); ```
+
 ### app.threads
 
 Conversation-oriented app objects for comments, discussions, Q&A, and reply-driven experiences.