@01.software/init 0.9.1 → 0.10.0

package/dist/create-app-templates/ecommerce/components/checkout/checkout-form.tsx

@@ -0,0 +1,267 @@
+"use client";
+
+import Link from "next/link";
+import { useRouter } from "next/navigation";
+import { useState } from "react";
+import { paymentProviderLabel } from "@/app-config";
+import { useCart } from "@/lib/cart/use-cart";
+import type { CustomerSnapshot, ShippingAddress } from "@/lib/commerce/types";
+import type { ClientPaymentRequest } from "@/lib/payment/types";
+
+type CheckoutResponse = {
+  orderNumber: string;
+  paymentId: string;
+  amount: number;
+  currency: string;
+  redirectUrl?: string;
+  clientPayment?: ClientPaymentRequest;
+};
+
+export function CheckoutForm() {
+  const router = useRouter();
+  const { cart, loading, reset } = useCart();
+  const [error, setError] = useState<string | null>(null);
+  const [submitting, setSubmitting] = useState(false);
+  const providerLabel = paymentProviderLabel();
+
+  async function submit(formData: FormData) {
+    setSubmitting(true);
+    setError(null);
+
+    const customerSnapshot: CustomerSnapshot = {
+      name: value(formData, "customerName"),
+      email: value(formData, "email"),
+      phone: value(formData, "phone"),
+    };
+    const shippingAddress: ShippingAddress = {
+      recipientName: value(formData, "recipientName"),
+      phone: value(formData, "shippingPhone"),
+      postalCode: value(formData, "postalCode"),
+      address: value(formData, "address"),
+      detailAddress: value(formData, "detailAddress"),
+      deliveryMessage: value(formData, "deliveryMessage"),
+    };
+
+    const response = await fetch("/api/checkout", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ customerSnapshot, shippingAddress }),
+    });
+
+    if (!response.ok) {
+      const payload = (await response.json()) as { message?: string };
+      setError(payload.message ?? "Checkout failed");
+      setSubmitting(false);
+      return;
+    }
+
+    const payload = (await response.json()) as CheckoutResponse;
+    // scaffold:provider:portone:start
+    if (payload.clientPayment?.provider === "portone") {
+      try {
+        await requestPortOnePayment(payload.clientPayment);
+        reset();
+      } catch (error) {
+        setError(error instanceof Error ? error.message : "Payment failed");
+        setSubmitting(false);
+      }
+      return;
+    }
+    // scaffold:provider:portone:end
+    // scaffold:provider:tosspayments:start
+    if (payload.clientPayment?.provider === "tosspayments") {
+      try {
+        await requestTossPayments(payload.clientPayment);
+        reset();
+      } catch (error) {
+        setError(error instanceof Error ? error.message : "Payment failed");
+        setSubmitting(false);
+      }
+      return;
+    }
+    // scaffold:provider:tosspayments:end
+
+    reset();
+    router.push(
+      payload.redirectUrl ??
+        `/checkout/success?paymentId=${encodeURIComponent(payload.paymentId)}&orderNumber=${encodeURIComponent(payload.orderNumber)}`,
+    );
+  }
+
+  if (!loading && (!cart || cart.items.length === 0)) {
+    return (
+      <section>
+        <h1>Cart required</h1>
+        <p>Add at least one item before checkout.</p>
+        <Link href="/products">Browse products</Link>
+      </section>
+    );
+  }
+
+  return (
+    <form action={submit} aria-describedby="checkout-summary">
+      <section aria-labelledby="checkout-title">
+        <h1 id="checkout-title">Review order details</h1>
+        <p id="checkout-summary">
+          Customer and shipping details are collected before payment handoff.
+        </p>
+
+        <fieldset>
+          <legend>Customer</legend>
+          <Field name="customerName" label="Customer name" autoComplete="name" />
+          <Field name="email" label="Email" type="email" autoComplete="email" />
+          <Field name="phone" label="Phone" autoComplete="tel" />
+        </fieldset>
+
+        <fieldset>
+          <legend>Shipping</legend>
+          <Field name="recipientName" label="Recipient name" autoComplete="name" />
+          <Field name="shippingPhone" label="Shipping phone" autoComplete="tel" />
+          <Field name="postalCode" label="Postal code" autoComplete="postal-code" />
+          <Field name="address" label="Address" autoComplete="street-address" />
+          <Field name="detailAddress" label="Address detail" />
+          <Field name="deliveryMessage" label="Shipping message" required={false} />
+        </fieldset>
+      </section>
+
+      <aside>
+        <h2>Payment handoff</h2>
+        <p>
+          Local demo payments complete immediately. Configured {providerLabel}{" "}
+          credentials start the provider handoff after the order is created.
+        </p>
+        <dl>
+          <div>
+            <dt>Order lines</dt>
+            <dd>Current cart</dd>
+          </div>
+          <div>
+            <dt>Price check</dt>
+            <dd>Before payment</dd>
+          </div>
+          <div>
+            <dt>Provider</dt>
+            <dd>{providerLabel}</dd>
+          </div>
+        </dl>
+        {error ? <p role="alert">{error}</p> : null}
+        <button type="submit" disabled={submitting}>
+          {submitting ? "Creating order..." : "Start payment"}
+        </button>
+        <p aria-live="polite">{submitting ? "Creating order and payment request." : null}</p>
+      </aside>
+    </form>
+  );
+}
+
+// scaffold:provider:portone:start
+async function requestPortOnePayment(payment: Extract<ClientPaymentRequest, { provider: "portone" }>) {
+  const PortOne = await import("@portone/browser-sdk/v2");
+  const redirectUrl = new URL("/api/checkout/payment-return", window.location.origin);
+  redirectUrl.searchParams.set("paymentId", payment.paymentId);
+  redirectUrl.searchParams.set("orderNumber", payment.orderNumber);
+
+  const result = await PortOne.requestPayment({
+    storeId: payment.storeId,
+    channelKey: payment.channelKey,
+    paymentId: payment.paymentId,
+    orderName: payment.orderName,
+    totalAmount: payment.amount,
+    currency: payment.currency,
+    payMethod: payment.payMethod,
+    customer: {
+      fullName: payment.customer.name,
+      email: payment.customer.email,
+      phoneNumber: payment.customer.phone,
+    },
+    redirectUrl: redirectUrl.toString(),
+    forceRedirect: true,
+    // Durable orderNumber↔pgPaymentId mapping carried on the payment itself, so
+    // a webhook arriving before/instead of this redirect can resolve the open
+    // checkout via a server re-fetch (#1544 / I6). No local index.
+    customData: { orderNumber: payment.orderNumber },
+  } as Parameters<typeof PortOne.requestPayment>[0]);
+
+  if (result?.code) {
+    throw new Error(result.message ?? result.code);
+  }
+
+  if (result?.paymentId) {
+    window.location.assign(redirectUrl.toString());
+  }
+}
+// scaffold:provider:portone:end
+
+// scaffold:provider:tosspayments:start
+async function requestTossPayments(
+  payment: Extract<ClientPaymentRequest, { provider: "tosspayments" }>,
+) {
+  const { ANONYMOUS, loadTossPayments } = await import(
+    "@tosspayments/tosspayments-sdk"
+  );
+  const tossPayments = await loadTossPayments(payment.clientKey);
+  const checkoutReturnUrl = new URL(
+    "/api/checkout/payment-return",
+    window.location.origin,
+  );
+  checkoutReturnUrl.searchParams.set("paymentId", payment.paymentId);
+  checkoutReturnUrl.searchParams.set("orderNumber", payment.orderNumber);
+
+  const failUrl = new URL("/checkout", window.location.origin);
+  failUrl.searchParams.set("paymentId", payment.paymentId);
+  failUrl.searchParams.set("orderNumber", payment.orderNumber);
+
+  const paymentClient = tossPayments.payment({
+    customerKey: payment.customerKey ?? ANONYMOUS,
+  });
+
+  await paymentClient.requestPayment({
+    method: "CARD",
+    amount: {
+      currency: payment.currency,
+      value: payment.amount,
+    },
+    orderId: payment.paymentId,
+    orderName: payment.orderName,
+    successUrl: checkoutReturnUrl.toString(),
+    failUrl: failUrl.toString(),
+    customerEmail: payment.customer.email,
+    customerName: payment.customer.name,
+    customerMobilePhone: payment.customer.phone,
+    // Durable orderNumber↔pgPaymentId mapping carried on the payment itself, so
+    // a webhook arriving before/instead of this redirect can resolve the open
+    // checkout via a server re-fetch (#1544 / I6). No local index.
+    metadata: { orderNumber: payment.orderNumber },
+  });
+}
+// scaffold:provider:tosspayments:end
+
+function Field({
+  label,
+  name,
+  type = "text",
+  autoComplete,
+  required = true,
+}: {
+  label: string;
+  name: string;
+  type?: string;
+  autoComplete?: string;
+  required?: boolean;
+}) {
+  return (
+    <label>
+      {label}
+      <input
+        name={name}
+        type={type}
+        autoComplete={autoComplete}
+        required={required}
+      />
+    </label>
+  );
+}
+
+function value(formData: FormData, key: string): string {
+  return String(formData.get(key) ?? "").trim();
+}

