@endora-commerce/mod-returns 0.100.0

package/dist/backend/services/return-status-graph-service.d.ts

@@ -0,0 +1,59 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+import type { AuditPort } from '@endora-commerce/platform/kernel';
+import { ReturnStatusGraph, type ReturnStatusDef, type ReturnTransitionDef } from '../domain/return-status-graph.js';
+/**
+ * ReturnStatusGraphService — feature 046 (US3).
+ *
+ * DB-backed loader + admin CRUD for the configurable RMA lifecycle. Builds an
+ * immutable `ReturnStatusGraph` from `return_statuses` + `return_status_transitions`
+ * and caches it in-process; every mutation invalidates the cache. Mirrors
+ * `OrderStatusGraphService`.
+ */
+export declare class ReturnStatusGraphService {
+    #private;
+    private readonly emFactory;
+    /** Feature 054 — audits status-graph writes co-transactionally when provided. */
+    private readonly auditLog?;
+    private cached;
+    constructor(emFactory: () => EntityManager, 
+    /** Feature 054 — audits status-graph writes co-transactionally when provided. */
+    auditLog?: AuditPort | undefined);
+    invalidate(): void;
+    /** Build (or return cached) the validated graph. */
+    loadGraph(): Promise<ReturnStatusGraph>;
+    hasStatus(code: string): Promise<boolean>;
+    /** The graph plus per-status `inUseCount` for the admin config view. */
+    listGraph(): Promise<{
+        statuses: Array<ReturnStatusDef & {
+            inUseCount: number;
+        }>;
+        transitions: ReturnTransitionDef[];
+    }>;
+    private statusUsageCounts;
+    createStatus(input: {
+        code: string;
+        name: Record<string, string>;
+        defaultName: string;
+        isTerminal?: boolean | undefined;
+        weight?: number | undefined;
+        color?: string | undefined;
+    }): Promise<void>;
+    updateStatus(code: string, patch: {
+        name?: Record<string, string> | undefined;
+        defaultName?: string | undefined;
+        isTerminal?: boolean | undefined;
+        weight?: number | undefined;
+        color?: string | undefined;
+    }): Promise<void>;
+    deleteStatus(code: string): Promise<void>;
+    /**
+     * Replace the full transition set (PUT semantics). Validates every pair
+     * against the current statuses and the no-edge-from-terminal invariant, then
+     * swaps the persisted rows.
+     */
+    replaceTransitions(pairs: Array<{
+        fromStatusCode: string;
+        toStatusCode: string;
+    }>): Promise<void>;
+}
+//# sourceMappingURL=return-status-graph-service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"return-status-graph-service.d.ts","sourceRoot":"","sources":["../../../src/backend/services/return-status-graph-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAI3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAIlE,OAAO,EAEL,iBAAiB,EACjB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACzB,MAAM,kCAAkC,CAAC;AAE1C;;;;;;;GAOG;AACH,qBAAa,wBAAwB;;IAIjC,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,iFAAiF;IACjF,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;IAL5B,OAAO,CAAC,MAAM,CAAkC;gBAG7B,SAAS,EAAE,MAAM,aAAa;IAC/C,iFAAiF;IAChE,QAAQ,CAAC,EAAE,SAAS,YAAA;IAqBvC,UAAU,IAAI,IAAI;IAIlB,oDAAoD;IAC9C,SAAS,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAmBvC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAI/C,wEAAwE;IAClE,SAAS,IAAI,OAAO,CAAC;QACzB,QAAQ,EAAE,KAAK,CAAC,eAAe,GAAG;YAAE,UAAU,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAC1D,WAAW,EAAE,mBAAmB,EAAE,CAAC;KACpC,CAAC;YASY,iBAAiB;IAWzB,YAAY,CAAC,KAAK,EAAE;QACxB,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC7B,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;QACjC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC5B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KAC5B,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBX,YAAY,CAChB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE;QACL,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;QAC1C,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QACjC,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;QACjC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC5B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KAC5B,GACA,OAAO,CAAC,IAAI,CAAC;IA+BV,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAuB/C;;;;OAIG;IACG,kBAAkB,CACtB,KAAK,EAAE,KAAK,CAAC;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,GAC7D,OAAO,CAAC,IAAI,CAAC;CAsCjB"}

