@commish/next 0.1.0-beta.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oftring Ventures LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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 THE
+AUTHORS OR COPYRIGHT HOLDERS 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,161 @@
+# @commish/next
+
+MIT-licensed Next.js App Router integration for permanent Commish TEST and LIVE modes.
+This source checkpoint is verified with Node 24.15.0, Next 16.3.4 and React 19.2.8.
+It does not establish npm availability or acceptance against a hosted Commish API.
+Use the exact paired `0.1.0-beta.10` SDK/Next packages and keep the consumer lockfile.
+Accepted candidate tarballs remain available for prepublication qualification.
+
+## Capture route
+
+Set `COMMISH_API_URL` to the selected mode's API base, including `/api/v1`, and
+`COMMISH_SECRET_KEY` to its application-scoped secret. Keep both on the server.
+Only the publishable key and application ID belong in the public variables below.
+Create `app/api/commish/attribution/route.ts` (or under `src/app`):
+
+```ts
+import { createAttributionHandler } from "@commish/next";
+
+export const runtime = "nodejs";
+export const POST = createAttributionHandler({
+  apiUrl: process.env.COMMISH_API_URL,
+  secretKey: process.env.COMMISH_SECRET_KEY,
+});
+```
+
+The route exchanges the referral with Commish and stores successful attribution
+in an HttpOnly cookie. Configure the API base explicitly for the selected deployment;
+the helper otherwise uses its default Commish API origin.
+
+## Application layout
+
+Wrap the existing content in `app/layout.tsx` (or `src/app/layout.tsx`):
+
+```tsx
+import { CommishProvider } from "@commish/next/react";
+import type { ReactNode } from "react";
+
+export default function Layout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <CommishProvider
+          publishableKey={process.env.NEXT_PUBLIC_COMMISH_PUBLISHABLE_KEY!}
+          applicationId={process.env.NEXT_PUBLIC_COMMISH_APPLICATION_ID!}
+        >
+          {children}
+        </CommishProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+The provider captures on client navigation through the same-origin route above.
+Set `capturePath` on the provider if that route uses another same-origin path.
+Successful capture removes `commish_ref` while preserving navigation state;
+failure keeps the referral for retry. Wait for capture before starting Checkout.
+
+## Agent-driven installation and Checkout
+
+In your existing authenticated server Checkout route, await
+`withCommishStripeMetadata(params)` from `@commish/next` before passing the result
+to your existing Stripe Checkout integration. The helper preserves other
+parameters and applies the request's attribution to payment or subscription
+metadata. `getCommishAttribution()` reads that cookie directly; both helpers
+require a Next request context. The root export is blocked in browser builds.
+The provider belongs at `@commish/next/react`; `@commish/next/browser` also exports
+`captureReferral` for direct browser integration.
+
+After installing an accepted pair, run from the consumer project root:
+
+```sh
+pnpm exec commish-next --json          # inspect the plan; no writes
+pnpm exec commish-next --write --json  # install the integration files
+```
+
+The CLI creates the capture route above and `app/commish-provider.tsx` (under
+`src/app` when there is no root `app`). JavaScript apps receive `.js`/`.jsx`
+files; the installer does not enable TypeScript. Repeated runs preserve identical files;
+custom files, conflicting extensions and symbolic links stop installation before
+writing. It never reads or writes credentials. Supply matching application keys
+for the selected mode through your environment configuration.
+
+The coding agent must finish these existing application edits:
+
+1. Import `CommishRootProvider` from `./commish-provider` in the root layout and
+   wrap its existing children. Preserve other providers, metadata and layout content.
+2. Add the awaited metadata helper to the authenticated Checkout handler as above.
+3. Build, then exercise a TEST referral through capture and Checkout. Successful
+   capture must set the HttpOnly cookie; Checkout must carry its attribution.
+
+JSON output lists file outcomes, required environment variable names and next
+steps. `files_installed` means those files exist; `integrationVerified: false`
+explicitly leaves wiring, configuration and end-to-end verification outstanding.
+If a custom route/provider already exists, integrate using the examples above;
+the installer will not overwrite it or guess at customer code.
+
+Package installation does not connect a Stripe account, configure a program,
+activate a creator, or prove a conversion. Complete the hosted TEST setup and
+record its acceptance separately from package build and installation evidence.
+
+## Provision TEST or LIVE credentials from the CLI
+
+An owner or admin can authorize an agent-driven setup without copying a secret
+from the dashboard:
+
+```sh
+pnpm exec commish-next setup \
+  --workspace wrk_your_workspace_id \
+  --application-name "Your product" \
+  --key-label "Local agent setup" \
+  --output .env.commish \
+  --json
+```
+
+The command defaults to TEST; add `--mode live` for LIVE credentials. LIVE requires
+current workspace eligibility and provider readiness at approval and exchange;
+it never falls back to TEST. The command generates the selected mode's keys on the developer's
+machine, opens a ten-minute approval page on `https://app.commish.sh`, and polls
+for the approved exchange. The browser requires an authenticated workspace owner
+or admin with a recent authenticator check. Only hashes and the publishable key
+cross the browser boundary; Commish never receives or stores the raw secret.
+
+After approval, the CLI atomically creates the explicitly named output with mode
+`0600`. It never overwrites an existing path. The file contains
+`COMMISH_API_URL`, `COMMISH_SECRET_KEY`,
+`NEXT_PUBLIC_COMMISH_PUBLISHABLE_KEY`, and
+`NEXT_PUBLIC_COMMISH_APPLICATION_ID`. Add that path to the product's local secret
+handling policy; do not commit it. An interrupted exchange can safely retry the
+same verifier and receives the same application and key.
+
+Use `--no-open` when the controlling agent will present the printed approval URL
+itself. For a trusted local Commish runtime, `--app-url` accepts an explicit
+loopback HTTP origin; other custom origins require HTTPS. Setup creates application
+credentials in the approved mode. Program configuration and the complete transaction
+journey remain separate verification steps.
+
+## Verify configuration from the CLI
+
+With the installed packages and configured environment, set `COMMISH_PROGRAM_ID`
+to your existing program ID and run `pnpm exec commish-next verify --json`.
+The command reads `COMMISH_SECRET_KEY`, `NEXT_PUBLIC_COMMISH_PUBLISHABLE_KEY`,
+`NEXT_PUBLIC_COMMISH_APPLICATION_ID` and `COMMISH_PROGRAM_ID` from the process
+environment. Use Node's `--env-file` support or your existing environment runner
+if needed; the CLI does not search for or change dotenv files.
+
+It performs one authenticated, read-only program lookup in the key's TEST or LIVE
+mode. `configuration_verified` means the key can read that program and its
+application/mode match the configured values. The receipt includes program status;
+a paused or draft program is not declared ready for transactions. Publishable-key
+format/mode is checked locally; its server-side application binding is **not** proved.
+`integrationVerified: false` and `unverified` identify the remaining real journey.
+
+The API defaults to `https://app.commish.sh/api/v1`. Set `COMMISH_API_URL` only to a
+Commish deployment you trust: this destination receives the secret key. Custom
+bases require HTTPS, except explicit loopback development addresses. Redirects are
+rejected; responses and request duration are bounded. The CLI does not provision resources or issue mutation requests. Authentication
+may update key-usage metadata. It never prints credentials/provider bodies or retries a request. Invalid configuration,
+denied/revoked keys, inaccessible programs, mismatches and unavailable responses exit
+with code 1 and a stable JSON error code. On older deployments that reject LIVE reads,
+verification fails with `access_denied`; it never falls back to TEST.

