@stacksjs/commerce 0.70.87 → 0.70.88

package/dist/orders/fetch.d.ts

@@ -1,76 +0,0 @@
-import type { OrderStats } from '../types';
-/**
- * Fetch all orders from the database with their items
- * @param limit Optional limit on number of orders to fetch
- */
-export declare function fetchAll(limit?: number): Promise<OrderJsonResponse[]>;
-/**
- * Fetch the most recent orders
- * @param limit Number of recent orders to fetch (default: 10)
- */
-export declare function fetchRecent(limit?: number): Promise<OrderJsonResponse[]>;
-/**
- * Fetch an order by ID
- */
-export declare function fetchById(id: number): Promise<OrderJsonResponse | undefined>;
-/**
- * Get order statistics
- */
-export declare function fetchStats(): Promise<OrderStats>;
-/**
- * Compare orders between different time periods
- * @param daysRange Number of days to look back (7, 30, 60, etc.)
- */
-export declare function compareOrdersByPeriod(_daysRange?: number): Promise<{
-  current_period: number
-  previous_period: number
-  difference: number
-  percentage_change: number
-  days_range: number
-}>;
-/**
- * Calculate order values and metrics for different time periods
- * @param daysRange Number of days to look back (7, 30, 60, etc.)
- */
-export declare function calculateOrderMetrics(_daysRange?: number): 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
-}>;
-/**
- * Get daily order counts for a time period
- * @param daysRange Number of days to look back
- */
-export declare function fetchDailyOrderTrends(_daysRange?: number): Promise<{
-  date: string
-  order_count: number
-  revenue: number
-}[]>;
-declare type OrderJsonResponse = ModelRow<typeof Order>;

package/dist/orders/guards.d.ts

@@ -1,93 +0,0 @@
-/**
- * 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 declare function validateCouponStacking(couponIds: ReadonlyArray<number>, policy?: CouponStackingPolicy): CouponStackingResult;
-/**
- * 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 declare function validateQuantityBounds(productId: number, quantity: number): Promise<QuantityBoundsResult>;
-/**
- * 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 declare function validateCartQuantities(items: ReadonlyArray<{ productId: number, quantity: number }>): Promise<QuantityBoundsResult>;
-/**
- * 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 declare function cleanupAbandonedCarts(options?: CleanupAbandonedCartsOptions): Promise<CleanupAbandonedCartsResult>;
-// ============================================================================
-// Co-7: coupon stacking guard
-// ============================================================================
-export declare interface CouponStackingPolicy {
-  allowMultiple?: boolean
-  maxStacked?: number
-}
-export declare interface CouponStackingResult {
-  ok: boolean
-  count: number
-  reason?: 'multiple-not-allowed' | 'exceeds-max-stacked'
-}
-// ============================================================================
-// Co-14: min/max order quantity bounds
-// ============================================================================
-export declare interface QuantityBoundsResult {
-  ok: boolean
-  productId: number
-  quantity: number
-  reason?: 'below-min' | 'above-max' | 'non-positive' | 'product-missing'
-  bound?: number
-}
-// ============================================================================
-// Co-15: abandoned cart cleanup
-// ============================================================================
-export declare interface CleanupAbandonedCartsOptions {
-  olderThanDays?: number
-  limit?: number
-}
-export declare interface CleanupAbandonedCartsResult {
-  deleted: number
-  cutoffAt: string
-}

package/dist/orders/index.d.ts

@@ -1,82 +0,0 @@
-export type { PlaceOrderInput, PlaceOrderResult } from './place-order';
-export type { OrderStatus } from './events';
-export type {
-  RecomputeLineItem,
-  RecomputeOrderInput,
-  RecomputeOrderResult,
-} from './totals';
-export type {
-  CleanupAbandonedCartsOptions,
-  CleanupAbandonedCartsResult,
-  CouponStackingPolicy,
-  CouponStackingResult,
-  QuantityBoundsResult,
-} from './guards';
-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';
-// 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 {
-  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';
-// 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';

package/dist/orders/place-order.d.ts

@@ -1,18 +0,0 @@
-export declare function placeOrder(input: PlaceOrderInput): Promise<PlaceOrderResult>;
-export declare interface PlaceOrderInput {
-  order: NewOrder
-  payment?: NewPayment
-  inventory?: ReadonlyArray<{ id: number, delta: number }>
-  idempotencyKey?: string
-}
-declare type OrderJsonResponse = ModelRow<typeof Order>;
-declare type NewOrder = NewModelData<typeof Order>;
-declare type PaymentJsonResponse = ModelRow<typeof Payment>;
-declare type NewPayment = NewModelData<typeof Payment>;
-/**
- * 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 }

package/dist/orders/store.d.ts

@@ -1,9 +0,0 @@
-/**
- * Create a new order
- *
- * @param data The order data to store
- * @returns The newly created order record
- */
-export declare function store(data: NewOrder): Promise<OrderJsonResponse | undefined>;
-declare type OrderJsonResponse = ModelRow<typeof Order>;
-declare type NewOrder = NewModelData<typeof Order>;