package/dist/backend/services/return-status-graph-service.js

@@ -0,0 +1,197 @@
+import { ERROR_CODES } from '@endora-commerce/contracts';
+import { HttpError } from '@endora-commerce/platform/http';
+import { recordAuditFromContext } from '@endora-commerce/platform/commands';
+import { ReturnStatus } from '../entities/return-status.entity.js';
+import { ReturnStatusTransition } from '../entities/return-status-transition.entity.js';
+import { ReturnCase } from '../entities/return-case.entity.js';
+import { RETURN_STATUS_INITIAL, ReturnStatusGraph, } from '../domain/return-status-graph.js';
+/**
+ * ReturnStatusGraphService — feature 046 (US3).
+ *
+ * DB-backed loader + admin CRUD for the configurable RMA lifecycle. Builds an
+ * immutable `ReturnStatusGraph` from `return_statuses` + `return_status_transitions`
+ * and caches it in-process; every mutation invalidates the cache. Mirrors
+ * `OrderStatusGraphService`.
+ */
+export class ReturnStatusGraphService {
+    emFactory;
+    auditLog;
+    cached = null;
+    constructor(emFactory, 
+    /** Feature 054 — audits status-graph writes co-transactionally when provided. */
+    auditLog) {
+        this.emFactory = emFactory;
+        this.auditLog = auditLog;
+    }
+    #audit(em, action, objectId, stateBefore, stateAfter) {
+        if (this.auditLog) {
+            recordAuditFromContext(this.auditLog, em, {
+                action,
+                objectType: 'return_status',
+                objectId,
+                stateBefore,
+                stateAfter,
+            });
+        }
+    }
+    invalidate() {
+        this.cached = null;
+    }
+    /** Build (or return cached) the validated graph. */
+    async loadGraph() {
+        if (this.cached)
+            return this.cached;
+        const em = this.emFactory();
+        const [statuses, transitions] = await Promise.all([
+            em.find(ReturnStatus, {}, { orderBy: { weight: 'asc' } }),
+            em.find(ReturnStatusTransition, {}),
+        ]);
+        const graph = new ReturnStatusGraph(statuses.map(toStatusDef), transitions.map((t) => ({
+            fromStatusCode: t.fromStatusCode,
+            toStatusCode: t.toStatusCode,
+            isSystem: t.isSystem,
+        })));
+        this.cached = graph;
+        return graph;
+    }
+    async hasStatus(code) {
+        return (await this.loadGraph()).has(code);
+    }
+    /** The graph plus per-status `inUseCount` for the admin config view. */
+    async listGraph() {
+        const graph = await this.loadGraph();
+        const counts = await this.statusUsageCounts();
+        return {
+            statuses: graph.statuses.map((s) => ({ ...s, inUseCount: counts.get(s.code) ?? 0 })),
+            transitions: graph.transitions,
+        };
+    }
+    async statusUsageCounts() {
+        const em = this.emFactory();
+        const rows = await em
+            .getKnex()
+            .from('return_cases')
+            .select('status_code')
+            .count('* as count')
+            .groupBy('status_code');
+        return new Map(rows.map((r) => [r.status_code, Number(r.count)]));
+    }
+    async createStatus(input) {
+        const em = this.emFactory();
+        const existing = await em.findOne(ReturnStatus, { code: input.code });
+        if (existing) {
+            throw new HttpError(409, ERROR_CODES.VALIDATION_FAILED, `Status "${input.code}" already exists.`);
+        }
+        const status = em.create(ReturnStatus, {
+            code: input.code,
+            name: input.name,
+            defaultName: input.defaultName,
+            isInitial: false,
+            isTerminal: input.isTerminal ?? false,
+            isSystem: false,
+            weight: input.weight ?? 100,
+            color: input.color ?? '#64748b',
+        });
+        em.persist(status);
+        this.#audit(em, 'return_status.create', input.code, null, { code: input.code, defaultName: input.defaultName });
+        await em.flush();
+        this.invalidate();
+    }
+    async updateStatus(code, patch) {
+        const em = this.emFactory();
+        const status = await em.findOne(ReturnStatus, { code });
+        if (!status)
+            throw new HttpError(404, ERROR_CODES.NOT_FOUND, `Status "${code}" not found.`);
+        if (patch.name !== undefined)
+            status.name = patch.name;
+        if (patch.defaultName !== undefined)
+            status.defaultName = patch.defaultName;
+        if (patch.weight !== undefined)
+            status.weight = patch.weight;
+        if (patch.color !== undefined)
+            status.color = patch.color;
+        if (patch.isTerminal !== undefined && patch.isTerminal !== status.isTerminal) {
+            if (patch.isTerminal) {
+                const outgoing = await em.count(ReturnStatusTransition, { fromStatusCode: code });
+                if (outgoing > 0) {
+                    throw new HttpError(409, ERROR_CODES.VALIDATION_FAILED, `Cannot mark "${code}" terminal while it has outgoing transitions.`);
+                }
+            }
+            status.isTerminal = patch.isTerminal;
+        }
+        this.#audit(em, 'return_status.update', code, null, {
+            defaultName: status.defaultName,
+            weight: status.weight,
+            color: status.color,
+            isTerminal: status.isTerminal,
+        });
+        await em.flush();
+        this.invalidate();
+    }
+    async deleteStatus(code) {
+        const em = this.emFactory();
+        const status = await em.findOne(ReturnStatus, { code });
+        if (!status)
+            throw new HttpError(404, ERROR_CODES.NOT_FOUND, `Status "${code}" not found.`);
+        if (code === RETURN_STATUS_INITIAL || status.isInitial) {
+            throw new HttpError(409, ERROR_CODES.VALIDATION_FAILED, 'The initial status cannot be deleted.');
+        }
+        const inUse = await em.count(ReturnCase, { statusCode: code });
+        if (inUse > 0) {
+            throw new HttpError(409, ERROR_CODES.VALIDATION_FAILED, `Cannot delete status "${code}" while ${inUse} case(s) use it.`);
+        }
+        const edges = await em.find(ReturnStatusTransition, {
+            $or: [{ fromStatusCode: code }, { toStatusCode: code }],
+        });
+        this.#audit(em, 'return_status.delete', code, { code, defaultName: status.defaultName }, null);
+        await em.remove(edges).remove(status).flush();
+        this.invalidate();
+    }
+    /**
+     * Replace the full transition set (PUT semantics). Validates every pair
+     * against the current statuses and the no-edge-from-terminal invariant, then
+     * swaps the persisted rows.
+     */
+    async replaceTransitions(pairs) {
+        const em = this.emFactory();
+        const graph = await this.loadGraph();
+        for (const edge of pairs) {
+            if (!graph.has(edge.fromStatusCode) || !graph.has(edge.toStatusCode)) {
+                throw new HttpError(422, ERROR_CODES.VALIDATION_FAILED, `Transition references an unknown status: ${edge.fromStatusCode} → ${edge.toStatusCode}.`);
+            }
+            if (graph.isTerminal(edge.fromStatusCode)) {
+                throw new HttpError(422, ERROR_CODES.VALIDATION_FAILED, `Terminal status "${edge.fromStatusCode}" cannot have outgoing transitions.`);
+            }
+        }
+        const existing = await em.find(ReturnStatusTransition, {});
+        await em.remove(existing).flush();
+        const seen = new Set();
+        for (const edge of pairs) {
+            const key = `${edge.fromStatusCode} ${edge.toStatusCode}`;
+            if (seen.has(key) || edge.fromStatusCode === edge.toStatusCode)
+                continue;
+            seen.add(key);
+            em.persist(em.create(ReturnStatusTransition, {
+                fromStatusCode: edge.fromStatusCode,
+                toStatusCode: edge.toStatusCode,
+                isSystem: false,
+            }));
+        }
+        this.#audit(em, 'return_status.replace_transitions', 'graph', null, { count: seen.size });
+        await em.flush();
+        this.invalidate();
+    }
+}
+function toStatusDef(s) {
+    return {
+        code: s.code,
+        name: s.name,
+        defaultName: s.defaultName,
+        isInitial: s.isInitial,
+        isTerminal: s.isTerminal,
+        isSystem: s.isSystem,
+        weight: s.weight,
+        color: s.color,
+    };
+}
+//# sourceMappingURL=return-status-graph-service.js.map

