@cosmoops/connect-sdk 0.3.0 → 0.6.0

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

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 service's name, in the `cosmo·ops VOICE` lockup. See `ConnectLogo`. */
+    name: string;
+    /** This service'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 service 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 services 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/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 organization 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;

package/dist/types/client/components/motion.d.ts

@@ -0,0 +1,22 @@
+import type { ReactNode } from "react";
+export { m, AnimatePresence } from "motion/react";
+/** HeroUI's --ease-out-quart, transcribed for motion transitions. */
+export declare const EASE_OUT_QUART: readonly [0.165, 0.84, 0.44, 1];
+export declare const ENTER: {
+    readonly duration: 0.3;
+    readonly ease: readonly [0.165, 0.84, 0.44, 1];
+};
+export declare const METER_SPRING: {
+    readonly type: "spring";
+    readonly stiffness: 170;
+    readonly damping: 26;
+};
+/**
+ * Per-component motion root. domAnimation keeps the feature bundle small,
+ * `strict` restricts rendering to `m.*` components, and reducedMotion="user"
+ * drops transform animation (keeping opacity) under prefers-reduced-motion -
+ * the same contract HeroUI's own `motion-reduce` styles follow.
+ */
+export declare function MotionProvider({ children }: Readonly<{
+    children: ReactNode;
+}>): import("react").JSX.Element;

package/dist/types/client/components/nav.d.ts

@@ -0,0 +1,110 @@
+import type { ReactNode } from "react";
+/**
+ * One destination in the shell's sidebar.
+ *
+ * `href` is a path in *your* app, not a Connect URL - the shell never
+ * routes anywhere itself, it hands `href` to `renderLink` and lets your
+ * router do the work.
+ */
+export interface ConnectNavItem {
+    label: string;
+    href: string;
+    /**
+     * A pre-rendered glyph, e.g. `<LayoutDashboard className="size-5" />`.
+     * Required in practice for anything in the primary rail: the collapsed rail
+     * is icon-only, and an item with no icon collapses to an empty box.
+     */
+    icon?: ReactNode;
+    /** Trailing content on the row - a count `<Chip>`, a status dot. Hidden while collapsed. */
+    badge?: ReactNode;
+    /**
+     * Match this route only when the path is exactly `href`, never as a prefix.
+     * `/` is always treated as exact regardless, since every path starts with it.
+     */
+    exact?: boolean;
+    /** Opens in a new tab, with a trailing arrow. For docs, status pages, anything outside the app. */
+    external?: boolean;
+    /** One level of children, revealed beneath the parent when the parent or a child is active. */
+    items?: ConnectNavItem[];
+    /**
+     * Leave this route *outside* `ConnectAccessGate` - see
+     * `ConnectAppShellProps.gate`. Declared here, next to the route it applies
+     * to, rather than as a second list somewhere else that has to be kept in
+     * step with this one.
+     */
+    gateExempt?: boolean;
+}
+/** A titled group of items. Untitled groups render as a plain divider-free block. */
+export interface ConnectNavSection {
+    title?: string;
+    items: ConnectNavItem[];
+}
+/**
+ * What `ConnectAppShell`/`ConnectSideNav` accept for `nav`: a flat list of
+ * items, a list of sections, or a mix. Consecutive bare items fold into one
+ * untitled section, so the common case is just an array of items.
+ */
+export type ConnectNav = ReadonlyArray<ConnectNavItem | ConnectNavSection>;
+/** Props the shell hands to `renderLink`. Spread them onto whatever your router's link component is. */
+export interface ConnectNavLinkProps {
+    href: string;
+    className: string;
+    children: ReactNode;
+    onClick?: () => void;
+    "aria-current"?: "page";
+    /**
+     * Always set, and the only name the link has while the rail is collapsed -
+     * spread it through rather than dropping it, or an icon-only rail reads as
+     * a column of unlabelled links.
+     */
+    "aria-label": string;
+    target?: string;
+    rel?: string;
+}
+/**
+ * How this app renders a link.
+ *
+ * The SDK ships into any React app and cannot import `next/link`,
+ * `react-router` or anything else framework-specific, so routing is a prop.
+ * The default is a plain `<a>`, which is correct but costs a full page load;
+ * an app with a client router should pass its own:
+ *
+ * ```tsx
+ * renderLink={(props) => <Link {...props} />}   // next/link
+ * ```
+ */
+export type ConnectLinkRenderer = (props: ConnectNavLinkProps) => ReactNode;
+/** Folds a mixed `ConnectNav` into sections, gathering consecutive bare items into one untitled group. */
+export declare function normalizeNav(nav: ConnectNav): ConnectNavSection[];
+/** Every item in the tree, parents and children alike, in render order. */
+export declare function flattenNav(nav: ConnectNav): ConnectNavItem[];
+/**
+ * `https://x.test/billing/?tab=1#top` -> `/billing`.
+ *
+ * Trailing slashes go too, so `/billing/` and `/billing` are the same route -
+ * they are, to every router, and treating them as different is how a nav item
+ * ends up unhighlighted on exactly one of the two URLs a user can arrive at.
+ */
+export declare function normalizePath(path: string): string;
+/**
+ * The href of the nav item the current path belongs to, or `null`.
+ *
+ * Longest prefix wins, so `/settings/billing` lights up Billing and not also
+ * its parent Settings - a plain `startsWith` over an unordered list lights up
+ * both, and the sidebar grows two highlights.
+ *
+ * External items never match: they leave the app, so no path inside it is
+ * ever "on" them.
+ */
+export declare function resolveActivePath(pathname: string, nav: ConnectNav): string | null;
+/**
+ * Whether `item` is the destination `resolveActivePath` picked.
+ *
+ * Not just `normalizePath(item.href) === activeHref`, which is the trap this
+ * exists to close: `normalizePath` strips the origin off an absolute URL, so
+ * an external item pointed at `https://docs.example.com` normalizes to `/` and
+ * lights up on every app's home route. External items are never active.
+ */
+export declare function isNavItemActive(item: ConnectNavItem, activeHref: string | null): boolean;
+/** Hrefs declared `gateExempt` - the routes `ConnectAppShell` renders outside its `ConnectAccessGate`. */
+export declare function gateExemptPaths(nav: ConnectNav): string[];

