@proveanything/smartlinks 2.0.18 → 2.0.20

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.18  |  Generated: 2026-09-24T11:49:54.037Z
+Version: 2.0.20  |  Generated: 2026-09-25T11:48:23.950Z
 
 This is a concise summary of all available API functions and types.
 
@@ -135,6 +135,7 @@ The Smartlinks SDK is organized into the following namespaces:
 - **config** - Functions for config operations
 - **containers** - Functions for containers operations
 - **facets** - Functions for facets operations
+- **functions** - Functions for functions operations
 - **http** - Functions for http operations
 - **integrations** - Functions for integrations operations
 - **jobs** - Functions for jobs operations
@@ -580,6 +581,8 @@ interface ResponsesRequest {
   max_concurrent_subagents?: number
   }
   service_tier?: 'auto' | 'standard' | 'flex' | 'priority'
+  feature?: string
+  session_id?: string
   server_tools?: boolean | AiToolName[]
   allowCapabilities?: AiToolCapability[]
   only?: AiToolName[]
@@ -857,6 +860,55 @@ interface SessionStatistics {
 }
 ```
 
+**AiSession** (interface)
+```typescript
+interface AiSession {
+  id: string
+  collectionId: string
+  appId?: string | null
+  scope: AiSessionScope
+  title?: string | null
+  status: string
+  ownerId?: string | null
+  authorId?: string | null
+  productId?: string | null
+  proofId?: string | null
+  feature?: string | null
+  items: ResponseInputItem[]
+  summary?: Record<string, any>
+  usage?: Record<string, any>
+  itemCount: number
+  lastTurnAt?: string | null
+  createdAt: string
+  updatedAt: string
+  expiresAt?: string | null
+}
+```
+
+**AiSessionCreate** (interface)
+```typescript
+interface AiSessionCreate {
+  appId?: string
+  title?: string
+  productId?: string
+  proofId?: string
+  feature?: string
+  ttlMs?: number
+  items?: ResponseInputItem[]
+}
+```
+
+**AiUsageReport** (interface)
+```typescript
+interface AiUsageReport {
+  groupBy: string[]
+  from?: string | null
+  to?: string | null
+  totals: { promptTokens: number; outputTokens: number; totalTokens: number; requests: number; costUnits: number }
+  groups: Array<Record<string, any> & { promptTokens: number; outputTokens: number; totalTokens: number; requests: number; costUnits: number }>
+}
+```
+
 **VoiceSessionRequest** (interface)
 ```typescript
 interface VoiceSessionRequest {
@@ -1440,6 +1492,8 @@ interface AgentResponseCompletedEvent {
 }
 ```
 
+**AiSessionScope** = `'admin' | 'owner' | 'public'`
+
 **AiToolCapability** = ``
 
 **AiToolName** = ``
@@ -2102,7 +2156,10 @@ interface ServerFunctionContext {
   collectionId: string;
   appId: string;
   sl: any;
-  secrets: { get(ref: string): Promise<string | null> };
+  secrets: {
+  get(ref: string): Promise<string | null>;
+  app(ref: string): Promise<string | null>;
+  };
   caller: ServerFunctionCaller;
   fetch: typeof fetch;
   log: (message: string, data?: Record<string, any>) => void;
@@ -8887,6 +8944,24 @@ type VerifyTokenResponse = {
 }
 ```
 
+### functions (api)
+
+**FunctionListEntry** (interface)
+```typescript
+interface FunctionListEntry {
+  name: string; visibility?: string; trigger?: string
+}
+```
+
+**FunctionListResponse** (interface)
+```typescript
+interface FunctionListResponse {
+  functions: FunctionListEntry[]
+}
+```
+
+**FunctionCallResult** = `any`
+
 ### sequence (api)
 
 **AllocateSequenceInput** (interface)
@@ -10379,6 +10454,21 @@ Update a form for a collection (admin only).
 **remove**(collectionId: string, formId: string) → `Promise<void>`
 Delete a form for a collection (admin only).
 
+### functions
+
+**call**(collectionId: string,
+    name: string,
+    body: Record<string, any> = {}) → `Promise<T>`
+Call a PUBLIC app server function inline. `POST /public/collection/:collectionId/functions/:name` — surface `'public'`. const { value } = await SL.functions.call<{ value: number }>(collectionId, 'increment')
+
+**callAdmin**(collectionId: string,
+    name: string,
+    body: Record<string, any> = {}) → `Promise<T>`
+Call an ADMIN app server function (surface `'admin'`; requires an admin session). `POST /admin/collection/:collectionId/functions/:name`.
+
+**list**(collectionId: string) → `Promise<FunctionListResponse>`
+List the public functions available for a collection (discovery). `GET /public/collection/:c/functions`.
+
 ### http
 
 **get**(path: string) → `Promise<T>`
@@ -11091,6 +11181,27 @@ Check rate limit status
       request: EphemeralTokenRequest) → `Promise<EphemeralTokenResponse>`
 Generate ephemeral token for Gemini Live
 
