@cosmoops/connect-sdk 0.28.0 → 0.30.0

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/esm/server/resources/conversations.js

@@ -0,0 +1,66 @@
+import { request } from "../http.js";
+import { actingAs } from "./acting-as.js";
+/**
+ * What a workspace's agents are saying in writing.
+ *
+ * **The sibling of `calls`, with one difference that decides how it is
+ * gated: these are the *workspace's* threads, not your application's.** A call
+ * arrived on a channel you hold, so `calls.list` is scoped to your
+ * application. A conversation lives in the workspace's own subtree and belongs
+ * to it the way its contact book does - so reading one needs a live
+ * subscription in that workspace, and, when the call comes from a browser
+ * through the bridge, the signed-in member's own `agent:read`.
+ *
+ * Read-only, and deliberately. Sending on a thread is not a missing verb:
+ * inside WhatsApp's 24-hour window a reply is the agent's to make, outside it
+ * only an approved template may be sent, and posting into a thread would mean
+ * saying which of those it was and what it means for the agent still
+ * answering.
+ */
+export class ConversationsResource {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /**
+     * The workspace's threads, newest activity first.
+     *
+     * **Page until `hasMore` is `false`; do not stop on an empty `items`.** An
+     * inbox grows without bound, so there is no total count to page against.
+     */
+    list(input) {
+        return request(this.transport, {
+            method: "GET",
+            path: "/conversations",
+            query: {
+                workspaceId: input.workspaceId,
+                contactAddress: input.contactAddress,
+                status: input.status,
+                cursor: input.cursor,
+                limit: input.limit === undefined ? undefined : String(input.limit),
+            },
+            headers: actingAs(input.asUser),
+        });
+    }
+    /**
+     * One thread and its recent messages, oldest first.
+     *
+     * **Capped, not paged** - you get the same window the agent itself sees when
+     * it composes a reply, so you are never shown less context than it used.
+     *
+     * Turns that produced no message are included and carry `failure`. Render
+     * them: a transcript that silently drops them reads as a customer being
+     * ignored, which is the opposite of what happened.
+     *
+     * Throws `ConnectError` with `code: "not_found"` for a thread this workspace
+     * does not hold.
+     */
+    get(conversationId, options) {
+        return request(this.transport, {
+            method: "GET",
+            path: `/conversations/${encodeURIComponent(conversationId)}`,
+            query: { workspaceId: options.workspaceId },
+            headers: actingAs(options.asUser),
+        });
+    }
+}

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/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

@@ -9,6 +9,7 @@ import { SchedulingResource } from "./resources/scheduling.js";
 import { ContactsResource } from "./resources/contacts.js";
 import { ChannelsResource } from "./resources/channels.js";
 import { CallsResource } from "./resources/calls.js";
+import { ConversationsResource } from "./resources/conversations.js";
 import { KvResource } from "./resources/kv.js";
 import { BillingResource } from "./resources/billing.js";
 import { DriveResource } from "./resources/drive.js";
