@cosmoops/connect-sdk 0.28.0 → 0.29.0

package/CHANGELOG.md

@@ -3,6 +3,50 @@
 `@cosmoops/connect-sdk` follows semver, with the 0.x convention that **minor
 versions may carry breaking changes** and patch versions never do.
 
+## 0.29.0
+
+Voice was readable and writing was not. `calls.list` has always let a partner
+read back what a customer said out loud; the WhatsApp threads a workspace's
+agents hold had no partner surface at all, so a CRM could show every call on a
+contact and nothing they had typed.
+
+### Added
+
+- `connect.conversations.list({ workspaceId, contactAddress?, status? })` and
+  `connect.conversations.get(id, { workspaceId })`, plus the four types they
+  answer with: `ConnectConversation`, `ConnectConversationMessage`,
+  `ConversationsPage` and `ConversationDetail`.
+
+  **These are the *workspace's* threads, not your application's**, which is the
+  difference from `calls` and it decides how they are gated. A call arrived on
+  a channel you hold, so `calls.list` is scoped to your application by the key
+  alone. A conversation lives in the workspace's own subtree and belongs to it
+  the way its contact book does — so reading one needs the `conversations:read`
+  scope **and** a live subscription in that workspace, and, when the call comes
+  through the browser bridge, the signed-in member's own `agent:read`.
+
+  Three things are worth reading before you render one:
+
+  `contactAddress` 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 —
+  the id is built from a hashed key, deliberately, so an id you could guess is
+  an id you could probe. Send the number however your records spell it.
+
+  `canReplyFreely` is computed against Connect's clock, and re-deriving it from
+  `lastInboundAt` against yours is the mistake to avoid: WhatsApp allows a
+  free-form reply only inside 24 hours of the customer's last message, and a
+  skew between your server and Connect's shows up as a thread your UI calls
+  answerable when it is not.
+
+  Messages that sent nothing 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. `refused` is not a failure at all: it is
+  the agent deciding not to answer, which is what it is for.
+
+  Read-only, and deliberately. Sending on a thread would mean saying whether it
+  is a free-form reply or an approved template, and what that means for the
+  agent still answering it.
+
 ## 0.28.0
 
 Connect's webhook bus carried four events, all of them about billing and

package/dist/cjs/server/client.js

@@ -11,6 +11,7 @@ const scheduling_js_1 = require("./resources/scheduling.js");
 const contacts_js_1 = require("./resources/contacts.js");
 const channels_js_1 = require("./resources/channels.js");
 const calls_js_1 = require("./resources/calls.js");
+const conversations_js_1 = require("./resources/conversations.js");
 const kv_js_1 = require("./resources/kv.js");
 const billing_js_1 = require("./resources/billing.js");
 const drive_js_1 = require("./resources/drive.js");
@@ -92,6 +93,8 @@ class ConnectClient {
     channels;
     /** The calls that arrived on those channels, with their transcripts. */
     calls;
+    /** The message threads a subscribing workspace's agents are holding. */
+    conversations;
     /** RAG chat and structured extraction. */
     ai;
     enrichment;
@@ -145,6 +148,7 @@ class ConnectClient {
         this.contacts = new contacts_js_1.ContactsResource(transport);
         this.channels = new channels_js_1.ChannelsResource(transport);
         this.calls = new calls_js_1.CallsResource(transport);
+        this.conversations = new conversations_js_1.ConversationsResource(transport);
         this.ai = new ai_js_1.AiResource(transport);
         this.enrichment = new enrichment_js_1.EnrichmentResource(transport);
         this.data = new data_js_1.DataResource(transport);
@@ -161,4 +165,4 @@ class ConnectClient {
 }
 exports.ConnectClient = ConnectClient;
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-exports.SDK_VERSION = "0.28.0";
+exports.SDK_VERSION = "0.29.0";

package/dist/cjs/server/resources/conversations.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConversationsResource = void 0;
+const http_js_1 = require("../http.js");
+const acting_as_js_1 = require("./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.
+ */
+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 (0, http_js_1.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: (0, acting_as_js_1.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 (0, http_js_1.request)(this.transport, {
+            method: "GET",
+            path: `/conversations/${encodeURIComponent(conversationId)}`,
+            query: { workspaceId: options.workspaceId },
+            headers: (0, acting_as_js_1.actingAs)(options.asUser),
+        });
+    }
+}
+exports.ConversationsResource = ConversationsResource;

package/dist/esm/server/client.js

@@ -8,6 +8,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";
@@ -89,6 +90,8 @@ export class ConnectClient {
     channels;
     /** The calls that arrived on those channels, with their transcripts. */
     calls;
+    /** The message threads a subscribing workspace's agents are holding. */
+    conversations;
     /** RAG chat and structured extraction. */
     ai;
     enrichment;
@@ -142,6 +145,7 @@ export class ConnectClient {
         this.contacts = new ContactsResource(transport);
         this.channels = new ChannelsResource(transport);
         this.calls = new CallsResource(transport);
+        this.conversations = new ConversationsResource(transport);
         this.ai = new AiResource(transport);
         this.enrichment = new EnrichmentResource(transport);
         this.data = new DataResource(transport);
@@ -157,4 +161,4 @@ export class ConnectClient {
     }
 }
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-export const SDK_VERSION = "0.28.0";
+export const SDK_VERSION = "0.29.0";

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/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.29.0";

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

@@ -1822,3 +1822,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.29.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",