@cosmoops/connect-sdk 0.19.0 → 0.21.0

package/dist/types/client/components/one-tap.d.ts

@@ -0,0 +1,50 @@
+/**
+ * "Continue as …" - a signed-out visitor who is already signed into Connect is
+ * offered their account, and one tap signs them in **without leaving the page**.
+ *
+ * The prompt is the visible half; what makes it worth having is that finding
+ * out costs one `fetch` rather than a redirect. `ConnectProviderProps.silentSignIn`
+ * answers the same question by bouncing the browser to Connect and back, which
+ * means a visible full-page navigation on the first load of every signed-out
+ * visit, nothing shown to the visitor while it happens, and no way to say no.
+ *
+ * ```tsx
+ * <ConnectProvider>
+ *   <App />
+ *   <ConnectOneTap />
+ * </ConnectProvider>
+ * ```
+ *
+ * ### It only appears when it can actually help
+ *
+ * Nothing renders unless the visitor is signed out here, signed in to Connect,
+ * and has not recently dismissed the prompt or signed out of this application.
+ * A visitor with no Connect session sees nothing at all, ever - which is why
+ * this is safe to mount unconditionally, unlike `silentSignIn`, whose cost
+ * lands on exactly the people it cannot help.
+ *
+ * ### Two prompts, because consent is not assumed
+ *
+ * A visitor who has authorised this application before gets their name, email,
+ * workspace and photo, because Connect will release those to an application
+ * they have already agreed to. A visitor who has not gets an impersonal prompt
+ * and a tap that leads to the real consent screen - Connect does not hand over
+ * so much as a first name until that has happened once.
+ *
+ * ### Placement
+ *
+ * Bottom of the viewport on a phone, bottom-right from `sm:` up. Deliberately
+ * not top-right: on a phone that is where the browser chrome and the
+ * application's own header live, and this must never cover the thing the
+ * visitor came to use.
+ */
+export interface ConnectOneTapProps {
+    /**
+     * Where to send someone whose tap needs the interactive screen - the first
+     * connection to this application, or an account that has an MFA or
+     * subscription step outstanding. Defaults to the bridge's own `/signin`.
+     */
+    onInteractiveSignIn?: () => void;
+    className?: string;
+}
+export declare function ConnectOneTap({ onInteractiveSignIn, className }: ConnectOneTapProps): import("react").JSX.Element | null;

package/dist/types/client/components/plan-pricing.d.ts

@@ -16,6 +16,19 @@
  * and nothing in it needs to be.
  */
 import type { AppliedDiscount, Plan, SubscriptionResponse } from "../../types.js";
+/**
+ * Whether a plan costs nothing - the SDK's copy of Connect's `isFreeSelection`
+ * (`packages/data/src/payments/free-plan.ts`), which is what the server
+ * actually decides the free-activation path with.
+ *
+ * A copy rather than an import for the reason `types.ts` gives: the published
+ * package carries none of Connect's internals. The rule is one line and does
+ * not drift, and `conformance.test.ts` pins the shape either side of it.
+ *
+ * @param addonsTotal Paise of the add-ons *selected*, not of the plan's whole
+ * catalog. A free plan with a paid add-on ticked is not free.
+ */
+export declare function isFreePlan(price: number, addonsTotal?: number): boolean;
 /** Paise are the wire unit everywhere in Connect; rupees are the display unit. */
 export declare function formatPrice(paise: number): string;
 /**

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

@@ -11,7 +11,7 @@
  * change lands identically in all of them.
  */
 export { ConnectProvider, useConnect, useConnectUser, useConnectWorkspaceType, useConnectAudience, useConnectPlatformAccess, useConnectEntitlements, useConnectPlans, useConnectApps, useConnectCompanyProfile, useConnectAddonUsage, useConnectSessions, useConnectIntegrations, useConnectResource, CONNECT_APP_URL, } from "./provider.js";
-export type { ConnectProviderProps, ConnectContextValue, ConnectSession } from "./provider.js";
+export type { ConnectProviderProps, ConnectContextValue, ConnectSession, ConnectOneTapHint, ConnectOneTapFailure, } from "./provider.js";
 export { blockingBlockers, normalizePlanFeatures } from "../helpers.js";
 export type { WirePlanFeature } from "../helpers.js";
 export { ConnectError, isConnectError } from "../errors.js";
