@cosmoops/connect-sdk 0.1.0

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

@@ -0,0 +1,47 @@
+/**
+ * Browser half of `@cosmoops/connect-sdk` - React components and hooks.
+ *
+ * Holds no credential. Everything here talks to your own origin, where
+ * `createConnectHandler` from `@cosmoops/connect-sdk/server` holds the API key
+ * and reaches Connect.
+ *
+ * Styling is HeroUI v3 semantic tokens only (`accent`, `muted`, `surface`,
+ * `separator`, ...), never a hardcoded colour - so these components inherit
+ * whatever theme the host service platform already configured, and one theme
+ * change lands identically in all of them.
+ */
+export { ConnectProvider, useConnect, useConnectUser, useConnectEntitlements, useConnectPlans, useConnectApps, useConnectAddonUsage, useConnectSessions, useConnectResource, CONNECT_APP_URL, } from "./provider.js";
+export type { ConnectProviderProps, ConnectContextValue, ConnectSession } from "./provider.js";
+export { blockingBlockers, normalizePlanFeatures } from "../helpers.js";
+export type { WirePlanFeature } from "../helpers.js";
+export { ConnectError, isConnectError } from "../errors.js";
+export type * from "../types.js";
+export { ConnectMark } from "./mark.js";
+export { ConnectLogo } from "./components/logo.js";
+export type { ConnectLogoProps } from "./components/logo.js";
+export { ConnectLoginButton, ConnectRegisterButton } from "./components/auth-buttons.js";
+export type { ConnectAuthButtonProps } from "./components/auth-buttons.js";
+export { ConnectUserMenu, ConnectManageSubscriptionButton, ConnectInvoicesButton, ConnectProfileButton, ConnectHomeButton, ConnectSignOutButton, } from "./components/user-menu.js";
+export { ConnectAccountSessions } from "./components/account-sessions.js";
+export type { ConnectAccountSessionsProps } from "./components/account-sessions.js";
+export type { ConnectUserMenuProps } from "./components/user-menu.js";
+export { ConnectAppsGrid } from "./components/apps-grid.js";
+export type { ConnectAppsGridProps } from "./components/apps-grid.js";
+export { ConnectPlans } from "./components/plans.js";
+export type { ConnectPlansProps } from "./components/plans.js";
+export { ConnectSubscribeDialog } from "./components/subscribe-dialog.js";
+export type { ConnectSubscribeDialogProps } from "./components/subscribe-dialog.js";
+export { ConnectSubscriptionGate, ConnectNoSubscriptionCard, ConnectSubscriptionCard, ConnectTrialBanner, ConnectSeatUsage, resolveSubscriptionState, } from "./components/subscription.js";
+export type { ConnectSubscriptionGateProps, ConnectNoSubscriptionCardProps, ConnectSubscriptionCardProps, ConnectTrialBannerProps, ConnectSubscriptionState, } from "./components/subscription.js";
+export { ConnectReadinessBanner, ConnectReadinessGate } from "./components/readiness.js";
+export type { ConnectReadinessBannerProps, ConnectReadinessGateProps } from "./components/readiness.js";
+export { ConnectFeatureGate, useConnectFeature } from "./components/feature-gate.js";
+export type { ConnectFeatureGateProps } from "./components/feature-gate.js";
+export { ConnectUsageMeter } from "./components/usage-meter.js";
+export type { ConnectUsageMeterProps } from "./components/usage-meter.js";
+export { ConnectPlansPage } from "./components/plans-page.js";
+export type { ConnectPlansPageProps } from "./components/plans-page.js";
+export { useConnectCheckout, buildCheckoutUrl } from "./use-checkout.js";
+export type { ConnectCheckoutStatus, ConnectCheckoutState, ConnectEntitlements, StartCheckoutOptions, CheckoutUrlOptions, } from "./use-checkout.js";
+export { formatPrice, monthlyOf, resolveAction, annualSaving, discountLabel, ACTION_LABEL, groupPlansByTier, resolvePlanGroup, } from "./components/plan-pricing.js";
+export type { PlanAction, PlanTier, ComparablePlan } from "./components/plan-pricing.js";

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

