@unifiedcommerce/core 0.1.0 → 0.2.0

package/src/modules/orders/service.ts

@@ -1,619 +0,0 @@
-import { resolveOrgId } from "../../auth/org.js";
-import { assertOwnership, assertPermission } from "../../auth/permissions.js";
-import type { Actor } from "../../auth/types.js";
-import {
-  CommerceInvalidTransitionError,
-  CommerceNotFoundError,
-  CommerceValidationError,
-  toCommerceError,
-} from "../../kernel/errors.js";
-import { runAfterHooks, runBeforeHooks } from "../../kernel/hooks/executor.js";
-import { createHookContext } from "../../kernel/hooks/create-context.js";
-import type {
-  AfterHook,
-  BeforeHook,
-  HookContext,
-} from "../../kernel/hooks/types.js";
-import type { HookRegistry } from "../../kernel/hooks/registry.js";
-import {
-  canTransition,
-  orderStateMachine,
-  type OrderState,
-  type StateDefinition,
-} from "../../kernel/state-machine/machine.js";
-import { Err, Ok, type Result } from "../../kernel/result.js";
-import { createLogger } from "../../utils/logger.js";
-import { paginate, type Pagination } from "../../utils/pagination.js";
-import type { TxContext } from "../../kernel/database/tx-context.js";
-import type { PluginDb } from "../../kernel/database/plugin-types.js";
-import {
-  OrdersRepository,
-  type Order,
-  type OrderLineItem,
-  type OrderStatusHistory,
-} from "./repository/index.js";
-
-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

@@ -1,76 +0,0 @@
-import { eq, and, lt, sql } from "drizzle-orm";
-import { orders } from "./schema.js";
-import type { TaskDefinition, TaskContext } from "../../kernel/jobs/types.js";
-
-/**
- * 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,
-      },
-    };
-  },
-};