@endora-commerce/mod-invoices 0.0.0-stage → 0.100.0

package/dist/backend/services/auto-issue-reactor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-issue-reactor.d.ts","sourceRoot":"","sources":["../../../src/backend/services/auto-issue-reactor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAS3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC3F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAG3D,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,aAAa,CAAC;IAC/B,cAAc,EAAE,cAAc,CAAC;IAC/B,eAAe,EAAE,cAAc,CAAC;IAChC,wEAAwE;IACxE,eAAe,CAAC,EAAE,sBAAsB,GAAG,SAAS,CAAC;IACrD;;;;OAIG;IACH,GAAG,CAAC,EAAE,eAAe,CAAC;CACvB;AAKD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,oBAAoB,GAAG;IAClE,oBAAoB,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3D,CAgFA"}

package/dist/backend/services/auto-issue-reactor.js

@@ -0,0 +1,122 @@
+import { z } from 'zod';
+import { Invoice } from '../entities/invoice.entity.js';
+import { rethrowIfModuleDisabled } from '@endora-commerce/platform/kernel';
+import { SettingNotRegistered, SettingOutOfScopeForChannel, } from '@endora-commerce/platform/kernel';
+import { INVOICES_SETTING_CODES } from '../../manifest.js';
+/** The message every non-delivery below is written under. */
+const NOT_EMAILED = '[invoices] the auto-issued invoice was not e-mailed';
+/**
+ * FR-002 — issue an invoice when an order reaches the configured status.
+ *
+ * The **subscription** lives in this module's `backend.ts` and goes through
+ * `ctx.subscribe` (issue #107). It was a bare `eventBus.on` in the plugin body,
+ * and of the twenty-two such registrations this was the heaviest write: a
+ * switched-off `invoices` module still issued a numbered legal document, took a
+ * number out of the invoice sequence and e-mailed the PDF to the customer, while
+ * the admin surface that would have shown it refused.
+ *
+ * Idempotent on `(orderId, kind='invoice')`, and still best-effort: a failed
+ * automatic attempt leaves manual issuance available. It is no longer *silent*
+ * (issue #115). This subscriber has no caller to answer, so "observed" means
+ * written to the log with the context only the reactor knows — which order
+ * triggered the issuance, and which number it drew. Three things were swallowed
+ * here and each now has a distinct outcome:
+ *
+ *   - a **non-sent dispatch**: `{ sent, reason }` was discarded exactly as the
+ *     plugin-body closure it was lifted out of discarded it, so an invoice that
+ *     was issued and never delivered read as success. The reason is recorded.
+ *   - a **switched-off module**: the outer `catch {}` absorbed
+ *     `ModuleDisabledError`, which is fail-closed turned into fail-open. It is
+ *     re-thrown; the EventBus isolates and logs handler throws, so the presence
+ *     answer surfaces instead of being confused with a transient failure.
+ *   - a **defective settings read**: `catch { trigger = '' }` made every failure
+ *     read as "no trigger configured" — the same `''` sentinel D-43 removed from
+ *     the dispatcher. Only the two conditions that genuinely mean "not
+ *     configured" degrade now.
+ *
+ * An operator who switched send-on-issue off is *not* a loss and is not logged:
+ * that is a configured choice, not an undelivered message.
+ */
+export function createAutoIssueReactor(deps) {
+    const log = deps.log ?? ((message, context) => console.warn(message, context));
+    /**
+     * The trigger status, or `''` when the operator has not configured one. The
+     * two conditions that degrade, and no others: the setting is not registered
+     * yet, or it is scoped to a subset of channels this read is not inside.
+     * Anything else — including a `ModuleDisabledError` from the settings port —
+     * propagates.
+     */
+    async function readTrigger(salesChannelId) {
+        try {
+            return await deps.settingsService.get(INVOICES_SETTING_CODES.AUTO_ISSUE_TRIGGER_STATUS, salesChannelId, z.string());
+        }
+        catch (error) {
+            if (error instanceof SettingNotRegistered)
+                return '';
+            if (error instanceof SettingOutOfScopeForChannel)
+                return '';
+            throw error;
+        }
+    }
+    return {
+        async onOrderStatusChanged(payload) {
+            const p = payload;
+            if (!p.orderId || !p.salesChannelId || !p.to)
+                return;
+            const trigger = await readTrigger(p.salesChannelId);
+            if (!trigger || trigger !== p.to)
+                return;
+            const em = deps.emFactory();
+            const existing = await em.findOne(Invoice, { orderId: p.orderId, kind: 'invoice' });
+            if (existing)
+                return; // idempotent
+            let detail;
+            try {
+                detail = await deps.invoiceService.issue(p.orderId, 'invoice', {
+                    issuedBy: 'system',
+                });
+            }
+            catch (error) {
+                // Narrow and after the fact: the order has already moved status and
+                // manual issuance stays available, so a failed automatic attempt must
+                // not take the subscriber down. A switched-off module is not that — it
+                // is a presence answer about the whole operation and is re-thrown.
+                rethrowIfModuleDisabled(error);
+                log('[invoices] the order was not auto-invoiced', {
+                    orderId: p.orderId,
+                    error: error instanceof Error ? error.message : error,
+                });
+                return;
+            }
+            const dispatcher = deps.emailDispatcher;
+            if (!dispatcher) {
+                // Same situation the dispatcher names `no_sender`, one layer earlier:
+                // there is no dispatcher to name it, so the reactor does.
+                log(NOT_EMAILED, {
+                    invoiceId: detail.id,
+                    orderId: p.orderId,
+                    number: detail.number,
+                    reason: 'no_sender',
+                });
+                return;
+            }
+            if (detail.status === 'pending')
+                return;
+            if (!(await dispatcher.sendOnIssueEnabled(detail.salesChannelId)))
+                return;
+            // Nothing catches here: `dispatch` contains its own failures and names
+            // them in the result (FR-029), and the one thing it re-throws is a
+            // presence answer that must reach the bus.
+            const result = await dispatcher.dispatch(detail.id);
+            if (result.sent)
+                return;
+            log(NOT_EMAILED, {
+                invoiceId: detail.id,
+                orderId: p.orderId,
+                number: detail.number,
+                reason: result.reason,
+            });
+        },
+    };
+}
+//# sourceMappingURL=auto-issue-reactor.js.map

