commerceforai 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "commerceforai",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Commerce for apps built by AI. Products, inventory, checkout and orders on top of your Stripe account.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "default": "./dist/react.js"
+    },
+    "./cart": {
+      "types": "./dist/cart-core.d.ts",
+      "default": "./dist/cart-core.js"
+    }
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "license": "MIT",
+  "bin": {
+    "commerceforai": "./dist/cli.js"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.3.0",
+    "react": "19.3.0",
+    "vitest": "^5.0.5"
+  },
+  "homepage": "https://commerceforai.com",
+  "keywords": [
+    "commerce",
+    "ecommerce",
+    "stripe",
+    "checkout",
+    "ai",
+    "agents"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
 }

package/templates/nextjs/app/shop/[id]/page.tsx

@@ -0,0 +1,44 @@
+import { notFound } from "next/navigation";
+import { Suspense } from "react";
+import { commerce, money } from "../../../lib/commerce";
+import { addToCart } from "../actions";
+
+export default function ProductPage({ params }: { params: Promise<{ id: string }> }) {
+  return <Suspense fallback={<p className="cfa-muted">Loading…</p>}><Product params={params} /></Suspense>;
+}
+
+async function Product({ params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params;
+  const { data: p } = await commerce.products.get(id);
+  if (!p || !p.active) notFound();
+  const variants = p.variants.filter((v) => v.active);
+  const buyable = variants.filter((v) => v.inventory.available === null || v.inventory.available > 0);
+  return (
+    <div className="cfa-detail">
+      {p.images[0] ? <img src={p.images[0]} alt={p.name} className="cfa-image" /> : <div className="cfa-placeholder" />}
+      <div>
+        <h1 className="cfa-h1">{p.name}</h1>
+        <p className="cfa-price">{money(variants[0]?.price ?? 0, variants[0]?.currency)}</p>
+        {p.description ? <p className="cfa-muted">{p.description}</p> : null}
+        <form action={addToCart}>
+          {variants.length > 1 ? (
+            <label className="cfa-field">
+              Option
+              <select name="variant_id" defaultValue={buyable[0]?.id}>
+                {variants.map((v) => {
+                  const soldOut = v.inventory.available !== null && v.inventory.available <= 0;
+                  return <option key={v.id} value={v.id} disabled={soldOut}>{v.name} · {money(v.price, v.currency)}{soldOut ? " (sold out)" : ""}</option>;
+                })}
+              </select>
+            </label>
+          ) : <input type="hidden" name="variant_id" value={variants[0]?.id ?? ""} />}
+          <label className="cfa-field">
+            Quantity
+            <input type="number" name="quantity" min={1} max={99} defaultValue={1} />
+          </label>
+          <button className="cfa-button" disabled={!buyable.length}>{buyable.length ? "Add to cart" : "Sold out"}</button>
+        </form>
+      </div>
+    </div>
+  );
+}

package/templates/nextjs/app/shop/actions.ts

@@ -0,0 +1,67 @@
+"use server";
+
+import { cookies, headers } from "next/headers";
+import { redirect } from "next/navigation";
+import { revalidatePath } from "next/cache";
+import { commerce } from "../../lib/commerce";
+import { CHECKOUT_COOKIE, readCart, writeCart } from "./cart-cookie";
+
+export async function addToCart(form: FormData) {
+  const variant_id = String(form.get("variant_id") ?? "");
+  const quantity = Math.max(1, Math.min(99, Number(form.get("quantity") ?? 1) || 1));
+  if (!variant_id) return;
+  const cart = await readCart();
+  const line = cart.find((l) => l.variant_id === variant_id);
+  if (line) line.quantity = Math.min(99, line.quantity + quantity);
+  else cart.push({ variant_id, quantity });
+  await writeCart(cart);
+  redirect("/shop/cart");
+}
+
+export async function setQuantity(form: FormData) {
+  const variant_id = String(form.get("variant_id") ?? "");
+  const quantity = Math.max(0, Math.min(99, Number(form.get("quantity") ?? 0) || 0));
+  await writeCart((await readCart()).map((l) => (l.variant_id === variant_id ? { ...l, quantity } : l)));
+  revalidatePath("/shop", "layout");
+}
+
+export async function clearCart() {
+  await writeCart([]);
+}
+
+/** Reserve stock and send the customer to Stripe Checkout. */
+export async function checkout() {
+  const cart = await readCart();
+  if (!cart.length) redirect("/shop/cart");
+  const h = await headers();
+  const origin = `${h.get("x-forwarded-proto") ?? "http"}://${h.get("x-forwarded-host") ?? h.get("host")}`;
+  const { data, error } = await commerce.checkouts.create({
+    items: cart,
+    success_url: `${origin}/shop/thanks`,
+    cancel_url: `${origin}/shop/cart`,
+  });
+  if (error || !data?.url) redirect(`/shop/cart?error=${encodeURIComponent(error?.message ?? "Checkout isn't available right now")}`);
+  (await cookies()).set(CHECKOUT_COOKIE, data.id, { httpOnly: true, sameSite: "lax", secure: process.env.NODE_ENV === "production", path: "/", maxAge: 60 * 60 * 24 });
+  redirect(data.url);
+}
+
+export type LookupState = { error?: string; order?: { number: number; status: string; total: number; currency: string; items: { name: string; quantity: number }[]; tracking: { carrier: string | null; number: string | null; url: string | null }[] } } | null;
+
+/** Order lookup needs both the order number and the email it was placed with. */
+export async function lookupOrder(_prev: LookupState, form: FormData): Promise<LookupState> {
+  const number = String(form.get("number") ?? "").replace(/^#/, "").trim();
+  const email = String(form.get("email") ?? "").trim().toLowerCase();
+  if (!/^\d+$/.test(number) || !email) return { error: "Enter your order number and email." };
+  const { data } = await commerce.orders.get(Number(number));
+  if (!data || (data.email ?? "").toLowerCase() !== email) return { error: "We couldn't find that order. Check the number and email." };
+  const shipments = data.fulfillment?.shipments?.length
+    ? data.fulfillment.shipments.map((s) => ({ carrier: s.carrier, number: s.tracking_number, url: s.tracking_url }))
+    : data.fulfillment ? [{ carrier: data.fulfillment.carrier, number: data.fulfillment.tracking_number, url: data.fulfillment.tracking_url }] : [];
+  return {
+    order: {
+      number: data.number, status: data.status.replace("_", " "), total: data.total, currency: data.currency,
+      items: data.items.map((i) => ({ name: i.variant_name === "Default" ? i.product_name : `${i.product_name} (${i.variant_name})`, quantity: i.quantity })),
+      tracking: shipments.filter((s) => s.number),
+    },
+  };
+}

package/templates/nextjs/app/shop/cart/page.tsx

@@ -0,0 +1,51 @@
+import Link from "next/link";
+import { Suspense } from "react";
+import { commerce, money } from "../../../lib/commerce";
+import { checkout, setQuantity } from "../actions";
+import { readCart } from "../cart-cookie";
+
+export const metadata = { title: "Cart" };
+
+export default function CartPage({ searchParams }: { searchParams: Promise<{ error?: string }> }) {
+  return <Suspense fallback={<p className="cfa-muted">Loading…</p>}><Cart searchParams={searchParams} /></Suspense>;
+}
+
+async function Cart({ searchParams }: { searchParams: Promise<{ error?: string }> }) {
+  const [{ error }, cart] = await Promise.all([searchParams, readCart()]);
+  if (!cart.length) return <div className="cfa-empty"><p>Your cart is empty.</p><Link href="/shop" className="cfa-button">Keep shopping</Link></div>;
+
+  // Look up current names and prices (the cart cookie only holds variant ids and quantities).
+  const { data } = await commerce.products.list({ limit: 100 });
+  const variants = new Map((data?.data ?? []).flatMap((p) => p.variants.map((v) => [v.id, { ...v, product: p.name }] as const)));
+  const lines = cart.map((l) => ({ ...l, v: variants.get(l.variant_id) })).filter((l) => l.v);
+  const currency = lines[0]?.v?.currency ?? "usd";
+  const subtotal = lines.reduce((sum, l) => sum + l.v!.price * l.quantity, 0);
+
+  return (
+    <div>
+      <h1 className="cfa-h1">Cart</h1>
+      {error ? <p className="cfa-alert">{error}</p> : null}
+      <table className="cfa-table">
+        <tbody>
+          {lines.map((l) => (
+            <tr key={l.variant_id}>
+              <td>{l.v!.product}{l.v!.name !== "Default" ? <span className="cfa-price"> · {l.v!.name}</span> : null}</td>
+              <td>
+                <form action={setQuantity} style={{ display: "flex", gap: 8 }}>
+                  <input type="hidden" name="variant_id" value={l.variant_id} />
+                  <input type="number" name="quantity" min={0} max={99} defaultValue={l.quantity} className="cfa-qty" aria-label="Quantity" />
+                  <button className="cfa-button cfa-secondary" style={{ height: 36 }}>Update</button>
+                </form>
+              </td>
+              <td style={{ textAlign: "right" }}>{money(l.v!.price * l.quantity, currency)}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+      <div className="cfa-row">
+        <p>Subtotal <strong>{money(subtotal, currency)}</strong> <span className="cfa-price">· shipping and tax at checkout</span></p>
+        <form action={checkout}><button className="cfa-button">Checkout</button></form>
+      </div>
+    </div>
+  );
+}

package/templates/nextjs/app/shop/cart-cookie.ts

@@ -0,0 +1,22 @@
+// The cart lives in a cookie: no database, works with server components and server actions.
+import { cookies } from "next/headers";
+
+export type CartLine = { variant_id: string; quantity: number };
+export const CART_COOKIE = "shop_cart";
+export const CHECKOUT_COOKIE = "shop_checkout";
+
+export async function readCart(): Promise<CartLine[]> {
+  try {
+    const raw = (await cookies()).get(CART_COOKIE)?.value;
+    const lines = raw ? (JSON.parse(raw) as CartLine[]) : [];
+    return lines.filter((l) => typeof l.variant_id === "string" && Number.isInteger(l.quantity) && l.quantity > 0).slice(0, 50);
+  } catch {
+    return [];
+  }
+}
+
+export async function writeCart(lines: CartLine[]) {
+  (await cookies()).set(CART_COOKIE, JSON.stringify(lines.filter((l) => l.quantity > 0)), {
+    httpOnly: true, sameSite: "lax", secure: process.env.NODE_ENV === "production", path: "/", maxAge: 60 * 60 * 24 * 30,
+  });
+}

package/templates/nextjs/app/shop/layout.tsx

@@ -0,0 +1,25 @@
+import Link from "next/link";
+import { Suspense } from "react";
+import { readCart } from "./cart-cookie";
+import "./shop.css";
+
+// Pages read cookies and live data, so each wraps its content in <Suspense> (works with or without cacheComponents).
+async function CartCount() {
+  const count = (await readCart()).reduce((n, l) => n + l.quantity, 0);
+  return <>{count ? ` (${count})` : ""}</>;
+}
+
+export default function ShopLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="cfa-page"><div className="cfa-shell">
+      <nav className="cfa-nav">
+        <Link href="/shop" className="cfa-brand">Shop</Link>
+        <div className="cfa-links">
+          <Link href="/shop/orders">Find an order</Link>
+          <Link href="/shop/cart">Cart<Suspense fallback={null}><CartCount /></Suspense></Link>
+        </div>
+      </nav>
+      {children}
+    </div></div>
+  );
+}

package/templates/nextjs/app/shop/orders/lookup-form.tsx

@@ -0,0 +1,32 @@
+"use client";
+
+import { useActionState } from "react";
+import { lookupOrder, type LookupState } from "../actions";
+
+const money = (cents: number, currency: string) =>
+  new Intl.NumberFormat("en-US", { style: "currency", currency: currency.toUpperCase() }).format(cents / 100);
+
+export function LookupForm() {
+  const [state, action, pending] = useActionState<LookupState, FormData>(lookupOrder, null);
+  return (
+    <>
+      <form action={action}>
+        <label className="cfa-field">Order number<input name="number" inputMode="numeric" placeholder="1001" required /></label>
+        <label className="cfa-field">Email<input name="email" type="email" required /></label>
+        <button className="cfa-button" disabled={pending}>{pending ? "Looking…" : "Find order"}</button>
+      </form>
+      {state?.error ? <p className="cfa-alert" style={{ marginTop: 16 }}>{state.error}</p> : null}
+      {state?.order ? (
+        <div style={{ marginTop: 24 }}>
+          <p><strong>Order #{state.order.number}</strong> · {state.order.status} · {money(state.order.total, state.order.currency)}</p>
+          <ul className="cfa-muted">{state.order.items.map((i) => <li key={i.name}>{i.name} × {i.quantity}</li>)}</ul>
+          {state.order.tracking.map((t) => (
+            <p key={t.number} className="cfa-muted">
+              Shipped{t.carrier ? ` with ${t.carrier}` : ""}: {t.url ? <a href={t.url}>{t.number}</a> : t.number}
+            </p>
+          ))}
+        </div>
+      ) : null}
+    </>
+  );
+}

package/templates/nextjs/app/shop/orders/page.tsx

@@ -0,0 +1,13 @@
+import { LookupForm } from "./lookup-form";
+
+export const metadata = { title: "Find an order" };
+
+export default function OrdersPage() {
+  return (
+    <div>
+      <h1 className="cfa-h1">Find an order</h1>
+      <p className="cfa-muted">Enter your order number and the email you used at checkout.</p>
+      <LookupForm />
+    </div>
+  );
+}

package/templates/nextjs/app/shop/page.tsx

@@ -0,0 +1,31 @@
+import Link from "next/link";
+import { Suspense } from "react";
+import { commerce, money } from "../../lib/commerce";
+
+export const metadata = { title: "Shop" };
+
+export default function ShopPage() {
+  return <Suspense fallback={<p className="cfa-muted">Loading…</p>}><Products /></Suspense>;
+}
+
+async function Products() {
+  const { data, error } = await commerce.products.list({ active: true, limit: 100 });
+  if (error) return <p className="cfa-alert">Couldn&apos;t load products: {error.message}</p>;
+  const products = data.data.filter((p) => p.variants.some((v) => v.active));
+  if (!products.length) return <p className="cfa-empty">No products yet. Add some with the SDK, the MCP server, or by connecting Printify/Printful.</p>;
+  return (
+    <div className="cfa-grid">
+      {products.map((p) => {
+        const prices = p.variants.filter((v) => v.active).map((v) => v.price);
+        const from = Math.min(...prices);
+        return (
+          <Link key={p.id} href={`/shop/${p.id}`} className="cfa-card">
+            {p.images[0] ? <img src={p.images[0]} alt={p.name} className="cfa-image" /> : <div className="cfa-placeholder" />}
+            <p className="cfa-title">{p.name}</p>
+            <p className="cfa-price">{prices.length > 1 && Math.max(...prices) !== from ? "From " : ""}{money(from, p.variants[0]?.currency)}</p>
+          </Link>
+        );
+      })}
+    </div>
+  );
+}

package/templates/nextjs/app/shop/shop.css

@@ -0,0 +1,31 @@
+/* Plain, prefixed CSS (cfa-*) so it works with or without Tailwind or CSS modules. Restyle freely. */
+/* The shop paints its own light page so it's readable whatever the app's global (e.g. dark-mode) styles are. */
+.cfa-page { min-height: 100vh; background: #fff; color: #111; color-scheme: light; }
+.cfa-shell { max-width: 1040px; margin: 0 auto; padding: 24px 16px 64px; font-family: system-ui, -apple-system, sans-serif; color: #111; }
+.cfa-nav { display: flex; align-items: center; justify-content: space-between; gap: 16px; padding-bottom: 20px; margin-bottom: 28px; border-bottom: 1px solid #e5e5e5; }
+.cfa-brand { font-weight: 600; font-size: 18px; color: inherit; text-decoration: none; }
+.cfa-links { display: flex; gap: 18px; font-size: 14px; }
+.cfa-links a { color: #444; text-decoration: none; }
+.cfa-links a:hover { color: #111; }
+.cfa-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(220px, 1fr)); gap: 24px; }
+.cfa-card { display: block; color: inherit; text-decoration: none; }
+.cfa-image { aspect-ratio: 1; width: 100%; object-fit: cover; border-radius: 10px; background: #f3f3f3; }
+.cfa-placeholder { aspect-ratio: 1; width: 100%; border-radius: 10px; background: #f3f3f3; }
+.cfa-title { margin: 10px 0 2px; font-size: 15px; font-weight: 500; }
+.cfa-price { color: #555; font-size: 14px; }
+.cfa-detail { display: grid; grid-template-columns: 1fr; gap: 32px; }
+@media (min-width: 760px) { .cfa-detail { grid-template-columns: 1fr 1fr; } }
+.cfa-h1 { font-size: 28px; font-weight: 600; margin: 0 0 8px; }
+.cfa-muted { color: #666; font-size: 14px; line-height: 1.5; white-space: pre-line; }
+.cfa-field { display: block; margin: 16px 0; font-size: 14px; }
+.cfa-field select, .cfa-field input { display: block; margin-top: 6px; width: 100%; max-width: 320px; height: 40px; padding: 0 10px; border: 1px solid #ccc; border-radius: 8px; font-size: 15px; background: #fff; }
+.cfa-button { display: inline-flex; align-items: center; justify-content: center; height: 44px; padding: 0 22px; border: 0; border-radius: 8px; background: #111; color: #fff; font-size: 15px; font-weight: 500; cursor: pointer; text-decoration: none; }
+.cfa-button:disabled { opacity: 0.5; cursor: not-allowed; }
+.cfa-secondary { background: #fff; color: #111; border: 1px solid #ccc; }
+.cfa-table { width: 100%; border-collapse: collapse; font-size: 15px; }
+.cfa-table td { padding: 14px 0; border-bottom: 1px solid #eee; vertical-align: middle; }
+.cfa-qty { width: 64px; height: 36px; padding: 0 8px; border: 1px solid #ccc; border-radius: 8px; }
+.cfa-row { display: flex; align-items: center; justify-content: space-between; gap: 16px; margin-top: 24px; flex-wrap: wrap; }
+.cfa-alert { padding: 12px 14px; border-radius: 8px; background: #fff4f4; color: #9b1c1c; font-size: 14px; margin-bottom: 16px; }
+.cfa-notice { padding: 12px 14px; border-radius: 8px; background: #f3f7ff; color: #1e3a8a; font-size: 14px; margin-bottom: 16px; }
+.cfa-empty { padding: 48px 0; text-align: center; color: #666; }

package/templates/nextjs/app/shop/thanks/clear-cart.tsx

@@ -0,0 +1,10 @@
+"use client";
+
+import { useEffect } from "react";
+import { clearCart } from "../actions";
+
+/** Empty the cart once the customer is back from Stripe (cookies can't be changed while rendering). */
+export function ClearCart() {
+  useEffect(() => { void clearCart(); }, []);
+  return null;
+}

package/templates/nextjs/app/shop/thanks/page.tsx

@@ -0,0 +1,47 @@
+import Link from "next/link";
+import { Suspense } from "react";
+import { cookies } from "next/headers";
+import { commerce, money } from "../../../lib/commerce";
+import { CHECKOUT_COOKIE } from "../cart-cookie";
+import { ClearCart } from "./clear-cart";
+
+export const metadata = { title: "Thank you" };
+
+export default function ThanksPage() {
+  return <Suspense fallback={<p className="cfa-muted">Loading…</p>}><Thanks /></Suspense>;
+}
+
+async function Thanks() {
+  const checkoutId = (await cookies()).get(CHECKOUT_COOKIE)?.value;
+  const { data: co } = checkoutId ? await commerce.checkouts.get(checkoutId) : { data: null };
+  // Stripe tells us about the payment by webhook, usually within a second or two.
+  const { data: order } = co?.order_id ? await commerce.orders.get(co.order_id) : { data: null };
+  return (
+    <div>
+      <ClearCart />
+      <h1 className="cfa-h1">Thank you!</h1>
+      {order ? (
+        <>
+          <p className="cfa-muted">Order #{order.number} is confirmed{order.email ? `. A receipt is on its way to ${order.email}` : ""}.</p>
+          <table className="cfa-table">
+            <tbody>
+              {order.items.map((i) => (
+                <tr key={i.variant_id + i.product_name}>
+                  <td>{i.product_name}{i.variant_name !== "Default" ? ` · ${i.variant_name}` : ""} × {i.quantity}</td>
+                  <td style={{ textAlign: "right" }}>{money(i.unit_price * i.quantity, order.currency)}</td>
+                </tr>
+              ))}
+              <tr><td><strong>Total</strong></td><td style={{ textAlign: "right" }}><strong>{money(order.total, order.currency)}</strong></td></tr>
+            </tbody>
+          </table>
+        </>
+      ) : (
+        <>
+          <p className="cfa-notice">We&apos;re confirming your payment. This page refreshes in a moment.</p>
+          <meta httpEquiv="refresh" content="3" />
+        </>
+      )}
+      <div className="cfa-row"><Link href="/shop" className="cfa-button cfa-secondary">Keep shopping</Link></div>
+    </div>
+  );
+}

package/templates/nextjs/lib/commerce.ts

@@ -0,0 +1,12 @@
+// CommerceForAI client for server code (server components, server actions, route handlers).
+// The API key is a secret: never import this file from a "use client" component.
+import { Commerce } from "commerceforai";
+
+if (!process.env.COMMERCEFORAI_API_KEY) {
+  console.warn("COMMERCEFORAI_API_KEY is not set. Run `npx commerceforai init` or add it to .env.local.");
+}
+
+export const commerce = new Commerce(process.env.COMMERCEFORAI_API_KEY ?? "");
+
+export const money = (cents: number, currency = "usd") =>
+  new Intl.NumberFormat("en-US", { style: "currency", currency: currency.toUpperCase() }).format(cents / 100);