package/dist/backend/services/return-status-graph-service.js.map

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

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

@@ -0,0 +1,48 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+import type { EventBus } from '@endora-commerce/platform/events';
+import type { AuditPort } from '@endora-commerce/platform/kernel';
+import { ReturnCase } from '../entities/return-case.entity.js';
+import type { ReturnStatusGraphService } from './return-status-graph-service.js';
+import { type ReturnStatusActor, type ReturnStatusEvent } from '../events/return-status-events.js';
+type TransitionGuard = (e: ReturnStatusEvent) => void | Promise<void>;
+/** Side-effects applied within the transition, before the after-events fire. */
+export type ReturnTransitionSideEffects = (e: {
+    returnCase: ReturnCase;
+    from: string;
+    to: string;
+    em: EntityManager;
+}) => Promise<void>;
+/**
+ * ReturnTransitionService — feature 046 (US3).
+ *
+ * Applies a status transition against the configurable graph and emits the four
+ * templated business events. The `.before` events run through a veto-capable
+ * guard registry; the `.after` events fire on the EventBus once the write has
+ * flushed. Mirrors `OrderTransitionService`.
+ */
+export declare class ReturnTransitionService {
+    private readonly emFactory;
+    private readonly events;
+    private readonly graphService;
+    private readonly auditLog?;
+    private readonly guards;
+    constructor(emFactory: () => EntityManager, events: EventBus, graphService: ReturnStatusGraphService, auditLog?: AuditPort | undefined);
+    onReturnTransitionGuard(match: {
+        from?: string;
+        to?: string;
+    }, guard: TransitionGuard): () => void;
+    /**
+     * Transition `returnCaseId` to status code `to`. Throws 404 if the case is
+     * missing, 422 for an unknown target, 409 if the transition is not permitted
+     * by the graph or a guard vetoes it. `mutate` runs after the graph check and
+     * before the status flush (e.g. assign RMA number, set rejection reason).
+     */
+    apply(returnCaseId: string, to: string, actor: ReturnStatusActor, opts?: {
+        reason?: string | null;
+        mutate?: (rc: ReturnCase, em: EntityManager) => void | Promise<void>;
+        sideEffects?: ReturnTransitionSideEffects;
+    }): Promise<ReturnCase>;
+    private runBeforeGuards;
+}
+export {};
+//# sourceMappingURL=return-transition-service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"return-transition-service.d.ts","sourceRoot":"","sources":["../../../src/backend/services/return-transition-service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AAEjE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAC;AAC/D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AACjF,OAAO,EAIL,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACvB,MAAM,mCAAmC,CAAC;AAE3C,KAAK,eAAe,GAAG,CAAC,CAAC,EAAE,iBAAiB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAMtE,gFAAgF;AAChF,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,EAAE;IAC5C,UAAU,EAAE,UAAU,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,aAAa,CAAC;CACnB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEpB;;;;;;;GAOG;AACH,qBAAa,uBAAuB;IAIhC,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;IAN5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;gBAGxB,SAAS,EAAE,MAAM,aAAa,EAC9B,MAAM,EAAE,QAAQ,EAChB,YAAY,EAAE,wBAAwB,EACtC,QAAQ,CAAC,EAAE,SAAS,YAAA;IAGvC,uBAAuB,CAAC,KAAK,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,KAAK,EAAE,eAAe,GAAG,MAAM,IAAI;IASlG;;;;;OAKG;IACG,KAAK,CACT,YAAY,EAAE,MAAM,EACpB,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,iBAAiB,EACxB,IAAI,CAAC,EAAE;QACL,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACvB,MAAM,CAAC,EAAE,CAAC,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE,aAAa,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QACrE,WAAW,CAAC,EAAE,2BAA2B,CAAC;KAC3C,GACA,OAAO,CAAC,UAAU,CAAC;YAkER,eAAe;CAc9B"}

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

