@cosmoops/connect-sdk 0.41.0 → 0.43.0

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

@@ -0,0 +1,62 @@
+/**
+ * The hand-off contract with Connect's portal - the pure half, so the rules
+ * can be tested without a browser. `openConnect` (on `useConnect()`) is the
+ * half that touches `window`.
+ *
+ * Every time this SDK sends somebody to Connect for a task - a plan, a
+ * payment method, their profile - it appends three params, and Connect's
+ * portal brings them back when the task is done:
+ *
+ * | Param | |
+ * |---|---|
+ * | `client_id` | Names this application. Connect only honours a `return_to` whose origin is registered for that client. |
+ * | `return_to` | The page they left. |
+ * | `mode` | `popup` - Connect closes its window when done and posts the outcome to this page first. `redirect` - Connect navigates back here with `?connect_result=`. |
+ */
+/** How this application sends people to Connect - see `ConnectProviderProps.handoff`. */
+export type ConnectHandoffMode = "popup" | "redirect";
+/**
+ * How a trip to Connect ended, as Connect reports it.
+ *
+ * Advisory. A payment confirmed by webhook can settle a moment after the
+ * window has closed, so `"completed"` means "they finished there", not "it is
+ * live" - re-read entitlements for that. The provider already does, for every
+ * hand-off.
+ */
+export type ConnectHandoffResult = "completed" | "cancelled" | "closed";
+/** `MessageEvent.data.type` of the message Connect posts before closing a popup. */
+export declare const CONNECT_HANDOFF_MESSAGE_TYPE = "connect:handoff";
+/** The query param Connect adds when it redirects back. */
+export declare const CONNECT_HANDOFF_RESULT_PARAM = "connect_result";
+export interface HandoffUrlOptions {
+    appUrl: string;
+    /** Empty when neither the provider nor the bridge knows it - the URL still works, Connect just cannot offer the way back. */
+    clientId: string;
+    mode: ConnectHandoffMode;
+    /** The page to come back to - `window.location.href` at the moment of the press. */
+    returnTo: string;
+}
+/**
+ * `target` - a path (`"/billing"`) or an absolute Connect URL (a readiness
+ * blocker's `resolveUrl`) - with the hand-off params set.
+ *
+ * Throws for a URL on any other origin: these params tell Connect where to
+ * send somebody back, and stamping them onto a third party's URL would hand
+ * that party the page this visitor was on.
+ */
+export declare function buildHandoffUrl(target: string, { appUrl, clientId, mode, returnTo }: HandoffUrlOptions): string;
+/**
+ * The result a `message` event carries, or `null` when it is not Connect's
+ * hand-off message. The origin check is the whole security story: any page
+ * can `postMessage` this window, and only Connect's verdict may trigger work.
+ */
+export declare function readHandoffMessage(event: Pick<MessageEvent, "origin" | "data">, appUrl: string): ConnectHandoffResult | null;
+/**
+ * The result a redirect-mode return carries in `href`, and `href` with it
+ * removed - so a reload does not report the same trip twice and the param
+ * does not end up in a link somebody shares.
+ */
+export declare function takeHandoffResult(href: string): {
+    result: ConnectHandoffResult;
+    cleaned: string;
+} | null;

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

@@ -11,7 +11,9 @@
  * change lands identically in all of them.
  */
 export { ConnectProvider, useConnect, useConnectOptional, useConnectUser, useConnectWorkspaceType, useConnectAudience, useConnectPlatformAccess, useConnectEntitlements, useConnectPlans, useConnectApps, useConnectCompanyProfile, useConnectAddonUsage, useConnectSessions, useConnectIntegrations, useConnectResource, CONNECT_APP_URL, } from "./provider.js";
-export type { ConnectProviderProps, ConnectContextValue, ConnectSession, ConnectOneTapHint, ConnectOneTapFailure, UseConnectResourceOptions, } from "./provider.js";
+export type { ConnectProviderProps, ConnectContextValue, ConnectSession, ConnectOneTapHint, ConnectOneTapFailure, UseConnectResourceOptions, OpenConnectOptions, } from "./provider.js";
+export type { ConnectHandoffMode, ConnectHandoffResult } from "./handoff.js";
+export { CONNECT_HANDOFF_MESSAGE_TYPE, CONNECT_HANDOFF_RESULT_PARAM } from "./handoff.js";
 export { blockingBlockers, normalizePlanFeatures } from "../helpers.js";
 export type { WirePlanFeature } from "../helpers.js";
 export { ConnectError, isConnectError } from "../errors.js";

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