@@ -23,6 +23,8 @@ export { ConnectLogo } from "./components/logo.js";
 export type { ConnectLogoProps } from "./components/logo.js";
 export { ConnectLoginButton, ConnectRegisterButton } from "./components/auth-buttons.js";
 export type { ConnectAuthButtonProps } from "./components/auth-buttons.js";
+export { ConnectOneTap } from "./components/one-tap.js";
+export type { ConnectOneTapProps } from "./components/one-tap.js";
 export { ConnectUserButton, ConnectProfileModal, 
 /** @deprecated Renamed to `ConnectUserButton`. */
 ConnectUserMenu, ConnectManageSubscriptionButton, ConnectInvoicesButton, ConnectProfileButton, ConnectHomeButton, ConnectSignOutButton, } from "./components/user-menu.js";
@@ -82,7 +84,7 @@ export { ConnectFilterTabs } from "./components/filter-tabs.js";
 export type { ConnectFilterTabsProps, ConnectFilterTabsOption } from "./components/filter-tabs.js";
 export { useConnectCheckout, buildCheckoutUrl } from "./use-checkout.js";
 export type { ConnectCheckoutStatus, ConnectCheckoutState, ConnectEntitlements, StartCheckoutOptions, CheckoutUrlOptions, } from "./use-checkout.js";
-export { formatPrice, monthlyOf, resolveAction, annualSaving, discountLabel, ACTION_LABEL, groupPlansByTier, resolvePlanGroup, } from "./components/plan-pricing.js";
+export { formatPrice, monthlyOf, resolveAction, annualSaving, discountLabel, ACTION_LABEL, isFreePlan, groupPlansByTier, resolvePlanGroup, } from "./components/plan-pricing.js";
 export type { PlanAction, PlanTier, ComparablePlan } from "./components/plan-pricing.js";
 export { ConnectWorkspaceSwitcher } from "./components/workspace-switcher.js";
 export type { ConnectWorkspaceSwitcherProps } from "./components/workspace-switcher.js";

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

@@ -20,7 +20,52 @@ export interface ConnectSession {
      * `null` on a signed-in session.
      */
     audience: SessionAudience | null;
+    /**
+     * Where the browser may ask Connect about the visitor, or `null` when this
+     * deployment cannot run One Tap - see `IdentityResource.oneTapEndpoints`.
+     *
+     * Delivered on the session read the provider already makes, so discovering
+     * One Tap costs no extra request. Optional because an older bridge will not
+     * send it.
+     */
+    oneTap?: {
+        hintUrl: string;
+        authorizeUrl: string;
+    } | null;
 }