package/dist/backend/services/auto-issue-reactor.js.map

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

package/dist/backend/services/corrective-invoice.d.ts

@@ -0,0 +1,38 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+import type { InvoiceNumberGenerator } from './invoice-number-generator.js';
+import type { InvoiceAuditRecorder, InvoiceDomainEventEmitter } from './invoice-service.js';
+import { type LedgerNumberingLookup } from './vendor-number-hold.js';
+import type { CorrectiveInvoiceInput, CorrectiveInvoicePort, CorrectiveInvoiceResult } from '@endora-commerce/contracts';
+/**
+ * Invoices-side implementation of the returns module's `CorrectiveInvoicePort`
+ * (feature 046 / 047 US3). Creates an `invoices` row of kind `correction`:
+ *   - number drawn from the correction counter (per channel/year) when a
+ *     number generator is wired (falls back to a UUID-stamped number otherwise);
+ *   - references the order's original VAT invoice;
+ *   - snapshots the corrected lines into `invoice_lines`, each carrying the VAT
+ *     rate and the unit of the original line it corrects (issues #131, #136.1);
+ *   - caps the credited total at the original invoice gross (FR-020).
+ *
+ * **An order that was never invoiced gets no document** (product ruling
+ * 2026-08-17, issue #135): there is nothing to correct, so the port answers
+ * `{ issued: false, reason: 'order_not_invoiced' }` and the settlement records
+ * the refund without a VAT-shaped document standing in for one that never
+ * existed.
+ */
+export declare class CorrectiveInvoiceProvider implements CorrectiveInvoicePort {
+    private readonly emFactory;
+    private readonly numbers?;
+    private readonly audit?;
+    private readonly events?;
+    private readonly ledgerRouting?;
+    /**
+     * `numbers` is an accessor for the same reason `emFactory` is: the generator
+     * is a gated port, so resolving it is a question about `invoices`' effective
+     * state whose answer changes while the process runs. A composition root that
+     * resolved it while wiring this provider asked at boot, and an operator who
+     * had switched `invoices` off took the backend down with it.
+     */
+    constructor(emFactory: () => EntityManager, numbers?: (() => InvoiceNumberGenerator) | undefined, audit?: InvoiceAuditRecorder | undefined, events?: InvoiceDomainEventEmitter | undefined, ledgerRouting?: LedgerNumberingLookup | undefined);
+    createCorrection(input: CorrectiveInvoiceInput): Promise<CorrectiveInvoiceResult>;
+}
+//# sourceMappingURL=corrective-invoice.d.ts.map