@@ -0,0 +1,116 @@
+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 { emitReturnStatusAfter, returnStatusBeforeEventNames, ReturnTransitionVetoError, } from '../events/return-status-events.js';
+/**
+ * ReturnTransitionService — feature 046 (US3).
+ *
+ * Applies a status transition against the configurable graph and emits the four
+ * templated business events. The `.before` events run through a veto-capable
+ * guard registry; the `.after` events fire on the EventBus once the write has
+ * flushed. Mirrors `OrderTransitionService`.
+ */
+export class ReturnTransitionService {
+    emFactory;
+    events;
+    graphService;
+    auditLog;
+    guards = [];
+    constructor(emFactory, events, graphService, auditLog) {
+        this.emFactory = emFactory;
+        this.events = events;
+        this.graphService = graphService;
+        this.auditLog = auditLog;
+    }
+    onReturnTransitionGuard(match, guard) {
+        const entry = { match, guard };
+        this.guards.push(entry);
+        return () => {
+            const idx = this.guards.indexOf(entry);
+            if (idx >= 0)
+                this.guards.splice(idx, 1);
+        };
+    }
+    /**
+     * Transition `returnCaseId` to status code `to`. Throws 404 if the case is
+     * missing, 422 for an unknown target, 409 if the transition is not permitted
+     * by the graph or a guard vetoes it. `mutate` runs after the graph check and
+     * before the status flush (e.g. assign RMA number, set rejection reason).
+     */
+    async apply(returnCaseId, to, actor, opts) {
+        const em = this.emFactory();
+        const rc = await em.findOne(ReturnCase, { id: returnCaseId });
+        if (!rc)
+            throw new HttpError(404, ERROR_CODES.NOT_FOUND, 'Return case not found.');
+        const from = rc.statusCode;
+        if (from === to)
+            return rc;
+        const graph = await this.graphService.loadGraph();
+        if (!graph.has(to)) {
+            throw new HttpError(422, ERROR_CODES.VALIDATION_FAILED, `Unknown return status "${to}".`);
+        }
+        if (!graph.canTransition(from, to)) {
+            throw new HttpError(409, ERROR_CODES.INVALID_TRANSITION, `Cannot transition from "${from}" to "${to}".`);
+        }
+        const event = {
+            eventId: randomUUID(),
+            occurredAt: new Date().toISOString(),
+            returnCaseId: rc.id,
+            orderId: rc.orderId,
+            organizationId: rc.organizationId ?? null,
+            salesChannelId: rc.salesChannelId,
+            from,
+            to,
+            actor,
+            reason: opts?.reason ?? null,
+        };
+        await this.runBeforeGuards(event);
+        for (const name of returnStatusBeforeEventNames(from, to)) {
+            this.events.emit(name, event);
+        }
+        if (opts?.mutate)
+            await opts.mutate(rc, em);
+        rc.statusCode = to;
+        await em.flush();
+        if (opts?.sideEffects)
+            await opts.sideEffects({ returnCase: rc, from, to, em });
+        emitReturnStatusAfter(this.events, event);
+        // Audit the status change (FR-041); best-effort, never blocks the transition.
+        if (this.auditLog) {
+            try {
+                await this.auditLog.record({
+                    actorAdminUserId: actor.kind === 'admin' ? (actor.adminUserId ?? null) : null,
+                    impersonatedCustomerAccountId: actor.kind === 'customer' ? (actor.customerAccountId ?? null) : null,
+                    action: 'return.status_changed',
+                    objectType: 'return_case',
+                    objectId: rc.id,
+                    stateBefore: { statusCode: from },
+                    stateAfter: { statusCode: to, reason: opts?.reason ?? null },
+                });
+            }
+            catch {
+                // ignore audit failures
+            }
+        }
+        return rc;
+    }
+    async runBeforeGuards(event) {
+        for (const entry of this.guards) {
+            if (entry.match.from !== undefined && entry.match.from !== event.from)
+                continue;
+            if (entry.match.to !== undefined && entry.match.to !== event.to)
+                continue;
+            try {
+                await entry.guard(event);
+            }
+            catch (err) {
+                if (err instanceof ReturnTransitionVetoError) {
+                    throw new HttpError(409, ERROR_CODES.INVALID_TRANSITION, err.message);
+                }
+                throw err;
+            }
+        }
+    }
+}
+//# sourceMappingURL=return-transition-service.js.map

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

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

