@endora-commerce/mod-returns 0.100.0

package/dist/backend/services/return-reason-service.js

@@ -0,0 +1,90 @@
+import { ERROR_CODES } from '@endora-commerce/contracts';
+import { HttpError } from '@endora-commerce/platform/http';
+import { recordAuditFromContext } from '@endora-commerce/platform/commands';
+import { ReturnReason } from '../entities/return-reason.entity.js';
+/**
+ * ReturnReasonService — feature 046 (US7, FR-030).
+ *
+ * Manages the return/complaint reason list. The storefront form reads the active
+ * reasons (optionally filtered by case kind) in `weight` order.
+ */
+export class ReturnReasonService {
+    emFactory;
+    auditLog;
+    constructor(emFactory, auditLog) {
+        this.emFactory = emFactory;
+        this.auditLog = auditLog;
+    }
+    #audit(em, action, objectId, stateBefore, stateAfter) {
+        if (this.auditLog) {
+            recordAuditFromContext(this.auditLog, em, {
+                action,
+                objectType: 'return_reason',
+                objectId,
+                stateBefore,
+                stateAfter,
+            });
+        }
+    }
+    /** All reasons (admin view), ordered by weight. */
+    async listAll() {
+        const em = this.emFactory();
+        const rows = await em.find(ReturnReason, {}, { orderBy: { weight: 'asc' } });
+        return rows.map(toDto);
+    }
+    /** Active reasons for a case kind (storefront), ordered by weight. */
+    async listActive(kind) {
+        const em = this.emFactory();
+        const rows = await em.find(ReturnReason, { isActive: true }, { orderBy: { weight: 'asc' } });
+        const applicable = kind
+            ? rows.filter((r) => r.appliesTo === kind || r.appliesTo === 'both')
+            : rows;
+        return applicable.map(toDto);
+    }
+    async create(input) {
+        const em = this.emFactory();
+        const row = em.create(ReturnReason, {
+            label: input.label,
+            appliesTo: input.appliesTo,
+            isActive: input.isActive ?? true,
+            weight: input.weight ?? 100,
+        });
+        em.persist(row);
+        this.#audit(em, 'return_reason.create', row.id, null, { appliesTo: row.appliesTo, isActive: row.isActive });
+        await em.flush();
+        return toDto(row);
+    }
+    async update(id, patch) {
+        const em = this.emFactory();
+        const row = await em.findOne(ReturnReason, { id });
+        if (!row)
+            throw new HttpError(404, ERROR_CODES.NOT_FOUND, 'Return reason not found.');
+        if (patch.label !== undefined)
+            row.label = patch.label;
+        if (patch.appliesTo !== undefined)
+            row.appliesTo = patch.appliesTo;
+        if (patch.isActive !== undefined)
+            row.isActive = patch.isActive;
+        if (patch.weight !== undefined)
+            row.weight = patch.weight;
+        this.#audit(em, 'return_reason.update', row.id, null, {
+            appliesTo: row.appliesTo,
+            isActive: row.isActive,
+            weight: row.weight,
+        });
+        await em.flush();
+        return toDto(row);
+    }
+    async remove(id) {
+        const em = this.emFactory();
+        const row = await em.findOne(ReturnReason, { id });
+        if (!row)
+            throw new HttpError(404, ERROR_CODES.NOT_FOUND, 'Return reason not found.');
+        this.#audit(em, 'return_reason.delete', row.id, { appliesTo: row.appliesTo }, null);
+        await em.removeAndFlush(row);
+    }
+}
+function toDto(r) {
+    return { id: r.id, label: r.label, appliesTo: r.appliesTo, isActive: r.isActive, weight: r.weight };
+}
+//# sourceMappingURL=return-reason-service.js.map

package/dist/backend/services/return-reason-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"return-reason-service.js","sourceRoot":"","sources":["../../../src/backend/services/return-reason-service.ts"],"names":[],"mappings":"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"}

package/dist/backend/services/return-settlement-service.d.ts

