@endora-commerce/contracts 0.100.0

package/dist/invoices.d.ts

@@ -0,0 +1,845 @@
+import { z } from 'zod';
+/**
+ * Invoices (FR-080 + feature 047-invoices-module). Produces proforma, VAT
+ * invoice, and corrective (credit-note) PDFs against orders. The binary
+ * download happens at `GET /orders/:id/invoices/:invoiceId/pdf` (customer) and
+ * `GET /admin/invoices/:id/pdf` (admin); this file defines the JSON metadata,
+ * the seller/company settings shape, the line/VAT-summary snapshots, and the
+ * WYSIWYG template metadata.
+ */
+export declare const invoiceKindSchema: z.ZodEnum<{
+    proforma: "proforma";
+    invoice: "invoice";
+    correction: "correction";
+    wz: "wz";
+}>;
+export type InvoiceKind = z.infer<typeof invoiceKindSchema>;
+/** Whether a row was issued by the platform or imported from an ERP connector. */
+export declare const invoiceOriginSchema: z.ZodEnum<{
+    platform: "platform";
+    erp_import: "erp_import";
+}>;
+export type InvoiceOrigin = z.infer<typeof invoiceOriginSchema>;
+/** Sale-document kind carried inside {@link externalDocumentRefSchema}. */
+export declare const erpSaleDocumentKindSchema: z.ZodEnum<{
+    invoice: "invoice";
+    wz: "wz";
+}>;
+export type ErpSaleDocumentKind = z.infer<typeof erpSaleDocumentKindSchema>;
+/**
+ * Stable identity for an ERP-imported sale document (feature 119, FR-087/FR-088).
+ *
+ * An imported document is identified by the pair `(system, externalId)`: the
+ * source system it was imported from, and its id in that system. Ids from two
+ * source systems come from unrelated id spaces, so the same `externalId` from
+ * another `system` is another document (feature 134, T135; `research.md` D21).
+ *
+ * `system` is also the key an attachment fetch provider registers under
+ * ({@link InvoiceAttachmentFetchRegistryPort}). It is open rather than a literal
+ * since feature 134 (T065): a free contract that enumerates its connectors has
+ * to be edited for every connector that is added, which is the coupling the
+ * seam removes. `externalNumber` is the document number the source system
+ * shows, when it has one.
+ */
+export declare const externalDocumentRefSchema: z.ZodObject<{
+    system: z.ZodString;
+    externalId: z.ZodString;
+    externalNumber: z.ZodOptional<z.ZodString>;
+    documentKind: z.ZodEnum<{
+        invoice: "invoice";
+        wz: "wz";
+    }>;
+}, z.core.$strip>;
+export type ExternalDocumentRef = z.infer<typeof externalDocumentRefSchema>;
+export declare const invoiceStatusSchema: z.ZodEnum<{
+    pending: "pending";
+    cancelled: "cancelled";
+    ready: "ready";
+}>;
+export type InvoiceStatus = z.infer<typeof invoiceStatusSchema>;
+/** Whether the invoice email carries the PDF or a storefront download link. */
+export declare const invoiceDeliveryModeSchema: z.ZodEnum<{
+    attachment: "attachment";
+    link: "link";
+}>;
+export type InvoiceDeliveryMode = z.infer<typeof invoiceDeliveryModeSchema>;
+/**
+ * Seller (own company) data printed on every invoice. Stored as a JSON setting
+ * (`invoices.seller.company_data`); the VAT/NIP lives in a separate
+ * `invoices.seller.tax_id` setting but is surfaced together here at render time.
+ */
+export declare const sellerCompanyDataSchema: z.ZodObject<{
+    legalName: z.ZodString;
+    addressLine1: z.ZodString;
+    addressLine2: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    postalCode: z.ZodString;
+    city: z.ZodString;
+    country: z.ZodString;
+    taxId: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    bankName: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    bankAccount: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    swift: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    email: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    phone: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+}, z.core.$strip>;
+export type SellerCompanyData = z.infer<typeof sellerCompanyDataSchema>;
+/** Buyer (recipient) snapshot captured at issuance. */
+export declare const invoiceBuyerSchema: z.ZodObject<{
+    name: z.ZodString;
+    taxId: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    addressLine1: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    addressLine2: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    postalCode: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    city: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    country: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+}, z.core.$strip>;
+export type InvoiceBuyer = z.infer<typeof invoiceBuyerSchema>;
+/** One immutable invoice line, snapshotted from the order at issuance. */
+export declare const invoiceLineSchema: z.ZodObject<{
+    ordinal: z.ZodNumber;
+    name: z.ZodString;
+    unit: z.ZodString;
+    quantity: z.ZodNumber;
+    unitNetPrice: z.ZodNumber;
+    taxRate: z.ZodNumber;
+    netValue: z.ZodNumber;
+    grossValue: z.ZodNumber;
+}, z.core.$strip>;
+export type InvoiceLine = z.infer<typeof invoiceLineSchema>;
+/** Aggregation per VAT rate; reconciles with the invoice totals. */
+export declare const vatSummaryRowSchema: z.ZodObject<{
+    taxRate: z.ZodNumber;
+    netTotal: z.ZodNumber;
+    vatAmount: z.ZodNumber;
+    grossTotal: z.ZodNumber;
+}, z.core.$strip>;
+export type VatSummaryRow = z.infer<typeof vatSummaryRowSchema>;
+export declare const invoiceSchema: z.ZodObject<{
+    id: z.ZodString;
+    orderId: z.ZodNullable<z.ZodString>;
+    salesChannelId: z.ZodNullable<z.ZodString>;
+    kind: z.ZodEnum<{
+        proforma: "proforma";
+        invoice: "invoice";
+        correction: "correction";
+        wz: "wz";
+    }>;
+    number: z.ZodString;
+    status: z.ZodEnum<{
+        pending: "pending";
+        cancelled: "cancelled";
+        ready: "ready";
+    }>;
+    currency: z.ZodString;
+    issuedAt: z.ZodString;
+    saleDate: z.ZodNullable<z.ZodString>;
+    paymentDueDate: z.ZodNullable<z.ZodString>;
+    paymentMethod: z.ZodNullable<z.ZodString>;
+    netTotal: z.ZodNumber;
+    taxTotal: z.ZodNumber;
+    grossTotal: z.ZodNumber;
+    paidTotal: z.ZodNumber;
+    amountDue: z.ZodNumber;
+    total: z.ZodNumber;
+    originalInvoiceId: z.ZodNullable<z.ZodString>;
+    templateId: z.ZodNullable<z.ZodString>;
+    pdfAssetId: z.ZodNullable<z.ZodString>;
+    ksefReferenceNumber: z.ZodNullable<z.ZodString>;
+    ksefProcessedAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type Invoice = z.infer<typeof invoiceSchema>;
+export declare const invoiceDetailSchema: z.ZodObject<{
+    id: z.ZodString;
+    orderId: z.ZodNullable<z.ZodString>;
+    salesChannelId: z.ZodNullable<z.ZodString>;
+    kind: z.ZodEnum<{
+        proforma: "proforma";
+        invoice: "invoice";
+        correction: "correction";
+        wz: "wz";
+    }>;
+    number: z.ZodString;
+    status: z.ZodEnum<{
+        pending: "pending";
+        cancelled: "cancelled";
+        ready: "ready";
+    }>;
+    currency: z.ZodString;
+    issuedAt: z.ZodString;
+    saleDate: z.ZodNullable<z.ZodString>;
+    paymentDueDate: z.ZodNullable<z.ZodString>;
+    paymentMethod: z.ZodNullable<z.ZodString>;
+    netTotal: z.ZodNumber;
+    taxTotal: z.ZodNumber;
+    grossTotal: z.ZodNumber;
+    paidTotal: z.ZodNumber;
+    amountDue: z.ZodNumber;
+    total: z.ZodNumber;
+    originalInvoiceId: z.ZodNullable<z.ZodString>;
+    templateId: z.ZodNullable<z.ZodString>;
+    pdfAssetId: z.ZodNullable<z.ZodString>;
+    ksefReferenceNumber: z.ZodNullable<z.ZodString>;
+    ksefProcessedAt: z.ZodNullable<z.ZodString>;
+    orderBusinessId: z.ZodNullable<z.ZodString>;
+    lines: z.ZodArray<z.ZodObject<{
+        ordinal: z.ZodNumber;
+        name: z.ZodString;
+        unit: z.ZodString;
+        quantity: z.ZodNumber;
+        unitNetPrice: z.ZodNumber;
+        taxRate: z.ZodNumber;
+        netValue: z.ZodNumber;
+        grossValue: z.ZodNumber;
+    }, z.core.$strip>>;
+    vatSummary: z.ZodArray<z.ZodObject<{
+        taxRate: z.ZodNumber;
+        netTotal: z.ZodNumber;
+        vatAmount: z.ZodNumber;
+        grossTotal: z.ZodNumber;
+    }, z.core.$strip>>;
+    seller: z.ZodObject<{
+        legalName: z.ZodString;
+        addressLine1: z.ZodString;
+        addressLine2: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        postalCode: z.ZodString;
+        city: z.ZodString;
+        country: z.ZodString;
+        taxId: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        bankName: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        bankAccount: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        swift: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        email: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        phone: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    }, z.core.$strip>;
+    buyer: z.ZodObject<{
+        name: z.ZodString;
+        taxId: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        addressLine1: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        addressLine2: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        postalCode: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        city: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        country: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type InvoiceDetail = z.infer<typeof invoiceDetailSchema>;
+/** WYSIWYG (Puck) invoice PDF template metadata. */
+export declare const invoiceTemplateSchema: z.ZodObject<{
+    id: z.ZodString;
+    code: z.ZodString;
+    name: z.ZodString;
+    salesChannelId: z.ZodNullable<z.ZodString>;
+    languages: z.ZodArray<z.ZodString>;
+    active: z.ZodBoolean;
+    isSystem: z.ZodBoolean;
+    version: z.ZodNumber;
+}, z.core.$strip>;
+export type InvoiceTemplate = z.infer<typeof invoiceTemplateSchema>;
+/** Body for issuing an invoice/proforma against an order. */
+export declare const issueInvoiceRequestSchema: z.ZodObject<{
+    kind: z.ZodDefault<z.ZodEnum<{
+        proforma: "proforma";
+        invoice: "invoice";
+    }>>;
+    saleDate: z.ZodOptional<z.ZodString>;
+    paymentDueDate: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type IssueInvoiceRequest = z.infer<typeof issueInvoiceRequestSchema>;
+/** Body for (re)sending the invoice email. */
+export declare const sendInvoiceEmailRequestSchema: z.ZodObject<{
+    mode: z.ZodOptional<z.ZodEnum<{
+        attachment: "attachment";
+        link: "link";
+    }>>;
+}, z.core.$strip>;
+export type SendInvoiceEmailRequest = z.infer<typeof sendInvoiceEmailRequestSchema>;
+/**
+ * Why the invoice e-mail did not go out (issue #103).
+ *
+ * The dispatcher has answered these seven since #103; they only ever reached a
+ * log. They are part of the API shape now because the operator who clicked
+ * "issue" is the one person who can act on them (issue #149).
+ */
+export declare const invoiceEmailNotSentReasonSchema: z.ZodEnum<{
+    failed: "failed";
+    no_sender: "no_sender";
+    invoice_not_found: "invoice_not_found";
+    no_recipient: "no_recipient";
+    deactivated: "deactivated";
+    no_transport: "no_transport";
+    no_definition: "no_definition";
+}>;
+export type InvoiceEmailNotSentReason = z.infer<typeof invoiceEmailNotSentReasonSchema>;
+/**
+ * `POST /admin/invoices/:id/send-email` — the answer to an explicitly requested
+ * re-send. The route has carried it since issue #103; it is written down here
+ * because both admin surfaces used to announce "sent" over it (issue #149).
+ */
+export declare const sendInvoiceEmailResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+}, z.core.$strip>, z.ZodObject<{
+    ok: z.ZodLiteral<false>;
+    reason: z.ZodEnum<{
+        failed: "failed";
+        no_sender: "no_sender";
+        invoice_not_found: "invoice_not_found";
+        no_recipient: "no_recipient";
+        deactivated: "deactivated";
+        no_transport: "no_transport";
+        no_definition: "no_definition";
+    }>;
+}, z.core.$strip>], "ok">;
+export type SendInvoiceEmailResult = z.infer<typeof sendInvoiceEmailResultSchema>;
+/**
+ * What became of the send-on-issue e-mail an issuance triggered (issue #149).
+ *
+ * Three answers, and the middle one is the point: `not_requested` means the
+ * operator switched send-on-issue off for this channel, which is a configured
+ * choice and not a delivery that failed. Reading "no e-mail" out of a missing
+ * field cannot tell those apart, which is how an issuance whose notification was
+ * suppressed came back as a bare 201 saying "issued".
+ *
+ * A suppressed or failed e-mail never invalidates the issuance (FR-029): the
+ * invoice is a legal document that was drawn, numbered and stored, so this
+ * rides **alongside** a 201 rather than turning it into an error.
+ */
+export declare const issueInvoiceEmailOutcomeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    status: z.ZodLiteral<"sent">;
+}, z.core.$strip>, z.ZodObject<{
+    status: z.ZodLiteral<"not_requested">;
+}, z.core.$strip>, z.ZodObject<{
+    status: z.ZodLiteral<"not_sent">;
+    reason: z.ZodEnum<{
+        failed: "failed";
+        no_sender: "no_sender";
+        invoice_not_found: "invoice_not_found";
+        no_recipient: "no_recipient";
+        deactivated: "deactivated";
+        no_transport: "no_transport";
+        no_definition: "no_definition";
+    }>;
+}, z.core.$strip>], "status">;
+export type IssueInvoiceEmailOutcome = z.infer<typeof issueInvoiceEmailOutcomeSchema>;
+/**
+ * `POST /admin/orders/:orderId/invoices` — the issued document plus what became
+ * of its notification. `email` is a sibling of `data`, the way `pagination` is
+ * on a collection: it describes the action, not the invoice, and the invoice
+ * detail shape stays identical on every surface that reads one.
+ */
+export declare const issueInvoiceResponseSchema: z.ZodObject<{
+    data: z.ZodObject<{
+        id: z.ZodString;
+        orderId: z.ZodNullable<z.ZodString>;
+        salesChannelId: z.ZodNullable<z.ZodString>;
+        kind: z.ZodEnum<{
+            proforma: "proforma";
+            invoice: "invoice";
+            correction: "correction";
+            wz: "wz";
+        }>;
+        number: z.ZodString;
+        status: z.ZodEnum<{
+            pending: "pending";
+            cancelled: "cancelled";
+            ready: "ready";
+        }>;
+        currency: z.ZodString;
+        issuedAt: z.ZodString;
+        saleDate: z.ZodNullable<z.ZodString>;
+        paymentDueDate: z.ZodNullable<z.ZodString>;
+        paymentMethod: z.ZodNullable<z.ZodString>;
+        netTotal: z.ZodNumber;
+        taxTotal: z.ZodNumber;
+        grossTotal: z.ZodNumber;
+        paidTotal: z.ZodNumber;
+        amountDue: z.ZodNumber;
+        total: z.ZodNumber;
+        originalInvoiceId: z.ZodNullable<z.ZodString>;
+        templateId: z.ZodNullable<z.ZodString>;
+        pdfAssetId: z.ZodNullable<z.ZodString>;
+        ksefReferenceNumber: z.ZodNullable<z.ZodString>;
+        ksefProcessedAt: z.ZodNullable<z.ZodString>;
+        orderBusinessId: z.ZodNullable<z.ZodString>;
+        lines: z.ZodArray<z.ZodObject<{
+            ordinal: z.ZodNumber;
+            name: z.ZodString;
+            unit: z.ZodString;
+            quantity: z.ZodNumber;
+            unitNetPrice: z.ZodNumber;
+            taxRate: z.ZodNumber;
+            netValue: z.ZodNumber;
+            grossValue: z.ZodNumber;
+        }, z.core.$strip>>;
+        vatSummary: z.ZodArray<z.ZodObject<{
+            taxRate: z.ZodNumber;
+            netTotal: z.ZodNumber;
+            vatAmount: z.ZodNumber;
+            grossTotal: z.ZodNumber;
+        }, z.core.$strip>>;
+        seller: z.ZodObject<{
+            legalName: z.ZodString;
+            addressLine1: z.ZodString;
+            addressLine2: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+            postalCode: z.ZodString;
+            city: z.ZodString;
+            country: z.ZodString;
+            taxId: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+            bankName: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+            bankAccount: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+            swift: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+            email: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+            phone: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, z.core.$strip>;
+        buyer: z.ZodObject<{
+            name: z.ZodString;
+            taxId: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+            addressLine1: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+            addressLine2: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+            postalCode: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+            city: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+            country: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    email: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        status: z.ZodLiteral<"sent">;
+    }, z.core.$strip>, z.ZodObject<{
+        status: z.ZodLiteral<"not_requested">;
+    }, z.core.$strip>, z.ZodObject<{
+        status: z.ZodLiteral<"not_sent">;
+        reason: z.ZodEnum<{
+            failed: "failed";
+            no_sender: "no_sender";
+            invoice_not_found: "invoice_not_found";
+            no_recipient: "no_recipient";
+            deactivated: "deactivated";
+            no_transport: "no_transport";
+            no_definition: "no_definition";
+        }>;
+    }, z.core.$strip>], "status">;
+}, z.core.$strip>;
+export type IssueInvoiceResponse = z.infer<typeof issueInvoiceResponseSchema>;
+/**
+ * An invoice as it crosses a module boundary — a plain shape, never the ORM
+ * entity (FR-011). Every money column stays a decimal string: these are VAT
+ * documents, and a `number` cannot round-trip one.
+ */
+export interface InvoiceRecord {
+    id: string;
+    orderId: string | null;
+    salesChannelId: string | null;
+    kind: InvoiceKind;
+    number: string;
+    issuedAt: Date;
+    /** ISO date (no time) — the tax point, which is not the issue timestamp. */
+    saleDate: string | null;
+    paymentDueDate: string | null;
+    paymentMethod: string | null;
+    currency: string;
+    netTotal: string | null;
+    taxTotal: string | null;
+    total: string;
+    paidTotal: string;
+    /** Set on a `correction`: the document this one credits. */
+    originalInvoiceId: string | null;
+    templateId: string | null;
+    ksefReferenceNumber: string | null;
+    ksefProcessedAt: Date | null;
+    issuedBy: string | null;
+    pdfAssetId: string | null;
+    status: InvoiceStatus;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Container name: `invoiceReadPort`. Owner: `invoices`.
+ *
+ * Four inbound sites read the entity: `orders` listing an order's invoices on
+ * the order screen and again at cancellation, and `ksef` resolving the invoice
+ * behind a submission — twice, once from its entity file, where the read is a
+ * `@TransitivelyScoped` tenancy classification rather than a query and needs
+ * its own remedy (R-05).
+ *
+ * The seller and buyer snapshots are deliberately absent. They are the
+ * document's own frozen copy of two other modules' rows; no cross-module
+ * caller reads them, and publishing them would invite one to.
+ */
+export interface InvoiceReadPort {
+    findById(id: string): Promise<InvoiceRecord | null>;
+    findByIds(ids: readonly string[]): Promise<InvoiceRecord[]>;
+    /**
+     * The document number is the operator's handle on an invoice — `ksef` filters
+     * its submission list by it — so the lookup is published rather than left as
+     * a second module's query over this one's unique index.
+     */
+    findByNumber(number: string): Promise<InvoiceRecord | null>;
+    /** An order's invoices, newest first. */
+    listForOrder(orderId: string): Promise<InvoiceRecord[]>;
+    /** Several orders' invoices at once, for a list screen. */
+    listForOrders(orderIds: readonly string[]): Promise<InvoiceRecord[]>;
+}
+/** One line of a bulk PDF — enough to identify the document it renders. */
+export interface InvoicePdfLine {
+    invoiceNumber: string;
+    total: string;
+    currency: string;
+}
+/**
+ * Container name: `invoicePdfPort`. Owner: `invoices`.
+ *
+ * **A port, although the two builders behind it are pure**, and the exception
+ * is worth stating because FR-013's test does not settle it. "Does switching
+ * the owner off change the answer?" asks whether the *bytes* would differ, and
+ * they would not. The question that decides this one is Constitution XVII's:
+ * should the platform produce an invoice document for a business that has
+ * switched invoicing off? An order screen offering an invoice PDF is a surface
+ * the module owns, and a surface a switched-off module owns must disappear.
+ *
+ * `hashPassword` is the contrast, and it is the right one: it is
+ * platform-generic, reachable from five modules and the dev seed, and nobody
+ * would call hashing "an `auth` surface". A VAT document is an `invoices`
+ * surface.
+ *
+ * Returns `Uint8Array` rather than Node's `Buffer` so this package stays free
+ * of Node types — it is imported by the admin SPA and the storefront too.
+ */
+export interface InvoicePdfPort {
+    renderMinimal(params: {
+        invoiceNumber: string;
+        total: string;
+        currency: string;
+    }): Uint8Array;
+    renderBulk(invoices: readonly InvoicePdfLine[]): Uint8Array;
+}
+export declare const INVOICE_NUMBERING_HOST_PORT: "invoiceNumberingHostPort";
+export declare const INVOICE_PAID_HOST_PORT: "invoicePaidHostPort";
+export declare const INVOICE_COPY_HOST_PORT: "invoiceCopyHostPort";
+export declare const INVOICE_KSEF_ASSIGNMENT_PORT: "invoiceKsefAssignmentPort";
+/**
+ * Container name: `invoiceNumberingHostPort`. Owner: `invoices`.
+ * Ledger vendor number wait (mode B) → ready + unique number.
+ */
+export interface InvoiceNumberingHostPort {
+    applyVendorAssignedNumber(invoiceId: string, number: string): Promise<void>;
+}
+/**
+ * Container name: `invoicePaidHostPort`. Owner: `invoices`.
+ * Infakt `invoice_paid` stamps paidTotal only. Never Payments.
+ */
+export interface InvoicePaidHostPort {
+    recordPaidFromLedger(invoiceId: string): Promise<void>;
+}
+/**
+ * Container name: `invoiceKsefAssignmentPort`. Owner: `invoices`.
+ * Native ksef and Infakt delegated KSeF success both call this. Idempotent
+ * same number; 409 on a different number.
+ */
+export interface InvoiceKsefAssignmentPort {
+    recordKsefAssignment(invoiceId: string, assignment: {
+        ksefReferenceNumber: string;
+        ksefProcessedAt: Date;
+    }): Promise<void>;
+}
+/**
+ * Container name: `invoiceCopyHostPort`. Owner: `invoices`.
+ * Ledger / Infakt VAT copy: buyer snapshot and lines, never a catalog write.
+ */
+export interface InvoiceCopyRecord {
+    invoiceId: string;
+    organizationId: string;
+    number: string;
+    kind: InvoiceKind;
+    salesChannelId: string | null;
+    currency: string;
+    saleDate: string | null;
+    paymentDueDate: string | null;
+    paymentMethod: string | null;
+    /** Set on a `correction`: the VAT document this one credits. */
+    originalInvoiceId: string | null;
+    buyer: InvoiceBuyer;
+    lines: InvoiceLine[];
+}
+export interface InvoiceCopyHostPort {
+    getById(invoiceId: string): Promise<InvoiceCopyRecord | null>;
+}
+/** `invoice.issued.v1` payload, emitted when `invoices` issues a VAT invoice or a proforma. */
+export declare const invoiceIssuedEventSchema: z.ZodObject<{
+    invoiceId: z.ZodString;
+    orderId: z.ZodString;
+    kind: z.ZodEnum<{
+        proforma: "proforma";
+        invoice: "invoice";
+    }>;
+    salesChannelId: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type InvoiceIssuedEvent = z.infer<typeof invoiceIssuedEventSchema>;
+/** `invoice.corrected.v1` payload, emitted when `invoices` issues a corrective invoice. */
+export declare const invoiceCorrectedEventSchema: z.ZodObject<{
+    invoiceId: z.ZodString;
+    originalInvoiceId: z.ZodNullable<z.ZodString>;
+    orderId: z.ZodString;
+    salesChannelId: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type InvoiceCorrectedEvent = z.infer<typeof invoiceCorrectedEventSchema>;
+/** One configurable field of an invoice template block, as the builder descriptor serves it. */
+export interface InvoiceTemplateBlockField {
+    type: 'text' | 'textarea' | 'number' | 'select' | 'radio' | 'color';
+    label: string;
+    options?: Array<{
+        label: string;
+        value: string | boolean | number;
+    }>;
+}
+/** What a contributed block tells the invoice template builder about itself. */
+export interface InvoiceTemplateBlockDescription {
+    readonly label: string;
+    readonly fields: Readonly<Record<string, InvoiceTemplateBlockField>>;
+}
+/** A block another module renders onto the invoice PDF. */
+export interface InvoicePdfBlockRegistration {
+    /** The full block name, `<moduleId>.<LocalName>`, exactly as the contributor's manifest declares it. */
+    readonly name: string;
+    /** The declaring module. While it is not present the block is neither rendered nor described. */
+    readonly moduleId: string;
+    /**
+     * `true` when this block prints the invoice's KSeF number itself
+     * (`specs/134-paid-module-extraction/` T137, `research.md` D22 §3(a)). The
+     * number is `invoices`' statutory data and is printed exactly once: while a
+     * block with this flag is present **and placed** in the template being
+     * rendered (present, for the built-in layout), `invoices`' own header row for
+     * the number is suppressed; otherwise the header prints it.
+     */
+    readonly printsKsefReferenceNumber?: boolean;
+    /** Label and field schema for the builder descriptor. */
+    describe(): InvoiceTemplateBlockDescription;
+    /**
+     * Data the block needs beyond the invoice, read once per render — the KSeF
+     * verification link, for instance. A rejection renders the block with
+     * `null`: the data is an enrichment and never fails the document.
+     */
+    resolve?(invoiceId: string): Promise<unknown>;
+    /**
+     * One pdfmake content node. `props` are the stored block props (`{}` in the
+     * built-in layout), and `resolved` is what {@link resolve} answered, or `null`.
+     */
+    render(input: {
+        readonly props: Readonly<Record<string, unknown>>;
+        readonly invoice: InvoiceDetail;
+        readonly locale: string;
+        readonly resolved: unknown;
+    }): unknown;
+}
+/**
+ * Container name: `invoicePdfBlockRegistry`. Owner: `invoices`.
+ *
+ * The registry of contributed PDF blocks. An ungated contribution registry: a
+ * contributor pushes from its boot hook, and `invoices` skips the block of a
+ * contributor that is not present on every render and descriptor read.
+ */
+export interface InvoicePdfBlockRegistryPort {
+    register(registration: InvoicePdfBlockRegistration): void;
+}
+/**
+ * The tokens an invoice numbering pattern may contain. Everything else in a
+ * pattern is literal text.
+ *
+ * `{channel}` renders the sales channel's `code`, uppercased and otherwise
+ * verbatim. The code charset is `/^[a-z][a-z0-9_-]*$/`
+ * (`salesChannelCreateBodySchema`), so uppercasing is injective and no two
+ * channels can produce the same discriminator; the code is also immutable
+ * (the update schema accepts it only when it repeats the current value), so a
+ * number already rendered through `{channel}` can never be retroactively
+ * invalidated by a rename.
+ */
+export declare const INVOICE_NUMBER_TOKENS: readonly ["seq", "seq:N", "channel", "YYYY", "YY", "MM"];
+export type InvoiceNumberToken = (typeof INVOICE_NUMBER_TOKENS)[number];
+/** One channel's numbering series for one document kind. */
+export interface NumberingSeries {
+    readonly salesChannelId: string;
+    readonly salesChannelCode: string;
+    readonly salesChannelName: string;
+    /** The *effective* pattern: the stored value, or the default when it is blank. */
+    readonly pattern: string;
+}
+/** Two series that can render one and the same document number. */
+export interface NumberPatternCollision {
+    readonly a: NumberingSeries;
+    readonly b: NumberingSeries;
+    /** One string both series can render — the proof, for the log and for tests. */
+    readonly example: string;
+}
+/**
+ * Why a single pattern cannot number a series on its own. Today there is one
+ * reason: a pattern with no sequence token renders one string for a whole
+ * year, so it collides with itself on the second document.
+ */
+export type NumberPatternSequenceDefect = 'no_sequence_token';
+export declare const ERP_SALE_DOCUMENT_WRITE_PORT: "erpSaleDocumentWritePort";
+/**
+ * Metadata for a source-system attachment registered on import; bytes arrive on
+ * first download (FR-086). `externalAttachmentId` is the attachment's id in the
+ * source system, unique within its document.
+ */
+export declare const erpSaleDocumentAttachmentInputSchema: z.ZodObject<{
+    externalAttachmentId: z.ZodString;
+    fileName: z.ZodString;
+    contentType: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type ErpSaleDocumentAttachmentInput = z.infer<typeof erpSaleDocumentAttachmentInputSchema>;
+export declare const erpSaleDocumentUpsertInputSchema: z.ZodObject<{
+    organizationId: z.ZodString;
+    orderId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    externalDocumentRef: z.ZodObject<{
+        system: z.ZodString;
+        externalId: z.ZodString;
+        externalNumber: z.ZodOptional<z.ZodString>;
+        documentKind: z.ZodEnum<{
+            invoice: "invoice";
+            wz: "wz";
+        }>;
+    }, z.core.$strip>;
+    kind: z.ZodEnum<{
+        proforma: "proforma";
+        invoice: "invoice";
+        correction: "correction";
+        wz: "wz";
+    }>;
+    number: z.ZodString;
+    currency: z.ZodString;
+    issuedAt: z.ZodString;
+    saleDate: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    paymentDueDate: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    paymentMethod: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    netTotal: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    taxTotal: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    grossTotal: z.ZodString;
+    paidTotal: z.ZodOptional<z.ZodString>;
+    buyerSnapshot: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        name: z.ZodString;
+        taxId: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        addressLine1: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        addressLine2: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        postalCode: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        city: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        country: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    }, z.core.$strip>>>;
+    attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        externalAttachmentId: z.ZodString;
+        fileName: z.ZodString;
+        contentType: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ErpSaleDocumentUpsertInput = z.infer<typeof erpSaleDocumentUpsertInputSchema>;
+export declare const erpSaleDocumentUpsertResultSchema: z.ZodObject<{
+    invoiceId: z.ZodString;
+    created: z.ZodBoolean;
+}, z.core.$strip>;
+export type ErpSaleDocumentUpsertResult = z.infer<typeof erpSaleDocumentUpsertResultSchema>;
+export declare const erpSaleDocumentAttachmentListItemSchema: z.ZodObject<{
+    id: z.ZodString;
+    fileName: z.ZodString;
+    contentType: z.ZodNullable<z.ZodString>;
+    downloadHref: z.ZodString;
+}, z.core.$strip>;
+export type ErpSaleDocumentAttachmentListItem = z.infer<typeof erpSaleDocumentAttachmentListItemSchema>;
+export declare const erpSaleDocumentListItemSchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<{
+        proforma: "proforma";
+        invoice: "invoice";
+        correction: "correction";
+        wz: "wz";
+    }>;
+    number: z.ZodString;
+    documentKind: z.ZodEnum<{
+        invoice: "invoice";
+        wz: "wz";
+    }>;
+    issuedAt: z.ZodString;
+    currency: z.ZodString;
+    total: z.ZodNumber;
+    orderId: z.ZodNullable<z.ZodString>;
+    attachments: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        fileName: z.ZodString;
+        contentType: z.ZodNullable<z.ZodString>;
+        downloadHref: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ErpSaleDocumentListItem = z.infer<typeof erpSaleDocumentListItemSchema>;
+/**
+ * Container name: `erpSaleDocumentWritePort`. Owner: `invoices`.
+ *
+ * An importing connector calls this when it applies a sale document from its
+ * source system (FR-087). `invoices` owns persistence and identifies a document
+ * by `(externalDocumentRef.system, externalDocumentRef.externalId)`; the
+ * connector owns the mapping from its source system and lazy attachment fetch
+ * (FR-088). `upsertImportedDocument` validates its input against
+ * {@link erpSaleDocumentUpsertInputSchema} and writes nothing when it does not
+ * parse.
+ */
+export interface ErpSaleDocumentAttachmentContext {
+    /** The imported document's `externalDocumentRef.system`. */
+    system: string;
+    /** The imported document's `externalDocumentRef.externalId`. */
+    externalId: string;
+    /** The attachment's id in the source system. */
+    externalAttachmentId: string;
+    fileName: string;
+    contentType: string | null;
+}
+export interface ErpSaleDocumentWritePort {
+    upsertImportedDocument(input: ErpSaleDocumentUpsertInput): Promise<ErpSaleDocumentUpsertResult>;
+    resolveAttachmentContext(input: {
+        invoiceId: string;
+        attachmentId: string;
+        organizationId: string;
+    }): Promise<ErpSaleDocumentAttachmentContext | null>;
+    /** Links fetched attachment bytes to an ERP-imported document (feature 119, FR-086). */
+    linkAttachmentAsset(input: {
+        invoiceId: string;
+        attachmentId: string;
+        organizationId: string;
+        assetId: string;
+        contentType?: string | null;
+    }): Promise<boolean>;
+}
+export declare const INVOICE_ATTACHMENT_FETCH_REGISTRY: "invoiceAttachmentFetchRegistry";
+/**
+ * Fetches and stores the bytes of one attachment of an ERP-imported sale
+ * document, on its first download (feature 119, FR-086). Answers the stored
+ * asset, or `null` when the attachment cannot be fetched.
+ *
+ * Implemented by the connector that imported the document. `invoices` calls it
+ * only through its own registry, after it has checked that the invoice and the
+ * attachment belong to the calling organization.
+ */
+export interface InvoiceAttachmentFetchPort {
+    ensureAttachmentBytes(input: {
+        invoiceId: string;
+        attachmentId: string;
+        organizationId: string;
+    }): Promise<{
+        assetId: string;
+    } | null>;
+}
+/** One contributed fetch provider, with the module that contributed it. */
+export interface InvoiceAttachmentFetchRegistration {
+    /** The `externalDocumentRef.system` value of the documents this provider serves. */
+    readonly system: string;
+    /** The contributing module; its effective presence is read on every download. */
+    readonly moduleId: string;
+    readonly provider: InvoiceAttachmentFetchPort;
+}
+/**
+ * Container name: `invoiceAttachmentFetchRegistry`. Owner: `invoices`.
+ *
+ * A contribution registry: a connector registers its provider from a boot
+ * hook, keyed by the source system it imports from. It is an ungated
+ * registration, and `invoices` skips a provider whose module is not
+ * effectively present, so the customer route answers the attachment as not
+ * found rather than reaching a switched-off connector. A second provider for a
+ * system that already has one is refused, not ordered.
+ */
+export interface InvoiceAttachmentFetchRegistryPort {
+    register(registration: InvoiceAttachmentFetchRegistration): void;
+}
+//# sourceMappingURL=invoices.d.ts.map