package/dist/backend/services/returns-seeder.d.ts

@@ -0,0 +1,18 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+/**
+ * ReturnsSeeder — feature 046 (T017).
+ *
+ * Idempotently ensures the default status graph and reasons exist. The init
+ * migration seeds these on a fresh install; this runtime seeder is a no-op when
+ * the data is present and restores it when absent (e.g. after a module
+ * uninstall/reinstall under the lifecycle), so the module is self-healing. It is
+ * invoked once at module boot.
+ */
+export declare class ReturnsSeeder {
+    private readonly emFactory;
+    constructor(emFactory: () => EntityManager);
+    ensureDefaults(): Promise<void>;
+    private ensureStatusGraph;
+    private ensureReasons;
+}
+//# sourceMappingURL=returns-seeder.d.ts.map

package/dist/backend/services/returns-seeder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"returns-seeder.d.ts","sourceRoot":"","sources":["../../../src/backend/services/returns-seeder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAU3D;;;;;;;;GAQG;AACH,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,SAAS;gBAAT,SAAS,EAAE,MAAM,aAAa;IAErD,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;YAKvB,iBAAiB;YA+BjB,aAAa;CAU5B"}

package/dist/backend/services/returns-seeder.js

@@ -0,0 +1,63 @@
+import { ReturnStatus } from '../entities/return-status.entity.js';
+import { ReturnStatusTransition } from '../entities/return-status-transition.entity.js';
+import { ReturnReason } from '../entities/return-reason.entity.js';
+import { DEFAULT_RETURN_STATUSES, computeDefaultTransitions, } from '../domain/return-status-graph.js';
+import { DEFAULT_RETURN_REASONS } from '../domain/default-reasons.js';
+/**
+ * ReturnsSeeder — feature 046 (T017).
+ *
+ * Idempotently ensures the default status graph and reasons exist. The init
+ * migration seeds these on a fresh install; this runtime seeder is a no-op when
+ * the data is present and restores it when absent (e.g. after a module
+ * uninstall/reinstall under the lifecycle), so the module is self-healing. It is
+ * invoked once at module boot.
+ */
+export class ReturnsSeeder {
+    emFactory;
+    constructor(emFactory) {
+        this.emFactory = emFactory;
+    }
+    async ensureDefaults() {
+        await this.ensureStatusGraph();
+        await this.ensureReasons();
+    }
+    async ensureStatusGraph() {
+        // command-coverage-ignore: idempotent first-run seed of the default status
+        // graph (skips when rows exist), a system bootstrap, not an operator write.
+        const em = this.emFactory();
+        if ((await em.count(ReturnStatus, {})) > 0)
+            return;
+        for (const s of DEFAULT_RETURN_STATUSES) {
+            em.persist(em.create(ReturnStatus, {
+                code: s.code,
+                name: s.name,
+                defaultName: s.defaultName,
+                isInitial: s.isInitial,
+                isTerminal: s.isTerminal,
+                isSystem: s.isSystem,
+                weight: s.weight,
+                color: s.color,
+            }));
+        }
+        for (const t of computeDefaultTransitions()) {
+            em.persist(em.create(ReturnStatusTransition, {
+                fromStatusCode: t.fromStatusCode,
+                toStatusCode: t.toStatusCode,
+                isSystem: t.isSystem,
+            }));
+        }
+        await em.flush();
+    }
+    async ensureReasons() {
+        // command-coverage-ignore: idempotent first-run seed of the default reasons
+        // (skips when rows exist), a system bootstrap, not an operator write.
+        const em = this.emFactory();
+        if ((await em.count(ReturnReason, {})) > 0)
+            return;
+        for (const r of DEFAULT_RETURN_REASONS) {
+            em.persist(em.create(ReturnReason, { label: r.label, appliesTo: r.appliesTo, weight: r.weight }));
+        }
+        await em.flush();
+    }
+}
+//# sourceMappingURL=returns-seeder.js.map