package/dist/create-app-templates/ecommerce/components/checkout/checkout-reconcile.tsx

@@ -0,0 +1,78 @@
+"use client";
+
+import Link from "next/link";
+import { useEffect, useRef, useState } from "react";
+
+type ReconcileStatus =
+  | "paid"
+  | "pending"
+  | "failed"
+  | "canceled"
+  | "payment_not_found";
+
+type ViewState = ReconcileStatus | "loading" | "error";
+
+/**
+ * Client trigger that reconciles the order once on mount via the reconcile
+ * route handler, keeping the mutation off the success-page RSC render
+ * (#1544 / I6). The `started` ref makes it fire exactly once even under React
+ * StrictMode's double-mount; `syncOrderPayment` is idempotent regardless.
+ */
+export function CheckoutReconcile({
+  paymentId,
+  orderNumber,
+}: {
+  paymentId: string;
+  orderNumber?: string;
+}) {
+  const [state, setState] = useState<ViewState>("loading");
+  const started = useRef(false);
+
+  useEffect(() => {
+    if (started.current) return;
+    started.current = true;
+
+    void (async () => {
+      try {
+        const response = await fetch("/api/checkout/reconcile", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ paymentId, orderNumber }),
+        });
+        if (!response.ok) {
+          setState("error");
+          return;
+        }
+        const data = (await response.json()) as { status: ReconcileStatus };
+        setState(data.status);
+      } catch {
+        setState("error");
+      }
+    })();
+  }, [paymentId, orderNumber]);
+
+  return (
+    <section>
+      <h1>{titleForState(state)}</h1>
+      <p>{bodyForState(state)}</p>
+      <Link href="/products">Continue shopping</Link>
+    </section>
+  );
+}
+
+function titleForState(state: ViewState): string {
+  if (state === "loading") return "Confirming payment…";
+  if (state === "paid") return "Payment confirmed";
+  if (state === "pending") return "Payment pending";
+  if (state === "payment_not_found") return "Payment not found";
+  if (state === "error") return "Could not confirm payment";
+  return "Payment not completed";
+}
+
+function bodyForState(state: ViewState): string {
+  if (state === "loading") return "Reconciling your order with the payment provider…";
+  if (state === "error") {
+    return "We could not confirm this payment. If you were charged, it will be reconciled automatically.";
+  }
+  return `Payment sync result: ${state}`;
+}