+/**
+ * What Connect says about the visitor, before anything has been signed.
+ *
+ * Note what is *not* here when `consented` is `false`: no name, no email, no
+ * photo. Connect withholds all of it until the visitor has authorised this
+ * application at least once, so the first prompt an application ever shows is
+ * necessarily the impersonal one.
+ */
+export interface ConnectOneTapHint {
+    status: "signed_out" | "signed_in";
+    consented?: boolean;
+    user?: {
+        displayName: string | null;
+        email: string | null;
+        photoUrl: string | null;
+    };
+    workspace?: {
+        name: string;
+    } | null;
+    application?: {
+        name: string;
+        iconUrl: string | null;
+    };
+}
+/**
+ * Why a tap did not end in a session.
+ *
+ * Every one of these is ordinary traffic rather than a fault, which is why
+ * `oneTapSignIn` reports them as a value instead of throwing: `consent_required`
+ * and `interaction_required` both mean "this needs the interactive screen", and
+ * that is a hand-off, not an error to show anybody.
+ */
+export type ConnectOneTapFailure = "unavailable" | "login_required" | "consent_required" | "interaction_required" | "rate_limited" | "failed";
 export interface ConnectContextValue {
     /**
      * Public OAuth client id, if `clientId` was passed to `<ConnectProvider>` -
@@ -89,6 +134,42 @@ export interface ConnectContextValue {
     streamResource(path: string, body: unknown, options?: {
         signal?: AbortSignal;
     }): Promise<Response>;
+    /**
+     * Asks Connect whether this visitor is already signed in there, without
+     * navigating anywhere.
+     *
+     * This is the read `<ConnectOneTap>` is built on, and the reason One Tap
+     * beats `silentSignIn`: one credentialed `fetch` answers the question that
+     * used to cost a full-page redirect to Connect and back.
+     *
+     * It only works when the application is served from the **same site** as
+     * Connect - a `cosmoops.com` subdomain. `SameSite` is judged on the
+     * registrable domain, so the visitor's Connect session cookie rides along
+     * from `crm.cosmoops.com` and does not from anywhere else. Off-site
+     * deployments get `signed_out`, which is why every caller treats that answer
+     * as "say nothing" rather than "this visitor has no account".
+     *
+     * Resolves to `null` when the bridge offers no One Tap endpoints, or when the
+     * request itself fails - a Connect that cannot be reached says nothing about
+     * whether anyone is signed into it.
+     */
+    readOneTapHint(): Promise<ConnectOneTapHint | null>;
+    /**
+     * Completes a One Tap sign-in, with no navigation at any point.
+     *
+     * Three requests: the bridge mints a PKCE pair and keeps the verifier, Connect
+     * hands back an authorization code, the bridge exchanges it and stores the
+     * session. The page only ever holds the code, which is worthless without the
+     * verifier it never sees.
+     *
+     * Refreshes the session on success, so consumers re-render signed in.
+     */
+    oneTapSignIn(): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        reason: ConnectOneTapFailure;
+    }>;
 }
 export interface ConnectProviderProps {
     /**

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

@@ -6,6 +6,8 @@ import { DataResource } from "./resources/data.js";
 import { WorkspacesResource } from "./resources/workspaces.js";
 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 { KvResource } from "./resources/kv.js";
 import { BillingResource } from "./resources/billing.js";
 import { DriveResource } from "./resources/drive.js";
@@ -81,6 +83,10 @@ export declare class ConnectClient {
     readonly scheduling: SchedulingResource;
     /** Who a workspace already knows how to reach, by phone or by id. */
     readonly contacts: ContactsResource;
+    /** The phone numbers Connect has assigned to your application, and where each one routes. */
+    readonly channels: ChannelsResource;
+    /** The calls that arrived on those channels, with their transcripts. */
+    readonly calls: CallsResource;
     /** RAG chat and structured extraction. */
     readonly ai: AiResource;
     /** Your application's own document store - see `DataResource`. */
@@ -115,4 +121,4 @@ export declare class ConnectClient {
     constructor(options: ConnectClientOptions);
 }
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-export declare const SDK_VERSION = "0.19.0";
+export declare const SDK_VERSION = "0.21.0";

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

@@ -29,6 +29,8 @@ export type { ExecuteIntegrationActionInput, IntegrationsResource } from "./reso
 export type { PlatformResource } from "./resources/platform.js";
 export type { SchedulingResource, FindSlotsInput, ListBookingsInput, CreateBookingInput, RescheduleBookingInput, } from "./resources/scheduling.js";
 export type { ContactsResource, LookupContactInput } from "./resources/contacts.js";
+export type { ChannelsResource, ListChannelsInput, ClaimChannelInput, } from "./resources/channels.js";
+export type { CallsResource, ListCallsInput } from "./resources/calls.js";
 /**
  * Webhook verification and a ready-made POST route. Server-only for the
  * obvious reason: the signing secret must never reach a browser bundle.

package/dist/types/server/resources/calls.d.ts

@@ -0,0 +1,45 @@
+import { type TransportOptions } from "../http.js";
+import type { CallDetail, CallsPage } from "../../types.js";
+export interface ListCallsInput {
+    /** Narrow to one channel. A channel belonging to another application simply matches nothing. */
+    channelId?: string;
+    /** From a previous page's `nextCursor`. */
+    cursor?: string;
+    /** 1-100, default 50. */
+    limit?: number;
+}
+/**
+ * Every call that arrived on a channel assigned to your application.
+ *
+ * The application is resolved from your API key and is never a parameter, so
+ * there is no request that reads another partner's calls.
+ *
+ * `channelId` is the only filter, and that is a budget decision rather than an
+ * oversight: each filter costs a Firestore composite index against a project
+ * already near its ceiling. Filter the rest client-side, or read the
+ * aggregates from `analytics`.
+ */
+export declare class CallsResource {
+    private readonly transport;
+    constructor(transport: TransportOptions);
+    /**
+     * Your calls, newest first, across all of your subscribing workspaces.
+     *
+     * **Page until `hasMore` is `false`; do not stop on an empty `items`.** A
+     * page can come back empty with more behind it.
+     */
+    list(input?: ListCallsInput): Promise<CallsPage>;
+    /**
+     * One call and every transcript turn, ordered by `sequence` - which is the
+     * sort to trust, since two turns can share a millisecond.
+     *
+     * `recordingFileId` and `transcriptFileId` are Drive file ids, readable with
+     * a `drive:read` key. Both are `null` until the carrier posts the audio,
+     * which is the normal state for a call that has only just ended - branch on
+     * `recordingStatus` rather than treating `null` as a failure.
+     *
+     * Throws `ConnectError` with `code: "not_found"` for a call that does not
+     * exist *or* belongs to another application.
+     */
+    get(callId: string): Promise<CallDetail>;
+}