package/dist/backend/services/returns-seeder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"returns-seeder.js","sourceRoot":"","sources":["../../../src/backend/services/returns-seeder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAC;AACnE,OAAO,EAAE,sBAAsB,EAAE,MAAM,gDAAgD,CAAC;AACxF,OAAO,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAC;AACnE,OAAO,EACL,uBAAuB,EACvB,yBAAyB,GAC1B,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAEtE;;;;;;;;GAQG;AACH,MAAM,OAAO,aAAa;IACK;IAA7B,YAA6B,SAA8B;QAA9B,cAAS,GAAT,SAAS,CAAqB;IAAG,CAAC;IAE/D,KAAK,CAAC,cAAc;QAClB,MAAM,IAAI,CAAC,iBAAiB,EAAE,CAAC;QAC/B,MAAM,IAAI,CAAC,aAAa,EAAE,CAAC;IAC7B,CAAC;IAEO,KAAK,CAAC,iBAAiB;QAC7B,2EAA2E;QAC3E,4EAA4E;QAC5E,MAAM,EAAE,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;QAC5B,IAAI,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC;YAAE,OAAO;QACnD,KAAK,MAAM,CAAC,IAAI,uBAAuB,EAAE,CAAC;YACxC,EAAE,CAAC,OAAO,CACR,EAAE,CAAC,MAAM,CAAC,YAAY,EAAE;gBACtB,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,WAAW,EAAE,CAAC,CAAC,WAAW;gBAC1B,SAAS,EAAE,CAAC,CAAC,SAAS;gBACtB,UAAU,EAAE,CAAC,CAAC,UAAU;gBACxB,QAAQ,EAAE,CAAC,CAAC,QAAQ;gBACpB,MAAM,EAAE,CAAC,CAAC,MAAM;gBAChB,KAAK,EAAE,CAAC,CAAC,KAAK;aACf,CAAC,CACH,CAAC;QACJ,CAAC;QACD,KAAK,MAAM,CAAC,IAAI,yBAAyB,EAAE,EAAE,CAAC;YAC5C,EAAE,CAAC,OAAO,CACR,EAAE,CAAC,MAAM,CAAC,sBAAsB,EAAE;gBAChC,cAAc,EAAE,CAAC,CAAC,cAAc;gBAChC,YAAY,EAAE,CAAC,CAAC,YAAY;gBAC5B,QAAQ,EAAE,CAAC,CAAC,QAAQ;aACrB,CAAC,CACH,CAAC;QACJ,CAAC;QACD,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC;IACnB,CAAC;IAEO,KAAK,CAAC,aAAa;QACzB,4EAA4E;QAC5E,sEAAsE;QACtE,MAAM,EAAE,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;QAC5B,IAAI,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC;YAAE,OAAO;QACnD,KAAK,MAAM,CAAC,IAAI,sBAAsB,EAAE,CAAC;YACvC,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC,YAAY,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;QACpG,CAAC;QACD,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC;IACnB,CAAC;CACF"}