package/dist/types/client/components/side-nav.d.ts

@@ -0,0 +1,31 @@
+import { type ConnectLinkRenderer, type ConnectNav } from "./nav.js";
+/** A plain anchor - correct anywhere, and a full page load. See `ConnectLinkRenderer`. */
+export declare const defaultRenderLink: ConnectLinkRenderer;
+export interface ConnectSideNavProps {
+    /** Items, sections, or a mix - see `ConnectNav`. */
+    nav: ConnectNav;
+    /**
+     * The current path. Pass your router's own (`usePathname()` in Next) -
+     * without it the nav reads `window.location` and patches `history` to hear
+     * about client-side navigations, which works but is guesswork the router
+     * never has to do. See `useActivePath`.
+     */
+    activePath?: string;
+    /** See `ConnectLinkRenderer`. Defaults to a plain `<a>`. */
+    renderLink?: ConnectLinkRenderer;
+    /** Icon-only rail. Labels move into tooltips and children are hidden. */
+    collapsed?: boolean;
+    /** Called after any nav link is pressed - the mobile drawer closes itself with this. */
+    onNavigate?: () => void;
+    className?: string;
+}
+/**
+ * The sidebar's nav column on its own - sections, items, one level of
+ * children, and the active highlight.
+ *
+ * `ConnectAppShell` renders this inside its rail and its mobile drawer, and it
+ * is exported for a host that wants the shell's navigation without its
+ * chrome: the same items, the same active resolution, dropped into a layout
+ * you already have.
+ */
+export declare function ConnectSideNav({ nav, activePath, renderLink, collapsed, onNavigate, className, }: ConnectSideNavProps): import("react").JSX.Element;