@@ -0,0 +1,11 @@
+/**
+ * The Connect mark - concentric rings on a solid accent badge.
+ *
+ * Painted from `--accent` / `--accent-foreground`, the same HeroUI tokens the
+ * host app themes, so the badge tracks whatever palette a service platform has
+ * configured rather than carrying a hardcoded CosmoOps green into someone
+ * else's brand.
+ */
+export declare function ConnectMark({ className }: Readonly<{
+    className?: string;
+}>): import("react").JSX.Element;

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

@@ -0,0 +1,209 @@
+import type { ReactNode } from "react";
+import type { AddonUsageResponse, ConnectUser, OrganizationApp, PlansResponse, ReadinessResponse, ServiceRole, SessionsListResponse, SessionSubscription, SubscriptionResponse } from "../types.js";
+export declare const CONNECT_APP_URL = "https://connect.cosmoops.com";
+export interface ConnectSession {
+    user: ConnectUser | null;
+    subscription: SessionSubscription | null;
+    serviceRole: ServiceRole | null;
+}
+export interface ConnectContextValue {
+    /** Public OAuth client id. Safe in a browser - it goes in the authorize URL. */
+    clientId: string;
+    /** Connect's own origin, for deep links out to Profile, Billing and the catalog. */
+    appUrl: string;
+    session: ConnectSession | null;
+    /** `true` until the first `/session` read settles. Render skeletons, not a Login button. */
+    isLoading: boolean;
+    error: string | null;
+    signIn(options?: {
+        prompt?: "create";
+    }): void;
+    signOut(): Promise<void>;
+    refresh(): Promise<void>;
+    /** GET through the bridge, relative to `basePath`. Shared cache, deduped in flight. */
+    fetchResource<T>(path: string): Promise<T>;
+    /**
+     * POST through the bridge, relative to `basePath`. Unlike `signOut`
+     * (which deliberately swallows a failed logout so the local UI doesn't
+     * hang on a Connect outage), this throws on a non-2xx response - a caller
+     * mutating state needs to know when it didn't take.
+     *
+     * Evicts only `path`'s own cache entry, not the whole shared cache - a
+     * blunt full clear would break `fetchResource`'s in-flight dedup for
+     * every *other* resource mounted on the same page. A component that reads
+     * `path` through `useConnectResource` still needs to call that hook's own
+     * `refetch()` afterward; clearing the cache entry alone does not re-render
+     * anything by itself.
+     */
+    mutateResource<T>(path: string, body?: unknown): Promise<T>;
+    /**
+     * Drops one path's cached read so the next `fetchResource` for it goes to
+     * the bridge again.
+     *
+     * `useConnectResource`'s own `refetch()` is not enough on its own: it bumps
+     * a version counter to re-run that hook's effect, and the effect calls
+     * `fetchResource`, which hands back the *same* cached promise. That is
+     * correct after a `mutateResource` (which evicts the entry itself), but a
+     * caller polling for a change made somewhere else entirely - a checkout
+     * completed in a Connect tab, say - has no mutation to piggyback on. So
+     * invalidate, then refetch.
+     *
+     * Scoped to one path for the same reason `mutateResource` is: clearing the
+     * whole cache would break in-flight dedup for every other resource on the
+     * page.
+     */
+    invalidateResource(path: string): void;
+}
+export interface ConnectProviderProps {
+    /**
+     * This service's public `client_id`, from its Setup tab in Connect.
+     *
+     * Optional in Next.js, where it falls back to `NEXT_PUBLIC_CONNECT_CLIENT_ID`
+     * - inlined at build time, so `<ConnectProvider>` needs no props at all.
+     * Pass it explicitly anywhere that variable does not exist.
+     */
+    clientId?: string;
+    /** Where `createConnectHandler` is mounted in your app. Must match its `basePath`. */
+    basePath?: string;
+    /**
+     * Where Connect sends the user back after sign-in. Your own callback route,
+     * not a Connect URL - it is your backend that exchanges the code.
+     */
+    redirectUri?: string;
+    /** Override for non-production Connect instances. */
+    appUrl?: string;
+    /**
+     * Replace the `fetch` used to reach your bridge. The browser-side twin of
+     * `ConnectClientOptions.fetch` - it exists so Storybook and tests can drive
+     * the real provider against canned responses instead of monkey-patching
+     * `window.fetch`, which is a render-time global mutation and races with
+     * child effects.
+     */
+    fetch?: (input: string, init?: RequestInit) => Promise<Response>;
+    children: ReactNode;
+}
+/**
+ * Wraps the part of your app that shows Connect UI.
+ *
+ * Holds one session read, shared by every component below it, so a page with a
+ * user menu, an apps grid and a plan table makes one request rather than three.
+ * There is no API key here and there cannot be: everything goes to your own
+ * origin, where `createConnectHandler` holds the credential.
+ *
+ * ```tsx
+ * // Next.js - clientId comes from NEXT_PUBLIC_CONNECT_CLIENT_ID
+ * <ConnectProvider>
+ *   <App />
+ * </ConnectProvider>
+ * ```
+ */
+export declare function ConnectProvider({ clientId, basePath, redirectUri, appUrl, fetch: fetchImpl, children, }: ConnectProviderProps): import("react").JSX.Element;
+export declare function useConnect(): ConnectContextValue;
+/** The signed-in user, or `null`. Sugar over `useConnect().session`. */
+export declare function useConnectUser(): ConnectUser | null;
+/** Readiness gates and the live subscription, fetched on first use. */
+export declare function useConnectEntitlements(): {
+    data: {
+        readiness: ReadinessResponse;
+        subscription: SubscriptionResponse;
+    } | null;
+    isLoading: boolean;
+    error: string | null;
+    /**
+     * Forces a fresh read - the provider's cache clears the mutated path's
+     * entry on a successful `mutateResource` call, but nothing re-triggers
+     * this hook's own effect on its own (none of its dependencies change from
+     * a cache write nobody here observes). Call this right after a
+     * `mutateResource` you made against the same `path` completes.
+     */
+    refetch(): void;
+};
+/**
+ * What is left of every consumable add-on on this workspace's subscription.
+ *
+ * The read half of `client.billing.consumeAddon` - a service that meters its
+ * own end users had no way to show them what remained until this existed.
+ * Empty `addons` means there is nothing to meter, which is not an error.
+ */
+export declare function useConnectAddonUsage(): {
+    data: AddonUsageResponse | null;
+    isLoading: boolean;
+    error: string | null;
+    /**
+     * Forces a fresh read - the provider's cache clears the mutated path's
+     * entry on a successful `mutateResource` call, but nothing re-triggers
+     * this hook's own effect on its own (none of its dependencies change from
+     * a cache write nobody here observes). Call this right after a
+     * `mutateResource` you made against the same `path` completes.
+     */
+    refetch(): void;
+};
+/** This service's plan catalog. */
+export declare function useConnectPlans(): {
+    data: PlansResponse | null;
+    isLoading: boolean;
+    error: string | null;
+    /**
+     * Forces a fresh read - the provider's cache clears the mutated path's
+     * entry on a successful `mutateResource` call, but nothing re-triggers
+     * this hook's own effect on its own (none of its dependencies change from
+     * a cache write nobody here observes). Call this right after a
+     * `mutateResource` you made against the same `path` completes.
+     */
+    refetch(): void;
+};
+/** The apps this organization can open. */
+export declare function useConnectApps(): {
+    data: {
+        apps: OrganizationApp[];
+    } | null;
+    isLoading: boolean;
+    error: string | null;
+    /**
+     * Forces a fresh read - the provider's cache clears the mutated path's
+     * entry on a successful `mutateResource` call, but nothing re-triggers
+     * this hook's own effect on its own (none of its dependencies change from
+     * a cache write nobody here observes). Call this right after a
+     * `mutateResource` you made against the same `path` completes.
+     */
+    refetch(): void;
+};
+/**
+ * This Connect account's own login sessions - account-wide, not scoped to
+ * this service, see `SessionsListResponse`'s doc comment. The component
+ * that calls this is also the one that must own any revoke actions and call
+ * the returned `refetch()` afterward - see `mutateResource`'s doc comment
+ * for why nothing does that automatically.
+ */
+export declare function useConnectSessions(): {
+    data: SessionsListResponse | null;
+    isLoading: boolean;
+    error: string | null;
+    /**
+     * Forces a fresh read - the provider's cache clears the mutated path's
+     * entry on a successful `mutateResource` call, but nothing re-triggers
+     * this hook's own effect on its own (none of its dependencies change from
+     * a cache write nobody here observes). Call this right after a
+     * `mutateResource` you made against the same `path` completes.
+     */
+    refetch(): void;
+};
+/**
+ * One bridge read, shared through the provider's cache.
+ *
+ * Only fetches once a user is known: every resource route needs a session, so
+ * firing before one exists just buys a guaranteed 401.
+ */
+export declare function useConnectResource<T>(path: string): {
+    data: T | null;
+    isLoading: boolean;
+    error: string | null;
+    /**
+     * Forces a fresh read - the provider's cache clears the mutated path's
+     * entry on a successful `mutateResource` call, but nothing re-triggers
+     * this hook's own effect on its own (none of its dependencies change from
+     * a cache write nobody here observes). Call this right after a
+     * `mutateResource` you made against the same `path` completes.
+     */
+    refetch(): void;
+};

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