package/bin/init.mjs

@@ -0,0 +1,329 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import {
+  linkSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+
+const hash = (value) => createHash("sha256").update(value).digest("hex");
+const token = () => randomBytes(24).toString("base64url");
+const safeUrl = (raw) => {
+  let value;
+  try { value = new URL(raw); } catch { throw new Error("invalid_app_url"); }
+  if (value.username || value.password || value.search || value.hash || value.pathname !== "/" ||
+      !(value.protocol === "https:" || value.protocol === "http:" &&
+        ["127.0.0.1", "[::1]", "localhost"].includes(value.hostname)))
+    throw new Error("invalid_app_url");
+  return value;
+};
+const responseJson = async (response) => {
+  if (Number(response.headers.get("content-length")) > 65_536 || !response.body)
+    throw new Error("invalid_response");
+  const chunks = []; let size = 0;
+  for await (const chunk of response.body) {
+    size += chunk.byteLength;
+    if (size > 65_536) throw new Error("invalid_response");
+    chunks.push(chunk);
+  }
+  try { return JSON.parse(Buffer.concat(chunks).toString("utf8")); }
+  catch { throw new Error("invalid_response"); }
+};
+const setupOptions = (values) => {
+  const result = { appUrl: "https://app.commish.sh", keyLabel: "Agent setup", mode: "test", open: true };
+  const keys = new Set();
+  for (let index = 0; index < values.length; index++) {
+    const name = values[index];
+    if (name === "--json" || name === "--no-open") {
+      if (keys.has(name)) throw new Error("invalid_arguments");
+      keys.add(name);
+      if (name === "--json") result.json = true;
+      else result.open = false;
+      continue;
+    }
+    const fields = {
+      "--workspace": "workspaceId", "--output": "output",
+      "--application-name": "applicationName", "--key-label": "keyLabel",
+      "--app-url": "appUrl", "--mode": "mode",
+    };
+    const field = fields[name], value = values[++index];
+    if (!field || keys.has(name) || !value || value.startsWith("--"))
+      throw new Error("invalid_arguments");
+    keys.add(name); result[field] = value;
+  }
+  if (!/^wrk_[A-Za-z0-9_-]{12,}$/.test(result.workspaceId ?? "") ||
+      !result.output || !result.applicationName?.trim() || result.applicationName.length > 100 ||
+      !result.keyLabel.trim() || result.keyLabel.length > 100 ||
+      !["test", "live"].includes(result.mode))
+    throw new Error("invalid_arguments");
+  result.applicationName = result.applicationName.trim();
+  result.keyLabel = result.keyLabel.trim();
+  result.appUrl = safeUrl(result.appUrl);
+  return result;
+};
+const openBrowser = (url) => {
+  const command = process.platform === "darwin" ? ["open", [url]]
+    : process.platform === "win32" ? ["rundll32", ["url.dll,FileProtocolHandler", url]]
+      : ["xdg-open", [url]];
+  const child = spawn(command[0], command[1], { detached: true, stdio: "ignore" });
+  child.on("error", () => {}); child.unref();
+};
+const credentialTarget = (output) => {
+  const target = resolve(output), parent = dirname(target);
+  const parentEntry = lstatSync(parent);
+  if (!parentEntry.isDirectory() || parentEntry.isSymbolicLink())
+    throw new Error("unsafe_output_path");
+  try {
+    lstatSync(target);
+    const error = new Error("output_exists"); error.code = "EEXIST"; throw error;
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  return target;
+};
+const saveCredentials = (output, values) => {
+  const target = credentialTarget(output), parent = dirname(target);
+  const temporary = join(parent, `.${basename(target)}.${randomUUID()}.tmp`);
+  const body = Object.entries(values).map(([name, value]) => `${name}=${value}\n`).join("");
+  try {
+    writeFileSync(temporary, body, { flag: "wx", mode: 0o600 });
+    linkSync(temporary, target);
+  } finally {
+    try { unlinkSync(temporary); } catch {}
+  }
+  return target;
+};
+const setupReceipt = (body, expected) => {
+  const value = body?.data, app = value?.application, key = value?.apiKey;
+  if (value?.protocol !== "commish-cli-setup-v1" || value.status !== "complete" ||
+      value.workspaceId !== expected.workspaceId || typeof value.expiresAt !== "string" ||
+      typeof value.replayed !== "boolean" || !/^app_[A-Za-z0-9_-]{12,}$/.test(app?.id ?? "") ||
+      app?.name !== expected.applicationName || !Array.isArray(app?.verifiedOrigins) ||
+      typeof app?.createdAt !== "string" || !/^key_[A-Za-z0-9_-]{12,}$/.test(key?.id ?? "") ||
+      key?.applicationId !== app.id || key?.mode !== expected.mode ||
+      (value.mode ?? "test") !== expected.mode ||
+      key?.publishableKey !== expected.publishableKey || key?.label !== expected.keyLabel ||
+      typeof key?.createdAt !== "string" || key?.lastUsedAt !== null || key?.revokedAt !== null)
+    throw new Error("invalid_response");
+  return value;
+};
+const setup = async (values) => {
+  const options = setupOptions(values), output = credentialTarget(options.output),
+    verifier = randomBytes(32).toString("base64url"),
+    publishableKey = `cm_${options.mode}_pk_${token()}`, secretKey = `cm_${options.mode}_sk_${token()}`,
+    expiresAt = new Date(Date.now() + 570_000).toISOString(),
+    request = {
+      workspaceId: options.workspaceId, mode: options.mode, challengeHash: hash(verifier),
+      applicationName: options.applicationName, keyLabel: options.keyLabel,
+      publishableKey, secretHash: hash(secretKey),
+      idempotencyKey: `cli-setup:${randomUUID()}`, expiresAt,
+    }, approval = new URL("/cli/setup", options.appUrl);
+  approval.search = new URLSearchParams(request).toString();
+  process.stderr.write(`Authorize ${options.mode.toUpperCase()} setup in your browser:\n${approval.href}\n`);
+  if (options.open) openBrowser(approval.href);
+  const exchange = new URL("/api/cli/setup-grants/exchange", options.appUrl);
+  let receipt;
+  while (Date.now() < Date.parse(expiresAt)) {
+    let response;
+    try {
+      response = await fetch(exchange, {
+        method: "POST", headers: { "content-type": "application/json", accept: "application/json" },
+        body: JSON.stringify({ verifier }), redirect: "error", cache: "no-store",
+        signal: AbortSignal.timeout(10_000),
+      });
+      const body = await responseJson(response);
+      if (response.ok) { receipt = setupReceipt(body, { ...options, publishableKey }); break; }
+      if (response.status !== 408 && response.status !== 429 && response.status !== 428 &&
+          response.status < 500)
+        throw new Error(body?.error?.code === "setup_grant_expired" ? "setup_expired" : "setup_denied");
+    } catch (error) {
+      if (["setup_expired", "setup_denied", "invalid_response"].includes(error.message)) throw error;
+    }
+    await delay(2_000);
+  }
+  if (!receipt) throw new Error("setup_expired");
+  const file = saveCredentials(output, {
+    COMMISH_API_URL: new URL("/api/v1", options.appUrl).href,
+    COMMISH_SECRET_KEY: secretKey,
+    NEXT_PUBLIC_COMMISH_PUBLISHABLE_KEY: publishableKey,
+    NEXT_PUBLIC_COMMISH_APPLICATION_ID: receipt.application.id,
+  });
+  return {
+    status: `${options.mode}_credentials_configured`, mode: options.mode, workspaceId: options.workspaceId,
+    applicationId: receipt.application.id, apiKeyId: receipt.apiKey.id, output: file,
+    replayed: receipt.replayed, integrationVerified: false,
+    next: `Configure a ${options.mode.toUpperCase()} program, then run commish-next verify --json with COMMISH_PROGRAM_ID.`,
+  };
+};
+
+const args = process.argv.slice(2);
+const json = args.includes("--json");
+if (args[0] === "setup") {
+  try {
+    const result = await setup(args.slice(1));
+    console.log(json ? JSON.stringify(result) :
+      `Commish ${result.mode.toUpperCase()} credentials saved to ${result.output}.\n${result.next}`);
+  } catch (error) {
+    const code = ["invalid_arguments", "invalid_app_url", "unsafe_output_path", "invalid_response",
+      "setup_expired", "setup_denied"].includes(error?.message) ? error.message :
+      error?.code === "EEXIST" ? "output_exists" : "setup_unavailable";
+    console.error(json ? JSON.stringify({ status: "error", code }) : `Setup failed: ${code}.`);
+    process.exitCode = 1;
+  }
+} else if (args[0] === "verify") {
+  const fail = (code) => { throw new Error(code); };
+  try {
+    if (args.slice(1).some((arg) => arg !== "--json") || new Set(args).size !== args.length)
+      fail("invalid_arguments");
+    const env = process.env;
+    const secret = env.COMMISH_SECRET_KEY ?? "";
+    const key = secret.match(/^cm_(test|live)_sk_[A-Za-z0-9_-]{12,}$/);
+    const publishable = (env.NEXT_PUBLIC_COMMISH_PUBLISHABLE_KEY ?? "").match(/^cm_(test|live)_pk_[A-Za-z0-9_-]{12,}$/);
+    const applicationId = env.NEXT_PUBLIC_COMMISH_APPLICATION_ID;
+    const programId = env.COMMISH_PROGRAM_ID;
+    if (!key || !publishable || !/^app_[A-Za-z0-9_-]{12,}$/.test(applicationId ?? "") ||
+        !/^prg_[A-Za-z0-9_-]{12,}$/.test(programId ?? "")) fail("invalid_configuration");
+    const mode = key[1] === "live" ? "live" : "test";
+    if (mode !== publishable[1]) fail("key_mode_mismatch");
+    let api;
+    try { api = new URL(env.COMMISH_API_URL ?? "https://app.commish.sh/api/v1"); }
+    catch { fail("invalid_api_url"); }
+    if (api.username || api.password || api.search || api.hash ||
+        !/^\/api\/v1\/?$/.test(api.pathname) ||
+        !(api.protocol === "https:" || api.protocol === "http:" &&
+          ["127.0.0.1", "[::1]", "localhost"].includes(api.hostname))) fail("invalid_api_url");
+    const response = await fetch(`${api.href.replace(/\/$/, "")}/programs/${programId}`, {
+      method: "GET", headers: { authorization: `Bearer ${secret}`, accept: "application/json" },
+      redirect: "error", cache: "no-store", signal: AbortSignal.timeout(10_000),
+    });
+    if (!response.ok) {
+      await response.body?.cancel();
+      fail(({ 401: "invalid_api_key", 403: "access_denied", 404: "program_not_found" })[response.status] ?? "verification_unavailable");
+    }
+    const chunks = []; let size = 0;
+    if (!response.body) fail("invalid_response");
+    for await (const chunk of response.body) {
+      size += chunk.byteLength;
+      if (size > 65_536) fail("invalid_response");
+      chunks.push(chunk);
+    }
+    let program;
+    try { program = JSON.parse(Buffer.concat(chunks).toString("utf8"))?.data; }
+    catch { fail("invalid_response"); }
+    if (!program || program.id !== programId ||
+        !["test", "live"].includes(program.mode) ||
+        !["draft", "active", "paused", "suspended", "archived"].includes(program.status)) fail("invalid_response");
+    if (program.applicationId !== applicationId) fail("application_mismatch");
+    if (program.mode !== mode) fail("program_mode_mismatch");
+    const result = {
+      status: "configuration_verified", mode, applicationId, programId,
+      programStatus: program.status,
+      checks: ["secret_key_authenticated", "program_accessible", "application_matches", "mode_matches", "publishable_key_mode_matches"],
+      unverified: ["publishable_key_binding", "consumer_wiring", "attribution", "checkout", "webhooks", "refunds", "renewals", "payouts"],
+      integrationVerified: false,
+    };
+    console.log(json ? JSON.stringify(result) :
+      `Configuration verified (${result.mode}, program ${programId}, status ${program.status}).\n` +
+      "Publishable-key binding and end-to-end integration remain unverified. Use --json for individual checks.");
+  } catch (error) {
+    const codes = ["invalid_arguments", "invalid_configuration", "key_mode_mismatch", "invalid_api_url",
+      "invalid_api_key", "access_denied", "program_not_found", "verification_unavailable",
+      "invalid_response", "application_mismatch", "program_mode_mismatch"];
+    const code = codes.includes(error?.message) ? error.message : "verification_unavailable";
+    console.error(json ? JSON.stringify({ status: "error", code, integrationVerified: false }) : `Verification failed: ${code}.`);
+    process.exitCode = 1;
+  }
+} else try {
+  if (args.some((arg) => !["init", "--write", "--json"].includes(arg)) ||
+      new Set(args).size !== args.length) throw new Error("Usage: commish-next [init] [--write] [--json]");
+  const stat = (path) => {
+    try { return lstatSync(path); } catch (error) {
+      if (error.code === "ENOENT") return null;
+      throw error;
+    }
+  };
+  // Next ignores src/app when a root app directory exists.
+  const app = stat("app") ? "app" : stat("src/app") ? "src/app" : null;
+  if (!app) throw new Error("No Next.js App Router directory found.");
+  const safePath = (path) => {
+    let current = ".";
+    for (const part of path.split("/")) {
+      current = join(current, part);
+      const entry = stat(current);
+      if (entry && (entry.isSymbolicLink() || (current !== path && !entry.isDirectory())))
+        throw new Error(`Refusing unsafe path: ${current}`);
+    }
+  };
+  safePath(`${app}/`);
+  const typed = Boolean(stat("tsconfig.json") || stat(`${app}/layout.tsx`));
+  const files = {
+    [`${app}/api/commish/attribution/route.${typed ? "ts" : "js"}`]: `import { createAttributionHandler } from "@commish/next";
+
+export const runtime = "nodejs";
+export const POST = createAttributionHandler({
+  apiUrl: process.env.COMMISH_API_URL,
+  secretKey: process.env.COMMISH_SECRET_KEY,
+});
+`,
+    [`${app}/commish-provider.${typed ? "tsx" : "jsx"}`]: `import { CommishProvider } from "@commish/next/react";
+${typed ? 'import type { ReactNode } from "react";\n' : ""}
+export default function CommishRootProvider({ children }${typed ? ": { children: ReactNode }" : ""}) {
+  return (
+    <CommishProvider
+      publishableKey={process.env.NEXT_PUBLIC_COMMISH_PUBLISHABLE_KEY${typed ? "!" : ""}}
+      applicationId={process.env.NEXT_PUBLIC_COMMISH_APPLICATION_ID${typed ? "!" : ""}}
+    >
+      {children}
+    </CommishProvider>
+  );
+}
+`,
+  };
+  for (const extension of ["js", "jsx", "ts", "tsx"])
+    if (stat(`${app}/api/commish/attribution/page.${extension}`))
+      throw new Error("The attribution URL already has a page. Choose a different capturePath and integrate using the Next setup guide.");
+  const plan = Object.entries(files).map(([path, content]) => {
+    safePath(path);
+    for (const extension of ["js", "jsx", "ts", "tsx"])
+      if (path.replace(/\.[^.]+$/, `.${extension}`) !== path &&
+          stat(path.replace(/\.[^.]+$/, `.${extension}`)))
+        throw new Error(`Conflicting file extension for ${path}; integrate using the Next setup guide.`);
+    const entry = stat(path);
+    return { path, status: !entry ? "create" :
+      entry.isFile() && readFileSync(path, "utf8") === content ? "unchanged" : "conflict" };
+  });
+  const conflicts = plan.filter(({ status }) => status === "conflict");
+  if (conflicts.length) throw new Error(`Existing custom files: ${conflicts.map(({ path }) => path).join(", ")}. No files changed; integrate using the Next setup guide.`);
+  const write = args.includes("--write");
+  if (write) for (const { path, status } of plan) if (status === "create") {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, files[path], { flag: "wx" });
+  }
+  const result = {
+    status: write ? "files_installed" : "plan", app, files: plan,
+    requiredEnvironment: ["COMMISH_API_URL", "COMMISH_SECRET_KEY",
+      "NEXT_PUBLIC_COMMISH_PUBLISHABLE_KEY", "NEXT_PUBLIC_COMMISH_APPLICATION_ID"],
+    next: [
+      `Import CommishRootProvider from './commish-provider' in the existing ${app}/layout file and wrap its existing children. Preserve the layout's other content.`,
+      "Set matching application credentials for the selected TEST or LIVE mode. Keep COMMISH_SECRET_KEY server-only.",
+      "Await referral capture before Checkout; await withCommishStripeMetadata(params) in your authenticated server Checkout handler.",
+      "Build the application, then verify a referral capture and attributed Checkout in TEST before LIVE activation.",
+    ],
+    integrationVerified: false,
+  };
+  console.log(json ? JSON.stringify(result) : [
+    write ? "Commish integration files installed." : "Commish setup plan (use --write to install).",
+    ...plan.map(({ path, status }) => `${status}: ${path}`),
+    `Required environment: ${result.requiredEnvironment.join(", ")}`,
+    ...result.next,
+  ].join("\n"));
+} catch (error) {
+  console.error(json ? JSON.stringify({ status: "error", message: error.message }) : error.message);
+  process.exitCode = 1;
+}

package/dist/browser.d.ts

@@ -0,0 +1,2 @@
+export { captureReferral } from "@commish/sdk/browser";
+export type { CommishBrowserOptions } from "@commish/sdk/browser";

package/dist/browser.js

@@ -0,0 +1 @@
+export { captureReferral } from "@commish/sdk/browser";

package/dist/capture.d.ts

@@ -0,0 +1,5 @@
+export declare const COMMISH_COOKIE = "commish_attribution";
+export declare function createAttributionHandler(options: {
+    apiUrl?: string;
+    secretKey?: string;
+}): (request: Request) => Promise<Response>;

package/dist/capture.js

@@ -0,0 +1,123 @@
+import { cookies } from "next/headers.js";
+export const COMMISH_COOKIE = "commish_attribution";
+export function createAttributionHandler(options) {
+    return async function POST(request) {
+        // Loaded per request so the root module stays importable wherever the
+        // cookie helpers are: only the handler needs the server response builder
+        // and the Node hash implementation.
+        const { NextResponse } = await import("next/server.js");
+        const body = await request.text();
+        const captureId = request.headers.get("x-commish-capture-id");
+        if (!captureId || !/^[a-f\d]{32}$/.test(captureId))
+            return NextResponse.json({
+                error: {
+                    code: "invalid_capture_id",
+                    message: "A valid browser capture ID is required.",
+                },
+            }, { status: 400 });
+        const configuredUrl = options.apiUrl ?? "https://app.commish.sh/api/v1";
+        let urlEnd = configuredUrl.length;
+        while (urlEnd > 0 && configuredUrl[urlEnd - 1] === "/")
+            urlEnd--;
+        const apiUrl = configuredUrl.slice(0, urlEnd);
+        const clientIp = request.headers.get("x-vercel-forwarded-for");
+        const userAgent = request.headers.get("user-agent");
+        const country = request.headers.get("x-vercel-ip-country");
+        const previousAttributionId = (await cookies()).get(COMMISH_COOKIE)?.value;
+        let idempotencyBody = body;
+        let forwardedBody = body;
+        try {
+            const parsed = JSON.parse(body);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                const { previousAttributionId: _untrusted, ...capture } = parsed;
+                void _untrusted;
+                idempotencyBody = JSON.stringify(capture);
+                forwardedBody = JSON.stringify({
+                    ...capture,
+                    ...(previousAttributionId &&
+                        /^atr_[A-Za-z0-9_-]{12,}$/.test(previousAttributionId)
+                        ? { previousAttributionId }
+                        : {}),
+                });
+            }
+        }
+        catch {
+            // Preserve malformed input for the API contract to reject consistently.
+        }
+        const { createHash } = await import("node:crypto");
+        const idempotencyKey = `attribution:${createHash("sha256")
+            .update(`${captureId}.${idempotencyBody}`)
+            .digest("hex")}`;
+        let response;
+        let responseText;
+        try {
+            response = await fetch(`${apiUrl}/attributions/capture`, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    "idempotency-key": idempotencyKey,
+                    "x-commish-publishable-key": request.headers.get("x-commish-publishable-key") ?? "",
+                    ...(options.secretKey
+                        ? { authorization: `Bearer ${options.secretKey}` }
+                        : {}),
+                    ...(clientIp ? { "x-commish-client-ip": clientIp } : {}),
+                    ...(userAgent ? { "user-agent": userAgent } : {}),
+                    ...(country ? { "x-vercel-ip-country": country } : {}),
+                },
+                body: forwardedBody,
+            });
+            responseText = await response.text();
+        }
+        catch {
+            // An unreachable or truncated upstream is a transport failure, not an
+            // attribution outcome: answer the caller instead of rejecting the route.
+            return NextResponse.json({
+                error: {
+                    code: "attribution_capture_unavailable",
+                    message: "Attribution capture is temporarily unavailable.",
+                },
+            }, { status: 502 });
+        }
+        let payload;
+        try {
+            payload = responseText ? JSON.parse(responseText) : undefined;
+        }
+        catch {
+            payload = undefined;
+        }
+        if (!response.ok)
+            return NextResponse.json(payload && typeof payload === "object"
+                ? payload
+                : {
+                    error: {
+                        code: "attribution_capture_failed",
+                        message: "Attribution capture failed.",
+                    },
+                }, { status: response.status });
+        const capturePayload = payload && typeof payload === "object"
+            ? payload
+            : undefined;
+        const token = capturePayload?.data?.token;
+        const expiresAt = capturePayload?.data?.expiresAt;
+        const expiresAtMs = typeof expiresAt === "string" ? Date.parse(expiresAt) : Number.NaN;
+        const maxAge = Math.floor((expiresAtMs - Date.now()) / 1000);
+        if (typeof token !== "string" || !token || typeof expiresAt !== "string" ||
+            !Number.isFinite(expiresAtMs) || maxAge <= 0)
+            return NextResponse.json({
+                error: {
+                    code: "invalid_capture_response",
+                    message: "Commish returned an invalid attribution response.",
+                },
+            }, { status: 502 });
+        const outgoing = NextResponse.json({ data: { captured: true, expiresAt } }, { status: response.status });
+        outgoing.cookies.set(COMMISH_COOKIE, token, {
+            httpOnly: true,
+            sameSite: "lax",
+            secure: process.env.NODE_ENV === "production",
+            path: "/",
+            expires: new Date(expiresAtMs),
+            maxAge,
+        });
+        return outgoing;
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { COMMISH_COOKIE, createAttributionHandler } from "./capture.js";
+import { applyCommishStripeMetadata, type StripeCheckoutParams } from "./metadata.js";
+export { applyCommishStripeMetadata };
+export declare function getCommishAttribution(): Promise<string | null>;
+export declare function withCommishStripeMetadata<T extends StripeCheckoutParams>(params: T): Promise<T>;

