@01.software/init 0.9.2 → 0.10.1

package/dist/create-app-templates/ecommerce/lib/commerce/product-summary.ts

@@ -0,0 +1,37 @@
+import { formatMoney } from "../format.ts";
+import type { ProductDetail } from "./types.ts";
+
+export type ProductAvailabilitySummary = {
+  hasVariants: boolean;
+  available: boolean;
+  priceLabel: string;
+};
+
+export function summarizeProductAvailability(
+  detail: ProductDetail,
+): ProductAvailabilitySummary {
+  const prices = detail.variants.map((variant) => variant.price);
+  const available = detail.variants.some(
+    (variant) => variant.isUnlimited || variant.stock - variant.reservedStock > 0,
+  );
+
+  if (prices.length === 0) {
+    return {
+      hasVariants: false,
+      available: false,
+      priceLabel: "Unavailable",
+    };
+  }
+
+  const minPrice = Math.min(...prices);
+  const maxPrice = Math.max(...prices);
+
+  return {
+    hasVariants: true,
+    available,
+    priceLabel:
+      minPrice === maxPrice
+        ? formatMoney(minPrice)
+        : `${formatMoney(minPrice)} - ${formatMoney(maxPrice)}`,
+  };
+}

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

@@ -0,0 +1,60 @@
+import "../server-only-guard.ts";
+import { createMockCommerceProvider } from "./adapters/mock.ts";
+import {
+  createSoftwareCommerceProvider,
+  createSoftwareCustomerCartProvider,
+  createSoftwareCustomerCheckoutProvider,
+} from "./adapters/software.ts";
+import type { CartProvider, CommerceProvider } from "./provider.ts";
+import type { CheckoutCommerceProvider } from "../checkout/types.ts";
+
+export function getCommerceProvider(): CommerceProvider {
+  if (hasSoftwareCredentials(process.env)) {
+    return createSoftwareCommerceProvider();
+  }
+
+  return createMockCommerceProvider();
+}
+
+/**
+ * Resolve the cart provider for a logged-in customer: cart reads/writes go
+ * through a customer-JWT-scoped client so they operate the customer's own,
+ * device-portable cart.
+ *
+ * Gated on the same full software credentials as the guest provider (publishable
+ * **and** secret): `createSoftwareCustomerCartProvider` reuses
+ * `getSoftwareCommerceConfig`, which needs the secret key for the shipping policy
+ * even though the customer client itself uses only the publishable key + JWT. The
+ * supported software config sets both keys; in the unsupported half-config
+ * (publishable only) this degrades to the in-memory mock just like the guest
+ * provider, rather than throwing.
+ */
+export function getCustomerCartProvider(token: string): CartProvider {
+  if (hasSoftwareCredentials(process.env)) {
+    return createSoftwareCustomerCartProvider(token);
+  }
+
+  return createMockCommerceProvider();
+}
+
+/**
+ * Resolve checkout for a logged-in customer through the customer-JWT client
+ * (publishable key + JWT, no secret key) so Console checkout runs under the
+ * customer identity and enforces cart ownership.
+ */
+export function getCustomerCheckoutProvider(
+  token: string,
+): CheckoutCommerceProvider {
+  if (hasSoftwareCredentials(process.env)) {
+    return createSoftwareCustomerCheckoutProvider(token);
+  }
+
+  return createMockCommerceProvider();
+}
+
+function hasSoftwareCredentials(env: NodeJS.ProcessEnv): boolean {
+  return Boolean(
+    env.NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY?.trim() &&
+      env.SOFTWARE_SECRET_KEY?.trim(),
+  );
+}

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