@@ -0,0 +1,93 @@
+import type { ReadinessResponse, SubscriptionResponse } from "../types.js";
+/**
+ * Where a hand-off to Connect has got to.
+ *
+ * - `idle` - nothing started, or the last one was acknowledged.
+ * - `waiting` - Connect is open and this hook is polling `/entitlements`.
+ * - `completed` - the entitlement actually changed. The only success signal
+ *   worth trusting; see this module's doc comment for why the Connect window
+ *   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.
+ */
+export type ConnectCheckoutStatus = "idle" | "waiting" | "completed" | "abandoned" | "blocked";
+export interface ConnectCheckoutState {
+    status: ConnectCheckoutStatus;
+    /** The Connect URL of the run that produced this state - render it as a fallback link when `status` is `"blocked"`. */
+    url: string | null;
+}
+export interface StartCheckoutOptions {
+    /** Absolute Connect URL to open. Build it with `buildCheckoutUrl`. */
+    url: string;
+    /**
+     * `true` once `/entitlements` reflects the change being waited on.
+     *
+     * Compared against the entitlements read *before* the window opened, so a
+     * predicate is genuinely needed - "the subscription exists" is the right
+     * test for a first subscribe and the wrong one for a plan change, where a
+     * subscription existed all along.
+     */
+    isSettled(entitlements: ConnectEntitlements): boolean;
+}
+export interface ConnectEntitlements {
+    readiness: ReadinessResponse;
+    subscription: SubscriptionResponse;
+}
+/**
+ * Drives a checkout that completes on Connect, not here.
+ *
+ * The partner's page cannot complete a subscription itself - see
+ * `ConnectPlans`' doc comment for why that is deliberate - so the flow is:
+ * open Connect, watch `/entitlements` until the entitlement changes, then
+ * refresh the session so every Connect component on the page repaints.
+ *
+ * **The result is read from Connect's own state, never from the window.**
+ * A closed window proves nothing: the customer may have paid and closed it,
+ * or opened it, thought better of it, and closed it. Polling is what tells
+ * the two apart, which is why the window closing only starts a short grace
+ * period rather than ending the run.
+ */
+export declare function useConnectCheckout(): ConnectCheckoutState & {
+    /** Opens `url` and starts watching. A second call supersedes any run in flight. */
+    start(options: StartCheckoutOptions): void;
+    /** Stops watching and returns to `idle` - for a "Done"/dismiss control. */
+    reset(): void;
+};
+export interface CheckoutUrlOptions {
+    /** Connect's origin, from `useConnect().appUrl`. */
+    appUrl: string;
+    serviceId: string;
+    planId: string;
+    /**
+     * The live subscription's id, when there is one. Present means "change the
+     * plan on this subscription"; absent means "subscribe for the first time" -
+     * and the two are separate screens in Connect, because only one of them can
+     * price proration against a cycle already paid for.
+     */
+    subscriptionId?: string | null;
+    /** Carried into Connect's checkout, where it is validated against the real cart. */
+    coupon?: string | null;
+}
+/**
+ * The Connect URL that cancels a subscription.
+ *
+ * Its own builder rather than a mode on `buildCheckoutUrl`, because it takes
+ * no plan: cancelling is about the subscription, not about what to move it to.
+ * Lands on the same kind of intercepted modal the other two do
+ * (`app/@modal/(.)billing/.../cancel`).
+ */
+export declare function buildCancelUrl({ appUrl, subscriptionId }: {
+    appUrl: string;
+    subscriptionId: string;
+}): string;
+/**
+ * The Connect URL that completes a subscribe or a plan change.
+ *
+ * Both land on a modal Connect renders over the relevant page (an intercepted
+ * parallel route - `app/@modal/(.)services/...` and
+ * `app/@modal/(.)billing/...`), so the customer arrives already looking at the
+ * confirmation for the plan they picked here, not at a catalogue they have to
+ * find it in again.
+ */
+export declare function buildCheckoutUrl({ appUrl, serviceId, planId, subscriptionId, coupon, }: CheckoutUrlOptions): string;