package/dist/types/server/resources/channels.d.ts

@@ -0,0 +1,91 @@
+import { type TransportOptions } from "../http.js";
+import type { ChannelKind, ChannelRoutingRecord, ChannelsPage, ClaimedChannel, ConnectChannel } from "../../types.js";
+export interface ListChannelsInput {
+    /** Narrow to one workspace. Omit to list every channel assigned to your application. */
+    workspaceId?: string;
+    /** From a previous page's `nextCursor`. */
+    cursor?: string;
+    /** 1-100, default 50. */
+    limit?: number;
+}
+export interface ClaimChannelInput {
+    workspaceId: string;
+    /** Defaults to `"voice"`, the only kind Connect stocks inventory for today. */
+    kind?: ChannelKind;
+}
+/**
+ * The phone numbers Connect has assigned to your application.
+ *
+ * **Inventory is platform-owned.** A number is a regulated asset bought under
+ * Connect's carrier account and reassignable between workspaces, so your
+ * application never provisions, prices or releases one - it claims from a pool
+ * it cannot see, and reads back what it was given. That is why `claim` takes a
+ * workspace and a kind rather than a number, and why nothing here exposes a
+ * carrier, a provider reference or a monthly rate.
+ *
+ * The application is resolved from your API key and is never a parameter, so
+ * no request shape here can reach another partner's channels. A channel
+ * belonging to someone else answers `404`, not `403` - confirming it exists
+ * would make these reads an oracle for enumerating their channel ids.
+ */
+export declare class ChannelsResource {
+    private readonly transport;
+    constructor(transport: TransportOptions);
+    /**
+     * Every channel assigned to your application, across all of your subscribing
+     * workspaces.
+     *
+     * Page until `hasMore` is `false`.
+     */
+    list(input?: ListChannelsInput): Promise<ChannelsPage>;
+    /**
+     * The channel behind an id you already hold - a webhook's `channelId`, or a
+     * call record's.
+     *
+     * Throws `ConnectError` with `code: "not_found"` for an id that does not
+     * exist *or* belongs to another application.
+     */
+    get(channelId: string): Promise<ConnectChannel>;
+    /**
+     * Takes a number out of Connect's inventory and binds it to one of your
+     * subscribing workspaces.
+     *
+     * **You do not pick the number.** A workspace may hold exactly one, across
+     * every application it uses, and it is then fixed for the life of the
+     * engagement - there is no re-claim and no swap. Only a Connect operator can
+     * unassign one.
+     *
+     * Two different `409`s, and they need different handling: the workspace
+     * already holds a channel of this kind (fix the call), or the pool is empty
+     * right now (retry - Connect is notified, and this is not permanent).
+     *
+     * The claimed channel comes back without routing, because it has none yet.
+     * Call `setRouting` next, or the number refuses every call that reaches it.
+     */
+    claim(input: ClaimChannelInput): Promise<ClaimedChannel>;
+    /**
+     * Points a channel at wherever inbound conversations should go.
+     *
+     * `destination` is yours: Connect stores it verbatim and never reads into
+     * it. It **replaces** the stored record rather than merging, so send the
+     * whole destination each time; it must serialize to 16 KB or fewer.
+     *
+     * Throws `code: "conflict"` when the channel is suspended or released - use
+     * `clearRouting` to stop a suspended number answering, which is deliberately
+     * still allowed.
+     */
+    setRouting(channelId: string, destination: Record<string, unknown>): Promise<ChannelRoutingRecord>;
+    /**
+     * Takes a number out of service without giving it up - the channel stays
+     * assigned to you and stays billable, and inbound calls are refused until
+     * you write routing again.
+     *
+     * This is the only way to say "stop answering": overwriting `destination`
+     * can only ever point the number somewhere *else*, and unassigning it is a
+     * Console action that returns the number to Connect's inventory.
+     *
+     * Idempotent - clearing already-clear routing answers `200` with
+     * `routing: null`, so a retry after a lost response is safe.
+     */
+    clearRouting(channelId: string): Promise<ChannelRoutingRecord>;
+}

