`@cosmoops/connect-sdk` follows semver, with the 0.x convention that **minor versions may carry breaking changes** and patch versions never do. ## 0.56.0 ### One CosmoOps login: account mode (first-party apps) `CONNECT_SESSION_MODE=account` makes the `./next` bridge use the shared CosmoOps account session Connect sets on the parent domain, instead of a per-application OAuth session. Sign in once at Connect and every first-party app knows you; signing out anywhere signs out everywhere; switching workspace in one app switches all of them. The application must be marked first-party in Console. Partner applications are unaffected - application mode stays the default. - **`connect.identity.getAccountUser(accountSession)`**, **`logoutAccount(accountSession)`**, **`switchAccountWorkspace(accountSession, workspaceId)`** and **`accountContinueUrl({ returnTo })`** - the account-session endpoints. The reads answer exactly `getUser`'s `UserResponse`, through the same mapping, and are retried like it. - **In account mode** (`./next`): `getConnectSession()` and `/session` resolve the `CONNECT_ACCOUNT_COOKIE` cookie (default `cosmoops_session_local`) through `getAccountUser`; `/signin` redirects to Connect's continue URL with `returnTo` = this app's origin plus `next`; `/logout` calls `logoutAccount` and clears the cookie (`Path=/`, plus `Domain=` from `CONNECT_ACCOUNT_COOKIE_DOMAIN`); `/workspaces/switch` goes through `switchAccountWorkspace`; `/callback` and One Tap do not exist. The app never writes the account cookie. `getConnectSessionToken()` returns the `acs_` account id, and `asUser` calls pass it through unchanged. - **Migration:** in account mode a per-application session from before the switch is still honoured through `getUser` until it expires. - New exports: `connectSessionMode()`, `connectAccountSession()`, `connectSessionCookieName(clientId)` (`./next`); types `ConnectAccountSessionOptions` (`./server`, `./next`) and `ConnectSessionOptions` (`./next`). `ConnectSessionStore` gains an optional `migrate()`, and `createConnectHandler` an optional `account`. ### Per-application session cookie name In application mode the `./next` cookie is now **`connect_session_`** rather than `connect_session`, so several apps on one host (`localhost`) stop overwriting each other's session. The legacy `connect_session` cookie is still read as a fallback and, once Connect accepts it, rewritten under the new name by `GET /session`; it is never cleared, because another app may own it. `CONNECT_SESSION_COOKIE` still overrides the name exactly (with no fallback). If you read the cookie yourself by name, use `connectSessionCookieName(clientId)`, or `getConnectSessionToken()`. ### Telephony: answer your own calls through Connect's carrier edge Connect stays the carrier - the carrier account, the number inventory, rental and billing - and an application with a telephony webhook configured in Console owns its calls. Every carrier callback for a number it handles is relayed to that webhook, signed with the application's webhook secret, and the XML it answers `answer`/`fallback` with is executed on the call. - **`verifyTelephonyEvent(rawBody, signatureHeader, secret)`** (`./server`) - verifies and parses a relayed `TelephonyCarrierEvent`, or throws `ConnectError` (`invalid_signature`, `malformed_event`). It accepts the header when *any* `v1=` matches, because Connect signs with every active endpoint secret the application holds. - **`connect.telephony`** - `dial(input)`, `hangup(providerCallUuid, { workspaceId })`, `browserToken(input)` and `archiveRecording(recordingId, input)`, behind the new `telephony:call` scope. `hangup` and `archiveRecording` are retried on a transient failure; `dial` never is. - **`connect.channels.release(channelId, { workspaceId })`** - the inverse of `claim`, under `channels:claim`. - **`ConnectChannel.handlerApplicationId`** - the application that answers the number itself, or `null` when Connect does. ### Call analysis - **`connect.ai.analyzeCall(input)`** - transcript, summary, intent, sentiment and action items for a recording your application stored in the workspace's Drive (e.g. `archiveRecording`'s `fileId`). Uses the `ai:generate` scope and the workspace's monthly AI budget. New type: `CallAnalysis`. New types: `TelephonyCarrierEvent`, `TelephonyEdgeEvent`, `TelephonyDialInput`, `TelephonyDialResult`, `BrowserTokenInput`, `BrowserTokenResult`, `ArchiveRecordingInput`, `ArchivedRecording`, `CallAnalysisInput`, `CallAnalysis`. ## 0.55.1 ### Fixed - **`` passes the button's full props through**, not just `href`, `className` and `children` - the `ref` and React Aria's press, keyboard and focus handlers included, which ends the "Ref was not connected" and "PressResponder" warnings and restores the pressed and focus styling. Clicks still navigate, `next/link` included; an `isDisabled` one now refuses the click and carries `aria-disabled`. Spread the props (`renderLink={(props) => }`) to benefit; the widened parameter type, `ConnectLinkButtonRenderProps`, is exported. ## 0.55.0 ### Breaking: `conversations` is removed `ConnectClient.conversations` (`list`, `get`) is gone, and so are the `ConnectConversation`, `ConnectConversationMessage`, `ConnectMessageFailure`, `ConversationDetail`, `ConversationsPage` and `ListConversationsInput` types. `GET /conversations` and `GET /conversations/{id}` and the `conversations:read` scope are removed from the API. Customer WhatsApp now belongs to the CosmoOps Messaging application, which holds the customer's own WhatsApp Business account, its templates, opt-outs and the human inbox. Connect's conversations came from an agent replying on a WhatsApp channel, and no workspace could ever create such a channel, so the endpoints only ever returned an empty list. If you read them, delete the call. Connect's own platform WhatsApp (`connect.whatsapp.*`, OTP over WhatsApp, notifications) is unchanged. Existing keys that still carry `conversations:read` keep working: the scope is dropped when the key is read, not refused. ### Send email `connect.email.send({ workspaceId, to, subject, html, text, replyTo?, fromName?, cc?, headers? })` sends your application's own email - a support reply, a portal sign-in code - for a workspace that subscribes to you, with no email provider account of your own. It backs the new `POST /email/send` and needs a key scoped to `email:send`. Server-side only. Every message leaves from Connect's address under `fromName` (the workspace's name by default); put your inbound address in `replyTo`. Store the returned `messageId` - it is the Message-ID the email actually left under, and the one a reply names in `In-Reply-To` - and thread the next reply with `headers.inReplyTo`/`headers.references`. Addresses that hard-bounced or complained are skipped and listed in `suppressed`, not thrown. Pass an `idempotencyKey` so a retry cannot send a second copy. Email is additive. ### Do-not-call `connect.doNotCall.get({ workspaceId, phone, history? })`, `.set(...)` and `.clear(...)` read and write the workspace's do-not-call list, which Connect now enforces before **every** outbound dial: a member's call, a partner's `POST /calls/start`, and an agent-placed call. A listed number is refused with `409 do_not_call`. If the list cannot be read, the dial is refused with a retryable `503 do_not_call_unverified` rather than placed. Setting a listed number again is a no-op, and clearing it needs a note; both are kept in an append-only history. The list needs `do-not-call:read` / `do-not-call:write` scopes. Write through to it wherever your own app records "do not call", because a flag only your app knows about stops nobody's dialer. ### Prepaid credit `connect.credit.getBalance`, `.consume`, `.refund` and `.listLedger` give your application a prepaid rupee balance per workspace. The customer tops it up on Connect (send them to the balance's `topUpPath` with `openConnect`; it hands them back), Connect charges GST and issues the invoice under your SAC, and you debit it per use. - `consume` takes an `idempotencyKey`. A replay returns `duplicate: true`; the same key with a different amount is refused. - A balance that cannot cover the debit is refused with `409 insufficient_credit`, unless Connect has granted your application an overdraft. - `refund` must name an earlier `consume` and can never exceed it. - Scopes: `credit:read` / `credit:write`. ### WhatsApp helpers: `@cosmoops/connect-sdk/whatsapp` A new browser-safe subpath with Meta's template component model, template compile and validate, template-name rules, the opt-out and consent decision, and webhook parsing. It is the same implementation Connect runs, for an application that runs its own WhatsApp Business account. Nothing changes for the root entry. ### Writes for applications that act for a workspace - **`contacts.upsertFromInteraction({ workspaceId, phone, facts, source, callId?, countCall? })`** contributes what a call or conversation learned to the workspace's contact book. It is find-or-create by phone, with the same merge Connect's own calls use: an automated source fills blanks and never overwrites. It raises `contact.created` / `contact.updated`. Scope: `contacts:write`, server-to-server only. - **`scheduling.holdSlot(...)` and `scheduling.confirmHold(...)`** hold a slot while you collect details, then confirm it. Only the application that took a hold can confirm it, and confirming twice is harmless. `createBooking` also accepts `source` (`api` | `agent-call`) and `sourceCallId`. Scope: `calendar:write`. - **`ai.generate(...)`** is raw model generation, separate from `ai.chat` (Connect's own assistant). One model step per request; any tools you declare are returned to you, never run by Connect. It answers `503` until Connect enables it for the platform. Scope: `ai:generate`. - **`workspaces.get({ workspaceId })`** returns a subscribing workspace's name, legal name, account type, status and the owner's name and email, with nobody signed in. Scope: `workspace-profile:read`, which is sensitive and refuses session tokens. ### New webhook: `subscription.activated` Fires once, when a subscription to your application first becomes active: free, trial or first payment. It does not fire on renewals, or when a subscription resumes from pause. Use it to provision what a new subscriber gets. ### Drive: list and delete your own files - `connect.drive.list({ workspaceId, limit? })` returns the files your application uploaded to that workspace's Drive, newest first. `limit` defaults to 50 and is capped at 100; `truncated: true` means more exist. Needs `drive:read`. - `connect.drive.delete(fileId, { workspaceId })` removes one of them and gives the space back to the workspace's quota. Needs `drive:write`. Both reach only files your application uploaded. A member's file, another application's file and an unknown id all answer the same 404, so a retried delete can treat 404 as done. ### Calling readiness from your own server `connect.calls.getCallingReadiness` now also accepts `{ workspaceId }` in place of `{ asUser }`, so a dialer can check before it places a call with nobody signed in. The answer is the same, except that `canManage` is always `false` because there is no member. Everything except the `conversations` removal is additive. ## 0.54.0 ### Report usage against your plan limits `connect.entitlements.reportUsage(workspaceId, { records: 1840 })` tells Connect how many of your own limited resources a workspace has, so the customer's Billing → Usage tab shows "1,840 of 5,000" with a meter instead of a bare ceiling. It backs the new `POST /usage` and needs a key scoped to `usage:report`. Send the **current count**, not a change - the number you already pass to `canAdd`. Reporting twice is harmless and a lost report is healed by the next, so no idempotency key is sent. Keys you leave out keep their last value; a key outside your limit catalog is refused by name (`400`), and a workspace that is not your subscriber answers `404`. Connect enforces nothing on these numbers - `canAdd` is still the gate - so report after the user's action and catch. ### Subscribe with a seat count `buildCheckoutUrl({ ..., seats: 8 })` (and the checkout hooks that take `CheckoutUrlOptions`) seeds Connect's checkout with the total seats on a per-seat plan, so "Subscribe for my 8-person team" is priced in one payment rather than the included count now and a prorated top-up after. Ignored on a plan change and on plans that do not sell seats one at a time. Additive; nothing to change for existing integrations. ## 0.53.0 ### Record a no-show `connect.scheduling.recordAttendance({ workspaceId, bookingId, attended })` marks an appointment the attendee missed as `no_show` (`attended: false`), and takes a mistaken one back to `confirmed` (`attended: true`). It backs the new `POST /scheduling/bookings/{bookingId}/attendance` and needs `calendar:write`. `no_show` has always been on the `Booking` wire and nothing could set it, so any attendance figure built on it read 100%. There is no "held" to record - a `confirmed` booking whose time has passed already is one. A booking that is not `confirmed`/`no_show`, or has not started yet, answers `409`. The slot is not released and the attendee is not notified. Additive; nothing to change for existing integrations. ## 0.52.0 ### Calls survive a dropped connection, or end saying why When the browser goes offline mid-call, the in-call bar now says "Reconnecting…" and Plivo's SDK renegotiates the audio by itself when the network returns - a few seconds' blip costs the call nothing. If it is still offline after 30 seconds, the call is ended in the browser instead of ticking on a dead line (the carrier's own hang-up cannot reach an offline browser, so the bar used to sit at "in call" indefinitely). A call that ends that way says "Your internet connection dropped, so the call ended." and offers **Call again**; `onEnded` / `onCallEnded` fire as for any other end. Pressing Call while offline now answers "You're offline. Check your internet connection and try again." instead of a phone-service sign-in error. `ConnectActiveCall` gains `reconnecting` and `canRedial`, and `ConnectActiveCallBar` an optional `onRedial`. Nothing to wire - the provider does all of it. ## 0.51.0 ### Inbound call routing `connect.calls.getRouting({ asUser })` reads the workspace's inbound call routing flow and its published agents; `connect.calls.setRouting({ routing, asUser })` sets it (smart CRM owner routing, AI agent, single number, team, fallback). Needs `CHANNEL_MANAGE` to write. ### Add-ons billed yearly `Addon.billingCadence` is `"annual"` for an add-on billed once on the first cycle that holds it and on each anniversary, even on a monthly plan; render its price as "/year". `"plan"` or absent means every plan cycle, as before. `ConnectPlans` already draws the suffix. Additive; nothing else changed. ## 0.50.0 ### Background tasks `connect.tasks.enqueue({ workspaceId, queue, payload, name?, scheduleAt? })` puts a task on one of your application's Cloud Tasks queues, declared in Console (scope `tasks:write`). Cloud Tasks delivers `{ workspaceId, queue, payload }` to the queue's URL with a Google-signed OIDC token; `createConnectTaskHandler({ handle })` - or `verifyConnectTask(request)` - from `./server` or `./next` verifies it. Set `CONNECT_TASK_INVOKER` to the invoker account the platform gives you. `name` dedups per workspace; `status: "unavailable"` means the Connect deployment has no queue, so keep a fallback. Additive; nothing else changed. ## 0.49.0 ### Calling readiness `connect.calls.getCallingReadiness({ asUser })` answers whether the workspace may legally make each kind of call - `runs` covers service and sales (`promotional`) calls, dialled by a rep (`preview`) or by software (`automatic`), each with the first `reason` in the way - plus the steps left on Connect's calling compliance journey and a `setupUrl` to finish them. Member-only, on the `calls:place` scope. Read `runs` rather than deriving anything from `steps`: Connect evaluates them with the gates its dialer refuses on. Additive; nothing else changed. ## 0.48.0 ### Calls declare a purpose ``, `startCall({ phone, purpose })` and `connect.calls.startBrowserCall({ phone, asUser, purpose })` take an optional `ConnectCallPurpose` - `"service"`, `"transactional"` or `"promotional"`. Connect records it on the call and places the call from a workspace number allowed to carry it: in India a regular number carries service and transactional calls only, and promotional calls need a 140-series number with an approved DLT header. Omit it and the call is placed as before. While the workspace's Connect deployment runs `CALL_PURPOSE_ENFORCEMENT=shadow` (the default), a call no number may carry is still placed and only logged; under `enforce` it is refused with a `412` whose message names the number series needed. The bridge drops a purpose that is not one of the three rather than forwarding it to be refused. ## 0.47.0 ### `connect.integrations.request()` reaches the endpoints a toolkit has no action for A Composio toolkit's action catalogue is not the provider's API: Zoho Books ships no action to create a sales order, an estimate or an invoice. `integrations.request(workspaceId, { toolkitSlug, method, endpoint, query, body })` sends one request to the provider through the workspace's connected account, under the `integrations:execute` scope - Connect still holds the credential. `endpoint` is a path relative to the provider's API base (`/salesorders`). Connect refuses an absolute URL, a query string in the path and dot segments, and there is no way to set a header: whoever chooses the host chooses where the credential goes. The call resolves whenever Connect relayed it - read the provider's own `status` and `data` from the result. ### `initiateConnect` takes `connectionData` Pre-fills a toolkit's own connection fields on the provider's screen. `{ extension: "in" }` puts a Zoho connection on the India data centre, which otherwise defaults to `zoho.com`. ### A 503 without `Retry-After` is no longer retried The SDK retried every 503 on an idempotent request, twice, sleeping the server's `Retry-After` between. Connect now leaves that header off a 503 it knows will not heal - a dependency rejecting Connect's own credential, such as the provider behind `connect.integrations.list()` - and the SDK now takes that at its word: no `Retry-After`, no retry, and `ConnectError.isRetryable` is `false`. A misconfigured dependency used to cost every read three round trips and about four seconds of sleeping to return the same error. Every 503 Connect means to be retried still carries the header, so nothing that recovers today stops recovering. ## 0.46.0 ### `secondary` buttons are soft indigo `