@cosmoops/connect-sdk 0.1.0 → 0.3.0

package/README.md

@@ -211,25 +211,15 @@ cookie, `/session`, `/entitlements`, `/plans`, `/addons`, `/apps`, `/sessions`,
 | --- | --- | --- |
 | `CONNECT_API_KEY` | yes | server-side credential |
 | `CONNECT_CLIENT_ID` | yes | OAuth client id |
-| `NEXT_PUBLIC_CONNECT_CLIENT_ID` | yes | same value, for `<ConnectProvider>` |
 | `CONNECT_APP_URL` | no | non-production Connect instance |
 | `CONNECT_SESSION_COOKIE` | no | session cookie name |
 
 Register `{your origin}/api/connect/callback` as a redirect URI in the service's
 Setup tab — the one step this cannot do for you.
 
-Optional `next.config` wrapper, which warns at config load if the public client
-id is missing (a `NEXT_PUBLIC_*` that isn't set fails silently in the browser):
-
-```ts
-import { withConnect } from "@cosmoops/connect-sdk/next";
-export default withConnect({ });
-```
-
-That is all it does. It does **not** stand in for the route file — Next has no
-plugin API that contributes a route from a package, so
-`app/api/connect/[...connect]/route.ts` has to exist either way. The two are
-independent; using both is just the default setup.
+No `next.config.ts` changes needed, including `transpilePackages`: `dist/` is
+already ES2022 with `"use client"` hoisted, so Turbopack and webpack both
+consume it as-is.
 
 Reading the session server-side — no argument, no `headers()` dance:
 
@@ -255,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:
@@ -280,11 +332,14 @@ Then wrap your app:
 ```tsx
 import { ConnectProvider } from "@cosmoops/connect-sdk/client";
 
-<ConnectProvider clientId={process.env.NEXT_PUBLIC_CONNECT_CLIENT_ID!}>
-  {children}
-</ConnectProvider>
+<ConnectProvider>{children}</ConnectProvider>
 ```
 
+No `clientId` prop needed here either: the default sign-in flow bounces the
+browser to your own `/signin` route, which builds the authorize URL
+server-side. Pass `clientId` only if you also pass `redirectUri`, to build
+that URL yourself instead.
+
 ### Components
 
 ```tsx
@@ -357,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
@@ -46,8 +47,6 @@ export { ConnectPlansPage as default } from "@cosmoops/connect-sdk/client";
 const ENV_TEMPLATE = `# CosmoOps Connect - values come from your service's Setup tab.
 CONNECT_API_KEY=
 CONNECT_CLIENT_ID=
-# Same value as CONNECT_CLIENT_ID. Inlined at build time for <ConnectProvider>.
-NEXT_PUBLIC_CONNECT_CLIENT_ID=
 `;
 const SCAFFOLDS = [
     {
@@ -112,7 +111,7 @@ function runInit(argv = []) {
         console.log(`  ${marker}  ${(0, node_path_1.relative)(root, target)}  - ${scaffold.description}`);
     }
     const env = ensureEnv(root);
-    console.log(`  ${env === "skipped" ? "exists " : env === "appended" ? "updated" : "created"}  .env.local  - fill in the three values from your service's Setup tab`);
+    console.log(`  ${env === "skipped" ? "exists " : env === "appended" ? "updated" : "created"}  .env.local  - fill in the two values from your service's Setup tab`);
     // The two steps a scaffolder must not do for you: editing an existing layout
     // means parsing and rewriting JSX someone else wrote, and the redirect URI
     // lives in Connect, not in this repo.
@@ -125,7 +124,7 @@ Three things left, all one-time:
 
        <ConnectProvider>{children}</ConnectProvider>
 
-     No props: it reads NEXT_PUBLIC_CONNECT_CLIENT_ID.
+     No props needed.
 
   2. Add the theme to your global stylesheet, last of the three - Tailwind
      first, HeroUI's token layer next, so these values win:
@@ -140,26 +139,24 @@ Three things left, all one-time:
   3. Register {your origin}/api/connect/callback as a redirect URI in your
      service's Setup tab in Connect.
 
-Optionally, in next.config.ts:
-
-     import { withConnect } from "@cosmoops/connect-sdk/next";
-     export default withConnect({ });
-
-It checks NEXT_PUBLIC_CONNECT_CLIENT_ID at config load - the one variable whose
-absence fails silently in the browser rather than loudly on the server.
+No next.config.ts changes needed - not even transpilePackages: dist/ is
+already ES2022 with "use client" hoisted, so Turbopack and webpack consume it
+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.
@@ -167,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/client/provider.js

@@ -24,13 +24,12 @@ const ConnectContext = (0, react_1.createContext)(null);
  * origin, where `createConnectHandler` holds the credential.
  *
  * ```tsx
- * // Next.js - clientId comes from NEXT_PUBLIC_CONNECT_CLIENT_ID
  * <ConnectProvider>
  *   <App />
  * </ConnectProvider>
  * ```
  */
-function ConnectProvider({ clientId = process.env.NEXT_PUBLIC_CONNECT_CLIENT_ID ?? "", basePath = "/api/connect", redirectUri, appUrl = exports.CONNECT_APP_URL, fetch: fetchImpl, children, }) {
+function ConnectProvider({ clientId = "", basePath = "/api/connect", redirectUri, appUrl = exports.CONNECT_APP_URL, fetch: fetchImpl, children, }) {
     // One state cell, not three. `isLoading` is *derived* from "no result yet"
     // rather than set - a `setIsLoading(true)` at the top of an effect is a
     // synchronous setState inside that effect, which cascades an extra render

package/dist/cjs/next/index.js

@@ -41,7 +41,6 @@ exports.createConnectHandlers = createConnectHandlers;
 exports.GET = handle;
 exports.POST = handle;
 exports.getConnectSession = getConnectSession;
-exports.withConnect = withConnect;
 const client_js_1 = require("../server/client.js");
 const handler_js_1 = require("../server/handler.js");
 /**
@@ -66,27 +65,23 @@ const handler_js_1 = require("../server/handler.js");
  * <ConnectProvider>{children}</ConnectProvider>
  * ```
  *
- * Plus one line in `next.config.ts`, which is optional but catches the single
- * misconfiguration that fails silently:
- *
- * ```ts
- * import { withConnect } from "@cosmoops/connect-sdk/next";
- * export default withConnect({});
- * ```
- *
- * Configuration comes from the environment, so none of those files take
- * arguments:
+ * No `next.config.ts` changes needed - configuration comes from the
+ * environment, so neither file takes arguments:
  *
  * | Variable | Required | Purpose |
  * | --- | --- | --- |
  * | `CONNECT_API_KEY` | yes | server-side credential |
  * | `CONNECT_CLIENT_ID` | yes | OAuth client id |
- * | `NEXT_PUBLIC_CONNECT_CLIENT_ID` | yes | same value, for `<ConnectProvider>` |
  * | `CONNECT_APP_URL` | no | non-production Connect instance |
  * | `CONNECT_SESSION_COOKIE` | no | session cookie name |
  *
  * Register `{your origin}/api/connect/callback` as a redirect URI in the
  * service's Setup tab. That is the only step this cannot do for you.
+ *
+ * No `next.config.ts` changes needed either, including `transpilePackages`:
+ * `dist/` is already ES2022 with `"use client"` hoisted to the top of every
+ * browser file, so Turbopack and webpack both consume it as-is - adding the
+ * entry only costs build time.
  */
 const DEFAULT_COOKIE = "connect_session";
 function requireEnv(name) {
@@ -266,45 +261,6 @@ async function getConnectSession(request, options = {}) {
         return 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({ });
- * ```
- */
-function withConnect(config = {}) {
-    if (!process.env.NEXT_PUBLIC_CONNECT_CLIENT_ID && process.env.NODE_ENV !== "test") {
-        console.warn("[@cosmoops/connect-sdk] NEXT_PUBLIC_CONNECT_CLIENT_ID is not set - <ConnectProvider> will not be able to start a sign-in.");
-    }
-    return config;
-}
 var handler_js_2 = require("../server/handler.js");
 Object.defineProperty(exports, "createConnectHandler", { enumerable: true, get: function () { return handler_js_2.createConnectHandler; } });
 var client_js_2 = require("../server/client.js");

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
@@ -41,8 +42,6 @@ export { ConnectPlansPage as default } from "@cosmoops/connect-sdk/client";
 const ENV_TEMPLATE = `# CosmoOps Connect - values come from your service's Setup tab.
 CONNECT_API_KEY=
 CONNECT_CLIENT_ID=
-# Same value as CONNECT_CLIENT_ID. Inlined at build time for <ConnectProvider>.
-NEXT_PUBLIC_CONNECT_CLIENT_ID=
 `;
 const SCAFFOLDS = [
     {
@@ -107,7 +106,7 @@ export function runInit(argv = []) {
         console.log(`  ${marker}  ${relative(root, target)}  - ${scaffold.description}`);
     }
     const env = ensureEnv(root);
-    console.log(`  ${env === "skipped" ? "exists " : env === "appended" ? "updated" : "created"}  .env.local  - fill in the three values from your service's Setup tab`);
+    console.log(`  ${env === "skipped" ? "exists " : env === "appended" ? "updated" : "created"}  .env.local  - fill in the two values from your service's Setup tab`);
     // The two steps a scaffolder must not do for you: editing an existing layout
     // means parsing and rewriting JSX someone else wrote, and the redirect URI
     // lives in Connect, not in this repo.
@@ -120,7 +119,7 @@ Three things left, all one-time:
 
        <ConnectProvider>{children}</ConnectProvider>
 
-     No props: it reads NEXT_PUBLIC_CONNECT_CLIENT_ID.
+     No props needed.
 
   2. Add the theme to your global stylesheet, last of the three - Tailwind
      first, HeroUI's token layer next, so these values win:
@@ -135,26 +134,24 @@ Three things left, all one-time:
   3. Register {your origin}/api/connect/callback as a redirect URI in your
      service's Setup tab in Connect.
 
-Optionally, in next.config.ts:
-
-     import { withConnect } from "@cosmoops/connect-sdk/next";
-     export default withConnect({ });
-
-It checks NEXT_PUBLIC_CONNECT_CLIENT_ID at config load - the one variable whose
-absence fails silently in the browser rather than loudly on the server.
+No next.config.ts changes needed - not even transpilePackages: dist/ is
+already ES2022 with "use client" hoisted, so Turbopack and webpack consume it
+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.
@@ -162,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/client/provider.js

@@ -12,13 +12,12 @@ const ConnectContext = createContext(null);
  * origin, where `createConnectHandler` holds the credential.
  *
  * ```tsx
- * // Next.js - clientId comes from NEXT_PUBLIC_CONNECT_CLIENT_ID
  * <ConnectProvider>
  *   <App />
  * </ConnectProvider>
  * ```
  */
-export function ConnectProvider({ clientId = process.env.NEXT_PUBLIC_CONNECT_CLIENT_ID ?? "", basePath = "/api/connect", redirectUri, appUrl = CONNECT_APP_URL, fetch: fetchImpl, children, }) {
+export function ConnectProvider({ clientId = "", basePath = "/api/connect", redirectUri, appUrl = CONNECT_APP_URL, fetch: fetchImpl, children, }) {
     // One state cell, not three. `isLoading` is *derived* from "no result yet"
     // rather than set - a `setIsLoading(true)` at the top of an effect is a
     // synchronous setState inside that effect, which cascades an extra render

package/dist/esm/next/index.js

@@ -22,27 +22,23 @@ import { createConnectHandler } from "../server/handler.js";
  * <ConnectProvider>{children}</ConnectProvider>
  * ```
  *
- * Plus one line in `next.config.ts`, which is optional but catches the single
- * misconfiguration that fails silently:
- *
- * ```ts
- * import { withConnect } from "@cosmoops/connect-sdk/next";
- * export default withConnect({});
- * ```
- *
- * Configuration comes from the environment, so none of those files take
- * arguments:
+ * No `next.config.ts` changes needed - configuration comes from the
+ * environment, so neither file takes arguments:
  *
  * | Variable | Required | Purpose |
  * | --- | --- | --- |
  * | `CONNECT_API_KEY` | yes | server-side credential |
  * | `CONNECT_CLIENT_ID` | yes | OAuth client id |
- * | `NEXT_PUBLIC_CONNECT_CLIENT_ID` | yes | same value, for `<ConnectProvider>` |
  * | `CONNECT_APP_URL` | no | non-production Connect instance |
  * | `CONNECT_SESSION_COOKIE` | no | session cookie name |
  *
  * Register `{your origin}/api/connect/callback` as a redirect URI in the
  * service's Setup tab. That is the only step this cannot do for you.
+ *
+ * No `next.config.ts` changes needed either, including `transpilePackages`:
+ * `dist/` is already ES2022 with `"use client"` hoisted to the top of every
+ * browser file, so Turbopack and webpack both consume it as-is - adding the
+ * entry only costs build time.
  */
 const DEFAULT_COOKIE = "connect_session";
 function requireEnv(name) {
@@ -236,44 +232,5 @@ export async function getConnectSession(request, options = {}) {
         return 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 function withConnect(config = {}) {
-    if (!process.env.NEXT_PUBLIC_CONNECT_CLIENT_ID && process.env.NODE_ENV !== "test") {
-        console.warn("[@cosmoops/connect-sdk] NEXT_PUBLIC_CONNECT_CLIENT_ID is not set - <ConnectProvider> will not be able to start a sign-in.");
-    }
-    return config;
-}
 export { createConnectHandler } from "../server/handler.js";
 export { ConnectClient } from "../server/client.js";

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

@@ -7,7 +7,12 @@ export interface ConnectSession {
     serviceRole: ServiceRole | null;
 }
 export interface ConnectContextValue {
-    /** Public OAuth client id. Safe in a browser - it goes in the authorize URL. */
+    /**
+     * Public OAuth client id, if `clientId` was passed to `<ConnectProvider>` -
+     * empty string otherwise. Safe in a browser regardless: it only ever goes
+     * into the authorize URL. Most integrations never read this - it exists for
+     * the explicit-`redirectUri` flow, see `ConnectProviderProps.clientId`.
+     */
     clientId: string;
     /** Connect's own origin, for deep links out to Profile, Billing and the catalog. */
     appUrl: string;
@@ -58,9 +63,11 @@ 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.
+     * Not needed for the default sign-in flow: `signIn()` with no `redirectUri`
+     * bounces the browser to your own `/signin` route, which already knows
+     * `client_id` server-side (`CONNECT_CLIENT_ID`) and builds the authorize URL
+     * itself - the browser never needs it. Pass this only alongside an explicit
+     * `redirectUri`, when you're building that URL yourself instead.
      */
     clientId?: string;
     /** Where `createConnectHandler` is mounted in your app. Must match its `basePath`. */
@@ -91,7 +98,6 @@ export interface ConnectProviderProps {
  * origin, where `createConnectHandler` holds the credential.
  *
  * ```tsx
- * // Next.js - clientId comes from NEXT_PUBLIC_CONNECT_CLIENT_ID
  * <ConnectProvider>
  *   <App />
  * </ConnectProvider>

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

@@ -97,40 +97,6 @@ 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";

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.1.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"
   },