package/dist/types/server/resources/identity.d.ts

@@ -27,6 +27,24 @@ export interface ExchangeCodeInput {
 }
 /** A URL-safe random string, suitable for `state` or a PKCE verifier. */
 export declare function createState(byteLength?: number): string;
+/** One Tap's PKCE pair - `challenge` is `BASE64URL(SHA256(verifier))`, RFC 7636 S256. */
+export interface PkcePair {
+    verifier: string;
+    challenge: string;
+}
+/**
+ * Mints a PKCE pair for the One Tap flow.
+ *
+ * The redirect flow can take PKCE or leave it, because the code is delivered
+ * to the application's server on a redirect the browser only forwards. One Tap
+ * hands the code *to the page*, so the verifier is the thing that makes a
+ * stolen code worthless - it stays in an `HttpOnly` cookie on the application's
+ * own origin and is never sent to the browser.
+ *
+ * `crypto.subtle` rather than a Node hash, so this stays isomorphic and the
+ * `./next` entry keeps loading on the edge runtime as well as Node.
+ */
+export declare function createPkcePair(): Promise<PkcePair>;
 /**
  * "Login with Connect" - the OAuth2 handshake, and the session that outlives
  * it.
@@ -42,6 +60,23 @@ export declare class IdentityResource {
     constructor(transport: TransportOptions, clientId: string | null, appBaseUrl: string);
     /** Step 1 - the URL to send the user's browser to. */
     authorizeUrl(input: AuthorizeUrlInput): string;
+    /**
+     * The two Connect endpoints One Tap talks to **from the browser**, or `null`
+     * when this client has no `clientId` configured and the flow cannot run.
+     *
+     * Handed out by the bridge rather than built in the page, so One Tap needs no
+     * client-side configuration at all - a `./next` application sets
+     * `CONNECT_CLIENT_ID` server-side and nothing else. Both URLs carry only the
+     * public `client_id`; neither is a credential.
+     *
+     * Returning `null` rather than throwing (as `authorizeUrl` does) because this
+     * is read on the `/session` route, which must keep answering for an
+     * application that has no OAuth client configured at all.
+     */
+    oneTapEndpoints(): {
+        hintUrl: string;
+        authorizeUrl: string;
+    } | null;
     /** Step 2 - trade the one-time `code` for a session. Server-side only. */
     exchangeCode(input: ExchangeCodeInput): Promise<TokenResponse>;
     /**

package/dist/types/types.d.ts

@@ -549,13 +549,26 @@ export interface WorkspaceApp {
     iconUrl: string | null;
     /** A `lucide-react` icon name from Connect's curated set. */
     icon: string;
+    /** Catalog classification, if you want to group or filter the grid by it. */
+    category: WorkspaceAppCategory;
     /** Where a tile navigates. `null` when the application registered no site. */
     launchUrl: string | null;