package/dist/types/errors.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Every failure the Connect service API can report, as one class.
+ *
+ * The API speaks two error dialects and this collapses them: the
+ * `/api/v1/service/*` endpoints use `{ error: { code, message } }`, while the
+ * three `/sso/*` ones use OAuth2's `{ error, error_description }` (RFC 6749
+ * §5.2). Both land here with `code` populated, so integrating code branches on
+ * one field either way.
+ */
+export declare class ConnectError extends Error {
+    readonly name = "ConnectError";
+    /** HTTP status. `0` when the request never got a response (network failure, timeout). */
+    readonly status: number;
+    /** `rate_limited`, `forbidden`, `invalid_token`, ... - branch on this, never on `message`. */
+    readonly code: string;
+    /** From `Retry-After` on a 429, in milliseconds. `null` otherwise. */
+    readonly retryAfterMs: number | null;
+    /** The endpoint that failed, e.g. `POST /sso/token` - present on every error. */
+    readonly endpoint: string;
+    /** Parsed response body, when there was one. */
+    readonly body: unknown;
+    constructor(init: {
+        message: string;
+        status: number;
+        code: string;
+        endpoint: string;
+        retryAfterMs?: number | null;
+        body?: unknown;
+        cause?: unknown;
+    });
+    /**
+     * Whether trying the exact same request again could plausibly succeed -
+     * throttling, a transient server fault, or no response at all. The SDK
+     * already retries these internally (see `ConnectClientOptions.maxRetries`);
+     * this is for callers deciding whether to queue their own retry after the
+     * SDK has given up.
+     */
+    get isRetryable(): boolean;
+    /**
+     * Whether the user's Connect sign-in is over and they need to go back
+     * through `identity.authorizeUrl()`. Collapses every session-side failure,
+     * matching how the API reports them - unknown, expired, revoked, or issued
+     * to a different service all arrive as one `invalid_token`.
+     */
+    get isSessionExpired(): boolean;
+    /**
+     * Whether *your own API key* is dead - revoked or past its expiry - rather
+     * than the request being wrong.
+     *
+     * Connect answers `403` for every credential failure and keeps the code
+     * uniform (`forbidden`) whenever telling them apart would help someone
+     * guessing keys. These two are the exception: reaching them required
+     * presenting a key whose hash matched, so you already hold it, and what you
+     * need to know is that no retry and no scope change will fix this - the key
+     * has to be reissued from the service's Setup tab.
+     *
+     * Worth alerting on. It is the one failure that will not resolve itself and
+     * takes down every call your integration makes.
+     */
+    get isKeyRejected(): boolean;
+}
+export declare function isConnectError(error: unknown): error is ConnectError;