@@ -0,0 +1,96 @@
+import type {
+  CartItemRef,
+  CartLine,
+  CartView,
+  CheckoutCartInput,
+  CreatePendingOrderResult,
+  Order,
+  ProductDetail,
+  ProductListResult,
+  ProductVariant,
+  ShippingPolicy,
+  StockCheckResult,
+} from "./types.ts";
+
+export type ConfirmOrderPaymentInput = {
+  paymentId: string;
+  /**
+   * Resolves the open checkout that placement promotes to a paid order. The
+   * Console resolves the checkout by `pgPaymentId` or by this `orderNumber`
+   * (→ `checkoutToken`); the synchronous return path always has it, the webhook
+   * backstop may not.
+   */
+  orderNumber?: string;
+  provider: string;
+  /** Provider-verified amount (server re-fetch), not a client-supplied value. */
+  amount: number;
+  providerEventId?: string;
+};
+
+export type PaymentStateInput = {
+  paymentId: string;
+  orderNumber?: string;
+  provider: string;
+  providerEventId?: string;
+};
+
+export type OrderLookupInput = {
+  paymentId: string;
+  provider: string;
+};
+
+/**
+ * The storefront commerce port. The cart is server-authoritative
+ * (`commerce.cart.*`): the browser never holds cart contents, only the
+ * unguessable `cartToken` in an HttpOnly cookie. Ordering goes through
+ * `orders.checkout({ cartId })`; the populated order is resolved by PG payment
+ * id (`getByPaymentId`) — there is no local order index.
+ */
+export type CommerceProvider = {
+  // Catalog
+  listProducts(input?: { limit?: number }): Promise<ProductListResult>;
+  getProductBySlug(slug: string): Promise<ProductDetail | null>;
+  getVariantsByIds(ids: string[]): Promise<ProductVariant[]>;
+  getShippingPolicy(): Promise<ShippingPolicy>;
+  checkStock(items: CartLine[]): Promise<StockCheckResult>;
+
+  // Server cart
+  createCart(): Promise<{ cartToken: string }>;
+  getCart(cartToken: string): Promise<CartView | null>;
+  addCartItem(input: { cartToken: string; item: CartItemRef }): Promise<CartView>;
+  updateCartItem(input: {
+    cartToken: string;
+    cartItemId: string;
+    quantity: number;
+  }): Promise<CartView>;
+  removeCartItem(input: {
+    cartToken: string;
+    cartItemId: string;
+  }): Promise<CartView>;
+  clearCart(input: { cartToken: string }): Promise<CartView>;
+
+  // Checkout + payment lifecycle
+  checkoutCart(input: CheckoutCartInput): Promise<CreatePendingOrderResult>;
+  getOrderByPaymentId(input: OrderLookupInput): Promise<Order | null>;
+  confirmOrderPayment(input: ConfirmOrderPaymentInput): Promise<Order>;
+  markPaymentFailed(input: PaymentStateInput): Promise<Order | null>;
+  cancelPendingOrder(input: PaymentStateInput): Promise<Order | null>;
+};
+
+/**
+ * The cart read/write subset of {@link CommerceProvider}. A logged-in customer
+ * operates the cart through a **customer-JWT-scoped** client (the JWT binds the
+ * customer; a publishable key alone cannot read/write a customer-bound cart), so
+ * `server-cart.ts` resolves one of these per request. Narrowing to the cart ops
+ * keeps the customer client — which cannot perform secret-key-only checkout /
+ * payment / collection-write operations — from being handed those calls.
+ */
+export type CartProvider = Pick<
+  CommerceProvider,
+  | "createCart"
+  | "getCart"
+  | "addCartItem"
+  | "updateCartItem"
+  | "removeCartItem"
+  | "clearCart"
+>;

package/dist/create-app-templates/ecommerce/lib/commerce/stock.ts

@@ -0,0 +1,37 @@
+import type { CartLine, ProductVariant, StockCheckResult } from "./types.ts";
+
+export function checkVariantStock(input: {
+  lines: CartLine[];
+  variants: ProductVariant[];
+}): StockCheckResult {
+  const variantById = new Map(input.variants.map((variant) => [variant.id, variant]));
+
+  const lines = input.lines.map((line) => {
+    const variant = variantById.get(line.variantId);
+    if (!variant) {
+      return {
+        ...line,
+        availableQuantity: 0,
+        ok: false,
+        reason: "variant_not_found" as const,
+      };
+    }
+
+    const availableQuantity = variant.isUnlimited
+      ? null
+      : Math.max(0, variant.stock - variant.reservedStock);
+    const ok = availableQuantity === null || availableQuantity >= line.quantity;
+
+    return {
+      ...line,
+      availableQuantity,
+      ok,
+      reason: ok ? undefined : ("insufficient_stock" as const),
+    };
+  });
+
+  return {
+    ok: lines.every((line) => line.ok),
+    lines,
+  };
+}

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

