@porulle/core 0.7.0 → 0.8.0

package/dist/modules/orders/service.d.ts

@@ -5,9 +5,11 @@ import { type Result } from "../../kernel/result.js";
 import { type Pagination } from "../../utils/pagination.js";
 import type { TxContext } from "../../kernel/database/tx-context.js";
 import type { DatabaseAdapter } from "../../kernel/database/adapter.js";
-import { OrdersRepository, type Order, type OrderLineItem, type OrderStatusHistory } from "./repository/index.js";
+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 +80,8 @@ export declare class OrderService {
     create(input: CreateOrderInput, actor: Actor | null, ctx?: TxContext): Promise<Result<HydratedOrder>>;
     getById(id: string, actor: Actor | null, ctx?: TxContext): Promise<Result<HydratedOrder>>;
     getByNumber(orderNumber: string, actor: Actor | null, ctx?: TxContext): Promise<Result<HydratedOrder>>;
+    /** Returns the order previously created with this idempotency key, or null. */
+    getByIdempotencyKey(idempotencyKey: string, actor?: Actor | null, ctx?: TxContext): Promise<Result<HydratedOrder | null>>;
     list(params: ListOrdersParams, actor: Actor | null, ctx?: TxContext): Promise<Result<OrderListResult>>;
     listByCustomer(customerId: string, params: ListOrdersParams, actor?: Actor | null, ctx?: TxContext): Promise<Result<OrderListResult>>;
     /**
@@ -108,6 +112,62 @@ export declare class OrderService {
     refund(orderId: string, actor: Actor | null, reason?: string, ctx?: TxContext, opts?: {
         amount?: number;
     }): Promise<Result<HydratedOrder>>;
+    private refundPolicies;
+    /**
+     * 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.
+     */
+    refundLines(orderId: string, input: {
+        lines: Array<{
+            lineItemId: string;
+            quantity: number;
+        }>;
+        reason?: string | undefined;
+    }, actor: Actor | null, ctx?: TxContext): Promise<Result<{
+        order: HydratedOrder;
+        refund: OrderRefund;
+    }>>;
+    /**
+     * 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.
+     */
+    undoRefund(orderId: string, refundId: string, actor: Actor | null, ctx?: TxContext): Promise<Result<{
+        order: HydratedOrder;
+        refund: OrderRefund;
+    }>>;
+    listRefunds(orderId: string, actor: Actor | null, ctx?: TxContext): Promise<Result<OrderRefund[]>>;
+    /** The acting operator's daily refund-cap status (issue #52). */
+    refundCapStatus(actor: Actor | null, ctx?: TxContext): Promise<Result<{
+        cap: number | null;
+        usedToday: number;
+        remaining: number | null;
+    }>>;
+    private requireOrderAccess;
+    addNote(orderId: string, input: {
+        body: string;
+        pinned?: boolean | undefined;
+    }, actor: Actor | null, ctx?: TxContext): Promise<Result<OrderNote>>;
+    listNotes(orderId: string, actor: Actor | null, ctx?: TxContext): Promise<Result<OrderNote[]>>;
+    deleteNote(orderId: string, noteId: string, actor: Actor | null, ctx?: TxContext): Promise<Result<{
+        deleted: true;
+    }>>;
+    /**
+     * One merged per-order activity view (issue #56): status history + operator
+     * notes + refund ledger events (both directions), newest first.
+     */
+    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>;
+    }>>>;
     /**
      * Capture an authorized payment for an order via the payment adapter and
      * record the captured amount. Does not transition order status — capture is a
@@ -117,6 +177,31 @@ export declare class OrderService {
         amount?: number;
     }, ctx?: TxContext): Promise<Result<HydratedOrder>>;
     getStatusHistory(orderId: string, actor?: Actor | null, ctx?: TxContext): Promise<Result<OrderStatusHistory[]>>;
+    /** Line items may not be edited on terminal or fully-captured orders. */
+    private lineItemEditGuard;
+    /**
+     * 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 recalcOrderTotals;
+    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>>;
+    updateOrderLineItem(orderId: string, lineItemId: string, patch: {
+        quantity: number;
+    }, actor: Actor | null, ctx?: TxContext): Promise<Result<HydratedOrder>>;
+    removeLineItem(orderId: string, lineItemId: string, actor: Actor | null, ctx?: TxContext): Promise<Result<HydratedOrder>>;
     updateOrder(orderId: string, data: {
         placedAt?: Date;
         metadata?: Record<string, unknown>;

package/dist/modules/orders/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../src/modules/orders/service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../src/modules/orders/service.ts"],"names":[],"mappings":"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"}

package/dist/modules/orders/service.js

@@ -1,6 +1,6 @@
 import { resolveOrgId } from "../../auth/org.js";
 import { assertOwnership, assertPermission } from "../../auth/permissions.js";
-import { CommerceInvalidTransitionError, CommerceNotFoundError, CommerceValidationError, toCommerceError, } from "../../kernel/errors.js";
+import { CommerceForbiddenError, 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 { canTransition, orderStateMachine, } from "../../kernel/state-machine/machine.js";
@@ -44,26 +44,47 @@ export class OrderService {
         const afterHooks = this.deps.hooks.resolve("orders.afterCreate");
         const hookCtx = context(actor, this.deps.services, this.deps.database, ctx?.tx);
         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);
+        // 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;
+        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,
             entityId: item.entityId,
@@ -127,6 +148,14 @@ export class OrderService {
             return Err(new CommerceNotFoundError("Order not found."));
         return this.getById(order.id, actor, ctx);
     }
+    /** Returns the order previously created with this idempotency key, or null. */
+    async getByIdempotencyKey(idempotencyKey, actor, ctx) {
+        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, actor, ctx) {
         try {
             assertPermission(actor, "orders:read");
@@ -360,6 +389,279 @@ export class OrderService {
             ...(opts?.amount != null ? { refundAmount: opts.amount } : {}),
         }, actor, ctx);
     }
