@cosmoops/connect-sdk 0.27.0 → 0.28.0

package/CHANGELOG.md

@@ -3,12 +3,61 @@
 `@cosmoops/connect-sdk` follows semver, with the 0.x convention that **minor
 versions may carry breaking changes** and patch versions never do.
 
+## 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

@@ -161,4 +161,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.28.0";

package/dist/esm/server/client.js

@@ -157,4 +157,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.28.0";

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

@@ -123,4 +123,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.28.0";

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

package/package.json

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