@@ -0,0 +1,208 @@
+export type CommerceImage = {
+  url: string
+  alt?: string
+  width?: number
+  height?: number
+}
+
+export type Product = {
+  id: string
+  slug: string
+  title: string
+  description?: string
+  thumbnail?: CommerceImage | null
+  images: CommerceImage[]
+  status: 'draft' | 'published' | 'archived'
+}
+
+export type ProductDetail = {
+  product: Product
+  variants: ProductVariant[]
+  options: ProductOption[]
+}
+
+export type ProductOption = {
+  id: string
+  slug: string
+  title: string
+  values: ProductOptionValue[]
+}
+
+export type ProductOptionValue = {
+  id: string
+  slug: string
+  value: string
+}
+
+export type ProductVariantOptionValue = {
+  optionId: string
+  valueId: string
+  valueSlug: string
+  value: string
+}
+
+export type ProductVariant = {
+  id: string
+  productId: string
+  title?: string
+  sku?: string
+  price: number
+  stock: number
+  reservedStock: number
+  isUnlimited: boolean
+  requiresShipping?: boolean | null
+  optionValues: ProductVariantOptionValue[]
+  images: CommerceImage[]
+}
+
+export type CartLine = {
+  variantId: string
+  quantity: number
+}
+
+/**
+ * Reference used to add a line to the server cart. The catalog identity
+ * (`product`/`variant`/`option`) is what `commerce.cart.addItem` expects — the
+ * cart, not the browser, owns price and stock.
+ */
+export type CartItemRef = {
+  productId: string
+  variantId: string
+  optionId?: string
+  quantity: number
+}
+
+/**
+ * A single line of the server cart, enriched with catalog display fields so the
+ * storefront can render it without a second round-trip. `cartItemId` is the
+ * handle used by update/remove.
+ */
+export type CartItemView = {
+  cartItemId: string
+  productId: string
+  variantId: string
+  quantity: number
+  unitAmount: number
+  lineAmount: number
+  requiresShipping?: boolean | null
+  productTitle: string
+  variantTitle?: string
+  image?: CommerceImage | null
+}
+
+/**
+ * The server cart projected for the storefront. `id` is the cart's DB id used
+ * by `orders.checkout({ cartId })`; the unguessable `cartToken` capability is
+ * never part of this view — it lives only in the HttpOnly cookie.
+ * `totalAmount` is the single payable quote (subtotal − discount + shipping,
+ * computed and stored by the Console cart).
+ */
+export type CartView = {
+  id: string
+  currency: string
+  subtotalAmount: number
+  shippingAmount: number
+  discountAmount: number
+  totalAmount: number
+  discountCode?: string
+  items: CartItemView[]
+}
+
+export type ShippingPolicy = {
+  currency: string
+  baseAmount: number
+  freeAboveAmount?: number
+}
+
+export type PricedOrderLine = CartLine & {
+  unitAmount: number
+  lineAmount: number
+  variant: ProductVariant
+}
+
+export type PricedOrder = {
+  currency: string
+  lines: PricedOrderLine[]
+  subtotalAmount: number
+  shippingAmount: number
+  totalAmount: number
+}
+
+export type StockCheckLine = CartLine & {
+  availableQuantity: number | null
+  ok: boolean
+  reason?: 'variant_not_found' | 'insufficient_stock'
+}
+
+export type StockCheckResult = {
+  ok: boolean
+  lines: StockCheckLine[]
+}
+
+export type CustomerSnapshot = {
+  name: string
+  email: string
+  phone: string
+}
+
+export type ShippingAddress = {
+  recipientName: string
+  phone: string
+  postalCode: string
+  address: string
+  detailAddress: string
+  deliveryMessage?: string
+}
+
+export type OrderItem = {
+  variantId: string
+  productTitle: string
+  variantTitle?: string
+  quantity: number
+  unitAmount: number
+  lineAmount: number
+}
+
+export type PaymentTransaction = {
+  paymentId: string
+  provider: string
+  status: 'pending' | 'paid' | 'failed' | 'canceled'
+  amount: number
+}
+
+export type Order = {
+  id: string
+  orderNumber: string
+  displayStatus: 'pending' | 'paid' | 'canceled'
+  items: OrderItem[]
+  customerSnapshot: CustomerSnapshot
+  shippingAddress?: ShippingAddress
+  subtotalAmount: number
+  shippingAmount: number
+  totalAmount: number
+  transactions: PaymentTransaction[]
+}
+
+export type ProductListResult = {
+  products: ProductDetail[]
+  total: number
+}
+
+/**
+ * Checkout input. The cart contents live server-side (addressed by `cartToken`
+ * from the HttpOnly cookie); the storefront supplies only the buyer + shipping
+ * snapshot. No client-supplied lines or totals — the cart is the quote.
+ */
+export type CheckoutCartInput = {
+  cartToken: string
+  customerSnapshot: CustomerSnapshot
+  shippingAddress?: ShippingAddress
+}
+
+export type CreatePendingOrderResult = {
+  order: Order
+  paymentId: string
+  paymentName: string
+  amount: number
+  currency: string
+}

