@cosmoops/connect-sdk 0.2.0 → 0.6.0

package/dist/esm/server/handler.js

@@ -101,6 +101,7 @@ export function createConnectHandler(options) {
     const { client, session } = options;
     const defaultRedirect = options.defaultRedirect ?? "/";
     const stateCookieName = options.stateCookieName ?? "connect_oauth_state";
+    const silentCookieName = `${stateCookieName}_silent`;
     const callbackPath = `${basePath}/callback`;
     /**
      * Short-lived, httpOnly, and `SameSite=Lax` - `Strict` would not be sent on
@@ -121,6 +122,32 @@ export function createConnectHandler(options) {
             .filter(Boolean)
             .join("; ");
     }
+    /**
+     * Marks the in-flight round trip as a silent (`prompt=none`) one, so the
+     * callback can tell a *probe that found nobody* from a *sign-in that
+     * failed*. The two arrive as the identical `error=login_required`, and they
+     * need opposite handling - see the callback.
+     *
+     * A cookie of its own rather than a flag folded into the state cookie:
+     * that one is parsed by splitting on `:` with the destination URL rejoined
+     * from the remainder, so smuggling a third field through it is exactly the
+     * kind of encoding trick that breaks the first time a `next` URL contains
+     * something unexpected. Same attributes and lifetime as the state cookie
+     * it travels beside.
+     */
+    function silentCookie(value, secure) {
+        const cleared = value === "";
+        return [
+            `${silentCookieName}=${encodeURIComponent(value)}`,
+            `Path=${basePath}`,
+            "HttpOnly",
+            "SameSite=Lax",
+            secure ? "Secure" : "",
+            cleared ? "Max-Age=0" : "Max-Age=900",
+        ]
+            .filter(Boolean)
+            .join("; ");
+    }
     async function requireToken(request) {
         const token = await session.read(request);
         if (!token) {
@@ -166,6 +193,37 @@ export function createConnectHandler(options) {
             const { user } = await whoami(request);
             return json({ apps: await client.apps.list(user.organizationId) });
         },
+        "GET /integrations": async (request) => {
+            const { user } = await whoami(request);
+            return json({ toolkits: await client.integrations.list(user.organizationId) });
+        },
+        "POST /integrations/connect": async (request) => {
+            const { user } = await whoami(request);
+            const body = (await request.json().catch(() => null));
+            if (!body?.toolkitSlug || !body?.returnUrl) {
+                throw new ConnectError({
+                    status: 400,
+                    code: "validation_error",
+                    message: "toolkitSlug and returnUrl are required",
+                    endpoint: "POST /integrations/connect",
+                });
+            }
+            return json(await client.integrations.initiateConnect(user.organizationId, body.toolkitSlug, body.returnUrl));
+        },
+        "POST /integrations/disconnect": async (request) => {
+            const { user } = await whoami(request);
+            const body = (await request.json().catch(() => null));
+            if (!body?.toolkitSlug) {
+                throw new ConnectError({
+                    status: 400,
+                    code: "validation_error",
+                    message: "toolkitSlug is required",
+                    endpoint: "POST /integrations/disconnect",
+                });
+            }
+            await client.integrations.disconnect(user.organizationId, body.toolkitSlug);
+            return json({ ok: true });
+        },
         // Account-wide, not scoped to this service - see `SessionsResource`'s
         // doc comment. `requireToken` alone identifies the caller; the target
         // `sessionId` on the revoke routes travels in the JSON body, not the
@@ -205,14 +263,19 @@ export function createConnectHandler(options) {
             const secure = url.protocol === "https:";
             const state = createState();
             const next = safeRedirect(url.searchParams.get("next"), defaultRedirect);
+            const requestedPrompt = url.searchParams.get("prompt");
+            const prompt = requestedPrompt === "create" || requestedPrompt === "none" ? requestedPrompt : undefined;
             const authorizeUrl = client.identity.authorizeUrl({
                 redirectUri: `${url.origin}${callbackPath}`,
                 state,
-                ...(url.searchParams.get("prompt") === "create" ? { prompt: "create" } : {}),
+                ...(prompt ? { prompt } : {}),
             });
             // State and destination travel together in one cookie so the callback
             // cannot end up with one and not the other.
-            return redirect(authorizeUrl, [stateCookie(`${state}:${next}`, secure)]);
+            const cookies = [stateCookie(`${state}:${next}`, secure)];
+            if (prompt === "none")
+                cookies.push(silentCookie("1", secure));
+            return redirect(authorizeUrl, cookies);
         },
         /**
          * The other end of the round trip. Verifies `state`, exchanges the code,
@@ -229,10 +292,29 @@ export function createConnectHandler(options) {
             if (!cookieState || !sameState(cookieState, returnedState)) {
                 // Either a forged callback or a genuinely stale tab. Neither should
                 // mint a session, and neither is worth an error page.
-                return redirect(`${next}${next.includes("?") ? "&" : "?"}connect_error=state_mismatch`, [clearState]);
+                return redirect(`${next}${next.includes("?") ? "&" : "?"}connect_error=state_mismatch`, [
+                    clearState,
+                    silentCookie("", secure),
+                ]);
             }
+            const wasSilent = readCookie(request, silentCookieName) === "1";
+            const clearSilent = silentCookie("", secure);
             const error = url.searchParams.get("error");
             if (error) {
+                // A silent (`prompt=none`) probe that came back empty-handed. All
+                // three of its outcomes mean the same thing to the app - "carry on
+                // signed out" - so it returns to `next` quietly: no retry, and no
+                // `connect_error`, because nothing went wrong.
+                //
+                // Getting this wrong is not subtle. The retry below fires on exactly
+                // the `login_required` a silent probe returns, so without this branch
+                // every silent attempt for a signed-out visitor would escalate itself
+                // into a full interactive sign-in redirect - turning "quietly check
+                // if they're already here" into "force everyone to log in", which is
+                // the precise opposite of the feature.
+                if (wasSilent) {
+                    return redirect(next, [clearState, clearSilent]);
+                }
                 // `login_required` is normal traffic, not a fault: a new account gets
                 // pulled out to their inbox to verify, and the ~15 minute request
                 // expires before they return. Connect has already signed them in, so
@@ -242,15 +324,16 @@ export function createConnectHandler(options) {
                     const retry = new URL(`${url.origin}${basePath}/signin`);
                     retry.searchParams.set("next", next);
                     retry.searchParams.set("connect_retry", "1");
-                    return redirect(retry.toString(), [clearState]);
+                    return redirect(retry.toString(), [clearState, clearSilent]);
                 }
                 return redirect(`${next}${next.includes("?") ? "&" : "?"}connect_error=${encodeURIComponent(error)}`, [
                     clearState,
+                    clearSilent,
                 ]);
             }
             const code = url.searchParams.get("code");
             if (!code) {
-                return redirect(`${next}${next.includes("?") ? "&" : "?"}connect_error=missing_code`, [clearState]);
+                return redirect(`${next}${next.includes("?") ? "&" : "?"}connect_error=missing_code`, [clearState, clearSilent]);
             }
             const result = await client.identity.exchangeCode({
                 code,
@@ -259,7 +342,7 @@ export function createConnectHandler(options) {
             // Verified before the session is stored, not after - an unverifiable
             // token must never become a signed-in user.
             await client.identity.verifyIdToken(result.idToken);
-            const response = redirect(next, [clearState]);
+            const response = redirect(next, [clearState, clearSilent]);
             await session.write(request, response, result.sessionToken);
             return response;
         },

package/dist/esm/server/index.js

@@ -8,3 +8,8 @@
 export { ConnectClient, DEFAULT_BASE_URL, SDK_VERSION } from "./client.js";
 export { createConnectHandler } from "./handler.js";
 export { createState } from "./resources/identity.js";
+/**
+ * Webhook verification and a ready-made POST route. Server-only for the
+ * obvious reason: the signing secret must never reach a browser bundle.
+ */
+export { createConnectWebhookHandler, verifyConnectWebhook, } from "./webhooks.js";

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

@@ -0,0 +1,62 @@
+import { request } from "../http.js";
+/**
+ * Your service's own analytics: emit product events, and read back the daily
+ * numbers Connect aggregates from them.
+ *
+ * There is no way to name a service in either call. The scope is always the one
+ * your API key belongs to - that is the endpoint's security model, not an
+ * omission.
+ */
+export class AnalyticsResource {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /**
+     * Daily series for the requested metrics, up to 90 days.
+     *
+     * **Throws on failure**, unlike `emit` below. A read whose result you are
+     * about to render has to be able to say "I could not load"; silently
+     * returning an empty series would draw a chart of zeroes.
+     */
+    async series(query) {
+        const params = new URLSearchParams({
+            metrics: query.metrics.join(","),
+            from: query.from,
+            to: query.to,
+        });
+        return request(this.transport, {
+            method: "GET",
+            path: `/analytics?${params.toString()}`,
+        });
+    }
+    /**
+     * Never throws - the same judgement `LogsResource.write` makes, for the same
+     * reason: telemetry that takes down the code path it was observing is worse
+     * than a lost event. A failure is reported through `delivered`.
+     *
+     * Up to 50 events per call. Pass `sessionToken` on an event to attribute it
+     * to the signed-in user; without one it still lands, just unattributed.
+     */
+    async emit(events) {
+        const normalized = events.map((event) => ({
+            ...event,
+            occurredAt: event.occurredAt instanceof Date ? event.occurredAt.toISOString() : event.occurredAt,
+        }));
+        try {
+            const result = await request(this.transport, {
+                method: "POST",
+                path: "/events",
+                json: { events: normalized },
+            });
+            return {
+                delivered: true,
+                accepted: result?.accepted ?? events.length,
+                attributed: result?.attributed ?? 0,
+            };
+        }
+        catch {
+            return { delivered: false, accepted: 0, attributed: 0 };
+        }
+    }
+}

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

@@ -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 service'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, ...) an organization has connected. Connect proxies every call
+ * here - your service 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 organization's connection status for each. */
+    async list(organizationId) {
+        const result = await request(this.transport, {
+            method: "GET",
+            path: "/integrations",
+            query: { organizationId },
+        });
+        // `?? []` 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 org 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(organizationId, toolkitSlug, returnUrl) {
+        return request(this.transport, {
+            method: "POST",
+            path: "/integrations/connect",
+            json: { organizationId, toolkitSlug, returnUrl },
+        });
+    }
+    /** Idempotent - disconnecting a toolkit that was never connected, or is already disconnected, is a success. */
+    async disconnect(organizationId, toolkitSlug) {
+        return request(this.transport, {
+            method: "POST",
+            path: "/integrations/disconnect",
+            json: { organizationId, toolkitSlug },
+        });
+    }
+    /** Calls a Composio action against this organization's connected account for the named toolkit. */
+    async execute(organizationId, input) {
+        return request(this.transport, {
+            method: "POST",
+            path: "/integrations/actions/execute",
+            json: { organizationId, ...input },
+        });
+    }
+}

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

@@ -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 service'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: {
+ *     "organization.deletion_scheduled": ({ organizationId, purgeAfter }) =>
+ *       freeze(organizationId, purgeAfter),
+ *     "organization.deletion_cancelled": ({ organizationId }) => unfreeze(organizationId),
+ *     "organization.deleted": ({ organizationId }) => purge(organizationId),
+ *   },
+ * })
+ * ```
+ *
+ * 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/this-entry-is-server-only.js

@@ -0,0 +1,30 @@
+/**
+ * The module a browser bundle gets if it reaches for `/server` or `/next`.
+ *
+ * Neither entry may run in a browser: both build a `ConnectClient` around
+ * `CONNECT_API_KEY`. Nothing enforced that before - the split was documented
+ * and unguarded, so a client component importing `@cosmoops/connect-sdk/server`
+ * compiled cleanly and failed later, somewhere else, for reasons that did not
+ * mention the import.
+ *
+ * The key itself does not leak: `CONNECT_API_KEY` has no `NEXT_PUBLIC_` prefix,
+ * so Next replaces the read with `undefined` in a client bundle rather than
+ * inlining the secret. What ships is the credential-handling code path and a
+ * client that authenticates with `undefined` - which 401s against Connect and
+ * looks like a server bug. This turns that into a build-time failure naming the
+ * entry to import instead.
+ *
+ * Wired through the `browser` export condition, which Next's client compiler
+ * resolves and its server, RSC and SSR passes do not - so the same import stays
+ * legal in a Route Handler, a Server Component and a non-Next backend.
+ *
+ * The filename is the error message. A bundler reaches this module while
+ * resolving a *named* import, so it reports "no matching export" and never
+ * evaluates the throw below - the path is the only part of that error carrying
+ * any meaning, so the path has to say what went wrong. The throw still covers
+ * side-effect, default and namespace imports, which do evaluate it.
+ */
+throw new Error('@cosmoops/connect-sdk: "@cosmoops/connect-sdk/server" and "@cosmoops/connect-sdk/next" hold your CONNECT_API_KEY and cannot be imported from browser code.\n' +
+    'Import "@cosmoops/connect-sdk/client" instead - its components and hooks call your own origin, and the bridge route reaches Connect for them.\n' +
+    'For types only, import from "@cosmoops/connect-sdk" (isomorphic) or use `import type`, which erases at compile time.');
+export {};

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/cli/doctor.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `npx @cosmoops/connect-sdk doctor` - checks a wired-up project for the
+ * mistakes that `init` cannot prevent.
+ *
+ * `init` writes the two files it owns. Everything else in the setup is a step
+ * someone performs by hand in a file this package must not rewrite - the
+ * provider goes into a layout somebody else wrote, the theme import goes into
+ * their stylesheet in a specific position, and the redirect URI lives in
+ * Connect rather than in the repo. Those are where setup actually breaks, and
+ * each one fails in a way that does not name its cause: a missing provider
+ * throws from a hook, a mis-ordered theme import silently loses to HeroUI's
+ * defaults, and an unregistered redirect URI only shows up as an OAuth error
+ * after a round trip to Connect.
+ *
+ * Deliberately offline. Connect exposes no endpoint that lists a client's
+ * registered redirect URIs, so there is nothing to check remotely that would
+ * justify the cost - and an offline check needs no credentials, which is what
+ * lets this run in CI on a pull request.
+ *
+ * The exit code is the point: `fail` means the app is broken and returns 1,
+ * `warn` means this cannot tell from the outside and returns 0.
+ */
+export declare function runDoctor(argv?: string[]): number;

package/dist/types/cli/init.d.ts

@@ -22,11 +22,10 @@
  */
 export declare function runInit(argv?: string[]): number;
 /**
- * Only `init` today. Parsed as a subcommand anyway so adding `doctor` or
- * `check` later does not change how the existing one is invoked.
+ * `init` writes the wiring; `doctor` checks the parts `init` cannot write.
  *
  * A bare path runs `init` against it, so both `connect-sdk init ./my-app` and
- * `connect-sdk ./my-app` work. A first argument that is neither the command nor
+ * `connect-sdk ./my-app` work. A first argument that is neither a command nor
  * an existing directory is a typo, and saying so beats reporting that
  * `./innit` contains no App Router - which is true, unhelpful, and points at
  * the wrong mistake.

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"
+/** `organization_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;