@proveanything/smartlinks 1.15.1 → 1.15.3

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/api/collection.d.ts

@@ -34,6 +34,18 @@ export declare namespace collection {
      * @throws ErrorResponse (404) if no collection is mapped to the domain
      */
     function getByHub(): Promise<CollectionResponse>;
+    /**
+     * Resolve the collection for an explicit Hub domain (public endpoint).
+     *
+     * Unlike {@link getByHub}, the domain is passed explicitly rather than derived
+     * from request headers — use this for raw/cross-origin calls where the Hub
+     * frontend knows its own hostname (e.g. "erbauer.mysmartlinks.app").
+     *
+     * @param domain – The Hub domain to resolve (custom domain or {brand}.mysmartlinks.app)
+     * @returns Promise resolving to the CollectionResponse mapped to the domain
+     * @throws ErrorResponse (404) if no collection is mapped to the domain
+     */
+    function getByDomain(domain: string): Promise<CollectionResponse>;
     /**
      * Check whether a Hub subdomain name is available to claim (admin only).
      * @param collectionId – Identifier of the collection making the request

package/dist/api/collection.js

@@ -54,6 +54,22 @@ export var collection;
         return request(path);
     }
     collection.getByHub = getByHub;
+    /**
+     * Resolve the collection for an explicit Hub domain (public endpoint).
+     *
+     * Unlike {@link getByHub}, the domain is passed explicitly rather than derived
+     * from request headers — use this for raw/cross-origin calls where the Hub
+     * frontend knows its own hostname (e.g. "erbauer.mysmartlinks.app").
+     *
+     * @param domain – The Hub domain to resolve (custom domain or {brand}.mysmartlinks.app)
+     * @returns Promise resolving to the CollectionResponse mapped to the domain
+     * @throws ErrorResponse (404) if no collection is mapped to the domain
+     */
+    async function getByDomain(domain) {
+        const path = `/public/collection/by-domain/${encodeURIComponent(domain)}`;
+        return request(path);
+    }
+    collection.getByDomain = getByDomain;
     /**
      * Check whether a Hub subdomain name is available to claim (admin only).
      * @param collectionId – Identifier of the collection making the request

package/dist/api/facets.d.ts

@@ -1,4 +1,4 @@
-import type { FacetDefinition, FacetDefinitionWriteInput, FacetGetParams, FacetListParams, FacetListResponse, FacetQueryRequest, FacetQueryResponse, FacetValueGetParams, FacetValueListParams, FacetValueListResponse, FacetValueResponse, FacetValueWriteInput, PublicFacetListParams } from "../types/facets";
+import type { FacetDefinition, FacetDefinitionWriteInput, FacetGetParams, FacetListParams, FacetListResponse, FacetNamespaceListResponse, FacetQueryRequest, FacetQueryResponse, FacetValueGetParams, FacetValueListParams, FacetValueListResponse, FacetValueResponse, FacetValueWriteInput, PublicFacetListParams } from "../types/facets";
 /**
  * Facet management and aggregation endpoints.
  *
@@ -18,9 +18,11 @@ export declare namespace facets {
     function updateValue(collectionId: string, facetKey: string, valueKey: string, data: FacetValueWriteInput): Promise<FacetValueResponse>;
     function removeValue(collectionId: string, facetKey: string, valueKey: string): Promise<void>;
     function query(collectionId: string, body: FacetQueryRequest): Promise<FacetQueryResponse>;
+    function namespaces(collectionId: string): Promise<FacetNamespaceListResponse>;
     function publicList(collectionId: string, params?: PublicFacetListParams): Promise<FacetListResponse>;
     function publicGet(collectionId: string, facetKey: string, params?: PublicFacetListParams): Promise<FacetDefinition>;
     function publicListValues(collectionId: string, facetKey: string): Promise<FacetValueListResponse>;
     function publicGetValue(collectionId: string, facetKey: string, valueKey: string): Promise<FacetValueResponse>;
     function publicQuery(collectionId: string, body: FacetQueryRequest): Promise<FacetQueryResponse>;
+    function publicNamespaces(collectionId: string): Promise<FacetNamespaceListResponse>;
 }

package/dist/api/facets.js

@@ -78,6 +78,11 @@ export var facets;
         return post(path, body);
     }
     facets.query = query;
+    async function namespaces(collectionId) {
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/facets/namespaces`;
+        return request(path);
+    }
+    facets.namespaces = namespaces;
     async function publicList(collectionId, params) {
         const path = `/public/collection/${encodeURIComponent(collectionId)}/facets${buildQueryString(params)}`;
         return request(path);
@@ -103,4 +108,9 @@ export var facets;
         return post(path, body);
     }
     facets.publicQuery = publicQuery;
+    async function publicNamespaces(collectionId) {
+        const path = `/public/collection/${encodeURIComponent(collectionId)}/facets/namespaces`;
+        return request(path);
+    }
+    facets.publicNamespaces = publicNamespaces;
 })(facets || (facets = {}));

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.15.1  |  Generated: 2026-06-13T08:46:42.914Z
+Version: 1.15.3  |  Generated: 2026-07-11T13:25:50.969Z
 
 This is a concise summary of all available API functions and types.
 
@@ -499,6 +499,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 +546,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'
 }
 ```
 
@@ -5039,6 +5046,7 @@ interface FacetDefinition {
   key: string
   name: string
   description?: string | null
+  namespace?: string | null
   cardinality?: "single" | "multi"
   kind?: "system" | "custom"
   hierarchical?: boolean
@@ -5087,6 +5095,7 @@ interface FacetDefinitionWriteInput {
   key?: string
   name: string
   description?: string | null
+  namespace?: string | null
   cardinality?: "single" | "multi"
   kind?: "system" | "custom"
   hierarchical?: boolean
@@ -5144,6 +5153,7 @@ interface FacetQueryRequest {
   facetKeys?: string[]
   includeEmpty?: boolean
   includeDeleted?: boolean
+  namespace?: string | null
   query?: ProductQueryRequest["query"] & {
   facetEquals?: Record<string, JsonValue | JsonValue[]>
   }
@@ -5182,6 +5192,7 @@ interface FacetListParams {
   includeDeleted?: boolean
   kind?: "system" | "custom"
   reserved?: boolean
+  namespace?: string
 }
 ```
 
@@ -5189,6 +5200,14 @@ interface FacetListParams {
 ```typescript
 interface PublicFacetListParams {
   includeValues?: boolean
+  namespace?: string
+}
+```
+
+**FacetNamespaceListResponse** (interface)
+```typescript
+interface FacetNamespaceListResponse {
+  namespaces: string[]
 }
 ```
 
@@ -8619,6 +8638,9 @@ Retrieve a collection by its shortId (public endpoint).
 **getByHub**() → `Promise<CollectionResponse>`
 Resolve the collection for the current Hub domain (public endpoint). The server derives the requesting domain from the request headers (`X-Source-Domain` / `X-Forwarded-Host` / `Host`), so no identifier is passed — this is the call a Hub frontend makes on load to find out which collection it is serving, whether it's reached via `{brand}.mysmartlinks.app` or a bring-your-own custom domain (e.g. `hub.acme.com`).
 
+**getByDomain**(domain: string) → `Promise<CollectionResponse>`
+Resolve the collection for an explicit Hub domain (public endpoint). Unlike {@link getByHub}, the domain is passed explicitly rather than derived from request headers — use this for raw/cross-origin calls where the Hub frontend knows its own hostname (e.g. "erbauer.mysmartlinks.app").
+
 **checkHubAvailability**(collectionId: string, name: string) → `Promise<HubAvailabilityResponse>`
 Check whether a Hub subdomain name is available to claim (admin only).
 
@@ -8942,6 +8964,8 @@ Delete a crate for a collection (admin only). This performs a soft delete. ```ty
 **query**(collectionId: string,
     body: FacetQueryRequest) → `Promise<FacetQueryResponse>`
 
+**namespaces**(collectionId: string) → `Promise<FacetNamespaceListResponse>`
+
 **publicList**(collectionId: string,
     params?: PublicFacetListParams) → `Promise<FacetListResponse>`
 
@@ -8959,6 +8983,8 @@ Delete a crate for a collection (admin only). This performs a soft delete. ```ty
 **publicQuery**(collectionId: string,
     body: FacetQueryRequest) → `Promise<FacetQueryResponse>`
 
+**publicNamespaces**(collectionId: string) → `Promise<FacetNamespaceListResponse>`
+
 ### form
 
 **get**(collectionId: string, formId: string, admin?: boolean) → `Promise<any>`

package/dist/docs/PRODUCT_FACETS_SDK.md

@@ -42,6 +42,21 @@ includeValues?: boolean
 includeDeleted?: boolean
 kind?: 'system' | 'custom'
 reserved?: boolean
+namespace?: string
+```
+
+When `namespace` is provided, returns facets matching that namespace plus global facets (`namespace: null`). Omit the param to return all facets.
+
+### List namespaces
+
+```ts
+GET /api/v1/admin/collection/:collectionId/facets/namespaces
+```
+
+Returns all distinct namespaces in use for the collection (excludes globals).
+
+```ts
+{ namespaces: string[] }
 ```
 
 ### Create facet definition
@@ -50,6 +65,8 @@ reserved?: boolean
 POST /api/v1/admin/collection/:collectionId/facets
 ```
 
+Pass `namespace` in the body to scope the facet to a domain (e.g. `"dpp"`, `"nutrition"`). Omit it to create a global facet.
+
 ### Get facet definition
 
 ```ts
@@ -146,6 +163,8 @@ Supported query filters now:
 - `tags`
 - `facetEquals`
 
+Body also accepts `namespace` (optional) to scope aggregation to a namespace plus global facets.
+
 ## Public endpoints
 
 ### List facet definitions
@@ -158,6 +177,21 @@ Optional query params:
 
 ```ts
 includeValues?: boolean
+namespace?: string
+```
+
+When `namespace` is provided, returns facets matching that namespace plus global facets (`namespace: null`). Omit the param to return all facets.
+
+### List namespaces
+
+```ts
+GET /api/v1/public/collection/:collectionId/facets/namespaces
+```
+
+Returns all distinct namespaces in use for the collection (excludes globals).
+
+```ts
+{ namespaces: string[] }
 ```
 
 ### Get facet definition
@@ -215,6 +249,7 @@ export interface FacetDefinition {
   key: string
   name: string
   description?: string | null
+  namespace?: string | null
   cardinality: 'single' | 'multi'
   kind: 'system' | 'custom'
   hierarchical: boolean
@@ -230,6 +265,7 @@ export interface FacetDefinitionWriteInput {
   key?: string
   name: string
   description?: string | null
+  namespace?: string | null
   cardinality?: 'single' | 'multi'
   kind?: 'system' | 'custom'
   hierarchical?: boolean
@@ -305,6 +341,7 @@ export interface FacetQueryRequest {
   facetKeys?: string[]
   includeEmpty?: boolean
   includeDeleted?: boolean
+  namespace?: string | null
   query?: {
     search?: string
     status?: string[]
@@ -326,6 +363,10 @@ export interface FacetBucket {
   count: number
 }
 
+export interface FacetNamespaceListResponse {
+  namespaces: string[]
+}
+
 export interface FacetQueryResponse {
   items: Array<{
     facet: FacetDefinition
@@ -344,4 +385,5 @@ export interface FacetQueryResponse {
 - treat facet definitions and facet values as collection-scoped resources
 - use the facet API to manage definitions and values
 - use product read/write routes to assign facet data onto products
-- treat `label` and `category` as reserved system facets when present
+- treat `label` and `category` as reserved system facets when present
+- facets with `namespace: null` are global and appear in all contexts; namespaced facets belong to a specific domain (e.g. `"dpp"`, `"nutrition"`)

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/index.d.ts

@@ -15,7 +15,7 @@ export type { BroadcastSendRequest } from "./types/broadcasts";
 export type { AppConfigOptions } from "./api/appConfiguration";
 export type { AdditionalGtin, ISODateString, JsonPrimitive, JsonValue, ProductCreateRequest, ProductClaimCreateInput, ProductClaimCreateRequestBody, ProductClaimLookupInput, ProductFacetMap, ProductFacetValue, ProductImageUrlInput, ProductKey, ProductQueryRequest, ProductQueryResponse, ProductUpdateRequest, Product, ProductWriteInput, PublicProduct, } from "./types/product";
 export type { TranslationLookupMode, TranslationContentType, TranslationQuality, TranslationItemStatus, TranslationContextValue, TranslationContext, TranslationLookupRequestBase, TranslationLookupSingleRequest, TranslationLookupBatchRequest, TranslationLookupRequest, TranslationLookupItem, TranslationLookupResponse, ResolvedTranslationItem, ResolvedTranslationResponse, TranslationHashOptions, TranslationResolveOptions, TranslationRecord, TranslationListParams, TranslationListResponse, TranslationUpdateRequest, } from "./types/translations";
-export type { FacetBucket, FacetDefinition, FacetDefinitionWriteInput, FacetGetParams, FacetListParams, FacetListResponse, FacetQueryRequest, FacetQueryResponse, FacetValue, FacetValueDefinition, FacetValueGetParams, FacetValueListParams, FacetValueListResponse, FacetValueResponse, FacetValueWriteInput, PublicFacetListParams, } from "./types/facets";
+export type { FacetBucket, FacetDefinition, FacetDefinitionWriteInput, FacetGetParams, FacetListParams, FacetListResponse, FacetNamespaceListResponse, FacetQueryRequest, FacetQueryResponse, FacetValue, FacetValueDefinition, FacetValueGetParams, FacetValueListParams, FacetValueListResponse, FacetValueResponse, FacetValueWriteInput, PublicFacetListParams, } from "./types/facets";
 export type { Collection, CollectionResponse, CollectionCreateRequest, CollectionUpdateRequest, DomainTarget, HubAvailabilityResponse, } from "./types/collection";
 export type { Proof, ProofResponse, ProofCreateRequest, ProofUpdateRequest, ProofClaimRequest, } from "./types/proof";
 export type { QrShortCodeLookupResponse, } from "./types/qr";

package/dist/openapi.yaml

@@ -3429,6 +3429,11 @@ paths:
           required: false
           schema:
             type: boolean
+        - name: namespace
+          in: query
+          required: false
+          schema:
+            type: string
       responses:
         200:
           description: Success
@@ -3474,6 +3479,33 @@ paths:
           application/json:
             schema:
               $ref: "#/components/schemas/FacetDefinitionWriteInput"
+  /admin/collection/{collectionId}/facets/namespaces:
+    get:
+      tags:
+        - facets
+      summary: facets.namespaces
+      operationId: facets_namespaces
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/FacetNamespaceListResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
   /admin/collection/{collectionId}/facets/query:
     post:
       tags:
@@ -9316,6 +9348,32 @@ paths:
           application/json:
             schema:
               $ref: "#/components/schemas/RequestUploadTokenOptions"
+  /public/collection/by-domain/{domain}:
+    get:
+      tags:
+        - collection
+      summary: Resolve the collection for an explicit Hub domain (public endpoint).
+      operationId: collection_getByDomain
+      security: []
+      parameters:
+        - name: domain
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CollectionResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
   /public/collection/getByHub:
     get:
       tags:
@@ -10811,6 +10869,11 @@ paths:
           required: false
           schema:
             type: boolean
+        - name: namespace
+          in: query
+          required: false
+          schema:
+            type: string
       responses:
         200:
           description: Success
@@ -10824,6 +10887,32 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /public/collection/{collectionId}/facets/namespaces:
+    get:
+      tags:
+        - facets
+      summary: facets.publicNamespaces
+      operationId: facets_publicNamespaces
+      security: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/FacetNamespaceListResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
   /public/collection/{collectionId}/facets/query:
     post:
       tags:
@@ -10879,6 +10968,11 @@ paths:
           required: false
           schema:
             type: boolean
+        - name: namespace
+          in: query
+          required: false
+          schema:
+            type: string
       responses:
         200:
           description: Success
@@ -13870,6 +13964,16 @@ components:
         parameters:
           type: object
           additionalProperties: true
+        output_schema:
+          type: object
+          additionalProperties: true
+        allowed_callers:
+          type: array
+          items:
+            type: string
+            enum:
+              - assistant
+              - programmatic
       required:
         - type
     ResponseInputItem:
@@ -13958,6 +14062,22 @@ components:
             type: string
         prompt_cache_key:
           type: string
+        multi_agent:
+          type: object
+          additionalProperties: true
+        enabled:
+          type: boolean
+        max_concurrent_subagents:
+          type: number
+        service_tier:
+          type: string
+          enum:
+            - auto
+            - standard
+            - flex
+            - priority
+      required:
+        - enabled
     ResponsesResult:
       type: object
       properties:
@@ -20697,6 +20817,8 @@ components:
           type: string
         description:
           type: string
+        namespace:
+          type: string
         cardinality:
           type: object
           additionalProperties: true
@@ -20792,6 +20914,8 @@ components:
           type: string
         description:
           type: string
+        namespace:
+          type: string
         cardinality:
           type: object
           additionalProperties: true
@@ -20887,6 +21011,8 @@ components:
           type: boolean
         includeDeleted:
           type: boolean
+        namespace:
+          type: string
         query:
           type: object
           additionalProperties: true
@@ -20954,11 +21080,24 @@ components:
           additionalProperties: true
         reserved:
           type: boolean
+        namespace:
+          type: string
     PublicFacetListParams:
       type: object
       properties:
         includeValues:
           type: boolean
+        namespace:
+          type: string
+    FacetNamespaceListResponse:
+      type: object
+      properties:
+        namespaces:
+          type: array
+          items:
+            type: string
+      required:
+        - namespaces
     FacetGetParams:
       type: object
       properties:

package/dist/types/ai.d.ts

@@ -56,6 +56,10 @@ export interface ResponseTool {
     name?: string;
     description?: string;
     parameters?: Record<string, any>;
+    /** Expected shape of this tool's output, used by Programmatic Tool Calling. */
+    output_schema?: Record<string, any>;
+    /** Restricts which callers may invoke this tool (e.g. `['programmatic']` for Programmatic Tool Calling). */
+    allowed_callers?: Array<'assistant' | 'programmatic'>;
     [key: string]: any;
 }
 /** Structured input item accepted by the Responses API. */