@@ -1,4 +1,5 @@
 import type { ReactNode } from "react";
+import { type ConnectHandoffMode, type ConnectHandoffResult } from "./handoff.js";
 import type { AddonUsageResponse, CompanyProfileResponse, ConnectUser, IntegrationsListResponse, WorkspaceApp, UserWorkspace, ConnectWorkspaceMember, PlansResponse, ReadinessResponse, SessionsListResponse, SessionSubscription, SessionAudience, SubscriptionResponse, WorkspaceType } from "../types.js";
 export declare const CONNECT_APP_URL = "https://connect.cosmoops.com";
 export interface ConnectSession {
@@ -32,6 +33,13 @@ export interface ConnectSession {
         hintUrl: string;
         authorizeUrl: string;
     } | null;
+    /**
+     * This application's public `client_id`, from the bridge - so `openConnect`
+     * can name the application on a hand-off without `clientId` being passed to
+     * `<ConnectProvider>` as well. Optional because an older bridge will not
+     * send it; the provider's own `clientId` prop wins when both exist.
+     */
+    clientId?: string | null;
 }
 /**
  * What Connect says about the visitor, before anything has been signed.
@@ -68,14 +76,39 @@ export interface ConnectOneTapHint {
 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>` -
-     * empty string otherwise. Safe in a browser regardless: it only ever goes
-     * into the authorize URL. Most integrations never read this - it exists for
-     * the explicit-`redirectUri` flow, see `ConnectProviderProps.clientId`.
+     * Public OAuth client id - the `clientId` passed to `<ConnectProvider>`,
+     * else the one your bridge reports on `/session`, else an empty string
+     * (an older bridge, before the session read settles). Safe in a browser
+     * regardless: it only ever goes into Connect URLs. Most integrations never
+     * read this - it exists for the explicit-`redirectUri` flow and for
+     * `connectPortalUrl`'s way back.
      */
     clientId: string;
     /** Connect's own origin, for deep links out to Profile, Billing and the catalog. */
     appUrl: string;
+    /** How `openConnect` sends people to Connect - `ConnectProviderProps.handoff`, after defaulting. */
+    handoffMode: ConnectHandoffMode;
+    /**
+     * Sends the visitor to a Connect page for a task, and brings them back when
+     * it is done. **Call it from a press handler** - a popup opened after an
+     * `await` is what pop-up blockers exist to stop.
+     *
+     * `target` is a path (`"/billing"`) or an absolute Connect URL, such as a
+     * readiness blocker's `resolveUrl`. Anything on another origin throws.
+     *
+     * - `"popup"` mode opens Connect in a new tab (or a sized window, with
+     *   `features`), which closes itself when the task is done and tells this
+     *   page first - every Connect component on it then re-reads. Returns the
+     *   window, for a caller that wants to watch it.
+     * - `"redirect"` mode, or a popup the browser blocked, navigates this tab
+     *   to Connect, which navigates back with `?connect_result=`. Returns
+     *   `null`; the page is going away.
+     *
+     * Either way the way back carries this page's URL and this application's
+     * `client_id`, and Connect only honours an origin registered for that
+     * client - register your app's origin among its redirect URIs.
+     */
+    openConnect(target: string, options?: OpenConnectOptions): Window | null;
     session: ConnectSession | null;
     /** `true` until the first `/session` read settles. Render skeletons, not a Login button. */
     isLoading: boolean;
@@ -178,6 +211,16 @@ export interface ConnectContextValue {
         reason: ConnectOneTapFailure;
     }>;
 }
