@stacksjs/commerce 0.70.54 → 0.70.55

package/src/orders/destroy.ts

@@ -0,0 +1,111 @@
+import { db } from '@stacksjs/database'
+
+/**
+ * Delete an order by ID
+ *
+ * @param id The ID of the order to delete
+ * @returns True if the order was deleted, false otherwise
+ */
+export async function destroy(id: number): Promise<boolean> {
+  try {
+    const result = await db
+      .deleteFrom('orders')
+      .where('id', '=', id)
+      .executeTakeFirst()
+
+    return Number(result.numDeletedRows) > 0
+  }
+  catch (error) {
+    if (error instanceof Error) {
+      throw new TypeError(`Failed to delete order: ${error.message}`)
+    }
+
+    throw error
+  }
+}
+
+/**
+ * Soft delete an order by ID (updates status to CANCELED)
+ *
+ * @param id The ID of the order to soft delete
+ * @returns True if the order was soft deleted, false otherwise
+ */
+export async function softDelete(id: number): Promise<boolean> {
+  try {
+    // Update the status to CANCELED instead of deleting
+    const result = await db
+      .updateTable('orders')
+      .set({ status: 'CANCELED' })
+      .where('id', '=', id)
+      .executeTakeFirst()
+
+    // Return true if any row was affected (updated)
+    return Number(result.numUpdatedRows) > 0
+  }
+  catch (error) {
+    if (error instanceof Error) {
+      throw new TypeError(`Failed to soft delete order: ${error.message}`)
+    }
+
+    throw error
+  }
+}
+
+/**
+ * Delete multiple orders by ID
+ *
+ * @param ids Array of order IDs to delete
+ * @returns Number of orders deleted
+ */
+export async function bulkDestroy(ids: number[]): Promise<number> {
+  if (!ids.length)
+    return 0
+
+  try {
+    // Perform the delete operation
+    const result = await db
+      .deleteFrom('orders')
+      .where('id', 'in', ids)
+      .executeTakeFirst()
+
+    // Return the number of deleted rows
+    return Number(result.numDeletedRows)
+  }
+  catch (error) {
+    if (error instanceof Error) {
+      throw new TypeError(`Failed to delete orders: ${error.message}`)
+    }
+
+    throw error
+  }
+}
+
+/**
+ * Soft delete multiple orders by ID (updates status to CANCELED)
+ *
+ * @param ids Array of order IDs to soft delete
+ * @returns Number of orders soft deleted
+ */
+export async function bulkSoftDelete(ids: number[]): Promise<number> {
+  if (!ids.length)
+    return 0
+
+  try {
+    // Update the status to CANCELED instead of deleting
+    const result = await db
+      .updateTable('orders')
+      .set({ status: 'CANCELED' })
+      .where('id', 'in', ids)
+      .executeTakeFirst()
+
+    // Return the number of updated rows
+    return Number(result.numUpdatedRows)
+  }
+  catch (error) {
+    if (error instanceof Error) {
+      throw new TypeError(`Failed to soft delete orders: ${error.message}`)
+    }
+
+    throw error
+  }
+}

package/src/orders/events.ts