@@ -98,6 +102,13 @@ export interface ResponsesRequest {
     text?: Record<string, any>;
     metadata?: Record<string, string>;
     prompt_cache_key?: string;
+    /** Enables multi-agent (subagent) orchestration. Not supported together with `stream: true`. */
+    multi_agent?: {
+        enabled: boolean;
+        max_concurrent_subagents?: number;
+    };
+    /** `'flex'` is ~50% cheaper at Batch-API rates but slower; reserve for non-interactive/background work. */
+    service_tier?: 'auto' | 'standard' | 'flex' | 'priority';
 }
 /** Response from the Responses API. */
 export interface ResponsesResult {

package/dist/types/facets.d.ts

@@ -6,6 +6,7 @@ export interface FacetDefinition {
     key: string;
     name: string;
     description?: string | null;
+    namespace?: string | null;
     cardinality?: "single" | "multi";
     kind?: "system" | "custom";
     hierarchical?: boolean;
@@ -46,6 +47,7 @@ export interface FacetDefinitionWriteInput {
     key?: string;
     name: string;
     description?: string | null;
+    namespace?: string | null;
     cardinality?: "single" | "multi";
     kind?: "system" | "custom";
     hierarchical?: boolean;
@@ -83,6 +85,7 @@ export interface FacetQueryRequest {
     facetKeys?: string[];
     includeEmpty?: boolean;
     includeDeleted?: boolean;
+    namespace?: string | null;
     query?: ProductQueryRequest["query"] & {
         facetEquals?: Record<string, JsonValue | JsonValue[]>;
     };
@@ -109,9 +112,14 @@ export interface FacetListParams {
     includeDeleted?: boolean;
     kind?: "system" | "custom";
     reserved?: boolean;
+    namespace?: string;
 }
 export interface PublicFacetListParams {
     includeValues?: boolean;
+    namespace?: string;
+}
+export interface FacetNamespaceListResponse {
+    namespaces: string[];
 }
 export interface FacetGetParams {
     includeValues?: boolean;

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.15.1  |  Generated: 2026-06-13T08:46:42.914Z
+Version: 1.15.3  |  Generated: 2026-07-11T13:25:50.969Z
 
 This is a concise summary of all available API functions and types.
 
@@ -499,6 +499,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 +546,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'
 }
 ```
 
@@ -5039,6 +5046,7 @@ interface FacetDefinition {
   key: string
   name: string
   description?: string | null
+  namespace?: string | null
   cardinality?: "single" | "multi"
   kind?: "system" | "custom"
   hierarchical?: boolean
@@ -5087,6 +5095,7 @@ interface FacetDefinitionWriteInput {
   key?: string
   name: string
   description?: string | null
+  namespace?: string | null
   cardinality?: "single" | "multi"
   kind?: "system" | "custom"
   hierarchical?: boolean
@@ -5144,6 +5153,7 @@ interface FacetQueryRequest {
   facetKeys?: string[]
   includeEmpty?: boolean
   includeDeleted?: boolean
+  namespace?: string | null
   query?: ProductQueryRequest["query"] & {
   facetEquals?: Record<string, JsonValue | JsonValue[]>
   }
@@ -5182,6 +5192,7 @@ interface FacetListParams {
   includeDeleted?: boolean
   kind?: "system" | "custom"
   reserved?: boolean
+  namespace?: string
 }
 ```
 
@@ -5189,6 +5200,14 @@ interface FacetListParams {
 ```typescript
 interface PublicFacetListParams {
   includeValues?: boolean
+  namespace?: string
+}
+```
+
+**FacetNamespaceListResponse** (interface)
+```typescript
+interface FacetNamespaceListResponse {
+  namespaces: string[]
 }
 ```
 
@@ -8619,6 +8638,9 @@ Retrieve a collection by its shortId (public endpoint).
 **getByHub**() → `Promise<CollectionResponse>`
 Resolve the collection for the current Hub domain (public endpoint). The server derives the requesting domain from the request headers (`X-Source-Domain` / `X-Forwarded-Host` / `Host`), so no identifier is passed — this is the call a Hub frontend makes on load to find out which collection it is serving, whether it's reached via `{brand}.mysmartlinks.app` or a bring-your-own custom domain (e.g. `hub.acme.com`).
 
+**getByDomain**(domain: string) → `Promise<CollectionResponse>`
+Resolve the collection for an explicit Hub domain (public endpoint). Unlike {@link getByHub}, the domain is passed explicitly rather than derived from request headers — use this for raw/cross-origin calls where the Hub frontend knows its own hostname (e.g. "erbauer.mysmartlinks.app").
+
 **checkHubAvailability**(collectionId: string, name: string) → `Promise<HubAvailabilityResponse>`
 Check whether a Hub subdomain name is available to claim (admin only).
 
@@ -8942,6 +8964,8 @@ Delete a crate for a collection (admin only). This performs a soft delete. ```ty
 **query**(collectionId: string,
     body: FacetQueryRequest) → `Promise<FacetQueryResponse>`
 
+**namespaces**(collectionId: string) → `Promise<FacetNamespaceListResponse>`
+
 **publicList**(collectionId: string,
     params?: PublicFacetListParams) → `Promise<FacetListResponse>`
 
@@ -8959,6 +8983,8 @@ Delete a crate for a collection (admin only). This performs a soft delete. ```ty
 **publicQuery**(collectionId: string,
     body: FacetQueryRequest) → `Promise<FacetQueryResponse>`
 
+**publicNamespaces**(collectionId: string) → `Promise<FacetNamespaceListResponse>`
+
 ### form
 
 **get**(collectionId: string, formId: string, admin?: boolean) → `Promise<any>`

package/docs/PRODUCT_FACETS_SDK.md

@@ -42,6 +42,21 @@ includeValues?: boolean
 includeDeleted?: boolean
 kind?: 'system' | 'custom'
 reserved?: boolean
+namespace?: string
+```
+
+When `namespace` is provided, returns facets matching that namespace plus global facets (`namespace: null`). Omit the param to return all facets.
+
+### List namespaces
+
+```ts
+GET /api/v1/admin/collection/:collectionId/facets/namespaces
+```
+
+Returns all distinct namespaces in use for the collection (excludes globals).
+
+```ts
+{ namespaces: string[] }
 ```
 
 ### Create facet definition
@@ -50,6 +65,8 @@ reserved?: boolean
 POST /api/v1/admin/collection/:collectionId/facets
 ```
 
+Pass `namespace` in the body to scope the facet to a domain (e.g. `"dpp"`, `"nutrition"`). Omit it to create a global facet.
+
 ### Get facet definition
 
 ```ts
@@ -146,6 +163,8 @@ Supported query filters now:
 - `tags`
 - `facetEquals`
 
+Body also accepts `namespace` (optional) to scope aggregation to a namespace plus global facets.
+
 ## Public endpoints
 
 ### List facet definitions
@@ -158,6 +177,21 @@ Optional query params:
 
 ```ts
 includeValues?: boolean
+namespace?: string
+```
+
+When `namespace` is provided, returns facets matching that namespace plus global facets (`namespace: null`). Omit the param to return all facets.
+
+### List namespaces
+
+```ts
+GET /api/v1/public/collection/:collectionId/facets/namespaces
+```
+
+Returns all distinct namespaces in use for the collection (excludes globals).
+
+```ts
+{ namespaces: string[] }
 ```
 
 ### Get facet definition
@@ -215,6 +249,7 @@ export interface FacetDefinition {
   key: string
   name: string
   description?: string | null
+  namespace?: string | null
   cardinality: 'single' | 'multi'
   kind: 'system' | 'custom'
   hierarchical: boolean
@@ -230,6 +265,7 @@ export interface FacetDefinitionWriteInput {
   key?: string
   name: string
   description?: string | null
+  namespace?: string | null
   cardinality?: 'single' | 'multi'
   kind?: 'system' | 'custom'
   hierarchical?: boolean
@@ -305,6 +341,7 @@ export interface FacetQueryRequest {
   facetKeys?: string[]
   includeEmpty?: boolean
   includeDeleted?: boolean
+  namespace?: string | null
   query?: {
     search?: string
     status?: string[]
@@ -326,6 +363,10 @@ export interface FacetBucket {
   count: number
 }
 
+export interface FacetNamespaceListResponse {
+  namespaces: string[]
+}
+
 export interface FacetQueryResponse {
   items: Array<{
     facet: FacetDefinition
@@ -344,4 +385,5 @@ export interface FacetQueryResponse {
 - treat facet definitions and facet values as collection-scoped resources
 - use the facet API to manage definitions and values
 - use product read/write routes to assign facet data onto products
-- treat `label` and `category` as reserved system facets when present
+- treat `label` and `category` as reserved system facets when present
+- facets with `namespace: null` are global and appear in all contexts; namespaced facets belong to a specific domain (e.g. `"dpp"`, `"nutrition"`)

package/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/openapi.yaml

@@ -3429,6 +3429,11 @@ paths:
           required: false
           schema:
             type: boolean
+        - name: namespace
+          in: query
+          required: false
+          schema:
+            type: string
       responses:
         200:
           description: Success
@@ -3474,6 +3479,33 @@ paths:
           application/json:
             schema:
               $ref: "#/components/schemas/FacetDefinitionWriteInput"
+  /admin/collection/{collectionId}/facets/namespaces:
+    get:
+      tags:
+        - facets
+      summary: facets.namespaces
+      operationId: facets_namespaces
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/FacetNamespaceListResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
   /admin/collection/{collectionId}/facets/query:
     post:
       tags:
@@ -9316,6 +9348,32 @@ paths:
           application/json:
             schema:
               $ref: "#/components/schemas/RequestUploadTokenOptions"
+  /public/collection/by-domain/{domain}:
+    get:
+      tags:
+        - collection
+      summary: Resolve the collection for an explicit Hub domain (public endpoint).
+      operationId: collection_getByDomain
+      security: []
+      parameters:
+        - name: domain
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CollectionResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
   /public/collection/getByHub:
     get:
       tags:
@@ -10811,6 +10869,11 @@ paths:
           required: false
           schema:
             type: boolean
+        - name: namespace
+          in: query
+          required: false
+          schema:
+            type: string
       responses:
         200:
           description: Success
@@ -10824,6 +10887,32 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /public/collection/{collectionId}/facets/namespaces:
+    get:
+      tags:
+        - facets
+      summary: facets.publicNamespaces
+      operationId: facets_publicNamespaces
+      security: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/FacetNamespaceListResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
   /public/collection/{collectionId}/facets/query:
     post:
       tags:
@@ -10879,6 +10968,11 @@ paths:
           required: false
           schema:
             type: boolean
+        - name: namespace
+          in: query
+          required: false
+          schema:
+            type: string
       responses:
         200:
           description: Success
@@ -13870,6 +13964,16 @@ components:
         parameters:
           type: object
           additionalProperties: true
+        output_schema:
+          type: object
+          additionalProperties: true
+        allowed_callers:
+          type: array
+          items:
+            type: string
+            enum:
+              - assistant
+              - programmatic
       required:
         - type
     ResponseInputItem:
@@ -13958,6 +14062,22 @@ components:
             type: string
         prompt_cache_key:
           type: string
+        multi_agent:
+          type: object
+          additionalProperties: true
+        enabled:
+          type: boolean
+        max_concurrent_subagents:
+          type: number
+        service_tier:
+          type: string
+          enum:
+            - auto
+            - standard
+            - flex
+            - priority
+      required:
+        - enabled
     ResponsesResult:
       type: object
       properties:
@@ -20697,6 +20817,8 @@ components:
           type: string
         description:
           type: string
+        namespace:
+          type: string
         cardinality:
           type: object
           additionalProperties: true
@@ -20792,6 +20914,8 @@ components:
           type: string
         description:
           type: string
+        namespace:
+          type: string
         cardinality:
           type: object
           additionalProperties: true
@@ -20887,6 +21011,8 @@ components:
           type: boolean
         includeDeleted:
           type: boolean
+        namespace:
+          type: string
         query:
           type: object
           additionalProperties: true
@@ -20954,11 +21080,24 @@ components:
           additionalProperties: true
         reserved:
           type: boolean
+        namespace:
+          type: string
     PublicFacetListParams:
       type: object
       properties:
         includeValues:
           type: boolean
+        namespace:
+          type: string
+    FacetNamespaceListResponse:
+      type: object
+      properties:
+        namespaces:
+          type: array
+          items:
+            type: string
+      required:
+        - namespaces
     FacetGetParams:
       type: object
       properties:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "1.15.1",
+  "version": "1.15.3",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",