package/dist/backend/services/corrective-invoice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"corrective-invoice.d.ts","sourceRoot":"","sources":["../../../src/backend/services/corrective-invoice.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAK3D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAC5E,OAAO,KAAK,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAC5F,OAAO,EAEL,KAAK,qBAAqB,EAC3B,MAAM,yBAAyB,CAAC;AAMjC,OAAO,KAAK,EACV,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,EACxB,MAAM,4BAA4B,CAAC;AAuCpC;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,yBAA0B,YAAW,qBAAqB;IASnE,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IACxB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC;IAZjC;;;;;;OAMG;gBAEgB,SAAS,EAAE,MAAM,aAAa,EAC9B,OAAO,CAAC,GAAE,MAAM,sBAAsB,aAAA,EACtC,KAAK,CAAC,EAAE,oBAAoB,YAAA,EAC5B,MAAM,CAAC,EAAE,yBAAyB,YAAA,EAClC,aAAa,CAAC,EAAE,qBAAqB,YAAA;IAGlD,gBAAgB,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,uBAAuB,CAAC;CA+MxF"}

package/dist/backend/services/corrective-invoice.js

@@ -0,0 +1,257 @@
+import { randomUUID } from 'crypto';
+import { ERROR_CODES } from '@endora-commerce/contracts';
+import { HttpError } from '@endora-commerce/platform/http';
+import { Invoice } from '../entities/invoice.entity.js';
+import { InvoiceLine } from '../entities/invoice-line.entity.js';
+import { shouldHoldForVendorNumber, } from './vendor-number-hold.js';
+import { rethrowIfModuleDisabled } from '@endora-commerce/platform/kernel';
+import { refuseDuplicateInvoiceNumber } from './duplicate-number-refusal.js';
+function round2(n) {
+    return Math.round((n + Number.EPSILON) * 100) / 100;
+}
+/**
+ * What a corrective line inherits from the line it corrects (product ruling
+ * 2026-08-16, issue #131 and #136.1): the VAT rate and the unit of measure,
+ * never the rate in force on the correction date and never a constant.
+ *
+ * A line naming an order item the original never invoiced is refused —
+ * inventing a rate for an added position is worse than refusing it.
+ */
+function mirrorFor(original, byOrderItem, orderItemId) {
+    const mirrored = byOrderItem.get(orderItemId);
+    if (!mirrored) {
+        throw new HttpError(422, ERROR_CODES.VALIDATION_FAILED, 'The corrected line has no counterpart on the original invoice, so its VAT rate is unknown.', { code: 'no_corrected_line', orderItemId, originalInvoiceId: original.id });
+    }
+    return mirrored;
+}
+/**
+ * Invoices-side implementation of the returns module's `CorrectiveInvoicePort`
+ * (feature 046 / 047 US3). Creates an `invoices` row of kind `correction`:
+ *   - number drawn from the correction counter (per channel/year) when a
+ *     number generator is wired (falls back to a UUID-stamped number otherwise);
+ *   - references the order's original VAT invoice;
+ *   - snapshots the corrected lines into `invoice_lines`, each carrying the VAT
+ *     rate and the unit of the original line it corrects (issues #131, #136.1);
+ *   - caps the credited total at the original invoice gross (FR-020).
+ *
+ * **An order that was never invoiced gets no document** (product ruling
+ * 2026-08-17, issue #135): there is nothing to correct, so the port answers
+ * `{ issued: false, reason: 'order_not_invoiced' }` and the settlement records
+ * the refund without a VAT-shaped document standing in for one that never
+ * existed.
+ */
+export class CorrectiveInvoiceProvider {
+    emFactory;
+    numbers;
+    audit;
+    events;
+    ledgerRouting;
+    /**
+     * `numbers` is an accessor for the same reason `emFactory` is: the generator
+     * is a gated port, so resolving it is a question about `invoices`' effective
+     * state whose answer changes while the process runs. A composition root that
+     * resolved it while wiring this provider asked at boot, and an operator who
+     * had switched `invoices` off took the backend down with it.
+     */
+    constructor(emFactory, numbers, audit, events, ledgerRouting) {
+        this.emFactory = emFactory;
+        this.numbers = numbers;
+        this.audit = audit;
+        this.events = events;
+        this.ledgerRouting = ledgerRouting;
+    }
+    async createCorrection(input) {
+        const em = this.emFactory();
+        // The same correction, asked for twice (D-91). A settlement attempts every
+        // external effect before it writes any state, so a refusal from a later
+        // step leaves a retryable case and the retry arrives here with the key of
+        // the correction this call already issued. Answering with that document is
+        // what keeps one return case to one credit note; the partial unique index
+        // on the column is what keeps two concurrent retries to one as well.
+        if (input.idempotencyKey) {
+            const already = await em.findOne(Invoice, {
+                correctionIdempotencyKey: input.idempotencyKey,
+                kind: 'correction',
+            });
+            if (already) {
+                return {
+                    issued: true,
+                    invoiceId: already.id,
+                    number: already.number,
+                    status: already.status,
+                };
+            }
+        }
+        const original = await em.findOne(Invoice, { orderId: input.orderId, kind: 'invoice' });
+        // No original, no correction (#135). The caller records the refund on the
+        // return case and the payment; only the VAT document is skipped, and the
+        // reason is stated so the caller reports it rather than reporting nothing.
+        if (!original)
+            return { issued: false, reason: 'order_not_invoiced' };
+        // A correction is denominated in the corrected document's currency: the cap
+        // below compares the credited amount with the original gross, and two
+        // amounts in different currencies do not compare (#136.2). Nothing produces
+        // a cross-currency credit today — the return case inherits the order's
+        // currency — so refusing costs nothing and closes the seam. Conversion is
+        // deliberately not attempted here.
+        if (input.currency !== original.currency) {
+            throw new HttpError(422, ERROR_CODES.VALIDATION_FAILED, `A correction must be issued in the corrected invoice's currency (${original.currency}), not ${input.currency}.`, {
+                code: 'correction_currency_mismatch',
+                requestedCurrency: input.currency,
+                originalCurrency: original.currency,
+                originalInvoiceId: original.id,
+            });
+        }
+        // The correction belongs to the corrected document's channel — that is the
+        // numbering series it continues.
+        const salesChannelId = original.salesChannelId ?? null;
+        // Cap the credited total at the original invoice gross (never credit more
+        // than was invoiced).
+        const originalGross = Number(original.total);
+        const requested = round2(input.total);
+        const credited = Math.min(requested, originalGross);
+        // A correction mirrors the line it corrects. The link is `orderItemId`:
+        // issuance snapshots it on every product line of the original, and a return
+        // case item names the same order item.
+        const mirrorByOrderItem = new Map();
+        const originalLines = await em.find(InvoiceLine, { invoiceId: original.id });
+        for (const l of originalLines) {
+            if (l.orderItemId)
+                mirrorByOrderItem.set(l.orderItemId, { rate: Number(l.taxRate), unit: l.unit });
+        }
+        // Resolve every line before the transaction opens, so a line that cannot
+        // be mirrored refuses without having drawn a correction number.
+        //
+        // The credited amount is gross (a return credits what was paid, tax
+        // included), so the net follows from the mirrored rate rather than the
+        // other way round.
+        let remaining = credited;
+        const snapshots = input.lines.map((l, index) => {
+            const mirrored = mirrorFor(original, mirrorByOrderItem, l.orderItemId);
+            const gross = round2(Math.min(Math.max(l.amount, 0), remaining));
+            remaining = round2(remaining - gross);
+            const net = round2(gross / (1 + mirrored.rate));
+            const qty = l.quantity || 1;
+            return {
+                ordinal: index + 1,
+                orderItemId: l.orderItemId,
+                name: l.productName,
+                quantity: qty,
+                rate: mirrored.rate,
+                unit: mirrored.unit,
+                net,
+                gross,
+                unitNetPrice: net / qty,
+            };
+        });
+        // The document's own totals follow its lines: net + tax = the credited
+        // gross, which stays the FR-020 cap.
+        const taxTotal = round2(snapshots.reduce((sum, s) => sum + (s.gross - s.net), 0));
+        const netTotal = round2(credited - taxTotal);
+        const issuedAt = new Date();
+        const holdForVendor = await shouldHoldForVendorNumber(this.ledgerRouting, salesChannelId);
+        // Captured out of the transaction: see the same note in `InvoiceService`.
+        let drawnNumber = null;
+        const runCorrection = async (tx) => {
+            // Draw from the correction counter (a real numbering series to continue)
+            // whenever a generator and a channel are known.
+            let number;
+            if (this.numbers && salesChannelId) {
+                number = await this.numbers().next(tx, 'correction', salesChannelId, issuedAt);
+            }
+            else {
+                number = `KOR-${randomUUID().slice(0, 8).toUpperCase()}`;
+            }
+            drawnNumber = number;
+            const inv = tx.create(Invoice, {
+                orderId: input.orderId,
+                salesChannelId,
+                kind: 'correction',
+                number,
+                issuedAt,
+                // The sale date is a fact about the sale, not about the correction
+                // (product ruling 2026-08-17, #136.4): a credit note reports the date
+                // the goods were delivered or the service performed, which is the
+                // original's sale date. `issuedAt` above is the correction's own issue
+                // date and keeps its meaning — do not collapse the two back together.
+                saleDate: original.saleDate ?? issuedAt.toISOString().slice(0, 10),
+                currency: input.currency,
+                netTotal: netTotal.toFixed(2),
+                taxTotal: taxTotal.toFixed(2),
+                total: credited.toFixed(2),
+                paidTotal: '0',
+                originalInvoiceId: original.id,
+                ...(input.idempotencyKey ? { correctionIdempotencyKey: input.idempotencyKey } : {}),
+                ...(original.buyerSnapshot ? { buyerSnapshot: original.buyerSnapshot } : {}),
+                ...(original.sellerSnapshot ? { sellerSnapshot: original.sellerSnapshot } : {}),
+                issuedBy: 'system',
+                status: holdForVendor ? 'pending' : 'ready',
+            });
+            await tx.persistAndFlush(inv);
+            // Snapshot the corrected lines (already capped at the credited remainder).
+            for (const s of snapshots) {
+                tx.create(InvoiceLine, {
+                    invoiceId: inv.id,
+                    ordinal: s.ordinal,
+                    name: s.name,
+                    // The unit comes from the original line, so a position invoiced in
+                    // `opak.` is credited in `opak.` and not in `szt.` (#136.1).
+                    unit: s.unit,
+                    quantity: String(s.quantity),
+                    unitNetPrice: s.unitNetPrice.toFixed(4),
+                    taxRate: s.rate.toFixed(4),
+                    netValue: s.net.toFixed(2),
+                    grossValue: s.gross.toFixed(2),
+                    orderItemId: s.orderItemId,
+                });
+            }
+            await tx.flush();
+            return inv;
+        };
+        // Feature 078, D-95.2 — a correction draws from the same platform-wide
+        // number space, so it is refused the same way. `rethrowIfModuleDisabled` is
+        // the **first** line: `ModuleDisabledError` is an `HttpError`, so any other
+        // test lets it through by accident rather than by decision, and the
+        // callback reaches this module's own gated number generator.
+        let invoice;
+        try {
+            invoice = await em.transactional(runCorrection);
+        }
+        catch (err) {
+            rethrowIfModuleDisabled(err);
+            await refuseDuplicateInvoiceNumber({
+                error: err,
+                drawnNumber,
+                salesChannelId,
+                emFactory: this.emFactory,
+            });
+            throw err;
+        }
+        if (this.audit) {
+            await this.audit
+                .record({
+                action: 'invoice.corrected',
+                objectType: 'invoice',
+                objectId: invoice.id,
+                stateAfter: {
+                    number: invoice.number,
+                    orderId: input.orderId,
+                    originalInvoiceId: original.id,
+                    credited,
+                },
+            })
+                .catch(() => undefined);
+        }
+        // Feature 059 — domain event for downstream consumers (e.g. KSeF submission).
+        this.events?.emit('invoice.corrected.v1', {
+            eventId: randomUUID(),
+            occurredAt: new Date().toISOString(),
+            invoiceId: invoice.id,
+            originalInvoiceId: original.id,
+            orderId: input.orderId,
+            salesChannelId,
+        });
+        return { issued: true, invoiceId: invoice.id, number: invoice.number, status: invoice.status };
+    }
+}
+//# sourceMappingURL=corrective-invoice.js.map

