@cosmoops/connect-sdk 0.20.0 → 0.23.0

package/dist/types/types.d.ts

@@ -597,13 +597,30 @@ export interface GrievanceChannel {
  */
 export interface CompanyProfile {
     legalName: string;
-    /** Trading name, for prose the full registered name reads oddly in. */
+    /**
+     * Trading name, for prose the full registered name reads oddly in.
+     *
+     * Editable by the platform operator since SDK 0.23. It was a hardcoded
+     * constant on Connect's side before that - the one company fact no
+     * operator could correct without a deploy.
+     */
     brandName: string;
     registeredAddress: string;
     contactEmail: string;
     website: string | null;
     /** GSTIN, `null` if the operating entity is not GST-registered. */
     gstNumber: string | null;
+    /**
+     * The seat a governing-law clause names - `"Chennai, Tamil Nadu"`.
+     *
+     * **Not the registered address**, and the distinction is the reason it is
+     * its own field: an entity registered in one state routinely names another
+     * as the venue for disputes, and the two copies of this that applications
+     * used to keep disagreed about which. `null` when the operator has not
+     * published one, in which case a terms page should omit the venue rather
+     * than reach for `registeredAddress` instead.
+     */
+    legalJurisdiction: string | null;
     grievance: GrievanceChannel;
 }
 export interface CompanyProfileResponse {
@@ -1153,6 +1170,71 @@ export interface ConnectWorkspaceMember {
     granted: string[];
     role: string | null;
 }
+/**
+ * How many member seats the workspace has, and whether there is another.
+ *
+ * The number is the **workspace's**, not your plan's: a baseline plus
+ * `allowances.members` from every subscription it holds, folded across
+ * applications - so a seat bought through another product is a seat you may
+ * fill. `included: null` means unlimited. `used` counts active members *and*
+ * pending invitations, because an invitation is a seat already spoken for.
+ *
+ * Advisory. The authoritative check runs inside `invite`, which is where two
+ * people claiming the last seat at once is settled.
+ */
+export interface ConnectMemberCapacity {
+    included: number | null;
+    used: number;
+    canAdd: boolean;
+    /**
+     * `no_allowance` - nothing the workspace subscribes to grants member seats,
+     * and the answer is a plan. `exhausted` - every seat is taken, and the
+     * answer is an upgrade or a removal. They read alike and need different
+     * next steps, so word them differently.
+     */
+    reason: "no_allowance" | "exhausted" | "hard_ceiling" | null;
+}
+/**
+ * What the **signed-in caller** may do with the roster, from their Connect
+ * permissions - not your application's.
+ *
+ * Render your Invite and Change-role controls from this. Without it the only
+ * way to find out is to try, which is a button that exists to fail.
+ */
+export interface ConnectMemberViewer {
+    canInvite: boolean;
+    canManageAccess: boolean;
+}
+/** An invitation that has been sent and not yet accepted - and is holding a seat. */
+export interface ConnectPendingInvitation {
+    invitationId: string;
+    inviteeEmail: string;
+    /** The role on *your* application it carries, or `null`. */
+    roleKey: string | null;
+    /** ISO 8601. Seven days from when it was sent. */
+    expiresAt: string;
+}
+export interface ConnectMemberAccess {
+    capacity: ConnectMemberCapacity;
+    viewer: ConnectMemberViewer;
+    invitations: ConnectPendingInvitation[];
+}
+export interface ConnectInvitation {
+    invitationId: string;
+    inviteeEmail: string;
+    /** ISO 8601. */
+    expiresAt: string;
+    /** Always present, so you can offer copy/share when the email did not go out. */
+    inviteUrl: string;
+    emailSent: boolean;
+}
+export interface ConnectMemberAccessResult {
+    userId: string;
+    /** The role on your application after the change - `null` when access was revoked. */
+    roleKey: string | null;
+    /** Your application's permissions this member now holds, re-resolved. */
+    granted: string[];
+}
 /**
  * One bookable thing a workspace offers - "15-minute intro call", "site
  * survey".
@@ -1282,3 +1364,264 @@ export interface ConnectContact {
     createdAt: string;
     updatedAt: string;
 }
+/** Coarse on purpose - a headcount read off a homepage is a claim, not a measurement. */
+export type CompanySizeBand = "1-10" | "11-50" | "51-200" | "201-500" | "500+";
+/**
+ * Where a value came from.
+ *
+ * - `domain` - the input itself. `url` is `null`, because there is no page.
+ * - `website` - a page on the company's own site, at `url`.
+ * - `registry` - a statutory register. Reserved; nothing returns it yet.
+ */
+export type EnrichmentSource = "domain" | "registry" | "website";
+export interface EnrichmentCitation {
+    source: EnrichmentSource;
+    /** The exact page read. `null` only for `domain`. */
+    url: string | null;
+    /** ISO-8601. */
+    retrievedAt: string;
+}
+/**
+ * Every field nullable, including the ones your own record calls required.
+ *
+ * An enrichment is partial by nature: a site with no address printed on it
+ * yields no address. A shape that demanded a city would only be forcing one to
+ * be invented.
+ */
+export interface EnrichedAddress {
+    line1: string | null;
+    line2: string | null;
+    city: string | null;
+    /** The state or region's *name* as written, not a code. */
+    state: string | null;
+    postalCode: string | null;
+    /** ISO 3166-1 alpha-2, uppercase. */
+    country: string | null;
+}
+/**
+ * What Connect read about a company, and where each part came from.
+ *
+ * Every value is a claim from a page named in `citations`. Nothing here is
+ * recalled by a model: a field the pages did not state is `null`, which is why
+ * `null` is common and should be rendered as "not found" rather than as an
+ * empty input somebody has to notice.
+ */
+export interface EnrichedCompany {
+    /** Normalised - lowercase, no scheme, no `www.`. */
+    domain: string;
+    name: string | null;
+    /**
+     * The registered entity name.
+     *
+     * Always `null` today. It is reserved for a statutory register, and
+     * deliberately never filled from a website - a footer says "Acme" where the
+     * register says "Acme Industries Private Limited", and this is the one field
+     * here that would end up on a contract.
+     */
+    legalName: string | null;
+    description: string | null;
+    industry: string | null;
+    sizeBand: CompanySizeBand | null;
+    phone: string | null;
+    email: string | null;
+    website: string | null;
+    address: EnrichedAddress | null;
+    /**
+     * Derived from how many fields the pages actually supported - not the
+     * model's opinion of itself, which reflects the confidence of the prose it
+     * read. Treat `low` as "offer this", `high` as "safe to pre-fill".
+     */
+    confidence: "high" | "medium" | "low";
+    citations: EnrichmentCitation[];
+    /** ISO-8601. Age the profile against this. */
+    retrievedAt: string;
+}
+/**
+ * Why there is nothing to report. A normal outcome, not an error - most
+ * records legitimately have nothing to enrich.
+ *
+ * `consumer_domain` and `blocked_domain` will never succeed on retry.
+ * `unreachable` and `no_signal` may, later.
+ */
+export type EnrichmentSkipReason = "no_domain" | "consumer_domain" | "blocked_domain" | "unreachable" | "no_signal";
+export type CompanyEnrichmentResult = {
+    status: "enriched";
+    profile: EnrichedCompany;
+    /** Whether Connect served this from its platform-wide cache. The profile is the same either way. */
+    cached: boolean;
+} | {
+    status: "skipped";
+    reason: EnrichmentSkipReason;
+};
+/**
+ * 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.20.0",
+  "version": "0.23.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",