@porulle/core 0.8.0 → 0.10.0

package/src/modules/orders/service.ts

@@ -10,6 +10,7 @@ import {
 } from "../../kernel/errors.js";
 import { runAfterHooks, runBeforeHooks } from "../../kernel/hooks/executor.js";
 import { createHookContext } from "../../kernel/hooks/create-context.js";
+import type { JobsAdapter } from "../../kernel/jobs/adapter.js";
 import type {
   AfterHook,
   BeforeHook,
@@ -25,7 +26,10 @@ import {
 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 {
+  withTransaction,
+  type TxContext,
+} from "../../kernel/database/tx-context.js";
 import type { DatabaseAdapter } from "../../kernel/database/adapter.js";
 import type { PluginDb } from "../../kernel/database/plugin-types.js";
 import {
@@ -127,6 +131,7 @@ function context(
     tx,
     logger: createLogger("orders"),
     services,
+    ...(services.jobs ? { jobs: services.jobs as JobsAdapter } : {}),
     context: { moduleName: "orders" },
     database: { db: database.db as PluginDb },
   });
@@ -149,11 +154,128 @@ export class OrderService {
     return { ...order, lineItems };
   }
 
+  /**
+   * Resolve every line item's price with org-integrity + price provenance,
+   * mirroring how our forefathers handle this (Vendure: order lines are always
+   * server-priced from the variant; Medusa: an admin override is honored but
+   * flagged `is_custom_price`). Three modes:
+   *   - trusted caller (checkout / POS exchange, already server-priced) → prices honored as-is.
+   *   - actor with `orders:manage` → explicit price honored as a manual override, flagged isCustomPrice.
+   *   - otherwise → price re-derived server-side from the catalog; client prices ignored.
+   * The referenced entity MUST belong to the order's org in every mode.
+   */
+  private async resolveLines(
+    input: CreateOrderInput,
+    actor: Actor | null,
+    trusted: boolean,
+    ctx: TxContext | undefined,
+  ): Promise<Result<Array<CreateOrderInput["lineItems"][number] & { isCustomPrice: boolean }>>> {
+    let canOverride = trusted;
+    if (!canOverride) {
+      try {
+        assertPermission(actor, "orders:manage");
+        canOverride = true;
+      } catch {
+        canOverride = false;
+      }
+    }
+    const catalog = this.deps.services.catalog as {
+      getById(
+        id: string,
+        options: Record<string, unknown>,
+        actor?: Actor | null,
+        ctx?: TxContext,
+      ): Promise<{
+        ok: boolean;
+        value?: { variants?: Array<{ id: string }> };
+      }>;
+    };
+    const pricing = this.deps.services.pricing as {
+      resolve(
+        input: {
+          entityId: string;
+          variantId?: string;
+          currency: string;
+          quantity: number;
+          customerId?: string;
+        },
+        actor?: Actor | null,
+        ctx?: TxContext,
+      ): Promise<{ ok: boolean; value?: { finalAmount: number } }>;
+    };
+    const resolved: Array<
+      CreateOrderInput["lineItems"][number] & { isCustomPrice: boolean }
+    > = [];
+    for (const item of input.lineItems) {
+      // Org-integrity — the referenced entity must belong to this order's org.
+      const owned = await catalog.getById(
+        item.entityId,
+        { includeVariants: item.variantId !== undefined },
+        actor,
+        ctx,
+      );
+      if (!owned.ok) {
+        return Err(
+          new CommerceValidationError(
+            `Line item entity ${item.entityId} does not belong to this organization.`,
+          ),
+        );
+      }
+      if (
+        item.variantId !== undefined &&
+        !owned.value?.variants?.some((variant) => variant.id === item.variantId)
+      ) {
+        return Err(
+          new CommerceValidationError(
+            `Line item variant ${item.variantId} does not belong to entity ${item.entityId}.`,
+          ),
+        );
+      }
+      if (trusted || canOverride) {
+        // Trusted pipeline totals, or a staff manual/negotiated override.
+        resolved.push({ ...item, isCustomPrice: !trusted && canOverride });
+        continue;
+      }
+      // Server-derive the price; the client-supplied unitPrice/totalPrice is ignored.
+      const priced = await pricing.resolve(
+        {
+          entityId: item.entityId,
+          currency: input.currency,
+          quantity: item.quantity,
+          ...(item.variantId ? { variantId: item.variantId } : {}),
+          ...(input.customerId ? { customerId: input.customerId } : {}),
+        },
+        actor,
+        ctx,
+      );
+      if (!priced.ok || !priced.value) {
+        return Err(
+          new CommerceValidationError(`Cannot resolve price for ${item.entityId}.`),
+        );
+      }
+      const unitPrice = priced.value.finalAmount;
+      resolved.push({
+        ...item,
+        unitPrice,
+        totalPrice: unitPrice * item.quantity,
+        isCustomPrice: false,
+      });
+    }
+    return Ok(resolved);
+  }
+
   async create(
     input: CreateOrderInput,
     actor: Actor | null,
     ctx?: TxContext,
+    opts?: { trustedPricing?: boolean; stockPolicy?: "reserve" | "backorder" },
   ): Promise<Result<HydratedOrder>> {
+    if (opts?.stockPolicy === "reserve" && !ctx) {
+      return withTransaction(this.deps.database, { actor }, (txCtx) =>
+        this.create(input, actor, txCtx, opts),
+      );
+    }
+
     try {
       assertPermission(actor, "orders:create");
     } catch (error) {
@@ -196,6 +318,61 @@ export class OrderService {
       }
     }
 
+    // Resolve line prices with org-integrity + provenance (see resolveLines).
+    const trusted = opts?.trustedPricing === true;
+    const resolvedResult = await this.resolveLines(processed, actor, trusted, ctx);
+    if (!resolvedResult.ok) return Err(resolvedResult.error);
+    const resolvedLines = resolvedResult.value;
+
+    // Order totals: trusted callers (checkout / exchange) supply rich totals
+    // (promotions, tax, shipping); otherwise derive from the server-priced lines.
+    const computedSubtotal = trusted
+      ? processed.subtotal
+      : resolvedLines.reduce(
+          (sum, l) => sum + (l.totalPrice ?? l.unitPrice * l.quantity),
+          0,
+        );
+    const computedGrandTotal = trusted
+      ? processed.grandTotal
+      : computedSubtotal +
+        processed.taxTotal +
+        processed.shippingTotal -
+        (processed.discountTotal ?? 0);
+
+    // Stock: order creation does NOT reserve by default. Stock is allocated at
+    // the lifecycle transition to a committed state — checkout reserves in its
+    // own pipeline, mirroring Vendure's StockAllocationStrategy (allocate on
+    // PaymentAuthorized, not on creation). A caller that represents an immediate
+    // committed sale (e.g. a POS exchange) opts in with stockPolicy: "reserve".
+    const stockPolicy = opts?.stockPolicy;
+    if (stockPolicy === "reserve") {
+      const inventory = this.deps.services.inventory as {
+        getAvailable(
+          entityId: string,
+          variantId: string | undefined,
+          ctx?: TxContext,
+          actor?: Actor | null,
+        ): Promise<{ ok: boolean; value?: number }>;
+      };
+      for (const line of resolvedLines) {
+        const avail = await inventory.getAvailable(
+          line.entityId,
+          line.variantId,
+          ctx,
+          actor,
+        );
+        if (!avail.ok || (avail.value ?? 0) < line.quantity) {
+          return Err(
+            new CommerceValidationError(
+              `Insufficient stock for ${line.title ?? line.entityId}. Available: ${
+                avail.ok ? (avail.value ?? 0) : 0
+              }, requested: ${line.quantity}.`,
+            ),
+          );
+        }
+      }
+    }
+
     const orderNumber = await this.repo.getNextOrderNumber(ctx);
 
     let order: Order;
@@ -206,11 +383,11 @@ export class OrderService {
           orderNumber,
           status: "pending",
           currency: processed.currency,
-          subtotal: processed.subtotal,
+          subtotal: computedSubtotal,
           taxTotal: processed.taxTotal,
           shippingTotal: processed.shippingTotal,
           discountTotal: processed.discountTotal ?? 0,
-          grandTotal: processed.grandTotal,
+          grandTotal: computedGrandTotal,
           ...(processed.paymentIntentId != null ? { paymentIntentId: processed.paymentIntentId } : {}),
           ...(processed.paymentMethodId != null ? { paymentMethodId: processed.paymentMethodId } : {}),
           ...(processed.idempotencyKey != null ? { idempotencyKey: processed.idempotencyKey } : {}),
@@ -235,14 +412,15 @@ export class OrderService {
       throw error;
     }
 
-    const lineItemsData = processed.lineItems.map((item) => ({
+    const lineItemsData = resolvedLines.map((item) => ({
       orderId: order.id,
       entityId: item.entityId,
       entityType: item.entityType,
       title: item.title,
       quantity: item.quantity,
       unitPrice: item.unitPrice,
-      totalPrice: item.totalPrice,
+      totalPrice: item.totalPrice ?? item.unitPrice * item.quantity,
+      isCustomPrice: item.isCustomPrice,
       taxAmount: item.taxAmount ?? 0,
       discountAmount: item.discountAmount ?? 0,
       fulfillmentStatus: "unfulfilled" as const,
@@ -253,6 +431,45 @@ export class OrderService {
 
     await this.repo.createLineItems(lineItemsData, ctx);
 
+    // Reserve stock for the resolved lines when the reserve policy is active
+    // (availability was verified above). Trusted callers reserve themselves.
+    if (stockPolicy === "reserve") {
+      const inventory = this.deps.services.inventory as {
+        reserve(
+          input: {
+            entityId: string;
+            quantity: number;
+            orderId: string;
+            variantId?: string;
+          },
+          actor?: Actor | null,
+          ctx?: TxContext,
+        ): Promise<{ ok: boolean; error?: unknown }>;
+      };
+      for (const line of resolvedLines) {
+        const reserved = await inventory.reserve(
+          {
+            entityId: line.entityId,
+            quantity: line.quantity,
+            orderId: order.id,
+            ...(line.variantId ? { variantId: line.variantId } : {}),
+          },
+          actor,
+          ctx,
+        );
+        if (!reserved.ok) {
+          return Err(
+            toCommerceError(
+              reserved.error ??
+                new CommerceValidationError(
+                  `Unable to reserve stock for ${line.title ?? line.entityId}.`,
+                ),
+            ),
+          );
+        }
+      }
+    }
+
     await this.repo.createStatusHistory(
       {
         orderId: order.id,
@@ -518,6 +735,19 @@ export class OrderService {
     const previous = order.status;
     const lineItems = await this.repo.findLineItemsByOrderId(order.id, ctx);
 
+    // R-04: goods must not ship against refunded lines. Reject the fulfilled
+    // transition if any line has been (partially) refunded.
+    if (
+      input.newStatus === "fulfilled" &&
+      lineItems.some((li) => li.refundedQuantity > 0)
+    ) {
+      return Err(
+        new CommerceValidationError(
+          "Cannot fulfill an order that has refunded line items.",
+        ),
+      );
+    }
+
     // VAPT r2 (codex) finding: side effects (inventory release, payment
     // refund, tax void) used to run BEFORE the atomic compare-and-swap on
     // updateStatus. Two parallel cancel/refund requests on the same order
@@ -545,13 +775,17 @@ export class OrderService {
       // 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>;
+            release(
+              input: {
+                entityId: string;
+                variantId?: string;
+                quantity: number;
+                orderId: string;
+                performedBy?: string;
+              },
+              actor?: Actor | null,
+              ctx?: TxContext,
+            ): Promise<Result<void>>;
           }
         | undefined;
 
@@ -561,15 +795,27 @@ export class OrderService {
           // 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 }
-                : {}),
-            });
+            const releaseResult = await inventory.release(
+              {
+                entityId: lineItem.entityId,
+                quantity: lineItem.quantity,
+                orderId: order.id,
+                performedBy: actor?.userId ?? "system",
+                ...(lineItem.variantId != null
+                  ? { variantId: lineItem.variantId }
+                  : {}),
+              },
+              actor,
+              ctx,
+            );
+            if (!releaseResult.ok) {
+              const err = toCommerceError(releaseResult.error);
+              // Tolerate a missing inventory record (nothing to release); surface
+              // any other inventory error. Check the typed code, not the message.
+              if (err.code !== "INVENTORY_RECORD_NOT_FOUND") {
+                return Err(err);
+              }
+            }
           }
         }
       }
@@ -591,19 +837,27 @@ export class OrderService {
           | undefined;
 
         if (payments?.refund) {
-          const maxRefund = Math.min(
-            order.grandTotal,
-            order.amountCaptured ?? order.grandTotal,
+          // R-01: subtract prior gateway refunds (line-level refundLines, and
+          // undone refunds — the gateway was never reversed) so this order-level
+          // refund can't double-pay on top of what has already been refunded.
+          const priorRefunds = await this.repo.findRefundsByOrderId(order.id, ctx);
+          const alreadyRefunded = priorRefunds.reduce((sum, r) => sum + r.amount, 0);
+          const maxRefund = Math.max(
+            0,
+            Math.min(order.grandTotal, order.amountCaptured ?? order.grandTotal) -
+              alreadyRefunded,
           );
           const refundAmount =
             input.refundAmount != null
               ? Math.min(input.refundAmount, maxRefund)
               : maxRefund;
-          await payments.refund(
-            paymentIntentId,
-            refundAmount,
-            input.reason ?? `order_${input.newStatus}`,
-          );
+          if (refundAmount > 0) {
+            await payments.refund(
+              paymentIntentId,
+              refundAmount,
+              input.reason ?? `order_${input.newStatus}`,
+            );
+          }
         }
       }
 
@@ -636,13 +890,17 @@ export class OrderService {
               orderId: string;
               orgId?: string;
             }): Promise<unknown>;
-            release(input: {
-              entityId: string;
-              variantId?: string;
-              quantity: number;
-              orderId: string;
-              performedBy?: string;
-            }): Promise<unknown>;
+            release(
+              input: {
+                entityId: string;
+                variantId?: string;
+                quantity: number;
+                orderId: string;
+                performedBy?: string;
+              },
+              actor?: Actor | null,
+              ctx?: TxContext,
+            ): Promise<Result<void>>;
           }
         | undefined;
 
@@ -661,15 +919,27 @@ export class OrderService {
             });
 
             // 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 }
-                : {}),
-            });
+            const releaseResult = await inventory.release(
+              {
+                entityId: lineItem.entityId,
+                quantity: lineItem.quantity,
+                orderId: order.id,
+                performedBy: actor?.userId ?? "system",
+                ...(lineItem.variantId != null
+                  ? { variantId: lineItem.variantId }
+                  : {}),
+              },
+              actor,
+              ctx,
+            );
+            if (!releaseResult.ok) {
+              const err = toCommerceError(releaseResult.error);
+              // Tolerate a missing inventory record (nothing to release); surface
+              // any other inventory error. Check the typed code, not the message.
+              if (err.code !== "INVENTORY_RECORD_NOT_FOUND") {
+                return Err(err);
+              }
+            }
 
             // Mark line item as fulfilled
             await this.repo.updateLineItem(
@@ -790,6 +1060,26 @@ export class OrderService {
     if (input.lines.length === 0) {
       return Err(new CommerceValidationError("At least one line is required."));
     }
+    // R-02: a terminal order (cancelled / fully refunded) cannot be line-refunded.
+    if (this.machine.terminal.includes(found.order.status)) {
+      return Err(
+        new CommerceValidationError(
+          `Cannot refund an order in terminal status "${found.order.status}".`,
+        ),
+      );
+    }
+    // R-03: a refund moves collected money — reject an unpaid order (otherwise a
+    // "refund" is recorded against funds never taken). "Paid" is either a core
+    // captured payment (checkout: amountCaptured > 0) or the order having left
+    // the initial pending state (e.g. a completed POS/in-store sale). Only a
+    // still-pending, uncaptured order is treated as unpaid.
+    if ((found.order.amountCaptured ?? 0) <= 0 && found.order.status === "pending") {
+      return Err(
+        new CommerceValidationError(
+          "Cannot refund an unpaid order (no captured payment and still pending).",
+        ),
+      );
+    }
 
     const byId = new Map(found.lineItems.map((li) => [li.id, li]));
     const refundLines: Array<{ lineItemId: string; quantity: number; amount: number }> = [];
@@ -841,15 +1131,20 @@ export class OrderService {
         | undefined;
       if (payments?.refund) {
         const priorRefunds = await this.repo.findRefundsByOrderId(orderId, ctx);
-        const alreadyRefunded = priorRefunds
-          .filter((r) => r.status === "completed")
-          .reduce((sum, r) => sum + r.amount, 0);
+        // Gross total incl. UNDONE refunds: undoRefund reverses the local ledger
+        // but not the payment gateway, so that money already left. Counting only
+        // "completed" would let refund → undo → refund re-issue a gateway refund
+        // (F-04 / R-05 / R-07). Capping on gross keeps total payout ≤ captured.
+        const alreadyRefunded = priorRefunds.reduce((sum, r) => sum + r.amount, 0);
         const refundable = Math.max(0, (found.order.amountCaptured ?? 0) - alreadyRefunded);
-        await payments.refund(
-          found.order.paymentIntentId,
-          Math.min(totalAmount, refundable),
-          input.reason ?? "line_refund",
-        );
+        const payAmount = Math.min(totalAmount, refundable);
+        if (payAmount > 0) {
+          await payments.refund(
+            found.order.paymentIntentId,
+            payAmount,
+            input.reason ?? "line_refund",
+          );
+        }
       }
     }
 
@@ -1238,6 +1533,14 @@ export class OrderService {
         "Order payment is fully captured; line items cannot be edited.",
       );
     }
+    // R-06: a checkout order carries a paymentIntentId. If amountCaptured is null
+    // (auth-only capture, or a mock adapter reporting 0), treat it as authorized —
+    // an order with a live payment must not have its lines silently edited/inflated.
+    if (order.paymentIntentId != null && order.amountCaptured == null) {
+      return new CommerceValidationError(
+        "Order has an authorized payment; line items cannot be edited.",
+      );
+    }
     return null;
   }
 
@@ -1304,22 +1607,59 @@ export class OrderService {
     const guard = this.lineItemEditGuard(order);
     if (guard) return Err(guard);
 
+    // Org-integrity + price provenance for the added line (same rules as create):
+    // the entity must belong to the order's org, and the price is server-derived
+    // unless the actor holds `orders:manage` (then honored + flagged isCustomPrice).
+    const resolvedResult = await this.resolveLines(
+      {
+        currency: order.currency,
+        subtotal: 0,
+        taxTotal: 0,
+        shippingTotal: 0,
+        grandTotal: 0,
+        lineItems: [
+          {
+            entityId: input.entityId,
+            entityType: input.entityType,
+            title: input.title,
+            quantity: input.quantity,
+            unitPrice: input.unitPrice,
+            totalPrice: input.totalPrice ?? input.unitPrice * input.quantity,
+            ...(input.variantId !== undefined ? { variantId: input.variantId } : {}),
+            ...(input.sku !== undefined ? { sku: input.sku } : {}),
+            ...(input.taxAmount !== undefined ? { taxAmount: input.taxAmount } : {}),
+            ...(input.discountAmount !== undefined
+              ? { discountAmount: input.discountAmount }
+              : {}),
+            ...(input.metadata !== undefined ? { metadata: input.metadata } : {}),
+          },
+        ],
+        ...(order.customerId ? { customerId: order.customerId } : {}),
+      },
+      actor,
+      false,
+      ctx,
+    );
+    if (!resolvedResult.ok) return Err(resolvedResult.error);
+    const line = resolvedResult.value[0]!;
+
     await this.repo.createLineItems(
       [
         {
           orderId: order.id,
-          entityId: input.entityId,
-          entityType: input.entityType,
-          title: input.title,
-          quantity: input.quantity,
-          unitPrice: input.unitPrice,
-          totalPrice: input.totalPrice ?? input.unitPrice * input.quantity,
-          taxAmount: input.taxAmount ?? 0,
-          discountAmount: input.discountAmount ?? 0,
+          entityId: line.entityId,
+          entityType: line.entityType,
+          title: line.title,
+          quantity: line.quantity,
+          unitPrice: line.unitPrice,
+          totalPrice: line.totalPrice ?? line.unitPrice * line.quantity,
+          isCustomPrice: line.isCustomPrice,
+          taxAmount: line.taxAmount ?? 0,
+          discountAmount: line.discountAmount ?? 0,
           fulfillmentStatus: "unfulfilled",
-          metadata: input.metadata ?? {},
-          ...(input.variantId !== undefined ? { variantId: input.variantId } : {}),
-          ...(input.sku !== undefined ? { sku: input.sku } : {}),
+          metadata: line.metadata ?? {},
+          ...(line.variantId !== undefined ? { variantId: line.variantId } : {}),
+          ...(line.sku !== undefined ? { sku: line.sku } : {}),
         },
       ],
       ctx,