@cosmoops/connect-sdk 0.40.0 → 0.42.0

package/dist/types/client/components/call-button.d.ts

@@ -0,0 +1,132 @@
+import { type ReactNode } from "react";
+import type { CallingAvailability } from "../../types.js";
+/**
+ * Calling from the browser, through the workspace's own number.
+ *
+ * Three pieces: `<ConnectCallProvider>` once, high in your tree;
+ * `<ConnectCallButton phone="+91...">` wherever a person can be rung; and
+ * `useConnectCall()` if you want your own button.
+ *
+ * ## Why a provider, and why high up
+ *
+ * A call has to outlive the page it was started from - someone who rings a
+ * customer and then opens their invoices must not hang up on them by doing so.
+ * So the call lives in the provider, which also draws the in-call bar, and a
+ * button only asks it to start one. Mount it inside `<ConnectProvider>`,
+ * beside your app shell rather than inside a page.
+ *
+ * ## What happens when someone presses Call
+ *
+ * 1. The browser signs in to the phone network (`POST /calls/browser-token`
+ *    on your bridge), once per session - Plivo's SDK keeps its registration.
+ *    Plivo's SDK is loaded at this moment, not before, so a page that never
+ *    places a call never downloads it.
+ * 2. Connect approves the call (`POST /calls/start`): the workspace must hold
+ *    a number and the member must have "Make calls". What comes back lets this
+ *    browser place exactly this call and no other.
+ * 3. The browser places it. Connect dials the number from the workspace's own
+ *    number; nothing is recorded.
+ *
+ * ## Logging a call
+ *
+ * `onEnded` hands you the call id - deliberately not an outcome. A browser is
+ * not a witness your call log should trust, and the carrier's report reaches
+ * Connect a moment after the line drops anyway. Read the outcome on your
+ * **server** with `connect.calls.get(callId)` (`calls:read`): `status`,
+ * `talkSeconds`, `unansweredReason` and `placedByUserId` are what to log.
+ */
+type CallPhase = "connecting" | "ringing" | "in-call" | "ended";
+interface ActiveCall {
+    phase: CallPhase;
+    label: string;
+    number: string;
+    callId: string | null;
+    connectedAt: number | null;
+    endedAfterSeconds: number | null;
+    muted: boolean;
+    notice: string | null;
+}
+/** The number to ring, and how to name the person on the in-call bar. */
+export interface ConnectCallTarget {
+    /** E.164, e.g. `+919876543210`. */
+    phone: string;
+    /** Shown on the in-call bar. Defaults to the number. */
+    name?: string;
+    /**
+     * Called once the call is over, with Connect's id for it - or `null` when it
+     * never got as far as being approved. Read the outcome on your server with
+     * `connect.calls.get(callId)`; see the module comment for why not here.
+     */
+    onEnded?: (result: {
+        callId: string | null;
+    }) => void;
+}
+export interface ConnectCallContextValue {
+    /** A call is in progress - every Call button disables on it. */
+    isBusy: boolean;
+    startCall(target: ConnectCallTarget): Promise<void>;
+    /**
+     * Whether this member can call and, if not, why - `null` while it loads.
+     * Read once by the provider and shared, so every button and status panel
+     * agrees, and refreshed after each call so the minutes shown keep up.
+     */
+    availability: CallingAvailability | null;
+    /** Re-read `availability` - after a top-up in another tab, say. */
+    refreshAvailability(): void;
+}
+/** Start a call yourself. Must be inside `<ConnectCallProvider>`. */
+export declare function useConnectCall(): ConnectCallContextValue;
+export interface ConnectCallProviderProps {
+    children: ReactNode;
+    /**
+     * Called for every call that ends, whichever button started it - the place
+     * to wire "log this call" once for the whole app. A button's own `onEnded`
+     * runs as well.
+     */
+    onCallEnded?: (result: {
+        callId: string | null;
+        phone: string;
+    }) => void;
+    /** Called when a call could not be placed, with the reason to show. Defaults to the in-call bar saying so. */
+    onError?: (message: string) => void;
+    /** Extra classes for the in-call bar's outer element - merged with `cn`. */
+    className?: string;
+}
+/**
+ * Holds the call in progress and draws the in-call bar. See the module comment.
+ */
+export declare function ConnectCallProvider({ children, onCallEnded, onError, className, }: ConnectCallProviderProps): import("react").JSX.Element;
+export interface ConnectCallButtonProps extends ConnectCallTarget {
+    /** `compact` is an icon-only button for a row beside a number. */
+    variant?: "default" | "compact";
+    /** Button label. Defaults to "Call". */
+    children?: ReactNode;
+    isDisabled?: boolean;
+    /** Merged with `cn`, so an override replaces the default it conflicts with. */
+    className?: string;
+}
+/**
+ * Rings `phone` from the workspace's number. Needs `<ConnectCallProvider>`
+ * above it, and a member with "Make calls" - render it only for them, since a
+ * button the server refuses for everyone else helps nobody.
+ */
+export declare function ConnectCallButton({ phone, name, onEnded, variant, children, isDisabled, className, }: ConnectCallButtonProps): import("react").JSX.Element | null;
+export interface ConnectCallingStatusProps {
+    /** Merged with `cn`. */
+    className?: string;
+}
+/**
+ * The workspace's calling at a glance - its business number, the minutes
+ * left, and the next step - for a settings page. Reads the same availability
+ * the Call buttons do, so the two never disagree. Buying minutes and adding a
+ * number happen in Connect, and come back here when done.
+ */
+export declare function ConnectCallingStatus({ className }: ConnectCallingStatusProps): import("react").JSX.Element;
+/** The floating in-call card. Exported for Storybook only - the provider draws it. */
+export declare function ConnectActiveCallBar({ call, onHangUp, onToggleMute, className, }: {
+    call: ActiveCall;
+    onHangUp: () => void;
+    onToggleMute: () => void;
+    className?: string;
+}): import("react").JSX.Element;
+export type { ActiveCall as ConnectActiveCall };

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";
@@ -106,6 +108,8 @@ export { ConnectCreateWorkspaceModal } from "./components/create-workspace-form.
 export type { ConnectCreateWorkspaceModalProps } from "./components/create-workspace-form.js";
 export { useCreateWorkspace } from "./use-workspaces.js";
 export type { WorkspaceActionsState } from "./use-workspaces.js";
