@stacksjs/commerce 0.70.55 → 0.70.57

package/src/orders/index.ts

@@ -1,91 +0,0 @@
-export {
-  bulkDestroy,
-  bulkSoftDelete,
-  destroy,
-  softDelete,
-} from './destroy'
-
-export {
-  downloadOrders,
-  exportOrders,
-  storeOrdersExport,
-} from './export'
-
-export {
-  calculateOrderMetrics,
-  compareOrdersByPeriod,
-  fetchAll,
-  fetchById,
-  fetchDailyOrderTrends,
-  fetchStats,
-} from './fetch'
-
-export {
-  store,
-} from './store'
-
-// Atomic order placement (stacksjs/stacks#1879 Co-1).
-// Wraps order + payment + inventory decrement in a single
-// transaction so any failure rolls back the rest.
-export { placeOrder } from './place-order'
-export type { PlaceOrderInput, PlaceOrderResult } from './place-order'
-
-// Event bus integration + status-transition state machine
-// (stacksjs/stacks#1879 Co-18, Co-4). Emit helpers fire
-// order:created / order:paid / order:shipped / order:delivered /
-// order:cancelled / order:refunded for downstream subscribers;
-// `canTransition` rejects illegal state changes.
-export {
-  canTransition,
-  emitForStatus,
-  emitOrderCancelled,
-  emitOrderCreated,
-  emitOrderDelivered,
-  emitOrderPaid,
-  emitOrderRefunded,
-  emitOrderShipped,
-} from './events'
-export type { OrderStatus } from './events'
-
-export {
-  update,
-  updateDeliveryInfo,
-  updateStatus,
-} from './update'
-
-// Stripe webhook handlers (stacksjs/stacks#1879 Co-17). Call
-// registerCommerceWebhookHandlers() once at boot; the payments
-// package's processWebhook() verifies signatures + dispatches.
-export {
-  handleChargeRefunded,
-  handlePaymentIntentFailed,
-  handlePaymentIntentSucceeded,
-  registerCommerceWebhookHandlers,
-} from './webhook'
-
-// Server-side cart-to-order total recompute (stacksjs/stacks#1879 Co-13).
-// Apps pre-flight the cart through this before placeOrder to detect
-// client-supplied drift and reject "price changed" cases.
-export { recomputeOrderTotals } from './totals'
-export type {
-  RecomputeLineItem,
-  RecomputeOrderInput,
-  RecomputeOrderResult,
-} from './totals'
-
-// Cart / order policy guards (stacksjs/stacks#1879 Co-7, Co-14, Co-15).
-// Pre-flight the cart through these before placeOrder; abandoned-
-// cart cleanup runs as a scheduled job.
-export {
-  cleanupAbandonedCarts,
-  validateCartQuantities,
-  validateCouponStacking,
-  validateQuantityBounds,
-} from './guards'
-export type {
-  CleanupAbandonedCartsOptions,
-  CleanupAbandonedCartsResult,
-  CouponStackingPolicy,
-  CouponStackingResult,
-  QuantityBoundsResult,
-} from './guards'

package/src/orders/place-order.ts