@@ -0,0 +1,67 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+import type { CorrectiveInvoicePort, CreditTopupPort, PaymentRefundPort, SettlementPrefill, SettlementRequest, SettlementResult } from '@endora-commerce/contracts';
+import type { EventBus } from '@endora-commerce/platform/events';
+import type { AuditPort } from '@endora-commerce/platform/kernel';
+import type { ReturnTransitionService } from './return-transition-service.js';
+import type { ReturnStatusGraphService } from './return-status-graph-service.js';
+export interface ReturnSettlementServiceDeps {
+    emFactory: () => EntityManager;
+    events: EventBus;
+    transitions: ReturnTransitionService;
+    graphService: ReturnStatusGraphService;
+    paymentRefund: PaymentRefundPort;
+    correctiveInvoice: CorrectiveInvoicePort;
+    creditTopup: CreditTopupPort;
+    auditLog?: AuditPort;
+}
+/**
+ * ReturnSettlementService — feature 046 (US5).
+ *
+ * Validates per-line refund amounts (never exceeding the paid amount), advances
+ * the case to `resolved`, and orchestrates the financial side-effects through
+ * the documented ports: money refund (payments), store credit (credit_limits),
+ * and the corrective invoice (invoices). Replacement/repair resolutions move no
+ * money.
+ *
+ * **The ordering law (D-91, issue #157). Every external effect is attempted
+ * before any state is written, and the case reaches `resolved` in the same unit
+ * of work as the `Refund` row that records what happened.** In order:
+ *
+ *  1. **Validate** — the graph transition, the refund method, the per-line
+ *     caps. Nothing is assigned and nothing is flushed.
+ *  2. **Attempt every external effect: money, then document.** The gateway
+ *     refund or the store credit, then the corrective invoice. Outcomes are
+ *     held in memory. A refusal here — a `ModuleDisabledError` from a
+ *     switched-off `payments`, `credit_limits` or `invoices`, a gateway
+ *     rejection — propagates, and because nothing has been written the case is
+ *     still `received` and the whole settlement is retryable.
+ *  3. **Build the `Refund` row from those outcomes**, including its
+ *     `settlementState` and its provider details.
+ *  4. **One unit of work** — the item amounts, the `Refund` row, the audit
+ *     entry and the transition to `resolved`, in the transition's single flush.
+ *     Either the case is resolved with a complete record of what happened, or
+ *     it is untouched.
+ *  5. **After commit** — the settled event.
+ *
+ * The gateway arm has followed this since feature 046 ("a PSP rejection must
+ * not leave the RMA looking successfully settled"); the `credit` and
+ * corrective-invoice arms called their ports *after* the case was resolved and
+ * flushed, so a refusal arrived too late to prevent anything and left "case
+ * resolved, refund row absent, money possibly already moved" behind. That is a
+ * fact about the relationship between an irreversible effect and a state
+ * change, not a fact about PSPs — so it holds for a store credit and for a VAT
+ * document, and any arm added later follows it too.
+ *
+ * The retry the law makes reachable is what makes the two non-gateway effects
+ * take a key: `creditFromReturn` applies once per return case and
+ * `createCorrection` takes `idempotencyKey: rc.id`, the same key
+ * `paymentRefund.refund` has always taken.
+ */
+export declare class ReturnSettlementService {
+    private readonly deps;
+    constructor(deps: ReturnSettlementServiceDeps);
+    getPrefill(id: string): Promise<SettlementPrefill>;
+    settle(id: string, adminUserId: string, input: SettlementRequest): Promise<SettlementResult>;
+    private emitSettled;
+}
+//# sourceMappingURL=return-settlement-service.d.ts.map

package/dist/backend/services/return-settlement-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"return-settlement-service.d.ts","sourceRoot":"","sources":["../../../src/backend/services/return-settlement-service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,OAAO,KAAK,EACV,qBAAqB,EACrB,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AACjE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAOlE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAC9E,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAEjF,MAAM,WAAW,2BAA2B;IAC1C,SAAS,EAAE,MAAM,aAAa,CAAC;IAC/B,MAAM,EAAE,QAAQ,CAAC;IACjB,WAAW,EAAE,uBAAuB,CAAC;IACrC,YAAY,EAAE,wBAAwB,CAAC;IACvC,aAAa,EAAE,iBAAiB,CAAC;IACjC,iBAAiB,EAAE,qBAAqB,CAAC;IACzC,WAAW,EAAE,eAAe,CAAC;IAC7B,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,qBAAa,uBAAuB;IACtB,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,2BAA2B;IAExD,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAkBlD,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA8OlG,OAAO,CAAC,WAAW;CAapB"}