+export { ConnectCallProvider, ConnectCallButton, ConnectCallingStatus, useConnectCall, } from "./components/call-button.js";
+export type { ConnectCallProviderProps, ConnectCallButtonProps, ConnectCallTarget, ConnectCallContextValue, ConnectCallingStatusProps, } from "./components/call-button.js";
 export { ConnectBookingCalendar } from "./components/booking-calendar.js";
 export type { ConnectBookingCalendarProps } from "./components/booking-calendar.js";
 export { ConnectBookingDialog, ConnectBookingDetail } from "./components/booking-dialogs.js";

package/dist/types/client/portal-links.d.ts

@@ -4,7 +4,7 @@
  * `connectPortalUrl(appUrl, clientId, "/calendar/settings")`, and so on.
  *
  * Connect answers any of these paths for a signed-in user on the bare URL -
- * these two params only add the "Back to <your app>" banner
+ * these two params only add the `"Back to <your app>"` banner
  * (`ApplicationReturnBar` on Connect's side). It validates `return_to`
  * against this `client_id`'s registered redirect origins and silently drops
  * the banner if they don't match, so a wrong or stale `appUrl`/`clientId`

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.40.0";
+export declare const SDK_VERSION = "0.42.0";

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

@@ -1,5 +1,5 @@
 import { type TransportOptions } from "../http.js";
-import type { CallDetail, CallsPage } from "../../types.js";
+import type { BrowserCallingToken, CallingAvailability, CallDetail, CallsPage, StartedBrowserCall } from "../../types.js";
 export interface ListCallsInput {
     /** Narrow to one channel. A channel belonging to another application simply matches nothing. */
     channelId?: string;
@@ -42,4 +42,35 @@ export declare class CallsResource {
      * exist *or* belongs to another application.
      */
     get(callId: string): Promise<CallDetail>;
+    /**
+     * 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"`.
+     */
+    getCallingAvailability(input: {
+        asUser: string;
+    }): Promise<CallingAvailability>;
+    /** A carrier token the member's browser signs in to the phone network with. */
+    getBrowserCallingToken(input: {
+        asUser: string;
+    }): Promise<BrowserCallingToken>;
+    /**
+     * 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.
+     */
+    startBrowserCall(input: {
+        phone: string;
+        asUser: string;
+    }): Promise<StartedBrowserCall>;
+    /**
+     * Closes a call the browser never managed to place - recorded as
+     * `unanswered`/`cancelled`. A no-op once the carrier has it.
+     */
+    cancelBrowserCall(input: {
+        callId: string;
+        asUser: string;
+    }): Promise<void>;
 }

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>;
+}