@01.software/init 0.9.2 → 0.10.1

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

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

@@ -0,0 +1,28 @@
+import "../server-only-guard.ts";
+import {
+  getCommerceProvider,
+  getCustomerCheckoutProvider,
+} from "../commerce/provider.server.ts";
+import { getSessionToken } from "../customer/session.ts";
+import type { CheckoutCommerceProvider } from "./types.ts";
+
+export type CheckoutProviderFactories = {
+  guest: () => CheckoutCommerceProvider;
+  customer: (token: string) => CheckoutCommerceProvider;
+};
+
+export function resolveCheckoutCommerceProvider(
+  sessionToken: string | null,
+  factories: CheckoutProviderFactories,
+): CheckoutCommerceProvider {
+  return sessionToken
+    ? factories.customer(sessionToken)
+    : factories.guest();
+}
+
+export async function getCheckoutCommerceProvider(): Promise<CheckoutCommerceProvider> {
+  return resolveCheckoutCommerceProvider(await getSessionToken(), {
+    guest: getCommerceProvider,
+    customer: getCustomerCheckoutProvider,
+  });
+}

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

@@ -0,0 +1,86 @@
+import type { CustomerSnapshot, ShippingAddress } from '../commerce/types.ts'
+
+const MAX_TEXT_LENGTH = 160
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+
+/**
+ * Checkout collects only the buyer + shipping snapshot. The cart contents live
+ * server-side (addressed by the HttpOnly `cartToken`); there are no
+ * client-supplied lines or totals — the cart is the quote.
+ */
+export type CheckoutPayload = {
+  customerSnapshot: CustomerSnapshot
+  shippingAddress?: ShippingAddress
+}
+
+export function parseCheckoutPayload(
+  input: unknown,
+  options: { requiresShipping?: boolean } = {},
+): CheckoutPayload {
+  if (!input || typeof input !== 'object') {
+    throw new Error('Checkout payload must be an object')
+  }
+
+  const body = input as {
+    customerSnapshot?: unknown
+    shippingAddress?: unknown
+  }
+  const customer = parseRecord(body.customerSnapshot, 'customerSnapshot')
+  const email = requiredString(customer.email, 'email')
+  if (!EMAIL_RE.test(email)) {
+    throw new Error('email must be a valid email address')
+  }
+
+  const customerSnapshot = {
+    name: requiredString(customer.name, 'customer name'),
+    email,
+    phone: requiredString(customer.phone, 'customer phone'),
+  }
+
+  if (options.requiresShipping === false) {
+    return { customerSnapshot }
+  }
+
+  const shipping = parseRecord(body.shippingAddress, 'shippingAddress')
+
+  return {
+    customerSnapshot,
+    shippingAddress: {
+      recipientName: requiredString(shipping.recipientName, 'recipient name'),
+      phone: requiredString(shipping.phone, 'shipping phone'),
+      postalCode: requiredString(shipping.postalCode, 'postal code'),
+      address: requiredString(shipping.address, 'address'),
+      detailAddress: requiredString(shipping.detailAddress, 'address detail'),
+      deliveryMessage: optionalString(
+        shipping.deliveryMessage,
+        'shipping message',
+      ),
+    },
+  }
+}
+
+function parseRecord(input: unknown, field: string): Record<string, unknown> {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw new Error(`${field} must be an object`)
+  }
+
+  return input as Record<string, unknown>
+}
+
+function requiredString(input: unknown, field: string): string {
+  const value = optionalString(input, field)
+  if (!value) throw new Error(`${field} is required`)
+  return value
+}
+
+function optionalString(input: unknown, field: string): string {
+  if (input === undefined || input === null) return ''
+  if (typeof input !== 'string') throw new Error(`${field} must be a string`)
+
+  const value = input.trim()
+  if (value.length > MAX_TEXT_LENGTH) {
+    throw new Error(`${field} must be ${MAX_TEXT_LENGTH} characters or fewer`)
+  }
+
+  return value
+}

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

@@ -0,0 +1,73 @@
+import '../server-only-guard.ts'
+import type { CheckoutCommerceProvider } from './types.ts'
+import type { ClientPaymentRequest } from '../payment/types.ts'
+import type { PaymentProvider } from '../payment/provider.ts'
+import {
+  parseCheckoutPayload,
+  type CheckoutPayload,
+} from './parse-checkout-payload.ts'
+
+export type StartCheckoutResult = {
+  orderNumber: string
+  paymentId: string
+  paymentName: string
+  amount: number
+  currency: string
+  redirectUrl?: string
+  clientPayment?: ClientPaymentRequest
+}
+
+/**
+ * Convert the server cart (addressed by `cartToken`) into an order via
+ * `orders.checkout({ cartId })` and open the PG payment window. The cart is the
+ * single payable quote — no client-supplied lines or totals.
+ */
+export async function startCheckout(input: {
+  cartToken: string
+  payload: unknown
+  commerceProvider: CheckoutCommerceProvider
+  paymentProvider: PaymentProvider
+}): Promise<StartCheckoutResult> {
+  const cart = await input.commerceProvider.getCart(input.cartToken)
+  if (!cart) throw new Error('Cart not found')
+
+  const requiresShipping = cart.items.some(
+    (item) => item.requiresShipping !== false,
+  )
+  const payload: CheckoutPayload = parseCheckoutPayload(input.payload, {
+    requiresShipping,
+  })
+  const pending = await input.commerceProvider.checkoutCart({
+    cartToken: input.cartToken,
+    customerSnapshot: payload.customerSnapshot,
+    ...(payload.shippingAddress
+      ? { shippingAddress: payload.shippingAddress }
+      : {}),
+  })
+
+  const payment = await input.paymentProvider.requestPayment({
+    paymentId: pending.paymentId,
+    orderNumber: pending.order.orderNumber,
+    orderName: pending.paymentName,
+    amount: pending.amount,
+    currency: pending.currency,
+    customer: pending.order.customerSnapshot,
+  })
+
+  if (!payment.ok) {
+    // Checkout created an OPEN Checkout but no Order/Transaction yet. A failed
+    // PG handoff leaves nothing durable to cancel; the abandoned Checkout (and
+    // its inventory hold) is released by the Console `expire-checkouts` cron.
+    throw new Error(payment.reason ?? 'payment_request_failed')
+  }
+
+  return {
+    orderNumber: pending.order.orderNumber,
+    paymentId: pending.paymentId,
+    paymentName: pending.paymentName,
+    amount: pending.amount,
+    currency: pending.currency,
+    redirectUrl: payment.redirectUrl,
+    clientPayment: payment.clientPayment,
+  }
+}

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

@@ -0,0 +1,6 @@
+import type { CommerceProvider } from '../commerce/provider.ts'
+
+export type CheckoutCommerceProvider = Pick<
+  CommerceProvider,
+  'checkoutCart' | 'getCart'
+>