@cosmoops/connect-sdk 0.2.0 → 0.3.0

package/README.md

@@ -245,6 +245,68 @@ it above every boundary gives up its static shell.
 You do **not** need `transpilePackages`. `dist/` is ES2022 with `"use client"`
 already hoisted, so Turbopack and webpack consume it as-is.
 
+## Route protection and `proxy.ts`
+
+Nothing here is auto-wired, and nothing needs to be: this SDK ships no proxy and
+never writes one. Next 16 renamed Middleware to **Proxy** — a single `proxy.ts`
+at the project root (or in `src/`, beside `app/`).
+
+You only need one if you want unauthenticated visitors bounced *before* a page
+renders. If you are happy redirecting inside the page, `getConnectSession()`
+above already does the job and there is nothing to add.
+
+If you do add one, keep it to a cookie **presence** check:
+
+```ts
+// proxy.ts
+import { NextResponse } from "next/server";
+import type { NextRequest } from "next/server";
+
+const COOKIE = process.env.CONNECT_SESSION_COOKIE ?? "connect_session";
+
+export function proxy(request: NextRequest) {
+  if (request.cookies.has(COOKIE)) return NextResponse.next();
+
+  const signin = new URL("/api/connect/signin", request.url);
+  signin.searchParams.set("next", request.nextUrl.pathname);
+  return NextResponse.redirect(signin);
+}
+
+// Must not match /api/connect/* — the sign-in route has no session cookie yet,
+// so matching it would redirect the sign-in to itself.
+export const config = { matcher: ["/dashboard/:path*", "/settings/:path*"] };
+```
+
+**A cookie is not a session, and this check is not authorization.** The cookie
+holds an opaque Connect `sessionToken`; deciding whether it is still valid means
+asking Connect, and proxy runs on every matched request — so a real check here
+would put a network round trip in front of each one. Next's own guidance says
+the same thing: proxy is for [optimistic
+checks](https://nextjs.org/docs/app/guides/authentication#optimistic-checks-with-proxy-optional),
+"not ... a full session management or authorization solution."
+
+An expired or revoked token still arrives as a cookie and still passes the
+snippet above. The authoritative check is `getConnectSession()` in the Server
+Component, or `client.entitlements.*` on your server — treat the proxy purely as
+a way to skip rendering a page the visitor cannot use.
+
+### The server/client boundary
+
+`@cosmoops/connect-sdk/server` and `/next` build a client around
+`CONNECT_API_KEY`; `/client` holds no credential and calls your own origin. That
+split is enforced, not just documented — both credential-holding entries resolve
+to a stub in a browser bundle, so importing one from a client component fails the
+build:
+
+```
+No matching export in ".../dist/esm/this-entry-is-server-only.js" for import "ConnectClient"
+```
+
+Import from `/client` instead, or use `import type`, which erases before any
+bundler sees it. Server Components, Route Handlers, Server Actions and non-Next
+backends are unaffected — the stub is wired to the `browser` export condition,
+which only a client bundle resolves.
+
 ## Other frameworks
 
 Mount the bridge once in your backend:
@@ -350,7 +412,13 @@ All three render `loading` — never the fallback — while the answer is unknow
 npx @cosmoops/connect-sdk init
 ```
 
-Writes `app/api/connect/[...connect]/route.ts`, `app/plans/page.tsx` and an `.env.local` template, then prints the two steps it will not do for you (wrapping your layout in `<ConnectProvider>`, and registering the redirect URI in Connect). It never overwrites, so re-running is safe.
+Writes `app/api/connect/[...connect]/route.ts`, `app/plans/page.tsx` and an `.env.local` template, then prints the steps it will not do for you (wrapping your layout in `<ConnectProvider>`, importing the theme, and registering the redirect URI in Connect). It never overwrites, so re-running is safe.
+
+```bash
+npx @cosmoops/connect-sdk doctor
+```
+
+Checks a wired-up project and names what is missing: the bridge route (wherever you mounted it) exporting both verbs, exactly one `<ConnectProvider>`, the theme imported *after* `@heroui/styles`, and both credentials actually set rather than declared empty. Exits non-zero on a real problem, so it works as a CI step. It is entirely offline — no credentials, no network — which is also its one limit: Connect exposes no endpoint listing a client's registered redirect URIs, so that step is reported as something only you can confirm.
 
 Next has no plugin API that adds routes — `next.config` can rewrite and redirect, but both need a route to point at, and the App Router only discovers routes in your own `app/` directory. So this is a scaffolder rather than a plugin: `ConnectPlansPage` makes the file that must exist one line, and `init` writes that line.
 

package/dist/cjs/cli/doctor.js

@@ -0,0 +1,209 @@
+"use strict";
+/**
+ * `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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDoctor = runDoctor;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/** Directories that are never a project's own source, and are large enough to matter. */
+const SKIP = new Set(["node_modules", ".next", ".git", "dist", "build", ".turbo", "coverage"]);
+function walk(dir, extensions, found = [], depth = 0) {
+    if (depth > 8 || !(0, node_fs_1.existsSync)(dir))
+        return found;
+    for (const entry of (0, node_fs_1.readdirSync)(dir)) {
+        if (SKIP.has(entry))
+            continue;
+        const path = (0, node_path_1.join)(dir, entry);
+        if ((0, node_fs_1.statSync)(path).isDirectory())
+            walk(path, extensions, found, depth + 1);
+        else if (extensions.some((extension) => entry.endsWith(extension)))
+            found.push(path);
+    }
+    return found;
+}
+function read(path) {
+    try {
+        return (0, node_fs_1.readFileSync)(path, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+function findAppDir(root) {
+    for (const candidate of [(0, node_path_1.join)(root, "app"), (0, node_path_1.join)(root, "src", "app")]) {
+        if ((0, node_fs_1.existsSync)(candidate))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * The bridge is found by what it exports, not by where it sits.
+ *
+ * `createConnectHandlers({ basePath })` exists precisely so the route can be
+ * mounted somewhere other than `/api/connect`, so checking for that one path
+ * would report a false failure on every app that took the option.
+ */
+function checkBridge(appDir, root) {
+    const routes = walk(appDir, ["route.ts", "route.tsx", "route.js"]);
+    const bridge = routes.find((path) => /@cosmoops\/connect-sdk\/next/.test(read(path)));
+    if (!bridge) {
+        return {
+            status: "fail",
+            title: "Bridge route handler",
+            detail: 'No route re-exports the bridge. Create app/api/connect/[...connect]/route.ts containing:\n       export { GET, POST } from "@cosmoops/connect-sdk/next";\n     or run `npx @cosmoops/connect-sdk init`.',
+        };
+    }
+    const source = read(bridge);
+    const exportsBoth = /\bGET\b/.test(source) && /\bPOST\b/.test(source);
+    if (!exportsBoth) {
+        return {
+            status: "fail",
+            title: "Bridge route handler",
+            detail: `${(0, node_path_1.relative)(root, bridge)} exports only one verb. GET and POST are the same function - the bridge routes on method itself - and sign-out POSTs, so both must be exported.`,
+        };
+    }
+    return { status: "pass", title: `Bridge route handler (${(0, node_path_1.relative)(root, bridge)})` };
+}
+function checkProvider(appDir, root) {
+    const layouts = walk(appDir, ["layout.tsx", "layout.jsx"]);
+    const hosting = layouts.filter((path) => /<ConnectProvider/.test(read(path)));
+    if (hosting.length === 0) {
+        return {
+            status: "fail",
+            title: "ConnectProvider in a layout",
+            detail: 'Nothing renders <ConnectProvider>. Every client hook and component below it throws without one. In app/layout.tsx:\n       import { ConnectProvider } from "@cosmoops/connect-sdk/client";\n       <ConnectProvider>{children}</ConnectProvider>',
+        };
+    }
+    // A nested provider re-fetches the session and keeps a second cache that the
+    // first one's mutations never invalidate, so a plan change updates one half
+    // of the page. Worth naming even though both layouts look correct alone.
+    if (hosting.length > 1) {
+        return {
+            status: "warn",
+            title: "ConnectProvider in a layout",
+            detail: `Found in ${hosting.length} layouts (${hosting.map((path) => (0, node_path_1.relative)(root, path)).join(", ")}). Nested providers keep separate caches, so a mutation in one is invisible to the other. Keep the outermost one only.`,
+        };
+    }
+    return { status: "pass", title: `ConnectProvider in a layout (${(0, node_path_1.relative)(root, hosting[0])})` };
+}
+/**
+ * Order is the whole check.
+ *
+ * `theme.css` sets the HeroUI token values Connect's components read. Imported
+ * before `@heroui/styles`, HeroUI's own defaults are declared later, win on
+ * source order, and the theme silently does nothing - the app looks fine, just
+ * not themed. The import also has to live in the app's own stylesheet: from
+ * inside node_modules, Tailwind roots its content scan there and never scans
+ * the app.
+ */
+function checkTheme(root) {
+    const stylesheets = walk(root, [".css"]).filter((path) => !path.includes("node_modules"));
+    const importing = stylesheets.filter((path) => read(path).includes("@cosmoops/connect-sdk/theme.css"));
+    if (importing.length === 0) {
+        return {
+            status: "fail",
+            title: "Theme stylesheet imported",
+            detail: 'No stylesheet imports the Connect theme, so the components render with HeroUI defaults. Add it last of the three, in your own global CSS:\n       @import "tailwindcss";\n       @import "@heroui/styles";\n       @import "@cosmoops/connect-sdk/theme.css";',
+        };
+    }
+    for (const path of importing) {
+        const source = read(path);
+        const connect = source.indexOf("@cosmoops/connect-sdk/theme.css");
+        const heroui = source.indexOf("@heroui/styles");
+        if (heroui !== -1 && heroui > connect) {
+            return {
+                status: "fail",
+                title: "Theme stylesheet imported",
+                detail: `${(0, node_path_1.relative)(root, path)} imports @heroui/styles *after* the Connect theme, so HeroUI's defaults win on source order and the theme has no effect. Put "@cosmoops/connect-sdk/theme.css" last.`,
+            };
+        }
+    }
+    return { status: "pass", title: `Theme stylesheet imported (${(0, node_path_1.relative)(root, importing[0])})` };
+}
+/**
+ * `.env.local` is read directly rather than trusting `process.env`, because
+ * the interesting case is a developer running this in a shell that never
+ * loaded it - exactly the shell `next dev` will inherit.
+ */
+function checkEnv(root) {
+    const files = [".env.local", ".env.development.local", ".env"].map((name) => (0, node_path_1.join)(root, name));
+    const combined = files.filter(node_fs_1.existsSync).map(read).join("\n");
+    return ["CONNECT_API_KEY", "CONNECT_CLIENT_ID"].map((name) => {
+        // Horizontal whitespace only. `\s*` also matches the newline, so a bare
+        // `CONNECT_API_KEY=` was satisfied by the *next* line's value and an empty
+        // credential reported as set - which is the exact failure this check exists
+        // to catch.
+        const assigned = new RegExp(`^[ \\t]*${name}[ \\t]*=[ \\t]*\\S`, "m").test(combined);
+        if (assigned || process.env[name]) {
+            return { status: "pass", title: `${name} set` };
+        }
+        const declaredEmpty = new RegExp(`^[ \\t]*${name}[ \\t]*=`, "m").test(combined);
+        return {
+            status: "fail",
+            title: `${name} set`,
+            detail: declaredEmpty
+                ? `Declared but empty in .env.local. The value is in your service's Setup tab in Connect.`
+                : `Not found in .env.local or the environment. Both values are in your service's Setup tab in Connect.`,
+        };
+    });
+}
+/**
+ * Nothing here can verify this - Connect has no endpoint listing a client's
+ * redirect URIs - but it is the single most common reason a correct setup
+ * still fails at sign-in, so it is worth a line that always prints.
+ */
+function checkRedirectUri() {
+    return {
+        status: "warn",
+        title: "Redirect URI registered in Connect",
+        detail: "Not checkable from here. Confirm {your origin}/api/connect/callback is listed as a redirect URI in your service's Setup tab - including the deployed origin, not just http://localhost:3000.",
+    };
+}
+const MARKER = { pass: "  ok  ", warn: " note ", fail: " FAIL " };
+function runDoctor(argv = []) {
+    const root = (0, node_path_1.resolve)(argv[0] ?? process.cwd());
+    const appDir = findAppDir(root);
+    if (!appDir) {
+        console.error(`[connect-sdk] No App Router directory found in ${root} - looked for "app/" and "src/app/".\n` +
+            "Run this from your Next.js project root, or pass the path: npx @cosmoops/connect-sdk doctor ./my-app");
+        return 1;
+    }
+    console.log(`[connect-sdk] Checking ${(0, node_path_1.relative)(process.cwd(), root) || root}\n`);
+    const checks = [
+        checkBridge(appDir, root),
+        checkProvider(appDir, root),
+        checkTheme(root),
+        ...checkEnv(root),
+        checkRedirectUri(),
+    ];
+    for (const check of checks) {
+        console.log(`  ${MARKER[check.status]}  ${check.title}`);
+        if (check.detail)
+            console.log(`          ${check.detail.replace(/\n/g, "\n          ")}\n`);
+    }
+    const failed = checks.filter((check) => check.status === "fail").length;
+    console.log(failed === 0
+        ? "\nNo problems found.\n"
+        : `\n${failed} problem${failed === 1 ? "" : "s"} to fix. Run \`npx @cosmoops/connect-sdk init\` to scaffold anything missing.\n`);
+    return failed === 0 ? 0 : 1;
+}

package/dist/cjs/cli/init.js

@@ -27,6 +27,7 @@ exports.runInit = runInit;
 exports.main = main;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const doctor_js_1 = require("./doctor.js");
 const BRIDGE_ROUTE = `// The Connect bridge - the only place your API key is used.
 //
 // It answers your own origin, so the browser half of the SDK never holds a
@@ -145,15 +146,17 @@ as-is.
 Then <ConnectPlans />, <ConnectSubscriptionGate>, <ConnectFeatureGate> and the
 rest work anywhere below the provider, and getConnectSession() reads the same
 session from any Server Component.
+
+Run \`npx @cosmoops/connect-sdk doctor\` when you have done those three - it
+checks all of them and says which are still outstanding.
 `);
     return 0;
 }
 /**
- * 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.
@@ -161,13 +164,22 @@ session from any Server Component.
 function main(argv) {
     const [first, ...rest] = argv;
     if (first === "--help" || first === "-h") {
-        console.log("Usage: connect-sdk init [project-dir]");
+        console.log([
+            "Usage: connect-sdk <command> [project-dir]",
+            "",
+            "  init     scaffold the bridge route, /plans page and .env.local",
+            "  doctor   check an existing setup and report what is missing",
+            "",
+            "With no command, runs init against the given directory (default: cwd).",
+        ].join("\n"));
         return 0;
     }
     if (first === "init")
         return runInit(rest);
+    if (first === "doctor" || first === "check")
+        return (0, doctor_js_1.runDoctor)(rest);
     if (!first || (0, node_fs_1.existsSync)(first))
         return runInit(argv);
-    console.error(`[connect-sdk] Unknown command "${first}". Try: connect-sdk init`);
+    console.error(`[connect-sdk] Unknown command "${first}". Try: connect-sdk init, or connect-sdk doctor`);
     return 1;
 }

package/dist/cjs/server/client.js

@@ -111,4 +111,4 @@ class ConnectClient {
 }
 exports.ConnectClient = ConnectClient;
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-exports.SDK_VERSION = "0.1.0";
+exports.SDK_VERSION = "0.3.0";

package/dist/cjs/this-entry-is-server-only.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * 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.');

package/dist/esm/cli/doctor.js

@@ -0,0 +1,206 @@
+/**
+ * `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.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+/** Directories that are never a project's own source, and are large enough to matter. */
+const SKIP = new Set(["node_modules", ".next", ".git", "dist", "build", ".turbo", "coverage"]);
+function walk(dir, extensions, found = [], depth = 0) {
+    if (depth > 8 || !existsSync(dir))
+        return found;
+    for (const entry of readdirSync(dir)) {
+        if (SKIP.has(entry))
+            continue;
+        const path = join(dir, entry);
+        if (statSync(path).isDirectory())
+            walk(path, extensions, found, depth + 1);
+        else if (extensions.some((extension) => entry.endsWith(extension)))
+            found.push(path);
+    }
+    return found;
+}
+function read(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+function findAppDir(root) {
+    for (const candidate of [join(root, "app"), join(root, "src", "app")]) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * The bridge is found by what it exports, not by where it sits.
+ *
+ * `createConnectHandlers({ basePath })` exists precisely so the route can be
+ * mounted somewhere other than `/api/connect`, so checking for that one path
+ * would report a false failure on every app that took the option.
+ */
+function checkBridge(appDir, root) {
+    const routes = walk(appDir, ["route.ts", "route.tsx", "route.js"]);
+    const bridge = routes.find((path) => /@cosmoops\/connect-sdk\/next/.test(read(path)));
+    if (!bridge) {
+        return {
+            status: "fail",
+            title: "Bridge route handler",
+            detail: 'No route re-exports the bridge. Create app/api/connect/[...connect]/route.ts containing:\n       export { GET, POST } from "@cosmoops/connect-sdk/next";\n     or run `npx @cosmoops/connect-sdk init`.',
+        };
+    }
+    const source = read(bridge);
+    const exportsBoth = /\bGET\b/.test(source) && /\bPOST\b/.test(source);
+    if (!exportsBoth) {
+        return {
+            status: "fail",
+            title: "Bridge route handler",
+            detail: `${relative(root, bridge)} exports only one verb. GET and POST are the same function - the bridge routes on method itself - and sign-out POSTs, so both must be exported.`,
+        };
+    }
+    return { status: "pass", title: `Bridge route handler (${relative(root, bridge)})` };
+}
+function checkProvider(appDir, root) {
+    const layouts = walk(appDir, ["layout.tsx", "layout.jsx"]);
+    const hosting = layouts.filter((path) => /<ConnectProvider/.test(read(path)));
+    if (hosting.length === 0) {
+        return {
+            status: "fail",
+            title: "ConnectProvider in a layout",
+            detail: 'Nothing renders <ConnectProvider>. Every client hook and component below it throws without one. In app/layout.tsx:\n       import { ConnectProvider } from "@cosmoops/connect-sdk/client";\n       <ConnectProvider>{children}</ConnectProvider>',
+        };
+    }
+    // A nested provider re-fetches the session and keeps a second cache that the
+    // first one's mutations never invalidate, so a plan change updates one half
+    // of the page. Worth naming even though both layouts look correct alone.
+    if (hosting.length > 1) {
+        return {
+            status: "warn",
+            title: "ConnectProvider in a layout",
+            detail: `Found in ${hosting.length} layouts (${hosting.map((path) => relative(root, path)).join(", ")}). Nested providers keep separate caches, so a mutation in one is invisible to the other. Keep the outermost one only.`,
+        };
+    }
+    return { status: "pass", title: `ConnectProvider in a layout (${relative(root, hosting[0])})` };
+}
+/**
+ * Order is the whole check.
+ *
+ * `theme.css` sets the HeroUI token values Connect's components read. Imported
+ * before `@heroui/styles`, HeroUI's own defaults are declared later, win on
+ * source order, and the theme silently does nothing - the app looks fine, just
+ * not themed. The import also has to live in the app's own stylesheet: from
+ * inside node_modules, Tailwind roots its content scan there and never scans
+ * the app.
+ */
+function checkTheme(root) {
+    const stylesheets = walk(root, [".css"]).filter((path) => !path.includes("node_modules"));
+    const importing = stylesheets.filter((path) => read(path).includes("@cosmoops/connect-sdk/theme.css"));
+    if (importing.length === 0) {
+        return {
+            status: "fail",
+            title: "Theme stylesheet imported",
+            detail: 'No stylesheet imports the Connect theme, so the components render with HeroUI defaults. Add it last of the three, in your own global CSS:\n       @import "tailwindcss";\n       @import "@heroui/styles";\n       @import "@cosmoops/connect-sdk/theme.css";',
+        };
+    }
+    for (const path of importing) {
+        const source = read(path);
+        const connect = source.indexOf("@cosmoops/connect-sdk/theme.css");
+        const heroui = source.indexOf("@heroui/styles");
+        if (heroui !== -1 && heroui > connect) {
+            return {
+                status: "fail",
+                title: "Theme stylesheet imported",
+                detail: `${relative(root, path)} imports @heroui/styles *after* the Connect theme, so HeroUI's defaults win on source order and the theme has no effect. Put "@cosmoops/connect-sdk/theme.css" last.`,
+            };
+        }
+    }
+    return { status: "pass", title: `Theme stylesheet imported (${relative(root, importing[0])})` };
+}
+/**
+ * `.env.local` is read directly rather than trusting `process.env`, because
+ * the interesting case is a developer running this in a shell that never
+ * loaded it - exactly the shell `next dev` will inherit.
+ */
+function checkEnv(root) {
+    const files = [".env.local", ".env.development.local", ".env"].map((name) => join(root, name));
+    const combined = files.filter(existsSync).map(read).join("\n");
+    return ["CONNECT_API_KEY", "CONNECT_CLIENT_ID"].map((name) => {
+        // Horizontal whitespace only. `\s*` also matches the newline, so a bare
+        // `CONNECT_API_KEY=` was satisfied by the *next* line's value and an empty
+        // credential reported as set - which is the exact failure this check exists
+        // to catch.
+        const assigned = new RegExp(`^[ \\t]*${name}[ \\t]*=[ \\t]*\\S`, "m").test(combined);
+        if (assigned || process.env[name]) {
+            return { status: "pass", title: `${name} set` };
+        }
+        const declaredEmpty = new RegExp(`^[ \\t]*${name}[ \\t]*=`, "m").test(combined);
+        return {
+            status: "fail",
+            title: `${name} set`,
+            detail: declaredEmpty
+                ? `Declared but empty in .env.local. The value is in your service's Setup tab in Connect.`
+                : `Not found in .env.local or the environment. Both values are in your service's Setup tab in Connect.`,
+        };
+    });
+}
+/**
+ * Nothing here can verify this - Connect has no endpoint listing a client's
+ * redirect URIs - but it is the single most common reason a correct setup
+ * still fails at sign-in, so it is worth a line that always prints.
+ */
+function checkRedirectUri() {
+    return {
+        status: "warn",
+        title: "Redirect URI registered in Connect",
+        detail: "Not checkable from here. Confirm {your origin}/api/connect/callback is listed as a redirect URI in your service's Setup tab - including the deployed origin, not just http://localhost:3000.",
+    };
+}
+const MARKER = { pass: "  ok  ", warn: " note ", fail: " FAIL " };
+export function runDoctor(argv = []) {
+    const root = resolve(argv[0] ?? process.cwd());
+    const appDir = findAppDir(root);
+    if (!appDir) {
+        console.error(`[connect-sdk] No App Router directory found in ${root} - looked for "app/" and "src/app/".\n` +
+            "Run this from your Next.js project root, or pass the path: npx @cosmoops/connect-sdk doctor ./my-app");
+        return 1;
+    }
+    console.log(`[connect-sdk] Checking ${relative(process.cwd(), root) || root}\n`);
+    const checks = [
+        checkBridge(appDir, root),
+        checkProvider(appDir, root),
+        checkTheme(root),
+        ...checkEnv(root),
+        checkRedirectUri(),
+    ];
+    for (const check of checks) {
+        console.log(`  ${MARKER[check.status]}  ${check.title}`);
+        if (check.detail)
+            console.log(`          ${check.detail.replace(/\n/g, "\n          ")}\n`);
+    }
+    const failed = checks.filter((check) => check.status === "fail").length;
+    console.log(failed === 0
+        ? "\nNo problems found.\n"
+        : `\n${failed} problem${failed === 1 ? "" : "s"} to fix. Run \`npx @cosmoops/connect-sdk init\` to scaffold anything missing.\n`);
+    return failed === 0 ? 0 : 1;
+}

package/dist/esm/cli/init.js

@@ -22,6 +22,7 @@
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
+import { runDoctor } from "./doctor.js";
 const BRIDGE_ROUTE = `// The Connect bridge - the only place your API key is used.
 //
 // It answers your own origin, so the browser half of the SDK never holds a
@@ -140,15 +141,17 @@ as-is.
 Then <ConnectPlans />, <ConnectSubscriptionGate>, <ConnectFeatureGate> and the
 rest work anywhere below the provider, and getConnectSession() reads the same
 session from any Server Component.
+
+Run \`npx @cosmoops/connect-sdk doctor\` when you have done those three - it
+checks all of them and says which are still outstanding.
 `);
     return 0;
 }
 /**
- * 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.
@@ -156,13 +159,22 @@ session from any Server Component.
 export function main(argv) {
     const [first, ...rest] = argv;
     if (first === "--help" || first === "-h") {
-        console.log("Usage: connect-sdk init [project-dir]");
+        console.log([
+            "Usage: connect-sdk <command> [project-dir]",
+            "",
+            "  init     scaffold the bridge route, /plans page and .env.local",
+            "  doctor   check an existing setup and report what is missing",
+            "",
+            "With no command, runs init against the given directory (default: cwd).",
+        ].join("\n"));
         return 0;
     }
     if (first === "init")
         return runInit(rest);
+    if (first === "doctor" || first === "check")
+        return runDoctor(rest);
     if (!first || existsSync(first))
         return runInit(argv);
-    console.error(`[connect-sdk] Unknown command "${first}". Try: connect-sdk init`);
+    console.error(`[connect-sdk] Unknown command "${first}". Try: connect-sdk init, or connect-sdk doctor`);
     return 1;
 }

package/dist/esm/server/client.js

@@ -107,4 +107,4 @@ export class ConnectClient {
     }
 }
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-export const SDK_VERSION = "0.1.0";
+export const SDK_VERSION = "0.3.0";

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/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/server/client.d.ts

@@ -80,4 +80,4 @@ export declare class ConnectClient {
     constructor(options: ConnectClientOptions);
 }
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-export declare const SDK_VERSION = "0.1.0";
+export declare const SDK_VERSION = "0.3.0";

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

@@ -10,6 +10,14 @@ export type { ConnectClientOptions } from "./client.js";
 export { createConnectHandler } from "./handler.js";
 export type { ConnectHandlerOptions, ConnectSessionStore } from "./handler.js";
 export { createState } from "./resources/identity.js";
-export type { AuthorizeUrlInput, ExchangeCodeInput } from "./resources/identity.js";
-export type { UploadInput } from "./resources/drive.js";
+export type { AuthorizeUrlInput, ExchangeCodeInput, IdentityResource } from "./resources/identity.js";
+export type { UploadInput, DriveResource } from "./resources/drive.js";
 export type { FetchLike } from "./http.js";
+export type { AccessResource } from "./resources/access.js";
+export type { AppsResource } from "./resources/apps.js";
+export type { EntitlementsResource } from "./resources/entitlements.js";
+export type { BillingResource } from "./resources/billing.js";
+export type { AiResource } from "./resources/ai.js";
+export type { OtpResource } from "./resources/otp.js";
+export type { LogsResource } from "./resources/logs.js";
+export type { SessionsResource } from "./resources/sessions.js";

package/dist/types/this-entry-is-server-only.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmoops/connect-sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Official server-side SDK for the CosmoOps Connect platform API - Login with Connect, entitlements, billing and metering.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "commonjs",
@@ -15,11 +15,19 @@
     },
     "./server": {
       "types": "./dist/types/server/index.d.ts",
+      "browser": {
+        "import": "./dist/esm/this-entry-is-server-only.js",
+        "require": "./dist/cjs/this-entry-is-server-only.js"
+      },
       "import": "./dist/esm/server/index.js",
       "require": "./dist/cjs/server/index.js"
     },
     "./next": {
       "types": "./dist/types/next/index.d.ts",
+      "browser": {
+        "import": "./dist/esm/this-entry-is-server-only.js",
+        "require": "./dist/cjs/this-entry-is-server-only.js"
+      },
       "import": "./dist/esm/next/index.js",
       "require": "./dist/cjs/next/index.js"
     },
@@ -58,6 +66,8 @@
     "verify:pack": "bun run scripts/verify-pack.ts",
     "prepublishOnly": "bun run build && bun run verify:pack",
     "test": "bun test",
+    "docs": "typedoc",
+    "docs:md": "typedoc --options typedoc.markdown.json",
     "storybook": "storybook dev -p 6106",
     "build:storybook": "storybook build -o storybook-static"
   },
@@ -76,6 +86,8 @@
     "react-dom": "19.2.8",
     "storybook": "^10.5.10",
     "tailwindcss": "^4.3.3",
+    "typedoc": "^0.28.20",
+    "typedoc-plugin-markdown": "^4.12.0",
     "typescript": "^5",
     "vite": "^8.2.2"
   },