package/dist/index.js

@@ -0,0 +1,11 @@
+import { cookies } from "next/headers.js";
+import { COMMISH_COOKIE } from "./capture.js";
+export { COMMISH_COOKIE, createAttributionHandler } from "./capture.js";
+import { applyCommishStripeMetadata } from "./metadata.js";
+export { applyCommishStripeMetadata };
+export async function getCommishAttribution() {
+    return (await cookies()).get(COMMISH_COOKIE)?.value ?? null;
+}
+export async function withCommishStripeMetadata(params) {
+    return applyCommishStripeMetadata(params, await getCommishAttribution());
+}

package/dist/metadata.d.ts

@@ -0,0 +1,12 @@
+type StripeMetadata = Record<string, string | number | null>;
+export type StripeCheckoutParams = {
+    mode?: string;
+    client_reference_id?: string;
+    metadata?: StripeMetadata;
+    subscription_data?: {
+        metadata?: StripeMetadata;
+        [key: string]: unknown;
+    };
+};
+export declare function applyCommishStripeMetadata<T extends StripeCheckoutParams>(params: T, attribution: string | null): T;
+export {};

package/dist/metadata.js

@@ -0,0 +1,22 @@
+export function applyCommishStripeMetadata(params, attribution) {
+    if (!attribution)
+        return params;
+    return {
+        ...params,
+        metadata: { ...params.metadata, commish_attribution: attribution },
+        ...(params.mode === "subscription"
+            ? {
+                subscription_data: {
+                    ...params.subscription_data,
+                    metadata: {
+                        ...params.subscription_data?.metadata,
+                        commish_attribution: attribution,
+                        ...(params.client_reference_id
+                            ? { commish_customer_id: params.client_reference_id }
+                            : {}),
+                    },
+                },
+            }
+            : {}),
+    };
+}