package/dist/backend/services/rma-number-generator.d.ts

@@ -0,0 +1,35 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+/**
+ * Resolves the admin-configurable RMA-number prefix/suffix for a Sales Channel.
+ * In production these wrap `SettingsService.get('returns.rma_number_*')` (wired
+ * in composition); the generator treats any resolver failure as an empty string
+ * so authorization never fails because a setting is missing or out of scope.
+ */
+export interface RmaNumberSettingsResolver {
+    resolvePrefix(salesChannelId: string): Promise<string>;
+    resolveSuffix(salesChannelId: string): Promise<string>;
+}
+/** Draws the next value from the monotonic RMA sequence. */
+export type DrawRmaSequence = (tx: EntityManager) => Promise<string>;
+/**
+ * Feature 046 — generates the RMA number `${prefix}${sequence}${suffix}`. The
+ * numeric core comes from the `return_cases_rma_seq` Postgres sequence
+ * (monotonic, never resets), so the number is unique regardless of later
+ * prefix/suffix changes. The sequence draw is injected so the generator is
+ * unit-testable without a database (mirrors `BusinessIdGenerator`).
+ */
+export declare class RmaNumberGenerator {
+    private readonly drawSequence;
+    private readonly settings?;
+    constructor(drawSequence: DrawRmaSequence, settings?: RmaNumberSettingsResolver | undefined);
+    generate(tx: EntityManager, salesChannelId: string): Promise<string>;
+    /** Resolve a prefix/suffix, swallowing missing/out-of-scope settings as ''. */
+    private resolve;
+}
+/**
+ * Production factory: draws `nextval('return_cases_rma_seq')` on the
+ * transaction's connection so the value is allocated inside the authorize
+ * transaction without row locking.
+ */
+export declare function createRmaNumberGenerator(settings?: RmaNumberSettingsResolver): RmaNumberGenerator;
+//# sourceMappingURL=rma-number-generator.d.ts.map