@@ -1,274 +0,0 @@
-/**
- * Atomic order placement (stacksjs/stacks#1879 Co-1).
- *
- * Background: order creation, payment recording, and inventory
- * decrement happened as three separate writes. A failure between
- * steps left the system in a split-brain state:
- *   - Order created but no payment row → reconciliation churn
- *   - Payment created but no inventory decrement → over-sale
- *   - Inventory decremented but order rolled back → phantom stock loss
- *
- * Fix: wrap all three writes in a single `db.transaction`. Either
- * everything commits or nothing does. The Stripe API call (a
- * network round-trip, not a DB write) stays OUTSIDE the transaction
- * to keep the transaction window short — apps that need
- * Stripe-side atomicity already get it via #1876 X-1's idempotency
- * keys (a retry of the local DB after a successful Stripe call
- * returns the same Stripe object).
- *
- * @example
- * ```ts
- * const result = await placeOrder({
- *   order: { customer_id: user.id, total_amount: 12345, ... },
- *   payment: { transaction_id: stripeIntent.id, amount: 12345, ... },
- *   inventory: [
- *     { id: cart.itemA, delta: -2 },
- *     { id: cart.itemB, delta: -1 },
- *   ],
- * })
- * if (!result.ok) {
- *   // Stock changed between cart view and checkout, or payment
- *   // duplicated — caller can show a useful error.
- *   throw new HttpError(409, result.reason)
- * }
- * await sendOrderConfirmation(result.order)
- * ```
- */
-
-import { randomUUIDv7 } from 'bun'
-import { db } from '@stacksjs/database'
-import { formatDate } from '@stacksjs/orm'
-import { sql } from '@stacksjs/database'
-import { emitOrderCreated, emitOrderPaid } from './events'
-
-type OrderJsonResponse = ModelRow<typeof Order>
-type NewOrder = NewModelData<typeof Order>
-type PaymentJsonResponse = ModelRow<typeof Payment>
-type NewPayment = NewModelData<typeof Payment>
-
-export interface PlaceOrderInput {
-  /** Order row fields. UUID / created_at / updated_at are filled in. */
-  order: NewOrder
-  /** Optional payment row to record alongside the order. */
-  payment?: NewPayment
-  /** Optional inventory decrements to apply (each delta is signed). */
-  inventory?: ReadonlyArray<{ id: number, delta: number }>
-  /**
-   * Optional caller-supplied idempotency key (stacksjs/stacks#1879
-   * Co-3). When set, the order is recorded against this key in a
-   * dedup side-table; a retry with the same key returns the
-   * original order id instead of creating a duplicate. Use this
-   * when a user might double-click "place order" (network blip,
-   * impatient retry, mobile background-sync race). UUID per
-   * logical checkout attempt is typical; server-side `userId +
-   * cartId` also works.
-   */
-  idempotencyKey?: string
-}
-
-/**
- * Discriminated result. `ok: true` means the order, payment, and
- * inventory all committed; `ok: false` carries a `reason` so the
- * caller can surface a specific error to the user.
- */
-export type PlaceOrderResult =
-  | { ok: true, order: OrderJsonResponse, payment?: PaymentJsonResponse }
-  | { ok: false, reason: 'out-of-stock' | 'duplicate-payment' | 'duplicate-idempotency-key' | 'unknown', failedAt?: string, error?: unknown }
-
-/**
- * Look up an existing order by idempotency key — returns the
- * original order when this key has been seen before, null when it
- * hasn't. Degrades to "always null" with a startup warn when the
- * `order_idempotency` dedup table isn't migrated yet.
- */
-let warnedAboutMissingOrderIdempotencyTable = false
-async function findOrderByIdempotencyKey(key: string): Promise<OrderJsonResponse | null> {
-  try {
-    const row = await (db as any)
-      .selectFrom('order_idempotency')
-      .where('idempotency_key', '=', key)
-      .selectAll()
-      .executeTakeFirst()
-    if (!row) return null
-    const order = await (db as any)
-      .selectFrom('orders')
-      .where('id', '=', row.order_id)
-      .selectAll()
-      .executeTakeFirst()
-    return (order ?? null) as OrderJsonResponse | null
-  }
-  catch (err: any) {
-    if (err?.message?.includes('no such table') || err?.message?.includes("doesn't exist")) {
-      if (!warnedAboutMissingOrderIdempotencyTable) {
-        warnedAboutMissingOrderIdempotencyTable = true
-        // eslint-disable-next-line no-console
-        console.warn('[commerce/orders] order_idempotency table missing — idempotency keys are accepted but NOT enforced. Run migrations to enable dedup.')
-      }
-      return null
-    }
-    throw err
-  }
-}
-
-export async function placeOrder(input: PlaceOrderInput): Promise<PlaceOrderResult> {
-  // Idempotency-key short-circuit (stacksjs/stacks#1879 Co-3).
-  // Before doing any work, check the dedup side-table — a retry
-  // with the same key returns the original order without
-  // re-running the transaction. Insert-into-dedup happens AFTER
-  // the order successfully commits, so a partial failure (e.g.,
-  // the original placeOrder threw mid-transaction) doesn't
-  // permanently lock the key.
-  if (input.idempotencyKey) {
-    const existing = await findOrderByIdempotencyKey(input.idempotencyKey)
-    if (existing)
-      return { ok: true, order: existing }
-  }
-
-  try {
-    const result = await db.transaction().execute(async (trx: any) => {
-      const now = formatDate(new Date())
-
-      // 1. Insert the order row.
-      const orderData = {
-        ...input.order,
-        status: input.order.status || 'PENDING',
-        uuid: randomUUIDv7(),
-        created_at: now,
-        updated_at: now,
-      }
-      const orderInsert: any = await trx
-        .insertInto('orders')
-        .values(orderData as NewOrder)
-        .executeTakeFirst()
-
-      const orderId = Number(orderInsert?.insertId) || Number(orderInsert?.numInsertedOrUpdatedRows)
-      if (!orderId)
-        throw Object.assign(new Error('order insert returned no id'), { __placeFail: true, failedAt: 'order', reason: 'unknown' })
-
-      // 2. Insert the payment row if provided. The transaction_id
-      // unique constraint catches duplicate Stripe webhook deliveries
-      // (the pre-fix code's Co-19 backstop) — we surface it as a
-      // structured result instead of a generic SQL error.
-      let paymentRow: PaymentJsonResponse | undefined
-      if (input.payment) {
-        try {
-          const paymentInsert: any = await trx
-            .insertInto('payments')
-            .values({
-              ...input.payment,
-              order_id: orderId,
-              created_at: now,
-              updated_at: now,
-            } as NewPayment)
-            .executeTakeFirst()
-          const paymentId = Number(paymentInsert?.insertId) || Number(paymentInsert?.numInsertedOrUpdatedRows)
-          if (paymentId)
-            paymentRow = await trx.selectFrom('payments').where('id', '=', paymentId).selectAll().executeTakeFirst() as PaymentJsonResponse | undefined
-        }
-        catch (err: any) {
-          if (err?.message?.includes('UNIQUE constraint') || err?.message?.includes('Duplicate entry'))
-            throw Object.assign(new Error('duplicate payment transaction_id'), { __placeFail: true, failedAt: 'payment', reason: 'duplicate-payment' })
-          throw Object.assign(err, { __placeFail: true, failedAt: 'payment', reason: 'unknown' })
-        }
-      }
-
-      // 3. Decrement inventory atomically. Same conditional UPDATE
-      // shape as adjustInventoryMany — `inventory_count + delta >=
-      // 0` enforces the precondition in the WHERE clause so two
-      // concurrent placeOrders for the same last-in-stock item don't
-      // both succeed.
-      if (input.inventory && input.inventory.length > 0) {
-        for (let i = 0; i < input.inventory.length; i++) {
-          const { id, delta } = input.inventory[i]!
-          if (!Number.isFinite(delta) || delta === 0)
-            throw Object.assign(new Error('inventory delta must be a non-zero finite number'), { __placeFail: true, failedAt: 'inventory', reason: 'unknown' })
-
-          const adjResult: any = await trx
-            .updateTable('products')
-            .set({
-              inventory_count: sql`inventory_count + ${delta}`,
-              updated_at: now,
-            })
-            .where('id', '=', id)
-            .where(sql`inventory_count + ${delta}`, '>=', 0)
-            .execute()
-
-          const affected = Number(
-            adjResult?.numUpdatedRows
-            ?? adjResult?.[0]?.numUpdatedRows
-            ?? adjResult?.numAffectedRows
-            ?? 0,
-          )
-          if (!affected)
-            throw Object.assign(new Error(`inventory adjust failed for product ${id}`), { __placeFail: true, failedAt: 'inventory', reason: 'out-of-stock' })
-        }
-      }
-
-      // 4. Record the idempotency key inside the transaction so a
-      // concurrent retry of the same key (the classic double-click
-      // scenario) hits the unique constraint and rolls back here
-      // instead of creating a second order. Skipped silently when
-      // the table isn't migrated yet — same opt-in pattern as the
-      // Stripe webhook dedup.
-      if (input.idempotencyKey) {
-        try {
-          await trx
-            .insertInto('order_idempotency')
-            .values({
-              idempotency_key: input.idempotencyKey,
-              order_id: orderId,
-              created_at: now,
-            })
-            .execute()
-        }
-        catch (err: any) {
-          // Unique-constraint collision = concurrent retry won the
-          // race; abort this transaction so the caller falls back
-          // to the existing order via the pre-transaction lookup
-          // on the next attempt (or right now if they re-call).
-          if (err?.message?.includes('UNIQUE constraint') || err?.message?.includes('Duplicate entry'))
-            throw Object.assign(new Error('idempotency-key collision'), { __placeFail: true, failedAt: 'idempotency', reason: 'duplicate-idempotency-key' })
-          // Missing table: degrade silently (the pre-transaction
-          // lookup already warned).
-          if (!(err?.message?.includes('no such table') || err?.message?.includes("doesn't exist")))
-            throw err
-        }
-      }
-
-      // 5. Refetch the order so callers get the post-write canonical row.
-      const order = await trx.selectFrom('orders').where('id', '=', orderId).selectAll().executeTakeFirst() as OrderJsonResponse | undefined
-      if (!order)
-        throw Object.assign(new Error('order disappeared mid-transaction'), { __placeFail: true, failedAt: 'order', reason: 'unknown' })
-
-      return { order, payment: paymentRow }
-    })
-
-    // Fire `order:created` AFTER the transaction commits (#1879
-    // Co-18). If a payment row also landed, also emit `order:paid`
-    // — the placeOrder path is the typical "checkout completed
-    // successfully" entry point. Both fire-and-forget; emission
-    // failures never undo the write.
-    void emitOrderCreated(result.order as unknown as Record<string, unknown>)
-    if (result.payment) {
-      void emitOrderPaid(
-        result.order as unknown as Record<string, unknown>,
-        result.payment as unknown as Record<string, unknown>,
-      )
-    }
-
-    return { ok: true, order: result.order, payment: result.payment }
-  }
-  catch (err: any) {
-    if (err?.__placeFail) {
-      return {
-        ok: false,
-        reason: err.reason as PlaceOrderResult['reason'] extends infer R ? R : never,
-        failedAt: err.failedAt,
-        error: err,
-      }
-    }
-    // Genuinely unexpected error — surface up so the global error
-    // handler can log it. Transaction already rolled back.
-    throw err
-  }
-}

