@01.software/init 0.10.0 → 0.10.1

package/dist/create-app-templates/ecommerce/CHANGELOG.md

@@ -1,5 +1,23 @@
 # ecommerce
 
+## 0.1.2
+
+### Patch Changes
+
+- Updated dependencies [81ef105]
+- Updated dependencies [9789528]
+- Updated dependencies [9b7afab]
+- Updated dependencies [db8bd4b]
+- Updated dependencies [b95f6ac]
+- Updated dependencies [c60ec7f]
+- Updated dependencies [6c71a71]
+- Updated dependencies [3aa6239]
+- Updated dependencies [5d7b26f]
+- Updated dependencies [294b7d1]
+- Updated dependencies [f87fe09]
+- Updated dependencies [4362b14]
+  - @01.software/sdk@0.43.0
+
 ## 0.1.1
 
 ### Patch Changes

package/dist/create-app-templates/ecommerce/README.md

@@ -21,7 +21,13 @@ provider for a generated app is recorded in `app-config.ts` and its keys live in
     TossPayments payment REST API on the server.
 - A theming seam: a CSS-variable token layer in `app/globals.css` plus Tailwind.
 - Server-side order pricing, stock checks, and payment sync invariants.
-- Local persisted cart state with Zustand.
+- Server-authoritative cart operations through the template's own route handlers,
+  backed by `commerce.cart.*`.
+- An HttpOnly cart cookie containing only the unguessable `cartToken`; client
+  JavaScript receives rendered cart views but never owns the authoritative cart
+  or token, and no cart contents are persisted in localStorage.
+- Checkout through `orders.checkout({ cartId })`, with orders resolved after
+  payment by `orders.getByPaymentId`.
 
 ## Scaffolding vs. this in-repo source
 
@@ -44,13 +50,13 @@ pnpm dev
 Without SDK or payment credentials, the app uses demo providers:
 
 ```bash
-# 01.software keys omitted -> demo catalog
+# 01.software keys omitted -> demo catalog plus in-memory cart/checkout
 # payment keys omitted -> local demo payment completion
 ```
 
-Mock orders are persisted to `.mock-orders.json` so redirect and success routes
-can observe the same order during local development. This file is ignored and is
-not a production store.
+The mock adapter emulates the server cart and checkout flow in memory for
+zero-backend demos. Redirect and success routes resolve the same in-process
+checkout model without writing a local order index.
 
 To use the Console ecommerce SDK adapter, set both SDK keys:
 
@@ -63,10 +69,11 @@ SOFTWARE_FREE_SHIPPING_ABOVE_AMOUNT=100000
 ```
 
 `SOFTWARE_API_URL`, `SOFTWARE_SHIPPING_AMOUNT`, and
-`SOFTWARE_FREE_SHIPPING_ABOVE_AMOUNT` are optional. The SDK adapter resolves
-payment return/webhook requests through the SDK `transactions` collection first,
-then falls back to a local `.software-orders.json` development index. This file
-is ignored and is not a production store.
+`SOFTWARE_FREE_SHIPPING_ABOVE_AMOUNT` are optional. The SDK adapter uses Console
+cart and order APIs for the full server-authoritative flow: route handlers call
+`commerce.cart.*`, checkout calls `orders.checkout({ cartId })`, and
+return/webhook/success reconciliation resolves orders by payment id through
+`orders.getByPaymentId`.
 
 ## Payment provider keys
 
@@ -96,9 +103,12 @@ NEXT_PUBLIC_TOSSPAYMENTS_CUSTOMER_KEY=customer_...
 
 `NEXT_PUBLIC_TOSSPAYMENTS_CUSTOMER_KEY` is optional. If omitted, the browser SDK
 uses TossPayments' anonymous customer key. TossPayments redirects back with
-`paymentKey`, `orderId`, and `amount`; the template validates the returned
-amount against the stored order and confirms the payment on
-`/api/checkout/payment-return` before showing the success page.
+`paymentKey`, `orderId`, and `amount`; `/api/checkout/payment-return` re-fetches
+the provider payment, rejects a tampered redirect amount, captures with the
+PG-verified amount, then redirects to the success page. Success-page
+reconciliation re-fetches the provider payment again and places the Console
+checkout through `orders.confirmPayment`, where the open checkout quote remains
+the authoritative amount check.
 `TOSSPAYMENTS_API_BASE_URL` is optional and defaults to
 `https://api.tosspayments.com/v1`.
 
@@ -133,7 +143,12 @@ pnpm build
 
 ## Important boundary
 
