@01.software/init 0.9.1 → 0.10.0

package/dist/create-app-templates/ecommerce/data/mock-catalog.json

@@ -0,0 +1,173 @@
+{
+  "shippingPolicy": {
+    "currency": "KRW",
+    "baseAmount": 3000,
+    "freeAboveAmount": 100000
+  },
+  "products": [
+    {
+      "product": {
+        "id": "prod-canvas-tote",
+        "slug": "canvas-market-tote",
+        "title": "Canvas Market Tote",
+        "description": "A sturdy everyday tote with enough structure for books, produce, and a laptop sleeve.",
+        "thumbnail": {
+          "url": "https://images.unsplash.com/photo-1594223274512-ad4803739b7c?auto=format&fit=crop&w=900&q=80",
+          "alt": "Canvas tote bag on a neutral studio surface"
+        },
+        "images": [
+          {
+            "url": "https://images.unsplash.com/photo-1594223274512-ad4803739b7c?auto=format&fit=crop&w=1200&q=80",
+            "alt": "Canvas tote bag on a neutral studio surface"
+          },
+          {
+            "url": "https://images.unsplash.com/photo-1542291026-7eec264c27ff?auto=format&fit=crop&w=1200&q=80",
+            "alt": "Packed goods for a daily market run"
+          }
+        ],
+        "status": "published"
+      },
+      "options": [
+        {
+          "id": "opt-color",
+          "slug": "color",
+          "title": "Color",
+          "values": [
+            { "id": "val-natural", "slug": "natural", "value": "Natural" },
+            { "id": "val-ink", "slug": "ink", "value": "Ink" }
+          ]
+        }
+      ],
+      "variants": [
+        {
+          "id": "var-tote-natural",
+          "productId": "prod-canvas-tote",
+          "title": "Natural",
+          "sku": "TOTE-NAT",
+          "price": 42000,
+          "stock": 18,
+          "reservedStock": 3,
+          "isUnlimited": false,
+          "optionValues": [
+            {
+              "optionId": "opt-color",
+              "valueId": "val-natural",
+              "valueSlug": "natural",
+              "value": "Natural"
+            }
+          ],
+          "images": [
+            {
+              "url": "https://images.unsplash.com/photo-1594223274512-ad4803739b7c?auto=format&fit=crop&w=1200&q=80",
+              "alt": "Natural canvas tote"
+            }
+          ]
+        },
+        {
+          "id": "var-tote-ink",
+          "productId": "prod-canvas-tote",
+          "title": "Ink",
+          "sku": "TOTE-INK",
+          "price": 45000,
+          "stock": 0,
+          "reservedStock": 0,
+          "isUnlimited": false,
+          "optionValues": [
+            {
+              "optionId": "opt-color",
+              "valueId": "val-ink",
+              "valueSlug": "ink",
+              "value": "Ink"
+            }
+          ],
+          "images": [
+            {
+              "url": "https://images.unsplash.com/photo-1590874103328-eac38a683ce7?auto=format&fit=crop&w=1200&q=80",
+              "alt": "Dark tote bag"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "product": {
+        "id": "prod-desk-lamp",
+        "slug": "task-lamp",
+        "title": "Task Lamp",
+        "description": "A compact aluminum lamp with a warm dimmable beam for late packing, reading, or desk work.",
+        "thumbnail": {
+          "url": "https://images.unsplash.com/photo-1507473885765-e6ed057f782c?auto=format&fit=crop&w=900&q=80",
+          "alt": "Black task lamp on a desk"
+        },
+        "images": [
+          {
+            "url": "https://images.unsplash.com/photo-1507473885765-e6ed057f782c?auto=format&fit=crop&w=1200&q=80",
+            "alt": "Black task lamp on a desk"
+          }
+        ],
+        "status": "published"
+      },
+      "options": [
+        {
+          "id": "opt-finish",
+          "slug": "finish",
+          "title": "Finish",
+          "values": [
+            { "id": "val-black", "slug": "black", "value": "Black" },
+            { "id": "val-silver", "slug": "silver", "value": "Silver" }
+          ]
+        }
+      ],
+      "variants": [
+        {
+          "id": "var-lamp-black",
+          "productId": "prod-desk-lamp",
+          "title": "Black",
+          "sku": "LAMP-BLK",
+          "price": 78000,
+          "stock": 6,
+          "reservedStock": 1,
+          "isUnlimited": false,
+          "optionValues": [
+            {
+              "optionId": "opt-finish",
+              "valueId": "val-black",
+              "valueSlug": "black",
+              "value": "Black"
+            }
+          ],
+          "images": [
+            {
+              "url": "https://images.unsplash.com/photo-1507473885765-e6ed057f782c?auto=format&fit=crop&w=1200&q=80",
+              "alt": "Black task lamp"
+            }
+          ]
+        },
+        {
+          "id": "var-lamp-silver",
+          "productId": "prod-desk-lamp",
+          "title": "Silver",
+          "sku": "LAMP-SLV",
+          "price": 82000,
+          "stock": 1000,
+          "reservedStock": 0,
+          "isUnlimited": true,
+          "optionValues": [
+            {
+              "optionId": "opt-finish",
+              "valueId": "val-silver",
+              "valueSlug": "silver",
+              "value": "Silver"
+            }
+          ],
+          "images": [
+            {
+              "url": "https://images.unsplash.com/photo-1513506003901-1e6a229e2d15?auto=format&fit=crop&w=1200&q=80",
+              "alt": "Silver desk lamp"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/dist/create-app-templates/ecommerce/eslint.config.mjs

@@ -0,0 +1,18 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+
+const eslintConfig = defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  // Override default ignores of eslint-config-next.
+  globalIgnores([
+    // Default ignores of eslint-config-next:
+    ".next/**",
+    "out/**",
+    "build/**",
+    "next-env.d.ts",
+  ]),
+]);
+
+export default eslintConfig;

package/dist/create-app-templates/ecommerce/lib/cart/cookie.ts

@@ -0,0 +1,40 @@
+import "server-only";
+import { cookies } from "next/headers";
+import { appConfig } from "@/app-config";
+
+/**
+ * Guest-cart ownership cookie. It holds the unguessable `cartToken` capability
+ * — never the enumerable cart id — and is **HttpOnly + SameSite + Secure** so it
+ * is invisible to client JS (XSS) and only travels on same-site requests. The
+ * SDK cart endpoints re-verify this token against the cart row on every
+ * mutation (`assertCartAccess`), so possession of the cookie is the guest
+ * ownership check.
+ *
+ * `.set`/`.delete` are only valid in Route Handlers / Server Functions, never
+ * during Server Component render — keep cookie writes in the cart/checkout
+ * routes.
+ */
+const COOKIE_MAX_AGE_SECONDS = 60 * 60 * 24 * 30; // 30 days
+
+export async function readCartToken(): Promise<string | null> {
+  const store = await cookies();
+  return store.get(appConfig.cartKey)?.value ?? null;
+}
+
+export async function writeCartToken(token: string): Promise<void> {
+  const store = await cookies();
+  store.set(appConfig.cartKey, token, {
+    httpOnly: true,
+    // Secure cookies are dropped by browsers over plain http, so allow http in
+    // local dev and enforce Secure in production.
+    secure: process.env.NODE_ENV === "production",
+    sameSite: "lax",
+    path: "/",
+    maxAge: COOKIE_MAX_AGE_SECONDS,
+  });
+}
+
+export async function clearCartToken(): Promise<void> {
+  const store = await cookies();
+  store.delete(appConfig.cartKey);
+}

package/dist/create-app-templates/ecommerce/lib/cart/normalize.ts

@@ -0,0 +1,32 @@
+import type { CartLine } from "../commerce/types.ts";
+
+const MAX_LINE_QUANTITY = 99;
+
+export function normalizeCartLines(input: unknown): CartLine[] {
+  if (!Array.isArray(input)) return [];
+
+  const quantities = new Map<string, number>();
+
+  for (const line of input) {
+    if (!line || typeof line !== "object") continue;
+
+    const candidate = line as { variantId?: unknown; quantity?: unknown };
+    if (typeof candidate.variantId !== "string") continue;
+
+    const variantId = candidate.variantId.trim();
+    if (!variantId) continue;
+
+    const quantity =
+      typeof candidate.quantity === "number" && Number.isFinite(candidate.quantity)
+        ? Math.floor(candidate.quantity)
+        : 1;
+    const safeQuantity = Math.min(MAX_LINE_QUANTITY, Math.max(1, quantity));
+
+    quantities.set(variantId, (quantities.get(variantId) ?? 0) + safeQuantity);
+  }
+
+  return Array.from(quantities.entries()).map(([variantId, quantity]) => ({
+    variantId,
+    quantity: Math.min(MAX_LINE_QUANTITY, quantity),
+  }));
+}

package/dist/create-app-templates/ecommerce/lib/cart/parse-cart-request.ts

@@ -0,0 +1,56 @@
+import type { CartItemRef } from "../commerce/types.ts";
+
+const MAX_QUANTITY = 99;
+
+export function parseAddItem(input: unknown): CartItemRef {
+  const body = asRecord(input);
+  const option = optionalString(body.optionId);
+  return {
+    productId: requiredString(body.productId, "productId"),
+    variantId: requiredString(body.variantId, "variantId"),
+    ...(option ? { option } : {}),
+    quantity: parseQuantity(body.quantity),
+  };
+}
+
+export function parseUpdateItem(input: unknown): {
+  cartItemId: string;
+  quantity: number;
+} {
+  const body = asRecord(input);
+  return {
+    cartItemId: requiredString(body.cartItemId, "cartItemId"),
+    quantity: parseQuantity(body.quantity),
+  };
+}
+
+export function parseRemoveItem(input: unknown): { cartItemId: string } {
+  const body = asRecord(input);
+  return { cartItemId: requiredString(body.cartItemId, "cartItemId") };
+}
+
+function asRecord(input: unknown): Record<string, unknown> {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new Error("Request body must be an object");
+  }
+  return input as Record<string, unknown>;
+}
+
+function requiredString(input: unknown, field: string): string {
+  if (typeof input !== "string" || input.trim() === "") {
+    throw new Error(`${field} is required`);
+  }
+  return input.trim();
+}
+
+function optionalString(input: unknown): string | undefined {
+  if (input === undefined || input === null || input === "") return undefined;
+  if (typeof input !== "string") throw new Error("optionId must be a string");
+  return input.trim() || undefined;
+}
+
+function parseQuantity(input: unknown): number {
+  const value =
+    typeof input === "number" && Number.isFinite(input) ? Math.floor(input) : 1;
+  return Math.min(MAX_QUANTITY, Math.max(1, value));
+}

package/dist/create-app-templates/ecommerce/lib/cart/route-helpers.ts

@@ -0,0 +1,17 @@
+import { CartNotFoundError } from "./server-cart.ts";
+
+/** Map a cart-route error to a public JSON response with a sensible status. */
+export function cartErrorResponse(error: unknown): Response {
+  const message = error instanceof Error ? error.message : "Cart request failed";
+
+  if (error instanceof CartNotFoundError) {
+    return Response.json({ code: "cart_not_found", message }, { status: 409 });
+  }
+  if (/required|must be an object|must be a string/.test(message)) {
+    return Response.json({ code: "invalid_request", message }, { status: 400 });
+  }
+  if (/stock|not found/i.test(message)) {
+    return Response.json({ code: "cart_unavailable", message }, { status: 422 });
+  }
+  return Response.json({ code: "cart_failed", message }, { status: 500 });
+}

package/dist/create-app-templates/ecommerce/lib/cart/select-provider.ts

@@ -0,0 +1,44 @@
+import "../server-only-guard.ts";
+import {
+  getCommerceProvider,
+  getCustomerCartProvider,
+} from "../commerce/provider.server.ts";
+import type { CartProvider } from "../commerce/provider.ts";
+// scaffold:customer:start
+import { getSessionToken } from "../customer/session.ts";
+// scaffold:customer:end
+
+/**
+ * Pick the cart provider for a session token. A logged-in customer (token
+ * present) operates a server-owned, device-portable, customer-bound cart through
+ * a **customer-JWT-scoped** client; an anonymous visitor keeps the guest cart
+ * path. Both still address the cart by the `cartToken` in the HttpOnly cart
+ * cookie — only the client (and thus the ownership check) differs.
+ *
+ * Dependency-injected so the branch unit-tests with fake providers and without
+ * `next/headers`.
+ */
+export function resolveCartProvider(
+  sessionToken: string | null,
+  deps: {
+    guest: () => CartProvider;
+    customer: (token: string) => CartProvider;
+  } = { guest: getCommerceProvider, customer: getCustomerCartProvider },
+): CartProvider {
+  return sessionToken ? deps.customer(sessionToken) : deps.guest();
+}
+
+/**
+ * Resolve the cart provider for the current request, reading the customer-JWT
+ * session cookie. The customer-session coupling lives in the
+ * `scaffold:customer` block so a guest-only scaffold (customer accounts pruned)
+ * compiles to the guest path alone — without it, `sessionToken` stays `null` and
+ * this always returns the guest provider.
+ */
+export async function resolveCartProviderForRequest(): Promise<CartProvider> {
+  // scaffold:customer:start
+  const sessionToken = await getSessionToken();
+  if (sessionToken) return resolveCartProvider(sessionToken);
+  // scaffold:customer:end
+  return resolveCartProvider(null);
+}

package/dist/create-app-templates/ecommerce/lib/cart/server-cart.ts

@@ -0,0 +1,96 @@
+import "server-only";
+import type { CartItemRef, CartView } from "../commerce/types.ts";
+import { clearCartToken, readCartToken, writeCartToken } from "./cookie.ts";
+import { resolveCartProviderForRequest } from "./select-provider.ts";
+
+/** Thrown when a mutation is attempted without an owned cart cookie. */
+export class CartNotFoundError extends Error {
+  constructor() {
+    super("No active cart");
+    this.name = "CartNotFoundError";
+  }
+}
+
+/**
+ * Resolve the cart provider for the current request. Guest by default; a
+ * logged-in customer's session cookie (when customer accounts are present)
+ * routes to the customer-JWT-scoped provider — see `select-provider.ts`.
+ */
+const cartProvider = resolveCartProviderForRequest;
+
+/**
+ * Read the current cart from the ownership cookie. Read-only: a
+ * stale/expired/completed token resolves to `null` (a fresh cart is minted on
+ * the next add) and the cookie is not mutated here, so this is safe to call
+ * from any context including Server Component render.
+ */
+export async function getCartFromCookie(): Promise<CartView | null> {
+  const token = await readCartToken();
+  if (!token) return null;
+  return (await cartProvider()).getCart(token);
+}
+
+/**
+ * Add a line, creating + stamping a fresh cart cookie when none is owned yet (or
+ * when the owned token no longer resolves to an active cart). For a logged-in
+ * customer the new cart is minted via the customer-JWT client, so it is
+ * customer-bound (JWT auto-binds `customer`) — never a guest cart.
+ */
+export async function addItemToCart(item: CartItemRef): Promise<CartView> {
+  const provider = await cartProvider();
+  let token = await readCartToken();
+
+  if (token && !(await provider.getCart(token))) {
+    token = null;
+  }
+  if (!token) {
+    // Minted through the resolved provider: for a logged-in customer that is the
+    // customer client, so create() is customer-bound. (If a prior login-sync
+    // failed best-effort and left a guest token, the logged-in customer keeps
+    // operating that same-identity guest cart until the next successful sync —
+    // never another identity's cart, since the customer client re-verifies
+    // ownership.)
+    const created = await provider.createCart();
+    token = created.cartToken;
+    await writeCartToken(token);
+  }
+
+  return provider.addCartItem({ cartToken: token, item });
+}
+
+export async function updateCartItemQuantity(input: {
+  cartItemId: string;
+  quantity: number;
+}): Promise<CartView> {
+  const token = await requireCartToken();
+  return (await cartProvider()).updateCartItem({ cartToken: token, ...input });
+}
+
+export async function removeCartItemFromCart(input: {
+  cartItemId: string;
+}): Promise<CartView> {
+  const token = await requireCartToken();
+  return (await cartProvider()).removeCartItem({ cartToken: token, ...input });
+}
+
+export async function clearActiveCart(): Promise<CartView | null> {
+  const token = await readCartToken();
+  if (!token) return null;
+  return (await cartProvider()).clearCart({ cartToken: token });
+}
+
+/** Returns the owned cart token for checkout, or null when no cart is owned. */
+export async function getCheckoutCartToken(): Promise<string | null> {
+  return readCartToken();
+}
+
+/** Drop the cart cookie once a checkout has consumed the cart. */
+export async function dropCartCookie(): Promise<void> {
+  await clearCartToken();
+}
+
+async function requireCartToken(): Promise<string> {
+  const token = await readCartToken();
+  if (!token) throw new CartNotFoundError();
+  return token;
+}

package/dist/create-app-templates/ecommerce/lib/cart/sync-on-login.server.ts

@@ -0,0 +1,34 @@
+import "server-only";
+import { resolveCustomerCartToken } from "../customer/cart-sync.ts";
+import { createCustomerCommerceClient } from "../customer/client.server.ts";
+import { clearCartToken, readCartToken, writeCartToken } from "./cookie.ts";
+
+/**
+ * After a login/register mints the session JWT, slave the active-cart cookie to
+ * the customer's server-owned cart: union any pre-login guest cart, else load
+ * the existing customer cart, then persist the resolved `cartToken` (or clear
+ * the cookie when the customer has no active cart). Route Handlers only — it
+ * writes cookies.
+ *
+ * Best-effort: a sync failure (network/backend) must not fail the login. The
+ * session JWT cookie is already set; the next cart action recovers (a logged-in
+ * `addItem` mints a customer-bound cart through the customer client).
+ */
+export async function syncActiveCartCookieOnLogin(token: string): Promise<void> {
+  const client = await createCustomerCommerceClient(token);
+  if (!client) return;
+  const guestCartToken = await readCartToken();
+  try {
+    const { cartToken } = await resolveCustomerCartToken(
+      client.commerce,
+      guestCartToken,
+    );
+    if (cartToken) {
+      await writeCartToken(cartToken);
+    } else {
+      await clearCartToken();
+    }
+  } catch {
+    // Leave the cart cookie as-is; login itself must still succeed.
+  }
+}

package/dist/create-app-templates/ecommerce/lib/cart/use-cart.tsx

@@ -0,0 +1,151 @@
+"use client";
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type ReactNode,
+} from "react";
+import type { CartItemRef, CartView } from "../commerce/types.ts";
+
+type CartContextValue = {
+  cart: CartView | null;
+  loading: boolean;
+  error: string | null;
+  itemCount: number;
+  addItem: (item: CartItemRef) => Promise<boolean>;
+  updateItem: (input: {
+    cartItemId: string;
+    quantity: number;
+  }) => Promise<void>;
+  removeItem: (cartItemId: string) => Promise<void>;
+  clear: () => Promise<void>;
+  /** Drop the local cart view (e.g. after checkout consumed the server cart). */
+  reset: () => void;
+};
+
+const CartContext = createContext<CartContextValue | null>(null);
+
+/**
+ * Client cart state backed by the server cart routes (`/api/cart*`). The cart
+ * lives in the Console (`commerce.cart.*`); this holds only the rendered view —
+ * the ownership `cartToken` stays in the HttpOnly cookie, never in JS.
+ */
+export function CartProvider({ children }: { children: ReactNode }) {
+  const [cart, setCart] = useState<CartView | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  // Hydrate the current cart on mount. setState lives in the async resolution
+  // callbacks (external-system → React sync), not the synchronous effect body.
+  useEffect(() => {
+    let active = true;
+    fetch("/api/cart")
+      .then((response) => response.json() as Promise<{ cart?: CartView | null }>)
+      .then((data) => {
+        if (!active) return;
+        setCart(data.cart ?? null);
+        setLoading(false);
+      })
+      .catch(() => {
+        if (!active) return;
+        setCart(null);
+        setLoading(false);
+      });
+    return () => {
+      active = false;
+    };
+  }, []);
+
+  const mutate = useCallback(
+    async (url: string, method: string, body?: unknown): Promise<boolean> => {
+      setError(null);
+      try {
+        const response = await fetch(url, {
+          method,
+          headers: { "Content-Type": "application/json" },
+          body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        const data = (await response.json().catch(() => ({}))) as {
+          cart?: CartView | null;
+          message?: string;
+        };
+        if (!response.ok) {
+          setError(data.message ?? "Cart update failed");
+          return false;
+        }
+        setCart(data.cart ?? null);
+        return true;
+      } catch {
+        setError("Cart update failed");
+        return false;
+      }
+    },
+    [],
+  );
+
+  const addItem = useCallback(
+    (item: CartItemRef) => mutate("/api/cart/items", "POST", item),
+    [mutate],
+  );
+  const updateItem = useCallback(
+    async (input: { cartItemId: string; quantity: number }) => {
+      await mutate("/api/cart/items", "PATCH", input);
+    },
+    [mutate],
+  );
+  const removeItem = useCallback(
+    async (cartItemId: string) => {
+      await mutate("/api/cart/items", "DELETE", { cartItemId });
+    },
+    [mutate],
+  );
+  const clear = useCallback(async () => {
+    await mutate("/api/cart/clear", "POST");
+  }, [mutate]);
+  const reset = useCallback(() => {
+    setCart(null);
+    setError(null);
+  }, []);
+
+  const itemCount =
+    cart?.items.reduce((sum, item) => sum + item.quantity, 0) ?? 0;
+
+  const value = useMemo<CartContextValue>(
+    () => ({
+      cart,
+      loading,
+      error,
+      itemCount,
+      addItem,
+      updateItem,
+      removeItem,
+      clear,
+      reset,
+    }),
+    [
+      cart,
+      loading,
+      error,
+      itemCount,
+      addItem,
+      updateItem,
+      removeItem,
+      clear,
+      reset,
+    ],
+  );
+
+  return <CartContext.Provider value={value}>{children}</CartContext.Provider>;
+}
+
+export function useCart(): CartContextValue {
+  const context = useContext(CartContext);
+  if (!context) {
+    throw new Error("useCart must be used within a CartProvider");
+  }
+  return context;
+}

package/dist/create-app-templates/ecommerce/lib/checkout/checkout-errors.ts

@@ -0,0 +1,22 @@
+const CHECKOUT_VALIDATION_PATTERN = /required|must be|valid email|payload|empty/;
+
+export function getCheckoutErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : "Checkout failed";
+}
+
+export function getCheckoutErrorStatus(error: unknown): number {
+  const status = readHttpStatus(error);
+  if (status !== null) return status;
+
+  return CHECKOUT_VALIDATION_PATTERN.test(getCheckoutErrorMessage(error))
+    ? 400
+    : 422;
+}
+
+function readHttpStatus(error: unknown): number | null {
+  if (typeof error !== "object" || error === null) return null;
+  const status = (error as { status?: unknown }).status;
+  return typeof status === "number" && status >= 400 && status < 500
+    ? status
+    : null;
+}