package/dist/backend/services/corrective-invoice.js.map

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

package/dist/backend/services/cross-module-context.d.ts

@@ -0,0 +1,82 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+import type { AssetReadPort, CustomerAccountReadPort, OrderRecord } from '@endora-commerce/contracts';
+import type { LoadAssetImage } from '../pdf-components/embed-logo-images.js';
+/**
+ * The three facts an invoice needs from outside this module
+ * (`specs/110-instance-repository/` T118c).
+ *
+ * All three were `invoicesBridge` members — closures a composition root wrote,
+ * once in `backend/src/composition.ts` and once in
+ * `backend/test/helpers/test-server.ts`, with the same body in each. They are
+ * functions of what they read rather than of a `ModuleContext`, so
+ * `backend/index.ts` supplies the real inputs and this file is testable over a
+ * stub with nothing composed.
+ *
+ * The other three members of that bridge needed no mapping at all and are not
+ * here: the acting admin and the calling customer are the platform's own
+ * `adminContextResolver` and `customerContextResolver`, read from the cradle,
+ * and the transactional sender is `transactional_emails`' published
+ * `transactionalEmailSenderAccessor`.
+ */
+/**
+ * Where the invoice e-mail goes.
+ *
+ * `customer_accounts` publishes the record; this maps it to the one field the
+ * dispatcher needs and answers `null` when no account resolves, which the
+ * dispatcher reports as `no_recipient` rather than treating as sent.
+ *
+ * **No `catch`, deliberately.** `findById` on a `lazyPort` proxy throws
+ * `ModuleDisabledError` when its owner is absent, and reading that as "this
+ * buyer has no e-mail address" is the fail-open composition checklist item 7
+ * refuses. `customer_accounts` declares `nonDeactivatable`, so it cannot happen
+ * today; the absence of the `catch` is what keeps it fail-closed if that ever
+ * changes.
+ */
+export declare function createRecipientEmailResolver(accounts: Pick<CustomerAccountReadPort, 'findById'>): (order: OrderRecord) => Promise<string | null>;
+/**
+ * The language the invoice e-mail is rendered in.
+ *
+ * A read of the platform's own `SalesChannel` entity through this module's
+ * `EntityManager`, which is what both composition roots did and what `orders`
+ * and `returns` do at the identical site — resolving the language for a
+ * transactional e-mail.
+ *
+ * **Not `salesChannelResolutionPort`**, though the platform contributes it and
+ * its `CachedChannel` carries `defaultLanguage`. That port is the *cache*, and
+ * swapping a direct read for a cached one changes what this answers for a
+ * channel written outside the invalidation path — a design decision about
+ * channel reads rather than a drain's. Constitution XII is untouched either
+ * way: this resolves no request channel, it reads one attribute of the channel
+ * the invoice already names.
+ *
+ * `en-US` for an invoice with no channel, or a channel that is not there, is
+ * the fallback both roots carried.
+ */
+export declare function createChannelLanguageResolver(emFactory: () => EntityManager): (salesChannelId: string | null) => Promise<string>;
+/**
+ * The operator's logo, as bytes pdfmake can inline.
+ *
+ * Two reads on one port, and the order is the point. `findById` is a metadata
+ * question and cheap; `openAssetBytes` moves the object. Asking the cheap one
+ * first is what keeps an asset that is not an image — a slot an operator can
+ * point at anything — from being streamed into this process before it is
+ * refused.
+ *
+ * **What is left here is this module's rule, and nothing about storage.** The
+ * root closure it replaces dispatched on `storageBackend`, knew that `legacy`
+ * has no `open`, knew that the locator falls back to `storageUrl`, and drained
+ * the stream itself; all four are `assets_library`' now, behind
+ * `openAssetBytes`. What cannot go there is which MIME types this consumer can
+ * use: pdfmake embeds PNG and JPEG and nothing else, which is
+ * `embed-logo-images.ts`' rule one layer down and is a fact about a PDF
+ * renderer rather than about an asset library.
+ *
+ * **No `catch`, and that is a change from the closure.** The root wrapped the
+ * storage half in one, because a backend that could not stream had to become an
+ * invoice without a logo rather than an error. That degrade is in
+ * `openAssetBytes`' return type now, where the owner can tell "this asset is
+ * not there" from "the bucket did not answer" — so the only throw that could
+ * still reach here is `ModuleDisabledError`, which must not be absorbed.
+ */
+export declare function createAssetImageLoader(assets: Pick<AssetReadPort, 'findById' | 'openAssetBytes'>): LoadAssetImage;
+//# sourceMappingURL=cross-module-context.d.ts.map