+### publicClient.sessions
+
+**create**(collectionId: string,
+        body: AiSessionCreate & { scope?: 'owner' | 'public' } = {}) → `Promise<AiSession>`
+
+**list**(collectionId: string,
+        params?: { appId?: string; limit?: number }) → `Promise<`
+List the signed-in consumer's own ('owner') sessions — requires an authKit bearer.
+
+**get**(collectionId: string, id: string) → `Promise<AiSession>`
+List the signed-in consumer's own ('owner') sessions — requires an authKit bearer.
+
+**append**(collectionId: string,
+        id: string,
+        items: ResponseInputItem[],
+        opts?: { usage?: Record<string, any> }) → `Promise<AiSession>`
+List the signed-in consumer's own ('owner') sessions — requires an authKit bearer.
+
+**clear**(collectionId: string, id: string) → `Promise<`
+List the signed-in consumer's own ('owner') sessions — requires an authKit bearer.
+
 ### qr
 
 **lookupShortCode**(shortId: string, code: string) → `Promise<QrShortCodeLookupResponse>`
@@ -11176,6 +11287,24 @@ Allocate (or return the existing) sequence number for a subject. Idempotent —
 **stats**(collectionId: string) → `Promise<SessionStatistics>`
 Get session statistics
 
+**create**(collectionId: string, body: AiSessionCreate = {}) → `Promise<AiSession>`
+Persisted AI assistant sessions (admin scope) — durable conversation history for admin/host assistants. Create one, then either append your turns explicitly, OR pass its `id` as `session_id` to `ai.chat.responses.create` and the server threads prior turns into the input and persists the new turn automatically (works with `server_tools`).
+
+**list**(collectionId: string, params?: { appId?: string; limit?: number }) → `Promise<`
+List sessions, most-recently-active first (optionally filtered by app).
+
+**get**(collectionId: string, id: string) → `Promise<AiSession>`
+Get one session, including its full transcript.
+
+**append**(collectionId: string,
+      id: string,
+      items: ResponseInputItem[],
+      opts?: { usage?: Record<string, any> }) → `Promise<AiSession>`
+Append Responses items (input/output/tool) to a session — the manual-persistence path.
+
+**clear**(collectionId: string, id: string) → `Promise<`
+Archive (soft-delete) a session.
+
 ### skills
 
 **list**(collectionId: string) → `Promise<SkillsListResponse>`

package/docs/host-dependency-contract.md