@@ -0,0 +1,121 @@
+/**
+ * Commerce → events bus integration (stacksjs/stacks#1879 Co-18).
+ *
+ * Background: orders moved through created → paid → shipped →
+ * delivered states with no `events.dispatch(...)` calls. Every
+ * downstream service (email confirmation, inventory replenishment,
+ * analytics, fraud detection) had to poll the orders table because
+ * there was no subscription path. The framework's event bus from
+ * `@stacksjs/events` has been ready since #1878 — commerce just
+ * wasn't wired into it.
+ *
+ * This module wraps the dispatch calls so they:
+ *   - Lazy-import the events package so commerce stays usable in
+ *     environments that don't load it (CLI scripts, migrations)
+ *   - Silently no-op when the events package isn't installed
+ *   - Use a structured payload shape callers can subscribe with type safety
+ *   - Never throw — emission failures shouldn't abort the order write
+ *
+ * Status-transition guard (stacksjs/stacks#1879 Co-4) lives here
+ * too so the rules are co-located with the events they trigger.
+ */
+
+export type OrderStatus = 'PENDING' | 'PROCESSING' | 'SHIPPED' | 'DELIVERED' | 'CANCELLED' | 'REFUNDED'
+
+/**
+ * Whitelisted state transitions. Forward-only progressions and
+ * branch-to-cancel/refund from any non-terminal state. SHIPPED →
+ * PENDING and similar nonsense are rejected.
+ *
+ * REFUNDED and DELIVERED are terminal — nothing transitions out
+ * of them. CANCELLED can be re-entered (rare admin recovery), so
+ * we allow CANCELLED → PROCESSING but not the other terminals.
+ */
+const TRANSITIONS: Record<OrderStatus, OrderStatus[]> = {
+  PENDING: ['PROCESSING', 'CANCELLED'],
+  PROCESSING: ['SHIPPED', 'CANCELLED', 'REFUNDED'],
+  SHIPPED: ['DELIVERED', 'REFUNDED'],
+  DELIVERED: ['REFUNDED'], // post-delivery refund is the only legal exit
+  CANCELLED: ['PROCESSING'], // admin recovery — rare but supported
+  REFUNDED: [], // terminal
+}
+
+/**
+ * Check whether `from → to` is a legal status transition
+ * (stacksjs/stacks#1879 Co-4). Use in `updateStatus` to reject
+ * illegal jumps like SHIPPED → PENDING before they hit the database.
+ */
+export function canTransition(from: OrderStatus, to: OrderStatus): boolean {
+  if (from === to) return true // no-op
+  return TRANSITIONS[from]?.includes(to) ?? false
+}
+
+/**
+ * Best-effort event dispatch. Catches the lazy-import miss (events
+ * package not installed) and any per-listener throw — order writes
+ * MUST NOT depend on the events bus's health.
+ */
+async function emitOrderEvent(eventName: string, payload: Record<string, unknown>): Promise<void> {
+  try {
+    const mod = await import('@stacksjs/events').catch(() => null)
+    if (!mod) return
+    const dispatch = (mod as { dispatch?: (t: string, p: unknown) => void }).dispatch
+    if (typeof dispatch !== 'function') return
+    dispatch(eventName, payload)
+  }
+  catch {
+    // Swallow — the events bus is a notification side-channel, not
+    // the source of truth. A listener that throws shouldn't be able
+    // to abort an order write. The events package itself logs handler
+    // errors via #1876 O-2 / #1878 E-1 paths.
+  }
+}
+
+/** Emit `order:created` after a successful placeOrder / store call. */
+export async function emitOrderCreated(order: Record<string, unknown>): Promise<void> {
+  await emitOrderEvent('order:created', { order })
+}
+
+/** Emit `order:paid` after payment confirmation lands. */
+export async function emitOrderPaid(order: Record<string, unknown>, payment?: Record<string, unknown>): Promise<void> {
+  await emitOrderEvent('order:paid', { order, payment })
+}
+
+/** Emit `order:shipped` after fulfillment marks the order shipped. */
+export async function emitOrderShipped(order: Record<string, unknown>): Promise<void> {
+  await emitOrderEvent('order:shipped', { order })
+}
+
+/** Emit `order:delivered` after the carrier confirms delivery. */
+export async function emitOrderDelivered(order: Record<string, unknown>): Promise<void> {
+  await emitOrderEvent('order:delivered', { order })
+}
+
+/** Emit `order:cancelled` on cancellation (pre- or post-payment). */
+export async function emitOrderCancelled(order: Record<string, unknown>, reason?: string): Promise<void> {
+  await emitOrderEvent('order:cancelled', { order, reason })
+}
+
+/** Emit `order:refunded` after a refund settles. */
+export async function emitOrderRefunded(order: Record<string, unknown>, refundAmount?: number): Promise<void> {
+  await emitOrderEvent('order:refunded', { order, refundAmount })
+}
+
+/**
+ * Convenience dispatch keyed by status. Used from `updateStatus`
+ * so a single function fires the right event for whichever status
+ * we just transitioned into.
+ */
+export async function emitForStatus(status: OrderStatus, order: Record<string, unknown>): Promise<void> {
+  switch (status) {
+    case 'PROCESSING': return emitOrderPaid(order)
+    case 'SHIPPED': return emitOrderShipped(order)
+    case 'DELIVERED': return emitOrderDelivered(order)
+    case 'CANCELLED': return emitOrderCancelled(order)
+    case 'REFUNDED': return emitOrderRefunded(order)
+    // PENDING fires no event — the initial state is already covered
+    // by `order:created` from the placeOrder path.
+    case 'PENDING':
+    default:
+  }
+}

package/src/orders/export.ts