package/dist/orders/totals.d.ts

@@ -1,24 +0,0 @@
-export declare function recomputeOrderTotals(input: RecomputeOrderInput): Promise<RecomputeOrderResult>;
-export declare interface RecomputeLineItem {
-  productId: number
-  quantity: number
-  unitPriceCents?: number
-}
-export declare interface RecomputeOrderInput {
-  items: ReadonlyArray<RecomputeLineItem>
-  taxRateId?: number
-  shippingCents?: number
-  discountCents?: number
-  clientTotalCents?: number
-  maxDriftCents?: number
-}
-export declare interface RecomputeOrderResult {
-  subtotalCents: number
-  discountCents: number
-  taxCents: number
-  shippingCents: number
-  totalCents: number
-  resolvedItems: Array<{ productId: number, quantity: number, unitPriceCents: number, lineCents: number }>
-  priceChanged: boolean
-  diffCents: number
-}

package/dist/orders/update.d.ts

@@ -1,28 +0,0 @@
-import type { OrderStatus } from './events';
-/**
- * Update an order by ID
- *
- * @param id The ID of the order to update
- * @param data The updated order data
- * @returns The updated order record
- */
-export declare function update(id: number, data: Omit<OrderUpdate, 'id'>): Promise<OrderJsonResponse | undefined>;
-/**
- * Update an order's status
- *
- * @param id The ID of the order
- * @param status The new order status
- * @returns The updated order with the new status
- */
-export declare function updateStatus(id: number, status: OrderStatus): Promise<OrderJsonResponse | undefined>;
-/**
- * Update delivery information for an order
- *
- * @param id The ID of the order
- * @param delivery_address The updated delivery address
- * @param estimated_delivery_time The updated estimated delivery time
- * @returns The updated order
- */
-export declare function updateDeliveryInfo(id: number, delivery_address?: string, estimated_delivery_time?: string): Promise<OrderJsonResponse | undefined>;
-declare type OrderJsonResponse = ModelRow<typeof Order>;
-declare type OrderUpdate = UpdateModelData<typeof Order>;

package/dist/orders/webhook.d.ts

@@ -1,31 +0,0 @@
-/**
- * Handler for `payment_intent.succeeded`. Marks the linked payment
- * row + order row as paid in a single transaction. Idempotent via
- * `recordEventOrSkip`.
- */
-declare function handlePaymentIntentSucceeded(event: { id: string, data: { object: any } }): Promise<void>;
-/**
- * Handler for `payment_intent.payment_failed`. Marks the payment
- * as failed and cancels the linked order. Records the failure
- * reason on the payment row for ops triage.
- */
-declare function handlePaymentIntentFailed(event: { id: string, data: { object: any } }): Promise<void>;
-/**
- * Handler for `charge.refunded`. Marks the order REFUNDED and
- * records the refund amount on the linked payment.
- */
-declare function handleChargeRefunded(event: { id: string, data: { object: any } }): Promise<void>;
-/**
- * Wire commerce's Stripe webhook handlers into the payments
- * package's event router. Call once at boot.
- *
- * Returns an unregister callback for tests that want to swap the
- * handler set between cases.
- */
-export declare function registerCommerceWebhookHandlers(): Promise<() => void>;
-// Export the individual handlers for direct testing.
-export {
-  handleChargeRefunded,
-  handlePaymentIntentFailed,
-  handlePaymentIntentSucceeded,
-};

package/dist/payments/destroy.d.ts

@@ -1,14 +0,0 @@
-/**
- * Delete a payment by ID
- *
- * @param id The ID of the payment to delete
- * @returns True if the payment was deleted, false otherwise
- */
-export declare function destroy(id: number): Promise<boolean>;
-/**
- * Delete multiple payments by ID
- *
- * @param ids Array of order IDs to delete
- * @returns Number of payments deleted
- */
-export declare function bulkDestroy(ids: number[]): Promise<number>;

package/dist/payments/fetch.d.ts