package/src/orders/store.ts

@@ -1,51 +0,0 @@
-// Import dependencies
-import { randomUUIDv7 } from 'bun'
-import { db } from '@stacksjs/database'
-import { formatDate } from '@stacksjs/orm'
-type OrderJsonResponse = ModelRow<typeof Order>
-type NewOrder = NewModelData<typeof Order>
-
-/**
- * Create a new order
- *
- * @param data The order data to store
- * @returns The newly created order record
- */
-export async function store(data: NewOrder): Promise<OrderJsonResponse | undefined> {
-  const orderData = {
-    ...data,
-    status: data.status || 'PENDING',
-    uuid: randomUUIDv7(),
-    created_at: formatDate(new Date()),
-    updated_at: formatDate(new Date()),
-  }
-
-  try {
-    // Insert the order record
-    const createdOrder = await db
-      .insertInto('orders')
-      .values(orderData as NewOrder)
-      .executeTakeFirst()
-
-    const insertId = Number(createdOrder?.insertId) || Number(createdOrder?.numInsertedOrUpdatedRows)
-
-    // If insert was successful, retrieve the newly created order
-    if (insertId) {
-      const order = await db
-        .selectFrom('orders')
-        .where('id', '=', insertId)
-        .selectAll()
-        .executeTakeFirst()
-
-      return order as OrderJsonResponse | undefined
-    }
-
-    return undefined
-  }
-  catch (error) {
-    if (error instanceof Error)
-      throw new Error(`Failed to create order: ${error.message}`)
-
-    throw error
-  }
-}

