@proveanything/smartlinks 2.0.18 → 2.0.19

package/dist/api/ai.d.ts

@@ -1,5 +1,5 @@
-import type { ContentPart, FunctionCall, ToolCall, ChatMessage, ToolDefinition, ResponseTool, ResponseInputItem, ResponsesRequest, ResponsesResult, ResponsesStreamEvent, ChatCompletionRequest, ChatCompletionChoice, ChatCompletionResponse, ChatCompletionChunk, AIModel, AIModelListParams, AIModelListResponse, AgentRunRequest, AgentRunResult, AgentToolsQuery, AgentToolsResponse, SkillsListResponse, CatalogResponse, DocumentChunk, IndexDocumentRequest, IndexDocumentResponse, ConfigureAssistantRequest, ConfigureAssistantResponse, PublicChatRequest, PublicChatResponse, Session, RateLimitStatus, SessionStatistics, VoiceSessionRequest, VoiceSessionResponse, EphemeralTokenRequest, EphemeralTokenResponse, TranscriptionResponse, TTSRequest, GeneratePodcastRequest, PodcastScript, GeneratePodcastResponse, PodcastStatus, AIGenerateContentRequest, AIGenerateContentCandidate, AIGenerateContentResponse, AIGenerateImageRequest, AIGenerateImageResponse, AIGeneratedImage, AISearchPhotosRequest, AISearchPhotosPhoto, AISearchPhotosResponse, AIUploadedFile, AICacheRef } from "../types/ai.js";
-export type { ContentPart, FunctionCall, ToolCall, ChatMessage, ToolDefinition, ResponseTool, ResponseInputItem, ResponsesRequest, ResponsesResult, ResponsesStreamEvent, ChatCompletionRequest, ChatCompletionChoice, ChatCompletionResponse, ChatCompletionChunk, AIModel, AIModelListParams, AIModelListResponse, DocumentChunk, IndexDocumentRequest, IndexDocumentResponse, ConfigureAssistantRequest, ConfigureAssistantResponse, PublicChatRequest, PublicChatResponse, Session, RateLimitStatus, SessionStatistics, VoiceSessionRequest, VoiceSessionResponse, EphemeralTokenRequest, EphemeralTokenResponse, TranscriptionResponse, TTSRequest, GeneratePodcastRequest, PodcastScript, GeneratePodcastResponse, PodcastStatus, AIGenerateContentRequest, AIGenerateContentCandidate, AIGenerateContentResponse, AIGenerateImageRequest, AIGenerateImageResponse, AIGeneratedImage, AISearchPhotosRequest, AISearchPhotosPhoto, AISearchPhotosResponse, AIUploadedFile, AICacheRef, };
+import type { ContentPart, FunctionCall, ToolCall, ChatMessage, ToolDefinition, ResponseTool, ResponseInputItem, ResponsesRequest, ResponsesResult, ResponsesStreamEvent, ChatCompletionRequest, ChatCompletionChoice, ChatCompletionResponse, ChatCompletionChunk, AIModel, AIModelListParams, AIModelListResponse, AgentRunRequest, AgentRunResult, AgentToolsQuery, AgentToolsResponse, SkillsListResponse, CatalogResponse, DocumentChunk, IndexDocumentRequest, IndexDocumentResponse, ConfigureAssistantRequest, ConfigureAssistantResponse, PublicChatRequest, PublicChatResponse, Session, RateLimitStatus, SessionStatistics, AiSession, AiSessionCreate, AiUsageReport, VoiceSessionRequest, VoiceSessionResponse, EphemeralTokenRequest, EphemeralTokenResponse, TranscriptionResponse, TTSRequest, GeneratePodcastRequest, PodcastScript, GeneratePodcastResponse, PodcastStatus, AIGenerateContentRequest, AIGenerateContentCandidate, AIGenerateContentResponse, AIGenerateImageRequest, AIGenerateImageResponse, AIGeneratedImage, AISearchPhotosRequest, AISearchPhotosPhoto, AISearchPhotosResponse, AIUploadedFile, AICacheRef } from "../types/ai.js";
+export type { ContentPart, FunctionCall, ToolCall, ChatMessage, ToolDefinition, ResponseTool, ResponseInputItem, ResponsesRequest, ResponsesResult, ResponsesStreamEvent, ChatCompletionRequest, ChatCompletionChoice, ChatCompletionResponse, ChatCompletionChunk, AIModel, AIModelListParams, AIModelListResponse, DocumentChunk, IndexDocumentRequest, IndexDocumentResponse, ConfigureAssistantRequest, ConfigureAssistantResponse, PublicChatRequest, PublicChatResponse, Session, RateLimitStatus, SessionStatistics, AiSession, AiSessionCreate, AiUsageReport, VoiceSessionRequest, VoiceSessionResponse, EphemeralTokenRequest, EphemeralTokenResponse, TranscriptionResponse, TTSRequest, GeneratePodcastRequest, PodcastScript, GeneratePodcastResponse, PodcastStatus, AIGenerateContentRequest, AIGenerateContentCandidate, AIGenerateContentResponse, AIGenerateImageRequest, AIGenerateImageResponse, AIGeneratedImage, AISearchPhotosRequest, AISearchPhotosPhoto, AISearchPhotosResponse, AIUploadedFile, AICacheRef, };
 declare namespace aiInternal {
     namespace chat {
         namespace responses {
@@ -70,7 +70,41 @@ declare namespace aiInternal {
          * Get session statistics
          */
         function stats(collectionId: string): Promise<SessionStatistics>;
+        /**
+         * 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`).
+         */
+        function create(collectionId: string, body?: AiSessionCreate): Promise<AiSession>;
+        /** List sessions, most-recently-active first (optionally filtered by app). */
+        function list(collectionId: string, params?: {
+            appId?: string;
+            limit?: number;
+        }): Promise<{
+            sessions: AiSession[];
+        }>;
+        /** Get one session, including its full transcript. */
+        function get(collectionId: string, id: string): Promise<AiSession>;
+        /** Append Responses items (input/output/tool) to a session — the manual-persistence path. */
+        function append(collectionId: string, id: string, items: ResponseInputItem[], opts?: {
+            usage?: Record<string, any>;
+        }): Promise<AiSession>;
+        /** Archive (soft-delete) a session. */
+        function clear(collectionId: string, id: string): Promise<{
+            ok: boolean;
+            id: string;
+        }>;
     }
+    /**
+     * AI usage / cost report for a collection, grouped by any of model/serviceTier/appId/feature/mode
+     * over an optional date window. `costUnits` are OPAQUE internal units, never provider currency.
+     */
+    function usage(collectionId: string, params?: {
+        groupBy?: string | string[];
+        from?: string;
+        to?: string;
+    }): Promise<AiUsageReport>;
     namespace rateLimit {
         /**
          * Reset rate limit for a user
@@ -111,6 +145,32 @@ declare namespace aiInternal {
         function clearSession(collectionId: string, sessionId: string): Promise<{
             success: boolean;
         }>;
+        /**
+         * Persisted consumer AI sessions (durable — the replacement for getSession/clearSession above).
+         * `scope: 'owner'` keys the history to the signed-in consumer (send the authKit bearer, and
+         * only that consumer can read/append/clear it); `scope: 'public'` (default) is an anonymous
+         * session where possession of the id is the capability.
+         */
+        namespace sessions {
+            function create(collectionId: string, body?: AiSessionCreate & {
+                scope?: 'owner' | 'public';
+            }): Promise<AiSession>;
+            /** List the signed-in consumer's own ('owner') sessions — requires an authKit bearer. */
+            function list(collectionId: string, params?: {
+                appId?: string;
+                limit?: number;
+            }): Promise<{
+                sessions: AiSession[];
+            }>;
+            function get(collectionId: string, id: string): Promise<AiSession>;
+            function append(collectionId: string, id: string, items: ResponseInputItem[], opts?: {
+                usage?: Record<string, any>;
+            }): Promise<AiSession>;
+            function clear(collectionId: string, id: string): Promise<{
+                ok: boolean;
+                id: string;
+            }>;
+        }
         /**
          * Check rate limit status
          */

package/dist/api/ai.js

@@ -173,7 +173,59 @@ var aiInternal;
             return request(path);
         }
         sessions.stats = stats;
+        /**
+         * 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`).
+         */
+        async function create(collectionId, body = {}) {
+            const path = `/admin/collection/${encodeURIComponent(collectionId)}/ai/sessions`;
+            return post(path, body);
+        }
+        sessions.create = create;
+        /** List sessions, most-recently-active first (optionally filtered by app). */
+        async function list(collectionId, params) {
+            const path = `/admin/collection/${encodeURIComponent(collectionId)}/ai/sessions${encodeQueryParams({
+                appId: params === null || params === void 0 ? void 0 : params.appId,
+                limit: (params === null || params === void 0 ? void 0 : params.limit) != null ? String(params.limit) : undefined,
+            })}`;
+            return request(path);
+        }
+        sessions.list = list;
+        /** Get one session, including its full transcript. */
+        async function get(collectionId, id) {
+            const path = `/admin/collection/${encodeURIComponent(collectionId)}/ai/sessions/${encodeURIComponent(id)}`;
+            return request(path);
+        }
+        sessions.get = get;
+        /** Append Responses items (input/output/tool) to a session — the manual-persistence path. */
+        async function append(collectionId, id, items, opts) {
+            const path = `/admin/collection/${encodeURIComponent(collectionId)}/ai/sessions/${encodeURIComponent(id)}/append`;
+            return post(path, { items, usage: opts === null || opts === void 0 ? void 0 : opts.usage });
+        }
+        sessions.append = append;
+        /** Archive (soft-delete) a session. */
+        async function clear(collectionId, id) {
+            const path = `/admin/collection/${encodeURIComponent(collectionId)}/ai/sessions/${encodeURIComponent(id)}`;
+            return del(path);
+        }
+        sessions.clear = clear;
     })(sessions = aiInternal.sessions || (aiInternal.sessions = {}));
+    /**
+     * AI usage / cost report for a collection, grouped by any of model/serviceTier/appId/feature/mode
+     * over an optional date window. `costUnits` are OPAQUE internal units, never provider currency.
+     */
+    async function usage(collectionId, params) {
+        const groupBy = Array.isArray(params === null || params === void 0 ? void 0 : params.groupBy) ? params.groupBy.join(',') : params === null || params === void 0 ? void 0 : params.groupBy;
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/ai/usage${encodeQueryParams({
+            groupBy,
+            from: params === null || params === void 0 ? void 0 : params.from,
+            to: params === null || params === void 0 ? void 0 : params.to,
+        })}`;
+        return request(path);
+    }
+    aiInternal.usage = usage;
     // ============================================================================
     // Rate Limiting API
     // ============================================================================
@@ -254,6 +306,44 @@ var aiInternal;
             return del(path);
         }
         publicClient.clearSession = clearSession;
+        /**
+         * Persisted consumer AI sessions (durable — the replacement for getSession/clearSession above).
+         * `scope: 'owner'` keys the history to the signed-in consumer (send the authKit bearer, and
+         * only that consumer can read/append/clear it); `scope: 'public'` (default) is an anonymous
+         * session where possession of the id is the capability.
+         */
+        let sessions;
+        (function (sessions) {
+            async function create(collectionId, body = {}) {
+                const path = `/public/collection/${encodeURIComponent(collectionId)}/ai/sessions`;
+                return post(path, body);
+            }
+            sessions.create = create;
+            /** List the signed-in consumer's own ('owner') sessions — requires an authKit bearer. */
+            async function list(collectionId, params) {
+                const path = `/public/collection/${encodeURIComponent(collectionId)}/ai/sessions${encodeQueryParams({
+                    appId: params === null || params === void 0 ? void 0 : params.appId,
+                    limit: (params === null || params === void 0 ? void 0 : params.limit) != null ? String(params.limit) : undefined,
+                })}`;
+                return request(path);
+            }
+            sessions.list = list;
+            async function get(collectionId, id) {
+                const path = `/public/collection/${encodeURIComponent(collectionId)}/ai/sessions/${encodeURIComponent(id)}`;
+                return request(path);
+            }
+            sessions.get = get;
+            async function append(collectionId, id, items, opts) {
+                const path = `/public/collection/${encodeURIComponent(collectionId)}/ai/sessions/${encodeURIComponent(id)}/append`;
+                return post(path, { items, usage: opts === null || opts === void 0 ? void 0 : opts.usage });
+            }
+            sessions.append = append;
+            async function clear(collectionId, id) {
+                const path = `/public/collection/${encodeURIComponent(collectionId)}/ai/sessions/${encodeURIComponent(id)}`;
+                return del(path);
+            }
+            sessions.clear = clear;
+        })(sessions = publicClient.sessions || (publicClient.sessions = {}));
         /**
          * Check rate limit status
          */

package/dist/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/dist/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.