@@ -1,55 +0,0 @@
-export declare function fetchAll(): Promise<PaymentJsonResponse[]>;
-export declare function fetchById(id: number): Promise<PaymentJsonResponse | undefined>;
-/**
- * Fetch payment statistics for a specific time period
- *
- * @param daysRange Number of days to look back (7, 30, 60, etc.)
- */
-export declare function fetchPaymentStats(daysRange?: number): Promise<PaymentStats>;
-/**
- * Fetch payment statistics by payment method
- *
- * @param daysRange Number of days to look back
- */
-export declare function fetchPaymentStatsByMethod(_daysRange?: number): Promise<Record<string, {
-  count: number
-  revenue: number
-  percentage_of_total: number
-}>>;
-/**
- * Fetch monthly payment trends for the last 12 months
- */
-export declare function fetchMonthlyPaymentTrends(): Promise<Array<{
-  month: string
-  year: number
-  transactions: number
-  revenue: number
-  average: number
-}>>;
-/**
- * Payment statistics response interface
- */
-export declare interface PaymentStats {
-  total_transactions: number
-  total_revenue: number
-  average_transaction: number
-  successful_rate: number
-  comparison: {
-    transactions: {
-      difference: number
-      percentage: number
-      is_increase: boolean
-    }
-    revenue: {
-      difference: number
-      percentage: number
-      is_increase: boolean
-    }
-    average: {
-      difference: number
-      percentage: number
-      is_increase: boolean
-    }
-  }
-}
-declare type PaymentJsonResponse = ModelRow<typeof Payment>;

package/dist/payments/index.d.ts

@@ -1,13 +0,0 @@
-export { bulkDestroy, destroy } from './destroy';
-// Fetch operations - from fetch.ts
-export {
-  fetchAll,
-  fetchById,
-  fetchMonthlyPaymentTrends,
-  fetchPaymentStats,
-  fetchPaymentStatsByMethod,
-} from './fetch';
-// Store operations - from store.ts
-export { store } from './store';
-// Update operations - from update.ts
-export { update } from './update';

package/dist/payments/store.d.ts

@@ -1,9 +0,0 @@
-/**
- * Create a new payment
- *
- * @param data The payment data to store
- * @returns The newly created payment record
- */
-export declare function store(data: NewPayment): Promise<PaymentJsonResponse | undefined>;
-declare type PaymentJsonResponse = ModelRow<typeof Payment>;
-declare type NewPayment = NewModelData<typeof Payment>;

package/dist/payments/update.d.ts

@@ -1,18 +0,0 @@
-/**
- * Update a payment by ID.
- *
- * Supports the lifecycle a payment row goes through after creation —
- * status transitions (pending → completed/failed/refunded), refund
- * amount tracking, processor metadata (transaction ID, card brand),
- * and operator notes. The original `amount` is intentionally fillable
- * via this path because partial captures and adjustments can rewrite
- * it before settlement; if your processor never adjusts captured
- * amounts, just don't pass `amount` in `data`.
- *
- * @param id The ID of the payment to update
- * @param data The updated payment data (omit `id`)
- * @returns The updated payment record
- */
-export declare function update(id: number, data: Omit<PaymentUpdate, 'id'>): Promise<PaymentJsonResponse | undefined>;
-declare type PaymentJsonResponse = ModelRow<typeof Payment>;
-declare type PaymentUpdate = UpdateModelData<typeof Payment>;

package/dist/products/categories/destroy.d.ts

@@ -1,30 +0,0 @@
-/**
- * Delete a category by ID
- * @param id The ID of the category to delete
- * @returns A boolean indicating whether the deletion was successful
- */
-export declare function remove(id: number): Promise<boolean>;
-/**
- * Bulk delete multiple categories
- * @param ids Array of category IDs to delete
- * @returns Number of categories successfully deleted
- */
-export declare function bulkRemove(ids: number[]): Promise<number>;
-/**
- * Delete child categories of a parent category
- * @param parentId The ID of the parent category
- * @returns Number of categories deleted
- */
-export declare function removeChildCategories(parentId: string): Promise<number>;
-/**
- * Deactivate a category (set is_active to false)
- * @param id The ID of the category to deactivate
- * @returns A boolean indicating whether the deactivation was successful
- */
-export declare function deactivate(id: number): Promise<boolean>;
-/**
- * Deactivate all child categories of a parent category
- * @param parentId The ID of the parent category
- * @returns Number of categories deactivated
- */
-export declare function deactivateChildCategories(parentId: string): Promise<number>;

package/dist/products/categories/fetch.d.ts