+    /**
+     * Whether this workspace holds a launchable subscription.
+     *
+     * `/apps` answers with the platform's whole active catalog, not only what
+     * the workspace bought, so this is the split a launcher renders as two
+     * groups: the apps you open, and the apps you could. `false` means the tile
+     * belongs in the second - send it to Connect, not to `launchUrl`.
+     */
+    subscribed: boolean;
     /** True for the application whose API key made the call - render it as the active tile. */
     isCurrent: boolean;
-    /** Launchable but not healthy (paused, or cancelling at period end) - badge it, do not hide it. */
+    /** Launchable but not healthy (paused, or cancelling at period end) - badge it, do not hide it. Always `false` when `subscribed` is `false`. */
     needsAttention: boolean;
 }
+/** Connect's closed set of catalog categories - `WorkspaceApp.category`. */
+export type WorkspaceAppCategory = "communication" | "storage" | "analytics" | "security" | "billing" | "productivity" | "sales" | "operations" | "infrastructure" | "other";
 /**
  * The platform's DPDP grievance channel - `companyProfile.grievance`.
  *
@@ -1269,3 +1282,175 @@ export interface ConnectContact {
     createdAt: string;
     updatedAt: string;
 }
+/**
+ * What kind of conversation a channel carries. `voice` is the only kind
+ * Connect stocks inventory for today - `whatsapp` and `meeting` are modelled
+ * end to end and have no runtime yet, so `claim` refuses them.
+ */
+export type ChannelKind = "voice" | "meeting" | "whatsapp";
+/**
+ * `suspended` and `released` both stop the channel answering. The difference
+ * is whose act it was: a Connect operator suspended it, or the number went
+ * back to inventory.
+ */
+export type ChannelStatus = "active" | "suspended" | "released";
+/**
+ * Where inbound conversations on a channel go.
+ *
+ * `destination` is **yours**: an arbitrary JSON object Connect stores verbatim
+ * and never reads into. Which agent answers, business hours, overflow - all of
+ * it is your application's model, not Connect's.
+ */
+export interface ChannelRouting {
+    destination: Record<string, unknown>;
+    updatedAt: string;
+}
+/**
+ * A number assigned to your application, as your application sees it.
+ *
+ * Two things are deliberately withheld and will not appear later:
+ * `createdBy` names a Connect operator, and the carrier-side record (which
+ * carrier, which provider resource, what Connect pays per month) is Connect's
+ * cost and Connect's credential surface. An application reads what was
+ * assigned to it; it never provisions, prices or releases a number.
+ */
+export interface ConnectChannel {
+    id: string;
+    kind: ChannelKind;
+    /** E.164 for a voice channel - the number a caller dials. */
+    address: string;
+    label: string | null;
+    workspaceId: string;
+    status: ChannelStatus;
+    /** `null` when nothing has been routed yet, and after a `clearRouting()`. */
+    routing: ChannelRouting | null;
+}
+/**
+ * What a claim answers with - narrower than `ConnectChannel`, because a
+ * just-claimed number has no label and no routing yet. Read it back with
+ * `channels.get(id)` once you have written routing.
+ */
+export interface ClaimedChannel {
+    id: string;
+    kind: ChannelKind;
+    address: string;
+    workspaceId: string;
+    status: ChannelStatus;
+}
+/**
+ * What both routing writes echo back - the stored record, not the whole
+ * channel. `routing` is `null` after `clearRouting()`, which is the same shape
+ * a channel that was never routed has: to the answer path "cleared" and "never
+ * set" are the same fact.
+ */
+export interface ChannelRoutingRecord {
+    id: string;
+    routing: ChannelRouting | null;
+}
+/** One page of channels. Page until `hasMore` is `false`. */
+export interface ChannelsPage {
+    items: ConnectChannel[];
+    nextCursor: string | null;
+    hasMore: boolean;
+}
+/** Which way the call went. */
+export type CallDirection = "inbound" | "outbound";
+/**
+ * `rejected` means Connect never connected it - see `rejectReason`.
+ * `answered` is a call still in progress; `completed` is one that ran and
+ * ended.
+ */
+export type CallStatus = "answered" | "rejected" | "completed";
+/**
+ * Why a call was refused. Widened at the point of use with `(string & {})`,
+ * the same way `ReadinessBlocker.code` is: Connect adds reasons as it learns
+ * to tell failures apart, and a new one should reach you as a value to handle
+ * rather than as a type error on a published package you cannot patch. Handle
+ * the ones you branch on and treat the rest as "refused".
+ */
+export type CallRejectReason = "unknown_number" | "channel_suspended" | "channel_released" | "channel_unassigned" | "no_routing" | "workspace_blocked" | "answer_unavailable" | "runtime_unconfigured";
+/** How a call that actually ran came to an end. Widened at its use site for the same reason as `CallRejectReason`. */
+export type CallDisconnectReason = "caller_hangup" | "agent_hangup" | "max_duration" | "transferred" | "error" | "abandoned";
+/**
+ * Where the recording has got to. `pending` is normal for a call that has just
+ * ended - the carrier posts the audio afterwards - and `failed` is kept
+ * distinct from `none` so "we never recorded this" is never read as "we
+ * recorded it and lost it".
+ */
+export type CallRecordingStatus = "none" | "pending" | "stored" | "failed";
+/** What the model leg of a call cost. */
+export interface CallTokenUsage {
+    promptTokens: number;
+    responseTokens: number;
+    totalTokens: number;
+}
+/** One tool the agent called mid-conversation. Arguments and results are JSON strings, not parsed objects. */
+export interface CallToolInvocation {
+    name: string;
+    argumentsJson: string;
+    resultJson: string | null;
+    durationMs: number | null;
+    /** `null` for calls closed out before the runtime reported it - which is not zero. */
+    startedAt: string | null;
+    error: string | null;
+}
+/**
+ * One call that arrived on a channel assigned to your application.
+ *
+ * `durationSeconds` and `billDurationSeconds` are the two durations Connect
+ * stands behind - the carrier's own measure of the audio is deliberately not
+ * published, since a third near-identical number only invites a billing
+ * argument settled off the wrong one.
+ */
+export interface ConnectCall {
+    id: string;
+    channelId: string;
+    workspaceId: string;
+    direction: CallDirection;
+    fromNumber: string;
+    toNumber: string;
+    status: CallStatus;
+    rejectReason: CallRejectReason | (string & {}) | null;
+    disconnectReason: CallDisconnectReason | (string & {}) | null;
+    startedAt: string;
+    answeredAt: string | null;
+    endedAt: string | null;
+    durationSeconds: number | null;
+    billDurationSeconds: number | null;
+    recordingStatus: CallRecordingStatus;
+    /** A Drive file id - read it with a `drive:read` key. `null` until the carrier posts the audio. */
+    recordingFileId: string | null;
+    transcriptFileId: string | null;
+    turnCount: number | null;
+    tokenUsage: CallTokenUsage | null;
+    toolInvocations: CallToolInvocation[];
+    /** Your agent's own post-call structured output, keyed by its extraction schema. Connect stores it without interpreting it. */
+    extraction: Record<string, unknown> | null;
+    agentId: string | null;
+    agentVersion: number | null;
+}
+/** Who spoke. */
+export type CallTurnRole = "user" | "agent";
+/**
+ * One transcript turn. Order by `sequence`, never by `startedAt` - two turns
+ * can share a millisecond.
+ */
+export interface CallTranscriptTurn {
+    sequence: number;
+    role: CallTurnRole;
+    text: string;
+    startedAt: string | null;
+    /** True only ever for an `agent` turn - the caller talked over it. */
+    interrupted: boolean;
+}
+/** A call and its transcript. Long calls are capped at 2,000 turns. */
+export interface CallDetail {
+    call: ConnectCall;
+    turns: CallTranscriptTurn[];
+}
+/** One page of calls, newest first. Page until `hasMore` is `false` - do not stop on an empty `items`. */
+export interface CallsPage {
+    items: ConnectCall[];
+    nextCursor: string | null;
+    hasMore: boolean;
+}

package/package.json

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