@@ -88,6 +89,8 @@ export declare class ConnectClient {
     readonly channels: ChannelsResource;
     /** The calls that arrived on those channels, with their transcripts. */
     readonly calls: CallsResource;
+    /** The message threads a subscribing workspace's agents are holding. */
+    readonly conversations: ConversationsResource;
     /** RAG chat and structured extraction. */
     readonly ai: AiResource;
     readonly enrichment: EnrichmentResource;
@@ -123,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.28.0";
+export declare const SDK_VERSION = "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/server/resources/conversations.d.ts

@@ -0,0 +1,68 @@
+import { type TransportOptions } from "../http.js";
+import type { ConversationDetail, ConversationsPage } from "../../types.js";
+export interface ListConversationsInput {
+    workspaceId: string;
+    /**
+     * Narrow to one party's threads.
+     *
+     * Any reasonable spelling - `+919000000001`, `919000000001`,
+     * `+91 90000 00001` all resolve to the same threads, because the number is
+     * normalized server-side before the match. This is the filter to reach for
+     * beside your own customer record: you hold a phone number, and you cannot
+     * derive a conversation id from one because the id is built from a *hashed*
+     * key.
+     */
+    contactAddress?: string;
+    status?: "open" | "snoozed" | "closed";
+    /** From a previous page's `nextCursor`. */
+    cursor?: string;
+    /** 1-50, default 20. */
+    limit?: number;
+    /** See `ActingAsOption` on the scheduling resource - same contract. */
+    asUser?: string;
+}
+/**
+ * What a workspace's agents are saying in writing.
+ *
+ * **The sibling of `calls`, with one difference that decides how it is
+ * gated: these are the *workspace's* threads, not your application's.** A call
+ * arrived on a channel you hold, so `calls.list` is scoped to your
+ * application. A conversation lives in the workspace's own subtree and belongs
+ * to it the way its contact book does - so reading one needs a live
+ * subscription in that workspace, and, when the call comes from a browser
+ * through the bridge, the signed-in member's own `agent:read`.
+ *
+ * Read-only, and deliberately. Sending on a thread is not a missing verb:
+ * inside WhatsApp's 24-hour window a reply is the agent's to make, outside it
+ * only an approved template may be sent, and posting into a thread would mean
+ * saying which of those it was and what it means for the agent still
+ * answering.
+ */
+export declare class ConversationsResource {
+    private readonly transport;
+    constructor(transport: TransportOptions);
+    /**
+     * The workspace's threads, newest activity first.
+     *
+     * **Page until `hasMore` is `false`; do not stop on an empty `items`.** An
+     * inbox grows without bound, so there is no total count to page against.
+     */
+    list(input: ListConversationsInput): Promise<ConversationsPage>;
+    /**
+     * One thread and its recent messages, oldest first.
+     *
+     * **Capped, not paged** - you get the same window the agent itself sees when
+     * it composes a reply, so you are never shown less context than it used.
+     *
+     * Turns that produced no message are included and carry `failure`. Render
+     * them: a transcript that silently drops them reads as a customer being
+     * ignored, which is the opposite of what happened.
+     *
+     * Throws `ConnectError` with `code: "not_found"` for a thread this workspace
+     * does not hold.
+     */
+    get(conversationId: string, options: {
+        workspaceId: string;
+        asUser?: string;
+    }): Promise<ConversationDetail>;
+}

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. */
@@ -1822,3 +1870,85 @@ export interface CallsPage {
     nextCursor: string | null;
     hasMore: boolean;
 }
+/**
+ * One message thread a workspace's agents are holding.
+ *
+ * Hand-written rather than imported from Connect, like every other type in
+ * this file - `conformance.test.ts` type-checks it against the server DTO, so
+ * drift fails the build here rather than in your integration.
+ *
+ * Dates are ISO-8601 strings. JSON has no date type, and a UTC ISO string
+ * sorts lexicographically in chronological order, so these compare and
+ * range-filter without being parsed first.
+ */
+export interface ConnectConversation {
+    id: string;
+    /** The channel the thread arrived on. */
+    channelId: string;
+    /** Today always `whatsapp` - a voice channel produces calls, not threads. */
+    kind: "whatsapp";
+    /** The other party, normalized to E.164. */
+    contactAddress: string;
+    /**
+     * The Connect contact this thread is about, once one has been matched.
+     *
+     * The join to your own records - store this on yours rather than matching
+     * phone numbers. See `ContactsResource`.
+     */
+    contactId: string | null;
+    /** As the provider reported it, when it did. */
+    contactName: string | null;
+    status: "open" | "snoozed" | "closed";
+    /** `null` means nothing is answering: no routing, or a human took over. */
+    agentId: string | null;
+    lastInboundAt: string;
+    lastOutboundAt: string | null;
+    lastMessagePreview: string;
+    /**
+     * Whether a free-form reply is still allowed, computed against **Connect's**
+     * clock.
+     *
+     * WhatsApp allows one only inside 24 hours of the customer's last message;
+     * outside it, only an approved template may be sent. Do not re-derive this
+     * from `lastInboundAt` against your own clock - a skew shows up as a thread
+     * your UI calls answerable when it is not.
+     */
+    canReplyFreely: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Why a turn produced no message.
+ *
+ * `refused` is not a failure at all - it is the agent deciding not to answer,
+ * which is what it is for.
+ */
+export type ConnectMessageFailure = "window_closed" | "no_agent" | "model_error" | "send_failed" | "refused";
+/** One message on a thread. A turn that sent nothing still appears, carrying `failure`. */
+export interface ConnectConversationMessage {
+    id: string;
+    direction: "inbound" | "outbound";
+    /**
+     * Who produced it.
+     *
+     * `agent` and `human` are both outbound and deliberately distinguished - a
+     * thread that cannot show which replies were automatic is one nobody trusts
+     * enough to leave running. `system` is neither party: a turn Connect itself
+     * recorded, which is what a `failure` row is.
+     */
+    author: "contact" | "agent" | "human" | "system";
+    text: string;
+    failure: ConnectMessageFailure | null;
+    createdAt: string;
+}
+/** A thread and its recent messages, oldest first. Capped rather than paged. */
+export interface ConversationDetail {
+    conversation: ConnectConversation;
+    messages: ConnectConversationMessage[];
+}
+/** One page of threads, newest activity first. Page until `hasMore` is `false`. */
+export interface ConversationsPage {
+    items: ConnectConversation[];
+    nextCursor: string | null;
+    hasMore: boolean;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmoops/connect-sdk",
-  "version": "0.28.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",