@@ -1,49 +0,0 @@
-import type { CategoryStats } from '../../types';
-/**
- * Fetch all categories from the database
- */
-export declare function fetchAll(): Promise<CategoryJsonResponse[]>;
-/**
- * Fetch a category by ID
- */
-export declare function fetchById(id: number): Promise<CategoryJsonResponse | undefined>;
-/**
- * Fetch a category by name
- */
-export declare function fetchByName(name: string): Promise<CategoryJsonResponse | undefined>;
-/**
- * Fetch active categories (is_active = true)
- */
-export declare function fetchActive(): Promise<CategoryJsonResponse[]>;
-/**
- * Fetch root categories (parent_category_id is null)
- */
-export declare function fetchRootCategories(): Promise<CategoryJsonResponse[]>;
-/**
- * Fetch child categories for a given parent category ID
- */
-export declare function fetchChildCategories(parentId: string): Promise<CategoryJsonResponse[]>;
-/**
- * Fetch categories sorted by display order
- */
-export declare function fetchByDisplayOrder(ascending?: boolean): Promise<CategoryJsonResponse[]>;
-/**
- * Get category statistics
- */
-export declare function fetchStats(): Promise<CategoryStats>;
-/**
- * Compare category growth between different time periods
- * @param daysRange Number of days to look back (7, 30, 60, etc.)
- */
-export declare function compareCategoryGrowth(_daysRange?: number): Promise<{
-  current_period: number
-  previous_period: number
-  difference: number
-  percentage_change: number
-  days_range: number
-}>;
-/**
- * Build category tree structure
- */
-export declare function fetchCategoryTree(): Promise<any[]>;
-declare type CategoryJsonResponse = ModelRow<typeof Category>;

package/dist/products/categories/index.d.ts

@@ -1,33 +0,0 @@
-// Export all functions from destroy.ts
-export {
-  bulkRemove,
-  deactivate,
-  deactivateChildCategories,
-  remove,
-  removeChildCategories,
-} from './destroy';
-// Export all functions from fetch.ts
-export {
-  compareCategoryGrowth,
-  fetchActive,
-  fetchAll,
-  fetchByDisplayOrder,
-  fetchById,
-  fetchByName,
-  fetchCategoryTree,
-  fetchChildCategories,
-  fetchRootCategories,
-  fetchStats,
-} from './fetch';
-// Export all functions from store.ts
-export {
-  findOrCreateByName,
-  store,
-} from './store';
-// Export all functions from update.ts
-export {
-  update,
-  updateActiveStatus,
-  updateDisplayOrder,
-  updateParent,
-} from './update';

package/dist/products/categories/store.d.ts

@@ -1,21 +0,0 @@
-import { slug } from '@stacksjs/strings';
-/**
- * Create a new category
- *
- * @param data The category data to store
- * @returns The newly created category record
- */
-export declare function store(data: NewCategory): Promise<CategoryJsonResponse>;
-export declare function findOrCreateByName(data: Partial<CategorizableTable>): Promise<CategoryJsonResponse>;
-export declare interface CategorizableTable {
-  id: number
-  name: string
-  slug: string
-  description?: string
-  is_active: boolean
-  categorizable_type: string
-  created_at?: string
-  updated_at?: string
-}
-declare type CategoryJsonResponse = ModelRow<typeof Category>;
-declare type NewCategory = NewModelData<typeof Category>;

package/dist/products/categories/update.d.ts

@@ -1,33 +0,0 @@
-/**
- * Update a category by ID
- *
- * @param id The ID of the category to update
- * @param request The updated category data
- * @returns The updated category record
- */
-export declare function update(id: number, request: RequestInstance<typeof Category>): Promise<CategoryRow | undefined>;
-/**
- * Update category display order
- *
- * @param id The ID of the category
- * @param newOrder The new display order value
- * @returns The updated category
- */
-export declare function updateDisplayOrder(id: number, newOrder: number): Promise<CategoryRow | undefined>;
-/**
- * Update category active status
- *
- * @param id The ID of the category
- * @param isActive Whether the category should be active
- * @returns The updated category
- */
-export declare function updateActiveStatus(id: number, isActive: boolean): Promise<CategoryRow | undefined>;
-/**
- * Move category to a different parent
- *
- * @param id The ID of the category to move
- * @param newParentId The ID of the new parent category, or null to make it a root category
- * @returns The updated category
- */
-export declare function updateParent(id: number, newParentId: string | null): Promise<CategoryRow | undefined>;
-declare type CategoryRow = ModelRow<typeof Category>;

package/dist/products/index.d.ts

@@ -1,24 +0,0 @@
-import * as categories from './categories/index';
-import * as items from './items/index';
-import * as manufacturers from './manufacturers/index';
-import * as reviews from './reviews/index';
-import * as units from './units/index';
-import * as variants from './variants/index';
-declare const products: ProductsNamespace;
-declare interface ProductsNamespace {
-  categories: typeof categories
-  items: typeof items
-  manufacturers: typeof manufacturers
-  reviews: typeof reviews
-  units: typeof units
-  variants: typeof variants
-}
-export {
-  categories,
-  items,
-  manufacturers,
-  reviews,
-  units,
-  variants,
-};
-export default products;