-The cart stores only `variantId` and `quantity`. Checkout sends those lines plus
-customer and shipping details to the server; server code re-fetches variants,
-checks stock, recomputes subtotal/shipping/total, creates a pending order, and
-then synchronizes payment state.
+The browser never owns the authoritative cart or cart capability tokens. It
+talks to the template's cart route handlers, which keep the cart
+server-authoritative and store only an HttpOnly cart cookie in the browser.
+Client components may keep rendered cart views in memory, but cart mutations and
+checkout always return to the server cart. Checkout attaches customer and
+shipping details to that server cart, converts it with
+`orders.checkout({ cartId })`, and then synchronizes payment state. After
+payment, order lookup uses `orders.getByPaymentId`, so the template does not
+need a file-backed order index.

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

@@ -1,22 +1,25 @@
-"use client";
+'use client'
 
-import Image from "next/image";
-import Link from "next/link";
-import { useCart } from "@/lib/cart/use-cart";
-import { formatMoney } from "@/lib/format";
+import Image from 'next/image'
+import Link from 'next/link'
+import { useCart } from '@/lib/cart/use-cart'
+import { formatMoney } from '@/lib/format'
 
 export function CartContent() {
-  const { cart, loading, updateItem, removeItem } = useCart();
+  const { cart, loading, updateItem, removeItem } = useCart()
 
   if (loading && !cart) {
     return (
       <section>
         <h1>Loading your cart…</h1>
       </section>
-    );
+    )
   }
 
-  const items = cart?.items ?? [];
+  const items = cart?.items ?? []
+  const hasShippableItems = items.some(
+    (item) => item.requiresShipping !== false,
+  )
 
   if (items.length === 0) {
     return (
@@ -25,7 +28,7 @@ export function CartContent() {
         <p>Add products before starting a payment check.</p>
         <Link href="/products">Browse products</Link>
       </section>
-    );
+    )
   }
 
   return (
@@ -104,16 +107,23 @@ export function CartContent() {
           <dd>
             <output>{formatMoney(cart?.subtotalAmount ?? 0)}</output>
           </dd>
-          <dt>Shipping</dt>
-          <dd>{formatMoney(cart?.shippingAmount ?? 0)}</dd>
+          {hasShippableItems ? (
+            <>
+              <dt>Shipping</dt>
+              <dd>{formatMoney(cart?.shippingAmount ?? 0)}</dd>
+            </>
+          ) : null}
           <dt>Total</dt>
           <dd>
             <output>{formatMoney(cart?.totalAmount ?? 0)}</output>
           </dd>
         </dl>
-        <p>Totals are computed by the server cart and confirmed again at checkout.</p>
+        <p>
+          Totals are computed by the server cart and confirmed again at
+          checkout.
+        </p>
         <Link href="/checkout">Checkout</Link>
       </aside>
     </div>
-  );
+  )
 }

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

@@ -1,91 +1,99 @@
-"use client";
+'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";
+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;
-};
+  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();
+  const router = useRouter()
+  const { cart, loading, reset } = useCart()
+  const [error, setError] = useState<string | null>(null)
+  const [submitting, setSubmitting] = useState(false)
+  const providerLabel = paymentProviderLabel()
+  const hasShippableItems = !cart
+    ? true
+    : cart.items.some((item) => item.requiresShipping !== false)
 
   async function submit(formData: FormData) {
-    setSubmitting(true);
-    setError(null);
+    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"),
-    };
+      name: value(formData, 'customerName'),
+      email: value(formData, 'email'),
+      phone: value(formData, 'phone'),
+    }
+    const shippingAddress: ShippingAddress | undefined = hasShippableItems
+      ? {
+          recipientName: value(formData, 'recipientName'),
+          phone: value(formData, 'shippingPhone'),
+          postalCode: value(formData, 'postalCode'),
+          address: value(formData, 'address'),
+          detailAddress: value(formData, 'detailAddress'),
+          deliveryMessage: value(formData, 'deliveryMessage'),
+        }
+      : undefined
 
