@cosmoops/connect-sdk 0.3.0 → 0.7.0

package/dist/esm/server/resources/drive.js

@@ -1,5 +1,5 @@
 import { pathSegment, request } from "../http.js";
-/** Files in an organization's Drive - upload, and signed URLs to read back. */
+/** Files in a workspace's Drive - upload, and signed URLs to read back. */
 export class DriveResource {
     transport;
     constructor(transport) {
@@ -9,7 +9,7 @@ export class DriveResource {
         const form = new FormData();
         const fileName = input.fileName ?? input.file.name ?? "upload";
         form.set("file", input.file, fileName);
-        form.set("organizationId", input.organizationId);
+        form.set("workspaceId", input.workspaceId);
         if (input.parentId)
             form.set("parentId", input.parentId);
         return request(this.transport, { method: "POST", path: "/drive/files", multipart: form });
@@ -19,7 +19,7 @@ export class DriveResource {
         const result = await request(this.transport, {
             method: "GET",
             path: `/drive/files/${pathSegment(fileId, "fileId")}/url`,
-            query: { organizationId: input.organizationId },
+            query: { workspaceId: input.workspaceId },
         });
         return result.url;
     }
@@ -28,7 +28,7 @@ export class DriveResource {
         const result = await request(this.transport, {
             method: "GET",
             path: `/drive/files/${pathSegment(fileId, "fileId")}/preview-url`,
-            query: { organizationId: input.organizationId, size: input.size },
+            query: { workspaceId: input.workspaceId, size: input.size },
         });
         return result.url;
     }

package/dist/esm/server/resources/entitlements.js

@@ -9,7 +9,7 @@ export class EntitlementsResource {
         this.transport = transport;
     }
     /**
-     * Every gate Connect owns between an organization and your service -
+     * Every gate Connect owns between a workspace and your application -
      * subscription, KYC/KYB, a chargeable payment method, seat headroom -
      * resolved in one call.
      *
@@ -17,17 +17,17 @@ export class EntitlementsResource {
      * Connect screen that fixes it, so you can route them somewhere useful
      * instead of refusing them with nowhere to go.
      */
-    getReadiness(organizationId) {
+    getReadiness(workspaceId) {
         return request(this.transport, {
             method: "GET",
-            path: `/onboarding/organizations/${pathSegment(organizationId, "organizationId")}`,
+            path: `/onboarding/workspaces/${pathSegment(workspaceId, "workspaceId")}`,
         });
     }
     /** The live plan and subscription, including `plan.features`. */
-    getSubscription(organizationId) {
+    getSubscription(workspaceId) {
         return request(this.transport, {
             method: "GET",
-            path: `/subscriptions/organizations/${pathSegment(organizationId, "organizationId")}`,
+            path: `/subscriptions/workspaces/${pathSegment(workspaceId, "workspaceId")}`,
         });
     }
     /**
@@ -38,8 +38,8 @@ export class EntitlementsResource {
      * all: "not entitled" is the same answer either way, and a feature gate
      * should not need a try/catch around it.
      */
-    async hasFeature(organizationId, feature) {
-        const result = await this.getSubscription(organizationId);
+    async hasFeature(workspaceId, feature) {
+        const result = await this.getSubscription(workspaceId);
         return result.hasActiveSubscription && (result.plan?.features.includes(feature) ?? false);
     }
 }

package/dist/esm/server/resources/identity.js

@@ -66,7 +66,7 @@ export class IdentityResource {
             sessionTokenExpiresIn: wire.session_token_expires_in,
             user: wire.user,
             subscription: wire.subscription,
-            serviceRole: wire.serviceRole,
+            applicationRole: wire.applicationRole,
         };
     }
     /**
@@ -136,7 +136,7 @@ export class IdentityResource {
         return {
             user: wire.user,
             subscription: wire.subscription,
-            serviceRole: wire.serviceRole,
+            applicationRole: wire.applicationRole,
             sessionExpiresAt: wire.session_expires_at,
         };
     }
@@ -145,7 +145,7 @@ export class IdentityResource {
      * rest of its ~15-day life. Discard your own copy of `sessionToken` too;
      * this does not do that for you.
      *
-     * `scope` defaults to `"device"`: this sign-in, every other service signed
+     * `scope` defaults to `"device"`: this sign-in, every other application signed
      * into from the same browser, and Connect's own session on that one device.
      * `"all"` ends every session on every device - an explicit "sign out
      * everywhere" action only.
@@ -177,7 +177,7 @@ export class IdentityResource {
             throw new ConnectError({
                 status: 0,
                 code: "missing_client_id",
-                message: "identity.* needs `clientId`. Pass it to `new ConnectClient({ clientId, apiKey })` - it is shown in this service's Setup tab once SSO is enabled.",
+                message: "identity.* needs `clientId`. Pass it to `new ConnectClient({ clientId, apiKey })` - it is shown in this application's Integration tab, under Connect client.",
                 endpoint: "identity",
             });
         }

package/dist/esm/server/resources/integrations.js

@@ -0,0 +1,62 @@
+import { request } from "../http.js";
+/**
+ * Composio-hosted third-party connections (Google Calendar, Slack,
+ * Twitter/X, ...) a workspace has connected. Connect proxies every call
+ * here - your application never sees or holds the underlying OAuth token, which
+ * stays with Composio.
+ */
+export class IntegrationsResource {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /** Enabled toolkits and this workspace's connection status for each. */
+    async list(workspaceId) {
+        const result = await request(this.transport, {
+            method: "GET",
+            path: "/integrations",
+            query: { workspaceId },
+        });
+        // `?? []` for the same reason `AppsResource.list` has it - a collection
+        // every caller immediately maps or measures.
+        return result.toolkits ?? [];
+    }
+    /**
+     * Starts a Composio-hosted connection for one toolkit. The returned
+     * `redirectUrl` is where the browser completes the provider's OAuth
+     * screen, then Composio bounces it back to `returnUrl`.
+     *
+     * **The connection is not active when this returns.** Treat the toolkit
+     * as `pending` until a later `list()` call reports `active` - only
+     * Connect's own webhook from Composio confirms that, never the redirect
+     * itself. Reconnecting a disconnected/failed toolkit calls this same
+     * method - there is no separate reconnect.
+     *
+     * Meant to be called on behalf of a signed-in workspace admin (this is what the
+     * bridge's fixed `POST /integrations/connect` route does), not as a bare
+     * background action with no admin present to complete the OAuth screen.
+     */
+    async initiateConnect(workspaceId, toolkitSlug, returnUrl) {
+        return request(this.transport, {
+            method: "POST",
+            path: "/integrations/connect",
+            json: { workspaceId, toolkitSlug, returnUrl },
+        });
+    }
+    /** Idempotent - disconnecting a toolkit that was never connected, or is already disconnected, is a success. */
+    async disconnect(workspaceId, toolkitSlug) {
+        return request(this.transport, {
+            method: "POST",
+            path: "/integrations/disconnect",
+            json: { workspaceId, toolkitSlug },
+        });
+    }
+    /** Calls a Composio action against this workspace's connected account for the named toolkit. */
+    async execute(workspaceId, input) {
+        return request(this.transport, {
+            method: "POST",
+            path: "/integrations/actions/execute",
+            json: { workspaceId, ...input },
+        });
+    }
+}

package/dist/esm/server/resources/logs.js

@@ -1,5 +1,5 @@
 import { request } from "../http.js";
-/** Push feature events into the Console's audit log, filterable to your service. */
+/** Push feature events into the Console's audit log, filterable to your application. */
 export class LogsResource {
     transport;
     constructor(transport) {
@@ -11,9 +11,9 @@ export class LogsResource {
      * reported through the return value.
      *
      * Pass `sessionToken` to attribute the event to the end user it belongs to.
-     * Both scopes on the stored entry come from something verified - the service
+     * Both scopes on the stored entry come from something verified - the application
      * from your API key, the user from that token, which Connect checks was
-     * minted for your service before attributing anything. `attributed` in the
+     * minted for your application before attributing anything. `attributed` in the
      * result says whether it resolved; a `false` there still means the line was
      * stored, just without a user on it.
      */

package/dist/esm/server/resources/sessions.js

@@ -5,11 +5,11 @@ import { request } from "../http.js";
  * timestamps - the same list Connect's own account settings page shows the
  * user themselves.
  *
- * **Account-wide, not scoped to this service.** A Connect session is one
- * browser's login to Connect, and it fans out to every partner service's own
- * `sessionToken` - Connect has no per-service session concept to filter by.
+ * **Account-wide, not scoped to this application.** A Connect session is one
+ * browser's login to Connect, and it fans out to every partner application's own
+ * `sessionToken` - Connect has no per-application session concept to filter by.
  * `list()` returns every session on the account, including ones that
- * originated from a completely different, unrelated service. Requires the
+ * originated from a completely different, unrelated application. Requires the
  * `sessions:manage` scope on your API key - unlike `identity`'s base `sso`
  * capability, this is never granted to a zero-scope legacy key by default.
  *
@@ -35,7 +35,7 @@ export class SessionsResource {
     }
     /**
      * Ends one specific session by id - not necessarily the one `sessionToken`
-     * itself was minted from. Cascades to every partner-service sign-in that
+     * itself was minted from. Cascades to every partner-application sign-in that
      * originated from that same browser, same as Connect's own "sign out this
      * device".
      */
@@ -69,7 +69,7 @@ export class SessionsResource {
             throw new ConnectError({
                 status: 0,
                 code: "missing_client_id",
-                message: "sessions.* needs `clientId`. Pass it to `new ConnectClient({ clientId, apiKey })` - it is shown in this service's Setup tab once SSO is enabled.",
+                message: "sessions.* needs `clientId`. Pass it to `new ConnectClient({ clientId, apiKey })` - it is shown in this application's Integration tab, under Connect client.",
                 endpoint: "sessions",
             });
         }

package/dist/esm/server/webhooks.js

@@ -0,0 +1,123 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+/**
+ * How far out of date a timestamp may be. Five minutes, the same value
+ * Connect signs against and the same one Stripe uses - so a backend that
+ * already verifies Stripe webhooks needs no new assumptions.
+ */
+const TIMESTAMP_TOLERANCE_SECONDS = 300;
+const SIGNATURE_HEADER = "connect-signature";
+/**
+ * Verifies a `Connect-Signature` header against the raw request body.
+ *
+ * Exported on its own for anyone wiring this into a framework
+ * `createConnectWebhookHandler` does not cover. The **raw** body matters:
+ * verify before parsing, and never re-serialise - `JSON.stringify(await
+ * req.json())` produces a different string whenever key order or number
+ * formatting differs, and the signature will not match.
+ *
+ * Returns a boolean and never explains which check failed. Reporting "bad
+ * timestamp" separately from "bad signature" tells whoever is probing which
+ * half of a forgery to keep working on.
+ */
+export function verifyConnectWebhook(rawBody, signatureHeader, secret, now = new Date()) {
+    if (!signatureHeader)
+        return false;
+    const parts = new Map(signatureHeader
+        .split(",")
+        .map((part) => part.trim().split("="))
+        .filter((pair) => pair.length === 2)
+        .map(([key, value]) => [key, value]));
+    const timestamp = Number(parts.get("t"));
+    const presented = parts.get("v1");
+    if (!presented || !Number.isFinite(timestamp))
+        return false;
+    // Absolute difference: a timestamp from the future is as much a sign of a
+    // forgery as a stale one, and accepting it would let somebody mint a
+    // signature that stays valid indefinitely.
+    const nowSeconds = Math.floor(now.getTime() / 1000);
+    if (Math.abs(nowSeconds - timestamp) > TIMESTAMP_TOLERANCE_SECONDS)
+        return false;
+    const expected = createHmac("sha256", secret)
+        .update(`${timestamp}.${rawBody}`)
+        .digest("hex");
+    // `timingSafeEqual` throws on a length mismatch, and a wrong-length hex
+    // string is exactly what a probe looks like - so lengths are compared
+    // first and only equal-length buffers reach it.
+    if (presented.length !== expected.length)
+        return false;
+    return timingSafeEqual(Buffer.from(presented, "utf8"), Buffer.from(expected, "utf8"));
+}
+/**
+ * A ready-made `POST` route for Connect's webhooks.
+ *
+ * ```ts
+ * export const POST = createConnectWebhookHandler({
+ *   secret: process.env.CONNECT_WEBHOOK_SECRET!,
+ *   on: {
+ *     "workspace.deletion_scheduled": ({ workspaceId, purgeAfter }) =>
+ *       freeze(workspaceId, purgeAfter),
+ *     "workspace.deletion_cancelled": ({ workspaceId }) => unfreeze(workspaceId),
+ *     "workspace.deleted": ({ workspaceId }) => purge(workspaceId),
+ *   },
+ * })
+ * ```
+ *
+ * Three behaviours worth knowing, because each of them is a decision rather
+ * than an accident:
+ *
+ * **An unverified request gets a 401 and nothing else happens.** No parsing,
+ * no logging of the body, no handler. The endpoint is a public URL, so
+ * anything reachable before the signature check is reachable by anyone.
+ *
+ * **An unhandled event type is a 200.** Connect adds event types over time,
+ * and answering 4xx to one you have not written code for would dead-letter
+ * it immediately and, after enough of them, disable your endpoint. Silence
+ * is the correct answer to "we do not care about this one".
+ *
+ * **A throwing handler produces a 500, on purpose.** That is what makes
+ * Connect retry. Swallowing the error would acknowledge an event you failed
+ * to process, and the retry ladder is the only thing standing between a
+ * transient failure and a permanently missed deletion.
+ *
+ * Delivery is at-least-once and unordered. Dedupe on `envelope.id`, and
+ * reconcile against the readiness endpoint rather than trusting arrival
+ * order - the pull channel is authoritative, this one is fast.
+ */
+export function createConnectWebhookHandler(options) {
+    return async function POST(request) {
+        // Read as text and verify before parsing. `JSON.stringify(await
+        // request.json())` is not the same string that was signed - key order and
+        // number formatting both differ - so a handler that parses first can
+        // never verify.
+        const rawBody = await request.text();
+        const signature = request.headers.get(SIGNATURE_HEADER);
+        if (!verifyConnectWebhook(rawBody, signature, options.secret)) {
+            return new Response("Invalid signature", { status: 401 });
+        }
+        let envelope;
+        try {
+            envelope = JSON.parse(rawBody);
+        }
+        catch {
+            // Signed by us and still unparseable is not something a retry fixes.
+            return new Response("Malformed payload", { status: 400 });
+        }
+        const handler = options.on[envelope.type];
+        if (!handler)
+            return new Response(null, { status: 200 });
+        try {
+            await handler(envelope.data, envelope);
+        }
+        catch (error) {
+            if (options.onError) {
+                await options.onError(error, envelope);
+            }
+            else {
+                console.error(`Connect webhook ${envelope.type} (${envelope.id}) failed:`, error);
+            }
+            // Deliberately a 500: it is what makes Connect retry. See the doc above.
+            return new Response("Handler failed", { status: 500 });
+        }
+        return new Response(null, { status: 200 });
+    };
+}

package/dist/esm/types.js

@@ -1,5 +1,5 @@
 /**
- * Wire types for the `/api/v1/service/*` surface - the service-partner API,
+ * Wire types for the `/api/v1/application/*` surface - the application-partner API,
  * and the only thing this SDK covers.
  *
  * Hand-written rather than generated so the published package carries no

package/dist/theme.css

@@ -50,6 +50,31 @@
   --separator: oklch(92% 0.0067 145.67);
   --surface: oklch(100% 0.0034 145.67);
   --surface-secondary: oklch(94% 0.0067 145.67);
+  /*
+   * The neutral ramp every `secondary`/`tertiary` Button and every default
+   * Chip actually paints with - `.button--tertiary` resolves to
+   * `--button-bg: var(--default)`, not to `--surface`.
+   *
+   * Defining these is the difference between "the palette below is the
+   * palette" and it merely being most of it. Left out, `--default` and
+   * `--surface-tertiary` keep @heroui/styles' stock values, which sit at
+   * hue 286 - a cool blue-grey - while every token below is hue 145.67, a
+   * warm green-grey. The two ramps are near-neutral enough that neither
+   * reads as "blue" or "green" on its own, and precisely similar enough
+   * that a grey button next to a grey panel reads as an accident. In dark
+   * mode they also disagreed on lightness (27.4% against a 25% panel), so
+   * a tertiary button sat a step *above* the panel containing it.
+   *
+   * Lightness is kept at HeroUI's stock values so component relationships
+   * are unchanged; only the hue is brought onto the ramp.
+   *
+   * Everything ending in `-soft`, plus `--default-hover`/`--default-foreground`,
+   * is derived by @heroui/styles via `color-mix` from the base token, so
+   * those follow from these and must NOT be redefined here - hardcoding one
+   * pins it and stops it tracking a partner's override.
+   */
+  --default: oklch(94% 0.0067 145.67);
+  --surface-tertiary: oklch(93.73% 0.0067 145.67);
   --danger: oklch(65.32% 0.2359 12.76);
   --danger-foreground: oklch(99.11% 0 0);
   --warning: oklch(79% 0.16 76);
@@ -70,6 +95,9 @@
   --separator: oklch(26% 0.0067 145.67);
   --surface: oklch(21% 0.0067 145.67);
   --surface-secondary: oklch(25% 0.0067 145.67);
+  /* See the light block above. */
+  --default: oklch(27.4% 0.0067 145.67);
+  --surface-tertiary: oklch(27.21% 0.0067 145.67);
   --danger: oklch(65.32% 0.2359 12.76);
   --danger-foreground: oklch(99.11% 0 0);
   --warning: oklch(79% 0.16 76);

package/dist/types/client/components/access-gate.d.ts

@@ -0,0 +1,79 @@
+import type { ReactNode } from "react";
+import type { ReadinessBlocker } from "../../types.js";
+export type ConnectAccessGateState = "loading"
+/** No signed-in user - not this component's concern, see the doc comment on `ConnectAccessGate`. */
+ | "signed_out"
+/** `workspace_suspended` - a platform admin took this workspace offline. Hard block, no dismiss. */
+ | "suspended"
+/** `subscription_missing` - nothing to subscribe to yet. Hard block. */
+ | "no_subscription"
+/** `onboarding_approval_pending` - waiting on a reviewer. Hard block, no action to offer. */
+ | "onboarding_pending"
+/** Any other `blocking` readiness code (verification, audience, seats, ...). Hard block. */
+ | "blocked"
+/** `payment_retry_pending` - an automatic dunning retry is scheduled. Not blocking - `children` still render. */
+ | "payment_retry"
+/** Nothing outstanding. */
+ | "clear";
+export interface ConnectAccessGateResult {
+    state: ConnectAccessGateState;
+    /** The blocker driving a hard-block state (`suspended`/`no_subscription`/`onboarding_pending`/`blocked`). `null` otherwise. */
+    blocker: ReadinessBlocker | null;
+    /** The `payment_retry_pending` blocker, only when `state === "payment_retry"`. Carries `graceEndsAt`. */
+    paymentRetry: ReadinessBlocker | null;
+}
+/**
+ * The single composed answer to "can this workspace use my app right now,
+ * and if not, which of the four things is it": choose a plan, wait on
+ * approval, resolve an overdue payment, or - a suspended workspace - none of
+ * the above, because nothing short of a platform admin fixes that one.
+ *
+ * Reuses the existing single sources of truth rather than re-deriving them:
+ * `blockingBlockers()` (`helpers.ts`) for severity, the same readiness read
+ * `ConnectReadinessGate`/`ConnectReadinessBanner` already use. `ConnectAccessGate`
+ * is a priority ordering over the same data, not a second opinion about it.
+ *
+ * Priority, first match wins: `suspended` > `no_subscription` >
+ * `onboarding_pending` > any other blocking code (`blocked`) >
+ * `payment_retry` (advisory - `children` still render) > `clear`.
+ */
+export declare function useConnectAccessGate(): ConnectAccessGateResult;
+export interface ConnectAccessGateProps {
+    children: ReactNode;
+    /** Replaces the default card for every hard-block state (`suspended`/`no_subscription`/`onboarding_pending`/`blocked`) uniformly. For a different card per state, call `useConnectAccessGate()` directly instead. */
+    fallback?: ReactNode;
+    /** Shown while the first read is in flight. */
+    loading?: ReactNode;
+    className?: string;
+}
+/**
+ * Wrap your app's content once - typically in your root layout, alongside
+ * (not instead of) your own header/nav - and it renders exactly one of: the
+ * hard-block card for a suspended workspace, one with no plan, or one
+ * waiting on approval; your `children` plus a dismissible payment-due banner
+ * during an automatic dunning retry; or just `children` once everything is
+ * clear.
+ *
+ * **Do not wrap your own plans/pricing page with this.** The `no_subscription`
+ * card's button sends someone to Connect's subscribe page directly (see
+ * `GateCard`'s doc comment on why - it used to link to your in-app `/plans`
+ * instead, which is a dead end once this gate hides that very page too), but
+ * a customer can still navigate to your plans page on their own (a nav link,
+ * a bookmark) and must actually see it there. Since the gate is mounted once
+ * around every route, carving out that exception is your router's job, not
+ * a prop on this component: check the current path in your layout/shell and
+ * skip wrapping `children` in `<ConnectAccessGate>` for that one route.
+ *
+ * **Signed-out renders `children`, not a fallback** - deliberately different
+ * from `ConnectReadinessGate`/`ConnectSubscriptionGate`, which show nothing
+ * until signed in. None of the four states this component composes is a
+ * property of a signed-out visitor, and a component mounted around your
+ * entire app must not hide a public landing page behind an empty gate. Your
+ * own sign-in flow decides what a signed-out visitor sees.
+ *
+ * **This is a UX gate, not a security boundary** - same caveat as every
+ * other gate in this package. The authoritative check is
+ * `client.entitlements.getReadiness` on your server, before you do the
+ * thing.
+ */
+export declare function ConnectAccessGate({ children, fallback, loading, className }: ConnectAccessGateProps): import("react").JSX.Element;

package/dist/types/client/components/account-sessions.d.ts

@@ -10,7 +10,7 @@ export interface ConnectAccountSessionsProps {
 }
 /**
  * Every device signed into this Connect account - not scoped to this
- * service, see `ConnectUserSession`'s doc comment. Owns the one
+ * application, see `ConnectUserSession`'s doc comment. Owns the one
  * `useConnectSessions()` call for this modal; every revoke action here
  * mutates through it and re-reads the list itself, since nothing else
  * invalidates it automatically - see `mutateResource`'s doc comment.

package/dist/types/client/components/app-shell.d.ts

@@ -0,0 +1,115 @@
+import { type ReactNode } from "react";
+import { type ConnectLinkRenderer, type ConnectNav } from "./nav.js";
+import type { ThemeMode } from "../../types.js";
+export interface ConnectAppShellProps {
+    /** This application's name, in the `cosmo·ops VOICE` lockup. See `ConnectLogo`. */
+    name: string;
+    /** This application's glyph, drawn on the CosmoOps badge. Falls back to the Connect rings. */
+    icon?: ReactNode;
+    /** Where the lockup links. Defaults to `/`. */
+    homeHref?: string;
+    /** The sidebar's destinations - items, sections, or a mix. See `ConnectNav`. */
+    nav: ConnectNav;
+    /** Current path. Pass `usePathname()` in Next; see `ConnectSideNavProps.activePath`. */
+    activePath?: string;
+    /** See `ConnectLinkRenderer` - how this app renders a link. Defaults to a plain `<a>`. */
+    renderLink?: ConnectLinkRenderer;
+    /**
+     * Page heading in the top bar. A string renders as the page's `<h1>`, so
+     * don't also put one at the top of the page; pass a node for breadcrumbs or
+     * anything else.
+     */
+    title?: ReactNode;
+    /** Your own controls in the top bar, left of the Connect ones. */
+    headerActions?: ReactNode;
+    /** Extra content pinned to the bottom of the sidebar, above the fold-away. */
+    sidebarFooter?: ReactNode;
+    /** Rendered below `children`, inside the scrolling content pane. */
+    footer?: ReactNode;
+    /** Start the rail collapsed. Ignored when `collapsed` is supplied. */
+    defaultCollapsed?: boolean;
+    /** Drive the rail yourself. Supply `onCollapsedChange` with it. */
+    collapsed?: boolean;
+    onCollapsedChange?: (collapsed: boolean) => void;
+    /** Remove the collapse control and pin the rail expanded. */
+    collapsible?: boolean;
+    /** The app launcher in the top bar. On by default. */
+    showAppsGrid?: boolean;
+    /** "Continue with Connect" / "Create account" in the top bar when signed out. On by default. */
+    showAuthButtons?: boolean;
+    /** Passed to `ConnectUserMenu` - the SDK has no theme provider, so this is host-controlled. */
+    theme?: ThemeMode;
+    onThemeChange?: (theme: ThemeMode) => void;
+    /**
+     * Wrap `children` in `ConnectAccessGate` - suspended, no plan, onboarding
+     * pending, payment due, decided once for the whole app. **On by default**,
+     * because the shell is exactly the "wrap your app content once" place that
+     * gate asks for, and an app that mounts a shell and forgets the gate is an
+     * app that lets a suspended workspace keep working.
+     *
+     * The chrome is never gated: the sidebar, the lockup, the user menu and
+     * sign-out stay reachable in every blocked state, so a blocked customer can
+     * always get to the page that unblocks them.
+     *
+     * Routes flagged `gateExempt` on their nav item render outside it - see
+     * `ConnectNavItem.gateExempt` and `gateExemptRoutes`.
+     */
+    gate?: boolean;
+    /**
+     * Extra ungated paths, on top of the ones flagged `gateExempt` in `nav`.
+     * For a route that is not in the sidebar at all - a `/checkout/callback`,
+     * say. Prefix-matched, same as the nav's active resolution.
+     */
+    gateExemptRoutes?: string[];
+    className?: string;
+    /** Classes on the scrolling content pane - override the default max-width and padding here. */
+    contentClassName?: string;
+    children: ReactNode;
+}
+/**
+ * The application frame every CosmoOps application platform runs inside: a
+ * collapsible sidebar, a top bar carrying the app launcher and the account
+ * menu, and your pages in the middle.
+ *
+ * This is the piece each partner was otherwise writing by hand, and writing
+ * slightly differently - which is how a family of applications stops looking like
+ * one product. Everything that should be identical across platforms (the
+ * lockup, the rail geometry, the active-route treatment, the launcher, the
+ * account menu, the access gate) lives here; everything that genuinely
+ * differs is a prop:
+ *
+ * ```tsx
+ * "use client";
+ * import Link from "next/link";
+ * import { usePathname } from "next/navigation";
+ * import { ConnectAppShell } from "@cosmoops/connect-sdk/client";
+ * import { LayoutDashboard, Truck } from "lucide-react";
+ *
+ * export function Shell({ children }: { children: React.ReactNode }) {
+ *   return (
+ *     <ConnectAppShell
+ *       name="Dispatch"
+ *       icon={<Truck />}
+ *       activePath={usePathname()}
+ *       renderLink={(props) => <Link {...props} />}
+ *       nav={[
+ *         { label: "Overview", href: "/", icon: <LayoutDashboard className="size-5" /> },
+ *         { label: "Plans", href: "/plans", icon: <Truck className="size-5" />, gateExempt: true },
+ *       ]}
+ *     >
+ *       {children}
+ *     </ConnectAppShell>
+ *   );
+ * }
+ * ```
+ *
+ * There is no `isSignedIn` branch anywhere in here, and there should be none
+ * in yours: the auth buttons render nothing once a session exists, the user
+ * menu renders nothing without one, and the launcher renders nothing when
+ * signed out. The swap happens inside the components.
+ *
+ * It renders no provider of its own - mount `ConnectProvider` above it, once,
+ * so a page with a shell, a plan table and a usage meter still makes one
+ * session read.
+ */
+export declare function ConnectAppShell({ name, icon, homeHref, nav, activePath, renderLink, title, headerActions, sidebarFooter, footer, defaultCollapsed, collapsed: controlledCollapsed, onCollapsedChange, collapsible, showAppsGrid, showAuthButtons, theme, onThemeChange, gate, gateExemptRoutes, className, contentClassName, children, }: ConnectAppShellProps): import("react").JSX.Element;

package/dist/types/client/components/apps-grid.d.ts

@@ -6,7 +6,7 @@ export interface ConnectAppsGridProps {
 }
 /**
  * The Google-style app launcher: a grid icon in your top bar that opens a
- * modal of every Connect service this organization can actually open.
+ * modal of every Connect application this workspace can actually open.
  *
  * Only launchable apps appear, so no tile is a dead end - a paused
  * subscription still shows, badged, because a dunning cycle should not make a

package/dist/types/client/components/feature-gate.d.ts

@@ -48,7 +48,7 @@ export interface ConnectFeatureGateProps {
  *
  * Like every gate in this package, it is a **UX gate, not a security
  * boundary**: the entitlement is read through your own origin and the browser
- * can ignore it. Check `client.entitlements.hasFeature(orgId, feature)` on the
+ * can ignore it. Check `client.entitlements.hasFeature(workspaceId, feature)` on the
  * server before doing the thing the feature unlocks.
  *
  * Renders `loading` - not `fallback` - while the answer is unknown, so a paying

package/dist/types/client/components/integrations-modal.d.ts

@@ -0,0 +1,21 @@
+export interface ConnectIntegrationsModalProps {
+    /** Extra classes on the trigger button. */
+    className?: string;
+    /** Trigger label, both visible and for screen readers. */
+    label?: string;
+}
+/**
+ * A grid of every Composio-hosted toolkit this workspace can connect -
+ * Google Calendar, Slack, Twitter/X, whatever a platform admin enabled in
+ * Connect's own Console. Each tile carries its own connect/reconnect/
+ * disconnect action and its own pending state, independent of every other
+ * tile - see the doc comment on `pendingSlug` below for why that matters.
+ *
+ * Not optimistic: a tile stays whatever it already was after "Connect" is
+ * pressed, because the connection isn't settled until Composio's webhook
+ * confirms it - `mutateResource` here only ever gets as far as `pending`
+ * before the browser navigates away to complete the provider's OAuth screen.
+ *
+ * Renders nothing when signed out, same as `ConnectAppsGrid`.
+ */
+export declare function ConnectIntegrationsModal({ className, label }: ConnectIntegrationsModalProps): import("react").JSX.Element | null;