@cosmoops/connect-sdk 0.29.0 → 0.30.0

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.0",
   "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",