-    const response = await fetch("/api/checkout", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ customerSnapshot, shippingAddress }),
-    });
+    const response = await fetch('/api/checkout', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        customerSnapshot,
+        ...(shippingAddress ? { 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 { message?: string }
+      setError(payload.message ?? 'Checkout failed')
+      setSubmitting(false)
+      return
     }
 
-    const payload = (await response.json()) as CheckoutResponse;
+    const payload = (await response.json()) as CheckoutResponse
     // scaffold:provider:portone:start
-    if (payload.clientPayment?.provider === "portone") {
+    if (payload.clientPayment?.provider === 'portone') {
       try {
-        await requestPortOnePayment(payload.clientPayment);
-        reset();
+        await requestPortOnePayment(payload.clientPayment)
+        reset()
       } catch (error) {
-        setError(error instanceof Error ? error.message : "Payment failed");
-        setSubmitting(false);
+        setError(error instanceof Error ? error.message : 'Payment failed')
+        setSubmitting(false)
       }
-      return;
+      return
     }
     // scaffold:provider:portone:end
     // scaffold:provider:tosspayments:start
-    if (payload.clientPayment?.provider === "tosspayments") {
+    if (payload.clientPayment?.provider === 'tosspayments') {
       try {
-        await requestTossPayments(payload.clientPayment);
-        reset();
+        await requestTossPayments(payload.clientPayment)
+        reset()
       } catch (error) {
-        setError(error instanceof Error ? error.message : "Payment failed");
-        setSubmitting(false);
+        setError(error instanceof Error ? error.message : 'Payment failed')
+        setSubmitting(false)
       }
-      return;
+      return
     }
     // scaffold:provider:tosspayments:end
 
-    reset();
+    reset()
     router.push(
       payload.redirectUrl ??
         `/checkout/success?paymentId=${encodeURIComponent(payload.paymentId)}&orderNumber=${encodeURIComponent(payload.orderNumber)}`,
-    );
+    )
   }
 
   if (!loading && (!cart || cart.items.length === 0)) {
@@ -95,7 +103,7 @@ export function CheckoutForm() {
         <p>Add at least one item before checkout.</p>
         <Link href="/products">Browse products</Link>
       </section>
-    );
+    )
   }
 
   return (
@@ -103,31 +111,57 @@ export function CheckoutForm() {
       <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.
+          Customer details are collected before payment handoff.
         </p>
 
         <fieldset>
           <legend>Customer</legend>
-          <Field name="customerName" label="Customer name" autoComplete="name" />
+          <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>
+        {hasShippableItems ? (
+          <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>
+        ) : null}
       </section>
 
       <aside>
         <h2>Payment handoff</h2>
         <p>
-          Local demo payments complete immediately. Configured {providerLabel}{" "}
+          Local demo payments complete immediately. Configured {providerLabel}{' '}
           credentials start the provider handoff after the order is created.
         </p>
         <dl>
@@ -146,20 +180,27 @@ export function CheckoutForm() {
         </dl>
         {error ? <p role="alert">{error}</p> : null}
         <button type="submit" disabled={submitting}>
-          {submitting ? "Creating order..." : "Start payment"}
+          {submitting ? 'Creating order...' : 'Start payment'}
         </button>
-        <p aria-live="polite">{submitting ? "Creating order and payment request." : null}</p>
+        <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);
+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,
@@ -180,43 +221,42 @@ async function requestPortOnePayment(payment: Extract<ClientPaymentRequest, { pr
     // 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]);
+  } as Parameters<typeof PortOne.requestPayment>[0])
 
   if (result?.code) {
-    throw new Error(result.message ?? result.code);
+    throw new Error(result.message ?? result.code)
   }
 
   if (result?.paymentId) {
-    window.location.assign(redirectUrl.toString());
+    window.location.assign(redirectUrl.toString())
   }
 }
 // scaffold:provider:portone:end
 
 // scaffold:provider:tosspayments:start
 async function requestTossPayments(
-  payment: Extract<ClientPaymentRequest, { provider: "tosspayments" }>,
+  payment: Extract<ClientPaymentRequest, { provider: 'tosspayments' }>,
 ) {
-  const { ANONYMOUS, loadTossPayments } = await import(
-    "@tosspayments/tosspayments-sdk"
-  );
-  const tossPayments = await loadTossPayments(payment.clientKey);
+  const { ANONYMOUS, loadTossPayments } =
+    await import('@tosspayments/tosspayments-sdk')
+  const tossPayments = await loadTossPayments(payment.clientKey)
   const checkoutReturnUrl = new URL(
-    "/api/checkout/payment-return",
+    '/api/checkout/payment-return',
     window.location.origin,
-  );
-  checkoutReturnUrl.searchParams.set("paymentId", payment.paymentId);
-  checkoutReturnUrl.searchParams.set("orderNumber", payment.orderNumber);
+  )
+  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 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",
+    method: 'CARD',
     amount: {
       currency: payment.currency,
       value: payment.amount,
@@ -232,22 +272,22 @@ async function requestTossPayments(
     // 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",
+  type = 'text',
   autoComplete,
   required = true,
 }: {
-  label: string;
-  name: string;
-  type?: string;
-  autoComplete?: string;
-  required?: boolean;
+  label: string
+  name: string
+  type?: string
+  autoComplete?: string
+  required?: boolean
 }) {
   return (
     <label>
@@ -259,9 +299,9 @@ function Field({
         required={required}
       />
     </label>
-  );
+  )
 }
 
 function value(formData: FormData, key: string): string {
-  return String(formData.get(key) ?? "").trim();
+  return String(formData.get(key) ?? '').trim()
 }

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

@@ -1,5 +1,10 @@
 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";
 
@@ -40,16 +45,25 @@ 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))) {
-    token = null;
+    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. (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.)
+    // customer client, so create() is customer-bound.
     const created = await provider.createCart();
     token = created.cartToken;
     await writeCartToken(token);
@@ -94,3 +108,28 @@ async function requireCartToken(): Promise<string> {
   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