package/dist/create-app-templates/ecommerce/components/layout/account-nav.tsx

@@ -0,0 +1,48 @@
+"use client";
+
+import { useRouter } from "next/navigation";
+import Link from "next/link";
+import { useState } from "react";
+import type { CustomerSummary } from "@/lib/customer/auth-actions";
+
+/**
+ * Header account affordance. Renders login/register links for guests and the
+ * customer name + logout for an authenticated session. Logout posts JSON to the
+ * CSRF-guarded route, then refreshes so the server re-renders as a guest.
+ */
+export function AccountNav({ customer }: { customer: CustomerSummary | null }) {
+  const router = useRouter();
+  const [pending, setPending] = useState(false);
+
+  if (!customer) {
+    return (
+      <>
+        <Link href="/login">Login</Link>
+        <Link href="/register">Register</Link>
+      </>
+    );
+  }
+
+  async function logout() {
+    setPending(true);
+    try {
+      await fetch("/api/auth/logout", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: "{}",
+      });
+      router.refresh();
+    } finally {
+      setPending(false);
+    }
+  }
+
+  return (
+    <>
+      <span>{customer.name}</span>
+      <button type="button" onClick={logout} disabled={pending}>
+        {pending ? "Logging out…" : "Logout"}
+      </button>
+    </>
+  );
+}