package/dist/backend/services/return-settlement-service.js

@@ -0,0 +1,295 @@
+import { randomUUID } from 'crypto';
+import { ERROR_CODES } from '@endora-commerce/contracts';
+import { HttpError } from '@endora-commerce/platform/http';
+import { ReturnCase } from '../entities/return-case.entity.js';
+import { ReturnCaseItem } from '../entities/return-case-item.entity.js';
+import { Refund } from '../entities/refund.entity.js';
+import { RETURN_STATUS_RESOLVED } from '../domain/return-status-graph.js';
+import { exceedsCap, sumApproved } from '../domain/refund-math.js';
+/**
+ * ReturnSettlementService — feature 046 (US5).
+ *
+ * Validates per-line refund amounts (never exceeding the paid amount), advances
+ * the case to `resolved`, and orchestrates the financial side-effects through
+ * the documented ports: money refund (payments), store credit (credit_limits),
+ * and the corrective invoice (invoices). Replacement/repair resolutions move no
+ * money.
+ *
+ * **The ordering law (D-91, issue #157). Every external effect is attempted
+ * before any state is written, and the case reaches `resolved` in the same unit
+ * of work as the `Refund` row that records what happened.** In order:
+ *
+ *  1. **Validate** — the graph transition, the refund method, the per-line
+ *     caps. Nothing is assigned and nothing is flushed.
+ *  2. **Attempt every external effect: money, then document.** The gateway
+ *     refund or the store credit, then the corrective invoice. Outcomes are
+ *     held in memory. A refusal here — a `ModuleDisabledError` from a
+ *     switched-off `payments`, `credit_limits` or `invoices`, a gateway
+ *     rejection — propagates, and because nothing has been written the case is
+ *     still `received` and the whole settlement is retryable.
+ *  3. **Build the `Refund` row from those outcomes**, including its
+ *     `settlementState` and its provider details.
+ *  4. **One unit of work** — the item amounts, the `Refund` row, the audit
+ *     entry and the transition to `resolved`, in the transition's single flush.
+ *     Either the case is resolved with a complete record of what happened, or
+ *     it is untouched.
+ *  5. **After commit** — the settled event.
+ *
+ * The gateway arm has followed this since feature 046 ("a PSP rejection must
+ * not leave the RMA looking successfully settled"); the `credit` and
+ * corrective-invoice arms called their ports *after* the case was resolved and
+ * flushed, so a refusal arrived too late to prevent anything and left "case
+ * resolved, refund row absent, money possibly already moved" behind. That is a
+ * fact about the relationship between an irreversible effect and a state
+ * change, not a fact about PSPs — so it holds for a store credit and for a VAT
+ * document, and any arm added later follows it too.
+ *
+ * The retry the law makes reachable is what makes the two non-gateway effects
+ * take a key: `creditFromReturn` applies once per return case and
+ * `createCorrection` takes `idempotencyKey: rc.id`, the same key
+ * `paymentRefund.refund` has always taken.
+ */
+export class ReturnSettlementService {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async getPrefill(id) {
+        const em = this.deps.emFactory();
+        const rc = await em.findOne(ReturnCase, { id });
+        if (!rc)
+            throw new HttpError(404, ERROR_CODES.NOT_FOUND, 'Return case not found.');
+        const items = await em.find(ReturnCaseItem, { returnCaseId: id });
+        return {
+            currency: rc.currency,
+            resolutionOptions: ['refund', 'credit', 'replacement', 'repair'],
+            items: items.map((it) => ({
+                returnCaseItemId: it.id,
+                productName: it.productName,
+                quantity: it.quantity,
+                defaultRefundAmount: Number(it.defaultRefundAmount),
+                approvedRefundAmount: Number(it.approvedRefundAmount),
+            })),
+        };
+    }
+    async settle(id, adminUserId, input) {
+        const em = this.deps.emFactory();
+        const rc = await em.findOne(ReturnCase, { id });
+        if (!rc)
+            throw new HttpError(404, ERROR_CODES.NOT_FOUND, 'Return case not found.');
+        // Fail fast if the case cannot reach `resolved` before mutating anything.
+        const graph = await this.deps.graphService.loadGraph();
+        if (!graph.canTransition(rc.statusCode, RETURN_STATUS_RESOLVED)) {
+            throw new HttpError(409, ERROR_CODES.INVALID_TRANSITION, `Cannot settle a case in status "${rc.statusCode}".`);
+        }
+        if (input.resolutionType === 'refund' && !input.refundPaymentMethodId) {
+            throw new HttpError(422, ERROR_CODES.VALIDATION_FAILED, 'A refund payment method is required.', {
+                code: 'payment_method_required',
+            });
+        }
+        // Step 1 — validate. The approved amounts are computed into a map and
+        // **not** assigned: an assignment on a managed entity is a write the next
+        // flush carries, and under the ordering law nothing is written until step 4.
+        const items = await em.find(ReturnCaseItem, { returnCaseId: id });
+        const byId = new Map(items.map((it) => [it.id, it]));
+        const approvedByItemId = new Map();
+        const perLine = [];
+        for (const line of input.lines) {
+            const item = byId.get(line.returnCaseItemId);
+            if (!item) {
+                throw new HttpError(422, ERROR_CODES.VALIDATION_FAILED, 'Unknown return line.', {
+                    code: 'unknown_line',
+                });
+            }
+            if (exceedsCap(line.approvedRefundAmount, Number(item.defaultRefundAmount))) {
+                throw new HttpError(422, ERROR_CODES.VALIDATION_FAILED, 'Refund amount cannot exceed the amount paid for the line.', { code: 'refund_exceeds_paid' });
+            }
+            approvedByItemId.set(line.returnCaseItemId, line.approvedRefundAmount);
+            perLine.push(line.approvedRefundAmount);
+        }
+        const total = sumApproved(perLine);
+        const movesMoney = input.resolutionType === 'refund' || input.resolutionType === 'credit';
+        // Step 2 — every external effect, money first, then the document. A refusal
+        // from any of them propagates with the case still in `received` and nothing
+        // written, which is what makes the settlement retryable.
+        let gatewayOutcome = null;
+        let creditApplied = null;
+        let correction = null;
+        if (movesMoney) {
+            if (input.resolutionType === 'refund') {
+                gatewayOutcome = await this.deps.paymentRefund.refund({
+                    orderId: rc.orderId,
+                    amount: total,
+                    currency: rc.currency,
+                    ...(input.refundPaymentMethodId ? { paymentMethodId: input.refundPaymentMethodId } : {}),
+                    idempotencyKey: rc.id,
+                });
+                if (gatewayOutcome.state === 'failed') {
+                    throw new HttpError(502, ERROR_CODES.VALIDATION_FAILED, gatewayOutcome.failureReason ?? 'Payment gateway rejected the refund.', {
+                        code: 'gateway_refund_failed',
+                        settlementState: gatewayOutcome.state,
+                        providerDetails: gatewayOutcome.providerDetails ?? null,
+                    });
+                }
+            }
+            else {
+                // `credit_limits` applies once per return case, so this survives the
+                // retry the law above makes reachable.
+                const credit = rc.organizationId
+                    ? await this.deps.creditTopup.creditFromReturn({
+                        organizationId: rc.organizationId,
+                        amount: total,
+                        currency: rc.currency,
+                        returnCaseId: rc.id,
+                    })
+                    : { applied: false };
+                creditApplied = credit.applied;
+            }
+            if (input.createCorrectiveInvoice ?? true) {
+                correction = await this.deps.correctiveInvoice.createCorrection({
+                    orderId: rc.orderId,
+                    lines: items.map((it) => ({
+                        // The order item is what ties this credit to the invoice line it
+                        // corrects, so the correction can mirror that line's VAT rate.
+                        orderItemId: it.orderItemId,
+                        productName: it.productName,
+                        quantity: it.quantity,
+                        // The approved amount for this settlement, which is not on the row
+                        // yet: the rows are written in step 4.
+                        amount: approvedByItemId.get(it.id) ?? Number(it.approvedRefundAmount),
+                    })),
+                    total,
+                    currency: rc.currency,
+                    // One correction per return case, however often the settlement is
+                    // retried. Not per order: a second partial return against the same
+                    // order is a different case and gets its own document.
+                    idempotencyKey: rc.id,
+                });
+            }
+        }
+        // Step 3 — the outcomes, as the values the row and the response carry.
+        const result = { totalRefundAmount: total };
+        const refundFields = movesMoney
+            ? {
+                returnCaseId: id,
+                resolutionType: (input.resolutionType === 'refund' ? 'refund' : 'credit'),
+                amount: total.toFixed(2),
+                currency: rc.currency,
+                paymentMethodId: input.refundPaymentMethodId ?? null,
+                settlementState: 'pending_manual',
+                externalReference: null,
+                providerDetails: null,
+                failureReason: null,
+                creditLimitTopupApplied: false,
+                correctiveInvoiceId: null,
+                // D-92 — the three-way answer on the row, so it survives a page
+                // reload. `not_requested` is the default because the caller can
+                // switch the correction off; the two other values are set below,
+                // inside the branch that asked for one.
+                correctiveInvoiceOutcome: 'not_requested',
+            }
+            : null;
+        if (refundFields) {
+            if (gatewayOutcome) {
+                refundFields.settlementState = gatewayOutcome.state;
+                refundFields.externalReference = gatewayOutcome.externalReference ?? null;
+                refundFields.providerDetails = gatewayOutcome.providerDetails ?? null;
+                refundFields.failureReason = gatewayOutcome.failureReason ?? null;
+                result.refund = {
+                    settlementState: gatewayOutcome.state,
+                    externalReference: gatewayOutcome.externalReference ?? null,
+                    failureReason: gatewayOutcome.failureReason ?? null,
+                };
+            }
+            else {
+                refundFields.settlementState = creditApplied ? 'issued' : 'pending_manual';
+                refundFields.creditLimitTopupApplied = creditApplied ?? false;
+                result.creditLimitTopupApplied = creditApplied ?? false;
+                result.refund = { settlementState: refundFields.settlementState };
+            }
+            if (correction) {
+                // An order that was never invoiced has nothing to correct (#135). The
+                // settlement still stands — the refund is recorded on the return case
+                // and on the payment record — and the result says which of the two
+                // happened, because a silent absence would read as a lost document.
+                if (correction.issued) {
+                    refundFields.correctiveInvoiceId = correction.invoiceId;
+                    refundFields.correctiveInvoiceOutcome = 'issued';
+                    result.correctiveInvoiceId = correction.invoiceId;
+                    result.correctiveInvoice = {
+                        issued: true,
+                        invoiceId: correction.invoiceId,
+                        number: correction.number,
+                    };
+                }
+                else {
+                    refundFields.correctiveInvoiceOutcome = 'not_due';
+                    result.correctiveInvoiceId = null;
+                    result.correctiveInvoice = { issued: false, reason: correction.reason };
+                }
+            }
+        }
+        // Step 4 — one unit of work. `transitions.apply` flushes once, so the item
+        // amounts, the `Refund` row, the audit entry and the resolution commit
+        // together or not at all.
+        let refund = null;
+        await this.deps.transitions.apply(id, RETURN_STATUS_RESOLVED, { kind: 'admin', adminUserId, source: 'settlement' }, {
+            mutate: async (target, tx) => {
+                target.resolutionType = input.resolutionType;
+                target.refundPaymentMethodId = input.refundPaymentMethodId ?? null;
+                target.totalRefundAmount = total.toFixed(2);
+                target.resolvedAt = new Date();
+                for (const it of await tx.find(ReturnCaseItem, { returnCaseId: id })) {
+                    const approved = approvedByItemId.get(it.id);
+                    if (approved !== undefined)
+                        it.approvedRefundAmount = approved.toFixed(2);
+                }
+                if (refundFields) {
+                    refund = tx.create(Refund, refundFields);
+                    tx.persist(refund);
+                }
+                // The audit entry is part of the write, not a best-effort call after
+                // it: it used to sit behind `catch { /* ignore audit failures */ }`,
+                // which is a comment rather than a decision (Principle XIII's
+                // co-transactional clause).
+                this.deps.auditLog?.recordWithin(tx, {
+                    actorAdminUserId: adminUserId,
+                    action: 'return.settled',
+                    objectType: 'return_case',
+                    objectId: rc.id,
+                    stateAfter: {
+                        resolutionType: input.resolutionType,
+                        amount: total.toFixed(2),
+                        currency: rc.currency,
+                        settlementState: refundFields?.settlementState ?? null,
+                        // Says which of the three happened — issued, not due, or never
+                        // asked for — so "no corrective invoice" is readable after the
+                        // fact instead of being an absent field (#135).
+                        correctiveInvoice: result.correctiveInvoice
+                            ? result.correctiveInvoice.issued
+                                ? 'issued'
+                                : result.correctiveInvoice.reason
+                            : 'not_requested',
+                    },
+                });
+            },
+        });
+        // Step 5 — after commit.
+        this.emitSettled(rc, refund, total);
+        return result;
+    }
+    emitSettled(rc, refund, total) {
+        const payload = {
+            eventId: randomUUID(),
+            occurredAt: new Date().toISOString(),
+            returnCaseId: rc.id,
+            refundId: refund?.id ?? null,
+            resolutionType: rc.resolutionType,
+            amount: total,
+            currency: rc.currency,
+            settlementState: refund?.settlementState ?? null,
+        };
+        this.deps.events.emit('return.refund.settled.v1', payload);
+    }
+}
+//# sourceMappingURL=return-settlement-service.js.map

