commerceforai 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,40 @@
-# Temporary Holding Version
+# commerceforai
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Products, inventory, checkout, orders, shipping, returns and print-on-demand on top of your own Stripe account. One API key, built for you and your AI coding agent.
+
+```bash
+npm install commerceforai
+```
+
+```ts
+import { Commerce } from "commerceforai";
+
+const commerce = new Commerce(process.env.COMMERCEFORAI_API_KEY);
+
+const { data: product, error } = await commerce.products.create({ name: "Trail Tee", price: 3600, inventory: 25 });
+const { data: checkout } = await commerce.checkouts.create({
+  items: [{ variant_id: product!.variants[0]!.id, quantity: 1 }],
+  success_url: "https://yoursite.com/thanks",
+});
+// Send the customer to checkout.url
+```
+
+No account yet? `npx commerceforai init` creates a test store and an API key without signing up.
+
+Every method returns `{ data, error }`. All money is an integer in cents.
+
+## What's included
+
+- `commerceforai`: products, variants, inventory, checkouts, orders, returns, shipping labels, collections, discounts, customers, reports, webhooks, image hosting, Printify tools, test/live sync
+- `commerceforai/react`: `CartProvider`, `useCart`, `useVariantPicker`, `useClearCartOnSuccess` (draw nothing, fit any design)
+- `commerceforai/cart`: the same cart logic with no framework
+- `createCheckoutHandler()`: a one-line server route for your cart
+
+## Links
+
+- [Docs](https://commerceforai.com/docs)
+- [Quickstart](https://commerceforai.com/docs/quickstart)
+- [For AI agents: llms.txt](https://commerceforai.com/llms.txt)
+- [MCP server](https://www.npmjs.com/package/@commerceforai/mcp)
+
+MIT licensed.

package/dist/cart-core.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Cart and variant-picking logic with no framework attached. The React hooks in `commerceforai/react`
+ * are thin wrappers around these; use them directly from Vue, Svelte or plain JS.
+ */
+/** What a cart stores: ids and quantities only. Names and prices are always read fresh from the catalog. */
+export interface CartLine {
+    variant_id: string;
+    quantity: number;
+    /** Custom data for this line (e.g. a name to print). Lines with properties never merge. */
+    properties?: Record<string, string>;
+}
+export declare const MAX_QUANTITY = 20;
+export declare const MAX_LINES = 30;
+/** Add, merging into an existing line for the same variant (unless either line has custom properties). */
+export declare function addLine(lines: CartLine[], variantId: string, quantity?: number, properties?: Record<string, string>): CartLine[];
+/** Set a line's quantity by index (0 removes it). */
+export declare function setLineQuantity(lines: CartLine[], index: number, quantity: number): CartLine[];
+export declare const removeLine: (lines: CartLine[], index: number) => CartLine[];
+/** Parse untrusted stored data (localStorage, a cookie) into valid lines. */
+export declare function parseLines(raw: unknown): CartLine[];
+/** The parts of a product the cart and picker need. Works with SDK products and public store pages. */
+export interface CatalogVariant {
+    id: string;
+    name: string;
+    price: number;
+    currency: string;
+    options?: Record<string, string> | null;
+    active?: boolean;
+    /** SDK shape. */
+    inventory?: {
+        tracked?: boolean;
+        available: number | null;
+    };
+    /** Public store page shape. */
+    in_stock?: boolean;
+}
+export interface CatalogProduct {
+    id: string;
+    name: string;
+    images?: string[];
+    variants: CatalogVariant[];
+}
+/** How many can be bought (null = unlimited). */
+export declare function availableOf(v: CatalogVariant): number | null;
+export interface ResolvedLine extends CartLine {
+    index: number;
+    product: CatalogProduct;
+    variant: CatalogVariant;
+    unit_price: number;
+    line_total: number;
+    /** Stock left, or null for unlimited. */
+    available: number | null;
+    /** More in the cart than can be bought. */
+    over_stock: boolean;
+}
+/**
+ * Join cart lines to the catalog. Lines whose variant is gone or inactive go into `missing` (show a
+ * notice and drop them); everything else gets a current price and a stock check.
+ */
+export declare function resolveCart(lines: CartLine[], products: CatalogProduct[]): {
+    lines: ResolvedLine[];
+    missing: CartLine[];
+    currency: string;
+    count: number;
+    subtotal: number;
+    /** Ready for checkout: something in it, nothing missing or over stock. */
+    ready: boolean;
+};
+/** Option names in the order they first appear (e.g. ["Size", "Color"]). */
+export declare function optionNames(p: CatalogProduct): string[];
+export interface OptionChoice {
+    value: string; /** Some in-stock variant has this value with the other current selections. */
+    available: boolean;
+    selected: boolean;
+}
+/**
+ * Given the current selections, which values are offered for each option, which are buyable, and which
+ * variant (if any) the selection resolves to.
+ */
+export declare function pickVariant(p: CatalogProduct, selected: Record<string, string>): {
+    options: {
+        name: string;
+        values: OptionChoice[];
+    }[];
+    variant: CatalogVariant | null;
+    inStock: boolean;
+    available: number | null;
+};
+/** A sensible starting selection: the first in-stock variant's options (or the first variant's). */
+export declare function initialSelection(p: CatalogProduct): Record<string, string>;

package/dist/cart-core.js

@@ -0,0 +1,122 @@
+/**
+ * Cart and variant-picking logic with no framework attached. The React hooks in `commerceforai/react`
+ * are thin wrappers around these; use them directly from Vue, Svelte or plain JS.
+ */
+export const MAX_QUANTITY = 20;
+export const MAX_LINES = 30;
+const clampQty = (n) => Math.max(0, Math.min(MAX_QUANTITY, Math.floor(Number.isFinite(n) ? n : 0)));
+const sameProps = (a, b) => JSON.stringify(Object.entries(a ?? {}).sort()) === JSON.stringify(Object.entries(b ?? {}).sort());
+/** Add, merging into an existing line for the same variant (unless either line has custom properties). */
+export function addLine(lines, variantId, quantity = 1, properties) {
+    const hasProps = properties && Object.keys(properties).length > 0;
+    const i = hasProps ? -1 : lines.findIndex((l) => l.variant_id === variantId && !Object.keys(l.properties ?? {}).length);
+    if (i >= 0)
+        return lines.map((l, j) => (j === i ? { ...l, quantity: clampQty(l.quantity + quantity) } : l));
+    if (lines.length >= MAX_LINES)
+        return lines;
+    const q = clampQty(quantity);
+    return q ? [...lines, { variant_id: variantId, quantity: q, ...(hasProps ? { properties } : {}) }] : lines;
+}
+/** Set a line's quantity by index (0 removes it). */
+export function setLineQuantity(lines, index, quantity) {
+    const q = clampQty(quantity);
+    return q ? lines.map((l, i) => (i === index ? { ...l, quantity: q } : l)) : lines.filter((_, i) => i !== index);
+}
+export const removeLine = (lines, index) => lines.filter((_, i) => i !== index);
+/** Parse untrusted stored data (localStorage, a cookie) into valid lines. */
+export function parseLines(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const l of raw.slice(0, MAX_LINES)) {
+        if (!l || typeof l.variant_id !== "string" || !l.variant_id)
+            continue;
+        const quantity = clampQty(Number(l.quantity));
+        if (!quantity)
+            continue;
+        const props = l.properties && typeof l.properties === "object" && !Array.isArray(l.properties)
+            ? Object.fromEntries(Object.entries(l.properties).filter(([, v]) => typeof v === "string").slice(0, 20))
+            : undefined;
+        out.push({ variant_id: l.variant_id, quantity, ...(props && Object.keys(props).length ? { properties: props } : {}) });
+    }
+    return out;
+}
+/** How many can be bought (null = unlimited). */
+export function availableOf(v) {
+    if (v.active === false)
+        return 0;
+    if (v.inventory)
+        return v.inventory.available ?? null;
+    if (v.in_stock === false)
+        return 0;
+    return null;
+}
+/**
+ * Join cart lines to the catalog. Lines whose variant is gone or inactive go into `missing` (show a
+ * notice and drop them); everything else gets a current price and a stock check.
+ */
+export function resolveCart(lines, products) {
+    const byVariant = new Map(products.flatMap((p) => p.variants.map((v) => [v.id, { p, v }])));
+    const resolved = [];
+    const missing = [];
+    lines.forEach((l, index) => {
+        const hit = byVariant.get(l.variant_id);
+        if (!hit || hit.v.active === false) {
+            missing.push(l);
+            return;
+        }
+        const available = availableOf(hit.v);
+        resolved.push({ ...l, index, product: hit.p, variant: hit.v, unit_price: hit.v.price, line_total: hit.v.price * l.quantity,
+            available, over_stock: available !== null && l.quantity > available });
+    });
+    const currency = resolved[0]?.variant.currency ?? "usd";
+    return {
+        lines: resolved, missing, currency,
+        count: lines.reduce((n, l) => n + l.quantity, 0),
+        subtotal: resolved.reduce((n, l) => n + l.line_total, 0),
+        /** Ready for checkout: something in it, nothing missing or over stock. */
+        ready: resolved.length > 0 && !missing.length && resolved.every((l) => !l.over_stock),
+    };
+}
+// ---------- variant picking ----------
+/** Option names in the order they first appear (e.g. ["Size", "Color"]). */
+export function optionNames(p) {
+    const names = [];
+    for (const v of p.variants)
+        for (const k of Object.keys(v.options ?? {}))
+            if (!names.includes(k))
+                names.push(k);
+    return names;
+}
+/**
+ * Given the current selections, which values are offered for each option, which are buyable, and which
+ * variant (if any) the selection resolves to.
+ */
+export function pickVariant(p, selected) {
+    const live = p.variants.filter((v) => v.active !== false);
+    const names = optionNames(p);
+    const inStock = (v) => { const a = availableOf(v); return a === null || a > 0; };
+    const matches = (v, sel) => Object.entries(sel).every(([k, val]) => (v.options ?? {})[k] === val);
+    const options = names.map((name) => {
+        const values = [...new Set(live.map((v) => (v.options ?? {})[name]).filter((x) => !!x))];
+        const others = Object.fromEntries(Object.entries(selected).filter(([k]) => k !== name));
+        return {
+            name,
+            values: values.map((value) => ({
+                value, selected: selected[name] === value,
+                available: live.some((v) => (v.options ?? {})[name] === value && matches(v, others) && inStock(v)),
+            })),
+        };
+    });
+    // No options (a single "Default" variant, or variants named without options): match by the only one.
+    const variant = names.length
+        ? (names.every((n) => selected[n]) ? live.find((v) => matches(v, selected)) ?? null : null)
+        : live.length === 1 ? live[0] : null;
+    return { options, variant, inStock: variant ? inStock(variant) : false, available: variant ? availableOf(variant) : null };
+}
+/** A sensible starting selection: the first in-stock variant's options (or the first variant's). */
+export function initialSelection(p) {
+    const live = p.variants.filter((v) => v.active !== false);
+    const first = live.find((v) => { const a = availableOf(v); return a === null || a > 0; }) ?? live[0];
+    return { ...(first?.options ?? {}) };
+}

package/dist/checkout-handler.d.ts

@@ -0,0 +1,26 @@
+/**
+ * A ready-made server endpoint for carts built with `commerceforai/react` (or any client):
+ * it takes `{ items, discount_code? }`, creates the checkout with your secret key, and returns `{ url }`.
+ *
+ * ```ts
+ * // app/api/checkout/route.ts (Next.js) — also works in Hono, Remix, Astro, SvelteKit, Bun, Deno
+ * import { createCheckoutHandler } from "commerceforai";
+ * export const POST = createCheckoutHandler();
+ * ```
+ *
+ * The browser only sends variant ids and quantities. Prices, stock and discounts are checked by the API.
+ */
+import { Commerce } from "./index.js";
+export interface CheckoutHandlerOptions {
+    /** A client to use (default: `new Commerce()` from COMMERCEFORAI_API_KEY). */
+    commerce?: Commerce;
+    /** Where Stripe sends shoppers after paying (default `<origin>/checkout/success`). `cfa_checkout` is appended. */
+    successUrl?: string | ((origin: string) => string);
+    /** Where "back" on Stripe's page goes (default the page that started checkout, else `<origin>/`). */
+    cancelUrl?: string | ((origin: string) => string);
+    /** Sites allowed to start checkouts (default: same origin as the request only). */
+    allowedOrigins?: string[];
+    /** Add metadata to every checkout (e.g. `{ channel: "web" }`). */
+    metadata?: Record<string, string>;
+}
+export declare function createCheckoutHandler(opts?: CheckoutHandlerOptions): (request: Request) => Promise<Response>;

package/dist/checkout-handler.js

@@ -0,0 +1,63 @@
+/**
+ * A ready-made server endpoint for carts built with `commerceforai/react` (or any client):
+ * it takes `{ items, discount_code? }`, creates the checkout with your secret key, and returns `{ url }`.
+ *
+ * ```ts
+ * // app/api/checkout/route.ts (Next.js) — also works in Hono, Remix, Astro, SvelteKit, Bun, Deno
+ * import { createCheckoutHandler } from "commerceforai";
+ * export const POST = createCheckoutHandler();
+ * ```
+ *
+ * The browser only sends variant ids and quantities. Prices, stock and discounts are checked by the API.
+ */
+import { Commerce } from "./index.js";
+import { parseLines } from "./cart-core.js";
+const json = (body, status = 200) => new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
+const fail = (status, type, message, extra = {}) => json({ error: { type, message, ...extra } }, status);
+export function createCheckoutHandler(opts = {}) {
+    let client = opts.commerce;
+    return async function handler(request) {
+        if (request.method !== "POST")
+            return fail(405, "invalid_request", "Use POST");
+        const url = new URL(request.url);
+        const origin = request.headers.get("origin");
+        const host = request.headers.get("x-forwarded-host") ?? request.headers.get("host") ?? url.host;
+        const proto = request.headers.get("x-forwarded-proto") ?? url.protocol.replace(":", "");
+        const self = `${proto}://${host}`;
+        // Only your own pages may start checkouts (stops other sites holding your stock).
+        const allowed = new Set([self, ...(opts.allowedOrigins ?? [])].map((o) => o.replace(/\/$/, "")));
+        if (origin && !allowed.has(origin.replace(/\/$/, "")))
+            return fail(403, "permission_error", "Checkout can only be started from this site");
+        let body;
+        try {
+            body = await request.json();
+        }
+        catch {
+            return fail(400, "invalid_request", "Body must be JSON: { items: [{ variant_id, quantity }] }");
+        }
+        const items = parseLines(body?.items);
+        if (!items.length)
+            return fail(400, "invalid_request", "Your cart is empty.", { param: "items" });
+        const base = origin && allowed.has(origin.replace(/\/$/, "")) ? origin.replace(/\/$/, "") : self;
+        const resolveUrl = (u, fallback) => (typeof u === "function" ? u(base) : u ?? fallback);
+        const success = new URL(resolveUrl(opts.successUrl, `${base}/checkout/success`));
+        // Stripe fills in {CHECKOUT_SESSION_ID}; useClearCartOnSuccess() looks for this parameter.
+        const successUrl = `${success.toString()}${success.search ? "&" : "?"}cfa_checkout={CHECKOUT_SESSION_ID}`;
+        const referer = request.headers.get("referer");
+        const cancelUrl = resolveUrl(opts.cancelUrl, referer && referer.startsWith(base) ? referer : `${base}/`);
+        client ??= new Commerce();
+        const { data, error } = await client.checkouts.create({
+            items, success_url: successUrl, cancel_url: cancelUrl,
+            ...(typeof body.discount_code === "string" && body.discount_code.trim() ? { discount_code: body.discount_code.trim().slice(0, 40) } : {}),
+            ...(opts.metadata ? { metadata: opts.metadata } : {}),
+        });
+        if (error || !data?.url) {
+            const e = (error ?? { type: "api_error", message: "Checkout isn't available right now." });
+            const status = e.type === "out_of_stock" ? 409 : e.type === "invalid_request" ? 400 : e.type === "rate_limited" ? 429 : 502;
+            // Pass through what a shopper can act on; keep internals (keys, Stripe details) server-side.
+            const safe = e.type === "out_of_stock" || e.type === "invalid_request" || e.type === "rate_limited";
+            return fail(status, e.type, safe ? e.message : "Checkout isn't available right now. Please try again.", safe ? Object.fromEntries(Object.entries(e).filter(([k]) => ["param", "variant_id", "available"].includes(k))) : {});
+        }
+        return json({ id: data.id, url: data.url }, 201);
+    };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+/**
+ * npx commerceforai init
+ *
+ * Creates a free test-mode store and API key with no sign-up, saves the key to .env.local,
+ * and prints a link a person uses later to claim the store and connect Stripe.
+ * Designed for coding agents: `--json` prints machine-readable output.
+ */
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const HELP = `Usage: npx commerceforai init [options]
+
+Creates a free test-mode CommerceForAI store and API key (no sign-up needed).
+
+Options:
+  --template nextjs    Also add a working storefront to this Next.js app (App Router):
+                       /shop product grid, product pages, cart, Stripe checkout,
+                       thank-you page and order lookup. Never overwrites files.
+                       Reuses COMMERCEFORAI_API_KEY if it's already set.
+  --name <name>        Store name (default: this folder's package.json name)
+  --env-file <path>    Where to save COMMERCEFORAI_API_KEY (default: .env.local)
+  --no-write           Don't write any file; just print the key
+  --force              Replace an existing COMMERCEFORAI_API_KEY in the env file
+  --json               Print JSON (for agents and scripts)
+  --base-url <url>     API base URL (default: https://api.commerceforai.com)
+  -h, --help           Show this help
+`;
+function parse(argv) {
+    const o = {};
+    const pos = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "-h" || a === "--help")
+            o.help = true;
+        else if (a === "--no-write" || a === "--force" || a === "--json")
+            o[a.slice(2)] = true;
+        else if (a.startsWith("--")) {
+            const [k, inline] = a.slice(2).split("=", 2);
+            o[k] = inline ?? argv[++i] ?? "";
+        }
+        else
+            pos.push(a);
+    }
+    return { o, pos };
+}
+function defaultName() {
+    try {
+        const pkg = JSON.parse(readFileSync(resolve("package.json"), "utf8"));
+        if (typeof pkg.name === "string" && pkg.name)
+            return pkg.name.replace(/^@[^/]+\//, "");
+    }
+    catch { }
+    return undefined;
+}
+async function init(o) {
+    const base = String(o["base-url"] ?? process.env.COMMERCEFORAI_BASE_URL ?? "https://api.commerceforai.com").replace(/\/$/, "");
+    const envFile = resolve(String(o["env-file"] ?? ".env.local"));
+    const write = !o["no-write"];
+    const template = typeof o.template === "string" ? o.template : null;
+    if (template && template !== "nextjs") {
+        const msg = `Unknown template "${template}". Available: nextjs`;
+        if (o.json)
+            console.log(JSON.stringify({ ok: false, error: { type: "invalid_request", message: msg } }));
+        else
+            console.error(msg);
+        process.exit(1);
+    }
+    const hasKey = existsSync(envFile) && /^COMMERCEFORAI_API_KEY=/m.test(readFileSync(envFile, "utf8"));
+    // With a template and an existing key: just add the storefront.
+    if (template && hasKey && !o.force) {
+        const sc = scaffoldNext();
+        if (o.json)
+            console.log(JSON.stringify({ ok: sc.ok, store_created: false, env_file: envFile, template: sc }));
+        else
+            printScaffold(sc, "Using the COMMERCEFORAI_API_KEY already in " + envFile.split("/").pop());
+        process.exit(sc.ok ? 0 : 1);
+    }
+    if (write && hasKey && !o.force) {
+        const msg = `${envFile} already has COMMERCEFORAI_API_KEY. Re-run with --force to replace it, or --no-write to just print a new key.`;
+        if (o.json)
+            console.log(JSON.stringify({ ok: false, error: { type: "already_configured", message: msg } }));
+        else
+            console.error(msg);
+        process.exit(1);
+    }
+    const res = await fetch(`${base}/sandbox/stores`, {
+        method: "POST",
+        headers: { "content-type": "application/json", "user-agent": "commerceforai-cli/0.1.0" },
+        body: JSON.stringify({ name: o.name || defaultName() }),
+    }).catch((e) => {
+        console.error(`Couldn't reach ${base}: ${e instanceof Error ? e.message : e}`);
+        process.exit(1);
+    });
+    const json = await res.json().catch(() => null);
+    if (!res.ok) {
+        if (o.json)
+            console.log(JSON.stringify({ ok: false, error: json?.error ?? { message: `HTTP ${res.status}` } }));
+        else
+            console.error(`CommerceForAI: ${json?.error?.message ?? `HTTP ${res.status}`}`);
+        process.exit(1);
+    }
+    if (write) {
+        const line = `COMMERCEFORAI_API_KEY=${json.api_key}\n`;
+        if (existsSync(envFile)) {
+            const cur = readFileSync(envFile, "utf8");
+            if (/^COMMERCEFORAI_API_KEY=.*$/m.test(cur))
+                writeFileSync(envFile, cur.replace(/^COMMERCEFORAI_API_KEY=.*$/m, line.trim()));
+            else
+                appendFileSync(envFile, (cur.endsWith("\n") || cur === "" ? "" : "\n") + line);
+        }
+        else
+            writeFileSync(envFile, line);
+    }
+    const gitignored = (() => {
+        try {
+            return /(^|\n)\s*\.env(\*|\.local|\.\*)?\s*(\n|$)/.test(readFileSync(resolve(".gitignore"), "utf8"));
+        }
+        catch {
+            return false;
+        }
+    })();
+    const sc = template ? scaffoldNext() : null;
+    if (o.json) {
+        console.log(JSON.stringify({
+            ok: true, store_id: json.store_id, mode: json.mode, api_key: json.api_key, claim_url: json.claim_url,
+            env_file: write ? envFile : null, docs: "https://commerceforai.com/llms.txt", ...(sc ? { template: sc } : {}),
+        }));
+        return;
+    }
+    if (sc) {
+        printScaffold(sc, `Created test store "${json.name}" (${json.store_id})${write ? ` and saved COMMERCEFORAI_API_KEY to ${envFile.split("/").pop()}` : `\n  API key: ${json.api_key}`}`);
+        console.log(`To manage this test store in the dashboard, claim it:
+  ${json.claim_url}
+
+When it's ready for real orders, create a go-live link for the store owner
+(commerce.store.goLiveLink(), or the create_go_live_link MCP tool).
+`);
+        return;
+    }
+    console.log(`
+✓ Created test store "${json.name}" (${json.store_id})
+${write ? `✓ Saved COMMERCEFORAI_API_KEY to ${envFile}` : `  API key: ${json.api_key}`}${write && !gitignored ? `\n! Add ${envFile.split("/").pop()} to .gitignore so the key isn't committed` : ""}
+
+Test mode is free forever. Pay with card 4242 4242 4242 4242.
+
+Next:
+  npm install commerceforai
+  Docs for you and your agent: https://commerceforai.com/llms.txt
+
+To manage this test store in the dashboard, claim it:
+  ${json.claim_url}
+
+When it's ready for real orders, create a go-live link and give it to the store owner
+(commerce.store.goLiveLink(), or the create_go_live_link MCP tool). One link signs them in,
+copies the store to live mode, and takes them to Connect Stripe.
+`);
+}
+function scaffoldNext() {
+    const fail = (error) => ({ ok: false, template: "nextjs", base: "", created: [], skipped: [], install_command: null, open: "", error });
+    let pkg;
+    try {
+        pkg = JSON.parse(readFileSync(resolve("package.json"), "utf8"));
+    }
+    catch {
+        return fail("No package.json here. Run this in a Next.js app (e.g. after `npx create-next-app@latest`).");
+    }
+    const deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+    if (!deps.next)
+        return fail("This isn't a Next.js app (no `next` dependency). Create one with `npx create-next-app@latest`, then re-run.");
+    // App Router lives in src/app or app.
+    const base = existsSync(resolve("src/app")) ? "src" : existsSync(resolve("app")) ? "" : existsSync(resolve("src")) ? "src" : "";
+    const from = fileURLToPath(new URL("../templates/nextjs/", import.meta.url));
+    const created = [], skipped = [];
+    const walk = (dir) => readdirSync(dir).flatMap((f) => statSync(join(dir, f)).isDirectory() ? walk(join(dir, f)) : [join(dir, f)]);
+    for (const file of walk(from)) {
+        const rel = relative(from, file);
+        const to = resolve(base, rel);
+        const shown = relative(process.cwd(), to);
+        if (existsSync(to)) {
+            skipped.push(shown);
+            continue;
+        }
+        mkdirSync(dirname(to), { recursive: true });
+        writeFileSync(to, readFileSync(file));
+        created.push(shown);
+    }
+    const pm = existsSync(resolve("pnpm-lock.yaml")) ? "pnpm add" : existsSync(resolve("yarn.lock")) ? "yarn add" : existsSync(resolve("bun.lockb")) || existsSync(resolve("bun.lock")) ? "bun add" : "npm install";
+    return { ok: true, template: "nextjs", base: base || ".", created, skipped, install_command: deps.commerceforai ? null : `${pm} commerceforai`, open: "http://localhost:3000/shop" };
+}
+function printScaffold(sc, first) {
+    if (!sc.ok) {
+        console.error(sc.error);
+        return;
+    }
+    console.log(`
+✓ ${first}
+✓ Added the storefront: ${sc.created.length} file(s)${sc.skipped.length ? `, skipped ${sc.skipped.length} that already exist (${sc.skipped.join(", ")})` : ""}
+
+Next:
+${sc.install_command ? `  ${sc.install_command}
+` : ""}  Add a product (SDK, MCP, or connect Printify/Printful), then run your dev server and open ${sc.open}
+  Pay with test card 4242 4242 4242 4242. Agents: verify without a browser with commerce.store.simulateOrder().
+`);
+}
+const { o, pos } = parse(process.argv.slice(2));
+if (o.help || !pos[0]) {
+    console.log(HELP);
+    process.exit(pos[0] ? 0 : o.help ? 0 : 1);
+}
+if (pos[0] === "init")
+    await init(o);
+else {
+    console.error(`Unknown command "${pos[0]}".\n\n${HELP}`);
+    process.exit(1);
+}