package/dist/create-app-templates/ecommerce/components/layout/account-slot.tsx

@@ -0,0 +1,12 @@
+import { getCurrentCustomer } from "@/lib/customer/current-customer";
+import { AccountNav } from "./account-nav";
+
+/**
+ * Async server boundary for the header's account state. Kept separate from
+ * `SiteHeader` so the guest-only build (customer accounts pruned at scaffold
+ * time) leaves a plain synchronous header with no dangling `await`.
+ */
+export async function AccountSlot() {
+  const customer = await getCurrentCustomer();
+  return <AccountNav customer={customer} />;
+}

package/dist/create-app-templates/ecommerce/components/layout/cart-link.tsx

@@ -0,0 +1,13 @@
+"use client";
+
+import Link from "next/link";
+import { useCart } from "@/lib/cart/use-cart";
+
+export function CartLink() {
+  const { itemCount } = useCart();
+  return (
+    <Link href="/cart">
+      Cart{itemCount > 0 ? ` (${itemCount})` : ""}
+    </Link>
+  );
+}

package/dist/create-app-templates/ecommerce/components/layout/page-shell.tsx

@@ -0,0 +1,11 @@
+import type { ReactNode } from "react";
+import { SiteHeader } from "./site-header";
+
+export function PageShell({ children }: { children: ReactNode }) {
+  return (
+    <>
+      <SiteHeader />
+      <main>{children}</main>
+    </>
+  );
+}

package/dist/create-app-templates/ecommerce/components/layout/site-header.tsx

@@ -0,0 +1,22 @@
+import Link from "next/link";
+// scaffold:customer:start
+import { AccountSlot } from "./account-slot";
+// scaffold:customer:end
+import { CartLink } from "./cart-link";
+
+export function SiteHeader() {
+  return (
+    <header>
+      <div>
+        <Link href="/products">Console Commerce</Link>
+        <nav aria-label="Storefront">
+          <Link href="/products">Products</Link>
+          <CartLink />
+          {/* scaffold:customer:start */}
+          <AccountSlot />
+          {/* scaffold:customer:end */}
+        </nav>
+      </div>
+    </header>
+  );
+}

package/dist/create-app-templates/ecommerce/components/product/add-to-cart.tsx

