@proveanything/smartlinks 2.0.18 → 2.0.19

package/dist/openapi.yaml

@@ -1081,6 +1081,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 +1141,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 +1300,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 +10425,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 +10484,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
@@ -15244,6 +15476,10 @@ components:
             - standard
             - flex
             - priority
+        feature:
+          type: string
+        session_id:
+          type: string
         server_tools:
           type: array
           items:
@@ -15799,6 +16035,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 +16988,12 @@ components:
           additionalProperties: true
       required:
         - type
+    AiSessionScope:
+      type: string
+      enum:
+        - admin
+        - owner
+        - public
     AiToolCapability:
       type: string
       enum:

package/dist/testing/index.js

@@ -116,6 +116,12 @@ export function createFunctionTestContext(opts) {
                     throw new CapabilityError(`secrets:${ref}`);
                 return Object.prototype.hasOwnProperty.call(secretsMap, ref) ? secretsMap[ref] : null;
             },
+            // App-scoped read — in tests it resolves from the same provided secrets map.
+            async app(ref) {
+                if (!parsed.secrets.has(ref))
+                    throw new CapabilityError(`secrets:${ref}`);
+                return Object.prototype.hasOwnProperty.call(secretsMap, ref) ? secretsMap[ref] : null;
+            },
         },
         caller: {
             userId: (_a = caller.userId) !== null && _a !== void 0 ? _a : null,

package/dist/types/ai.d.ts

@@ -109,6 +109,18 @@ export interface ResponsesRequest {
     };
     /** `'flex'` is ~50% cheaper at Batch-API rates but slower; reserve for non-interactive/background work. */
     service_tier?: 'auto' | 'standard' | 'flex' | 'priority';
+    /**
+     * Attribution tag for AI usage/cost reporting (see `ai.usage`). Not sent to the model —
+     * the server strips it. e.g. `'readiness-check'`, `'design-critique'`.
+     */
+    feature?: string;
+    /**
+     * Persist this turn to a server-managed session (create one with `ai.sessions.create`). The
+     * server threads the session's prior transcript into the input and appends the new turn — so
+     * you get conversation memory without managing history yourself, and it works even with
+     * `server_tools` (unlike `previous_response_id`).
+     */
+    session_id?: string;
     /**
      * Run through the server-side agent loop: the platform executes built-in tools
      * (see BUILTIN_AI_TOOLS / AiToolName) and feeds results back automatically, so the
@@ -350,6 +362,65 @@ export interface SessionStatistics {
     totalMessages: number;
     rateLimitedUsers: number;
 }
+/** Who may read/append a persisted AI session. */
+export type AiSessionScope = 'admin' | 'owner' | 'public';
+/** A persisted AI assistant conversation (durable, scoped). */
+export 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;
+    /** Append-only Responses items (input/output + tool calls/results). */
+    items: ResponseInputItem[];
+    /** Compacted digest of older turns (server-managed). */
+    summary?: Record<string, any>;
+    /** Running token/turn accounting for this session. */
+    usage?: Record<string, any>;
+    itemCount: number;
+    lastTurnAt?: string | null;
+    createdAt: string;
+    updatedAt: string;
+    expiresAt?: string | null;
+}
+/** Fields for creating a session (all optional). */
+export interface AiSessionCreate {
+    appId?: string;
+    title?: string;
+    productId?: string;
+    proofId?: string;
+    feature?: string;
+    /** Time-to-live in ms; omit to keep until explicitly cleared. */
+    ttlMs?: number;
+    /** Seed items (e.g. a system/instruction turn). */
+    items?: ResponseInputItem[];
+}
+/** Per-collection AI usage/cost report. `costUnits` are OPAQUE internal units, never provider currency. */
+export 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;
+    }>;
+}
 /** Voice session request */
 export interface VoiceSessionRequest {
     productId: string;

package/dist/types/appManifest.d.ts

@@ -298,9 +298,15 @@ export interface ServerFunctionContext {
      * Declared `capabilities` cap what these calls may do.
      */
     sl: any;
-    /** Capability-gated secret access. `get(ref)` resolves only refs granted via `secrets:<ref>`. */
+    /**
+     * Capability-gated secret access (both require the `secrets:<ref>` capability).
+     * `get(ref)` resolves the collection's OWN secret first (a client's credential), then falls back
+     * to the app-level secret (the developer's shared singleton, installed once per instance).
+     * `app(ref)` reads the app-level secret only, skipping the collection store.
+     */
     secrets: {
         get(ref: string): Promise<string | null>;
+        app(ref: string): Promise<string | null>;
     };
     /** Who invoked this function. */
     caller: ServerFunctionCaller;

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.19  |  Generated: 2026-09-24T19:51:28.993Z
 
 This is a concise summary of all available API functions and types.
 
@@ -580,6 +580,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 +859,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 +1491,8 @@ interface AgentResponseCompletedEvent {
 }
 ```
 
+**AiSessionScope** = `'admin' | 'owner' | 'public'`
+
 **AiToolCapability** = ``
 
 **AiToolName** = ``
@@ -2102,7 +2155,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;
@@ -11091,6 +11147,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 +11253,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.