@@ -0,0 +1,158 @@
+import type { SpreadsheetWrapper } from 'ts-spreadsheets'
+import type { OrderWithTotals } from '../types'
+import { db } from '@stacksjs/database'
+import { createSpreadsheet } from 'ts-spreadsheets'
+
+/**
+ * Represents the structure of an exported order
+ */
+export interface ExportedOrder {
+  'Order ID': number
+  'Customer': string
+  'Date': string
+  'Total': number
+  'Status': string
+  'Items': string
+}
+
+/**
+ * Export orders to a spreadsheet
+ * @param format The format of the spreadsheet (default is CSV)
+ * @returns Spreadsheet object ready for download or storage
+ */
+export async function exportOrders(format: 'csv' | 'excel' = 'csv'): Promise<SpreadsheetWrapper> {
+  // Fetch all orders with their details
+  const orders = await fetchAllWithDetails()
+
+  // Prepare data for spreadsheet
+  const spreadsheetData = prepareOrdersForExport(orders)
+
+  // Create and return spreadsheet
+  return createSpreadsheet(spreadsheetData, { type: format })
+}
+
+/**
+ * Fetch all orders with customer names and order items
+ */
+async function fetchAllWithDetails(): Promise<OrderWithTotals[] | []> {
+  const ordersWithCustomers = await db
+    .selectFrom('orders')
+    .leftJoin('customers', 'customers.id', '=', 'orders.customer_id')
+    .selectAll()
+    .select(['customers.name as customer_name', 'customers.email as customer_email'])
+    .execute()
+
+  const orderIds = ordersWithCustomers.map((order: any) => order.id)
+
+  if (orderIds.length === 0) {
+    return []
+  }
+
+  // Fetch order items related only to the fetched orders
+  const allOrderItems = await db
+    .selectFrom('order_items')
+    .where('order_items.order_id', 'in', orderIds)
+    .select([
+      'order_items.order_id',
+      'order_items.quantity',
+      'order_items.price',
+    ])
+    .execute()
+
+  const orderItemsMap = allOrderItems.reduce(
+    (acc: any, item: any) => {
+      if (!item.order_id)
+        return acc // Skip items without order_id
+
+      if (!acc[item.order_id]) {
+        acc[item.order_id] = {
+          totalItems: 0,
+          totalPrice: 0,
+        }
+      }
+
+      acc[item.order_id].totalItems += item.quantity
+      acc[item.order_id].totalPrice += item.price * item.quantity
+
+      return acc
+    },
+    {},
+  )
+
+  const enrichedOrders = ordersWithCustomers.map((order: any) => {
+    const orderItemData = orderItemsMap[order.id] || { totalItems: 0, totalPrice: 0 }
+
+    return {
+      ...order,
+      totalItems: orderItemData.totalItems,
+      totalPrice: orderItemData.totalPrice,
+    }
+  })
+
+  return enrichedOrders as OrderWithTotals[]
+}
+
+/**
+ * Prepare orders data for spreadsheet export
+ * @param orders Array of order objects
+ * @returns Spreadsheet data structure
+ */
+function prepareOrdersForExport(orders: OrderWithTotals[]) {
+  // Define headings
+  const headings: (keyof ExportedOrder)[] = [
+    'Order ID',
+    'Customer',
+    'Date',
+    'Total',
+    'Status',
+    'Items',
+  ]
+
+  // Transform orders into export format
+  const data = orders.map((order: any) => {
+    // Convert items to a readable string
+    const itemsString = order.order_items
+      ?.map((item: any) => `${item.product?.name} (Qty: ${item.quantity}, Price: $${item.price})`)
+      .join(' | ') || 'No Items'
+
+    return [
+      order.id,
+      order.customer?.name || 'N/A',
+      order.created_at,
+      order.total_amount,
+      order.status,
+      itemsString,
+    ]
+  })
+
+  return { headings, data }
+}
+
+/**
+ * Export orders and automatically download
+ * @param format The format of the spreadsheet (default is CSV)
+ * @param filename Optional filename for the download
+ * @returns Download response
+ */
+export async function downloadOrders(format: 'csv' | 'excel' = 'csv', filename?: string): Promise<Response> {
+  const spreadsheet = await exportOrders(format)
+
+  // Use default filename if not provided
+  const defaultFilename = `orders_export_${new Date().toISOString().split('T')[0]}.${format}`
+  return spreadsheet.download(filename || defaultFilename)
+}
+
+/**
+ * Store orders export to disk
+ * @param format The format of the spreadsheet (default is CSV)
+ * @param path Optional path to store the file
+ * @returns Path where the file is stored
+ */
+export async function storeOrdersExport(format: 'csv' | 'excel' = 'csv', path?: string): Promise<void> {
+  const spreadsheet = await exportOrders(format)
+
+  // Use default path and filename if not provided
+  const defaultPath = `orders_export_${new Date().toISOString().split('T')[0]}.${format}`
+
+  spreadsheet.store(path || defaultPath)
+}