package/dist/types/format-relative-time.d.ts

@@ -0,0 +1,2 @@
+/** "3m ago" / "2h ago" / "5d ago", falling back to a plain date past 30 days. */
+export declare function formatRelativeTime(date: Date): string;

package/dist/types/helpers.d.ts

@@ -0,0 +1,33 @@
+import type { PlanFeature, ReadinessBlocker, ReadinessResponse } from "./types.js";
+/**
+ * The blockers that actually deny access, in the order to show them.
+ *
+ * Advisory ones (no saved payment method mid-subscription, say) are worth
+ * surfacing but are not a reason to lock anyone out today - filtering them here
+ * keeps that judgement in one place rather than in every call site.
+ */
+export declare function blockingBlockers(readiness: ReadinessResponse): ReadinessBlocker[];
+/**
+ * What `features` can look like coming off the wire.
+ *
+ * Connect used to send bare keys and now sends `{ key, name, description }`.
+ * A published SDK talks to whatever version the partner's Connect instance is
+ * running and has no say in when that moves - so both shapes are real, and a
+ * client that assumes the newer one renders an empty feature list against
+ * every instance that has not upgraded yet.
+ */
+export type WirePlanFeature = string | PlanFeature;
+/**
+ * Coerces either wire shape into `PlanFeature[]`.
+ *
+ * A bare key becomes `{ key, name: key, description: "" }` - the same
+ * fallback the server applies for a plan older than its service's feature
+ * catalog, so an un-upgraded Connect renders exactly what it always did
+ * rather than a column of blanks.
+ *
+ * Applied inside `BillingResource.listPlans`, so anything reading a plan
+ * through the SDK or its bridge already has the normalised shape and no
+ * component needs to know this ambiguity exists. Exported for a partner who
+ * hand-rolled a bridge instead of using `createConnectHandler`.
+ */
+export declare function normalizePlanFeatures(features: readonly WirePlanFeature[] | undefined): PlanFeature[];

