@proveanything/smartlinks 1.15.2 → 1.15.4

package/dist/api/ai.js

@@ -28,7 +28,11 @@ var aiInternal;
              * @returns Responses API result or async iterable for streaming events
              */
             async function create(collectionId, request) {
+                var _a;
                 const path = `/admin/collection/${encodeURIComponent(collectionId)}/ai/v1/responses`;
+                if (((_a = request.multi_agent) === null || _a === void 0 ? void 0 : _a.enabled) && request.stream) {
+                    throw new Error('Streaming is not supported when multi_agent.enabled is true');
+                }
                 if (request.stream) {
                     return requestStream(path, { method: 'POST', body: request });
                 }

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.15.2  |  Generated: 2026-07-05T07:39:20.416Z
+Version: 1.15.4  |  Generated: 2026-07-14T15:01:53.978Z
 
 This is a concise summary of all available API functions and types.
 
@@ -42,6 +42,7 @@ For detailed guides on specific features:
 - **[Portal Back Button](portal-back-button.md)** - `parentPath` contract for hierarchy-aware "up" navigation; `useDeepLinkSync` integration
 - **[Contact Search](contact-search.md)** - Admin contact search: free-text, typeahead, identity/tag/JSONB filters, and pagination
 - **[App Data Storage](app-data-storage.md)** - User-specific and collection-scoped app data storage
+- **[Product/Proof Data Scoping](proof-product-data-scoping.md)** - Canonical spec for `product.data`/`.admin` and `proof.data`/`.admin`/`.values` (owner/personal) buckets, read/write authority, and the `productFields`/`proofFields` collection-settings schemas
 - **[Forms](forms.md)** - Platform-managed form definitions, submissions, and schema-driven React form UI
 - **[App Objects: Cases, Threads & Records](app-objects.md)** - Generic app-scoped building blocks for support cases, discussions, bookings, registrations, and more
 - **[App Records Pattern](app-records-pattern.md)** - Canonical pattern for storing per-product, per-facet, or rule-targeted app data
@@ -499,6 +500,8 @@ interface ResponseTool {
   name?: string
   description?: string
   parameters?: Record<string, any>
+  output_schema?: Record<string, any>
+  allowed_callers?: Array<'assistant' | 'programmatic'>
   [key: string]: any
 }
 ```
@@ -544,6 +547,11 @@ interface ResponsesRequest {
   text?: Record<string, any>
   metadata?: Record<string, string>
   prompt_cache_key?: string
+  multi_agent?: {
+  enabled: boolean
+  max_concurrent_subagents?: number
+  }
+  service_tier?: 'auto' | 'standard' | 'flex' | 'priority'
 }
 ```
 
@@ -6939,6 +6947,37 @@ interface ProductQueryResponse {
 }
 ```
 
+**ScopedFieldOption** (interface)
+```typescript
+interface ScopedFieldOption {
+  value: string
+  label: string
+}
+```
+
+**ScopedFieldDef** (interface)
+```typescript
+interface ScopedFieldDef {
+  key: string
+  label: string
+  type: ScopedFieldType
+  required?: boolean
+  placeholder?: string
+  help?: string
+  options?: ScopedFieldOption[]
+  defaultValue?: JsonValue
+  showInTable?: boolean
+  showInDetail?: boolean
+}
+```
+
+**ProductFieldsConfig** (interface)
+```typescript
+interface ProductFieldsConfig {
+  fields: ProductFieldDef[]
+}
+```
+
 **JsonPrimitive** = `string | number | boolean | null`
 
 **JsonValue** = ``
@@ -6955,8 +6994,23 @@ interface ProductQueryResponse {
 
 **ProductUpdateRequest** = `Partial<Omit<ProductWriteInput, 'id'>>`
 
+**ScopedFieldType** = ``
+
+**ProductFieldScope** = `'public' | 'admin'`
+
+**ProductFieldDef** = `ScopedFieldDef & { scope?: ProductFieldScope }`
+
 ### proof
 
+**ProofValues** (interface)
+```typescript
+interface ProofValues {
+  [key: string]: JsonValue | Record<string, JsonValue> | Record<string, Record<string, JsonValue>> | undefined
+  owner?: Record<string, JsonValue>
+  personal?: Record<string, Record<string, JsonValue>>
+}
+```
+
 **Proof** (interface)
 ```typescript
 interface Proof {
@@ -6968,25 +7022,40 @@ interface Proof {
   userId: string
   claimable?: boolean
   virtual?: boolean
-  values: Record<string, any>
+  data?: Record<string, JsonValue>
+  admin?: Record<string, JsonValue>
+  values: ProofValues
 }
 ```
 
 **ProofCreateRequest** (interface)
 ```typescript
 interface ProofCreateRequest {
-  values: Record<string, any>
+  values: ProofValues
+  data?: Record<string, JsonValue>
+  admin?: Record<string, JsonValue>
   claimable?: boolean
   virtual?: boolean
 }
 ```
 
+**ProofFieldsConfig** (interface)
+```typescript
+interface ProofFieldsConfig {
+  fields: ProofFieldDef[]
+}
+```
+
 **ProofResponse** = `Proof`
 
 **ProofUpdateRequest** = `Partial<ProofCreateRequest>`
 
 **ProofClaimRequest** = `Record<string, any>`
 
+**ProofFieldScope** = `'public' | 'owner' | 'personal' | 'admin'`
+
+**ProofFieldDef** = `ScopedFieldDef & { scope?: ProofFieldScope }`
+
 ### qr
 
 **QrShortCodeLookupResponse** (interface)

package/dist/docs/ai.md

@@ -251,6 +251,100 @@ const response = await ai.chat.responses.create('my-collection', {
 console.log(response.output);
 ```
 
+### Recommended Models
+
+For agentic workflows on `v1/responses`, GPT-5.6 ships in three tiers. Pass either the full model
+id (`openai/gpt-5.6-sol`) or the shorthand tier alias (`'cheap'`, `'balanced'`, `'premium'`) as
+`model` — both resolve through the same server-side model registry.
+
+| Tier | Model | Alias | Use for |
+|------|-------|-------|---------|
+| Cheapest (default) | `openai/gpt-5.6-luna` | `'cheap'` / omit `model` | Everyday chat, high-volume/simple turns |
+| Balanced | `openai/gpt-5.6-terra` | `'balanced'` | Admin agent / tool-heavy setup workflows (route default) |
+| Flagship | `openai/gpt-5.6-sol` | `'premium'` | Most demanding reasoning, coding, and multi-step tool use |
+
+Every tier supports function/tool calling, Programmatic Tool Calling, and Multi-agent (see below), and all
+three accept `service_tier: 'flex'` (≈50% cheaper, Batch-API rates, slower) or `'priority'` (premium, guaranteed
+throughput) alongside the default `'standard'` tier. Pass it straight through in the request body:
+
+```typescript
+const response = await ai.chat.responses.create('my-collection', {
+  model: 'balanced',
+  input: 'Summarize this week\'s ingested documents.',
+  service_tier: 'flex' // non-interactive/background work: cheaper, but can take minutes
+});
+```
+
+Flex requests run noticeably slower — reserve `flex` for non-production/background work (batch enrichment,
+evaluations, async jobs), not user-facing chat turns. The server already raises its own timeout to 15
+minutes for any request with `service_tier: 'flex'`, matching OpenAI's guidance — nothing to configure on
+the client. On a `429` ("resource unavailable") the request wasn't charged; retry with backoff or drop
+`service_tier` (or set it to `'auto'`) to fall back to standard processing.
+
+### Programmatic Tool Calling
+
+Lets the model write a short in-memory program that orchestrates several tool calls (filtering,
+looping, aggregating) before handing back one result, instead of a full message round-trip per
+call. Add the hosted `programmatic_tool_calling` tool, and mark each function tool the program is
+allowed to invoke with `allowed_callers: ['programmatic']`:
+
+```typescript
+const response = await ai.chat.responses.create('my-collection', {
+  model: 'balanced',
+  input: 'Compare inventory with demand for every SKU in this collection.',
+  tools: [
+    {
+      type: 'function',
+      name: 'get_inventory',
+      description: 'Return available_units for a sku',
+      parameters: { type: 'object', properties: { sku: { type: 'string' } }, required: ['sku'] },
+      output_schema: { type: 'object', properties: { sku: { type: 'string' }, available_units: { type: 'number' } } },
+      allowed_callers: ['programmatic']
+    },
+    {
+      type: 'function',
+      name: 'get_demand',
+      description: 'Return requested_units for a sku',
+      parameters: { type: 'object', properties: { sku: { type: 'string' } }, required: ['sku'] },
+      output_schema: { type: 'object', properties: { sku: { type: 'string' }, requested_units: { type: 'number' } } },
+      allowed_callers: ['programmatic']
+    },
+    { type: 'programmatic_tool_calling' }
+  ]
+});
+```
+
+The response's `output` array can include a `program` item (the generated code), one
+`function_call` item per program-issued call (tagged with `caller: { type: 'program', caller_id }`),
+and a `program_output` item with the program's final `result`/`status`. Execute the `function_call`
+items as normal and send results back keyed by their `call_id` on the next turn.
+
+### Multi-agent (subagents)
+
+Lets the root agent spawn a tree of subagents that run in parallel and get synthesized back into
+one response — useful for tasks that split cleanly into independent workstreams (e.g. research +
+draft + review). Enable it by setting `multi_agent.enabled: true` — that's the entire contract on
+your end; nothing else to configure or pass.
+
+This is upstream beta functionality (OpenAI may still be limiting it to certain accounts/rollout),
+so treat behavior and availability as subject to change until it's GA.
+
+```typescript
+const response = await ai.chat.responses.create('my-collection', {
+  model: 'premium', // Sol recommended for the root agent when spawning subagents
+  input: 'Research three competitor loyalty programs, then draft a comparison summary.',
+  multi_agent: { enabled: true, max_concurrent_subagents: 3 }
+});
+```
+
+Subagent output arrives as additional items in `output`, each tagged `agent: { agent_name: '/root/<name>' }`
+(root agent output uses `/root`). Notes/limits carried over from OpenAI's beta:
+
+- `max_concurrent_subagents` defaults to `3`
+- `reasoning.summary` and `max_tool_calls` are not supported while multi-agent is enabled
+- Streaming is not supported while multi-agent is enabled — the SDK throws if you pass both
+  `stream: true` and `multi_agent.enabled: true`
+
 ---
 
 ## Chat Completions

package/dist/docs/app-data-storage.md

@@ -2,6 +2,8 @@
 
 The SmartLinks platform provides two distinct types of data storage for apps:
 
+> **Not what you're looking for?** This guide covers app-owned config/records scoped to a collection or product. For the core product/proof documents themselves — `product.data`/`.admin`, `proof.data`/`.admin`/`.values` (owner/personal) — see [proof-product-data-scoping.md](proof-product-data-scoping.md).
+
 ## Choose the Right Model First
 
 There are now two different families of flexible app data in SmartLinks, and they solve different problems:

package/dist/docs/overview.md

@@ -80,6 +80,7 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **Contact Search** | `docs/contact-search.md` | Admin contact search: free-text, typeahead, identity/tag/JSONB filters, and pagination |
 | **App Records Pattern** | `docs/app-records-pattern.md` | Standard pattern for per-product/facet/variant/batch admin + public widget UIs |
 | **UI Utils** | `docs/ui-utils.md` | `@proveanything/smartlinks-utils-ui` — React shells, hooks, and primitives for records-based apps |
+| **Product/Proof Data Scoping** | `docs/proof-product-data-scoping.md` | Canonical spec for `product.data`/`.admin` and `proof.data`/`.admin`/`.values` (owner/personal) — who can read and write each bucket |
 
 ---
 
@@ -204,6 +205,12 @@ Prefer `app.records` over `setDataItem` when the data is becoming a real entity
 
 For data attached to specific proof instances, use `SL.attestation.create()` and `SL.attestation.list()`.
 
+### Custom Data Scoping (Product & Proof)
+
+`product.data`/`product.admin` and `proof.data`/`proof.admin`/`proof.values` are the canonical buckets for custom fields on products and proofs — `data` is public and business-writable, `admin` is business-only, and `proof.values` additionally supports owner-scoped (`values.owner`) and per-user (`values.personal[userId]`) sub-keys. This is a different mechanism from the app-scoped storage in `docs/app-data-storage.md` (which is for app-owned config/records, not the product/proof documents themselves).
+
+See `docs/proof-product-data-scoping.md` for the full read/write authority matrix, worked examples, and the `productFields`/`proofFields` collection-settings schemas that drive field-config editors.
+
 ---
 
 ## Error Handling