@@ -62,12 +62,19 @@ export default defineConfig({
 
 ## Host-provided globals (build against versions ≤ these)
 
+> **The SmartLinks packages on the host are always the latest published.** `@proveanything/smartlinks`
+> (and `-utils-ui`, `-auth-ui`) are considered *released* only once Hub and Portal are running them —
+> that's the first place a version lands, by design. So **build against the latest published SmartLinks
+> SDK**; never pin below it. The exact number below is just "current at time of writing" — the rule is
+> *latest*. The third-party framework versions (React, Vite, Router, …) change rarely and are the real
+> compile-time ceiling.
+
 | Import | Window global | Host provides (R5) |
 |---|---|---|
 | `react` | `React` | 19.3 (accepts 18.3 builds) |
 | `react-dom` | `ReactDOM` | 19.3 (accepts 18.3 builds) |
 | `react/jsx-runtime` | `jsxRuntime` | 19.3 |
-| `@proveanything/smartlinks` | `SL` | 2.0.5 |
+| `@proveanything/smartlinks` | `SL` | latest published 2.x (build against latest) |
 | `react-router-dom` | `ReactRouterDOM` | 7.18 (accepts 6.x builds) |
 | `@tanstack/react-query` | `ReactQuery` | 5.103 |
 | `lucide-react` | `LucideReact` | 1.47 |
@@ -130,10 +137,12 @@ app ships the Tailwind 4 CSS-first layout as the default; see its README.)
 ## The R5 host stack (reference)
 
 React **19.3** · Vite **8.3** · react-router-dom **7.18** · Tailwind **4.3** (CSS-first) ·
-TypeScript **6.0** · ESLint **10.11** · `@proveanything/smartlinks` **2.0.5** ·
-`@proveanything/smartlinks-utils-ui` **1.16.4** · liquidjs **10.29** · marked **12+** ·
+TypeScript **6.0** · ESLint **10.11** · liquidjs **10.29** · marked **12+** ·
 dompurify **3+** · clsx **2+** · tailwind-merge **3+**.
 
+The SmartLinks packages (`@proveanything/smartlinks`, `-utils-ui`, `-auth-ui`) are **always the latest
+published 2.x** — see the note above; build against latest, don't pin a specific number here (it rots).
+
 > **TypeScript 7** (the native/Go compiler) is **deliberately deferred** — tooling hasn't settled.
 > Target **TS 6** for R5; it compiles existing code with no source changes.
 

package/openapi.yaml

@@ -72,6 +72,8 @@ tags:
     description: Product facet querying and aggregation.
   - name: form
     description: Form definitions and submissions.
+  - name: functions
+    description: functions API
   - name: integrations
     description: Third-party integration flows and imports.
   - name: interactions
@@ -1081,6 +1083,39 @@ paths:
           application/json:
             schema:
               $ref: "#/components/schemas/AISearchPhotosRequest"
+  /admin/collection/{collectionId}/ai/sessions:
+    post:
+      tags:
+        - sessions
+      summary: Persisted AI assistant sessions (admin scope) — durable conversation history for admin/host assistants.
+      operationId: sessions_create
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AiSession"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AiSessionCreate"
   /admin/collection/{collectionId}/ai/sessions/stats:
     get:
       tags:
@@ -1108,6 +1143,77 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /admin/collection/{collectionId}/ai/sessions/{id}:
+    get:
+      tags:
+        - sessions
+      summary: Get one session, including its full transcript.
+      operationId: sessions_get
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AiSession"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+  /admin/collection/{collectionId}/ai/sessions/{id}/append:
+    post:
+      tags:
+        - sessions
+      summary: Append Responses items (input/output/tool) to a session — the manual-persistence path.
+      operationId: sessions_append
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AiSession"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: true
   /admin/collection/{collectionId}/ai/skills:
     get:
       tags:
@@ -1196,6 +1302,33 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /admin/collection/{collectionId}/ai/usage:
+    get:
+      tags:
+        - sessions
+      summary: AI usage / cost report for a collection, grouped by any of model/serviceTier/appId/feature/mode over an optional date window.
+      operationId: sessions_usage
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AiUsageReport"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
   /admin/collection/{collectionId}/ai/v1/chat/completions:
     post:
       tags:
@@ -10294,9 +10427,9 @@ paths:
   /public/collection/{collectionId}/ai/rate-limit/{userId}:
     get:
       tags:
-        - publicClient
+        - sessions
       summary: Check rate limit status
-      operationId: publicClient_getRateLimit
+      operationId: sessions_getRateLimit
       security: []
       parameters:
         - name: collectionId
@@ -10353,12 +10486,113 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /public/collection/{collectionId}/ai/sessions:
+    post:
+      tags:
+        - sessions
+      summary: sessions.create
+      operationId: sessions_create
+      security: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AiSession"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AiSessionCreate"
+  /public/collection/{collectionId}/ai/sessions/{id}:
+    get:
+      tags:
+        - sessions
+      summary: sessions.get
+      operationId: sessions_get
+      security: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AiSession"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+  /public/collection/{collectionId}/ai/sessions/{id}/append:
+    post:
+      tags:
+        - sessions
+      summary: sessions.append
+      operationId: sessions_append
+      security: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AiSession"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: true
   /public/collection/{collectionId}/ai/token:
     post:
       tags:
-        - publicClient
+        - sessions
       summary: Generate ephemeral token for Gemini Live
-      operationId: publicClient_getToken
+      operationId: sessions_getToken
       security: []
       parameters:
         - name: collectionId
@@ -11918,6 +12152,32 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /public/collection/{collectionId}/functions:
+    get:
+      tags:
+        - functions
+      summary: List the public functions available for a collection (discovery).
+      operationId: functions_list
+      security: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/FunctionListResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
   /public/collection/{collectionId}/interactions:
     get:
       tags:
@@ -15244,6 +15504,10 @@ components:
             - standard
             - flex
             - priority
+        feature:
+          type: string
+        session_id:
+          type: string
         server_tools:
           type: array
           items:
@@ -15799,6 +16063,102 @@ components:
         - activeSessions
         - totalMessages
         - rateLimitedUsers
+    AiSession:
+      type: object
+      properties:
+        id:
+          type: string
+        collectionId:
+          type: string
+        appId:
+          type: string
+        scope:
+          $ref: "#/components/schemas/AiSessionScope"
+        title:
+          type: string
+        status:
+          type: string
+        ownerId:
+          type: string
+        authorId:
+          type: string
+        productId:
+          type: string
+        proofId:
+          type: string
+        feature:
+          type: string
+        items:
+          type: array
+          items:
+            $ref: "#/components/schemas/ResponseInputItem"
+        summary:
+          type: object
+          additionalProperties: true
+        usage:
+          type: object
+          additionalProperties: true
+        itemCount:
+          type: number
+        lastTurnAt:
+          type: string
+        createdAt:
+          type: string
+        updatedAt:
+          type: string
+        expiresAt:
+          type: string
+      required:
+        - id
+        - collectionId
+        - scope
+        - status
+        - items
+        - itemCount
+        - createdAt
+        - updatedAt
+    AiSessionCreate:
+      type: object
+      properties:
+        appId:
+          type: string
+        title:
+          type: string
+        productId:
+          type: string
+        proofId:
+          type: string
+        feature:
+          type: string
+        ttlMs:
+          type: number
+        items:
+          type: array
+          items:
+            $ref: "#/components/schemas/ResponseInputItem"
+    AiUsageReport:
+      type: object
+      properties:
+        groupBy:
+          type: array
+          items:
+            type: string
+        from:
+          type: string
+        to:
+          type: string
+        totals:
+          type: object
+          additionalProperties: true
+        groups:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+      required:
+        - groupBy
+        - totals
+        - groups
     VoiceSessionRequest:
       type: object
       properties:
@@ -16656,6 +17016,12 @@ components:
           additionalProperties: true
       required:
         - type
+    AiSessionScope:
+      type: string
+      enum:
+        - admin
+        - owner
+        - public
     AiToolCapability:
       type: string
       enum:
@@ -28931,6 +29297,23 @@ components:
           additionalProperties: true
       required:
         - valid
+    FunctionListEntry:
+      type: object
+      properties:
+        name:
+          type: object
+          additionalProperties: true
+      required:
+        - name
+    FunctionListResponse:
+      type: object
+      properties:
+        functions:
+          type: array
+          items:
+            $ref: "#/components/schemas/FunctionListEntry"
+      required:
+        - functions
     AllocateSequenceInput:
       type: object
       properties:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "2.0.18",
+  "version": "2.0.20",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "type": "module",
   "main": "dist/index.js",