@stacksjs/commerce 0.70.53 → 0.70.55

package/src/orders/fetch.ts

@@ -0,0 +1,379 @@
+type OrderJsonResponse = ModelRow<typeof Order>
+import type {
+  OrderStats,
+  OrderTypeCount,
+  StatusCount,
+} from '../types'
+import type { StacksExpressionBuilder } from '@stacksjs/database'
+import { db } from '@stacksjs/database'
+
+/**
+ * Fetch all orders from the database with their items
+ * @param limit Optional limit on number of orders to fetch
+ */
+export async function fetchAll(limit?: number): Promise<OrderJsonResponse[]> {
+  let query = db
+    .selectFrom('orders')
+    .selectAll()
+    .orderBy('created_at', 'desc')
+
+  if (limit) {
+    query = query.limit(limit)
+  }
+
+  const orders = await query.execute()
+
+  // Fetch items for each order
+  return await Promise.all(orders.map(async (order: OrderJsonResponse) => {
+    const items = await db
+      .selectFrom('order_items')
+      .where('order_id', '=', order.id)
+      .selectAll()
+      .execute()
+
+    return {
+      ...order,
+      items,
+    }
+  }))
+}
+
+/**
+ * Fetch the most recent orders
+ * @param limit Number of recent orders to fetch (default: 10)
+ */
+export async function fetchRecent(limit: number = 10): Promise<OrderJsonResponse[]> {
+  return fetchAll(limit)
+}
+
+/**
+ * Fetch an order by ID
+ */
+export async function fetchById(id: number): Promise<OrderJsonResponse | undefined> {
+  const order = await db
+    .selectFrom('orders')
+    .where('id', '=', id)
+    .selectAll()
+    .executeTakeFirst()
+
+  return order as OrderJsonResponse | undefined
+}
+
+/**
+ * Get order statistics
+ */
+export async function fetchStats(): Promise<OrderStats> {
+  // Total orders
+  const totalOrders = await db
+    .selectFrom('orders')
+    .select(((eb: StacksExpressionBuilder) => eb.fn.count('id').as('count')) as any)
+    .executeTakeFirst() as { count: number } | undefined
+
+  // Orders by status
+  const ordersByStatus = await db
+    .selectFrom('orders')
+    .select(['status', (eb: StacksExpressionBuilder) => eb.fn.count('id').as('count')] as any)
+    .groupBy('status')
+    .execute() as unknown as StatusCount[]
+
+  // Orders by type
+  const ordersByType = await db
+    .selectFrom('orders')
+    .select(['order_type', (eb: StacksExpressionBuilder) => eb.fn.count('id').as('count')] as any)
+    .groupBy('order_type')
+    .execute() as unknown as OrderTypeCount[]
+
+  // Recent orders with their items
+  const recentOrdersRaw = await db
+    .selectFrom('orders')
+    .selectAll()
+    .orderBy('created_at', 'desc')
+    .limit(5)
+    .execute()
+
+  // Fetch items for each recent order
+  const recentOrders = await Promise.all(recentOrdersRaw.map(async (order: OrderJsonResponse) => {
+    const items = await db
+      .selectFrom('order_items')
+      .where('order_id', '=', order.id)
+      .selectAll()
+      .execute()
+
+    return {
+      ...order,
+      items,
+    }
+  }))
+
+  // Total revenue
+  const revenue = await db
+    .selectFrom('orders')
+    .select(((eb: StacksExpressionBuilder) => eb.fn.sum('total_amount').as('total')) as any)
+    .executeTakeFirst() as { total: number } | undefined
+
+  return {
+    total: Number(totalOrders?.count || 0),
+    by_status: ordersByStatus,
+    by_type: ordersByType,
+    recent: recentOrders,
+    revenue: Number(revenue?.total || 0),
+  }
+}
+
+/**
+ * Compare orders between different time periods
+ * @param daysRange Number of days to look back (7, 30, 60, etc.)
+ */
+export async function compareOrdersByPeriod(_daysRange: number = 30): Promise<{
+  current_period: number
+  previous_period: number
+  difference: number
+  percentage_change: number
+  days_range: number
+}> {
+  const today = new Date()
+
+  // Current period (last N days)
+  const currentPeriodStart = new Date(today)
+  currentPeriodStart.setDate(today.getDate() - _daysRange)
+
+  // Previous period (N days before the current period)
+  const previousPeriodEnd = new Date(currentPeriodStart)
+  previousPeriodEnd.setDate(previousPeriodEnd.getDate() - 1)
+
+  const previousPeriodStart = new Date(previousPeriodEnd)
+  previousPeriodStart.setDate(previousPeriodEnd.getDate() - _daysRange)
+
+  // Get orders for current period
+  const currentPeriodOrders = await db
+    .selectFrom('orders')
+    .select(((eb: StacksExpressionBuilder) => eb.fn.count('id').as('count')) as any)
+    .where('created_at', '>=', currentPeriodStart.toISOString())
+    .where('created_at', '<=', today.toISOString())
+    .executeTakeFirst() as { count: number } | undefined
+
+  // Get orders for previous period
+  const previousPeriodOrders = await db
+    .selectFrom('orders')
+    .select(((eb: StacksExpressionBuilder) => eb.fn.count('id').as('count')) as any)
+    .where('created_at', '>=', previousPeriodStart.toISOString())
+    .where('created_at', '<=', previousPeriodEnd.toISOString())
+    .executeTakeFirst() as { count: number } | undefined
+
+  const currentCount = Number(currentPeriodOrders?.count || 0)
+  const previousCount = Number(previousPeriodOrders?.count || 0)
+  const difference = currentCount - previousCount
+
+  // Calculate percentage change, handling division by zero
+  const percentageChange = previousCount !== 0
+    ? (difference / previousCount) * 100
+    : (currentCount > 0 ? 100 : 0)
+
+  return {
+    current_period: currentCount,
+    previous_period: previousCount,
+    difference,
+    percentage_change: percentageChange,
+    days_range: _daysRange,
+  }
+}
+
+/**
+ * Calculate order values and metrics for different time periods
+ * @param daysRange Number of days to look back (7, 30, 60, etc.)
+ */
+export async function calculateOrderMetrics(_daysRange: number = 30): Promise<{
+  current_period: {
+    total_orders: number
+    total_revenue: number
+    average_order_value: number
+    orders_by_status: { status: string, count: number }[]
+    orders_by_type: { order_type: string, count: number }[]
+  }
+  previous_period: {
+    total_orders: number
+    total_revenue: number
+    average_order_value: number
+  }
+  comparison: {
+    orders: {
+      difference: number
+      percentage: number
+      is_increase: boolean
+    }
+    revenue: {
+      difference: number
+      percentage: number
+      is_increase: boolean
+    }
+    average_order_value: {
+      difference: number
+      percentage: number
+      is_increase: boolean
+    }
+  }
+  days_range: number
+}> {
+  const today = new Date()
+
+  // Current period (last N days)
+  const currentPeriodStart = new Date(today)
+  currentPeriodStart.setDate(today.getDate() - _daysRange)
+
+  // Previous period (N days before the current period)
+  const previousPeriodEnd = new Date(currentPeriodStart)
+  previousPeriodEnd.setDate(previousPeriodEnd.getDate() - 1)
+
+  const previousPeriodStart = new Date(previousPeriodEnd)
+  previousPeriodStart.setDate(previousPeriodEnd.getDate() - _daysRange)
+
+  // Get values for current period
+  const currentPeriodValues = await db
+    .selectFrom('orders')
+    .select(((eb: StacksExpressionBuilder) => [
+      eb.fn.count('id').as('total_orders'),
+      eb.fn.sum('total_amount').as('total_revenue'),
+    ]) as any)
+    .where('created_at', '>=', currentPeriodStart.toISOString())
+    .where('created_at', '<=', today.toISOString())
+    .executeTakeFirst() as { total_orders: number, total_revenue: number } | undefined
+
+  // Get values for previous period
+  const previousPeriodValues = await db
+    .selectFrom('orders')
+    .select(((eb: StacksExpressionBuilder) => [
+      eb.fn.count('id').as('total_orders'),
+      eb.fn.sum('total_amount').as('total_revenue'),
+    ]) as any)
+    .where('created_at', '>=', previousPeriodStart.toISOString())
+    .where('created_at', '<=', previousPeriodEnd.toISOString())
+    .executeTakeFirst() as { total_orders: number, total_revenue: number } | undefined
+
+  // Get orders by status for current period
+  const ordersByStatus = await db
+    .selectFrom('orders')
+    .select(['status', (eb: StacksExpressionBuilder) => eb.fn.count('id').as('count')] as any)
+    .where('created_at', '>=', currentPeriodStart.toISOString())
+    .where('created_at', '<=', today.toISOString())
+    .groupBy('status')
+    .execute() as { status: string, count: number }[]
+
+  // Get orders by type for current period
+  const ordersByType = await db
+    .selectFrom('orders')
+    .select(['order_type', (eb: StacksExpressionBuilder) => eb.fn.count('id').as('count')] as any)
+    .where('created_at', '>=', currentPeriodStart.toISOString())
+    .where('created_at', '<=', today.toISOString())
+    .groupBy('order_type')
+    .execute() as { order_type: string, count: number }[]
+
+  // Calculate values for current period
+  const currentTotalOrders = Number(currentPeriodValues?.total_orders || 0)
+  const currentTotalRevenue = Number(currentPeriodValues?.total_revenue || 0)
+  const currentAverageOrderValue = currentTotalOrders > 0
+    ? currentTotalRevenue / currentTotalOrders
+    : 0
+
+  // Calculate values for previous period
+  const previousTotalOrders = Number(previousPeriodValues?.total_orders || 0)
+  const previousTotalRevenue = Number(previousPeriodValues?.total_revenue || 0)
+  const previousAverageOrderValue = previousTotalOrders > 0
+    ? previousTotalRevenue / previousTotalOrders
+    : 0
+
+  // Calculate differences
+  const ordersDifference = currentTotalOrders - previousTotalOrders
+  const revenueDifference = currentTotalRevenue - previousTotalRevenue
+  const aovDifference = currentAverageOrderValue - previousAverageOrderValue
+
+  // Calculate percentage changes
+  const ordersPercentageChange = previousTotalOrders !== 0
+    ? (ordersDifference / previousTotalOrders) * 100
+    : (currentTotalOrders > 0 ? 100 : 0)
+
+  const revenuePercentageChange = previousTotalRevenue !== 0
+    ? (revenueDifference / previousTotalRevenue) * 100
+    : (currentTotalRevenue > 0 ? 100 : 0)
+
+  const aovPercentageChange = previousAverageOrderValue !== 0
+    ? (aovDifference / previousAverageOrderValue) * 100
+    : (currentAverageOrderValue > 0 ? 100 : 0)
+
+  return {
+    current_period: {
+      total_orders: currentTotalOrders,
+      total_revenue: currentTotalRevenue,
+      average_order_value: currentAverageOrderValue,
+      orders_by_status: ordersByStatus.map((item: any) => ({
+        status: item.status,
+        count: Number(item.count),
+      })),
+      orders_by_type: ordersByType.map((item: any) => ({
+        order_type: item.order_type,
+        count: Number(item.count),
+      })),
+    },
+    previous_period: {
+      total_orders: previousTotalOrders,
+      total_revenue: previousTotalRevenue,
+      average_order_value: previousAverageOrderValue,
+    },
+    comparison: {
+      orders: {
+        difference: ordersDifference,
+        percentage: Math.abs(ordersPercentageChange),
+        is_increase: ordersDifference >= 0,
+      },
+      revenue: {
+        difference: revenueDifference,
+        percentage: Math.abs(revenuePercentageChange),
+        is_increase: revenueDifference >= 0,
+      },
+      average_order_value: {
+        difference: aovDifference,
+        percentage: Math.abs(aovPercentageChange),
+        is_increase: aovDifference >= 0,
+      },
+    },
+    days_range: _daysRange,
+  }
+}
+
+/**
+ * Get daily order counts for a time period
+ * @param daysRange Number of days to look back
+ */
+export async function fetchDailyOrderTrends(_daysRange: number = 30): Promise<{
+  date: string
+  order_count: number
+  revenue: number
+}[]> {
+  const today = new Date()
+  const startDate = new Date(today)
+  startDate.setDate(today.getDate() - _daysRange)
+
+  // Query all orders in the range, then aggregate in JS by date
+  const orders = await db
+    .selectFrom('orders')
+    .select(['created_at', 'total_amount'] as any)
+    .where('created_at', '>=', startDate.toISOString())
+    .where('created_at', '<=', today.toISOString())
+    .orderBy('created_at', 'asc')
+    .execute() as { created_at: string, total_amount: number }[]
+
+  // Group by date (YYYY-MM-DD)
+  const dailyMap = new Map<string, { order_count: number, revenue: number }>()
+  for (const order of orders) {
+    const date = (order.created_at || '').split('T')[0] || 'unknown'
+    const entry = dailyMap.get(date) || { order_count: 0, revenue: 0 }
+    entry.order_count++
+    entry.revenue += Number(order.total_amount || 0)
+    dailyMap.set(date, entry)
+  }
+
+  return Array.from(dailyMap.entries()).map(([date, stats]) => ({
+    date,
+    order_count: stats.order_count,
+    revenue: stats.revenue,
+  }))
+}