+export interface OpenConnectOptions {
+    /**
+     * `window.open` features for a sized pop-up window instead of a tab -
+     * checkout uses `"popup,width=520,height=780"`. Must not include
+     * `noopener`: the window handle is how Connect reports back and closes.
+     */
+    features?: string;
+    /** `window.open` target name. A second `openConnect` with the same name reuses that window. */
+    name?: string;
+}
 export interface ConnectProviderProps {
     /**
      * This application's public `client_id`, from its Connect client section in Connect.
@@ -241,6 +284,30 @@ export interface ConnectProviderProps {
      * to your own `/signin`, which mints the `state` server-side.
      */
     silentSignIn?: boolean;
+    /**
+     * How every Connect button in this package - Billing, Profile, Manage,
+     * checkout, a readiness blocker's fix - takes the visitor to Connect.
+     *
+     * - `"popup"` (the default): Connect opens in a new tab and **closes itself**
+     *   when the task is done, telling this page first, so the visitor is back
+     *   where they were with everything repainted. A blocked popup falls back
+     *   to `"redirect"` rather than leaving them with nothing.
+     * - `"redirect"`: this tab goes to Connect and comes back. Prefer it for an
+     *   installed PWA or an app inside an iframe, where a second tab is a
+     *   different window the visitor may never find.
+     *
+     * Both need this app's origin registered among the client's redirect URIs
+     * in Connect - an unregistered origin still reaches Connect, it just gets no
+     * way back.
+     */
+    handoff?: ConnectHandoffMode;
+    /**
+     * Told how each trip to Connect ended - from the popup's message, or from
+     * `?connect_result=` on the way back from a redirect (which the provider
+     * then strips from the address bar). The provider already re-reads the
+     * session and every Connect resource; this is for your own state.
+     */
+    onHandoffResult?: (result: ConnectHandoffResult) => void;
     children: ReactNode;
 }
 /**
@@ -257,7 +324,7 @@ export interface ConnectProviderProps {
  * </ConnectProvider>
  * ```
  */