package/dist/types/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `@cosmoops/connect-sdk` - the official client for the CosmoOps Connect
+ * **service-partner API** (`/api/v1/service/*`).
+ *
+ * This root entry is the isomorphic surface: wire types, the error class, and
+ * pure helpers. It pulls in neither Node-only code nor React, so it is safe to
+ * import from anywhere.
+ *
+ * - `@cosmoops/connect-sdk/server` - `ConnectClient` and `createConnectHandler`.
+ *   Holds the API key. Never import this from browser code.
+ * - `@cosmoops/connect-sdk/client` - React components and hooks. Talks to your
+ *   own origin only.
+ */
+export { ConnectError, isConnectError } from "./errors.js";
+export { blockingBlockers, normalizePlanFeatures } from "./helpers.js";
+export type { WirePlanFeature } from "./helpers.js";
+export type * from "./types.js";

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

@@ -0,0 +1,136 @@
+import { ConnectClient, type ConnectClientOptions } from "../server/client.js";
+import { type ConnectSessionStore } from "../server/handler.js";
+import type { UserResponse } from "../types.js";
+/**
+ * The shared server client, built from the environment on first use.
+ *
+ * Lazy on purpose: reading `CONNECT_API_KEY` at module load would throw during
+ * `next build`, where route modules are imported but never invoked and secrets
+ * are frequently absent.
+ */
+export declare function connectClient(overrides?: Partial<ConnectClientOptions>): ConnectClient;
+/**
+ * An httpOnly cookie holding the opaque `sessionToken`.
+ *
+ * Not signed or encrypted, deliberately. The token is opaque and useless
+ * without the `client_secret` that never leaves the server, so a tampered
+ * value buys an attacker a 401 rather than a forged identity - and a signing
+ * secret would be one more thing to rotate for protection already provided by
+ * the token's own design. `SameSite=Lax` because `Strict` would withhold the
+ * cookie on the redirect back from Connect.
+ */
+export declare function cookieSessionStore(cookieName?: string): ConnectSessionStore;
+export interface CreateConnectHandlersOptions {
+    client?: ConnectClient;
+    session?: ConnectSessionStore;
+    basePath?: string;
+    /** Where `/callback` lands when the request carried no `next`. Defaults to `/`. */
+    defaultRedirect?: string;
+}
+/**
+ * The catch-all route handlers, ready to re-export.
+ *
+ * Only needed when you are changing something - a different mount point, a
+ * session store that isn't a cookie, a post-login destination that isn't `/`.
+ * The zero-configuration case is the `GET` / `POST` re-export below, which is
+ * this function with no arguments.
+ *
+ * ```ts
+ * // app/api/connect/[...connect]/route.ts
+ * import { createConnectHandlers } from "@cosmoops/connect-sdk/next";
+ * export const { GET, POST } = createConnectHandlers({ basePath: "/api/auth" });
+ * ```
+ *
+ * `GET` and `POST` are the same function - the bridge routes on method and
+ * path itself, so Next only needs to know both verbs reach it.
+ */
+export declare function createConnectHandlers(options?: CreateConnectHandlersOptions): {
+    GET: (request: Request) => Promise<Response>;
+    POST: (request: Request) => Promise<Response>;
+};
+/**
+ * The bridge itself, for the default mount at `/api/connect`.
+ *
+ * Built on the first request rather than at module load, for the same reason
+ * `connectClient` is lazy: `next build` imports every route module, and an
+ * environment-reading constructor at the top level turns a missing secret in
+ * CI into a failed build of routes that were never going to run there.
+ */
+declare function handle(request: Request): Promise<Response>;
+/**
+ * The one-line backend.
+ *
+ * ```ts
+ * // app/api/connect/[...connect]/route.ts
+ * export { GET, POST } from "@cosmoops/connect-sdk/next";
+ * ```
+ *
+ * That gives you `/signin`, `/callback`, the session cookie, and the
+ * `/session` `/entitlements` `/plans` `/apps` `/addons` `/sessions` `/logout`
+ * reads the browser half calls. Reach for `createConnectHandlers` instead only
+ * when you need to configure one of them.
+ */
+export { handle as GET, handle as POST };
+/**
+ * The signed-in user for a Server Component, Route Handler or Server Action,
+ * or `null`.
+ *
+ * ```tsx
+ * // app/dashboard/page.tsx
+ * const session = await getConnectSession();
+ * if (!session) redirect("/api/connect/signin?next=/dashboard");
+ * ```
+ *
+ * Pass a `Request` to use it somewhere `next/headers` does not exist - a
+ * framework-agnostic handler, a test, a custom server. Both forms take the
+ * same path afterwards; the argument is only how the cookie is found.
+ *
+ * Reads `cookies()` transitively, so under `cacheComponents` this belongs
+ * inside a `<Suspense>` boundary (or a `'use cache: private'` function) like
+ * any other request-scoped read - a page that awaits it above every boundary
+ * gives up its static shell.
+ *
+ * Returns `null` for every failure - an expired session and a missing one both
+ * mean "not signed in", and a page guard should not need a try/catch.
+ */
+export declare function getConnectSession(request?: Request, options?: {
+    client?: ConnectClient;
+    session?: ConnectSessionStore;
+}): Promise<UserResponse | null>;
+/**
+ * `next.config` wrapper.
+ *
+ * Asserts, at config load, that the public client id is present - the one
+ * variable whose absence fails silently in the browser instead of loudly on
+ * the server, because `NEXT_PUBLIC_*` is inlined at build time and an unset
+ * one simply becomes `undefined`. That is its whole job.
+ *
+ * In particular it does **not** replace the bridge route, and cannot: Next has
+ * no plugin API that contributes a route from a `node_modules` package - the
+ * App Router discovers routes by walking your own `app/` directory and nothing
+ * else, and a `next.config` rewrite still needs a real route to point at. So
+ * `app/api/connect/[...connect]/route.ts` has to exist whether or not you use
+ * this wrapper. It is one line, and `npx @cosmoops/connect-sdk init` writes it:
+ *
+ * ```ts
+ * export { GET, POST } from "@cosmoops/connect-sdk/next";
+ * ```
+ *
+ * The two are independent - the route works with a plain config, and this
+ * wrapper is useful with no route at all. Using both is just the default setup.
+ *
+ * It does **not** add this package to `transpilePackages`, and you should not
+ * either. `dist/` is already ES2022 with `"use client"` hoisted to the top of
+ * every browser file, so Turbopack and webpack both consume it as-is;
+ * transpiling it again only costs build time. An earlier version of this
+ * wrapper added the entry, which is why it may still be in your config.
+ *
+ * ```ts
+ * import { withConnect } from "@cosmoops/connect-sdk/next";
+ * export default withConnect({ });
+ * ```
+ */
+export declare function withConnect<T extends object>(config?: T): T;
+export { createConnectHandler } from "../server/handler.js";
+export type { ConnectSessionStore } from "../server/handler.js";
+export { ConnectClient } from "../server/client.js";