Server

Generated from @cosmoops/connect-sdk/server's TypeScript source and its own doc comments - see Reference for the other entry points. Regenerated on every deploy; don't hand-edit.

Classes

Class: ConnectClient

The CosmoOps Connect application-partner API.

Covers /api/v1/application/* and nothing else - the surface an application platform integrates against. Connect's internal API is not part of this package and never will be.

const connect = new ConnectClient({
  apiKey: process.env.CONNECT_API_KEY!,
  clientId: process.env.CONNECT_CLIENT_ID,
});

const session = await connect.identity.exchangeCode({ code, redirectUri });
const { ready } = await connect.entitlements.getReadiness(session.user.workspaceId);

Every failure throws a ConnectError carrying a stable code. Nothing here holds state between calls, so one client can be built once and shared.

Constructors

Constructor

new ConnectClient(options: ConnectClientOptions): ConnectClient;

Parameters

Returns

ConnectClient

Properties

identity

readonly identity: IdentityResource;

"Login with Connect" - the OAuth2 handshake and the session after it.

access

readonly access: AccessResource;

What a signed-in member may do on your application.

apps

readonly apps: AppsResource;

The applications a workspace can open - for a launcher grid.

entitlements

readonly entitlements: EntitlementsResource;

Whether a workspace may use your application, and on what plan.

billing

readonly billing: BillingResource;

Your plan catalog, and metering usage against add-on balances.

drive

readonly drive: DriveResource;

Files in a workspace's Drive.

scheduling

readonly scheduling: SchedulingResource;

A subscribing workspace's own calendar - what is bookable, free, and booked.

contacts

readonly contacts: ContactsResource;

Who a workspace already knows how to reach, by phone or by id.

channels

readonly channels: ChannelsResource;

The phone numbers Connect has assigned to your application, and where each one routes.

calls

readonly calls: CallsResource;

The calls that arrived on those channels, with their transcripts.

telephony

readonly telephony: TelephonyResource;

Calls on the numbers your application handles, when it answers its own calls - see TelephonyResource.

doNotCall

readonly doNotCall: DoNotCallResource;

The workspace's do-not-call list, which Connect enforces on every outbound call - see DoNotCallResource.

credit

readonly credit: CreditResource;

Prepaid credit a workspace buys from Connect and your application spends per use - see CreditResource.

ai

readonly ai: AiResource;

RAG chat and structured extraction.

enrichment

readonly enrichment: EnrichmentResource;

data

readonly data: DataResource;

Your application's own document store - see DataResource.

kv

readonly kv: KvResource;

Your application's key/value store - see KvResource.

otp

readonly otp: OtpResource;

WhatsApp/SMS phone verification.

logs

readonly logs: LogsResource;

Feature events into the Console's audit log, filterable to your application.

analytics

readonly analytics: AnalyticsResource;

Emit product events and read back this application's aggregated numbers.

sessions

readonly sessions: SessionsResource;

This Connect account's own login sessions - account-wide, not scoped to this application. Requires the sessions:manage scope.

integrations

readonly integrations: IntegrationsResource;

Composio-hosted third-party connections (Google Calendar, Slack, ...) a workspace has connected.

workspaces

readonly workspaces: WorkspacesResource;

Which workspaces the signed-in user belongs to, switching between them, and the team - see WorkspacesResource.

visitor

readonly visitor: VisitorResource;

The public chat bubble on your own site - see VisitorResource. The one resource here whose caller is not one of your users.

platform

readonly platform: PlatformResource;

The platform's own legal identity and DPDP grievance channel - see PlatformResource.

push

readonly push: PushResource;

Web Push. Connect holds the VAPID keys, the devices and the member's own preferences; you supply a title, a body and a URL. See PushResource.

tasks

readonly tasks: TasksResource;

Background tasks on this application's declared Cloud Tasks queues - see TasksResource.

whatsapp

readonly whatsapp: WhatsAppResource;

Your application's own approved WhatsApp templates, to a workspace's customers.

email

readonly email: EmailResource;

Your application's own email, sent from Connect's address for a subscribing workspace - see EmailResource.

Class: ConnectTaskVerificationError

Receiving a Connect task - verify Google's OIDC token, then run. See TasksResource for the sending half.

Extends

• Error

Constructors

Constructor

new ConnectTaskVerificationError(message: string): ConnectTaskVerificationError;

Parameters

Returns

ConnectTaskVerificationError

Overrides

Error.constructor

Properties

stackTraceLimit

static stackTraceLimit: number;

The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).

The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

Inherited from

Error.stackTraceLimit

cause?

optional cause?: unknown;

The cause of the error.

Inherited from

Error.cause

name

name: string;

Inherited from

Error.name

message

message: string;

Inherited from

Error.message

stack?

optional stack?: string;

Inherited from

Error.stack

Methods

captureStackTrace()

Call Signature

static captureStackTrace(targetObject: object, constructorOpt?: Function): void;

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

Parameters

Returns

void

Inherited from

Error.captureStackTrace

Call Signature

static captureStackTrace(targetObject: object, constructorOpt?: Function): void;

Create .stack property on a target object

Parameters

Returns

void

Inherited from

Error.captureStackTrace

prepareStackTrace()

static prepareStackTrace(err: Error, stackTraces: CallSite[]): any;

Parameters

Returns

any

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from

Error.prepareStackTrace

isError()

static isError(value: unknown): value is Error;

Check if a value is an instance of Error

Parameters

Returns

value is Error

True if the value is an instance of Error, false otherwise

Inherited from

Error.isError

Interfaces

Interface: AccessResource

What a signed-in member may do on your application, and the role catalog behind it.

Methods

getUserRoles()

getUserRoles(userId: string, input: {
  workspaceId: string;
}): Promise<UserRolesResponse>;

Re-check one member's role and granted permissions, live. The same block identity.getUser() returns - use this when you need only the role axis and already know who the user is.

Parameters

Returns

Promise<UserRolesResponse>

listRoles()

listRoles(): Promise<RolesResponse>;

Your application's own permission catalog and role definitions - the definitions getUserRoles resolves against.

Returns

Promise<RolesResponse>

Interface: AiResource

RAG chat and structured extraction against a workspace's data.

asUser on chat behaves as it does on the store resources: pass a signed-in user's sessionToken and Connect resolves the workspace from it, ignoring workspaceId. Without it you are the application, naming the workspace yourself.

Methods

chat()

chat(input: {
  workspaceId: string;
  messages: ChatMessage[];
  asUser?: string;
  conversationId?: string;
  screens?: unknown;
  screenContext?: unknown;
}, options?: {
  signal?: AbortSignal;
}): Promise<Response>;

RAG-grounded chat. Returns the raw streaming Response rather than a parsed body - this endpoint answers with server-sent events, and buffering it here would throw away the only reason to stream. Pipe response.body onward, or hand it to the AI SDK's own reader.

Parameters

Returns

Promise<Response>

listConversations()

listConversations(input: {
  asUser: string;
  limit?: number;
  cursor?: string;
}): Promise<AiConversationList>;

The signed-in user's past conversations in your application, most recent first.

asUser is required rather than optional here, unlike on chat: the rows are scoped to a person, and there is no application-wide view of them to fall back to. Connect reads the user and the workspace from the token.

Cursor-paginated with no total - the list is ordered by last use, which moves while it is being read.

Parameters

Returns

Promise<AiConversationList>

getConversation()

getConversation(input: {
  conversationId: string;
  asUser: string;
}): Promise<AiConversationDetail>;

One stored transcript, oldest turn first.

turns[].parts comes back exactly as the model produced it - prose, reasoning and tool calls in order - so it can be handed straight back to a chat UI. Not this user's, or not your application's, is a 404 either way.

Parameters

Returns

Promise<AiConversationDetail>

deleteConversation()

deleteConversation(input: {
  conversationId: string;
  asUser: string;
}): Promise<{
  deleted: true;
}>;

Deletes a conversation and every turn beneath it.

Idempotent - one already gone answers { deleted: true }, so a retry after a dropped response does not read as a failure.

Parameters

Returns

Promise<{ deleted: true; }>

generate()

generate(input: AiGenerateInput): Promise<AiGenerateResult>;

One generation from your own prompt, against a model Connect allows - messages, optional tool declarations, an optional JSON schema for the answer. Needs ai:generate, and the platform must have it enabled.

Not chat. That is Connect's assistant, grounded in a workspace's Context Index; this is a bare model you prompt yourself, billed to the workspace you name against its monthly AI budget.

Tools come back to you. Connect never runs one: a requested call arrives in toolCalls, you run it, and the next generate carries the model's turn and your result. One model step per call.

Parameters

Returns

Promise<AiGenerateResult>

analyzeCall()

analyzeCall(input: CallAnalysisInput): Promise<CallAnalysis>;

Transcript, summary, intent, sentiment and action items for a call recording your application stored in the workspace's Drive - e.g. the fileId connect.telephony.archiveRecording returned. Counted against the workspace's monthly AI budget like generate; Connect stores nothing.

not_found for a file your application did not upload there; unavailable (503) when the platform has no call analyzer.

Parameters

Returns

Promise<CallAnalysis>

extract()

extract<T>(input: {
  schemaId: string;
  fileUrl: string;
}): Promise<T>;

Extract structured JSON from a file or image URL, against a platform extraction schema referenced by id.

Type Parameters

Parameters

Returns

Promise<T>

draftAssessment()

draftAssessment(input: {
  assessmentKey: string;
  seed: string;
}): Promise<AssessmentDraft>;

Draft every section of a platform-defined assessment from one sentence.

The intended flow is draft first, then let the person correct it section by section: a blank questionnaire is the reason most people abandon one, and editing a strawman is a far smaller ask than authoring from nothing.

Unattributed - assessments run against platform-wide definitions and the first consumers run before anyone has signed in, so there is no asUser and no workspace here.

Parameters

Returns

Promise<AssessmentDraft>

reviewAssessment()

reviewAssessment(input: {
  assessmentKey: string;
  answers: AssessmentAnswers;
}): Promise<AssessmentReview>;

Critique a completed assessment - the tensions between sections, the riskiest assumption, and a coarse score.

Unknown section keys in answers are ignored rather than rejected, so a definition changing under a half-finished assessment costs the reader nothing.

Parameters

Returns

Promise<AssessmentReview>

readiness()

readiness(input: {
  domain: string;
  asUser?: string;
  refresh?: boolean;
}, options?: {
  signal?: AbortSignal;
}): Promise<ReadinessAssessmentResult>;

How ready the site at a domain is for AI agents.

Probes for an MCP server, an OpenAPI description, llms.txt, structured data and a markdown twin; evaluates the site's robots.txt against the assistants that actually fetch pages; checks whether its content survives without JavaScript and whether a bot wall refuses agents outright. Then grades what it found and says what to fix first.

Needs an API key scoped to ai:readiness, which is separate from every other AI scope because it is the widest outbound surface on the API - it POSTs to candidate MCP endpoints and fetches the home page under two user agents.

const result = await connect.ai.readiness({ domain: "acme.com" });
if (result.status === "assessed") {
  console.log(result.report.grade, result.report.topFix?.fix);
}

Four things to know before wiring it in:

• Set your client timeout to at least 90 seconds. A cold assessment runs the whole probe before answering and can take up to a minute; many HTTP clients default to 30s and abandon a request that was about to succeed. Cached reads return in milliseconds and are the normal case - reports are held for a week.
• A week, not ninety days, because a report is a to-do list somebody is working through. Pass refresh after shipping a fix to see it land.
• Handle status: "error" checks as unknown, not as failures. They mean Connect could not measure that check, and they are excluded from the score rather than counted against it.
• skipped says whose problem it is. unreachable means the site did not answer; provider_unavailable means Connect's own assessment service did. Only the second is worth retrying silently, and neither should be shown as a failing grade.

Parameters

Returns

Promise<ReadinessAssessmentResult>

Interface: AnalyticsResource

Your application's own analytics: emit product events, and read back the daily numbers Connect aggregates from them.

There is no way to name an application in either call. The scope is always the one your API key belongs to - that is the endpoint's security model, not an omission.

Methods

series()

series(query: AnalyticsQuery): Promise<AnalyticsResponse>;

Daily series for the requested metrics, up to 90 days.

Throws on failure, unlike emit below. A read whose result you are about to render has to be able to say "I could not load"; silently returning an empty series would draw a chart of zeroes.

Parameters

Returns

Promise<AnalyticsResponse>

emit()

emit(events: EmitEventInput[]): Promise<EmitEventsResponse>;

Never throws - the same judgement LogsResource.write makes, for the same reason: telemetry that takes down the code path it was observing is worse than a lost event. A failure is reported through delivered.

Up to 50 events per call. Pass sessionToken on an event to attribute it to the signed-in user; without one it still lands, just unattributed.

Parameters

Returns

Promise<EmitEventsResponse>

Interface: AppsResource

The applications a workspace can open - the data behind a launcher grid.

Methods

list()

list(workspaceId: string): Promise<WorkspaceApp[]>;

Launchable apps only, so a grid tile is never a dead end. The calling application is included and flagged isCurrent rather than filtered out.

Parameters

Returns

Promise<WorkspaceApp[]>

Interface: AuthorizeUrlInput

Properties

Interface: BillingResource

The plan catalog you sell, and metering usage back against a subscriber's add-on balance.

Methods

listPlans()

listPlans(): Promise<PlansResponse>;

Your application's active plans - render live pricing instead of hardcoding it.

features is normalised on the way out: Connect used to send bare keys and now sends { key, name, description }, and this SDK is versioned independently of the instance it talks to. Without the coercion a partner pointed at a Connect that has not upgraded yet renders a feature list of blanks - which is exactly what happened. See normalizePlanFeatures.

limits is defaulted for the same reason, one version later: an instance that predates limits sends no such field, and a pricing grid mapping over plan.limits would throw rather than simply show no limit rows.

Returns

Promise<PlansResponse>

getAddonUsage()

getAddonUsage(workspaceId: string): Promise<AddonUsageResponse>;

What is left of every consumable add-on on a workspace's subscription - the read half of consumeAddon.

Needs a key scoped to addons:read, which is separate from addons:consume on purpose: a key that only renders a usage meter should not also be able to spend the balance down.

Returns an empty addons array rather than throwing when there is nothing to meter, so a caller can render it unconditionally.

Parameters

Returns

Promise<AddonUsageResponse>

consumeAddon()

consumeAddon(input: ConsumeAddonInput, options?: {
  idempotencyKey?: string;
}): Promise<ConsumeAddonResponse>;

Debit a consumable add-on's per-cycle balance on behalf of an workspace's users. Call it at whatever cadence your usage happens.

An Idempotency-Key is always sent, generated per call when you do not supply one: a balance cannot be un-spent, so a retried consume without a key double-debits. Pass your own when the natural unit of work is something you can name (a job id, a message id) and might submit twice.

Parameters

Returns

Promise<ConsumeAddonResponse>

Interface: CallsResource

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.

Methods

list()

list(input?: ListCallsInput): Promise<CallsPage>;

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.

Parameters

Returns

Promise<CallsPage>

get()

get(callId: string): Promise<CallDetail>;

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.

Parameters

Returns

Promise<CallDetail>

getCallingAvailability()

getCallingAvailability(input: {
  asUser: string;
}): Promise<CallingAvailability>;

Whether the member can call, and if not why - what <ConnectCallButton> renders from. Throws ConnectError 403 for a member without "Make calls"; the bridge turns that into status: "no_permission".

Parameters

Returns

Promise<CallingAvailability>

getRouting()

getRouting(input: {
  asUser: string;
}): Promise<any>;

Reads the inbound call routing flow and published agents for the workspace.

Parameters

Returns

Promise<any>

setRouting()

setRouting(input: {
  routing: Record<string, unknown>;
  asUser: string;
}): Promise<any>;

Sets the inbound call routing flow (smart CRM owner routing, AI agent, single number, team, fallback).

Parameters

Returns

Promise<any>

getCallSettings()

getCallSettings(input: {
  asUser: string;
}): Promise<CallSettings>;

Whether the workspace records its member calls, and whether this member may change that. The same switch as Connect's Calling screen.

Parameters

Returns

Promise<CallSettings>

setCallRecording()

setCallRecording(input: {
  recordingEnabled: boolean;
  asUser: string;
}): Promise<CallSettings>;

Switches recording on or off for calls started from now. Throws ConnectError 403 when the member lacks channel:manage; the change is audited against them. Answers the settings as they now stand.

Parameters

Returns

Promise<CallSettings>

getCallingReadiness()

getCallingReadiness(input: 
  | {
  asUser: string;
}
  | {
  workspaceId: string;
}): Promise<CallingReadiness>;

Whether the workspace may legally make each kind of call - service or sales, dialled by a rep or by software - and the steps left on Connect's calling compliance journey. Send the member to setupUrl to finish them.

Pass asUser to ask for a signed-in member, or workspaceId to ask from your own server with nobody signed in - a dialer checking before it places a call. The answer is the same either way, except that canManage is always false without a member.

Parameters

Returns

Promise<CallingReadiness>

getBrowserCallingToken()

getBrowserCallingToken(input: {
  asUser: string;
}): Promise<BrowserCallingToken>;

A carrier token the member's browser signs in to the phone network with.

Parameters

Returns

Promise<BrowserCallingToken>

startBrowserCall()

startBrowserCall(input: {
  phone: string;
  asUser: string;
  purpose?: ConnectCallPurpose;
}): Promise<StartedBrowserCall>;

Approves one call from the member to phone (E.164) and records it.

Throws ConnectError with status 412 when the workspace has no active number, is not allowed to place calls, or the member is already on one - the message is written to be shown to them. With a purpose, also when no number may carry it and the workspace enforces purposes.

Parameters

Returns

Promise<StartedBrowserCall>

cancelBrowserCall()

cancelBrowserCall(input: {
  callId: string;
  asUser: string;
}): Promise<void>;

Closes a call the browser never managed to place - recorded as unanswered/cancelled. A no-op once the carrier has it.

Parameters

Returns

Promise<void>

Interface: ChannelsResource

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.

Methods

list()

list(input?: ListChannelsInput): Promise<ChannelsPage>;

Every channel assigned to your application, across all of your subscribing workspaces.

Page until hasMore is false.

Parameters

Returns

Promise<ChannelsPage>

get()

get(channelId: string): Promise<ConnectChannel>;

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.

Parameters

Returns

Promise<ConnectChannel>

claim()

claim(input: ClaimChannelInput): Promise<ClaimedChannel>;

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. It leaves the workspace when you release it or a Connect operator unassigns it.

Two different 409s, 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.

Parameters

Returns

Promise<ClaimedChannel>

release()

release(channelId: string, input: {
  workspaceId: string;
}): Promise<ConnectChannel>;

Gives a number back: its rental closes, routing is cleared and it returns to Connect's inventory. A number your application handled stops reaching your telephony webhook. The inverse of claim, under the same scope.

Throws code: "not_found" for another application's channel, or one held by a different workspace than the one you name.

Parameters

Returns

Promise<ConnectChannel>

setRouting()

setRouting(channelId: string, destination: Record<string, unknown>): Promise<ChannelRoutingRecord>;

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.

Parameters

Returns

Promise<ChannelRoutingRecord>

clearRouting()

clearRouting(channelId: string): 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.

Parameters

Returns

Promise<ChannelRoutingRecord>

Interface: ClaimChannelInput

Properties

Interface: ConnectAccountSessionOptions

Account mode: one CosmoOps sign-in shared by every first-party app.

Connect sets an opaque account-session id in a cookie on the parent domain; the bridge only ever reads it (and clears it on sign-out). Every read resolves it through identity.getAccountUser, so the answer is still this application's own role, permissions and subscription.

Properties

Interface: ConnectClientOptions

Properties

Interface: ConnectHandlerOptions

Properties

Interface: ConnectSessionStore

What the bridge needs from the partner's own session, and what it may change about it.

Deliberately an interface rather than a cookie this SDK sets: the partner already has a session mechanism, and a second one owned by a dependency would be a second source of truth about who is signed in.

Methods

read()

read(request: Request): string | Promise<string | null> | null;

The Connect sessionToken for this caller, or null if signed out.

Parameters

Returns

string | Promise<string | null> | null

write()?

optional write(
   request: Request, 
   response: Response, 
sessionToken: string): void | Promise<void>;

Persist a freshly exchanged session. Supplying this turns on /signin and /callback, so the handler runs the whole OAuth round trip instead of leaving you to write the callback route - see createConnectHandler. Set cookies on response.

Parameters

Returns

void | Promise<void>

clear()?

optional clear(request: Request, response: Response): void | Promise<void>;

Called on sign-out, before Connect is told. Clear your own session here - set cookies on response.

Parameters

Returns

void | Promise<void>

migrate()?

optional migrate(
   request: Request, 
   response: Response, 
   sessionToken: string, 
session: UserResponse): void | Promise<void>;

Called by GET /session once Connect has accepted the token read returned, so a store that found it somewhere legacy can re-persist it where it now belongs - cookieSessionStore uses it to move a token from the shared connect_session cookie to this application's own name. session is the resolved answer (its sessionExpiresAt bounds the new cookie). Optional, and a no-op for any store with nothing to migrate.

Parameters

Returns

void | Promise<void>

Interface: ConnectTaskHandlerOptions<TPayload>

Extends

• VerifyConnectTaskOptions

Type Parameters

Properties

Interface: ConnectWebhookHandlerOptions

Webhook verification and a ready-made POST route. Server-only for the obvious reason: the signing secret must never reach a browser bundle.

Properties

Interface: ContactsResource

Who a workspace already knows how to reach.

This is the telephony identity, not a CRM record. A contact is keyed by primaryPhone - the one fact every inbound call carries - and it is written automatically: a voice agent creates one on the first call from a new number and fills fields in as it learns them. source says which kind you are holding, and it is worth rendering: call means an agent guessed and nobody has confirmed, manual means a person typed it.

Reference it, do not copy it. If your application keeps its own customer records, store this contact's id on yours rather than duplicating the fields. Two writable copies of a person's name with no single owner drift, and Connect's is the one an agent keeps updating from calls. The id is also an exact join to anything else keyed by it - Booking.contactId, most usefully - so "which of my records is this appointment for" becomes a lookup instead of a phone match.

Writing is contributing, not editing. upsertFromInteraction is the one write, and it declares where its facts came from (call or extraction): Connect merges them the way it merges a call's own, so they fill blanks and never overwrite what a person typed.

Methods

lookupByPhone()

lookupByPhone(input: LookupContactInput): Promise<ConnectContact | null>;

"Do we already know this number?" - one point read, cheap enough for a screen pop on every inbound call.

Resolves to null for a number nobody has called from before. That is the ordinary case for a first-time caller, not an error, which is why it is a null rather than a thrown ConnectError.

Parameters

Returns

Promise<ConnectContact | null>

get()

get(contactId: string, options: {
  workspaceId: string;
  asUser?: string;
}): Promise<ConnectContact>;

The record behind an id you already hold.

Throws ConnectError with code: "not_found" for an id that does not exist or belongs to another workspace - deliberately the same answer, since telling those apart would confirm a contact exists somewhere else.

Parameters

Returns

Promise<ConnectContact>

upsertFromInteraction()

upsertFromInteraction(input: UpsertContactFromInteractionInput): Promise<ContactInteractionResult>;

Finds the workspace's contact for phone, or creates it, and folds in what a call or conversation learned. Needs contacts:write; server-side only (no asUser).

Automated facts fill blanks; they never overwrite. A name somebody typed into the contact stays, a phone or email is never marked verified, and arrays are added to. changedFields is what actually landed, so answer the caller from it - "I've saved your email" when nothing changed is a promise the record does not keep.

Count the call once. Leave countCall off for every save made while the interaction is still running and pass true on the one write that closes it.

The workspace's applications receive contact.created or contact.updated when something changed - including yours, if you subscribe to them.

Parameters

Returns

Promise<ContactInteractionResult>

Interface: CreateBookingInput

Extends

• ActingAsOption

Properties

Interface: CreditResource

Prepaid credit - a rupee balance a workspace buys from Connect for your application (topping up whenever it likes, GST invoiced by Connect), and your application spends per use: calling minutes, SMS.

Unlike a consumable add-on it never resets with the billing cycle, can be topped up mid-cycle, and can be credited back. Every amount is paise, pre-tax.

const { spendable, topUpPath } = await connect.credit.getBalance(workspaceId);
// ...after the call ends:
await connect.credit.consume({ workspaceId, amount: 360, idempotencyKey: call.id, description: "Call (4 min)" });

A consume larger than spendable throws ConnectError code insufficient_credit; send the customer to topUpPath through useConnect().openConnect(). Needs credit:read / credit:write.

Methods

getBalance()

getBalance(workspaceId: string): Promise<CreditBalance>;

Parameters

Returns

Promise<CreditBalance>

consume()

consume(input: ConsumeCreditInput): Promise<CreditMovement>;

Debits credit for one unit of work. idempotencyKey is required and is enforced by Connect's ledger, so the request is safe to retry - a replay answers duplicate: true with the original entry.

Parameters

Returns

Promise<CreditMovement>

refund()

refund(input: RefundCreditInput): Promise<CreditMovement>;

Credits back part or all of one earlier consume. Never more than it took; idempotent like consume.

Parameters

Returns

Promise<CreditMovement>

listLedger()

listLedger(workspaceId: string, options?: {
  cursor?: string;
  limit?: number;
}): Promise<CreditLedgerPage>;

Every movement, newest first. Pass the previous page's nextCursor to continue.

Parameters

Returns

Promise<CreditLedgerPage>

Interface: DataResource

Your application's own document store - a dedicated Firestore database that only Connect can reach.

You hold no Firebase credential and write no security rules. Collections are declared in the Console; an undeclared name is refused rather than created, and workspaceId is a path segment rather than a filter, so a query cannot cross tenants.

A query needs an index for its shape, and there are two ways to have one. Firestore maintains a single-field index automatically, which covers one filter, or an orderBy on that same field. Anything wider - two filters, or a filter ordered by a different field - needs a composite index declared on your application's Store tab, which Connect then builds in your database. A query with no matching index is refused up front, naming the index to declare, rather than failing later with a Firestore index error pointing at a console you cannot open.

Dates are ISO-8601 strings. The store writes what you send it, and JSON has no date type, so a Date must be sent as toISOString(). That is not a compromise: UTC ISO strings sort lexicographically in chronological order, so ordering and range filters on them behave exactly as they would on a timestamp - and Connect's own _createdAt/_updatedAt come back in the same form.

workspaceId is omitted for master data. A collection declared application-scoped in the Console belongs to no workspace - one copy, owned by you, read by every tenant. Those are written with your API key only, never on behalf of a user: a write permission is something a workspace grants, so honouring one on shared data would give one tenant's admin reach over every other tenant's reference data.

asUser is how you act on behalf of a signed-in user. Pass the opaque sessionToken you were given at sign-in and Connect resolves the user and their workspace from it - checking the collection's declared permission against what that member actually holds, and ignoring workspaceId entirely. Without it you are the application itself: your API key's scopes are the only gate, and the per-user permissions do not apply. The bridge (createConnectHandler) always passes it, which is what makes the browser path safe.

Methods

get()

get(input: {
  workspaceId?: string;
  collection: string;
  id: string;
  asUser?: string;
}): Promise<StoreDocument>;

Reads one document. Throws ConnectError with status 404 when it does not exist.

Parameters

Returns

Promise<StoreDocument>

getMany()

getMany(input: {
  workspaceId?: string;
  collection: string;
  ids: string[];
  asUser?: string;
}): Promise<StoreGetManyResult>;

Reads up to 200 documents of one collection by id, in one request - the batch form of get.

Reach for it wherever you would loop over get: the contacts on a page of deals, the plans behind a list of subscriptions. It is gated exactly like get and spends one request of your rate limit however many ids it names.

const { items } = await connect.data.getMany({
  workspaceId,
  collection: "contacts",
  ids: deals.map((deal) => deal.data.contactId as string),
});
// items[i] belongs to ids[i]; null where that contact no longer exists.

Answers positionally, null where a document does not exist - unlike get, a missing document does not throw.

Parameters

Returns

Promise<StoreGetManyResult>

query()

query(input: {
  workspaceId?: string;
  collection: string;
  filters?: StoreQueryFilter[];
  orderBy?: StoreOrderBy;
  limit?: number;
  cursor?: string | null;
  asUser?: string;
}): Promise<StoreQueryPage>;

Lists a collection, one page at a time.

filters are ANDed. More than one, or one combined with an orderBy on a different field, needs a composite index declared on the Store tab - see the class note above.

limit defaults to 50 and caps at 200. Page by passing the previous page's nextCursor; a null nextCursor is the end of the collection.

Parameters

Returns

Promise<StoreQueryPage>

aggregate()

aggregate(input: {
  workspaceId?: string;
  collection: string;
  aggregations: StoreAggregation[];
  filters?: StoreQueryFilter[];
  asUser?: string;
}): Promise<StoreAggregatePage>;

Counts, sums and averages a filtered collection - in Firestore, not by reading the rows back and adding them up.

That distinction is the whole point. An aggregation is billed by the index entries it scans rather than by the documents it would have returned, so a dashboard tile over ten thousand rows costs a handful of reads and stays flat as the collection grows. Paging the rows into your own process to sum them is an unbounded read, and it is what every integration does when there is no aggregate call to reach for.

const { values } = await connect.data.aggregate({
  workspaceId,
  collection: "deals",
  filters: [{ field: "outcome", op: "==", value: "won" }],
  aggregations: [
    { op: "count", alias: "count" },
    { op: "sum", field: "value", alias: "total" },
  ],
});

A sum or avg over nothing answers null rather than 0, because "nothing matched" and "the total is zero" are different facts.

The index it needs is the one its filters need plus the aggregated field - Firestore reads a sum out of the index rather than out of the documents.

There is no orderBy, limit or cursor: the aggregate of an ordered page is the aggregate of the whole filtered set.

Parameters

Returns

Promise<StoreAggregatePage>

scan()

scan(input: {
  collection: string;
  filters?: StoreQueryFilter[];
  orderBy?: StoreOrderBy;
  limit?: number;
  cursor?: string | null;
}): Promise<StoreScanPage>;

Reads one collection across every workspace at once - your own back-office view of your whole customer base. Each row carries the workspaceId it came from.

Needs the data:read:all scope, and the collection must be marked cross-workspace in the Console. There is deliberately no asUser: a scan is never available on behalf of a signed-in user, because a workspace admin is an admin of their own workspace and not of your other customers.

Filtering and ordering follow the same index rules as query, and additionally need collection-group scope. Connect creates those from the declaration - the single-field ones when you mark a field queryable, and a group-scoped copy of every composite index the collection declares. A scan issued in the minutes after that declaration may fail while the index builds.

Parameters

Returns

Promise<StoreScanPage>

create()

create(input: {
  workspaceId?: string;
  collection: string;
  data: Record<string, unknown>;
  id?: string;
  asUser?: string;
}): Promise<StoreDocument>;

Creates a document. Pass id to choose it, or omit it and one is allocated. An id that already exists throws with status 409 - use replace to overwrite deliberately.

Parameters

Returns

Promise<StoreDocument>

replace()

replace(input: {
  workspaceId?: string;
  collection: string;
  id: string;
  data: Record<string, unknown>;
  asUser?: string;
}): Promise<StoreDocument>;

Replaces every field, creating the document if it does not exist. _createdAt/_createdBy survive.

Parameters

Returns

Promise<StoreDocument>

update()

update(input: {
  workspaceId?: string;
  collection: string;
  id: string;
  data: Record<string, unknown>;
  asUser?: string;
}): Promise<StoreDocument>;

Merges top-level fields into an existing document. Throws with status 404 if it does not exist.

Parameters

Returns

Promise<StoreDocument>

delete()

delete(input: {
  workspaceId?: string;
  collection: string;
  id: string;
  asUser?: string;
}): Promise<void>;

Idempotent - deleting a document that is not there succeeds.

Parameters

Returns

Promise<void>

commit()

commit(input: {
  workspaceId?: string;
  operations: StoreCommitOperation[];
  asUser?: string;
}): Promise<StoreCommitResult>;

Applies a set of writes atomically, across as many of your collections as they name. All of them land, or none.

This is the store's answer to a database transaction, and the shape is deliberate: you never hold one. A transaction handle passed across an HTTP boundary is a server-side lock whose duration your network controls, with Firestore's sixty-second ceiling and lock contention as the failure mode. Instead you read, decide, and commit conditional on nothing having moved - Connect runs the whole set as one short transaction on its side.

await connect.data.commit({
  workspaceId,
  operations: [
    { op: "create", collection: "ledger", id, data: entry },
    {
      op: "merge",
      collection: "funds",
      id: entry.fundId,
      data: { balancePaise: increment(entry.amountPaise) },
    },
  ],
});

A precondition that no longer holds throws ConnectError with status 409 and writes nothing - see transaction, which re-reads and retries for you. Note that the example above needs no precondition at all: an increment is commutative, so concurrent commits both land correctly.

Returns the id each operation wrote, in order - which is how you learn the id a create without one was given.

Parameters

Returns

Promise<StoreCommitResult>

transaction()

transaction(build: () => Promise<StoreCommitOperation[]>, options?: {
  workspaceId?: string;
  asUser?: string;
  attempts?: number;
}): Promise<StoreCommitResult>;

Read, decide, commit - retried when the world moved underneath you.

The optimistic-concurrency loop, written once. build reads whatever it needs and returns the operations to apply; if any precondition among them has gone stale by the time Connect looks, the commit is rejected whole and build runs again against fresh reads.

await connect.data.transaction(async () => {
  const fund = await connect.data.get({ workspaceId, collection: "funds", id });
  if (!fund.data.active) throw new Error("That fund is closed.");
  return [
    {
      op: "merge",
      collection: "funds",
      id,
      data: { balancePaise: increment(amount) },
      precondition: unchangedSince(fund),
    },
  ];
});

Only a 409 is retried. A 403 or a validation error means the operation was wrong rather than late, and retrying it would turn one clear failure into attempts identical ones. An error thrown by build itself - the closed-fund check above - is not retried either: it is a decision, not a collision.

build must be free of side effects outside the returned operations, because it can run more than once. That is the price of not holding a lock, and it is the same contract Firestore's own runTransaction states for the same reason.

Parameters

Returns

Promise<StoreCommitResult>

Interface: DoNotCallActorInput

Who made a change, in your own terms - kept as your application's claim.

Properties

Interface: DoNotCallResource

A workspace's do-not-call list - numbers that asked the business not to ring them.

Connect enforces it; you record it. Every outbound call to a listed number - a member's <ConnectCallButton> in any application, Connect's own dialer, an agent placing a call - is refused with ConnectError code do_not_call (HTTP 409) before anything reaches the carrier. So when a person asks your application not to be called, write it here; you do not need to check the list before dialling, and should not treat a read as permission to dial.

Every purpose: a person who said "stop ringing me" meant the service call too. Every change is kept in an append-only ledger (history: true).

Needs do-not-call:read / do-not-call:write.

Methods

get()

get(input: DoNotCallScope & {
  phone: string;
  history?: boolean;
}): Promise<ConnectDoNotCallLookup>;

A number's standing. Never-listed numbers resolve, with doNotCall: false.

Parameters

Returns

Promise<ConnectDoNotCallLookup>

set()

set(input: DoNotCallScope & {
  phone: string;
  reason: ConnectDoNotCallReason;
  note?: string | null;
  actor?: DoNotCallActorInput;
}): Promise<ConnectDoNotCallChange>;

Puts a number on the list. Idempotent - a number already listed keeps its original entry and answers changed: false, so a backfill can re-run.

Parameters

Returns

Promise<ConnectDoNotCallChange>

clear()

clear(input: DoNotCallScope & {
  phone: string;
  note: string;
  actor?: DoNotCallActorInput;
}): Promise<ConnectDoNotCallChange>;

Lifts a number's entry, so calls to it are placed again. note is required - it is a claim the person took their request back.

Parameters

Returns

Promise<ConnectDoNotCallChange>

Interface: DriveResource

Files in a workspace's Drive - upload, and signed URLs to read back.

Methods

upload()

upload(input: UploadInput): Promise<UploadedFile>;

Parameters

Returns

Promise<UploadedFile>

getFileUrl()

getFileUrl(fileId: string, input: {
  workspaceId: string;
}): Promise<string>;

A signed URL for the original bytes. Short-lived - fetch it when you need it, do not store it.

Parameters

Returns

Promise<string>

getPreviewUrl()

getPreviewUrl(fileId: string, input: {
  workspaceId: string;
  size?: ThumbnailSize;
}): Promise<string>;

A signed URL for the thumbnail. Same lifetime caveat as getFileUrl.

Parameters

Returns

Promise<string>

list()

list(input: {
  workspaceId: string;
  limit?: number;
}): Promise<DriveFileList>;

The files your application uploaded to this workspace's Drive, newest first - never a member's files, never another application's. limit defaults to 50 and is capped at 100; truncated says there were more. Needs drive:read.

Parameters

Returns

Promise<DriveFileList>

delete()

delete(fileId: string, input: {
  workspaceId: string;
}): Promise<void>;

Deletes a file your application uploaded. Throws ConnectError 404 for a file that is not yours, does not exist, or is already deleted - treat that as done when retrying. Needs drive:write.

Parameters

Returns

Promise<void>

getUsage()

getUsage(input: {
  workspaceId: string;
}): Promise<DriveUsage>;

How much of the workspace's Drive is used, against its limit. Needs drive:read and an active subscription to your application.

Parameters

Returns

Promise<DriveUsage>

Interface: EmailResource

Your application's own email - a support reply, a portal sign-in code - sent through Connect for a workspace that subscribes to you.

You hold no email provider credential. Every message leaves from Connect's sending address under the display name you choose (the workspace's name by default), with your own address in replyTo so the answer reaches you.

Server-side only, and deliberately absent from the browser bridge: mail to a customer is your backend's act, and Connect refuses a send that carries a member's session.

Methods

send()

send(input: SendEmailInput, options?: {
  idempotencyKey?: string;
}): Promise<SendEmailResponse>;

Send one email.

Store the returned messageId. It is the Message-ID the email actually left under - Connect's mail provider replaces any you propose - and a customer's reply names it in In-Reply-To. Thread the next reply by passing it as headers.inReplyTo (and appending it to headers.references).

suppressed is not an error. An address that hard-bounced or marked Connect's mail as spam is skipped and listed there while the others are sent; when every recipient is suppressed nothing is sent and the call still resolves. Retrying changes nothing - show the address as undeliverable.

Idempotent on idempotencyKey (a fresh UUID when you pass none, which protects only this call's own retries). Pass your own - the ticket and reply ids - so a retry after a timeout cannot put a second copy in somebody's inbox.

Parameters

Returns

Promise<SendEmailResponse>

Interface: EnrichmentResource

What Connect knows about the company at a domain.

The thing behind "the account filled itself in": a record holding nothing but priya@acme.com can offer a name, an industry, a size band and an address instead of an empty form.

Two properties are worth knowing before you wire it in, because they decide how you should render the result:

• Every value is cited, and nothing is recalled. Connect reads the company's own website and returns the URL each claim came from. A field the pages never stated comes back null rather than as a plausible guess.
• It is a suggestion, not a save. Nothing is written to your store, and nothing should be written to it without the person in front of it agreeing - which is also how HubSpot and Zoho present the same feature.

Methods

company()

company(input: {
  email?: string;
  domain?: string;
  asUser?: string;
  refresh?: boolean;
}, options?: {
  signal?: AbortSignal;
}): Promise<CompanyEnrichmentResult>;

Look a company up from a work email address or a domain.

Send whichever you hold; domain wins when both are given. A consumer address (founder@gmail.com) is answered with { status: "skipped", reason: "consumer_domain" } rather than an error - it names a person, not an employer.

asUser attributes the generation to the signed-in caller's workspace, resolved from their session token. Without it the call is attributed to your application.

Parameters

Returns

Promise<CompanyEnrichmentResult>

brand()

brand(input: {
  domain: string;
  asUser?: string;
  refresh?: boolean;
}, options?: {
  signal?: AbortSignal;
}): Promise<BrandExtractionResult>;

What the company at a domain looks like - logo, palette, typefaces, and the radius, spacing and breakpoint scales its own stylesheets declare.

The sibling of company() above: that one answers what a company does, this one answers what it looks like. Useful for white-labelling a portal to a customer's brand, pre-filling a design brief, or showing a real account card instead of a grey placeholder.

Needs an API key scoped to enrichment:brand - separate from enrichment:read because it is far more expensive: it crawls stylesheets, may render the page in a headless browser, and caches image bytes.

const result = await connect.enrichment.brand({ domain: "acme.com" });
if (result.status === "extracted") {
  const primary = result.profile.brandKit.palette.find((c) => c.role === "primary");
}

Three things to know before wiring it in:

• Set your client timeout to at least 90 seconds. A cold read runs the whole extraction before answering and can take up to a minute; many HTTP clients default to 30s and abandon a request that was about to succeed. Cached reads return in milliseconds, and cached is the normal case - profiles are held for 90 days, so you pay the cold path roughly once per domain.
• Never store brandKit.logos[].url. It is a short-lived signed URL minted per read. Render it directly or re-read the profile; persist sourceUrl if you need something stable.
• The values were measured, not generated. Check palette[].source - a css-var entry is the company naming its own colour, a frequency entry is a ranked count and much weaker.

Parameters