@01.software/init 0.9.2 → 0.10.1

package/dist/create-app-templates/ecommerce/components/product/product-gallery.tsx

@@ -0,0 +1,39 @@
+import Image from "next/image";
+import type { ProductDetail } from "@/lib/commerce/types";
+
+export function ProductGallery({ detail }: { detail: ProductDetail }) {
+  const images =
+    detail.product.images.length > 0
+      ? detail.product.images
+      : [detail.product.thumbnail].filter((image) => image !== null && image !== undefined);
+  const primary = images[0];
+
+  return (
+    <figure>
+      {primary ? (
+        <Image
+          src={primary.url}
+          alt={primary.alt ?? detail.product.title}
+          width={1000}
+          height={800}
+          priority
+        />
+      ) : null}
+      <figcaption>{detail.product.title}</figcaption>
+      {images.length > 1 ? (
+        <ul aria-label="Additional product images">
+          {images.slice(1, 4).map((image) => (
+            <li key={image.url}>
+              <Image
+                src={image.url}
+                alt={image.alt ?? detail.product.title}
+                width={320}
+                height={320}
+              />
+            </li>
+          ))}
+        </ul>
+      ) : null}
+    </figure>
+  );
+}

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,135 @@
+import "server-only";
+import type { CartItemRef, CartView } from "../commerce/types.ts";
+// scaffold:customer:start
+import { resolveCustomerCartToken } from "../customer/cart-sync.ts";
+import { createCustomerCommerceClient } from "../customer/client.server.ts";
+import { getSessionToken } from "../customer/session.ts";
+// scaffold:customer:end
+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();
+
+  // scaffold:customer:start
+  const sessionToken = await getSessionToken();
+  if (token && sessionToken) {
+    token = (await recoverCustomerCartToken(token, sessionToken)) ?? token;
+  }
+  // scaffold:customer:end
+
+  if (token && !(await provider.getCart(token))) {
+    let nextToken: string | null = null;
+    // scaffold:customer:start
+    if (sessionToken) {
+      nextToken = await recoverCustomerCartToken(token, sessionToken);
+    }
+    // scaffold:customer:end
+    token = nextToken && (await provider.getCart(nextToken)) ? nextToken : null;
+  }
+  if (!token) {
+    // Minted through the resolved provider: for a logged-in customer that is the
+    // customer client, so create() is customer-bound.
+    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;
+}
+
+// scaffold:customer:start
+async function recoverCustomerCartToken(
+  staleCartToken: string,
+  sessionToken: string,
+): Promise<string | null> {
+  const client = await createCustomerCommerceClient(sessionToken);
+  if (!client) return null;
+
+  try {
+    const { cartToken } = await resolveCustomerCartToken(
+      client.commerce,
+      staleCartToken,
+    );
+    if (cartToken) {
+      await writeCartToken(cartToken);
+    } else {
+      await clearCartToken();
+    }
+    return cartToken;
+  } catch {
+    return null;
+  }
+}
+// scaffold:customer:end

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.
+  }
+}