@unifiedcommerce/core 0.0.1

package/src/modules/orders/service.ts

@@ -0,0 +1,619 @@
+import { resolveOrgId } from "../../auth/org";
+import { assertOwnership, assertPermission } from "../../auth/permissions";
+import type { Actor } from "../../auth/types";
+import {
+  CommerceInvalidTransitionError,
+  CommerceNotFoundError,
+  CommerceValidationError,
+  toCommerceError,
+} from "../../kernel/errors";
+import { runAfterHooks, runBeforeHooks } from "../../kernel/hooks/executor";
+import { createHookContext } from "../../kernel/hooks/create-context";
+import type {
+  AfterHook,
+  BeforeHook,
+  HookContext,
+} from "../../kernel/hooks/types";
+import type { HookRegistry } from "../../kernel/hooks/registry";
+import {
+  canTransition,
+  orderStateMachine,
+  type OrderState,
+  type StateDefinition,
+} from "../../kernel/state-machine/machine";
+import { Err, Ok, type Result } from "../../kernel/result";
+import { createLogger } from "../../utils/logger";
+import { paginate, type Pagination } from "../../utils/pagination";
+import type { TxContext } from "../../kernel/database/tx-context";
+import type { PluginDb } from "../../kernel/database/plugin-types";
+import {
+  OrdersRepository,
+  type Order,
+  type OrderLineItem,
+  type OrderStatusHistory,
+} from "./repository";
+
+export interface CreateOrderInput {
+  customerId?: string;
+  currency: string;
+  subtotal: number;
+  taxTotal: number;
+  shippingTotal: number;
+  discountTotal?: number;
+  grandTotal: number;
+  paymentIntentId?: string | undefined;
+  paymentMethodId?: string | undefined;
+  metadata?: Record<string, unknown>;
+  lineItems: Array<{
+    entityId: string;
+    entityType: string;
+    variantId?: string;
+    sku?: string;
+    title: string;
+    quantity: number;
+    unitPrice: number;
+    totalPrice: number;
+    taxAmount?: number;
+    discountAmount?: number;
+    metadata?: Record<string, unknown>;
+  }>;
+}
+
+export interface ListOrdersParams {
+  page?: number;
+  limit?: number;
+  status?: string;
+}
+
+export interface ChangeStatusInput {
+  orderId: string;
+  newStatus: OrderState;
+  reason?: string;
+}
+
+export interface OrderServiceDeps {
+  repository: OrdersRepository;
+  hooks: HookRegistry;
+  services: Record<string, unknown>;
+  /** Custom state machine. If provided, overrides the default order transitions. */
+  stateMachine?: StateDefinition<string>;
+  /** Kernel database reference for hook contexts. Uses PluginDb to avoid circular Kernel import. */
+  kernel?: { database: { db: PluginDb } };
+}
+
+export type HydratedOrder = Order & { lineItems: OrderLineItem[] };
+type OrderListResult = { items: HydratedOrder[]; pagination: Pagination };
+type BeforeCreateOrderHook = BeforeHook<CreateOrderInput>;
+type AfterCreateOrderHook = AfterHook<HydratedOrder>;
+type StatusChangeHookInput = {
+  orderId: string;
+  fromStatus: OrderState;
+  newStatus: OrderState;
+  reason?: string;
+};
+type BeforeStatusChangeHook = BeforeHook<StatusChangeHookInput>;
+type AfterStatusChangeHook = AfterHook<HydratedOrder>;
+
+function context(
+  actor: Actor | null,
+  services: Record<string, unknown>,
+  tx: unknown = null,
+  kernel: { database: { db: PluginDb } } | null = null,
+): HookContext {
+  return createHookContext({
+    actor,
+    tx,
+    logger: createLogger("orders"),
+    services,
+    context: { moduleName: "orders" },
+    ...(kernel != null ? { kernel } : {}),
+  });
+}
+
+export class OrderService {
+  private readonly repo: OrdersRepository;
+  private readonly machine: StateDefinition<string>;
+
+  constructor(private deps: OrderServiceDeps) {
+    this.repo = deps.repository;
+    this.machine = deps.stateMachine ?? orderStateMachine;
+  }
+
+  private async hydrateOrder(
+    order: Order,
+    ctx?: TxContext,
+  ): Promise<HydratedOrder> {
+    const lineItems = await this.repo.findLineItemsByOrderId(order.id, ctx);
+    return { ...order, lineItems };
+  }
+
+  async create(
+    input: CreateOrderInput,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<HydratedOrder>> {
+    try {
+      assertPermission(actor, "orders:create");
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+
+    if (input.lineItems.length === 0) {
+      return Err(
+        new CommerceValidationError("Order requires at least one line item."),
+      );
+    }
+
+    const beforeHooks = this.deps.hooks.resolve(
+      "orders.beforeCreate",
+    ) as BeforeCreateOrderHook[];
+    const afterHooks = this.deps.hooks.resolve(
+      "orders.afterCreate",
+    ) as AfterCreateOrderHook[];
+    const hookCtx = context(actor, this.deps.services, ctx?.tx, this.deps.kernel);
+
+    const processed = await runBeforeHooks(
+      beforeHooks,
+      input,
+      "create",
+      hookCtx,
+    );
+
+    const orderNumber = await this.repo.getNextOrderNumber(ctx);
+    const orgId = resolveOrgId(actor);
+
+    const order = await this.repo.create(
+      {
+        organizationId: orgId,
+        orderNumber,
+        status: "pending",
+        currency: processed.currency,
+        subtotal: processed.subtotal,
+        taxTotal: processed.taxTotal,
+        shippingTotal: processed.shippingTotal,
+        discountTotal: processed.discountTotal ?? 0,
+        grandTotal: processed.grandTotal,
+        ...(processed.paymentIntentId != null ? { paymentIntentId: processed.paymentIntentId } : {}),
+        ...(processed.paymentMethodId != null ? { paymentMethodId: processed.paymentMethodId } : {}),
+        metadata: processed.metadata ?? {},
+        placedAt: new Date(),
+        ...(processed.customerId !== undefined
+          ? { customerId: processed.customerId }
+          : {}),
+      },
+      ctx,
+    );
+
+    const lineItemsData = processed.lineItems.map((item) => ({
+      orderId: order.id,
+      entityId: item.entityId,
+      entityType: item.entityType,
+      title: item.title,
+      quantity: item.quantity,
+      unitPrice: item.unitPrice,
+      totalPrice: item.totalPrice,
+      taxAmount: item.taxAmount ?? 0,
+      discountAmount: item.discountAmount ?? 0,
+      fulfillmentStatus: "unfulfilled" as const,
+      metadata: item.metadata ?? {},
+      ...(item.variantId !== undefined ? { variantId: item.variantId } : {}),
+      ...(item.sku !== undefined ? { sku: item.sku } : {}),
+    }));
+
+    await this.repo.createLineItems(lineItemsData, ctx);
+
+    await this.repo.createStatusHistory(
+      {
+        orderId: order.id,
+        fromStatus: "pending",
+        toStatus: "pending",
+        reason: "order_created",
+        changedBy: actor?.userId ?? "system",
+      },
+      ctx,
+    );
+
+    const hydrated = await this.hydrateOrder(order, ctx);
+    const report = await runAfterHooks(
+      afterHooks,
+      null,
+      hydrated,
+      "create",
+      hookCtx,
+    );
+
+    return Ok(
+      hydrated,
+      report.hasErrors ? { hookErrors: report.errors } : undefined,
+    );
+  }
+
+  async getById(
+    id: string,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<HydratedOrder>> {
+    const orgId = resolveOrgId(actor);
+    const order = await this.repo.findById(orgId, id, ctx);
+    if (!order) return Err(new CommerceNotFoundError("Order not found."));
+
+    try {
+      if (
+        actor?.permissions.includes("orders:read") ||
+        actor?.permissions.includes("*:*")
+      ) {
+        // no-op
+      } else if (actor?.permissions.includes("orders:read:own")) {
+        assertOwnership(actor, order.customerId ?? null);
+      } else {
+        assertPermission(actor, "orders:read");
+      }
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+
+    const hydrated = await this.hydrateOrder(order, ctx);
+
+    // Run afterGet hooks — allows plugins to enrich the order (e.g., vendor fulfillment)
+    const afterGetHooks = this.deps.hooks.resolve(
+      "orders.afterGet",
+    ) as AfterHook<HydratedOrder>[];
+    if (afterGetHooks.length > 0) {
+      const hookCtx = context(actor, this.deps.services, ctx?.tx, this.deps.kernel);
+      await runAfterHooks(afterGetHooks, null, hydrated, "read", hookCtx);
+    }
+
+    return Ok(hydrated);
+  }
+
+  async getByNumber(
+    orderNumber: string,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<HydratedOrder>> {
+    const orgId = resolveOrgId(actor);
+    const order = await this.repo.findByOrderNumber(orgId, orderNumber, ctx);
+    if (!order) return Err(new CommerceNotFoundError("Order not found."));
+    return this.getById(order.id, actor, ctx);
+  }
+
+  async list(
+    params: ListOrdersParams,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<OrderListResult>> {
+    try {
+      assertPermission(actor, "orders:read");
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+
+    const orgId = resolveOrgId(actor);
+    let items: Order[];
+    if (params.status) {
+      items = await this.repo.findByStatus(orgId, params.status, ctx);
+    } else {
+      items = await this.repo.findAll(orgId, undefined, ctx);
+    }
+
+    // Sort by placedAt descending (in-memory, as findAll already sorts)
+    items.sort((a, b) => b.placedAt.getTime() - a.placedAt.getTime());
+
+    const paged = paginate(items, params.page ?? 1, params.limit ?? 20);
+    const hydratedItems = await Promise.all(
+      paged.items.map((order) => this.hydrateOrder(order, ctx)),
+    );
+
+    return Ok({
+      items: hydratedItems,
+      pagination: paged.pagination,
+    });
+  }
+
+  async listByCustomer(
+    customerId: string,
+    params: ListOrdersParams,
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<OrderListResult>> {
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    let items = await this.repo.findByCustomerId(orgId, customerId, ctx);
+
+    if (params.status) {
+      items = items.filter((order) => order.status === params.status);
+    }
+
+    items.sort((a, b) => b.placedAt.getTime() - a.placedAt.getTime());
+    const paged = paginate(items, params.page ?? 1, params.limit ?? 20);
+    const hydratedItems = await Promise.all(
+      paged.items.map((order) => this.hydrateOrder(order, ctx)),
+    );
+
+    return Ok({
+      items: hydratedItems,
+      pagination: paged.pagination,
+    });
+  }
+
+  async changeStatus(
+    input: ChangeStatusInput,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<HydratedOrder>> {
+    const orgId = resolveOrgId(actor);
+    const order = await this.repo.findById(orgId, input.orderId, ctx);
+    if (!order) return Err(new CommerceNotFoundError("Order not found."));
+
+    try {
+      assertPermission(actor, "orders:update");
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+
+    if (
+      !canTransition(
+        this.machine,
+        order.status as OrderState,
+        input.newStatus,
+      )
+    ) {
+      return Err(
+        new CommerceInvalidTransitionError(
+          `Cannot transition from ${order.status} to ${input.newStatus}.`,
+        ),
+      );
+    }
+
+    const beforeHooks = this.deps.hooks.resolve(
+      "orders.beforeStatusChange",
+    ) as BeforeStatusChangeHook[];
+    const afterHooks = this.deps.hooks.resolve(
+      "orders.afterStatusChange",
+    ) as AfterStatusChangeHook[];
+
+    const hookCtx = context(actor, this.deps.services, ctx?.tx, this.deps.kernel);
+    const statusHookInput: StatusChangeHookInput = {
+      orderId: order.id,
+      fromStatus: order.status as OrderState,
+      newStatus: input.newStatus,
+      ...(input.reason !== undefined ? { reason: input.reason } : {}),
+    };
+
+    await runBeforeHooks(beforeHooks, statusHookInput, "statusChange", hookCtx);
+
+    const previous = order.status;
+    const lineItems = await this.repo.findLineItemsByOrderId(order.id, ctx);
+
+    // Handle cancellation and refund side effects
+    if (input.newStatus === "cancelled" || input.newStatus === "refunded") {
+      // 1. Release inventory reservations
+      const inventory = this.deps.services.inventory as
+        | {
+            release(input: {
+              entityId: string;
+              variantId?: string;
+              quantity: number;
+              orderId: string;
+              performedBy?: string;
+            }): Promise<unknown>;
+          }
+        | undefined;
+
+      if (inventory?.release) {
+        for (const lineItem of lineItems) {
+          // Only release inventory for unfulfilled items.
+          // Fulfilled items had their reservation released during the
+          // fulfilled transition — releasing again would double-release.
+          if (lineItem.fulfillmentStatus === "unfulfilled") {
+            await inventory.release({
+              entityId: lineItem.entityId,
+              quantity: lineItem.quantity,
+              orderId: order.id,
+              performedBy: actor?.userId ?? "system",
+              ...(lineItem.variantId != null
+                ? { variantId: lineItem.variantId }
+                : {}),
+            });
+          }
+        }
+      }
+
+      // 2. Refund payment (if captured)
+      const paymentIntentId =
+        (order as Record<string, unknown>).paymentIntentId as string | undefined
+        ?? (order.metadata as Record<string, unknown> | null)?.paymentIntentId as string | undefined;
+
+      if (paymentIntentId) {
+        const payments = this.deps.services.payments as
+          | {
+              refund(
+                paymentId: string,
+                amount: number,
+                reason?: string,
+              ): Promise<unknown>;
+            }
+          | undefined;
+
+        if (payments?.refund) {
+          await payments.refund(
+            paymentIntentId,
+            order.grandTotal,
+            input.reason ?? `order_${input.newStatus}`,
+          );
+        }
+      }
+
+      // 3. Void tax transaction
+      const tax = this.deps.services.tax as
+        | {
+            voidTransaction(input: { transactionId: string }): Promise<unknown>;
+          }
+        | undefined;
+      if (tax?.voidTransaction) {
+        await tax.voidTransaction({ transactionId: order.id });
+      }
+    }
+
+    // Handle fulfillment: deduct on_hand and release reservations.
+    // Items have been shipped — on_hand decreases (stock left the warehouse)
+    // and reservations are cleared (no longer needed).
+    //
+    // Net effect per line item:
+    //   on_hand -= quantity, reserved -= quantity, available unchanged
+    //   Before: on_hand=100, reserved=5, available=95
+    //   After:  on_hand=95,  reserved=0, available=95
+    if (input.newStatus === "fulfilled" || input.newStatus === "partially_fulfilled") {
+      const inventory = this.deps.services.inventory as
+        | {
+            deductForFulfillment(input: {
+              entityId: string;
+              variantId?: string;
+              quantity: number;
+              orderId: string;
+            }): Promise<unknown>;
+            release(input: {
+              entityId: string;
+              variantId?: string;
+              quantity: number;
+              orderId: string;
+              performedBy?: string;
+            }): Promise<unknown>;
+          }
+        | undefined;
+
+      if (inventory) {
+        for (const lineItem of lineItems) {
+          if (lineItem.fulfillmentStatus === "unfulfilled") {
+            // Deduct on_hand (stock physically left warehouse)
+            await inventory.deductForFulfillment({
+              entityId: lineItem.entityId,
+              quantity: lineItem.quantity,
+              orderId: order.id,
+              ...(lineItem.variantId != null
+                ? { variantId: lineItem.variantId }
+                : {}),
+            });
+
+            // Release reservation (no longer needed)
+            await inventory.release({
+              entityId: lineItem.entityId,
+              quantity: lineItem.quantity,
+              orderId: order.id,
+              performedBy: actor?.userId ?? "system",
+              ...(lineItem.variantId != null
+                ? { variantId: lineItem.variantId }
+                : {}),
+            });
+
+            // Mark line item as fulfilled
+            await this.repo.updateLineItem(
+              lineItem.id,
+              { fulfillmentStatus: "fulfilled" },
+              ctx,
+            );
+          }
+        }
+      }
+    }
+
+    // Update order status with atomic guard on current status
+    const updated = await this.repo.updateStatus(
+      order.id,
+      previous,
+      input.newStatus,
+      ctx,
+    );
+    if (!updated) {
+      return Err(new CommerceValidationError(
+        `Order status changed concurrently. Refresh and retry.`,
+      ));
+    }
+
+    await this.repo.createStatusHistory(
+      {
+        orderId: order.id,
+        fromStatus: previous,
+        toStatus: input.newStatus,
+        changedBy: actor?.userId ?? "system",
+        ...(input.reason !== undefined ? { reason: input.reason } : {}),
+      },
+      ctx,
+    );
+
+    // Audit logging is now automatic via audit hooks (RFC-005)
+    // registered in kernel boot — no manual audit.record() needed.
+
+    const hydrated = await this.hydrateOrder(updated, ctx);
+    const report = await runAfterHooks(
+      afterHooks,
+      null,
+      hydrated,
+      "statusChange",
+      hookCtx,
+    );
+
+    return Ok(
+      hydrated,
+      report.hasErrors ? { hookErrors: report.errors } : undefined,
+    );
+  }
+
+  async cancel(
+    orderId: string,
+    actor: Actor | null,
+    reason = "cancelled_by_user",
+    ctx?: TxContext,
+  ): Promise<Result<HydratedOrder>> {
+    return this.changeStatus(
+      { orderId, newStatus: "cancelled", reason },
+      actor,
+      ctx,
+    );
+  }
+
+  async refund(
+    orderId: string,
+    actor: Actor | null,
+    reason = "refunded",
+    ctx?: TxContext,
+  ): Promise<Result<HydratedOrder>> {
+    return this.changeStatus(
+      { orderId, newStatus: "refunded", reason },
+      actor,
+      ctx,
+    );
+  }
+
+  async getStatusHistory(
+    orderId: string,
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<OrderStatusHistory[]>> {
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const order = await this.repo.findById(orgId, orderId, ctx);
+    if (!order) {
+      return Err(new CommerceNotFoundError("Order not found."));
+    }
+
+    const items = await this.repo.findStatusHistoryByOrderId(orderId, ctx);
+    // Sort by changedAt ascending (oldest first)
+    items.sort((a, b) => a.changedAt.getTime() - b.changedAt.getTime());
+
+    return Ok(items);
+  }
+
+  async updateOrder(
+    orderId: string,
+    data: { placedAt?: Date; metadata?: Record<string, unknown> },
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<Order>> {
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const order = await this.repo.findById(orgId, orderId, ctx);
+    if (!order) {
+      return Err(new CommerceNotFoundError("Order not found."));
+    }
+    const updated = await this.repo.update(orderId, data, ctx);
+    return Ok(updated!);
+  }
+}

package/src/modules/orders/stale-order-cleanup.ts

@@ -0,0 +1,76 @@
+import { eq, and, lt, sql } from "drizzle-orm";
+import { orders } from "./schema";
+import type { TaskDefinition, TaskContext } from "../../kernel/jobs/types";
+
+/**
+ * Stale Order Cleanup Task
+ *
+ * Cancels orders stuck in "pending" status for longer than the configured
+ * threshold (default: 48 hours). This releases reserved inventory and
+ * refunds captured payments, preventing phantom stock loss from abandoned
+ * orders.
+ *
+ * Register via config.jobs.tasks:
+ * ```ts
+ * import { staleOrderCleanupTask } from "@unifiedcommerce/core";
+ * defineConfig({
+ *   jobs: {
+ *     tasks: [staleOrderCleanupTask],
+ *     autorun: { enabled: true, intervalMs: 3600_000 }, // hourly
+ *   },
+ * });
+ * ```
+ */
+export const staleOrderCleanupTask: TaskDefinition<
+  { thresholdHours?: number },
+  { cancelledCount: number; orderIds: string[] }
+> = {
+  slug: "orders/stale-cleanup",
+
+  async handler({ input, ctx }) {
+    const thresholdHours = input.thresholdHours ?? 48;
+    const cutoff = new Date(Date.now() - thresholdHours * 60 * 60 * 1000);
+
+    // Find stale pending orders
+    const staleOrders = await ctx.db
+      .select()
+      .from(orders)
+      .where(
+        and(
+          eq(orders.status, "pending"),
+          lt(orders.placedAt, cutoff),
+        ),
+      );
+
+    const cancelledIds: string[] = [];
+
+    // Cancel each stale order via the service (triggers inventory release + payment refund)
+    const orderService = ctx.services.orders as {
+      cancel(orderId: string, actor: null, reason: string): Promise<unknown>;
+    };
+
+    for (const order of staleOrders) {
+      try {
+        await orderService.cancel(
+          order.id,
+          null,
+          `Auto-cancelled: pending for >${thresholdHours}h`,
+        );
+        cancelledIds.push(order.id);
+        ctx.logger.info(`Stale order ${order.orderNumber} auto-cancelled`, {
+          orderId: order.id,
+          placedAt: order.placedAt,
+        });
+      } catch (error) {
+        ctx.logger.error(`Failed to cancel stale order ${order.orderNumber}`, { error });
+      }
+    }
+
+    return {
+      output: {
+        cancelledCount: cancelledIds.length,
+        orderIds: cancelledIds,
+      },
+    };
+  },
+};