package/dist/backend/services/return-settlement-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"return-settlement-service.js","sourceRoot":"","sources":["../../../src/backend/services/return-settlement-service.ts"],"names":[],"mappings":"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"}

package/dist/backend/services/return-shipment-service.d.ts

@@ -0,0 +1,40 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+import type { ReturnShipmentDto } from '@endora-commerce/contracts';
+import type { AuditPort } from '@endora-commerce/platform/kernel';
+import type { ReturnTransitionService } from './return-transition-service.js';
+export interface ReturnShipmentServiceDeps {
+    emFactory: () => EntityManager;
+    transitions: ReturnTransitionService;
+    /** Feature 054 — audits shipment writes co-transactionally when provided. */
+    auditLog?: AuditPort;
+}
+/**
+ * ReturnShipmentService — feature 046 (US6).
+ *
+ * Records inbound return shipments (customer → shop) and replacement shipments
+ * (shop → customer) against a case. Receiving an inbound shipment drives the
+ * case `authorized → received` (FR-024).
+ */
+export declare class ReturnShipmentService {
+    #private;
+    private readonly deps;
+    constructor(deps: ReturnShipmentServiceDeps);
+    listForCase(caseId: string): Promise<ReturnShipmentDto[]>;
+    create(caseId: string, input: {
+        direction: 'inbound' | 'replacement';
+        deliveryMethodId?: string | undefined;
+        externalReference?: string | undefined;
+    }): Promise<ReturnShipmentDto>;
+    /**
+     * Mark an inbound shipment received and advance the case to `received`.
+     *
+     * The case read comes first, and that ordering is the point rather than a
+     * tidiness: the shipment row is flushed before the transition is attempted,
+     * so a caller that reached the transition's own refusal had already written
+     * `received` onto a case in an organization it cannot see, and been told 404.
+     * Both ids on this route are the caller's, and neither entity carries a
+     * filter.
+     */
+    receive(caseId: string, shipmentId: string, adminUserId: string): Promise<ReturnShipmentDto>;
+}
+//# sourceMappingURL=return-shipment-service.d.ts.map

