@01.software/init 0.9.1 → 0.10.0

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

@@ -0,0 +1,913 @@
+import '../../server-only-guard.ts'
+import { normalizeCartLines } from '../../cart/normalize.ts'
+import type { CartProvider, CommerceProvider } from '../provider.ts'
+import type { CheckoutCommerceProvider } from '../../checkout/types.ts'
+import type {
+  CartItemView,
+  CartView,
+  CommerceImage,
+  CreatePendingOrderResult,
+  Order,
+  ShippingPolicy,
+} from '../types.ts'
+import {
+  mapSoftwareProductDetailResult,
+  mapSoftwareVariant,
+  type SoftwareProductDetailResultLike,
+} from './software-mappers.ts'
+
+type SoftwareProductListDoc = {
+  id: string | number
+  slug?: string | null
+  title?: string | null
+  description?: string | null
+  status?: string | null
+}
+
+type SoftwareVariantDoc = Parameters<typeof mapSoftwareVariant>[0] & {
+  product?: unknown
+}
+
+type SoftwareCommerceConfig = {
+  publishableKey: string
+  secretKey: string
+  apiUrl?: string
+  shippingPolicy: ShippingPolicy
+}
+
+type SoftwareEnv = NodeJS.ProcessEnv | Record<string, string | undefined>
+
+// ---------------------------------------------------------------------------
+// SDK response shapes (narrowed). The real SDK types are richer; we narrow to
+// the fields the storefront consumes and keep relation refs tolerant of
+// id-only (depth 0) or populated objects.
+// ---------------------------------------------------------------------------
+type CartItemDoc = {
+  id?: string | number
+  product?: unknown
+  variant?: unknown
+  quantity?: number | null
+  unitPrice?: number | null
+  discountedTotalPrice?: number | null
+}
+
+type CartDoc = {
+  id?: string | number
+  currency?: string | null
+  subtotalAmount?: number | null
+  shippingAmount?: number | null
+  discountAmount?: number | null
+  totalAmount?: number | null
+  discountCode?: string | null
+  items?: CartItemDoc[] | null
+}
+
+type OrderItemDoc = {
+  product?: unknown
+  variant?: unknown
+  productTitle?: string | null
+  variantTitle?: string | null
+  quantity?: number | null
+  unitPrice?: number | null
+  totalPrice?: number | null
+  discountedTotalPrice?: number | null
+}
+
+type TransactionDoc = {
+  pgPaymentId?: string | null
+  pgProvider?: string | null
+  status?: string | null
+  amount?: number | null
+}
+
+type OrderDoc = {
+  id?: string | number
+  orderNumber?: string | null
+  financialStatus?: string | null
+  displayFinancialStatus?: string | null
+  displayStatus?: string | null
+  customerSnapshot?: {
+    name?: string | null
+    email?: string | null
+    phone?: string | null
+  } | null
+  shippingAddress?: {
+    recipientName?: string | null
+    phone?: string | null
+    postalCode?: string | null
+    address?: string | null
+    detailAddress?: string | null
+    deliveryMessage?: string | null
+  } | null
+  subtotalAmount?: number | null
+  shippingAmount?: number | null
+  totalAmount?: number | null
+  items?: OrderItemDoc[] | { docs?: OrderItemDoc[] | null } | null
+}
+
+type OrderWithTransaction = {
+  order: OrderDoc
+  transaction: TransactionDoc | null
+}
+
+type CustomerSnapshotInput = { name?: string; email: string; phone?: string }
+
+/**
+ * The slice of the `@01.software/sdk` server client this adapter depends on.
+ * Declaring it explicitly is the SDK boundary: the real client is cast to it
+ * once in {@link createSoftwareCommerceProvider}, and tests can inject a fake to
+ * exercise the checkout → confirm round-trip without a live Console.
+ */
+export type SoftwareSdkClientLike = {
+  collections: {
+    from: (slug: string) => {
+      find: (options: {
+        limit?: number
+        depth?: number
+        where?: unknown
+        joins?: boolean
+      }) => Promise<{ docs: unknown[]; totalDocs?: number }>
+      update: (id: string, data: Record<string, unknown>) => Promise<unknown>
+    }
+  }
+  commerce: {
+    product: {
+      detail: (params: { slug: string }) => Promise<unknown>
+      stockCheck: (params: {
+        items: { variantId: string; quantity: number }[]
+      }) => Promise<{
+        allAvailable?: boolean
+        results: {
+          variantId: string | number
+          requestedQuantity: number
+          isUnlimited: boolean
+          availableStock: number | null
+          available: boolean
+          status: string
+        }[]
+      }>
+    }
+    cart: {
+      create: () => Promise<{ cartToken?: string }>
+      get: (cartToken: string) => Promise<CartDoc>
+      addItem: (params: {
+        cartToken: string
+        product: string
+        variant: string
+        option?: string
+        quantity: number
+      }) => Promise<unknown>
+      updateItem: (params: {
+        cartToken: string
+        cartItemId: string
+        quantity: number
+      }) => Promise<unknown>
+      removeItem: (params: {
+        cartToken: string
+        cartItemId: string
+      }) => Promise<unknown>
+      clear: (params: { cartToken: string }) => Promise<unknown>
+    }
+    orders: {
+      checkout: (params: {
+        cartId: string
+        orderNumber: string
+        customerSnapshot: CustomerSnapshotInput
+        idempotencyKey?: string
+      }) => Promise<OrderDoc>
+      confirmPaymentReturningOrder: (params: {
+        orderNumber?: string
+        pgPaymentId: string
+        pgProvider: string
+        amount: number
+        currency?: string
+        providerEventId?: string
+        confirmationSource?: string
+        idempotencyKey?: string
+      }) => Promise<OrderWithTransaction>
+      getByPaymentId: (params: {
+        pgProvider: string
+        pgPaymentId: string
+      }) => Promise<OrderWithTransaction>
+      updateTransaction: (params: {
+        pgPaymentId: string
+        status: string
+      }) => Promise<unknown>
+      cancelOrder: (params: {
+        orderNumber: string
+        reasonCode?: string
+        reasonDetail?: string
+        idempotencyKey?: string
+      }) => Promise<unknown>
+    }
+  }
+}
+
+export function createSoftwareCommerceProvider(): CommerceProvider {
+  const config = getSoftwareCommerceConfig(process.env)
+  const clientPromise = createSoftwareSdkClient(config)
+  return buildSoftwareCommerceProvider(
+    // The real server client is a structural superset of the slice we use.
+    clientPromise as unknown as Promise<SoftwareSdkClientLike>,
+    config.shippingPolicy,
+  )
+}
+
+export function buildSoftwareCommerceProvider(
+  clientPromise: Promise<SoftwareSdkClientLike>,
+  shippingPolicy: ShippingPolicy,
+): CommerceProvider {
+  const provider: CommerceProvider = {
+    async listProducts(input) {
+      const client = await clientPromise
+      const limit = input?.limit ?? 24
+      const productResponse = await client.collections.from('products').find({
+        limit,
+        depth: 1,
+        where: { status: { equals: 'published' } },
+        joins: false,
+      })
+
+      const productDetails = await Promise.allSettled(
+        (productResponse.docs as SoftwareProductListDoc[]).flatMap((product) =>
+          product.slug
+            ? [client.commerce.product.detail({ slug: product.slug })]
+            : [],
+        ),
+      )
+
+      const products = productDetails.flatMap((detail) =>
+        detail.status === 'fulfilled'
+          ? wrapOptional(
+              mapSoftwareProductDetailResult(
+                detail.value as unknown as SoftwareProductDetailResultLike,
+              ),
+            )
+          : [],
+      )
+
+      return {
+        products,
+        total: productResponse.totalDocs ?? products.length,
+      }
+    },
+
+    async getProductBySlug(slug) {
+      const client = await clientPromise
+      const result = await client.commerce.product.detail({ slug })
+      const detail = mapSoftwareProductDetailResult(
+        result as unknown as SoftwareProductDetailResultLike,
+      )
+      return detail?.product.status === 'published' ? detail : null
+    },
+
+    async getVariantsByIds(ids) {
+      const client = await clientPromise
+      const normalizedIds = [...new Set(ids.map(String).filter(Boolean))]
+      if (normalizedIds.length === 0) return []
+
+      const response = await client.collections.from('product-variants').find({
+        limit: normalizedIds.length,
+        depth: 2,
+        where: { id: { in: normalizedIds } },
+      })
+
+      return (response.docs as SoftwareVariantDoc[]).map((variant) =>
+        mapSoftwareVariant(variant, getRelationId(variant.product) ?? ''),
+      )
+    },
+
+    async getShippingPolicy() {
+      return shippingPolicy
+    },
+
+    async checkStock(items) {
+      const client = await clientPromise
+      const lines = normalizeCartLines(items)
+      if (lines.length === 0) {
+        return { ok: true, lines: [] }
+      }
+
+      const stock = await client.commerce.product.stockCheck({
+        items: lines.map((line) => ({
+          variantId: line.variantId,
+          quantity: line.quantity,
+        })),
+      })
+
+      return {
+        ok: Boolean(stock.allAvailable),
+        lines: stock.results.map((line) => ({
+          variantId: String(line.variantId),
+          quantity: line.requestedQuantity,
+          availableQuantity: line.isUnlimited ? null : line.availableStock,
+          ok: Boolean(line.available),
+          reason:
+            line.status === 'not_found'
+              ? 'variant_not_found'
+              : line.available
+                ? undefined
+                : 'insufficient_stock',
+        })),
+      }
+    },
+
+    async createCart() {
+      const client = await clientPromise
+      const created = await client.commerce.cart.create()
+      if (!created.cartToken) {
+        throw new Error('Cart create did not return a cartToken')
+      }
+      return { cartToken: created.cartToken }
+    },
+
+    async getCart(cartToken) {
+      const client = await clientPromise
+      try {
+        const cart = await client.commerce.cart.get(cartToken)
+        return enrichCart(cart)
+      } catch (error) {
+        // A missing/expired/completed cart resolves to "no active cart" so the
+        // storefront can mint a fresh one rather than surfacing a 404.
+        if (isNotFound(error)) return null
+        throw error
+      }
+    },
+
+    async addCartItem({ cartToken, item }) {
+      const client = await clientPromise
+      await client.commerce.cart.addItem({
+        cartToken,
+        product: item.productId,
+        variant: item.variantId,
+        ...(item.optionId ? { option: item.optionId } : {}),
+        quantity: item.quantity,
+      })
+      return getCartOrThrow(provider, cartToken)
+    },
+
+    async updateCartItem({ cartToken, cartItemId, quantity }) {
+      const client = await clientPromise
+      await client.commerce.cart.updateItem({ cartToken, cartItemId, quantity })
+      return getCartOrThrow(provider, cartToken)
+    },
+
+    async removeCartItem({ cartToken, cartItemId }) {
+      const client = await clientPromise
+      await client.commerce.cart.removeItem({ cartToken, cartItemId })
+      return getCartOrThrow(provider, cartToken)
+    },
+
+    async clearCart({ cartToken }) {
+      const client = await clientPromise
+      await client.commerce.cart.clear({ cartToken })
+      return getCartOrThrow(provider, cartToken)
+    },
+
+    async checkoutCart(input) {
+      const client = await clientPromise
+      const cart = await client.commerce.cart.get(input.cartToken)
+      const cartId = cart.id != null ? String(cart.id) : ''
+      const lines = cart.items ?? []
+      if (!cartId || lines.length === 0) {
+        throw new Error('Cart is empty')
+      }
+
+      // The order snapshots `shippingAddress` from the cart, and checkout only
+      // accepts `customerSnapshot` — so persist the buyer-entered address on the
+      // cart first. These fields are caller-writable (only the amount fields are
+      // read-only). Shipping was already computed by the cart on each item
+      // mutation; the base fee does not depend on the address for the default
+      // policy (postalCode-driven zone surcharge recompute is owned by the
+      // Console cart shipping-authority work, not the template).
+      await client.collections.from('carts').update(cartId, {
+        email: input.customerSnapshot.email,
+        shippingAddress: {
+          recipientName: input.shippingAddress.recipientName,
+          phone: input.shippingAddress.phone,
+          postalCode: input.shippingAddress.postalCode,
+          address: input.shippingAddress.address,
+          detailAddress: input.shippingAddress.detailAddress,
+          deliveryMessage: input.shippingAddress.deliveryMessage ?? '',
+        },
+        ...(input.shippingAddress.deliveryMessage
+          ? { customerNote: input.shippingAddress.deliveryMessage }
+          : {}),
+      })
+
+      const orderNumber = generateOrderNumber()
+      // pgPaymentId is minted template-side AFTER checkout (the design's "mint
+      // after" rule): passing it to checkout would route into the Toss-only
+      // Console-owned-capture path. Checkout creates an OPEN Checkout only (no
+      // Order / Transaction yet); placement resolves it by `orderNumber`
+      // (→ `checkoutToken`) at confirm. The durable orderNumber↔pgPaymentId
+      // mapping is the Console Checkout/Transaction row after confirm — there is
+      // no local index.
+      const paymentId = `pay_${crypto.randomUUID()}`
+
+      const placed = await client.commerce.orders.checkout({
+        cartId,
+        orderNumber,
+        customerSnapshot: {
+          name: input.customerSnapshot.name,
+          email: input.customerSnapshot.email,
+          phone: input.customerSnapshot.phone,
+        },
+        idempotencyKey: `checkout-${orderNumber}`,
+      })
+
+      const order = mapOrder(placed, {
+        fallbackOrderNumber: orderNumber,
+        contact: {
+          customerSnapshot: input.customerSnapshot,
+          shippingAddress: input.shippingAddress,
+        },
+      })
+
+      const amount = placed.totalAmount ?? cart.totalAmount ?? order.totalAmount
+
+      return {
+        order,
+        paymentId,
+        paymentName: buildPaymentName(
+          order.items.map((item) => item.productTitle),
+        ),
+        amount,
+        currency: cart.currency ?? shippingPolicy.currency,
+      } satisfies CreatePendingOrderResult
+    },
+
+    async getOrderByPaymentId({ paymentId, provider: pgProvider }) {
+      const client = await clientPromise
+      try {
+        const result = await client.commerce.orders.getByPaymentId({
+          pgProvider,
+          pgPaymentId: paymentId,
+        })
+        return mapOrder(result.order, {
+          transaction: result.transaction,
+          fallbackPaymentId: paymentId,
+          fallbackProvider: pgProvider,
+        })
+      } catch (error) {
+        // Before placement (confirm) there is no payment Transaction yet, so a
+        // by-payment lookup legitimately 404s. Callers treat null as "not
+        // placed yet".
+        if (isNotFound(error)) return null
+        throw error
+      }
+    },
+
+    async confirmOrderPayment(input) {
+      const client = await clientPromise
+      const result = await client.commerce.orders.confirmPaymentReturningOrder({
+        orderNumber: input.orderNumber,
+        pgPaymentId: input.paymentId,
+        pgProvider: input.provider,
+        amount: input.amount,
+        currency: shippingPolicy.currency,
+        providerEventId: input.providerEventId,
+        confirmationSource: input.providerEventId
+          ? 'provider_webhook'
+          : 'provider_lookup',
+        idempotencyKey: input.providerEventId ?? input.paymentId,
+      })
+
+      return mapOrder(result.order, {
+        transaction: result.transaction,
+        fallbackPaymentId: input.paymentId,
+        fallbackProvider: input.provider,
+      })
+    },
+
+    async markPaymentFailed(input) {
+      const client = await clientPromise
+      // The payment Transaction only exists once a checkout is placed. A failed
+      // PG attempt before placement leaves the Checkout to expire via the
+      // Console cron, so annotation is best-effort.
+      try {
+        await client.commerce.orders.updateTransaction({
+          pgPaymentId: input.paymentId,
+          status: 'failed',
+        })
+      } catch (error) {
+        if (!isNotFound(error)) throw error
+      }
+      return provider.getOrderByPaymentId({
+        paymentId: input.paymentId,
+        provider: input.provider,
+      })
+    },
+
+    async cancelPendingOrder(input) {
+      // Pre-placement there is no Order to cancel — the abandoned Checkout
+      // expires server-side. Only a placed order can be canceled.
+      const existing = await provider.getOrderByPaymentId({
+        paymentId: input.paymentId,
+        provider: input.provider,
+      })
+      if (!existing) return null
+
+      const client = await clientPromise
+      await client.commerce.orders.cancelOrder({
+        orderNumber: existing.orderNumber,
+        reasonCode: 'other',
+        reasonDetail: 'Payment canceled before completion',
+        idempotencyKey: input.providerEventId ?? input.paymentId,
+      })
+      return { ...existing, displayStatus: 'canceled' }
+    },
+  }
+
+  /**
+   * Map a Console cart (id-only relation refs at depth 0) into the storefront
+   * `CartView`, enriching each line with catalog title/image. Products are
+   * fetched only for the cart's distinct product ids in a single query — no
+   * full-catalog scan and no per-product `detail` fan-out.
+   */
+  async function enrichCart(cart: CartDoc): Promise<CartView> {
+    const client = await clientPromise
+    const rawItems = cart.items ?? []
+    const variantIds = rawItems
+      .map((item) => getRelationId(item.variant))
+      .filter((id): id is string => Boolean(id))
+
+    const variants =
+      variantIds.length > 0 ? await provider.getVariantsByIds(variantIds) : []
+    const variantById = new Map(
+      variants.map((variant) => [variant.id, variant]),
+    )
+
+    const productIds = [
+      ...new Set(variants.map((variant) => variant.productId).filter(Boolean)),
+    ]
+    const productById =
+      productIds.length > 0
+        ? await fetchProductSummaries(client, productIds)
+        : new Map<string, ProductSummary>()
+
+    const items: CartItemView[] = rawItems.flatMap((item) => {
+      const cartItemId = item.id != null ? String(item.id) : ''
+      const variantId = getRelationId(item.variant) ?? ''
+      if (!cartItemId || !variantId) return []
+
+      const variant = variantById.get(variantId)
+      const productId = variant?.productId ?? getRelationId(item.product) ?? ''
+      const summary = productById.get(productId)
+      const quantity = item.quantity ?? 0
+      const unitAmount = item.unitPrice ?? variant?.price ?? 0
+      const lineAmount = item.discountedTotalPrice ?? unitAmount * quantity
+
+      return [
+        {
+          cartItemId,
+          productId,
+          variantId,
+          quantity,
+          unitAmount,
+          lineAmount,
+          productTitle: summary?.title ?? 'Product',
+          variantTitle: variant?.title,
+          image: variant?.images[0] ?? summary?.image ?? null,
+        },
+      ]
+    })
+
+    return {
+      id: cart.id != null ? String(cart.id) : '',
+      currency: cart.currency ?? shippingPolicy.currency,
+      subtotalAmount: cart.subtotalAmount ?? 0,
+      shippingAmount: cart.shippingAmount ?? 0,
+      discountAmount: cart.discountAmount ?? 0,
+      totalAmount: cart.totalAmount ?? 0,
+      ...(cart.discountCode ? { discountCode: cart.discountCode } : {}),
+      items,
+    }
+  }
+
+  return provider
+}
+
+async function createSoftwareSdkClient(config: SoftwareCommerceConfig) {
+  const { createServerClient } = await import('@01.software/sdk/server')
+  return createServerClient({
+    publishableKey: config.publishableKey,
+    secretKey: config.secretKey,
+    apiUrl: config.apiUrl,
+  })
+}
+
+/**
+ * Per-request **customer-JWT-scoped** commerce client (browser SDK, no secret
+ * key — the JWT is the only credential, so cart writes bind to and re-verify the
+ * customer). This is the same client family as `lib/customer/client.server.ts`;
+ * here we consume its `commerce`/`collections` surface for cart ops.
+ */
+async function createSoftwareCustomerCommerceClient(
+  config: SoftwareCommerceConfig,
+  token: string,
+) {
+  const { createClient } = await import('@01.software/sdk')
+  return createClient({
+    publishableKey: config.publishableKey,
+    apiUrl: config.apiUrl,
+    customer: { persist: false, token },
+  })
+}
+
+/**
+ * Build the shared provider around a customer-JWT client. Cart reads/writes and
+ * checkout run as the customer (publishable key + JWT, no secret key), so the
+ * Console can bind new carts to the customer and reject checkout for carts owned
+ * by another customer.
+ */
+function createSoftwareCustomerProvider(token: string): CommerceProvider {
+  const config = getSoftwareCommerceConfig(process.env)
+  const clientPromise = createSoftwareCustomerCommerceClient(config, token)
+  return buildSoftwareCommerceProvider(
+    clientPromise as unknown as Promise<SoftwareSdkClientLike>,
+    config.shippingPolicy,
+  )
+}
+
+/**
+ * A {@link CartProvider} whose cart reads/writes go through the customer's JWT
+ * client. Logged-in `createCart()` therefore mints a **customer-bound** cart
+ * (the JWT auto-binds `customer`), never a guest cart.
+ */
+export function createSoftwareCustomerCartProvider(token: string): CartProvider {
+  return createSoftwareCustomerProvider(token)
+}
+
+/**
+ * Checkout-only customer provider for route handlers. Exposing only
+ * `checkoutCart` prevents unrelated payment lifecycle operations from being
+ * accidentally run through the customer client.
+ */
+export function createSoftwareCustomerCheckoutProvider(
+  token: string,
+): CheckoutCommerceProvider {
+  return createSoftwareCustomerProvider(token)
+}
+
+export function getSoftwareCommerceConfig(
+  env: SoftwareEnv,
+): SoftwareCommerceConfig {
+  const publishableKey = env.NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY?.trim()
+  const secretKey = env.SOFTWARE_SECRET_KEY?.trim()
+  if (!publishableKey) {
+    throw new Error(
+      '01.software commerce requires NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY.',
+    )
+  }
+  if (!secretKey) {
+    throw new Error('01.software commerce requires SOFTWARE_SECRET_KEY.')
+  }
+
+  const apiUrl =
+    env.SOFTWARE_API_URL?.trim() || env.NEXT_PUBLIC_SOFTWARE_API_URL?.trim()
+  const baseAmount = readMoneyEnv(env.SOFTWARE_SHIPPING_AMOUNT, 0)
+  const freeAboveAmount = readOptionalMoneyEnv(
+    env.SOFTWARE_FREE_SHIPPING_ABOVE_AMOUNT,
+  )
+
+  return {
+    publishableKey,
+    secretKey,
+    apiUrl: apiUrl || undefined,
+    shippingPolicy: {
+      currency: 'KRW',
+      baseAmount,
+      ...(freeAboveAmount == null ? {} : { freeAboveAmount }),
+    },
+  }
+}
+
+async function getCartOrThrow(
+  provider: CommerceProvider,
+  cartToken: string,
+): Promise<CartView> {
+  const cart = await provider.getCart(cartToken)
+  if (!cart) throw new Error('Cart not found')
+  return cart
+}
+
+type SoftwareMediaRef =
+  | string
+  | number
+  | {
+      url?: string | null
+      alt?: string | null
+      width?: number | null
+      height?: number | null
+    }
+  | null
+
+type SoftwareProductSummaryDoc = {
+  id?: string | number
+  title?: string | null
+  thumbnail?: SoftwareMediaRef
+  images?: SoftwareMediaRef[] | null
+}
+
+type ProductSummary = { title: string; image: CommerceImage | null }
+
+/**
+ * Fetch title + representative image for exactly the cart's distinct products
+ * in one tenant-scoped query (depth 1 populates the media relations). Avoids
+ * the full-catalog `listProducts` scan and its per-product `detail` fan-out.
+ */
+async function fetchProductSummaries(
+  client: SoftwareSdkClientLike,
+  productIds: string[],
+): Promise<Map<string, ProductSummary>> {
+  const response = await client.collections.from('products').find({
+    limit: productIds.length,
+    depth: 1,
+    where: { id: { in: productIds } },
+  })
+
+  const summaries = new Map<string, ProductSummary>()
+  for (const doc of response.docs as SoftwareProductSummaryDoc[]) {
+    const id = doc.id != null ? String(doc.id) : ''
+    if (!id) continue
+    summaries.set(id, {
+      title: doc.title ?? 'Product',
+      image: toImage(doc.thumbnail) ?? toImage(doc.images?.[0]),
+    })
+  }
+  return summaries
+}
+
+function toImage(media: SoftwareMediaRef | undefined): CommerceImage | null {
+  if (!media || typeof media !== 'object' || !media.url) return null
+  return {
+    url: media.url,
+    alt: media.alt ?? undefined,
+    width: media.width ?? undefined,
+    height: media.height ?? undefined,
+  }
+}
+
+function mapOrder(
+  order: OrderDoc,
+  opts: {
+    transaction?: TransactionDoc | null
+    fallbackPaymentId?: string
+    fallbackProvider?: string
+    fallbackOrderNumber?: string
+    contact?: {
+      customerSnapshot: Order['customerSnapshot']
+      shippingAddress: Order['shippingAddress']
+    }
+  } = {},
+): Order {
+  const rawItems = Array.isArray(order.items)
+    ? order.items
+    : (order.items?.docs ?? [])
+
+  const transactions: Order['transactions'] = opts.transaction
+    ? [
+        {
+          paymentId:
+            opts.transaction.pgPaymentId ?? opts.fallbackPaymentId ?? '',
+          provider:
+            opts.transaction.pgProvider ?? opts.fallbackProvider ?? 'unknown',
+          status: normalizeTransactionStatus(opts.transaction.status),
+          amount: opts.transaction.amount ?? order.totalAmount ?? 0,
+        },
+      ]
+    : []
+
+  return {
+    id: order.id != null ? String(order.id) : '',
+    orderNumber: order.orderNumber ?? opts.fallbackOrderNumber ?? '',
+    displayStatus: deriveDisplayStatus(order),
+    items: rawItems.map((item) => ({
+      variantId: getRelationId(item.variant) ?? '',
+      productTitle: item.productTitle ?? 'Product',
+      variantTitle: item.variantTitle ?? undefined,
+      quantity: item.quantity ?? 0,
+      unitAmount: item.unitPrice ?? 0,
+      lineAmount: item.totalPrice ?? item.discountedTotalPrice ?? 0,
+    })),
+    customerSnapshot: {
+      name:
+        order.customerSnapshot?.name ??
+        opts.contact?.customerSnapshot.name ??
+        '',
+      email:
+        order.customerSnapshot?.email ??
+        opts.contact?.customerSnapshot.email ??
+        '',
+      phone:
+        order.customerSnapshot?.phone ??
+        opts.contact?.customerSnapshot.phone ??
+        '',
+    },
+    shippingAddress: {
+      recipientName:
+        order.shippingAddress?.recipientName ??
+        opts.contact?.shippingAddress.recipientName ??
+        '',
+      phone:
+        order.shippingAddress?.phone ??
+        opts.contact?.shippingAddress.phone ??
+        '',
+      postalCode:
+        order.shippingAddress?.postalCode ??
+        opts.contact?.shippingAddress.postalCode ??
+        '',
+      address:
+        order.shippingAddress?.address ??
+        opts.contact?.shippingAddress.address ??
+        '',
+      detailAddress:
+        order.shippingAddress?.detailAddress ??
+        opts.contact?.shippingAddress.detailAddress ??
+        '',
+      deliveryMessage:
+        order.shippingAddress?.deliveryMessage ??
+        opts.contact?.shippingAddress.deliveryMessage ??
+        '',
+    },
+    subtotalAmount: order.subtotalAmount ?? 0,
+    shippingAmount: order.shippingAmount ?? 0,
+    totalAmount: order.totalAmount ?? 0,
+    transactions,
+  }
+}
+
+function deriveDisplayStatus(order: OrderDoc): Order['displayStatus'] {
+  const financial = order.displayFinancialStatus ?? order.financialStatus
+  if (financial === 'paid' || financial === 'partially_refunded') return 'paid'
+  if (
+    financial === 'canceled' ||
+    financial === 'voided' ||
+    financial === 'refunded'
+  ) {
+    return 'canceled'
+  }
+  if (order.displayStatus === 'paid') return 'paid'
+  if (order.displayStatus === 'canceled') return 'canceled'
+  return 'pending'
+}
+
+function normalizeTransactionStatus(
+  status: string | null | undefined,
+): Order['transactions'][number]['status'] {
+  if (status === 'paid') return 'paid'
+  if (status === 'failed') return 'failed'
+  // `refunded`/`canceled` both read as canceled on the storefront transaction.
+  if (status === 'canceled' || status === 'refunded') return 'canceled'
+  return 'pending'
+}
+
+function isNotFound(error: unknown): boolean {
+  if (!error || typeof error !== 'object') return false
+  const status = (error as { status?: number }).status
+  const name = (error as { name?: string }).name
+  return status === 404 || name === 'NotFoundError'
+}
+
+function readMoneyEnv(value: string | undefined, fallback: number): number {
+  if (value == null || value.trim() === '') return fallback
+  const parsed = Number(value)
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    throw new Error(`Expected a non-negative number, received ${value}.`)
+  }
+  return Math.round(parsed)
+}
+
+function readOptionalMoneyEnv(value: string | undefined): number | undefined {
+  if (value == null || value.trim() === '') return undefined
+  return readMoneyEnv(value, 0)
+}
+
+function getRelationId(value: unknown): string | null {
+  if (value == null) return null
+  if (typeof value === 'string' || typeof value === 'number')
+    return String(value)
+  if (typeof value === 'object' && 'id' in value) {
+    const id = (value as { id?: unknown }).id
+    if (typeof id === 'string' || typeof id === 'number') return String(id)
+  }
+  return null
+}
+
+function buildPaymentName(productTitles: string[]): string {
+  const [first, ...rest] = productTitles
+  if (!first) return 'Order'
+  return rest.length === 0 ? first : `${first} and ${rest.length} more`
+}
+
+function wrapOptional<T>(value: T | null | undefined): T[] {
+  return value == null ? [] : [value]
+}
+
+function generateOrderNumber(): string {
+  return `ORD-${Date.now().toString(36).toUpperCase()}-${crypto
+    .randomUUID()
+    .slice(0, 8)
+    .toUpperCase()}`
+}