package/dist/create-app-templates/ecommerce/lib/commerce/variant-selection.ts

@@ -0,0 +1,23 @@
+import type { ProductDetail, ProductVariant } from "./types.ts";
+
+export function resolveVariantFromSelection(
+  detail: ProductDetail,
+  selectedValueIdsByOptionId: Record<string, string | undefined>,
+): ProductVariant | null {
+  const requiredOptionIds = detail.options.map((option) => option.id);
+  if (requiredOptionIds.some((optionId) => !selectedValueIdsByOptionId[optionId])) {
+    return null;
+  }
+
+  return (
+    detail.variants.find((variant) =>
+      requiredOptionIds.every((optionId) =>
+        variant.optionValues.some(
+          (value) =>
+            value.optionId === optionId &&
+            value.valueId === selectedValueIdsByOptionId[optionId],
+        ),
+      ),
+    ) ?? null
+  );
+}

package/dist/create-app-templates/ecommerce/lib/customer/auth-actions.ts

@@ -0,0 +1,131 @@
+import "../server-only-guard.ts";
+import type { CustomerAuthClient } from "./client.server.ts";
+import { createCustomerClient } from "./client.server.ts";
+
+/**
+ * Customer auth core logic, isolated from `next/headers` and the SDK transport so
+ * it unit-tests with a fake client. Route handlers call these and then apply the
+ * returned cookie effect; render paths use {@link loadCustomer} read-only.
+ */
+
+export interface CustomerSummary {
+  id: string;
+  name: string;
+  email?: string | null;
+}
+
+export interface LoginInput {
+  email: string;
+  password: string;
+}
+
+export interface RegisterInput {
+  name: string;
+  email: string;
+  password: string;
+  phone?: string;
+}
+
+/** Result of a login/register attempt the route handler turns into a response. */
+export type AuthResult =
+  | { ok: true; token: string | null; customer: CustomerSummary | null }
+  | { ok: false; status: number; message: string };
+
+/** A client factory so tests can inject a fake SDK client. */
+export type CustomerClientFactory = (
+  token: string | null,
+) => Promise<CustomerAuthClient | null>;
+
+const UNCONFIGURED: AuthResult = {
+  ok: false,
+  status: 503,
+  message: "Customer accounts are not configured for this storefront.",
+};
+
+function toSummary(customer: unknown): CustomerSummary | null {
+  if (!customer || typeof customer !== "object") return null;
+  const c = customer as Record<string, unknown>;
+  if (typeof c.id !== "string" || typeof c.name !== "string") return null;
+  return {
+    id: c.id,
+    name: c.name,
+    email: typeof c.email === "string" ? c.email : null,
+  };
+}
+
+function statusOf(error: unknown): number {
+  const status = (error as { status?: unknown })?.status;
+  return typeof status === "number" ? status : 502;
+}
+
+function messageOf(error: unknown, fallback: string): string {
+  if (error instanceof Error && error.message) return error.message;
+  return fallback;
+}
+
+/** Log in and return the JWT for the route to persist in the session cookie. */
+export async function login(
+  input: LoginInput,
+  factory: CustomerClientFactory = (token) => createCustomerClient(token),
+): Promise<AuthResult> {
+  const client = await factory(null);
+  if (!client) return UNCONFIGURED;
+  try {
+    const { token, customer } = await client.customer.auth.login(input);
+    return { ok: true, token, customer: toSummary(customer) };
+  } catch (error) {
+    return {
+      ok: false,
+      status: statusOf(error),
+      message: messageOf(error, "Login failed"),
+    };
+  }
+}
+
+/**
+ * Register an account. The register endpoint returns the customer (no token), so
+ * the caller logs in afterward to mint the session; we surface only the customer
+ * here and let the route chain the login.
+ */
+export async function register(
+  input: RegisterInput,
+  factory: CustomerClientFactory = (token) => createCustomerClient(token),
+): Promise<AuthResult> {
+  const client = await factory(null);
+  if (!client) return UNCONFIGURED;
+  try {
+    const { customer } = await client.customer.auth.register(input);
+    return { ok: true, token: null, customer: toSummary(customer) };
+  } catch (error) {
+    return {
+      ok: false,
+      status: statusOf(error),
+      message: messageOf(error, "Registration failed"),
+    };
+  }
+}
+
+/**
+ * Resolve the current customer from a session token, for render paths. Returns
+ * `null` (guest) when there is no token, auth is unconfigured, the token is
+ * expired/invalid (the SDK's `me()` returns `null` on a 401), **or** the backend
+ * call fails — a render path must degrade to guest, never throw. We never
+ * refresh here: there is no infinite loop against a cookie a render path cannot
+ * rewrite. The stale (HttpOnly, harmless) cookie is overwritten on the next
+ * login or dropped on logout.
+ */
+export async function loadCustomer(
+  token: string | null,
+  factory: CustomerClientFactory = (t) => createCustomerClient(t),
+): Promise<CustomerSummary | null> {
+  if (!token) return null;
+  try {
+    const client = await factory(token);
+    if (!client) return null;
+    return toSummary(await client.customer.auth.me());
+  } catch {
+    // 5xx / timeout / network error — fall back to guest rather than crash the
+    // page. `me()` already maps 401 to `null` without throwing.
+    return null;
+  }
+}

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

