@porulle/core 0.6.0 → 0.8.0

package/src/modules/orders/service.ts

@@ -2,6 +2,7 @@ import { resolveOrgId } from "../../auth/org.js";
 import { assertOwnership, assertPermission } from "../../auth/permissions.js";
 import type { Actor } from "../../auth/types.js";
 import {
+  CommerceForbiddenError,
   CommerceInvalidTransitionError,
   CommerceNotFoundError,
   CommerceValidationError,
@@ -31,11 +32,15 @@ import {
   OrdersRepository,
   type Order,
   type OrderLineItem,
+  type OrderNote,
+  type OrderRefund,
   type OrderStatusHistory,
 } from "./repository/index.js";
 
 export interface CreateOrderInput {
   customerId?: string;
+  /** Client-supplied retry key — a repeat create with the same key returns the original order. */
+  idempotencyKey?: string | undefined;
   currency: string;
   subtotal: number;
   taxTotal: number;
@@ -78,6 +83,11 @@ export interface ChangeStatusInput {
   orderId: string;
   newStatus: OrderState;
   reason?: string;
+  /**
+   * Explicit refund amount (minor units) for a `refunded` transition. Clamped
+   * to the captured amount. Omit to refund the full captured amount.
+   */
+  refundAmount?: number;
 }
 
 export interface OrderServiceDeps {
@@ -171,30 +181,59 @@ export class OrderService {
       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,
-    );
+    // Idempotent replay: offline POS queues and network retries re-submit the
+    // same create — return the original order instead of double-creating.
+    if (processed.idempotencyKey) {
+      const existing = await this.repo.findByIdempotencyKey(
+        orgId,
+        processed.idempotencyKey,
+        ctx,
+      );
+      if (existing) {
+        return Ok(await this.hydrateOrder(existing, ctx));
+      }
+    }
+
+    const orderNumber = await this.repo.getNextOrderNumber(ctx);
+
+    let order: Order;
+    try {
+      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 } : {}),
+          ...(processed.idempotencyKey != null ? { idempotencyKey: processed.idempotencyKey } : {}),
+          metadata: processed.metadata ?? {},
+          placedAt: new Date(),
+          ...(processed.customerId !== undefined
+            ? { customerId: processed.customerId }
+            : {}),
+        },
+        ctx,
+      );
+    } catch (error) {
+      // Concurrent replay lost the unique-index race — return the winner.
+      if (processed.idempotencyKey) {
+        const winner = await this.repo.findByIdempotencyKey(
+          orgId,
+          processed.idempotencyKey,
+          ctx,
+        );
+        if (winner) return Ok(await this.hydrateOrder(winner, ctx));
+      }
+      throw error;
+    }
 
     const lineItemsData = processed.lineItems.map((item) => ({
       orderId: order.id,
@@ -289,6 +328,18 @@ export class OrderService {
     return this.getById(order.id, actor, ctx);
   }
 
+  /** Returns the order previously created with this idempotency key, or null. */
+  async getByIdempotencyKey(
+    idempotencyKey: string,
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<HydratedOrder | null>> {
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const order = await this.repo.findByIdempotencyKey(orgId, idempotencyKey, ctx);
+    if (!order) return Ok(null);
+    return Ok(await this.hydrateOrder(order, ctx));
+  }
+
   async list(
     params: ListOrdersParams,
     actor: Actor | null,
@@ -540,10 +591,14 @@ export class OrderService {
           | undefined;
 
         if (payments?.refund) {
-          const refundAmount = Math.min(
+          const maxRefund = Math.min(
             order.grandTotal,
             order.amountCaptured ?? order.grandTotal,
           );
+          const refundAmount =
+            input.refundAmount != null
+              ? Math.min(input.refundAmount, maxRefund)
+              : maxRefund;
           await payments.refund(
             paymentIntentId,
             refundAmount,
@@ -675,14 +730,481 @@ export class OrderService {
     actor: Actor | null,
     reason = "refunded",
     ctx?: TxContext,
+    opts?: { amount?: number },
   ): Promise<Result<HydratedOrder>> {
     return this.changeStatus(
-      { orderId, newStatus: "refunded", reason },
+      {
+        orderId,
+        newStatus: "refunded",
+        reason,
+        ...(opts?.amount != null ? { refundAmount: opts.amount } : {}),
+      },
       actor,
       ctx,
     );
   }
 
+  // ── Line-level refund policy primitives (issue #52) ─────────────────────
+
+  private async refundPolicies(orgId: string, ctx?: TxContext): Promise<{
+    cap: number | null;
+    undoWindowMinutes: number;
+    timezone: string;
+  }> {
+    const settings = this.deps.services.settings as
+      | { read(orgId: string, group: string, ctx?: TxContext): Promise<Record<string, unknown>> }
+      | undefined;
+    const policies = (await settings?.read(orgId, "policies", ctx)) ?? {};
+    const general = (await settings?.read(orgId, "general", ctx)) ?? {};
+    return {
+      cap: typeof policies.refundDailyCap === "number" ? policies.refundDailyCap : null,
+      undoWindowMinutes:
+        typeof policies.refundUndoWindowMinutes === "number"
+          ? policies.refundUndoWindowMinutes
+          : 15,
+      timezone: typeof general.timezone === "string" ? general.timezone : "UTC",
+    };
+  }
+
+  /**
+   * Refunds specific line-item quantities (issue #52). Enforces per-line
+   * refundable quantity (`quantity - refundedQuantity`), the operator's daily
+   * refund cap (`policies.refundDailyCap`, 403 with the cap surfaced), moves
+   * money through the payment adapter when the order has a captured payment,
+   * and records an auditable `order_refunds` ledger row.
+   */
+  async refundLines(
+    orderId: string,
+    input: { lines: Array<{ lineItemId: string; quantity: number }>; reason?: string | undefined },
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<{ order: HydratedOrder; refund: OrderRefund }>> {
+    try {
+      assertPermission(actor, "orders:update");
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+    const orgId = resolveOrgId(actor);
+    const found = await this.repo.findWithLineItems(orgId, orderId, ctx);
+    if (!found) return Err(new CommerceNotFoundError("Order not found."));
+    if (input.lines.length === 0) {
+      return Err(new CommerceValidationError("At least one line is required."));
+    }
+
+    const byId = new Map(found.lineItems.map((li) => [li.id, li]));
+    const refundLines: Array<{ lineItemId: string; quantity: number; amount: number }> = [];
+    for (const line of input.lines) {
+      const lineItem = byId.get(line.lineItemId);
+      if (!lineItem) {
+        return Err(new CommerceNotFoundError(`Line item ${line.lineItemId} not found on this order.`));
+      }
+      if (!Number.isInteger(line.quantity) || line.quantity < 1) {
+        return Err(new CommerceValidationError("Refund quantity must be a positive integer."));
+      }
+      const refundable = lineItem.quantity - lineItem.refundedQuantity;
+      if (line.quantity > refundable) {
+        return Err(
+          new CommerceValidationError(
+            `Line "${lineItem.title}" has ${refundable} refundable unit(s); requested ${line.quantity}.`,
+          ),
+        );
+      }
+      // Effective paid per unit: line total + tax − discount, split evenly.
+      const lineValue = lineItem.totalPrice + lineItem.taxAmount - lineItem.discountAmount;
+      const amount = Math.round((lineValue * line.quantity) / lineItem.quantity);
+      refundLines.push({ lineItemId: lineItem.id, quantity: line.quantity, amount });
+    }
+    const totalAmount = refundLines.reduce((sum, l) => sum + l.amount, 0);
+
+    const performedBy = actor?.userId ?? "system";
+    const policies = await this.refundPolicies(orgId, ctx);
+    if (policies.cap != null) {
+      const usedToday = await this.repo.sumRefundsByOperatorToday(
+        orgId,
+        performedBy,
+        policies.timezone,
+        ctx,
+      );
+      if (usedToday + totalAmount > policies.cap) {
+        return Err(
+          new CommerceForbiddenError(
+            `Daily refund cap exceeded: cap ${policies.cap}, used ${usedToday} today, requested ${totalAmount}.`,
+          ),
+        );
+      }
+    }
+
+    // Move money if a captured payment exists — clamped to what remains.
+    if (found.order.paymentIntentId && (found.order.amountCaptured ?? 0) > 0) {
+      const payments = this.deps.services.payments as
+        | { refund(paymentId: string, amount: number, reason?: string): Promise<unknown> }
+        | 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);
+        const refundable = Math.max(0, (found.order.amountCaptured ?? 0) - alreadyRefunded);
+        await payments.refund(
+          found.order.paymentIntentId,
+          Math.min(totalAmount, refundable),
+          input.reason ?? "line_refund",
+        );
+      }
+    }
+
+    for (const line of refundLines) {
+      const lineItem = byId.get(line.lineItemId)!;
+      await this.repo.updateLineItem(
+        line.lineItemId,
+        { refundedQuantity: lineItem.refundedQuantity + line.quantity },
+        ctx,
+      );
+    }
+    const refund = await this.repo.createRefund(
+      {
+        organizationId: orgId,
+        orderId,
+        amount: totalAmount,
+        reason: input.reason ?? null,
+        lines: refundLines,
+        performedBy,
+      },
+      ctx,
+    );
+    await this.repo.createStatusHistory(
+      {
+        orderId,
+        fromStatus: found.order.status,
+        toStatus: found.order.status,
+        reason: `refund ${refund.id}: ${totalAmount} (${input.reason ?? "line refund"})`,
+        changedBy: performedBy,
+      },
+      ctx,
+    );
+
+    const hydrated = await this.hydrateOrder(
+      (await this.repo.findById(orgId, orderId, ctx))!,
+      ctx,
+    );
+    return Ok({ order: hydrated, refund });
+  }
+
+  /**
+   * Undoes a refund within the configured window
+   * (`policies.refundUndoWindowMinutes`, default 15). Restores line
+   * refundedQuantity and marks the ledger row `undone` — an audited,
+   * compensating ledger operation; re-collecting the money (cash back into
+   * the drawer) is the operator's side of the exchange.
+   */
+  async undoRefund(
+    orderId: string,
+    refundId: string,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<{ order: HydratedOrder; refund: OrderRefund }>> {
+    try {
+      assertPermission(actor, "orders:update");
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+    const orgId = resolveOrgId(actor);
+    const refund = await this.repo.findRefundById(orgId, refundId, ctx);
+    if (!refund || refund.orderId !== orderId) {
+      return Err(new CommerceNotFoundError("Refund not found."));
+    }
+    if (refund.status !== "completed") {
+      return Err(new CommerceValidationError("Refund has already been undone."));
+    }
+    const policies = await this.refundPolicies(orgId, ctx);
+    const ageMs = Date.now() - refund.createdAt.getTime();
+    if (ageMs > policies.undoWindowMinutes * 60_000) {
+      return Err(
+        new CommerceValidationError(
+          `Refund undo window (${policies.undoWindowMinutes} minutes) has passed.`,
+        ),
+      );
+    }
+
+    const performedBy = actor?.userId ?? "system";
+    const undone = await this.repo.markRefundUndone(refundId, performedBy, ctx);
+    if (!undone) {
+      return Err(new CommerceValidationError("Refund has already been undone."));
+    }
+    for (const line of refund.lines) {
+      const lineItem = await this.repo.findLineItemById(line.lineItemId, ctx);
+      if (lineItem) {
+        await this.repo.updateLineItem(
+          line.lineItemId,
+          { refundedQuantity: Math.max(0, lineItem.refundedQuantity - line.quantity) },
+          ctx,
+        );
+      }
+    }
+    await this.repo.createStatusHistory(
+      {
+        orderId,
+        fromStatus: "refund_completed",
+        toStatus: "refund_undone",
+        reason: `refund ${refundId} undone (${refund.amount})`,
+        changedBy: performedBy,
+      },
+      ctx,
+    );
+
+    const order = await this.repo.findById(orgId, orderId, ctx);
+    const hydrated = await this.hydrateOrder(order!, ctx);
+    return Ok({ order: hydrated, refund: undone });
+  }
+
+  async listRefunds(
+    orderId: string,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<OrderRefund[]>> {
+    try {
+      assertPermission(actor, "orders:read");
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+    const orgId = resolveOrgId(actor);
+    const order = await this.repo.findById(orgId, orderId, ctx);
+    if (!order) return Err(new CommerceNotFoundError("Order not found."));
+    return Ok(await this.repo.findRefundsByOrderId(orderId, ctx));
+  }
+
+  /** The acting operator's daily refund-cap status (issue #52). */
+  async refundCapStatus(
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<{ cap: number | null; usedToday: number; remaining: number | null }>> {
+    try {
+      assertPermission(actor, "orders:read");
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+    const orgId = resolveOrgId(actor);
+    const policies = await this.refundPolicies(orgId, ctx);
+    const usedToday = await this.repo.sumRefundsByOperatorToday(
+      orgId,
+      actor?.userId ?? "system",
+      policies.timezone,
+      ctx,
+    );
+    return Ok({
+      cap: policies.cap,
+      usedToday,
+      remaining: policies.cap != null ? Math.max(0, policies.cap - usedToday) : null,
+    });
+  }
+
+  // ── Order notes + activity timeline (issue #56) ─────────────────────────
+
+  private async requireOrderAccess(
+    orderId: string,
+    actor: Actor | null,
+    perm: "orders:read" | "orders:update",
+    ctx?: TxContext,
+  ): Promise<Result<Order>> {
+    try {
+      assertPermission(actor, perm);
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+    const orgId = resolveOrgId(actor);
+    const order = await this.repo.findById(orgId, orderId, ctx);
+    if (!order) return Err(new CommerceNotFoundError("Order not found."));
+    return Ok(order);
+  }
+
+  async addNote(
+    orderId: string,
+    input: { body: string; pinned?: boolean | undefined },
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<OrderNote>> {
+    const order = await this.requireOrderAccess(orderId, actor, "orders:update", ctx);
+    if (!order.ok) return order;
+    if (!input.body.trim()) {
+      return Err(new CommerceValidationError("Note body must not be empty."));
+    }
+    const note = await this.repo.createNote(
+      {
+        organizationId: order.value.organizationId,
+        orderId,
+        author: actor?.userId ?? "system",
+        body: input.body,
+        pinned: input.pinned ?? false,
+      },
+      ctx,
+    );
+    return Ok(note);
+  }
+
+  async listNotes(
+    orderId: string,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<OrderNote[]>> {
+    const order = await this.requireOrderAccess(orderId, actor, "orders:read", ctx);
+    if (!order.ok) return order;
+    return Ok(await this.repo.findNotesByOrderId(orderId, ctx));
+  }
+
+  async deleteNote(
+    orderId: string,
+    noteId: string,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<{ deleted: true }>> {
+    const order = await this.requireOrderAccess(orderId, actor, "orders:update", ctx);
+    if (!order.ok) return order;
+    const deleted = await this.repo.deleteNote(order.value.organizationId, orderId, noteId, ctx);
+    if (!deleted) return Err(new CommerceNotFoundError("Note not found."));
+    return Ok({ deleted: true });
+  }
+
+  /**
+   * One merged per-order activity view (issue #56): status history + operator
+   * notes + refund ledger events (both directions), newest first.
+   */
+  async timeline(
+    orderId: string,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<Array<{
+    type: "status" | "note" | "refund";
+    at: Date;
+    actor: string;
+    summary: string;
+    data: Record<string, unknown>;
+  }>>> {
+    const order = await this.requireOrderAccess(orderId, actor, "orders:read", ctx);
+    if (!order.ok) return order;
+
+    const [history, notes, refunds] = await Promise.all([
+      this.repo.findStatusHistoryByOrderId(orderId, ctx),
+      this.repo.findNotesByOrderId(orderId, ctx),
+      this.repo.findRefundsByOrderId(orderId, ctx),
+    ]);
+
+    const events: Array<{
+      type: "status" | "note" | "refund";
+      at: Date;
+      actor: string;
+      summary: string;
+      data: Record<string, unknown>;
+    }> = [];
+
+    for (const entry of history) {
+      events.push({
+        type: "status",
+        at: entry.changedAt,
+        actor: entry.changedBy,
+        summary: `Status ${entry.fromStatus} → ${entry.toStatus}${entry.reason ? ` (${entry.reason})` : ""}`,
+        data: { fromStatus: entry.fromStatus, toStatus: entry.toStatus, reason: entry.reason },
+      });
+    }
+    for (const note of notes) {
+      events.push({
+        type: "note",
+        at: note.createdAt,
+        actor: note.author,
+        summary: note.body,
+        data: { noteId: note.id, pinned: note.pinned },
+      });
+    }
+    for (const refund of refunds) {
+      events.push({
+        type: "refund",
+        at: refund.createdAt,
+        actor: refund.performedBy,
+        summary: `Refund of ${refund.amount}${refund.reason ? ` (${refund.reason})` : ""}`,
+        data: { refundId: refund.id, amount: refund.amount, lines: refund.lines, status: refund.status },
+      });
+      if (refund.status === "undone" && refund.undoneAt) {
+        events.push({
+          type: "refund",
+          at: refund.undoneAt,
+          actor: refund.undoneBy ?? "system",
+          summary: `Refund of ${refund.amount} undone`,
+          data: { refundId: refund.id, amount: refund.amount, undone: true },
+        });
+      }
+    }
+
+    events.sort((a, b) => b.at.getTime() - a.at.getTime());
+    return Ok(events);
+  }
+
+  /**
+   * Capture an authorized payment for an order via the payment adapter and
+   * record the captured amount. Does not transition order status — capture is a
+   * payment operation, not a fulfillment one.
+   */
+  async capture(
+    orderId: string,
+    actor: Actor | null,
+    opts?: { amount?: number },
+    ctx?: TxContext,
+  ): Promise<Result<HydratedOrder>> {
+    const orgId = resolveOrgId(actor);
+    const order = await this.repo.findById(orgId, orderId, ctx);
+    if (!order) return Err(new CommerceNotFoundError("Order not found."));
+
+    try {
+      assertPermission(actor, "orders:update");
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+
+    const paymentIntentId =
+      ((order as Record<string, unknown>).paymentIntentId as string | undefined) ??
+      ((order.metadata as Record<string, unknown> | null)?.paymentIntentId as
+        | string
+        | undefined);
+    if (!paymentIntentId) {
+      return Err(
+        new CommerceValidationError("Order has no authorized payment to capture."),
+      );
+    }
+
+    const payments = this.deps.services.payments as
+      | {
+          capture(
+            paymentIntentId: string,
+            amount?: number,
+            paymentMethodId?: string,
+          ): Promise<{ ok: boolean; value?: { amountCaptured?: number }; error?: unknown }>;
+        }
+      | undefined;
+    if (!payments?.capture) {
+      return Err(
+        new CommerceValidationError("No payment adapter configured for capture."),
+      );
+    }
+
+    const paymentMethodId = (order as Record<string, unknown>).paymentMethodId as
+      | string
+      | undefined;
+    const captureResult = await payments.capture(
+      paymentIntentId,
+      opts?.amount,
+      paymentMethodId,
+    );
+    if (!captureResult.ok) {
+      return Err(toCommerceError(captureResult.error));
+    }
+
+    const amountCaptured =
+      captureResult.value?.amountCaptured ?? opts?.amount ?? order.grandTotal;
+    await this.repo.update(orderId, { amountCaptured }, ctx);
+
+    const refreshed = await this.repo.findById(orgId, orderId, ctx);
+    const hydrated = await this.hydrateOrder(refreshed ?? order, ctx);
+    return Ok(hydrated);
+  }
+
   async getStatusHistory(
     orderId: string,
     actor?: Actor | null,
@@ -701,6 +1223,199 @@ export class OrderService {
     return Ok(items);
   }
 
+  /** Line items may not be edited on terminal or fully-captured orders. */
+  private lineItemEditGuard(order: Order): CommerceValidationError | null {
+    if (this.machine.terminal.includes(order.status)) {
+      return new CommerceValidationError(
+        `Order in terminal status "${order.status}" cannot be edited.`,
+      );
+    }
+    if (
+      order.amountCaptured != null &&
+      order.amountCaptured >= order.grandTotal
+    ) {
+      return new CommerceValidationError(
+        "Order payment is fully captured; line items cannot be edited.",
+      );
+    }
+    return null;
+  }
+
+  /**
+   * Recomputes subtotal/taxTotal/grandTotal from the order's line items
+   * (shippingTotal and order-level discountTotal are preserved), persists
+   * them, and records an audit entry in the status history.
+   */
+  private async recalcOrderTotals(
+    order: Order,
+    actor: Actor | null,
+    reason: string,
+    ctx?: TxContext,
+  ): Promise<HydratedOrder> {
+    const lineItems = await this.repo.findLineItemsByOrderId(order.id, ctx);
+    const subtotal = lineItems.reduce((sum, li) => sum + li.totalPrice, 0);
+    const taxTotal = lineItems.reduce((sum, li) => sum + li.taxAmount, 0);
+    const grandTotal =
+      subtotal + taxTotal + order.shippingTotal - order.discountTotal;
+    const updated = await this.repo.update(
+      order.id,
+      { subtotal, taxTotal, grandTotal },
+      ctx,
+    );
+    await this.repo.createStatusHistory(
+      {
+        orderId: order.id,
+        fromStatus: order.status,
+        toStatus: order.status,
+        reason,
+        changedBy: actor?.userId ?? "system",
+      },
+      ctx,
+    );
+    return { ...(updated ?? order), lineItems };
+  }
+
+  async addLineItem(
+    orderId: string,
+    input: {
+      entityId: string;
+      entityType: string;
+      variantId?: string | undefined;
+      sku?: string | undefined;
+      title: string;
+      quantity: number;
+      unitPrice: number;
+      totalPrice?: number | undefined;
+      taxAmount?: number | undefined;
+      discountAmount?: number | undefined;
+      metadata?: Record<string, unknown> | undefined;
+    },
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<HydratedOrder>> {
+    try {
+      assertPermission(actor, "orders:update");
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+    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 guard = this.lineItemEditGuard(order);
+    if (guard) return Err(guard);
+
+    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,
+          fulfillmentStatus: "unfulfilled",
+          metadata: input.metadata ?? {},
+          ...(input.variantId !== undefined ? { variantId: input.variantId } : {}),
+          ...(input.sku !== undefined ? { sku: input.sku } : {}),
+        },
+      ],
+      ctx,
+    );
+
+    return Ok(await this.recalcOrderTotals(order, actor, "line_item_added", ctx));
+  }
+
+  async updateOrderLineItem(
+    orderId: string,
+    lineItemId: string,
+    patch: { quantity: number },
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<HydratedOrder>> {
+    try {
+      assertPermission(actor, "orders:update");
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+    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 guard = this.lineItemEditGuard(order);
+    if (guard) return Err(guard);
+
+    const line = await this.repo.findLineItemById(lineItemId, ctx);
+    if (!line || line.orderId !== order.id) {
+      return Err(new CommerceNotFoundError("Line item not found on this order."));
+    }
+    if (line.fulfillmentStatus !== "unfulfilled") {
+      return Err(
+        new CommerceValidationError(
+          "Line items with fulfillment progress cannot be adjusted.",
+        ),
+      );
+    }
+    if (patch.quantity < 1) {
+      return Err(new CommerceValidationError("Quantity must be at least 1."));
+    }
+
+    // Scale line totals with the quantity change (tax scales per-unit).
+    const perUnitTax = line.quantity > 0 ? line.taxAmount / line.quantity : 0;
+    await this.repo.updateLineItem(
+      lineItemId,
+      {
+        quantity: patch.quantity,
+        totalPrice: line.unitPrice * patch.quantity,
+        taxAmount: Math.round(perUnitTax * patch.quantity),
+      },
+      ctx,
+    );
+
+    return Ok(await this.recalcOrderTotals(order, actor, "line_item_updated", ctx));
+  }
+
+  async removeLineItem(
+    orderId: string,
+    lineItemId: string,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<HydratedOrder>> {
+    try {
+      assertPermission(actor, "orders:update");
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+    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 guard = this.lineItemEditGuard(order);
+    if (guard) return Err(guard);
+
+    const line = await this.repo.findLineItemById(lineItemId, ctx);
+    if (!line || line.orderId !== order.id) {
+      return Err(new CommerceNotFoundError("Line item not found on this order."));
+    }
+    if (line.fulfillmentStatus !== "unfulfilled") {
+      return Err(
+        new CommerceValidationError(
+          "Line items with fulfillment progress cannot be removed.",
+        ),
+      );
+    }
+    const existing = await this.repo.findLineItemsByOrderId(order.id, ctx);
+    if (existing.length <= 1) {
+      return Err(
+        new CommerceValidationError("An order must keep at least one line item."),
+      );
+    }
+
+    await this.repo.deleteLineItem(lineItemId, ctx);
+
+    return Ok(await this.recalcOrderTotals(order, actor, "line_item_removed", ctx));
+  }
+
   async updateOrder(
     orderId: string,
     data: {