package/dist/backend/services/rma-number-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rma-number-generator.d.ts","sourceRoot":"","sources":["../../../src/backend/services/rma-number-generator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,WAAW,yBAAyB;IACxC,aAAa,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACvD,aAAa,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACxD;AAED,4DAA4D;AAC5D,MAAM,MAAM,eAAe,GAAG,CAAC,EAAE,EAAE,aAAa,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAErE;;;;;;GAMG;AACH,qBAAa,kBAAkB;IAE3B,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;gBADT,YAAY,EAAE,eAAe,EAC7B,QAAQ,CAAC,EAAE,yBAAyB,YAAA;IAGjD,QAAQ,CAAC,EAAE,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAO1E,+EAA+E;YACjE,OAAO;CAUtB;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,CAAC,EAAE,yBAAyB,GACnC,kBAAkB,CAQpB"}

package/dist/backend/services/rma-number-generator.js

@@ -0,0 +1,45 @@
+/**
+ * Feature 046 — generates the RMA number `${prefix}${sequence}${suffix}`. The
+ * numeric core comes from the `return_cases_rma_seq` Postgres sequence
+ * (monotonic, never resets), so the number is unique regardless of later
+ * prefix/suffix changes. The sequence draw is injected so the generator is
+ * unit-testable without a database (mirrors `BusinessIdGenerator`).
+ */
+export class RmaNumberGenerator {
+    drawSequence;
+    settings;
+    constructor(drawSequence, settings) {
+        this.drawSequence = drawSequence;
+        this.settings = settings;
+    }
+    async generate(tx, salesChannelId) {
+        const sequence = await this.drawSequence(tx);
+        const prefix = await this.resolve((s) => s.resolvePrefix(salesChannelId));
+        const suffix = await this.resolve((s) => s.resolveSuffix(salesChannelId));
+        return `${prefix}${sequence}${suffix}`;
+    }
+    /** Resolve a prefix/suffix, swallowing missing/out-of-scope settings as ''. */
+    async resolve(pick) {
+        if (!this.settings)
+            return '';
+        try {
+            return (await pick(this.settings)) ?? '';
+        }
+        catch {
+            return '';
+        }
+    }
+}
+/**
+ * Production factory: draws `nextval('return_cases_rma_seq')` on the
+ * transaction's connection so the value is allocated inside the authorize
+ * transaction without row locking.
+ */
+export function createRmaNumberGenerator(settings) {
+    const draw = async (tx) => {
+        const rows = (await tx.execute(`select nextval('return_cases_rma_seq') as n`));
+        return String(rows[0]?.n ?? '');
+    };
+    return new RmaNumberGenerator(draw, settings);
+}
+//# sourceMappingURL=rma-number-generator.js.map

package/dist/backend/services/rma-number-generator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rma-number-generator.js","sourceRoot":"","sources":["../../../src/backend/services/rma-number-generator.ts"],"names":[],"mappings":"AAgBA;;;;;;GAMG;AACH,MAAM,OAAO,kBAAkB;IAEV;IACA;IAFnB,YACmB,YAA6B,EAC7B,QAAoC;QADpC,iBAAY,GAAZ,YAAY,CAAiB;QAC7B,aAAQ,GAAR,QAAQ,CAA4B;IACpD,CAAC;IAEJ,KAAK,CAAC,QAAQ,CAAC,EAAiB,EAAE,cAAsB;QACtD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;QAC7C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,cAAc,CAAC,CAAC,CAAC;QAC1E,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,cAAc,CAAC,CAAC,CAAC;QAC1E,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,EAAE,CAAC;IACzC,CAAC;IAED,+EAA+E;IACvE,KAAK,CAAC,OAAO,CACnB,IAAuD;QAEvD,IAAI,CAAC,IAAI,CAAC,QAAQ;YAAE,OAAO,EAAE,CAAC;QAC9B,IAAI,CAAC;YACH,OAAO,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;QAC3C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CACtC,QAAoC;IAEpC,MAAM,IAAI,GAAoB,KAAK,EAAE,EAAE,EAAE,EAAE;QACzC,MAAM,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC,OAAO,CAC5B,6CAA6C,CAC9C,CAAkC,CAAC;QACpC,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;IAClC,CAAC,CAAC;IACF,OAAO,IAAI,kBAAkB,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;AAChD,CAAC"}