package/dist/backend/services/cross-module-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-module-context.d.ts","sourceRoot":"","sources":["../../../src/backend/services/cross-module-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EACV,aAAa,EACb,uBAAuB,EACvB,WAAW,EACZ,MAAM,4BAA4B,CAAC;AAEpC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AAE7E;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,IAAI,CAAC,uBAAuB,EAAE,UAAU,CAAC,GAClD,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAGhD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,MAAM,aAAa,GAC7B,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,CAKpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,UAAU,GAAG,gBAAgB,CAAC,GACzD,cAAc,CAMhB"}

package/dist/backend/services/cross-module-context.js

@@ -0,0 +1,93 @@
+import { SalesChannel } from '@endora-commerce/platform/kernel';
+/**
+ * The three facts an invoice needs from outside this module
+ * (`specs/110-instance-repository/` T118c).
+ *
+ * All three were `invoicesBridge` members — closures a composition root wrote,
+ * once in `backend/src/composition.ts` and once in
+ * `backend/test/helpers/test-server.ts`, with the same body in each. They are
+ * functions of what they read rather than of a `ModuleContext`, so
+ * `backend/index.ts` supplies the real inputs and this file is testable over a
+ * stub with nothing composed.
+ *
+ * The other three members of that bridge needed no mapping at all and are not
+ * here: the acting admin and the calling customer are the platform's own
+ * `adminContextResolver` and `customerContextResolver`, read from the cradle,
+ * and the transactional sender is `transactional_emails`' published
+ * `transactionalEmailSenderAccessor`.
+ */
+/**
+ * Where the invoice e-mail goes.
+ *
+ * `customer_accounts` publishes the record; this maps it to the one field the
+ * dispatcher needs and answers `null` when no account resolves, which the
+ * dispatcher reports as `no_recipient` rather than treating as sent.
+ *
+ * **No `catch`, deliberately.** `findById` on a `lazyPort` proxy throws
+ * `ModuleDisabledError` when its owner is absent, and reading that as "this
+ * buyer has no e-mail address" is the fail-open composition checklist item 7
+ * refuses. `customer_accounts` declares `nonDeactivatable`, so it cannot happen
+ * today; the absence of the `catch` is what keeps it fail-closed if that ever
+ * changes.
+ */
+export function createRecipientEmailResolver(accounts) {
+    return async (order) => (await accounts.findById(order.placedByCustomerAccountId))?.email ?? null;
+}
+/**
+ * The language the invoice e-mail is rendered in.
+ *
+ * A read of the platform's own `SalesChannel` entity through this module's
+ * `EntityManager`, which is what both composition roots did and what `orders`
+ * and `returns` do at the identical site — resolving the language for a
+ * transactional e-mail.
+ *
+ * **Not `salesChannelResolutionPort`**, though the platform contributes it and
+ * its `CachedChannel` carries `defaultLanguage`. That port is the *cache*, and
+ * swapping a direct read for a cached one changes what this answers for a
+ * channel written outside the invalidation path — a design decision about
+ * channel reads rather than a drain's. Constitution XII is untouched either
+ * way: this resolves no request channel, it reads one attribute of the channel
+ * the invoice already names.
+ *
+ * `en-US` for an invoice with no channel, or a channel that is not there, is
+ * the fallback both roots carried.
+ */
+export function createChannelLanguageResolver(emFactory) {
+    return async (salesChannelId) => (salesChannelId
+        ? (await emFactory().findOne(SalesChannel, { id: salesChannelId }))?.defaultLanguage
+        : null) ?? 'en-US';
+}
+/**
+ * The operator's logo, as bytes pdfmake can inline.
+ *
+ * Two reads on one port, and the order is the point. `findById` is a metadata
+ * question and cheap; `openAssetBytes` moves the object. Asking the cheap one
+ * first is what keeps an asset that is not an image — a slot an operator can
+ * point at anything — from being streamed into this process before it is
+ * refused.
+ *
+ * **What is left here is this module's rule, and nothing about storage.** The
+ * root closure it replaces dispatched on `storageBackend`, knew that `legacy`
+ * has no `open`, knew that the locator falls back to `storageUrl`, and drained
+ * the stream itself; all four are `assets_library`' now, behind
+ * `openAssetBytes`. What cannot go there is which MIME types this consumer can
+ * use: pdfmake embeds PNG and JPEG and nothing else, which is
+ * `embed-logo-images.ts`' rule one layer down and is a fact about a PDF
+ * renderer rather than about an asset library.
+ *
+ * **No `catch`, and that is a change from the closure.** The root wrapped the
+ * storage half in one, because a backend that could not stream had to become an
+ * invoice without a logo rather than an error. That degrade is in
+ * `openAssetBytes`' return type now, where the owner can tell "this asset is
+ * not there" from "the bucket did not answer" — so the only throw that could
+ * still reach here is `ModuleDisabledError`, which must not be absorbed.
+ */
+export function createAssetImageLoader(assets) {
+    return async (assetId) => {
+        const record = await assets.findById(assetId, { liveOnly: true });
+        if (!record || !record.mimeType.startsWith('image/'))
+            return null;
+        return assets.openAssetBytes(assetId);
+    };
+}
+//# sourceMappingURL=cross-module-context.js.map

package/dist/backend/services/cross-module-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-module-context.js","sourceRoot":"","sources":["../../../src/backend/services/cross-module-context.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAGhE;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,4BAA4B,CAC1C,QAAmD;IAEnD,OAAO,KAAK,EAAE,KAAK,EAAE,EAAE,CACrB,CAAC,MAAM,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,yBAAyB,CAAC,CAAC,EAAE,KAAK,IAAI,IAAI,CAAC;AAC9E,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,6BAA6B,CAC3C,SAA8B;IAE9B,OAAO,KAAK,EAAE,cAAc,EAAE,EAAE,CAC9B,CAAC,cAAc;QACb,CAAC,CAAC,CAAC,MAAM,SAAS,EAAE,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,EAAE,EAAE,cAAc,EAAE,CAAC,CAAC,EAAE,eAAe;QACpF,CAAC,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC;AACzB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,sBAAsB,CACpC,MAA0D;IAE1D,OAAO,KAAK,EAAE,OAAO,EAAE,EAAE;QACvB,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QAClE,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,QAAQ,CAAC;YAAE,OAAO,IAAI,CAAC;QAClE,OAAO,MAAM,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;IACxC,CAAC,CAAC;AACJ,CAAC"}