@cosmoops/connect-sdk 0.29.0 → 0.30.1

package/dist/esm/server/handler.js

@@ -388,6 +388,12 @@ export function createConnectHandler(options) {
                 // decision, so there is nothing for this layer to check more strictly.
                 screenContext: body.screenContext,
                 screens: body.screens,
+                // The browser's own id for this conversation, so the turn is stored
+                // and can be reopened. Safe to relay: it decides *which* of the
+                // caller's own conversations is written to, never whose - Connect
+                // refuses an id belonging to another user or another application, and
+                // the owner comes from `asUser` below.
+                ...(typeof body.conversationId === "string" ? { conversationId: body.conversationId } : {}),
                 // Connect re-derives the workspace from this token, so the line above
                 // is belt to its braces - the browser cannot reach another tenant's
                 // Context Index even if this route were changed to trust the request.
@@ -406,6 +412,75 @@ export function createConnectHandler(options) {
                 },
             });
         },
+        /**
+         * Ask AI history - the list, one transcript, and a deletion.
+         *
+         * The same rule as every other route: the user comes from the caller's own
+         * session, forwarded as `asUser`, and Connect reads both the person and
+         * the workspace from it. Nothing here takes an owner from the request, so
+         * a browser cannot page through anybody else's conversations - which
+         * matters more here than on most routes, because a transcript is the most
+         * candid record this API holds of what somebody was trying to do.
+         *
+         * The id is the only thing a browser supplies. It selects among the
+         * caller's own conversations and nothing more: an id belonging to another
+         * user is a 404, and one belonging to another application the same, so a
+         * shared workspace's two products cannot read each other's.
+         *
+         * It travels as `?id=` rather than as a path segment, and the store routes
+         * are why. This table is keyed by an exact `METHOD /path` string; the only
+         * thing that matches a *prefix* is `isStoreRoute`, kept to a closed list
+         * precisely so the bridge cannot drift into a generic proxy. Widening that
+         * matcher for one more resource would be the first step of exactly that
+         * drift, so the id goes in the query and the route keys stay exact.
+         *
+         * `requireToken` rather than `requireWorkspace`: Connect resolves the
+         * workspace from the token itself and refuses a staff session there, so
+         * the extra identity round trip would buy a differently-worded 403 and
+         * nothing else.
+         */
+        "GET /ai/conversations": async (request) => {
+            const url = new URL(request.url);
+            const limit = url.searchParams.get("limit");
+            const cursor = url.searchParams.get("cursor");
+            return json(await client.ai.listConversations({
+                asUser: await requireToken(request),
+                // Forwarded only when present, so Connect's own defaults apply
+                // rather than this layer inventing a second set of them.
+                ...(limit !== null ? { limit: Number(limit) } : {}),
+                ...(cursor ? { cursor } : {}),
+            }));
+        },
+        "GET /ai/conversation": async (request) => {
+            const conversationId = new URL(request.url).searchParams.get("id");
+            if (!conversationId) {
+                throw new ConnectError({
+                    status: 400,
+                    code: "validation_error",
+                    message: "id is required",
+                    endpoint: "GET /ai/conversation",
+                });
+            }
+            return json(await client.ai.getConversation({
+                conversationId,
+                asUser: await requireToken(request),
+            }));
+        },
+        "DELETE /ai/conversation": async (request) => {
+            const conversationId = new URL(request.url).searchParams.get("id");
+            if (!conversationId) {
+                throw new ConnectError({
+                    status: 400,
+                    code: "validation_error",
+                    message: "id is required",
+                    endpoint: "DELETE /ai/conversation",
+                });
+            }
+            return json(await client.ai.deleteConversation({
+                conversationId,
+                asUser: await requireToken(request),
+            }));
+        },
         /**
          * The store, forwarded.
          *

package/dist/esm/server/resources/ai.js

@@ -30,6 +30,10 @@ export class AiResource {
             json: {
                 workspaceId: input.workspaceId,
                 messages: input.messages,
+                // Omitted when absent, which is how a caller opts out of history: no
+                // id, nothing stored. Connect also stores nothing for a call carrying
+                // no `asUser`, because a conversation belongs to a person.
+                ...(input.conversationId ? { conversationId: input.conversationId } : {}),
                 // Omitted entirely when absent, rather than sent as `undefined` - an
                 // application that describes no screens should send no field.
                 ...(input.screens ? { screens: input.screens } : {}),
@@ -40,6 +44,57 @@ export class AiResource {
             signal: options.signal,
         });
     }
+    /**
+     * The signed-in user's past conversations in your application, most recent
+     * first.
+     *
+     * `asUser` is required rather than optional here, unlike on `chat`: the rows
+     * are scoped to a person, and there is no application-wide view of them to
+     * fall back to. Connect reads the user and the workspace from the token.
+     *
+     * Cursor-paginated with no total - the list is ordered by last use, which
+     * moves while it is being read.
+     */
+    listConversations(input) {
+        const query = new URLSearchParams();
+        if (input.limit !== undefined)
+            query.set("limit", String(input.limit));
+        if (input.cursor)
+            query.set("cursor", input.cursor);
+        const suffix = query.size > 0 ? `?${query.toString()}` : "";
+        return request(this.transport, {
+            method: "GET",
+            path: `/ai/conversations${suffix}`,
+            headers: actingAs(input.asUser),
+        });
+    }
+    /**
+     * One stored transcript, oldest turn first.
+     *
+     * `turns[].parts` comes back exactly as the model produced it - prose,
+     * reasoning and tool calls in order - so it can be handed straight back to a
+     * chat UI. Not this user's, or not your application's, is a `404` either way.
+     */
+    getConversation(input) {
+        return request(this.transport, {
+            method: "GET",
+            path: `/ai/conversations/${encodeURIComponent(input.conversationId)}`,
+            headers: actingAs(input.asUser),
+        });
+    }
+    /**
+     * Deletes a conversation and every turn beneath it.
+     *
+     * Idempotent - one already gone answers `{ deleted: true }`, so a retry after
+     * a dropped response does not read as a failure.
+     */
+    deleteConversation(input) {
+        return request(this.transport, {
+            method: "DELETE",
+            path: `/ai/conversations/${encodeURIComponent(input.conversationId)}`,
+            headers: actingAs(input.asUser),
+        });
+    }
     /** Extract structured JSON from a file or image URL, against a platform extraction schema referenced by id. */
     async extract(input) {
         const result = await request(this.transport, {

package/dist/types/client/components/ask-ai-history.d.ts

@@ -0,0 +1,25 @@
+import type { AiConversationDetail } from "../../types.js";
+/**
+ * Past Ask AI conversations, for reopening or deleting.
+ *
+ * ## It fetches only while it is open
+ *
+ * `<ConnectAskAi>` is mounted for the whole application shell, so an
+ * unconditional read here would put a request on every page load to populate a
+ * list most people never open. It reads on open, and again whenever the panel
+ * has written a new conversation since - which is what `refreshKey` is for.
+ *
+ * ## Deletion confirms inline, not in a dialog
+ *
+ * Destructive actions confirm; this one does it at the weight it deserves.
+ * Losing a transcript is recoverable by asking again, not a cancelled
+ * subscription, and a modal over a 400px panel would be heavier than the thing
+ * it guards. The row swaps to "Delete? / Cancel" and stays there until
+ * answered.
+ */
+export declare function AskAiHistory({ refreshKey, activeConversationId, onOpenConversation, }: Readonly<{
+    /** Changes when the panel has written something, so the list re-reads. */
+    refreshKey: number;
+    activeConversationId: string;
+    onOpenConversation: (id: string, detail: AiConversationDetail) => void;
+}>): import("react").JSX.Element;

package/dist/types/client/components/ask-ai-turns.d.ts

@@ -0,0 +1,55 @@
+import type { AiConversationTurn } from "../../types.js";
+/**
+ * One piece of an assistant turn, in the order it arrived.
+ *
+ * Blocks rather than one text string, because an answer interleaves prose and
+ * drawings - a sentence, a table, the sentence that reads the table - and
+ * flattening it would silently reorder the model's own argument.
+ */
+export type AskAiBlock = {
+    kind: "text";
+    text: string;
+} | {
+    kind: "tool";
+    id: string;
+    name: string;
+    input: unknown | null;
+};
+export interface AskAiTurn {
+    id: string;
+    role: "user" | "assistant";
+    blocks: AskAiBlock[];
+    /** The model's streamed thoughts, if it sent any. */
+    reasoning: string;
+}
+/**
+ * Index of the final text block, or `-1`. A reverse loop rather than
+ * `findLastIndex`, which is ES2023 - this package targets ES2022 so its
+ * published output stays usable on the runtimes its `engines` field claims.
+ */
+export declare function lastTextBlockIndex(blocks: AskAiBlock[]): number;
+/** Appends a text delta to the open text block, or opens one after a widget. */
+export declare function appendText(blocks: AskAiBlock[], text: string): AskAiBlock[];
+/**
+ * Rebuilds the panel's turns from a stored transcript.
+ *
+ * The inverse of what the stream reader does live, and it has to agree with it
+ * or a reopened conversation renders differently from the one the user just
+ * had. Two shapes, one source: the stream delivers `text-delta`,
+ * `reasoning-delta` and `tool-input-available` frames, and storage keeps the
+ * settled `UIMessage` parts those frames built - `{ type: "text" }`,
+ * `{ type: "reasoning" }`, and `{ type: "tool-<name>" }` carrying the input the
+ * widget was drawn from.
+ *
+ * Three rules, each of which is a thing that would otherwise render wrong:
+ *
+ * - **A tool part with no input is dropped, not restored.** `input: null` means
+ *   "still arriving" to the renderer, which draws a skeleton - correct live,
+ *   and a shimmer that never resolves on a transcript that finished days ago.
+ * - **Reasoning is hoisted per turn**, not left in place. It is rendered above
+ *   the answer in a disclosure, which is where it sat while streaming.
+ * - **A part this build cannot place is skipped rather than guessed at.**
+ *   `parts` is the AI SDK's own shape and gains kinds over time; an unknown one
+ *   costs a widget, and inventing a rendering for it costs the whole turn.
+ */
+export declare function turnsFromStored(turns: readonly AiConversationTurn[]): AskAiTurn[];

package/dist/types/client/components/ask-ai.d.ts

@@ -1,5 +1,5 @@
 import { type ReactNode } from "react";
-import { type StreamdownProps } from "streamdown";
+import type { StreamdownProps } from "streamdown";
 import type { ConnectScreen } from "../../types.js";
 export interface ConnectAskAiProps {
     /**

package/dist/types/client/provider.d.ts

@@ -99,8 +99,15 @@ export interface ConnectContextValue {
      * `path` through `useConnectResource` still needs to call that hook's own
      * `refetch()` afterward; clearing the cache entry alone does not re-render
      * anything by itself.
+     *
+     * `method` widens this to the one other verb the bridge answers, `DELETE`,
+     * for the routes where removal is the whole operation and a body would be
+     * ceremony - Ask AI's history is the first. It stays a two-value union
+     * rather than `string`: everything else on this bridge is a POST, and a
+     * free-form verb here would be an invitation to invent REST semantics the
+     * bridge's exact-match route table does not have.
      */
-    mutateResource<T>(path: string, body?: unknown): Promise<T>;
+    mutateResource<T>(path: string, body?: unknown, method?: "POST" | "DELETE"): Promise<T>;
     /**
      * Drops one path's cached read so the next `fetchResource` for it goes to
      * the bridge again.

package/dist/types/server/client.d.ts

@@ -126,4 +126,4 @@ export declare class ConnectClient {
     constructor(options: ConnectClientOptions);
 }
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-export declare const SDK_VERSION = "0.29.0";
+export declare const SDK_VERSION = "0.30.1";

package/dist/types/server/resources/ai.d.ts

@@ -1,5 +1,5 @@
 import { type TransportOptions } from "../http.js";
-import type { ChatMessage, ConnectScreen } from "../../types.js";
+import type { AiConversationDetail, AiConversationList, ChatMessage, ConnectScreen } from "../../types.js";
 /**
  * RAG chat and structured extraction against a workspace's data.
  *
@@ -21,6 +21,15 @@ export declare class AiResource {
         workspaceId: string;
         messages: ChatMessage[];
         asUser?: string;
+        /**
+         * Your own id for this conversation, sent with every turn of it.
+         *
+         * What makes the conversation *resumable*: Connect upserts against it and
+         * `conversations.list`/`get` read it back. Persisted only alongside
+         * `asUser` - a conversation belongs to a person, and a server-to-server
+         * call acts as nobody. Omit it to keep a turn out of history entirely.
+         */
+        conversationId?: string;
         /**
          * Your application's screens, so the assistant answers in your product's
          * words and can link into it - see `ConnectScreen`. Prose and links only:
@@ -34,6 +43,45 @@ export declare class AiResource {
     }, options?: {
         signal?: AbortSignal;
     }): Promise<Response>;
+    /**
+     * The signed-in user's past conversations in your application, most recent
+     * first.
+     *
+     * `asUser` is required rather than optional here, unlike on `chat`: the rows
+     * are scoped to a person, and there is no application-wide view of them to
+     * fall back to. Connect reads the user and the workspace from the token.
+     *
+     * Cursor-paginated with no total - the list is ordered by last use, which
+     * moves while it is being read.
+     */
+    listConversations(input: {
+        asUser: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<AiConversationList>;
+    /**
+     * One stored transcript, oldest turn first.
+     *
+     * `turns[].parts` comes back exactly as the model produced it - prose,
+     * reasoning and tool calls in order - so it can be handed straight back to a
+     * chat UI. Not this user's, or not your application's, is a `404` either way.
+     */
+    getConversation(input: {
+        conversationId: string;
+        asUser: string;
+    }): Promise<AiConversationDetail>;
+    /**
+     * Deletes a conversation and every turn beneath it.
+     *
+     * Idempotent - one already gone answers `{ deleted: true }`, so a retry after
+     * a dropped response does not read as a failure.
+     */
+    deleteConversation(input: {
+        conversationId: string;
+        asUser: string;
+    }): Promise<{
+        deleted: true;
+    }>;
     /** Extract structured JSON from a file or image URL, against a platform extraction schema referenced by id. */
     extract<T = unknown>(input: {
         schemaId: string;

package/dist/types/types.d.ts

@@ -538,6 +538,54 @@ export interface ChatMessage {
     role: "user" | "assistant" | "system";
     [field: string]: unknown;
 }
+/**
+ * One row of Ask AI history.
+ *
+ * A conversation exists only if the turns that made it carried a
+ * `conversationId` *and* were sent on a user's behalf - see `AiResource.chat`.
+ * It belongs to one person in one of your workspaces, and never leaves your
+ * application: a workspace subscribing to two products keeps two lists.
+ */
+export interface AiConversation {
+    id: string;
+    /** Derived from the first thing the user said - no model call, so it costs nothing. */
+    title: string;
+    /** ISO-8601. */
+    createdAt: string;
+    /**
+     * ISO-8601, and the sort key - a conversation returned to a week later is at
+     * the top, not where it was created.
+     */
+    updatedAt: string;
+}
+export interface AiConversationList {
+    conversations: AiConversation[];
+    /** Pass back as `cursor` for the next page; `null` at the end. */
+    nextCursor: string | null;
+}
+/** One stored turn, in the AI SDK's own shape. */
+export interface AiConversationTurn {
+    id: string;
+    role: "user" | "assistant";
+    /**
+     * The message's parts exactly as the model produced them - prose, reasoning
+     * and tool calls, in the order they arrived.
+     *
+     * Opaque on purpose. The shape is the AI SDK's and moves with it, so a type
+     * restating it here would start rejecting transcripts the moment the SDK adds
+     * a part kind. Flattening it to text is the other mistake: the order is the
+     * model's own argument, and a flattened turn cannot be resumed.
+     */
+    parts: unknown[];
+    /** Position in the conversation. Turns arrive in this order. */
+    sequence: number;
+    /** ISO-8601. */
+    createdAt: string;
+}
+export interface AiConversationDetail {
+    conversation: AiConversation;
+    turns: AiConversationTurn[];
+}
 export interface WorkspaceApp {
     applicationId: string;
     /** Stable, human-readable key - branch on this, not `applicationId`, which is per-environment. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmoops/connect-sdk",
-  "version": "0.29.0",
+  "version": "0.30.1",
   "description": "Official server-side SDK for the CosmoOps Connect platform API - Login with Connect, entitlements, billing and metering.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "commonjs",