package/dist/provider.d.ts

@@ -0,0 +1,10 @@
+import { type ReactNode } from "react";
+type CommishCaptureProps = {
+    publishableKey: string;
+    applicationId: string;
+    capturePath?: string;
+};
+export declare function CommishProvider({ children, ...captureProps }: CommishCaptureProps & {
+    children: ReactNode;
+}): import("react").JSX.Element;
+export {};

package/dist/provider.js

@@ -0,0 +1,14 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Suspense, useEffect } from "react";
+import { captureReferral } from "@commish/sdk/browser";
+import { usePathname, useSearchParams } from "next/navigation.js";
+function CommishCapture({ publishableKey, applicationId, capturePath, }) {
+    const pathname = usePathname();
+    const searchParams = useSearchParams();
+    useEffect(() => void captureReferral({ publishableKey, applicationId, capturePath }), [publishableKey, applicationId, capturePath, pathname, searchParams]);
+    return null;
+}
+export function CommishProvider({ children, ...captureProps }) {
+    return (_jsxs(_Fragment, { children: [_jsx(Suspense, { fallback: null, children: _jsx(CommishCapture, { ...captureProps }) }), children] }));
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@commish/next",
+  "version": "0.1.0-beta.10",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oftring-ventures/commish-sdk.git",
+    "directory": "packages/next"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=24 <25"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta"
+  },
+  "description": "Next.js referral capture and Stripe metadata helpers for Commish",
+  "exports": {
+    ".": {
+      "browser": null,
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "default": "./dist/browser.js"
+    },
+    "./react": {
+      "types": "./dist/provider.d.ts",
+      "default": "./dist/provider.js"
+    }
+  },
+  "peerDependencies": {
+    "@commish/sdk": "0.1.0-beta.10",
+    "next": ">=16.2.12 <17",
+    "react": ">=19.2.8 <20"
+  },
+  "bin": {
+    "commish-next": "./bin/init.mjs"
+  }
+}