@@ -0,0 +1,44 @@
+/**
+ * Login cart-sync core, isolated from `next/headers` and the SDK transport so it
+ * unit-tests with a fake commerce client. The route wrapper
+ * (`lib/cart/sync-on-login.server.ts`) reads the guest cart cookie, builds a
+ * customer-JWT commerce client, calls this, and applies the cookie effect.
+ */
+
+/** The merge/mine surface the login cart-sync consumes (customer-JWT scoped). */
+export interface CartSyncCommerce {
+  cart: {
+    merge(params: {
+      guestCartToken: string;
+    }): Promise<{ cartToken: string | null }>;
+    mine(): Promise<{ cartToken: string | null }>;
+  };
+}
+
+export interface CartSyncResult {
+  /** The resolved customer cart token to persist, or `null` to clear the cookie. */
+  cartToken: string | null;
+}
+
+/**
+ * After login, resolve the customer's active-cart token. If a pre-login guest
+ * cart exists, union/claim it into the customer cart (`merge`); otherwise load
+ * the existing customer cart (`mine`). The returned token is what the caller
+ * persists in the cart cookie (or clears the cookie when `null`).
+ *
+ * `merge` returns the resolved customer cart's token on **both** the `claimed`
+ * (guest cart taken over) and `merged` (lines unioned into an existing customer
+ * cart) branches, so the guest cookie always ends up pointing at the customer
+ * cart — never the abandoned guest cart.
+ */
+export async function resolveCustomerCartToken(
+  commerce: CartSyncCommerce,
+  guestCartToken: string | null,
+): Promise<CartSyncResult> {
+  if (guestCartToken) {
+    const { cartToken } = await commerce.cart.merge({ guestCartToken });
+    return { cartToken };
+  }
+  const { cartToken } = await commerce.cart.mine();
+  return { cartToken };
+}