@stacksjs/commerce 0.70.55 → 0.70.57

package/src/orders/fetch.ts

@@ -1,379 +0,0 @@
-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

@@ -1,261 +0,0 @@
-/**
- * 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 }
-    }
-  }
-}