+    // ── Line-level refund policy primitives (issue #52) ─────────────────────
+    async refundPolicies(orgId, ctx) {
+        const settings = this.deps.services.settings;
+        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, input, actor, ctx) {
+        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 = [];
+        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;
+            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, refundId, actor, ctx) {
+        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, actor, ctx) {
+        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, ctx) {
+        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) ─────────────────────────
+    async requireOrderAccess(orderId, actor, perm, ctx) {
+        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, input, actor, ctx) {
+        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, actor, ctx) {
+        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, noteId, actor, ctx) {
+        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, actor, ctx) {
+        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 = [];
+        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
@@ -407,6 +709,131 @@ export class OrderService {
         items.sort((a, b) => a.changedAt.getTime() - b.changedAt.getTime());
         return Ok(items);
     }
+    /** Line items may not be edited on terminal or fully-captured orders. */
+    lineItemEditGuard(order) {
+        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.
+     */
+    async recalcOrderTotals(order, actor, reason, ctx) {
+        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, input, actor, ctx) {
+        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, lineItemId, patch, actor, ctx) {
+        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, lineItemId, actor, ctx) {
+        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, data, actor, ctx) {
         const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
         const order = await this.repo.findById(orgId, orderId, ctx);

package/dist/modules/pricing/repository/index.d.ts

@@ -25,6 +25,11 @@ export declare class PricingRepository {
     deletePricesByEntityId(entityId: string, ctx?: TxContext): Promise<void>;
     findModifierById(orgId: string, id: string, ctx?: TxContext): Promise<PriceModifier | undefined>;
     findModifiersByEntityId(orgId: string, entityId: string, ctx?: TxContext): Promise<PriceModifier[]>;
+    findModifiers(orgId: string, filter?: {
+        entityId?: string;
+        currency?: string;
+        activeAt?: Date;
+    }, ctx?: TxContext): Promise<PriceModifier[]>;
     findActiveModifiers(orgId: string, entityId: string, variantId?: string, customerGroupId?: string, currency?: string, quantity?: number, ctx?: TxContext): Promise<PriceModifier[]>;
     createModifier(data: PriceModifierInsert, ctx?: TxContext): Promise<PriceModifier>;
     updateModifier(id: string, data: Partial<Omit<PriceModifierInsert, "id">>, ctx?: TxContext): Promise<PriceModifier | undefined>;