package/src/orders/guards.ts

@@ -0,0 +1,261 @@
+/**
+ * Order / cart policy guards (stacksjs/stacks#1879 Co-7, Co-14, Co-15).
+ *
+ * Three small helpers that callers pre-flight against the cart
+ * before handing off to `placeOrder`. Kept together because they
+ * all answer the same question: "should this checkout be
+ * allowed to proceed?"
+ */
+
+import type { StacksExpressionBuilder } from '@stacksjs/database'
+import { db } from '@stacksjs/database'
+
+// ============================================================================
+// Co-7: coupon stacking guard
+// ============================================================================
+
+export interface CouponStackingPolicy {
+  /**
+   * Allow multiple coupons on the same order. Default is `false`
+   * (single-coupon-only). Apps that intentionally stack coupons
+   * (e.g. one fixed-amount + one percentage) opt in explicitly.
+   */
+  allowMultiple?: boolean
+  /**
+   * When `allowMultiple: true`, cap the number of stacked coupons.
+   * Default unlimited (no cap). Useful for "up to 2 coupons" or
+   * "BOGO + free-shipping" style rules.
+   */
+  maxStacked?: number
+}
+
+export interface CouponStackingResult {
+  ok: boolean
+  /** Number of coupon ids the caller submitted. */
+  count: number
+  /** Set when the policy rejected the combination. */
+  reason?: 'multiple-not-allowed' | 'exceeds-max-stacked'
+}
+
+/**
+ * Validate that a set of coupon ids satisfies the stacking policy
+ * (stacksjs/stacks#1879 Co-7). Pre-fix there was no enforcement
+ * anywhere — frontend could submit two coupons and double-discount
+ * the order with no signal. Default policy is single-coupon-only;
+ * apps that intentionally support stacking opt in.
+ *
+ * @example
+ * ```ts
+ * const stack = validateCouponStacking(cart.couponIds)
+ * if (!stack.ok)
+ *   throw new HttpError(400, `Coupon stacking violation: ${stack.reason}`)
+ * ```
+ */
+export function validateCouponStacking(
+  couponIds: ReadonlyArray<number>,
+  policy: CouponStackingPolicy = {},
+): CouponStackingResult {
+  const count = couponIds.length
+  if (count <= 1) return { ok: true, count }
+  if (!policy.allowMultiple) {
+    return { ok: false, count, reason: 'multiple-not-allowed' }
+  }
+  const cap = policy.maxStacked ?? Number.POSITIVE_INFINITY
+  if (count > cap) {
+    return { ok: false, count, reason: 'exceeds-max-stacked' }
+  }
+  return { ok: true, count }
+}
+
+// ============================================================================
+// Co-14: min/max order quantity bounds
+// ============================================================================
+
+export interface QuantityBoundsResult {
+  ok: boolean
+  productId: number
+  quantity: number
+  /** Set when the quantity violated a bound. */
+  reason?: 'below-min' | 'above-max' | 'non-positive' | 'product-missing'
+  /** The bound that was violated (when applicable). */
+  bound?: number
+}
+
+/**
+ * Validate that a cart line-item's quantity respects the product's
+ * `min_order_qty` / `max_order_qty` fields
+ * (stacksjs/stacks#1879 Co-14). Looks up the product server-side
+ * so the client can't bypass by lying about the bounds.
+ *
+ * Products without explicit bounds default to "any positive int."
+ * A quantity of 0 or negative always fails — the cart's UI is
+ * responsible for letting users remove items, not for passing
+ * sentinel zeros through the API.
+ */
+export async function validateQuantityBounds(
+  productId: number,
+  quantity: number,
+): Promise<QuantityBoundsResult> {
+  if (!Number.isFinite(quantity) || quantity <= 0)
+    return { ok: false, productId, quantity, reason: 'non-positive' }
+
+  let product: { min_order_qty?: number | null, max_order_qty?: number | null } | undefined
+  try {
+    product = await (db as any)
+      .selectFrom('products')
+      .where('id', '=', productId)
+      .select(['min_order_qty', 'max_order_qty'])
+      .executeTakeFirst()
+  }
+  catch {
+    // Schema doesn't have the columns yet — degrade to "any positive
+    // quantity is fine," matching the pre-fix behavior. Apps that
+    // need bounds enforcement add the columns first.
+    return { ok: true, productId, quantity }
+  }
+
+  if (!product)
+    return { ok: false, productId, quantity, reason: 'product-missing' }
+
+  const min = product.min_order_qty ?? null
+  const max = product.max_order_qty ?? null
+
+  if (min != null && quantity < min)
+    return { ok: false, productId, quantity, reason: 'below-min', bound: min }
+  if (max != null && quantity > max)
+    return { ok: false, productId, quantity, reason: 'above-max', bound: max }
+
+  return { ok: true, productId, quantity }
+}
+
+/**
+ * Batch variant — short-circuits on the first violation so the
+ * caller can surface a single useful "item X has min qty Y"
+ * error rather than a list of every failed line.
+ */
+export async function validateCartQuantities(
+  items: ReadonlyArray<{ productId: number, quantity: number }>,
+): Promise<QuantityBoundsResult> {
+  for (const item of items) {
+    const r = await validateQuantityBounds(item.productId, item.quantity)
+    if (!r.ok) return r
+  }
+  // ok-path uses the last item's id as a placeholder; callers
+  // only branch on `.ok`.
+  const last = items[items.length - 1] ?? { productId: 0, quantity: 0 }
+  return { ok: true, productId: last.productId, quantity: last.quantity }
+}
+
+// ============================================================================
+// Co-15: abandoned cart cleanup
+// ============================================================================
+
+export interface CleanupAbandonedCartsOptions {
+  /**
+   * Delete carts whose `updated_at` is older than this many days.
+   * Default 30. Apps with rolling-window cart-recovery emails set
+   * higher (e.g. 90).
+   */
+  olderThanDays?: number
+  /**
+   * Maximum rows to delete in a single call. Default 1000 — keeps
+   * the delete from holding a long write lock on busy databases.
+   * Apps call repeatedly until `deleted < limit`.
+   */
+  limit?: number
+}
+
+export interface CleanupAbandonedCartsResult {
+  /** Number of cart rows deleted in this call. */
+  deleted: number
+  /** Cutoff timestamp used for the delete (ISO 8601). */
+  cutoffAt: string
+}
+
+/**
+ * Delete carts that have been untouched for more than
+ * `olderThanDays` days (stacksjs/stacks#1879 Co-15). Default 30.
+ * Capped at `limit` rows per call (default 1000) so the delete
+ * doesn't hold a long write lock on a busy database. Returns the
+ * count + cutoff so callers can log or loop.
+ *
+ * Schedule via `@stacksjs/scheduler` (now fully wired since
+ * #1877's scheduler audit closed) to run nightly:
+ *
+ * @example
+ * ```ts
+ * // app/Scheduler.ts
+ * import { cleanupAbandonedCarts } from '@stacksjs/commerce'
+ *
+ * schedule.job(async () => {
+ *   let total = 0
+ *   while (true) {
+ *     const r = await cleanupAbandonedCarts({ olderThanDays: 30, limit: 1000 })
+ *     total += r.deleted
+ *     if (r.deleted < 1000) break
+ *   }
+ *   log.info(`Cleaned up ${total} abandoned carts`)
+ * }).daily().setTimeZone('UTC').withName('CleanupAbandonedCarts')
+ * ```
+ */
+export async function cleanupAbandonedCarts(
+  options: CleanupAbandonedCartsOptions = {},
+): Promise<CleanupAbandonedCartsResult> {
+  const olderThanDays = options.olderThanDays ?? 30
+  const limit = options.limit ?? 1000
+
+  const cutoff = new Date(Date.now() - olderThanDays * 24 * 60 * 60 * 1000)
+  const cutoffAt = cutoff.toISOString().slice(0, 19).replace('T', ' ')
+
+  // The pattern below uses a sub-select to apply the LIMIT because
+  // most SQL drivers don't accept LIMIT on DELETE directly. SQLite
+  // and MySQL both accept the DELETE-from-subselect form; PG needs
+  // a CTE-style alternative. Fall back via try/catch so the helper
+  // works across drivers without driver-detect plumbing.
+  try {
+    const result: any = await (db as any)
+      .deleteFrom('carts')
+      .where('updated_at', '<', cutoffAt)
+      .where('id', 'in', (eb: StacksExpressionBuilder) =>
+        eb.selectFrom('carts')
+          .select('id')
+          .where('updated_at', '<', cutoffAt)
+          .limit(limit),
+      )
+      .execute()
+    const deleted = Number(
+      result?.numDeletedRows
+      ?? result?.[0]?.numDeletedRows
+      ?? result?.affectedRows
+      ?? 0,
+    )
+    return { deleted, cutoffAt }
+  }
+  catch {
+    // Fallback: select-then-delete by id. Slower but driver-portable.
+    try {
+      const rows = await (db as any)
+        .selectFrom('carts')
+        .where('updated_at', '<', cutoffAt)
+        .select(['id'])
+        .limit(limit)
+        .execute() as Array<{ id: number }>
+      if (rows.length === 0) return { deleted: 0, cutoffAt }
+      const ids = rows.map(r => r.id)
+      const result: any = await (db as any)
+        .deleteFrom('carts')
+        .where('id', 'in', ids)
+        .execute()
+      const deleted = Number(
+        result?.numDeletedRows
+        ?? result?.[0]?.numDeletedRows
+        ?? result?.affectedRows
+        ?? rows.length,
+      )
+      return { deleted, cutoffAt }
+    }
+    catch {
+      return { deleted: 0, cutoffAt }
+    }
+  }
+}