@cosmoops/connect-sdk 0.27.0 → 0.29.0

package/CHANGELOG.md

@@ -3,12 +3,105 @@
 `@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
+deletion. It now carries the seven a system of record is actually built on —
+calls, appointments and contacts — so the work your customers do inside
+Connect can reach the product they do the rest of their work in.
+
+### Added
+
+- Seven webhook event types, with their payloads fully typed on
+  `ConnectWebhookEventMap`: `call.completed`, `call.missed`,
+  `booking.confirmed`, `booking.cancelled`, `booking.rescheduled`,
+  `contact.created` and `contact.updated`. Register handlers for them on
+  `createConnectWebhookHandler` exactly as you do the existing four.
+- `ConnectCallDirection` and `ConnectContactSource`, the two unions those
+  payloads carry.
+
+  These are **activity** events rather than lifecycle ones, and the difference
+  decides who receives them: they are delivered only to applications the
+  workspace is actually subscribed to, so a lapsed customer stops emitting on
+  the same boundary that stops their access.
+
+  Three conventions are worth reading before you write a handler, each
+  documented on the types themselves. Phone numbers are E.164. A call event
+  identifies its party by `contactPhone` and deliberately carries no
+  `contactId` — Connect resolves a caller *by* the number and at the moment a
+  call ends it often has not, so the field would be `null` on most deliveries.
+  And `booking.rescheduled` carries `previousBookingId` as well as `bookingId`,
+  because Connect retires the old booking and writes a new one: reconcile on
+  the previous id or you will end up holding two appointments.
+
+### Fixed
+
+- `Booking` fixtures in the bundled tests compile again — the type gained a
+  required `hostMemberIds` in 0.27.0 and one fixture was missed. No runtime
+  change.
+
+### A note on exhaustiveness
+
+`ConnectWebhookEventType` is a union that grows, and this release grows it.
+`createConnectWebhookHandler` is unaffected — its `on` map is partial and it
+answers 200 to anything you have not registered. A hand-written `switch` with
+an exhaustive `never` check on that union will now fail to compile until you
+add the new members; that is the documented contract of this union rather than
+a break, and it is the reason the handler exists.
+
 ## 0.27.0
 
 A minor rather than a patch because `Booking` gains a required field, so a
 hand-written object satisfying the old interface no longer type-checks. Nothing
 you *read* from the API breaks.
 
+0.26.1 was never published; its note below ships as part of this release, so the
+registry goes 0.26.0 → 0.27.0.
+
 ### Added
 
 - **`connect.scheduling.getBooking()`** - one appointment, by the id you

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.27.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.27.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.27.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

@@ -775,7 +775,7 @@ export interface EmitEventsResponse {
  * `createConnectWebhookHandler` simply ignores anything you have not
  * registered a handler for.
  */
-export type ConnectWebhookEventType = "workspace.deletion_scheduled" | "workspace.deletion_cancelled" | "workspace.deleted" | "subscription.cancelled";
+export type ConnectWebhookEventType = "workspace.deletion_scheduled" | "workspace.deletion_cancelled" | "workspace.deleted" | "subscription.cancelled" | "call.completed" | "call.missed" | "booking.confirmed" | "booking.cancelled" | "booking.rescheduled" | "contact.created" | "contact.updated";
 /**
  * A workspace's deletion has been confirmed and the grace window is running.
  *
@@ -815,12 +815,197 @@ export interface SubscriptionCancelledEvent {
     subscriptionId: string;
     applicationId: string;
 }
+/** Which way a call went. */
+export type ConnectCallDirection = "inbound" | "outbound";
+/**
+ * A call ended.
+ *
+ * The event an external system of record is built on: it is what turns a
+ * conversation that happened in Connect's telephony into a row in your own
+ * timeline with nobody retyping it. Fires for every completed call, whether an
+ * agent answered it or a person did.
+ */
+export interface CallCompletedEvent {
+    workspaceId: string;
+    callId: string;
+    channelId: string | null;
+    /**
+     * E.164, and the only identity a call event carries.
+     *
+     * There is deliberately no `contactId`: Connect resolves a caller to a
+     * contact by number, and at the moment a call ends it may not have done so
+     * at all - the field would be `null` on most deliveries, which is a field
+     * that silently does nothing. Match on this instead. It is the same
+     * canonical form `contacts.lookupByPhone` takes, so resolving it is one call
+     * if you want the contact.
+     */
+    contactPhone: string | null;
+    direction: ConnectCallDirection;
+    /** How it ended, as Connect's telephony reported it - `"completed"`, `"transferred"`, … */
+    outcome: string;
+    durationSeconds: number;
+    /**
+     * What the agent's skills captured during the conversation, keyed by the
+     * capture fields the agent declares.
+     *
+     * Shapeless on purpose - the keys and the value types are whatever that
+     * agent's `extractionSchema` declares, which Connect does not constrain.
+     * `{}` on most calls, since an unanswered or human-answered call extracts
+     * nothing, so treat every key as optional rather than checking the object
+     * for presence.
+     */
+    extraction: Record<string, unknown>;
+    /** ISO-8601. */
+    occurredAt: string;
+}
+/**
+ * A call reached a channel and nothing answered it.
+ *
+ * Its own event rather than an `outcome` on the one above, because the action
+ * differs in kind: a completed call is something to file, a missed one is
+ * somebody to ring back. Treating this as a lead is the right thing to do
+ * with it.
+ */
+export interface CallMissedEvent {
+    workspaceId: string;
+    callId: string;
+    channelId: string | null;
+    /** E.164, and the only identity this carries - see `CallCompletedEvent.contactPhone`. */
+    contactPhone: string | null;
+    direction: ConnectCallDirection;
+    /** ISO-8601. */
+    occurredAt: string;
+}
+/**
+ * An appointment was booked and is holding its slot.
+ *
+ * Raised however it was booked - the customer's portal, the public booking
+ * page, a voice agent mid-call, or your own API call - so you get one shape
+ * for all four and never have to reconcile "did we create this, or did they?".
+ * Dedupe on `bookingId`, not on the envelope alone.
+ */
+export interface BookingConfirmedEvent {
+    workspaceId: string;
+    bookingId: string;
+    eventTypeId: string;
+    eventTypeName: string;
+    /** ISO-8601, UTC. Render it in `timezone`, which is the workspace's, not the viewer's. */
+    startAt: string;
+    endAt: string;
+    /** IANA zone the appointment was booked in. */
+    timezone: string;
+    attendeeName: string;
+    attendeeEmail: string | null;
+    /** E.164. */
+    attendeePhone: string | null;
+    contactId: string | null;
+    /** Connect user ids of the hosts. */
+    hostMemberIds: string[];
+    /** ISO-8601. */
+    occurredAt: string;
+}
+/** An appointment was cancelled. The slot is free and any prep against it is void. */
+export interface BookingCancelledEvent {
+    workspaceId: string;
+    bookingId: string;
+    eventTypeId: string;
+    eventTypeName: string;
+    /** ISO-8601. The time it *was* going to happen. */
+    startAt: string;
+    attendeeName: string;
+    contactId: string | null;
+    /** ISO-8601. */
+    occurredAt: string;
+}
+/**
+ * An appointment moved.
+ *
+ * Connect retires the old booking and writes a new one rather than mutating
+ * it, so this carries **both ids**: `bookingId` is the row that now exists and
+ * `previousBookingId` is the one you are already holding. Reconcile on the
+ * previous id or you will end up with two appointments.
+ */
+export interface BookingRescheduledEvent {
+    workspaceId: string;
+    bookingId: string;
+    eventTypeId: string;
+    eventTypeName: string;
+    /** ISO-8601, the new time. */
+    startAt: string;
+    endAt: string;
+    previousBookingId: string;
+    /** ISO-8601, the time it was before. */
+    previousStartAt: string;
+    timezone: string;
+    attendeeName: string;
+    contactId: string | null;
+    /** ISO-8601. */
+    occurredAt: string;
+}
+/**
+ * How Connect came to know a contact.
+ *
+ * `extraction` is the interesting one: an agent's skill captured them from
+ * what was said, with nobody typing anything. `call` means the number was seen
+ * on a call. `manual` and `import` are the two a human stands behind, and
+ * Connect lets only those overwrite a field that already has a value.
+ */
+export type ConnectContactSource = "call" | "manual" | "import" | "api" | "extraction";
+/**
+ * Connect learned about a person.
+ *
+ * The event with no equivalent anywhere else in this API: most often an agent
+ * captured them mid-call through the `contact-capture` skill, so the contact
+ * exists in Connect and your product has never heard of them. Without this the
+ * capture is invisible where the customer actually works.
+ */
+export interface ContactCreatedEvent {
+    workspaceId: string;
+    contactId: string;
+    name: string | null;
+    /** E.164. */
+    phone: string | null;
+    email: string | null;
+    company: string | null;
+    source: ConnectContactSource;
+    /** ISO-8601. */
+    occurredAt: string;
+}
+/**
+ * A known contact's details changed.
+ *
+ * `changed` names the fields that actually moved, so you can apply a patch
+ * rather than overwriting fields your own users may have curated - a customer
+ * who corrected a company name in your product should not have it replaced by
+ * what an agent heard over a bad line.
+ */
+export interface ContactUpdatedEvent {
+    workspaceId: string;
+    contactId: string;
+    name: string | null;
+    /** E.164. */
+    phone: string | null;
+    email: string | null;
+    company: string | null;
+    /** The field names that changed on this update. */
+    changed: string[];
+    source: ConnectContactSource;
+    /** ISO-8601. */
+    occurredAt: string;
+}
 /** Maps each event type to the shape of its `data`. */
 export interface ConnectWebhookEventMap {
     "workspace.deletion_scheduled": WorkspaceDeletionScheduledEvent;
     "workspace.deletion_cancelled": WorkspaceDeletionCancelledEvent;
     "workspace.deleted": WorkspaceDeletedEvent;
     "subscription.cancelled": SubscriptionCancelledEvent;
+    "call.completed": CallCompletedEvent;
+    "call.missed": CallMissedEvent;
+    "booking.confirmed": BookingConfirmedEvent;
+    "booking.cancelled": BookingCancelledEvent;
+    "booking.rescheduled": BookingRescheduledEvent;
+    "contact.created": ContactCreatedEvent;
+    "contact.updated": ContactUpdatedEvent;
 }
 /** The envelope, as it arrives on the wire. */
 export interface ConnectWebhookEnvelope<T extends ConnectWebhookEventType = ConnectWebhookEventType> {
@@ -1637,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.27.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",