-export declare function ConnectProvider({ clientId, basePath, redirectUri, appUrl, fetch: fetchImpl, silentSignIn, children, }: ConnectProviderProps): import("react").JSX.Element;
+export declare function ConnectProvider({ clientId, basePath, redirectUri, appUrl, fetch: fetchImpl, silentSignIn, handoff, onHandoffResult, children, }: ConnectProviderProps): import("react").JSX.Element;
 export declare function useConnect(): ConnectContextValue;
 /**
  * The context when there is one, `null` when there is not.

package/dist/types/client/use-checkout.d.ts

@@ -9,7 +9,10 @@ import type { ReadinessResponse, SubscriptionResponse } from "../types.js";
  *   closing is not one.
  * - `abandoned` - the window closed (or the deadline passed) with the
  *   entitlement unchanged.
- * - `blocked` - the browser refused to open the window at all.
+ * - `blocked` - **no longer produced.** A blocked window now falls back to a
+ *   same-tab trip to Connect and back (see `openConnect`), which reaches the
+ *   same place without asking the customer to click a fallback link. Kept in
+ *   the union so code that handles it still compiles.
  */
 export type ConnectCheckoutStatus = "idle" | "waiting" | "completed" | "abandoned" | "blocked";
 export interface ConnectCheckoutState {

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

@@ -23,6 +23,7 @@ import { SessionsResource } from "./resources/sessions.js";
 import { PlatformResource } from "./resources/platform.js";
 import { VisitorResource } from "./resources/visitor.js";
 import { PushResource } from "./resources/push.js";
+import { WhatsAppResource } from "./resources/whatsapp.js";
 export declare const DEFAULT_BASE_URL = "https://connect.cosmoops.com";
 export interface ConnectClientOptions {
     /**
@@ -124,6 +125,8 @@ export declare class ConnectClient {
      * preferences; you supply a title, a body and a URL. See `PushResource`.
      */
     readonly push: PushResource;
+    /** Your application's own approved WhatsApp templates, to a workspace's customers. */
+    readonly whatsapp: WhatsAppResource;
     /**
      * Relays one `/data/*` or `/kv/*` request verbatim - `createConnectHandler`'s
      * store route and nothing else. See `storePassthrough`.
@@ -138,4 +141,4 @@ export declare class ConnectClient {
     constructor(options: ConnectClientOptions);
 }
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-export declare const SDK_VERSION = "0.41.0";
+export declare const SDK_VERSION = "0.43.0";

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

@@ -77,6 +77,16 @@ export declare class IdentityResource {
         hintUrl: string;
         authorizeUrl: string;
     } | null;
+    /**
+     * This client's public `client_id`, or `null` when none is configured.
+     *
+     * The bridge hands it to the browser on `/session` so `openConnect` can name
+     * the application on every hand-off without the host passing `clientId` to
+     * `<ConnectProvider>` too - Connect only honours a `return_to` it can match
+     * against *a client's* registered redirect origins. Public by definition:
+     * it already rides on every authorize URL.
+     */
+    publicClientId(): string | null;
     /** Step 2 - trade the one-time `code` for a session. Server-side only. */
     exchangeCode(input: ExchangeCodeInput): Promise<TokenResponse>;
     /**

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

@@ -0,0 +1,44 @@
+import { type TransportOptions } from "../http.js";
+import type { SendWhatsAppInput, SendWhatsAppResponse, WhatsAppTemplateState } from "../../types.js";
+/**
+ * Your application's own WhatsApp templates, sent to a workspace's customers
+ * through Connect's WhatsApp sender - no WhatsApp Business account of your
+ * own.
+ *
+ * Templates are written and submitted to Meta in Console under your
+ * application; you name them here by slug and Connect resolves
+ * `app_<yourApplicationKey>_<slug>` from your key, so a key can never send
+ * another application's message or one of Connect's own. There is no free
+ * text: outside a customer's 24-hour window WhatsApp permits nothing else.
+ *
+ * Server-to-server only - there is no browser path, by design.
+ */
+export declare class WhatsAppResource {
+    private readonly transport;
+    constructor(transport: TransportOptions);
+    /**
+     * Send one template to one customer.
+     *
+     * Refusals arrive as a `ConnectError` whose `code` says what to tell the
+     * person who pressed Send - `template_not_approved`, `consent_required`,
+     * `opted_out`, `not_found`. None of them is a fault worth retrying.
+     *
+     * An `Idempotency-Key` is always sent, as on `otp.send`: a retried send
+     * without one is a second message on somebody's phone. Pass your own -
+     * derived from what is being sent, e.g. the quote number - to make a
+     * retry from a *later* request safe too.
+     */
+    send(input: SendWhatsAppInput, options?: {
+        idempotencyKey?: string;
+    }): Promise<SendWhatsAppResponse>;
+    /**
+     * Whether a template would send right now, and the values it needs.
+     *
+     * Ask before offering WhatsApp on a screen: Meta's approval takes minutes
+     * to days, and an approved template can be paused later. A `ConnectError`
+     * with `status: 404` means your application has no such template.
+     */
+    template(slug: string, options?: {
+        language?: string;
+    }): Promise<WhatsAppTemplateState>;
+}

package/dist/types/types.d.ts

@@ -1114,7 +1114,7 @@ export interface EmitEventsResponse {
  * `createConnectWebhookHandler` simply ignores anything you have not
  * registered a handler for.
  */
-export type ConnectWebhookEventType = "workspace.deletion_scheduled" | "workspace.deletion_cancelled" | "workspace.deleted" | "subscription.cancelled" | "call.completed" | "call.missed" | "booking.confirmed" | "booking.cancelled" | "booking.rescheduled" | "contact.created" | "contact.updated";
+export type ConnectWebhookEventType = "workspace.deletion_scheduled" | "workspace.deletion_cancelled" | "workspace.deleted" | "subscription.cancelled" | "call.completed" | "call.missed" | "call.analyzed" | "booking.confirmed" | "booking.cancelled" | "booking.rescheduled" | "contact.created" | "contact.updated";
 /** What becomes of one class of data when the workspace is purged. */
 export type ConnectDataDisposition = "erase" | "anonymize" | "retain";
 /** Who answers for your copy of the customer's data. See the deletion-policy guide. */
@@ -1321,6 +1321,48 @@ export interface CallMissedEvent {
     /** ISO-8601. */
     occurredAt: string;
 }
+/** How the person called came across, by the end of the call. */
+export type CallSentiment = "positive" | "neutral" | "negative";
+/**
+ * Something somebody committed to on a recorded call. `owner` is who said
+ * they would do it - `rep` for your user's side, `customer` for the person
+ * called. Both are worth a follow-up: one to do, one to chase.
+ */
+export interface CallActionItem {
+    title: string;
+    /** `YYYY-MM-DD` when a day was named or clearly implied, else `null`. */
+    dueDate: string | null;
+    owner: "rep" | "customer";
+}
+/**
+ * A recorded call, transcribed and read. Sent minutes after `call.completed`,
+ * and only for calls placed while the workspace records them - file the call
+ * on `call.completed` and enrich that row here. The transcript itself is the
+ * call's turns on `calls.get`.
+ */
+export interface CallAnalyzedEvent {
+    workspaceId: string;
+    callId: string;
+    channelId: string | null;
+    /** E.164 - the person called on an outbound call, the caller on an inbound one. */
+    contactPhone: string | null;
+    direction: ConnectCallDirection;
+    handler: CallHandler;
+    placedByUserId: string | null;
+    placedByName: string | null;
+    /** Two or three sentences, in English whatever language was spoken. */
+    summary: string | null;
+    /** Why they were on the call, in a few lowercase words - "pricing enquiry". */
+    intent: string | null;
+    sentiment: CallSentiment | null;
+    /** The main language spoken, BCP-47 - `hi-IN`, `en-IN`. */
+    language: string | null;
+    actionItems: CallActionItem[];
+    /** The audio in the workspace's Drive - read it with a `drive:read` key. */
+    recordingFileId: string | null;
+    /** ISO-8601 - when the call started. */
+    occurredAt: string;
+}
 /**
  * An appointment was booked and is holding its slot.
  *
@@ -1446,6 +1488,7 @@ export interface ConnectWebhookEventMap {
     "subscription.cancelled": SubscriptionCancelledEvent;
     "call.completed": CallCompletedEvent;
     "call.missed": CallMissedEvent;
+    "call.analyzed": CallAnalyzedEvent;
     "booking.confirmed": BookingConfirmedEvent;
     "booking.cancelled": BookingCancelledEvent;
     "booking.rescheduled": BookingRescheduledEvent;
@@ -2804,7 +2847,7 @@ export interface ConnectCall {
     extraction: Record<string, unknown> | null;
     agentId: string | null;
     agentVersion: number | null;
-    /** `member` for a call a person placed with `<ConnectCallButton>`; such a call has no agent, transcript or recording. */
+    /** `member` for a call a person placed with `<ConnectCallButton>`. Such a call has no agent; it has a recording, a transcript and an `analysis` only when the workspace records calls. */
     handler: CallHandler;
     /** The member who placed a `member` call - their Connect user id. */
     placedByUserId: string | null;
@@ -2817,6 +2860,21 @@ export interface ConnectCall {
     talkSeconds: number | null;
     /** Why nobody answered - set only when `status` is `unanswered`. */
     unansweredReason: CallUnansweredReason | (string & {}) | null;
+    /**
+     * The reading of a recorded member call - summary, intent, action items.
+     * `null` for a call that was not recorded; `status: "pending"` while it is
+     * being read. The transcript is `CallDetail.turns`, the member as `agent`
+     * and the person called as `user`.
+     */
+    analysis: ConnectCallAnalysis | null;
+}
+export interface ConnectCallAnalysis {
+    status: "pending" | "done" | "failed";
+    summary: string | null;
+    intent: string | null;
+    sentiment: CallSentiment | null;
+    actionItems: CallActionItem[];
+    language: string | null;
 }
 /**
  * What the browser needs to place one approved call - see
@@ -2982,6 +3040,48 @@ export interface ConversationsPage {
     nextCursor: string | null;
     hasMore: boolean;
 }
+/**
+ * One of your application's own Meta-approved templates, to one customer.
+ *
+ * Hand-written here like every wire type in this file - see `SendPushInput`.
+ */
+export interface SendWhatsAppInput {
+    /** The subscribing workspace this is sent on behalf of. */
+    workspaceId: string;
+    /** The template's slug within your application, e.g. `quote-issued` - never its Meta name. */
+    template: string;
+    /** Meta language code the template was approved in. Defaults to `en`. */
+    language?: string;
+    /** E.164, e.g. `+919876543210`. */
+    to: string;
+    /** One value per template variable, by name. A missing one refuses the send. */
+    values?: Record<string, string>;
+    /**
+     * The opt-in your application collected, recorded only when Connect has
+     * none on file for the number. A number that withdrew stays withdrawn.
+     */
+    consent?: {
+        collectedVia: string;
+    };
+}
+export interface SendWhatsAppResponse {
+    status: "sent";
+    messageId: string;
+}
+/** Meta's review state for a template. Only `APPROVED` sends. */
+export type WhatsAppTemplateReviewStatus = "DRAFT" | "PENDING" | "APPROVED" | "REJECTED" | "PAUSED" | "DISABLED";
+/** Whether one of your templates would send right now. Branch on `live`. */
+export interface WhatsAppTemplateState {
+    slug: string;
+    language: string;
+    /** Meta's name for it: `app_<applicationKey>_<slug>`. */
+    name: string;
+    status: WhatsAppTemplateReviewStatus;
+    /** Approved by Meta *and* currently served. */
+    live: boolean;
+    /** The values a send must carry, from the approved content. */
+    variables: string[];
+}
 /**
  * One notification, to members of one workspace.
  *

package/package.json

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