@@ -0,0 +1,116 @@
+"use client";
+
+import { useMemo, useState } from "react";
+import { useCart } from "@/lib/cart/use-cart";
+import { formatMoney } from "@/lib/format";
+import { resolveVariantFromSelection } from "@/lib/commerce/variant-selection.ts";
+import type { ProductDetail } from "@/lib/commerce/types";
+
+export function AddToCart({ detail }: { detail: ProductDetail }) {
+  const firstVariant = detail.variants[0];
+  const [selection, setSelection] = useState<Record<string, string>>(() =>
+    Object.fromEntries(
+      firstVariant?.optionValues.map((value) => [value.optionId, value.valueId]) ?? [],
+    ),
+  );
+  const [quantity, setQuantity] = useState(1);
+  const [added, setAdded] = useState(false);
+  const [pending, setPending] = useState(false);
+  const { addItem, error } = useCart();
+
+  const selectedVariant = useMemo(
+    () => resolveVariantFromSelection(detail, selection),
+    [detail, selection],
+  );
+  const availableQuantity = selectedVariant?.isUnlimited
+    ? null
+    : Math.max(0, (selectedVariant?.stock ?? 0) - (selectedVariant?.reservedStock ?? 0));
+  const isAvailable = selectedVariant
+    ? availableQuantity === null || availableQuantity >= quantity
+    : false;
+
+  if (!firstVariant) {
+    return (
+      <section aria-labelledby="purchase-options">
+        <h2 id="purchase-options">Purchase options</h2>
+        <p>Unavailable</p>
+        <button type="button" disabled>
+          No variants available
+        </button>
+      </section>
+    );
+  }
+
+  return (
+    <section aria-labelledby="purchase-options">
+      <h2 id="purchase-options">Purchase options</h2>
+      <dl>
+        <dt>Selected price</dt>
+        <dd>
+          <output>{selectedVariant ? formatMoney(selectedVariant.price) : "Select options"}</output>
+        </dd>
+        <dt>Stock</dt>
+        <dd>{availableQuantity === null ? "Unlimited" : availableQuantity}</dd>
+      </dl>
+
+      {detail.options.map((option) => (
+        <fieldset key={option.id}>
+          <legend>{option.title}</legend>
+          <div>
+            {option.values.map((value) => {
+              const active = selection[option.id] === value.id;
+              return (
+                <button
+                  key={value.id}
+                  type="button"
+                  onClick={() =>
+                    setSelection((current) => ({
+                      ...current,
+                      [option.id]: value.id,
+                    }))
+                  }
+                  aria-pressed={active}
+                >
+                  {value.value}
+                </button>
+              );
+            })}
+          </div>
+        </fieldset>
+      ))}
+
+      <label>
+        Quantity
+        <input
+          type="number"
+          min="1"
+          max="99"
+          value={quantity}
+          aria-label="Quantity"
+          onChange={(event) => setQuantity(Math.max(1, Number(event.target.value) || 1))}
+        />
+      </label>
+
+      <button
+        type="button"
+        disabled={!selectedVariant || !isAvailable || pending}
+        onClick={async () => {
+          if (!selectedVariant) return;
+          setAdded(false);
+          setPending(true);
+          const ok = await addItem({
+            productId: detail.product.id,
+            variantId: selectedVariant.id,
+            quantity,
+          });
+          setPending(false);
+          if (ok) setAdded(true);
+        }}
+      >
+        {pending ? "Adding..." : isAvailable ? "Add to cart" : "Sold out"}
+      </button>
+      <p aria-live="polite">{added ? "Added to cart." : null}</p>
+      {error ? <p role="alert">{error}</p> : null}
+    </section>
+  );
+}

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

@@ -0,0 +1,50 @@
+import Image from "next/image";
+import Link from "next/link";
+import { summarizeProductAvailability } from "@/lib/commerce/product-summary";
+import type { ProductDetail } from "@/lib/commerce/types";
+
+export function ProductCard({
+  detail,
+  priority = false,
+}: {
+  detail: ProductDetail;
+  priority?: boolean;
+}) {
+  const summary = summarizeProductAvailability(detail);
+  const image = detail.product.thumbnail ?? detail.product.images[0];
+  const variantLabel =
+    detail.variants.length === 1 ? "1 variant" : `${detail.variants.length} variants`;
+
+  const href = `/products/${detail.product.slug}`;
+
+  return (
+    <article>
+      {image ? (
+        <Link href={href} aria-label={`View ${detail.product.title}`}>
+          <Image
+            src={image.url}
+            alt={image.alt ?? detail.product.title}
+            width={900}
+            height={675}
+            priority={priority}
+          />
+        </Link>
+      ) : null}
+      <h2>
+        <Link href={href}>{detail.product.title}</Link>
+      </h2>
+      <p>{detail.product.description}</p>
+      <dl>
+        <dt>Status</dt>
+        <dd>{summary.available ? "Available" : summary.hasVariants ? "Sold out" : "Unavailable"}</dd>
+        <dt>Price</dt>
+        <dd>{summary.priceLabel}</dd>
+        <dt>Options</dt>
+        <dd>{variantLabel}</dd>
+      </dl>
+      <p>
+        <Link href={href}>Review product</Link>
+      </p>
+    </article>
+  );
+}

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>
+  );
+}