package/src/orders/totals.ts

@@ -1,190 +0,0 @@
-/**
- * Server-side order-total recomputation (stacksjs/stacks#1879 Co-13).
- *
- * Background: the pre-fix `placeOrder` path trusted whatever
- * `total_amount` the client supplied on the order row. A client
- * could submit `total_amount: 0.01` and the order would persist
- * at that amount (Stripe-side might catch it if the payment
- * intent's amount field disagrees, but the LOCAL order record
- * was already wrong). Worse: a benign client whose cart total
- * drifted (price change between cart view and checkout) would
- * silently charge the wrong amount with no signal.
- *
- * This module ships a `recomputeOrderTotals(input)` helper that
- * derives subtotal + tax + shipping + discount from the line
- * items + current product prices + current tax rates + current
- * shipping rates, returns the canonical totals, and (optionally)
- * compares against a client-supplied total to flag drift.
- *
- * Caller pattern:
- *   1. Build the line-items array from the cart (server-side)
- *   2. Call `recomputeOrderTotals({ items, ... })` to get canonical numbers
- *   3. If `result.diffCents > MAX_DRIFT_CENTS`, reject with "price changed"
- *   4. Use `result.total` as the authoritative order.total_amount
- *
- * Currency: all amounts are integer cents (or your currency's smallest
- * unit). Float arithmetic on money is a known footgun (#1879 Co-12);
- * cents avoid the rounding-error class entirely.
- */
-
-import { db } from '@stacksjs/database'
-
-export interface RecomputeLineItem {
-  /** Product ID — used to look up the current canonical unit price. */
-  productId: number
-  /** Quantity ordered. */
-  quantity: number
-  /**
-   * Optional override unit price in cents. When set, used INSTEAD
-   * of the product table lookup — for grandfathered prices, admin
-   * discounts, or B2B contract pricing. Document the override in
-   * the order metadata so the audit trail is traceable.
-   */
-  unitPriceCents?: number
-}
-
-export interface RecomputeOrderInput {
-  /** Server-built line items. Quantities and product IDs only — prices
-   *  default to the products table. */
-  items: ReadonlyArray<RecomputeLineItem>
-  /** Optional tax rate ID to apply. Looked up server-side; rate is
-   *  applied to subtotal AFTER discount. */
-  taxRateId?: number
-  /** Optional shipping rate cents. Apps that pre-validate the zone
-   *  (#1879 Co-11) pass the resolved cost here. */
-  shippingCents?: number
-  /** Optional flat discount in cents (e.g. from coupon). Applied to
-   *  subtotal before tax. */
-  discountCents?: number
-  /** Optional client-supplied total in cents for drift detection. */
-  clientTotalCents?: number
-  /** Max acceptable drift between client total and canonical total,
-   *  default 5 cents. Drift past this returns `priceChanged: true`. */
-  maxDriftCents?: number
-}
-
-export interface RecomputeOrderResult {
-  /** Sum of line-item subtotals (qty × unit price) in cents. */
-  subtotalCents: number
-  /** Discount applied (>= 0). */
-  discountCents: number
-  /** Tax in cents, computed from (subtotal - discount) × rate. */
-  taxCents: number
-  /** Shipping cost in cents. */
-  shippingCents: number
-  /** Final total: subtotal - discount + tax + shipping. */
-  totalCents: number
-  /** Per-line resolved unit prices, for the audit trail. */
-  resolvedItems: Array<{ productId: number, quantity: number, unitPriceCents: number, lineCents: number }>
-  /** Set when `clientTotalCents` was provided and differs from
-   *  canonical by more than `maxDriftCents`. Caller should reject
-   *  the checkout and ask the user to re-confirm. */
-  priceChanged: boolean
-  /** Absolute drift in cents (always >= 0). */
-  diffCents: number
-}
-
-/**
- * Fetch the current canonical unit price for each product id.
- * Bulk single-query so a 10-item cart isn't a 10-query stampede.
- * Returns a Map keyed by product id.
- */
-async function fetchProductPrices(ids: number[]): Promise<Map<number, number>> {
-  if (ids.length === 0) return new Map()
-  const rows = await (db as any)
-    .selectFrom('products')
-    .where('id', 'in', ids)
-    .select(['id', 'price'])
-    .execute() as Array<{ id: number, price: number | string }>
-  const out = new Map<number, number>()
-  for (const r of rows) {
-    // Some schemas store price as DECIMAL/string — coerce to cents.
-    // We assume `price` is in cents already (that's the framework
-    // convention since money math should never touch floats); a
-    // string-stored numeric coerces cleanly via Number().
-    const cents = Number(r.price)
-    if (Number.isFinite(cents))
-      out.set(r.id, Math.round(cents))
-  }
-  return out
-}
-
-/**
- * Look up a tax rate by id and return its decimal multiplier
- * (e.g. `0.0875` for 8.75% sales tax). Returns 0 when the id is
- * missing or the lookup fails — the caller already passed
- * `taxRateId` deliberately, so a missing rate is a config bug
- * worth surfacing via the canonical total being wrong.
- */
-async function fetchTaxRate(id: number): Promise<number> {
-  try {
-    const row = await (db as any)
-      .selectFrom('tax_rates')
-      .where('id', '=', id)
-      .select(['rate'])
-      .executeTakeFirst()
-    const rate = Number(row?.rate ?? 0)
-    return Number.isFinite(rate) ? rate : 0
-  }
-  catch {
-    return 0
-  }
-}
-
-export async function recomputeOrderTotals(input: RecomputeOrderInput): Promise<RecomputeOrderResult> {
-  // Lookups happen up-front so the rest of the function is pure
-  // arithmetic against in-memory data — easier to reason about
-  // and easier to mock in tests.
-  const productIds = input.items.map(i => i.productId)
-  const priceMap = await fetchProductPrices(productIds)
-  const taxRate = input.taxRateId != null ? await fetchTaxRate(input.taxRateId) : 0
-
-  let subtotalCents = 0
-  const resolvedItems: RecomputeOrderResult['resolvedItems'] = []
-
-  for (const item of input.items) {
-    // Prefer the caller's explicit override (admin discount, B2B
-    // contract pricing) over the products-table lookup.
-    const unitCents = item.unitPriceCents ?? priceMap.get(item.productId) ?? 0
-    const lineCents = Math.round(unitCents * item.quantity)
-    subtotalCents += lineCents
-    resolvedItems.push({
-      productId: item.productId,
-      quantity: item.quantity,
-      unitPriceCents: unitCents,
-      lineCents,
-    })
-  }
-
-  const discountCents = Math.max(0, input.discountCents ?? 0)
-  // Tax applies to (subtotal - discount), clamped to non-negative.
-  const taxableCents = Math.max(0, subtotalCents - discountCents)
-  // Round half-up at the cent boundary to match how most payment
-  // processors round (Stripe documents this).
-  const taxCents = Math.round(taxableCents * taxRate)
-  const shippingCents = Math.max(0, input.shippingCents ?? 0)
-  const totalCents = subtotalCents - discountCents + taxCents + shippingCents
-
-  // Drift detection against client-supplied total. Default tolerance
-  // is 5 cents — covers most rounding-disagreement cases (one side
-  // rounded a quarter-cent up, the other rounded it down) without
-  // hiding genuine price changes.
-  const maxDrift = input.maxDriftCents ?? 5
-  let priceChanged = false
-  let diffCents = 0
-  if (input.clientTotalCents != null) {
-    diffCents = Math.abs(totalCents - input.clientTotalCents)
-    priceChanged = diffCents > maxDrift
-  }
-
-  return {
-    subtotalCents,
-    discountCents,
-    taxCents,
-    shippingCents,
-    totalCents,
-    resolvedItems,
-    priceChanged,
-    diffCents,
-  }
-}