package/dist/backend/services/return-shipment-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"return-shipment-service.d.ts","sourceRoot":"","sources":["../../../src/backend/services/return-shipment-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAGpE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAIlE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAE9E,MAAM,WAAW,yBAAyB;IACxC,SAAS,EAAE,MAAM,aAAa,CAAC;IAC/B,WAAW,EAAE,uBAAuB,CAAC;IACrC,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;;;;GAMG;AACH,qBAAa,qBAAqB;;IACpB,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,yBAAyB;IAoBtD,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAOzD,MAAM,CACV,MAAM,EAAE,MAAM,EACd,KAAK,EAAE;QACL,SAAS,EAAE,SAAS,GAAG,aAAa,CAAC;QACrC,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QACtC,iBAAiB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KACxC,GACA,OAAO,CAAC,iBAAiB,CAAC;IAwB7B;;;;;;;;;OASG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAyBnG"}

package/dist/backend/services/return-shipment-service.js

@@ -0,0 +1,113 @@
+import { ERROR_CODES } from '@endora-commerce/contracts';
+import { HttpError } from '@endora-commerce/platform/http';
+import { recordAuditFromContext } from '@endora-commerce/platform/commands';
+import { ReturnCase } from '../entities/return-case.entity.js';
+import { ReturnShipment } from '../entities/return-shipment.entity.js';
+import { RETURN_STATUS_RECEIVED } from '../domain/return-status-graph.js';
+/**
+ * ReturnShipmentService — feature 046 (US6).
+ *
+ * Records inbound return shipments (customer → shop) and replacement shipments
+ * (shop → customer) against a case. Receiving an inbound shipment drives the
+ * case `authorized → received` (FR-024).
+ */
+export class ReturnShipmentService {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * Resolve the case every method below is keyed on.
+     *
+     * `ReturnShipment` is `@GlobalEntity` — no organization column, no filter —
+     * so a read keyed on `returnCaseId` answers for every case on the platform.
+     * `ReturnCase` is `@OrgScoped`, so this read *is* the tenant boundary: an
+     * assignment-scoped administrator gets nothing back and the caller stops.
+     *
+     * `create` has made this read since it was written, for its own reasons;
+     * `listForCase` and `receive` had no reason of their own to make it, which is
+     * exactly how they came to have none.
+     */
+    async #loadCase(em, caseId) {
+        const rc = await em.findOne(ReturnCase, { id: caseId });
+        if (!rc)
+            throw new HttpError(404, ERROR_CODES.NOT_FOUND, 'Return case not found.');
+        return rc;
+    }
+    async listForCase(caseId) {
+        const em = this.deps.emFactory();
+        await this.#loadCase(em, caseId);
+        const rows = await em.find(ReturnShipment, { returnCaseId: caseId }, { orderBy: { createdAt: 'asc' } });
+        return rows.map(toDto);
+    }
+    async create(caseId, input) {
+        const em = this.deps.emFactory();
+        await this.#loadCase(em, caseId);
+        const shipment = em.create(ReturnShipment, {
+            returnCaseId: caseId,
+            direction: input.direction,
+            deliveryMethodId: input.deliveryMethodId ?? null,
+            externalReference: input.externalReference ?? null,
+            status: 'pending',
+        });
+        em.persist(shipment);
+        if (this.deps.auditLog) {
+            recordAuditFromContext(this.deps.auditLog, em, {
+                action: 'return_shipment.create',
+                objectType: 'return_shipment',
+                objectId: shipment.id,
+                stateBefore: null,
+                stateAfter: { returnCaseId: caseId, direction: shipment.direction },
+            });
+        }
+        await em.flush();
+        return toDto(shipment);
+    }
+    /**
+     * Mark an inbound shipment received and advance the case to `received`.
+     *
+     * The case read comes first, and that ordering is the point rather than a
+     * tidiness: the shipment row is flushed before the transition is attempted,
+     * so a caller that reached the transition's own refusal had already written
+     * `received` onto a case in an organization it cannot see, and been told 404.
+     * Both ids on this route are the caller's, and neither entity carries a
+     * filter.
+     */
+    async receive(caseId, shipmentId, adminUserId) {
+        const em = this.deps.emFactory();
+        await this.#loadCase(em, caseId);
+        const shipment = await em.findOne(ReturnShipment, { id: shipmentId, returnCaseId: caseId });
+        if (!shipment)
+            throw new HttpError(404, ERROR_CODES.NOT_FOUND, 'Return shipment not found.');
+        shipment.status = 'received';
+        if (this.deps.auditLog) {
+            recordAuditFromContext(this.deps.auditLog, em, {
+                action: 'return_shipment.receive',
+                objectType: 'return_shipment',
+                objectId: shipment.id,
+                stateBefore: { status: 'pending' },
+                stateAfter: { status: 'received' },
+            });
+        }
+        await em.flush();
+        if (shipment.direction === 'inbound') {
+            await this.deps.transitions.apply(caseId, RETURN_STATUS_RECEIVED, {
+                kind: 'admin',
+                adminUserId,
+                source: 'shipment',
+            });
+        }
+        return toDto(shipment);
+    }
+}
+function toDto(s) {
+    return {
+        id: s.id,
+        direction: s.direction,
+        deliveryMethodId: s.deliveryMethodId ?? null,
+        externalReference: s.externalReference ?? null,
+        status: s.status,
+        createdAt: s.createdAt.toISOString(),
+    };
+}
+//# sourceMappingURL=return-shipment-service.js.map

package/dist/backend/services/return-shipment-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"return-shipment-service.js","sourceRoot":"","sources":["../../../src/backend/services/return-shipment-service.ts"],"names":[],"mappings":"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"}