@stacksjs/commerce 0.70.45 → 0.70.54

package/dist/src/coupons/index.d.ts

@@ -1,3 +1,4 @@
+export type { CouponRedemptionResult } from './update';
 export {
   deleteCoupon,
   deleteCoupons,
@@ -21,5 +22,6 @@ export {
   store,
 } from './store';
 export {
+  redeem,
   update,
 } from './update';

package/dist/src/coupons/update.d.ts

@@ -6,5 +6,41 @@
  * @returns The updated coupon record
  */
 export declare function update(id: number, data: Omit<CouponUpdate, 'id'>): Promise<CouponJsonResponse | undefined>;
+/**
+ * Atomically redeem a coupon (stacksjs/stacks#1879 Co-5).
+ *
+ * Pre-fix: callers fetched the coupon, checked `usage_count <
+ * max_uses`, then bumped `usage_count` via `update()`. Two concurrent
+ * redemption requests against a coupon with `max_uses=1` both saw
+ * `usage_count=0`, both incremented, both succeeded. The coupon
+ * was redeemed twice — direct revenue loss equal to `discount_value`
+ * times the over-redemption count.
+ *
+ * Post-fix: single conditional UPDATE that bumps `usage_count` and
+ * enforces `max_uses` / `is_active` / expiry in the WHERE clause.
+ * The database guarantees only one writer wins the race. Returns a
+ * discriminated result so callers can surface a useful reason
+ * ("limit reached" vs "expired" vs "inactive") instead of a generic
+ * failure.
+ *
+ * @example
+ * ```ts
+ * const result = await redeem(couponId)
+ * if (!result.ok) {
+ *   throw new HttpError(400, `Coupon cannot be redeemed: ${result.reason}`)
+ * }
+ * // Use result.coupon — it reflects the post-redemption state.
+ * ```
+ */
+export declare function redeem(id: number): Promise<CouponRedemptionResult>;
 declare type CouponJsonResponse = ModelRow<typeof Coupon>;
 declare type CouponUpdate = UpdateModelData<typeof Coupon>;
+/**
+ * Discriminated result for `redeem` — `ok: true` on a successful
+ * atomic redemption (the row's `usage_count` was bumped and the
+ * limit wasn't already hit); `ok: false` with a `reason` when the
+ * redemption failed (out of uses, expired, inactive, missing).
+ * Callers branch on `reason` to surface a useful error to the user.
+ */
+export type CouponRedemptionResult = | { ok: true, coupon: CouponJsonResponse }
+  | { ok: false, reason: 'not-found' | 'inactive' | 'expired' | 'limit-reached' }

package/dist/src/gift-cards/update.d.ts

@@ -7,7 +7,19 @@
  */
 export declare function update(id: number, data: Omit<GiftCardUpdate, 'id'>): Promise<GiftCardJsonResponse | undefined>;
 /**
- * Update a gift card's balance
+ * Update a gift card's balance atomically (stacksjs/stacks#1879 Co-8).
+ *
+ * Pre-fix: read balance → compute new → write. Two parallel $50
+ * redemptions of a $100 card both saw `current_balance = 100`,
+ * both wrote `50`, leaving `50` instead of `0`. The post-read
+ * negative-balance guard only caught single-threaded misuse.
+ *
+ * Post-fix: single conditional UPDATE that does the arithmetic and
+ * enforces every precondition in the WHERE clause. The database
+ * guarantees only one writer wins the race. Throws when the row
+ * was found but the precondition failed (insufficient balance,
+ * inactive, missing) so the caller can distinguish from a
+ * not-found row.
  *
  * @param id The ID of the gift card
  * @param amount The amount to adjust (positive to add, negative to deduct)

package/dist/src/orders/events.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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 declare function canTransition(from: OrderStatus, to: OrderStatus): boolean;
+/** Emit `order:created` after a successful placeOrder / store call. */
+export declare function emitOrderCreated(order: Record<string, unknown>): Promise<void>;
+/** Emit `order:paid` after payment confirmation lands. */
+export declare function emitOrderPaid(order: Record<string, unknown>, payment?: Record<string, unknown>): Promise<void>;
+/** Emit `order:shipped` after fulfillment marks the order shipped. */
+export declare function emitOrderShipped(order: Record<string, unknown>): Promise<void>;
+/** Emit `order:delivered` after the carrier confirms delivery. */
+export declare function emitOrderDelivered(order: Record<string, unknown>): Promise<void>;
+/** Emit `order:cancelled` on cancellation (pre- or post-payment). */
+export declare function emitOrderCancelled(order: Record<string, unknown>, reason?: string): Promise<void>;
+/** Emit `order:refunded` after a refund settles. */
+export declare function emitOrderRefunded(order: Record<string, unknown>, refundAmount?: number): Promise<void>;
+/**
+ * Convenience dispatch keyed by status. Used from `updateStatus`
+ * so a single function fires the right event for whichever status
+ * we just transitioned into.
+ */
+export declare function emitForStatus(status: OrderStatus, order: Record<string, unknown>): Promise<void>;
+/**
+ * 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';

package/dist/src/orders/guards.d.ts

@@ -0,0 +1,93 @@
+/**
+ * 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/src/orders/index.d.ts

@@ -1,3 +1,17 @@
+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,
@@ -20,8 +34,49 @@ export {
 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/src/orders/place-order.d.ts

@@ -0,0 +1,18 @@
+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/src/orders/totals.d.ts

@@ -0,0 +1,24 @@
+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/src/orders/update.d.ts

@@ -1,3 +1,4 @@
+import type { OrderStatus } from './events';
 /**
  * Update an order by ID
  *
@@ -13,7 +14,7 @@ export declare function update(id: number, data: Omit<OrderUpdate, 'id'>): Promi
  * @param status The new order status
  * @returns The updated order with the new status
  */
-export declare function updateStatus(id: number, status: 'PENDING' | 'PROCESSING' | 'SHIPPED' | 'DELIVERED' | 'CANCELLED' | 'REFUNDED'): Promise<OrderJsonResponse | undefined>;
+export declare function updateStatus(id: number, status: OrderStatus): Promise<OrderJsonResponse | undefined>;
 /**
  * Update delivery information for an order
  *

package/dist/src/orders/webhook.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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/src/products/items/update.d.ts

@@ -33,6 +33,34 @@ export declare function updateAvailability(id: number, isAvailable: boolean): Pr
  * semantics for admin tooling.
  */
 export declare function adjustInventory(id: number, delta: number): Promise<ProductJsonResponse | null>;
+/**
+ * Atomic batch inventory adjustment (stacksjs/stacks#1879 Co-2).
+ *
+ * Pre-fix: a multi-item cart called `adjustInventory(id, delta)` N
+ * times sequentially. If item 2 failed (out of stock), item 1's
+ * decrement was already committed with no rollback — the order
+ * persisted with partial stock reservation and the customer saw
+ * a refund-on-next-page-load surprise.
+ *
+ * Post-fix: wraps the per-item loop in `db.transaction`. Any item
+ * that can't be adjusted (the existing `adjustInventory` returns
+ * null on insufficient stock) throws inside the transaction; the
+ * driver rolls every prior decrement back. Returns a discriminated
+ * result so the cart handler can surface "item X was out of stock"
+ * specifically instead of a generic transaction-failed error.
+ *
+ * @example
+ * ```ts
+ * const result = await adjustInventoryMany([
+ *   { id: cart.itemA, delta: -2 },
+ *   { id: cart.itemB, delta: -1 },
+ * ])
+ * if (!result.ok) {
+ *   throw new HttpError(409, `Item ${result.productId} is out of stock`)
+ * }
+ * ```
+ */
+export declare function adjustInventoryMany(updates: ReadonlyArray<{ id: number, delta: number }>): Promise<InventoryBatchResult>;
 /**
  * Update inventory information for a product item
  *
@@ -43,3 +71,12 @@ export declare function adjustInventory(id: number, delta: number): Promise<Prod
 export declare function updateInventory(id: number, inventoryCount?: number): Promise<ProductJsonResponse | undefined>;
 declare type ProductJsonResponse = ModelRow<typeof Product>;
 declare type ProductUpdate = UpdateModelData<typeof Product>;
+/**
+ * Discriminated result for `adjustInventoryMany` — `ok: true` when
+ * every per-item adjustment succeeded; `ok: false` with `failedAt`
+ * (the index in the input array that triggered the rollback) when
+ * any single item couldn't be adjusted (out of stock, missing,
+ * etc.). All adjustments roll back as a unit on failure.
+ */
+export type InventoryBatchResult = | { ok: true, products: ProductJsonResponse[] }
+  | { ok: false, failedAt: number, productId: number, reason: 'out-of-stock' | 'not-found' }

package/dist/src/shippings/shipping-rates/fetch.d.ts

@@ -14,13 +14,63 @@ export declare function fetchAll(): Promise<ShippingRateJsonResponse[]>;
  */
 export declare function getRatesByZone(zoneId: number): Promise<ShippingRateJsonResponse[]>;
 /**
- * Get shipping rate based on weight and zone
+ * Get shipping rate based on weight and zone.
+ *
+ * **⚠️ Caller-trusted zone (stacksjs/stacks#1879 Co-11).** This
+ * function does NOT verify that the `zoneId` actually serves the
+ * customer's declared address. A user in NYC can pass a Texas
+ * `zoneId` and get cheaper shipping. Use `getRateByWeightAndAddress`
+ * below when the request boundary involves untrusted input — it
+ * resolves the zone server-side from the address.
+ *
+ * Kept for back-compat with internal callers that have already
+ * resolved the zone (admin tooling, scheduled fulfillment jobs).
  *
  * @param weight Weight in the appropriate unit
- * @param zoneId Shipping zone identifier
+ * @param zoneId Shipping zone identifier (caller-trusted)
  * @returns Matching shipping rate or undefined
  */
 export declare function getRateByWeightAndZone(weight: number, zoneId: number): Promise<ShippingRateJsonResponse | undefined>;
+/**
+ * Resolve the canonical shipping zone for a delivery address
+ * (stacksjs/stacks#1879 Co-11). Walks the zones table looking for
+ * the most specific match: postal-code → region → country-only.
+ * Returns null when no zone covers the address.
+ *
+ * The current zones schema stores `countries` as a comma-separated
+ * string (per `getZonesByCountry`'s LIKE-query); we use the same
+ * convention here. Apps with a normalized zone-country join table
+ * can override by replacing this function via the package facade.
+ */
+export declare function resolveZoneForAddress(address: ShippingAddress): Promise<number | null>;
+/**
+ * Safer counterpart to `getRateByWeightAndZone`. Resolves the zone
+ * server-side from the delivery address, then fetches the rate
+ * for that zone. Throws when the address doesn't match any active
+ * zone — caller surfaces "we don't ship to your area" to the user.
+ *
+ * Use this from any HTTP/API boundary where the address is
+ * caller-controlled. Internal callers that already have a verified
+ * zone can stay on `getRateByWeightAndZone`.
+ *
+ * @example
+ * ```ts
+ * const rate = await getRateByWeightAndAddress(2.5, {
+ *   countryCode: 'US',
+ *   region: 'NY',
+ *   postalCode: '10001',
+ * })
+ * if (!rate) throw new HttpError(404, 'No shipping rate for this address')
+ * ```
+ */
+export declare function getRateByWeightAndAddress(weight: number, address: ShippingAddress): Promise<ShippingRateJsonResponse | undefined>;
+/**
+ * Verify that a caller-supplied `zoneId` actually serves the given
+ * address. Returns true when the address resolves to the same zone.
+ * Use when a flow already has a `zoneId` from earlier and just
+ * wants to confirm it wasn't tampered with mid-checkout.
+ */
+export declare function validateZoneMatchesAddress(zoneId: number, address: ShippingAddress): Promise<boolean>;
 /**
  * Format shipping rate options for dropdown menus or selectors
  *
@@ -34,4 +84,15 @@ export declare function formatShippingRateOptions(): Promise<{ id: number, shipp
  * @returns List of shipping rates for the specified method
  */
 export declare function getShippingRatesByMethod(methodId: number): Promise<ShippingRateJsonResponse[]>;
+/**
+ * Shipping address shape used by the safe-by-default lookup helpers
+ * (stacksjs/stacks#1879 Co-11). All fields except `countryCode` are
+ * optional — zone matching tries them in order of specificity
+ * (postal → region → country) and returns the most specific match.
+ */
+export declare interface ShippingAddress {
+  countryCode: string
+  region?: string
+  postalCode?: string
+}
 declare type ShippingRateJsonResponse = ModelRow<typeof ShippingRate>;

package/dist/src/shippings/shipping-rates/index.d.ts

@@ -1,3 +1,4 @@
+export type { ShippingAddress } from './fetch';
 export {
   bulkDestroy,
   destroy,
@@ -9,9 +10,14 @@ export {
   fetchAll,
   fetchById,
   formatShippingRateOptions,
+  // Safe-by-default address-based lookups (stacksjs/stacks#1879 Co-11).
+  // Use these from request handlers where the address is caller-controlled.
+  getRateByWeightAndAddress,
   getRateByWeightAndZone,
   getRatesByZone,
   getShippingRatesByMethod,
+  resolveZoneForAddress,
+  validateZoneMatchesAddress,
 } from './fetch';
 // Functions from store.ts
 export {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/commerce",
   "type": "module",
-  "version": "0.70.45",
+  "version": "0.70.54",
   "description": "Stacks commerce utilities.",
   "author": "Chris Breuer",
   "contributors": [