@01.software/init 0.9.1 → 0.10.0

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,76 @@
+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): 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 shipping = parseRecord(body.shippingAddress, "shippingAddress");
+  const email = requiredString(customer.email, "email");
+  if (!EMAIL_RE.test(email)) {
+    throw new Error("email must be a valid email address");
+  }
+
+  return {
+    customerSnapshot: {
+      name: requiredString(customer.name, "customer name"),
+      email,
+      phone: requiredString(customer.phone, "customer phone"),
+    },
+    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,63 @@
+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 payload: CheckoutPayload = parseCheckoutPayload(input.payload)
+  const pending = await input.commerceProvider.checkoutCart({
+    cartToken: input.cartToken,
+    customerSnapshot: payload.customerSnapshot,
+    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,3 @@
+import type { CommerceProvider } from "../commerce/provider.ts";
+
+export type CheckoutCommerceProvider = Pick<CommerceProvider, "checkoutCart">;

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

@@ -0,0 +1,336 @@
+import seed from "../../../data/mock-catalog.json" with { type: "json" };
+import { normalizeCartLines } from "../../cart/normalize.ts";
+import type { CommerceProvider } from "../provider.ts";
+import { checkVariantStock } from "../stock.ts";
+import type {
+  CartItemView,
+  CartView,
+  CheckoutCartInput,
+  CreatePendingOrderResult,
+  Order,
+  ProductDetail,
+  ProductVariant,
+  ShippingPolicy,
+} from "../types.ts";
+
+/**
+ * In-memory server-cart emulation for the zero-backend demo. The mock stands in
+ * for the Console `commerce.cart.*` + `orders.checkout` surface so the template
+ * runs without credentials. Carts and orders live in module-level maps for the
+ * lifetime of the dev server process — there is no file-based index.
+ */
+type MockCartItem = {
+  cartItemId: string;
+  productId: string;
+  variantId: string;
+  optionId?: string;
+  quantity: number;
+  unitPrice: number;
+};
+
+type MockCart = {
+  id: string;
+  cartToken: string;
+  currency: string;
+  items: MockCartItem[];
+};
+
+const carts = new Map<string, MockCart>();
+const orders = new Map<string, Order>();
+
+export function createMockCommerceProvider(): CommerceProvider {
+  const products = seed.products as ProductDetail[];
+  const shippingPolicy = seed.shippingPolicy as ShippingPolicy;
+  const variants = allVariants(products);
+  const variantById = new Map(variants.map((variant) => [variant.id, variant]));
+
+  function viewCart(cart: MockCart): CartView {
+    const items: CartItemView[] = cart.items.map((item) => {
+      const variant = variantById.get(item.variantId);
+      const detail = products.find(
+        (entry) => entry.product.id === item.productId,
+      );
+      const image =
+        variant?.images[0] ??
+        detail?.product.thumbnail ??
+        detail?.product.images[0] ??
+        null;
+      return {
+        cartItemId: item.cartItemId,
+        productId: item.productId,
+        variantId: item.variantId,
+        quantity: item.quantity,
+        unitAmount: item.unitPrice,
+        lineAmount: item.unitPrice * item.quantity,
+        productTitle: detail?.product.title ?? "Unknown product",
+        variantTitle: variant?.title,
+        image,
+      };
+    });
+
+    const subtotalAmount = items.reduce((sum, item) => sum + item.lineAmount, 0);
+    const shippingAmount =
+      shippingPolicy.freeAboveAmount !== undefined &&
+      subtotalAmount >= shippingPolicy.freeAboveAmount
+        ? 0
+        : subtotalAmount > 0
+          ? shippingPolicy.baseAmount
+          : 0;
+
+    return {
+      id: cart.id,
+      currency: shippingPolicy.currency,
+      subtotalAmount,
+      shippingAmount,
+      discountAmount: 0,
+      totalAmount: subtotalAmount + shippingAmount,
+      items,
+    };
+  }
+
+  function requireCart(cartToken: string): MockCart {
+    const cart = carts.get(cartToken);
+    if (!cart) throw new Error("Cart not found");
+    return cart;
+  }
+
+  return {
+    async listProducts(input) {
+      const limit = input?.limit ?? 24;
+      const publishedProducts = products.filter(
+        (entry) => entry.product.status === "published",
+      );
+      return {
+        products: publishedProducts.slice(0, limit),
+        total: publishedProducts.length,
+      };
+    },
+
+    async getProductBySlug(slug) {
+      return (
+        products.find(
+          (entry) =>
+            entry.product.slug === slug &&
+            entry.product.status === "published",
+        ) ?? null
+      );
+    },
+
+    async getVariantsByIds(ids) {
+      const idSet = new Set(ids);
+      return variants.filter((variant) => idSet.has(variant.id));
+    },
+
+    async getShippingPolicy() {
+      return shippingPolicy;
+    },
+
+    async checkStock(items) {
+      return checkVariantStock({
+        lines: normalizeCartLines(items),
+        variants,
+      });
+    },
+
+    async createCart() {
+      const cartToken = `mock_cart_${crypto.randomUUID()}`;
+      carts.set(cartToken, {
+        id: `cart_${crypto.randomUUID()}`,
+        cartToken,
+        currency: shippingPolicy.currency,
+        items: [],
+      });
+      return { cartToken };
+    },
+
+    async getCart(cartToken) {
+      const cart = carts.get(cartToken);
+      return cart ? viewCart(cart) : null;
+    },
+
+    async addCartItem({ cartToken, item }) {
+      const cart = requireCart(cartToken);
+      const variant = variantById.get(item.variantId);
+      if (!variant) throw new Error("Variant not found");
+
+      const existing = cart.items.find(
+        (line) => line.variantId === item.variantId,
+      );
+      const nextQuantity = (existing?.quantity ?? 0) + item.quantity;
+      const stock = checkVariantStock({
+        lines: [{ variantId: item.variantId, quantity: nextQuantity }],
+        variants,
+      });
+      if (!stock.ok) throw new Error("Insufficient stock");
+
+      if (existing) {
+        existing.quantity = Math.min(99, nextQuantity);
+      } else {
+        cart.items.push({
+          cartItemId: `item_${crypto.randomUUID()}`,
+          productId: item.productId || variant.productId,
+          variantId: item.variantId,
+          optionId: item.optionId,
+          quantity: Math.min(99, item.quantity),
+          unitPrice: variant.price,
+        });
+      }
+      return viewCart(cart);
+    },
+
+    async updateCartItem({ cartToken, cartItemId, quantity }) {
+      const cart = requireCart(cartToken);
+      const line = cart.items.find((entry) => entry.cartItemId === cartItemId);
+      if (!line) throw new Error("Cart item not found");
+      if (quantity <= 0) {
+        cart.items = cart.items.filter(
+          (entry) => entry.cartItemId !== cartItemId,
+        );
+      } else {
+        line.quantity = Math.min(99, Math.floor(quantity));
+      }
+      return viewCart(cart);
+    },
+
+    async removeCartItem({ cartToken, cartItemId }) {
+      const cart = requireCart(cartToken);
+      cart.items = cart.items.filter((entry) => entry.cartItemId !== cartItemId);
+      return viewCart(cart);
+    },
+
+    async clearCart({ cartToken }) {
+      const cart = requireCart(cartToken);
+      cart.items = [];
+      return viewCart(cart);
+    },
+
+    async checkoutCart(input) {
+      return checkoutMockCart({ input, products, viewCart, requireCart });
+    },
+
+    async getOrderByPaymentId({ paymentId }) {
+      return orders.get(paymentId) ?? null;
+    },
+
+    async confirmOrderPayment(input) {
+      const order = orders.get(input.paymentId);
+      if (!order) throw new Error("Order not found");
+      const paidOrder: Order = {
+        ...order,
+        displayStatus: "paid",
+        transactions: order.transactions.map((transaction) =>
+          transaction.paymentId === input.paymentId
+            ? { ...transaction, provider: input.provider, status: "paid" }
+            : transaction,
+        ),
+      };
+      orders.set(input.paymentId, paidOrder);
+      return paidOrder;
+    },
+
+    async markPaymentFailed(input) {
+      const order = orders.get(input.paymentId);
+      if (!order) return null;
+      const failedOrder: Order = {
+        ...order,
+        transactions: order.transactions.map((transaction) =>
+          transaction.paymentId === input.paymentId
+            ? { ...transaction, provider: input.provider, status: "failed" }
+            : transaction,
+        ),
+      };
+      orders.set(input.paymentId, failedOrder);
+      return failedOrder;
+    },
+
+    async cancelPendingOrder(input) {
+      const order = orders.get(input.paymentId);
+      if (!order) return null;
+      const canceledOrder: Order = {
+        ...order,
+        displayStatus: "canceled",
+        transactions: order.transactions.map((transaction) =>
+          transaction.paymentId === input.paymentId
+            ? { ...transaction, provider: input.provider, status: "canceled" }
+            : transaction,
+        ),
+      };
+      orders.set(input.paymentId, canceledOrder);
+      return canceledOrder;
+    },
+  };
+}
+
+function checkoutMockCart(args: {
+  input: CheckoutCartInput;
+  products: ProductDetail[];
+  viewCart: (cart: MockCart) => CartView;
+  requireCart: (cartToken: string) => MockCart;
+}): CreatePendingOrderResult {
+  const cart = args.requireCart(args.input.cartToken);
+  const view = args.viewCart(cart);
+  if (view.items.length === 0) throw new Error("Cart is empty");
+
+  const paymentId = `mock_${Date.now()}_${Math.random().toString(16).slice(2)}`;
+  const orderNumber = `ORD-${Date.now().toString().slice(-8)}`;
+  const order: Order = {
+    id: `order_${paymentId}`,
+    orderNumber,
+    displayStatus: "pending",
+    items: view.items.map((item) => ({
+      variantId: item.variantId,
+      productTitle: item.productTitle,
+      variantTitle: item.variantTitle,
+      quantity: item.quantity,
+      unitAmount: item.unitAmount,
+      lineAmount: item.lineAmount,
+    })),
+    customerSnapshot: args.input.customerSnapshot,
+    shippingAddress: args.input.shippingAddress,
+    subtotalAmount: view.subtotalAmount,
+    shippingAmount: view.shippingAmount,
+    totalAmount: view.totalAmount,
+    transactions: [
+      {
+        paymentId,
+        provider: "mock",
+        status: "pending",
+        amount: view.totalAmount,
+      },
+    ],
+  };
+
+  orders.set(paymentId, order);
+  // The cart is consumed by checkout (Shopify cart→checkout boundary); the
+  // browser cookie will resolve to no active cart and mint a fresh one.
+  carts.delete(args.input.cartToken);
+
+  return {
+    order,
+    paymentId,
+    paymentName: buildPaymentName(order.items.map((item) => item.productTitle)),
+    amount: view.totalAmount,
+    currency: view.currency,
+  };
+}
+
+function allVariants(products: ProductDetail[]): ProductVariant[] {
+  return products.flatMap((entry) => entry.variants);
+}
+
+function buildPaymentName(productTitles: string[]): string {
+  const [first, ...rest] = productTitles;
+  if (!first) return "Order";
+  return rest.length === 0 ? first : `${first} and ${rest.length} more`;
+}
+
+/** Test helper: reset the in-memory stores between cases. */
+export function resetMockCommerceState(): void {
+  carts.clear();
+  orders.clear();
+}
+
+/** Test helper: read a stored mock order by its mock payment id. */
+export function getMockOrder(paymentId: string): Order | null {
+  return orders.get(paymentId) ?? null;
+}