@cosmoops/connect-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,34 @@
+CosmoOps Proprietary License
+
+Copyright (c) 2026 CosmoOps. All rights reserved.
+
+This software and its accompanying documentation (the "Software") are the
+confidential and proprietary property of CosmoOps.
+
+NO LICENSE IS GRANTED.
+
+Except for CosmoOps and those it has authorised in writing, no person or
+entity may, in whole or in part, for any purpose whether personal,
+educational, non-commercial or commercial:
+
+  (a) use, run, execute or evaluate the Software;
+  (b) copy, reproduce, publish, distribute, sublicense, sell, rent, lease or
+      otherwise transfer the Software;
+  (c) modify, adapt, translate, or create derivative works of the Software;
+  (d) reverse engineer, decompile or disassemble the Software, except to the
+      extent that this restriction is prohibited by applicable law; or
+  (e) remove, obscure or alter this notice or any proprietary marking.
+
+Publication of the Software to a public package registry is a distribution
+convenience for CosmoOps and its authorised integrators. It is not an offer,
+and it does not place the Software in the public domain, make it open source,
+or grant any licence by implication, estoppel or otherwise.
+
+To request authorisation, contact legal@cosmoops.com.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+COSMOOPS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,446 @@
+# @cosmoops/connect-sdk
+
+Official client for the **CosmoOps Connect service-partner API** (`/api/v1/service/*`).
+
+```bash
+npm install @cosmoops/connect-sdk
+```
+
+Two entry points, and the split is a security boundary, not a preference:
+
+| Import | Runs in | Holds the API key |
+| --- | --- | --- |
+| `@cosmoops/connect-sdk/server` | your backend | **yes** |
+| `@cosmoops/connect-sdk/client` | the browser | never |
+| `@cosmoops/connect-sdk/next` | your backend | **yes** (Next.js plug-and-play) |
+| `@cosmoops/connect-sdk` | anywhere | types + `ConnectError` only |
+
+The browser half never sees a credential. It calls your own origin, and
+`createConnectHandler` — mounted in your backend — is what talks to Connect.
+
+```
+Browser  ──►  your backend  ──►  Connect
+(client)      (createConnectHandler + server client, holds the key)
+```
+
+## Server setup
+
+One credential does three jobs — the API key plaintext from your service's Setup tab is also your OAuth2 `client_secret` and the key your `id_token` is signed with. Revoking it revokes all three.
+
+```ts
+import { ConnectClient } from "@cosmoops/connect-sdk/server";
+
+export const connect = new ConnectClient({
+  apiKey: process.env.CONNECT_API_KEY!,
+  clientId: process.env.CONNECT_CLIENT_ID, // only needed for identity.*
+});
+```
+
+An API key or a `sessionToken` in browser code is a leaked credential.
+
+## Login with Connect
+
+**1. Send the user out.**
+
+```ts
+import { createState } from "@cosmoops/connect-sdk/server";
+
+const state = createState();
+await saveToSession({ state });
+
+redirect(connect.identity.authorizeUrl({
+  redirectUri: "https://you.example/callback",
+  state,
+  // prompt: "create"  ← opens registration instead of sign-in
+}));
+```
+
+**2. Handle the callback.**
+
+```ts
+if (query.state !== savedState) throw new Error("state mismatch");
+
+if (query.error === "login_required") return retrySignIn(); // normal — not an error
+if (query.error) return showCancelled();
+
+const session = await connect.identity.exchangeCode({
+  code: query.code,
+  redirectUri: "https://you.example/callback",
+});
+
+await connect.identity.verifyIdToken(session.idToken);
+
+await saveToSession({ sessionToken: session.sessionToken });
+```
+
+**3. On each later request.**
+
+```ts
+const { user, serviceRole } = await connect.identity.getUser(sessionToken);
+
+if (!serviceRole.granted.includes("invoice:write")) return forbidden();
+```
+
+**4. On logout.**
+
+```ts
+await connect.identity.logout(sessionToken);
+```
+
+## Gate on entitlements
+
+```ts
+import { blockingBlockers } from "@cosmoops/connect-sdk";  // isomorphic
+
+const readiness = await connect.entitlements.getReadiness(orgId);
+
+if (!readiness.ready) {
+  const [blocker] = blockingBlockers(readiness);
+  return showBlocked(blocker.message, blocker.resolveUrl); // resolveUrl links into Connect
+}
+
+if (await connect.entitlements.hasFeature(orgId, "campaign-module")) {
+  // ...
+}
+```
+
+Branch on `blocker.code`, never on `message`. Treat an unrecognised code as blocking — the list grows.
+
+## Meter usage
+
+```ts
+const { balance } = await connect.billing.consumeAddon({
+  organizationId: orgId,
+  addonId: "api-calls",
+  quantity: 1,
+});
+```
+
+An `Idempotency-Key` is sent on every consume, so a retry can't double-debit.
+
+## Errors
+
+Everything throws `ConnectError` with a stable `code`.
+
+```ts
+import { isConnectError } from "@cosmoops/connect-sdk";  // isomorphic
+
+try {
+  await connect.identity.getUser(sessionToken);
+} catch (error) {
+  if (isConnectError(error) && error.isSessionExpired) return redirectToSignIn();
+  throw error;
+}
+```
+
+`isRetryable` covers throttling, 5xx and network failures. The SDK already retries those for safe requests; the flag is for deciding whether to queue your own.
+
+## Namespaces
+
+| | |
+| --- | --- |
+| `identity` | `authorizeUrl` · `exchangeCode` · `verifyIdToken` · `getUser` · `logout` |
+| `access` | `getUserRoles` · `listRoles` |
+| `entitlements` | `getReadiness` · `getSubscription` · `hasFeature` |
+| `billing` | `listPlans` · `getAddonUsage` · `consumeAddon` |
+| `drive` | `upload` · `getFileUrl` · `getPreviewUrl` |
+| `ai` | `chat` · `extract` |
+| `otp` | `send` · `verify` |
+| `logs` | `write` |
+| `apps` | `list` |
+| `sessions` | `list` · `revoke` · `revokeOthers` |
+
+### Attributing a log to a user
+
+```ts
+await client.logs.write({
+  message: "campaign sent",
+  metadata: { campaignId },
+  sessionToken,          // that user's Connect session token
+});
+```
+
+Both scopes on the stored entry come from something verified, never from your payload: `serviceId` from your API key, and `userId` from this token — which Connect checks is unrevoked, unexpired, and **minted for your service** before attributing anything. **There is no `userId` field to send.** An actor a caller can type is not an actor worth recording, and a conformance test fails the build if one ever appears in the server schema.
+
+`write` returns `{ delivered, attributed }` and never throws. `attributed: false` with `delivered: true` means the token had expired (~15 days) or been revoked and the line was stored *without* a user — deliberately kept rather than rejected, because losing telemetry over a failed attribution is the worse of the two outcomes.
+
+## Options
+
+```ts
+new ConnectClient({
+  apiKey,
+  clientId,
+  baseUrl,      // default https://connect.cosmoops.com
+  timeoutMs,    // default 20000, per attempt
+  maxRetries,   // default 2, safe requests only
+  fetch,        // bring your own instrumented fetch
+});
+```
+
+## Next.js — plug and play
+
+Two files, no arguments.
+
+```ts
+// app/api/connect/[...connect]/route.ts
+export { GET, POST } from "@cosmoops/connect-sdk/next";
+```
+
+```tsx
+// app/layout.tsx
+import { ConnectProvider } from "@cosmoops/connect-sdk/client";
+
+<ConnectProvider>{children}</ConnectProvider>
+```
+
+```css
+/* app/globals.css */
+@import "tailwindcss";
+@import "@heroui/styles";
+@import "@cosmoops/connect-sdk/theme.css";
+```
+
+`npx @cosmoops/connect-sdk init` writes the route file and a `/plans` page for
+you; the provider and the stylesheet are the two it won't edit on your behalf.
+
+That gives you the whole round trip — `/signin`, `/callback`, an httpOnly session
+cookie, `/session`, `/entitlements`, `/plans`, `/addons`, `/apps`, `/sessions`,
+`/logout`. Config comes from the environment:
+
+| 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 — 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.
+
+Reading the session server-side — no argument, no `headers()` dance:
+
+```tsx
+// app/dashboard/page.tsx
+import { getConnectSession } from "@cosmoops/connect-sdk/next";
+import { redirect } from "next/navigation";
+
+export default async function DashboardPage() {
+  const session = await getConnectSession(); // UserResponse | null
+  if (!session) redirect("/api/connect/signin?next=/dashboard");
+  return <h1>{session.user.organizationName}</h1>;
+}
+```
+
+Pass a `Request` — `getConnectSession(request)` — anywhere `next/headers` does
+not exist: a framework-agnostic handler, a custom server, a test.
+
+It reads `cookies()` transitively, so under `cacheComponents` it belongs inside
+a `<Suspense>` boundary like any other request-scoped read. A page that awaits
+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.
+
+## Other frameworks
+
+Mount the bridge once in your backend:
+
+```ts
+// app/api/connect/[...route]/route.ts
+import { createConnectHandler } from "@cosmoops/connect-sdk/server";
+import { connect } from "@/lib/connect";
+
+const handler = createConnectHandler({
+  client: connect,
+  session: {
+    read: async (req) => (await cookies()).get("connect_session")?.value ?? null,
+    clear: (req, res) => res.headers.append("set-cookie", "connect_session=; Max-Age=0; Path=/"),
+  },
+});
+
+export { handler as GET, handler as POST };
+```
+
+Then wrap your app:
+
+```tsx
+import { ConnectProvider } from "@cosmoops/connect-sdk/client";
+
+<ConnectProvider clientId={process.env.NEXT_PUBLIC_CONNECT_CLIENT_ID!}>
+  {children}
+</ConnectProvider>
+```
+
+### Components
+
+```tsx
+import {
+  ConnectLoginButton, ConnectRegisterButton,
+  ConnectUserMenu, ConnectAppsGrid, ConnectPlans,
+} from "@cosmoops/connect-sdk/client";
+
+// Top bar — the pair swaps automatically on sign-in state
+<ConnectAppsGrid />
+<ConnectLoginButton />
+<ConnectUserMenu />
+
+// Pricing page
+<ConnectPlans />
+```
+
+| Component | What it does |
+| --- | --- |
+| `ConnectLoginButton` · `ConnectRegisterButton` | "Continue with Connect", in the shape people know from Google. Render nothing when signed in. |
+| `ConnectUserMenu` | Avatar, name, workspace. Profile, Manage subscription and Open Connect each open Connect in a new tab; Sign out acts in place. Renders nothing when signed out. |
+| `ConnectAppsGrid` | Google-style launcher — grid icon opening a modal of every app this workspace can open. |
+| `ConnectPlans` | Monthly/annual toggle, features, add-ons, live discount, coupon field, and the subscribe / upgrade / downgrade / cancel flow. |
+| `ConnectPlansPage` | A whole `/plans` page — readiness banner, current subscription, and the grid. What `connect-sdk init` scaffolds. |
+| `ConnectSubscribeDialog` | The review step `ConnectPlans` opens — plan, GST, what happens to the current cycle. Exported so you can drive the flow from your own pricing page. |
+| `ConnectSubscriptionGate` | Renders your module for a subscribed workspace, and `ConnectNoSubscriptionCard` for everyone else. Never flashes the upsell while loading. |
+| `ConnectNoSubscriptionCard` · `ConnectSubscriptionCard` | The same slot, unsubscribed and subscribed. Plan, status, renewal date, seats, and one way into Connect. |
+| `ConnectReadinessBanner` · `ConnectReadinessGate` | Every gate between this workspace and your service — KYC, payment method, seat headroom — each with the Connect screen that fixes it. |
+| `ConnectFeatureGate` | Renders a module only when `plan.features` includes its key. |
+| `ConnectTrialBanner` | A running trial and the date it converts. Renders nothing otherwise. |
+| `ConnectAccountSessions` | Every device signed into this Connect account, with revoke. |
+| `ConnectUsageMeter` | Remaining balance of each consumable add-on, with overage and carry-forward. |
+| `ConnectManageSubscriptionButton` · `ConnectInvoicesButton` · `ConnectProfileButton` · `ConnectHomeButton` · `ConnectSignOutButton` | The menu items as standalone buttons — Connect's Billing, Invoices and Profile. |
+| `ConnectLogo` | The shared lockup — your `icon` on the CosmoOps badge, `cosmo·ops` beside it, your `name` underneath. |
+
+### Hooks
+
+`useConnect` · `useConnectUser` · `useConnectEntitlements` · `useConnectPlans` · `useConnectApps` · `useConnectAddonUsage` · `useConnectSessions` · `useConnectResource` · `useConnectFeature` · `useConnectCheckout`
+
+### Metering
+
+```tsx
+await client.billing.consumeAddon({ organizationId, addonId: "addon_sms", quantity: 1 });  // server
+<ConnectUsageMeter />                                                                     // browser
+```
+
+The meter reads the same balance `consumeAddon` debits (`addons:read`, separate from `addons:consume` so a key that only renders a meter cannot spend the balance down). It shows `balance` against `includedPerCycle` and never a "used" figure: with `carryForward` a balance survives the cycle boundary, so `included − balance` can go negative — a meter running backwards.
+
+Invoices stay a deep link (`ConnectInvoicesButton`). A GST tax invoice is a legal document emailed and downloaded from one place; a partner-rendered copy would be a second version of a record that must have exactly one.
+
+### Plan features: label vs key
+
+The catalogue read (`useConnectPlans`, `<ConnectPlans />`) reports `features` as `{ key, name, description }` — **render `name`, gate on `key`**. The subscription read (`useConnectEntitlements`, `hasFeature`, `<ConnectFeatureGate>`) reports `features` as a bare `string[]` of keys, and stays that way: that one is a contract your backend compares against, and a display label is neither stable nor comparable. `name` falls back to the key for a plan older than its service's feature catalog.
+
+### Gates
+
+```tsx
+<ConnectReadinessBanner />                       {/* KYC, payment method, seats — each with a fix */}
+<ConnectSubscriptionGate><Dashboard /></ConnectSubscriptionGate>
+<ConnectFeatureGate feature="advanced_reports"><Reports /></ConnectFeatureGate>
+```
+
+All three render `loading` — never the fallback — while the answer is unknown, so a paying customer is never flashed an upsell for something they already have.
+
+**They are UX gates, not security boundaries.** Everything they read reaches your own origin and a browser can ignore it. The authoritative check is on your server: `client.entitlements.getReadiness(orgId)` and `client.entitlements.hasFeature(orgId, feature)`.
+
+### Scaffolding
+
+```bash
+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.
+
+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.
+
+### Subscribe, upgrade, downgrade, cancel
+
+`<ConnectPlans />` runs all three. Pressing a plan's action opens a review step — the plan, its GST-inclusive price, and what happens to the cycle the customer is part-way through — and confirming opens Connect on the confirmation screen **for that exact plan**, not a catalogue they have to search again. The page then watches `/entitlements` and repaints itself once the change lands, so nobody has to be told to refresh.
+
+To drive it from your own pricing page instead, the two pieces are exported:
+
+```tsx
+import { useConnectCheckout, buildCheckoutUrl, useConnect, useConnectEntitlements }
+  from "@cosmoops/connect-sdk/client";
+
+const { appUrl } = useConnect();
+const { data } = useConnectEntitlements();
+const checkout = useConnectCheckout();
+
+<button
+  onClick={() =>
+    checkout.start({
+      url: buildCheckoutUrl({
+        appUrl,
+        serviceId: data!.subscription.serviceId,
+        planId: "plan_growth_m",
+        // Present ⇒ change this subscription's plan; absent ⇒ first subscribe.
+        subscriptionId: data!.subscription.subscription?.id ?? null,
+      }),
+      isSettled: (next) => next.subscription.plan?.id === "plan_growth_m",
+    })
+  }
+>
+  Upgrade
+</button>
+```
+
+`checkout.status` moves `idle → waiting → completed | abandoned`, plus `blocked` if the browser refused the window (render `checkout.url` as a link). **A closed window is never read as success** — only the entitlement changing is, because "paid and closed it" and "opened it and thought better of it" look identical from here.
+
+Cancelling uses the same machinery via `buildCancelUrl`. There is no *resume*: Connect has no uncancel path, so a subscription already set to cancel gets a statement of when access ends, not a button that cannot work.
+
+### Logo
+
+```tsx
+import { ConnectLogo } from "@cosmoops/connect-sdk/client";
+import { Truck } from "lucide-react";
+
+<ConnectLogo name="Dispatch" icon={<Truck />} />
+```
+
+Each platform passes only what differs — `name` and `icon`. Mark geometry, wordmark, separator and accent come from one place, so the family reads as one product. Sizes are `em`-based: `className="text-xl"` scales the whole lockup, which is why there's no `size` prop. `collapsed` gives the mark alone.
+
+### Theming
+
+```css
+@import "tailwindcss";
+@import "@heroui/styles";
+@import "@cosmoops/connect-sdk/theme.css";
+```
+
+One shared **HeroUI v3** theme for every service platform. The components paint with semantic tokens only — `accent`, `muted`, `surface`, `separator`, `danger` — never a hardcoded colour, so one edit to the theme restyles all of them everywhere at once. To diverge on brand, redefine individual tokens *after* the import rather than forking the file.
+
+Requires `@heroui/react` and `lucide-react` as peers (optional — server-only consumers need neither).
+
+### Why payment happens on Connect
+
+The *flow* is in your app; the *payment* is not. A plan change is not one write — it re-runs the readiness gates, prices proration against accumulated credit, re-checks the RBI mandate ceiling for the new amount, and issues a GST invoice. Connect owns that sequence end to end, and a partner-side implementation would be a second copy of it that drifts. It would also mean a browser holding your credentials could move money, which is the one thing the bridge exists to prevent.
+
+So the hand-off is a URL, and Connect renders it as a modal over the relevant page (an intercepted parallel route) — the customer lands on the confirmation for the plan they picked, and returns to a subscription that is already correct.
+
+## Development
+
+```bash
+bun test              # server suite - hermetic, no network
+bun run storybook     # client components against a mock bridge, port 6106
+bun run build         # dual CJS/ESM + types
+```
+
+Server tests drive the injectable `fetch` seam, so nothing reaches Connect.
+Storybook renders the real `ConnectProvider` and substitutes only `fetch` — the
+same seam the production bridge sits behind — so loading, error and empty
+states are exercised for real. `.storybook/theme.css` is a sample host theme:
+change it and every story should move together. If one doesn't, it has a
+hardcoded colour.
+
+## License
+
+Proprietary. See [LICENSE](./LICENSE) — no rights are granted to anyone outside CosmoOps and its authorised integrators.

package/dist/cjs/cli/bin.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * The `connect-sdk` executable.
+ *
+ * A thin wrapper so `init.ts` stays importable and testable - a module that
+ * calls `process.exit` at import time cannot be unit tested, and this is the
+ * only file that does.
+ *
+ * The shebang is added by `scripts/finalize-dist.ts`: TypeScript strips leading
+ * comments it does not recognise as directives, and a `bin` without one is run
+ * by the shell rather than by Node.
+ */
+const init_js_1 = require("./init.js");
+process.exit((0, init_js_1.main)(process.argv.slice(2)));

package/dist/cjs/cli/init.js

@@ -0,0 +1,179 @@
+"use client";
+"use strict";
+/**
+ * `npx @cosmoops/connect-sdk init` - writes the Connect wiring into a Next.js
+ * App Router project.
+ *
+ * ## Why this is a CLI and not a plugin
+ *
+ * Next has no plugin API that injects routes. `next.config` can rewrite and
+ * redirect, but both need a real route to point at, and there is no hook that
+ * contributes a `page.tsx` from a node_module - the App Router discovers routes
+ * by walking the project's own `app/` directory and nothing else. So a package
+ * cannot add `/plans` to an app by being installed, however much one would like
+ * it to.
+ *
+ * What it *can* do is make the file that must exist a single line, and then
+ * write that file for you. `ConnectPlansPage` is the first half; this is the
+ * second. The result is the same as a plugin from the developer's side - one
+ * command and the page is there - without pretending an extension point exists.
+ *
+ * Nothing here overwrites. Every file that already exists is reported as
+ * skipped, so re-running after a partial setup is safe and running it on an
+ * app that already has Connect wired up does nothing at all.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runInit = runInit;
+exports.main = main;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+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
+// credential. GET and POST are the same function; the bridge routes on method
+// and path itself.
+export { GET, POST } from "@cosmoops/connect-sdk/next";
+`;
+const PLANS_PAGE = `"use client";
+
+// The full pricing page: readiness banner, current subscription, plan grid, and
+// the subscribe / upgrade / downgrade flow.
+//
+// Swap this for \`<ConnectPlansPage title="..." />\` (or compose \`ConnectPlans\`
+// with the other exports) whenever you want your own copy or layout.
+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 = [
+    {
+        path: (0, node_path_1.join)("api", "connect", "[...connect]", "route.ts"),
+        contents: BRIDGE_ROUTE,
+        description: "Connect bridge route handler",
+    },
+    {
+        path: (0, node_path_1.join)("plans", "page.tsx"),
+        contents: PLANS_PAGE,
+        description: "/plans pricing page",
+    },
+];
+/**
+ * `app/` or `src/app/`, whichever this project uses.
+ *
+ * Both are official layouts and neither is more correct, so guessing wrong
+ * would scatter routes into a directory Next never reads - a failure that looks
+ * like "the page just 404s" and takes a while to trace. Refusing to guess is
+ * better than a default.
+ */
+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;
+}
+function write(file, contents) {
+    if ((0, node_fs_1.existsSync)(file))
+        return "skipped";
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(file), { recursive: true });
+    (0, node_fs_1.writeFileSync)(file, contents);
+    return "written";
+}
+/** Appends the Connect block to `.env.local`, or creates it - never rewrites an existing value. */
+function ensureEnv(root) {
+    const file = (0, node_path_1.join)(root, ".env.local");
+    if (!(0, node_fs_1.existsSync)(file)) {
+        (0, node_fs_1.writeFileSync)(file, ENV_TEMPLATE);
+        return "written";
+    }
+    const current = (0, node_fs_1.readFileSync)(file, "utf8");
+    if (current.includes("CONNECT_CLIENT_ID"))
+        return "skipped";
+    (0, node_fs_1.writeFileSync)(file, `${current.trimEnd()}\n\n${ENV_TEMPLATE}`);
+    return "appended";
+}
+function runInit(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 init ./my-app");
+        return 1;
+    }
+    console.log(`[connect-sdk] Wiring Connect into ${(0, node_path_1.relative)(process.cwd(), appDir) || appDir}\n`);
+    for (const scaffold of SCAFFOLDS) {
+        const target = (0, node_path_1.join)(appDir, scaffold.path);
+        const result = write(target, scaffold.contents);
+        const marker = result === "written" ? "created" : "exists ";
+        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`);
+    // 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.
+    console.log(`
+Three things left, all one-time:
+
+  1. Wrap your app in the provider - app/layout.tsx:
+
+       import { ConnectProvider } from "@cosmoops/connect-sdk/client";
+
+       <ConnectProvider>{children}</ConnectProvider>
+
+     No props: it reads NEXT_PUBLIC_CONNECT_CLIENT_ID.
+
+  2. Add the theme to your global stylesheet, last of the three - Tailwind
+     first, HeroUI's token layer next, so these values win:
+
+       @import "tailwindcss";
+       @import "@heroui/styles";
+       @import "@cosmoops/connect-sdk/theme.css";
+
+     It has to be imported from your *own* CSS, not from node_modules, or
+     Tailwind roots its content scan inside node_modules and skips your app.
+
+  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.
+
+Then <ConnectPlans />, <ConnectSubscriptionGate>, <ConnectFeatureGate> and the
+rest work anywhere below the provider, and getConnectSession() reads the same
+session from any Server Component.
+`);
+    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.
+ *
+ * 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
+ * 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.
+ */
+function main(argv) {
+    const [first, ...rest] = argv;
+    if (first === "--help" || first === "-h") {
+        console.log("Usage: connect-sdk init [project-dir]");
+        return 0;
+    }
+    if (first === "init")
+        return runInit(rest);
+    if (!first || (0, node_fs_1.existsSync)(first))
+        return runInit(argv);
+    console.error(`[connect-sdk] Unknown command "${first}". Try: connect-sdk init`);
+    return 1;
+}