@cosmoops/connect-sdk 0.41.0 → 0.42.0

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.42.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

@@ -2982,6 +2982,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.42.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",