@sixtyninecommerce/admin 0.8.0 → 0.10.0

package/dist/documents/index.d.ts

@@ -1,5 +1,5 @@
 import { type Page, type Transport } from '@sixtyninecommerce/core';
-import type { Call } from '../types.js';
+import type { Call, ListOptions } from '../types.js';
 /**
  * Which document a call is about. The platform issues three, and every method
  * here that takes a type takes one of these.
@@ -13,14 +13,30 @@ export interface Invoice {
     invoicedOn: string;
     orderId: string;
     languageCode: string;
+    /**
+     * @deprecated An object-storage key, not a link: documents are stored
+     * privately and no URL can be built from it. Use {@link DocumentsModule.downloadUrl}.
+     */
     storageKey: string;
     totalWithTax: number;
     currencyCode: string;
     note: string | null;
     /** Set once a void & reissue reversed it; null while the invoice is live. */
     voidedOn: string | null;
+    /** The credit note that reversed it when it was voided; null while it is live. */
+    reversedByCreditNoteId: string | null;
+    /** The corrected invoice that replaces it (a reissue or a re-bill); null otherwise. */
+    supersededByInvoiceId: string | null;
+    /** On a replacement: the voided invoice it reissues; null otherwise. */
+    reissueOfInvoiceId: string | null;
     /** `standard` for the order's invoice, `supplementary` for an under-charge billed on top. */
     kind: string;
+    /** On a supplementary invoice: the live invoice it adds to; null otherwise. */
+    supplementsInvoiceId: string | null;
+    /** What it billed, frozen when it was issued; null on a standard invoice derived from the order. */
+    lines: DocumentLine[] | null;
+    /** Who numbered it: `platform`, or an ERP's code (`afas`). */
+    numberingProvider: string;
     createdAt: string;
 }
 /** An issued credit note. `totalWithTax` is the POSITIVE value of the credit. */
@@ -34,7 +50,21 @@ export interface CreditNote {
     invoiceId: string;
     /** `correction` | `cancellation` | `return` | `adjustment`. */
     kind: string;
-    /** Null until the PDF has been rendered and stored. */
+    /** On a full reversal: the invoice it voids (`correction`, `cancellation`); null otherwise. */
+    reversalOfInvoiceId: string | null;
+    /** On a return's credit note: the return it settles; null otherwise. */
+    returnId: string | null;
+    /** What it credited, frozen when it was issued; null on a lump-sum credit note. */
+    lines: DocumentLine[] | null;
+    /** The refund that paid it back, when one did; null otherwise. */
+    refundId: string | null;
+    /** Who numbered it: `platform`, or an ERP's code (`afas`). */
+    numberingProvider: string;
+    /**
+     * Null until the PDF has been rendered and stored.
+     * @deprecated An object-storage key, not a link: documents are stored
+     * privately and no URL can be built from it. Use {@link DocumentsModule.downloadUrl}.
+     */
     storageKey: string | null;
     createdAt: string;
 }
@@ -43,9 +73,28 @@ export interface PackingSlip {
     packingSlipNumber: string;
     fulfillmentId: string;
     languageCode: string;
+    /**
+     * @deprecated An object-storage key, not a link: documents are stored
+     * privately and no URL can be built from it. Use {@link DocumentsModule.downloadUrl}.
+     */
     storageKey: string;
     createdAt: string;
 }
+/**
+ * A short-lived link to one stored document PDF, from {@link DocumentsModule.downloadUrl}.
+ */
+export interface DocumentDownloadUrl {
+    /**
+     * A signed GET on private storage. A BEARER link: anyone holding it can
+     * fetch the PDF until {@link expiresAt}. Open it right away; never store it,
+     * log it or send it on.
+     */
+    url: string;
+    /** When the link stops working — five minutes after it was minted. ISO-8601, UTC. */
+    expiresAt: string;
+    /** The PDF's file name, from the document number. */
+    filename: string;
+}
 /**
  * One block as supplied at generation time.
  *
@@ -164,17 +213,28 @@ export interface DocumentDataTotals {
     totalWithTax: number;
 }
 /**
- * Where a document's number came from.
+ * Where a document's number came from. Numbering itself stays platform-owned:
+ * there is no SDK method that allocates or reserves a number.
  *
- * `scope` is modelled rather than assumed. Today every series is per channel;
- * multi-region will issue per legal entity (spec §12.2), and a consumer that
- * reads `scope`/`scopeId` keeps working when that lands — which is why the
- * field exists before there is a second value for it. Numbering itself stays
- * platform-owned: there is no SDK method that allocates or reserves a number.
+ * - `legal_entity`: an invoice or credit note numbered in its legal entity's
+ *   series, which every store of that entity shares; `scopeId` is the entity
+ *   (its Seller id) as frozen when the document was issued. The number is
+ *   unique across the entity's stores.
+ * - `channel`: a store that numbers on its own (no legal entity, or a sandbox),
+ *   every packing slip, and anything a server that predates legal-entity
+ *   numbering reports; `scopeId` is the channel id.
+ *
+ * Handle a value you do not know as `channel`-like: the union may grow.
  */
 export interface DocumentDataNumbering {
-    scope: 'channel';
+    scope: 'channel' | 'legal_entity';
     scopeId: string;
+    /**
+     * Which invoicing provider assigned {@link number}: `platform`, or an ERP such
+     * as `afas` whose number the document carries verbatim. Absent from servers
+     * that predate invoicing providers — read that as `platform`.
+     */
+    provider?: string;
     /** The configured prefix of the series, when the store set one. */
     series: string | null;
     number: string;
@@ -200,7 +260,11 @@ export interface DocumentDataIssuer {
         province?: string;
         country?: string;
     };
+    /** The legal entity's legal name; the {@link name} is its trading name. Absent on older engines. */
+    legalName?: string;
     vatNumber?: string;
+    /** The UK VAT number, when the legal entity has one. Absent on older engines. */
+    vatNumberUk?: string;
     registrationNumber?: string;
 }
 /**
@@ -271,6 +335,250 @@ export interface DocumentData {
         orderCodes: string[];
     };
 }
+/** Which book an invoice is in: the store's own invoices, or the accounts-receivable ledger. */
+export type InvoiceCorrectionLedger = 'RETAIL' | 'AR';
+/** What is wrong with an issued invoice. One outcome is one operation. */
+export type InvoiceCorrectionOutcome = 
+/** We charged too much and the customer keeps the goods: a partial credit note. */
+'OVER_CHARGE'
+/** The details are wrong, the sale is fine: a full credit note and a corrected invoice. */
+ | 'DETAILS_WRONG'
+/** The invoice should not exist: a full credit note, the invoice voided. */
+ | 'SHOULD_NOT_EXIST'
+/** We charged too little: a supplementary invoice; both stay owed. */
+ | 'UNDER_CHARGE';
+/** The billing or shipping fields a details correction changes; a field left out keeps its value. */
+export interface InvoiceAddressCorrection {
+    fullName?: string;
+    company?: string;
+    streetLine1?: string;
+    streetLine2?: string;
+    city?: string;
+    province?: string;
+    postalCode?: string;
+    countryCode?: string;
+    country?: string;
+    phoneNumber?: string;
+}
+/** What {@link DocumentsModule.planCorrection} is asked. */
+export interface InvoiceCorrectionInput {
+    ledger: InvoiceCorrectionLedger;
+    /** A store invoice's id (`RETAIL`) or an AR invoice's (`AR`). */
+    invoiceId: string;
+    /** Omitted: only which outcomes are available and the lines a correction starts from. */
+    outcome?: InvoiceCorrectionOutcome;
+    /** Printed on a credit note (required there); the note of a supplementary invoice. At most 500. */
+    reason?: string;
+    /**
+     * The lines, in the basis `prefill.basis` states. Omitted: the prefill for an outcome that
+     * starts from it, none for an under-charge. At most 200. A `prefill.lines` row is sent back as
+     * it came (its `sku` and `orderLineId` may be null).
+     */
+    lines?: Array<DocumentLineInput | InvoiceCorrectionLine>;
+    /** Details wrong only. */
+    billingAddress?: InvoiceAddressCorrection;
+    /** Details wrong only. */
+    shippingAddress?: InvoiceAddressCorrection;
+    /** RETAIL only: refund the credited amount to this payment (one of `refund.options`). */
+    refundPaymentId?: string;
+    /** RETAIL only: move the credited amount to the customer's account instead (`accountCredit`). */
+    creditToAccount?: boolean;
+}
+/** One line a correction states, every key present. */
+export interface InvoiceCorrectionLine {
+    description: string;
+    sku: string | null;
+    orderLineId: string | null;
+    quantity: number;
+    unitPrice: number;
+    unitPriceBasis: 'net' | 'gross';
+    taxRate: number;
+}
+/** One line of a document, as it would be frozen. Money in minor units. */
+export interface DocumentLine {
+    description: string;
+    /** Empty for a free-form row. */
+    sku: string;
+    orderLineId: string | null;
+    quantity: number;
+    /** Display only on a gross-entered line. */
+    unitPriceNet: number;
+    /** Display only on a net-entered line. */
+    unitPriceWithTax: number;
+    taxRate: number;
+    lineTotalNet: number;
+    lineTotalWithTax: number;
+    unitPriceBasis: 'net' | 'gross';
+}
+/** Totals of a planned document, or of the lines being typed. */
+export interface InvoiceCorrectionTotals {
+    /** Null when the document states its gross only (a reversal whose split cannot be derived). */
+    net: number | null;
+    tax: number | null;
+    gross: number;
+    taxSummary: Array<{
+        taxRate: number;
+        net: number;
+        tax: number;
+        gross: number;
+    }>;
+}
+/** A document a correction would issue. It carries no number: a plan never draws one. */
+export interface InvoiceCorrectionDocument {
+    type: 'INVOICE' | 'CREDIT_NOTE';
+    /** `adjustment`, `correction`, `cancellation`, `standard` or `supplementary`. */
+    kind: string;
+    /** The date it would state: today in the store's numbering zone. */
+    documentDate: string;
+    currencyCode: string;
+    /** Null when it states a lump sum, or bills the order. */
+    lines: DocumentLine[] | null;
+    totals: InvoiceCorrectionTotals;
+    /** The issuer it would freeze, in `documentData`'s issuer shape. */
+    issuer: unknown;
+    numbering: {
+        /** Who would number it: `platform`, or an ERP's code (`afas`). */
+        provider: string;
+        providerLabel: string;
+        /**
+         * Booked in a system outside the platform: once issued, the document is corrected THERE,
+         * never undone from the platform.
+         */
+        external: boolean;
+        /** It could be numbered now; when not, a blocker carries the provider's refusal. */
+        ready: boolean;
+        legalEntityId: string | null;
+        testStore: boolean;
+    };
+}
+/** What {@link DocumentsModule.planCorrection} answers. Money in minor units. */
+export interface InvoiceCorrectionPlan {
+    /** Names this plan; it moves when the invoice, its order, the payments or the input move. */
+    planHash: string;
+    ledger: InvoiceCorrectionLedger;
+    invoice: {
+        id: string;
+        invoiceNumber: string;
+        kind: string;
+        totalWithTax: number;
+        /** What may still be credited against it. */
+        creditable: number;
+        currencyCode: string;
+        orderIds: string[];
+        voidedOn: string | null;
+    };
+    /** The four outcomes, in the order a wizard asks them. */
+    outcomes: Array<{
+        outcome: InvoiceCorrectionOutcome;
+        available: boolean;
+        /** The first reason it is not, as the operation would refuse it. */
+        unavailableCode: string | null;
+        unavailableMessage: string | null;
+        document: 'CREDIT_NOTE' | 'CREDIT_NOTE_AND_INVOICE' | 'INVOICE';
+        needsLines: boolean;
+        prefillsLines: boolean;
+        needsAddresses: boolean;
+        allowsRefund: boolean;
+        allowsNote: boolean;
+    }>;
+    /** The lines a correction starts from. `differs`: they do not add up to the invoice. */
+    prefill: {
+        source: 'snapshot' | 'order' | 'none';
+        basis: 'net' | 'gross';
+        lines: InvoiceCorrectionLine[];
+        seededGross: number;
+        billedGross: number;
+        differs: boolean;
+    };
+    outcome: InvoiceCorrectionOutcome | null;
+    operation: 'ISSUE_PARTIAL_CREDIT_NOTE' | 'VOID_AND_REBILL' | 'VOID_AND_REISSUE' | 'VOID' | 'ISSUE_SUPPLEMENTARY' | null;
+    /** The running total of the lines the input states: the issue's own figure. */
+    lineTotals: InvoiceCorrectionTotals;
+    documents: InvoiceCorrectionDocument[];
+    /** Null when the outcome gives nothing back. */
+    refund: {
+        amount: number;
+        available: boolean;
+        unavailableCode: string | null;
+        unavailableMessage: string | null;
+        /** The payments a refund can go to now, newest first (the order's refund position). */
+        options: Array<{
+            paymentId: string;
+            method: string | null;
+            amount: number;
+            refundable: number;
+        }>;
+        recommendedPaymentId: string | null;
+    } | null;
+    /** Null where the plan offers no choice (the AR ledger, an outcome that gives nothing back). */
+    accountCredit: {
+        available: boolean;
+        unavailableCode: string | null;
+        message: string | null;
+    } | null;
+    settlement: 'NONE' | 'REFUND' | 'ACCOUNT_CREDIT';
+    /** Everything that stops this correction. Empty: it can be committed. */
+    blockers: Array<{
+        code: string;
+        message: string;
+        path: string | null;
+    }>;
+}
+/** A document {@link DocumentsModule.commitCorrection} issued, on either ledger. */
+export interface InvoiceCorrectionCommittedDocument {
+    /** `RETAIL`: an {@link Invoice} or {@link CreditNote} of the order; `AR`: the AR ledger's. */
+    ledger: InvoiceCorrectionLedger;
+    type: 'INVOICE' | 'CREDIT_NOTE';
+    id: string;
+    /** Its number, as printed. */
+    number: string;
+    /** `adjustment`, `correction`, `cancellation`, `standard` or `supplementary`. */
+    kind: string;
+    /** Minor units; a credit note's is the positive value of the credit. */
+    totalWithTax: number;
+    currencyCode: string;
+    /** The date it states, `YYYY-MM-DD`. */
+    issuedOn: string;
+    /** Who numbered it: `platform`, or an ERP's code (booked there, corrected there). */
+    numberingProvider: string;
+}
+/** What {@link DocumentsModule.commitCorrection} carried out. Money in minor units. */
+export interface InvoiceCorrectionCommit {
+    /**
+     * The plan that was carried out, as {@link DocumentsModule.planCorrection} answered it. A repeat
+     * under the same `idempotencyKey` answers the plan as it was, and the documents and refund as
+     * they are now.
+     */
+    plan: InvoiceCorrectionPlan;
+    /** What was issued, in issuing order (a reversal before its replacement). */
+    documents: InvoiceCorrectionCommittedDocument[];
+    /** The refund it made (`refundPaymentId`); null otherwise. */
+    refund: {
+        id: string;
+        /** `Pending` until a gateway confirms it, `Settled` for money returned by hand. */
+        state: string;
+        total: number;
+        paymentId: string;
+    } | null;
+    /** The account credit it made (`creditToAccount`); null otherwise. */
+    accountCredit: {
+        amount: number;
+        currencyCode: string;
+        /** The receipts on the customer's account, one per payment the money came from. */
+        unappliedCashIds: string[];
+    } | null;
+}
+export interface CommitInvoiceCorrectionCall extends Call {
+    /** The `planHash` of the plan the merchant saw ({@link DocumentsModule.planCorrection}). Required. */
+    expectedPlanHash: string;
+    /**
+     * One key per attempt to commit, re-sent unchanged on a retry of THAT attempt. Pass your own:
+     * left out, one is made up (a UUIDv7) and returned as `idempotencyKey` on the result, but on a
+     * thrown error only as an untyped own property of the error. Never reuse a key for another
+     * correction or a fresh attempt.
+     */
+    idempotencyKey?: string;
+}
 /** What `generate` needs, per document type. */
 export interface GenerateDocumentOptions extends Call {
     /**
@@ -330,6 +638,40 @@ export interface SendInvoiceEmailInput {
     recipientsTo: string[];
     recipientsCc?: string[];
 }
+export interface SendCreditNoteEmailInput {
+    /** A credit note of this store (see {@link DocumentsModule.creditNotes}). */
+    creditNoteId: string;
+    /** At least one, at most 10. */
+    recipientsTo: string[];
+    /** At most 10; one already in `recipientsTo` is dropped. */
+    recipientsCc?: string[];
+}
+/** One "Email the credit note" send, as recorded once the email went out. */
+export interface CreditNoteEmailSend {
+    id: string;
+    orderId: string;
+    creditNoteId: string;
+    /** Who it went to: a sandbox store's withheld customer is not listed. */
+    recipientsTo: string[];
+    recipientsCc: string[];
+    createdAt: string;
+}
+/**
+ * One of a customer's documents in this store, from {@link DocumentsModule.forCustomer}: a retail
+ * invoice or credit note, with the order it was issued for.
+ */
+export interface CustomerDocument {
+    /**
+     * `invoice` or `credit-note`; exactly one of {@link invoice} and {@link creditNote} is set, the
+     * one this names. Typed open, like the other document kinds here: a value this SDK does not know
+     * is passed through as the server spelled it.
+     */
+    type: 'invoice' | 'credit-note' | (string & {});
+    invoice: Invoice | null;
+    creditNote: CreditNote | null;
+    orderId: string;
+    orderCode: string;
+}
 /** The store's extension-block registry. Reading needs `ReadSettings`, writing `UpdateSettings`. */
 export interface DocumentExtensionsModule {
     /**
@@ -396,10 +738,37 @@ export interface DocumentsModule {
     generate(subjectId: string, type: 'packing-slip', options?: Omit<GenerateDocumentOptions, 'invoicedOn' | 'note'>): Promise<PackingSlip>;
     /** The numbered facts a document was built from. Needs `ReadOrder`. */
     data(documentId: string, type: DocumentType, options?: Call): Promise<DocumentData>;
+    /**
+     * A five-minute download link for one of this store's documents. Needs
+     * `ReadOrder`.
+     *
+     * Documents carry customer names and addresses and are stored privately:
+     * there is no permanent URL, and `storageKey` is not one. Mint a link when
+     * the user asks for the file and open it straight away — the link is a
+     * bearer capability until it expires, so never persist it. Each call is on
+     * the store's audit trail.
+     *
+     * `ENTITY_NOT_FOUND` (→ `NotFoundError`) for a document outside this store
+     * or of another type; `DOCUMENT_PDF_NOT_AVAILABLE` when no PDF is stored for
+     * it (a credit note whose render has not landed).
+     */
+    downloadUrl(documentId: string, type: DocumentType, options?: Call): Promise<DocumentDownloadUrl>;
     /** Every invoice of an order, including voided ones. */
     invoices(orderId: string, options?: Call): Promise<Page<Invoice>>;
     /** Every credit note of an order. */
     creditNotes(orderId: string, options?: Call): Promise<Page<CreditNote>>;
+    /**
+     * The retail invoices and credit notes of a customer's orders in THIS store, newest first (the
+     * date each document states, then when it was issued). Voided invoices are listed, with
+     * `voidedOn` set; accounts-receivable documents are not. A customer row several stores hold
+     * answers only this store's documents. Needs `ReadOrder`.
+     *
+     * Paged: `limit` 1 to 100 (default 25), and `after` the previous page's cursor; the page says
+     * the `total`. `ENTITY_NOT_FOUND` (→ `NotFoundError`) for a customer this store does not hold;
+     * a `limit` outside 1 to 100 is refused `USER_INPUT_ERROR` (→ `ValidationError`). An engine
+     * older than this method fails the document's validation.
+     */
+    forCustomer(customerId: string, options?: ListOptions): Promise<Page<CustomerDocument>>;
     /**
      * Render what an invoice WOULD look like, without numbering or storing one.
      * Returns the PDF bytes (the wire carries base64; this decodes it).
@@ -411,21 +780,149 @@ export interface DocumentsModule {
     } & Call): Promise<Uint8Array>;
     /** Email an order's invoice. True when the dispatch was accepted. */
     sendInvoiceEmail(input: SendInvoiceEmailInput, options?: Call): Promise<boolean>;
-    /** Credit PART of a still-valid invoice; the invoice keeps standing. */
+    /**
+     * Email one of this store's credit notes: the same email and PDF the
+     * customer gets when it is issued, to the recipients given, in the credited
+     * invoice's language. True once it went out; each send is recorded (see
+     * {@link creditNoteEmailSends}). Needs `UpdateOrder`.
+     *
+     * `ENTITY_NOT_FOUND` (→ `NotFoundError`) for a credit note outside this
+     * store; `CREDIT_NOTE_EMAIL_RECIPIENTS_INVALID` (→ `ValidationError`);
+     * `CREDIT_NOTE_PDF_NOT_AVAILABLE` (its PDF could not be rendered, nothing was
+     * sent), `CREDIT_NOTE_EMAIL_UNAVAILABLE` and `CREDIT_NOTE_EMAIL_SEND_FAILED`
+     * (the email provider's code when it gave one; its reason is in the email deliveries log) (→ `BusinessRuleError`).
+     */
+    sendCreditNoteEmail(input: SendCreditNoteEmailInput, options?: Call): Promise<boolean>;
+    /** Every "Email the credit note" send of an order, newest first. Needs `ReadOrder`. */
+    creditNoteEmailSends(orderId: string, options?: Call): Promise<Page<CreditNoteEmailSend>>;
+    /**
+     * Credit PART of a still-valid invoice; the invoice keeps standing.
+     *
+     * With `refundPaymentId`, the credited amount is refunded first and the
+     * document follows. **`IDEMPOTENCY_OUTCOME_UNKNOWN` is neither success nor
+     * refusal**, exactly as on `payments.refund`: the refund reached the payment
+     * provider and was never confirmed, so the money may be on its way back. No
+     * credit note was issued, and the platform will not ask for that refund
+     * again — a retry with the same payment and amount answers the same code. Do
+     * NOT treat it as a refusal: reconcile the payment with the provider first.
+     * If the refund was made, issue the credit note without `refundPaymentId`;
+     * if it was not, refund the payment separately, then issue it without one.
+     * The GraphQL error carries the handles in `extensions.movement`
+     * (`refundId`, `paymentId`, `providerTransactionId`), which `PlatformError`
+     * does not surface — read them off the order's payments.
+     *
+     * **Coded refusals** (nothing is refunded or issued): `INVOICE_NOT_FOUND` and
+     * `INVOICE_PAYMENT_NOT_FOUND` (→ `NotFoundError`); `ORDER_NOT_INVOICED`,
+     * `INVOICE_ORDER_MISMATCH`, `INVOICE_ALREADY_VOIDED`,
+     * `INVOICE_CREDIT_EXCEEDS_INVOICE`, `REFUND_TARGET_NOT_REFUNDABLE`,
+     * `REFUND_WOULD_DOUBLE_CREDIT`, `REFUND_PAYMENT_UNCOLLECTED`,
+     * `REFUND_ORPHAN_EXISTS` (a refund on ANY payment of the order that no credit note names:
+     * issue the credit note without `refundPaymentId`) and `REFUND_EXCEEDS_PAYMENT`
+     * (→ `BusinessRuleError`).
+     * An engine before these codes answered each one as `USER_INPUT_ERROR`
+     * (`ValidationError`) with the same sentence. Field-shape refusals (an empty
+     * reason, an invalid line) stay `USER_INPUT_ERROR`.
+     */
     issuePartialCreditNote(input: IssuePartialCreditNoteInput, options?: Call): Promise<CreditNote>;
-    /** Bill an under-charge as a supplementary invoice; both invoices stay owed. */
+    /**
+     * What a correction of an issued invoice would issue, give back and refuse, before anything
+     * is written. Without an `outcome` it answers which outcomes the invoice can take and the
+     * lines a correction starts from (a wizard's first step); with one, the operation, every
+     * `blocker`, the documents (date, lines, totals, tax split, issuer, who would number them) and
+     * the refund and account-credit options.
+     *
+     * **It writes nothing and never shows or reserves a number.** A credit note follows its
+     * invoice's provider: on an ERP-numbered store (`documents[].numbering.external`), committing
+     * the correction BOOKS the documents in the ERP, and that cannot be undone from the platform.
+     * Refund options are the order's refund position (`payments.refundPosition`). While a refund
+     * of the order stands that no credit note names, on any payment, the money went back once
+     * already: `refund` and `accountCredit` are unavailable with `REFUND_ORPHAN_EXISTS` (a blocker
+     * when either is asked for), and the correction can still be issued on its own. `planHash`
+     * changes when the invoice, its order, the payments, the numbering or the input change.
+     *
+     * What would stop the correction is a `blocker`, not an error: `INVOICE_CORRECTION_*`, the
+     * issuing door's own codes (`INVOICE_HAS_PARTIAL_CREDITS`, `REFUND_EXCEEDS_PAYMENT`, …) and
+     * the numbering provider's (`INVOICING_PROVIDER_NOT_READY`, …). Refusals of the call:
+     * `INVOICE_CORRECTION_INVOICE_NOT_FOUND` (→ `NotFoundError`; another store's invoice too),
+     * `INVALID_INVOICE_CORRECTION_INPUT` (→ `ValidationError`, `details[].field` names the field)
+     * and `INVOICE_CORRECTION_LEDGER_NOT_ALLOWED` (→ `PermissionDeniedError`: AR on a store
+     * without the AR ledger). Needs `UpdateOrder`. An engine older than this method fails the
+     * document's validation.
+     */
+    planCorrection(input: InvoiceCorrectionInput, options?: Call): Promise<InvoiceCorrectionPlan>;
+    /**
+     * Carry out a correction as its plan ({@link planCorrection}) states it, once: the documents it
+     * previewed, and the refund or the account credit it settled on. Needs `UpdateOrder`, and an
+     * engine that serves `commitInvoiceCorrection`.
+     *
+     * Hand it the SAME `input` you planned and the plan's `planHash` as `expectedPlanHash`. The
+     * engine plans again under the issuing services' locks and carries it out only when the hash
+     * is yours and nothing blocks; otherwise nothing is issued. Without a refund everything is ONE
+     * transaction. With `refundPaymentId` the refund comes first and the credit note follows: a
+     * refund the provider confirmed stays even when the credit note cannot follow.
+     *
+     * `idempotencyKey`: one per attempt. A retry of that attempt (a timeout, a dropped connection)
+     * re-sends it and gets the first answer back, with nothing issued or refunded twice. Left out,
+     * one is made up and returned as `idempotencyKey` on the result and on a thrown error.
+     *
+     * Refusals, with nothing issued:
+     * - `INVOICE_CORRECTION_PLAN_CONFLICT` (`ConflictError`, 409): the invoice, its order, the
+     *   payments, the numbering or the date moved since the plan. Plan again, show the merchant
+     *   the new plan, and commit under a NEW key.
+     * - `INVOICE_CORRECTION_BLOCKED` (`BusinessRuleError`, 422): the plan has blockers, or a
+     *   document's numbering provider refused it before anything was numbered (an ERP's debtor,
+     *   article or VAT checks); `error.details` lists them, `code` = the blocker's code.
+     * - `IDEMPOTENCY_CONFLICT` (409): the key was used for another request.
+     * - `REFUND_REFUSED` (`BusinessRuleError`, 422): the payment provider, or the engine before it
+     *   asked the provider, refused the refund; nothing moved. A provider's refusal stays on the
+     *   payment as a `Failed` refund, which moves the plan: once the payment can take the refund,
+     *   plan again and commit the new plan under a NEW key.
+     * - {@link planCorrection}'s refusals of the call.
+     *
+     * `IDEMPOTENCY_OUTCOME_UNKNOWN` (`error.outcomeUnknown`) is neither success nor refusal. Either
+     * the refund reached the payment provider and its answer never came (no credit note was
+     * issued; record the provider's answer with `admin.payments.reconcileRefund`, which frees the
+     * key, then plan again), or the refund was made and the credit note could not follow (plan
+     * again: it is issued without a refund). Never retry blind under a new key.
+     *
+     * On an ERP-numbered store (`documents[].numberingProvider`), the documents are booked in the
+     * ERP and cannot be undone from the platform.
+     */
+    commitCorrection(input: InvoiceCorrectionInput, options: CommitInvoiceCorrectionCall): Promise<InvoiceCorrectionCommit & {
+        idempotencyKey: string;
+    }>;
+    /**
+     * Bill an under-charge as a supplementary invoice; both invoices stay owed.
+     *
+     * **Coded refusals** (nothing is numbered or issued): `INVOICE_NOT_FOUND` (→ `NotFoundError`);
+     * `INVOICE_ORDER_MISMATCH`, `INVOICE_ALREADY_VOIDED`, `INVOICE_NOT_SUPPLEMENTABLE` (the target
+     * is itself a supplementary invoice), `INVOICE_ORDER_STATE_BLOCKS_SUPPLEMENT` and
+     * `INVOICE_GENERATION_DISABLED` (→ `BusinessRuleError`). An engine before these codes answered
+     * the first four as `USER_INPUT_ERROR` (`ValidationError`) with the same sentence, and the last
+     * two as an uncoded error. Field-shape refusals (an invalid line) stay `USER_INPUT_ERROR`.
+     */
     issueSupplementaryInvoice(input: IssueSupplementaryInvoiceInput, options?: Call): Promise<Invoice>;
     extensions: DocumentExtensionsModule;
 }
-export declare const GENERATE_INVOICE_MUTATION = "\n  mutation GenerateInvoice(\n    $orderId: ID!\n    $invoicedOn: String!\n    $languageCode: String\n    $note: String\n    $extensions: [DocumentExtensionInput!]\n  ) {\n    generateInvoice(\n      orderId: $orderId\n      invoicedOn: $invoicedOn\n      languageCode: $languageCode\n      note: $note\n      extensions: $extensions\n    ) { \n  id\n  invoiceNumber\n  invoicedOn\n  orderId\n  languageCode\n  storageKey\n  totalWithTax\n  currencyCode\n  note\n  voidedOn\n  kind\n  createdAt\n }\n  }\n";
+export declare const GENERATE_INVOICE_MUTATION = "\n  mutation GenerateInvoice(\n    $orderId: ID!\n    $invoicedOn: String!\n    $languageCode: String\n    $note: String\n    $extensions: [DocumentExtensionInput!]\n  ) {\n    generateInvoice(\n      orderId: $orderId\n      invoicedOn: $invoicedOn\n      languageCode: $languageCode\n      note: $note\n      extensions: $extensions\n    ) { \n  id\n  invoiceNumber\n  invoicedOn\n  orderId\n  languageCode\n  storageKey\n  totalWithTax\n  currencyCode\n  note\n  voidedOn\n  reversedByCreditNoteId\n  supersededByInvoiceId\n  reissueOfInvoiceId\n  kind\n  supplementsInvoiceId\n  lines { \n  description\n  sku\n  orderLineId\n  quantity\n  unitPriceNet\n  unitPriceWithTax\n  taxRate\n  lineTotalNet\n  lineTotalWithTax\n  unitPriceBasis\n }\n  numberingProvider\n  createdAt\n }\n  }\n";
 export declare const GENERATE_PACKING_SLIP_MUTATION = "\n  mutation GeneratePackingSlip(\n    $fulfillmentId: ID!\n    $languageCode: String\n    $extensions: [DocumentExtensionInput!]\n  ) {\n    generatePackingSlip(\n      fulfillmentId: $fulfillmentId\n      languageCode: $languageCode\n      extensions: $extensions\n    ) { \n  id\n  packingSlipNumber\n  fulfillmentId\n  languageCode\n  storageKey\n  createdAt\n }\n  }\n";
 export declare const DOCUMENT_DATA_QUERY = "\n  query DocumentData($documentId: ID!, $type: DocumentType!) {\n    documentData(documentId: $documentId, type: $type)\n  }\n";
-export declare const ORDER_INVOICES_QUERY = "\n  query OrderInvoices($orderId: ID!) {\n    orderInvoices(orderId: $orderId) { \n  id\n  invoiceNumber\n  invoicedOn\n  orderId\n  languageCode\n  storageKey\n  totalWithTax\n  currencyCode\n  note\n  voidedOn\n  kind\n  createdAt\n }\n  }\n";
-export declare const ORDER_CREDIT_NOTES_QUERY = "\n  query OrderCreditNotes($orderId: ID!) {\n    orderCreditNotes(orderId: $orderId) { \n  id\n  creditNoteNumber\n  issuedOn\n  totalWithTax\n  currencyCode\n  reason\n  invoiceId\n  kind\n  storageKey\n  createdAt\n }\n  }\n";
+export declare const CREATE_DOCUMENT_DOWNLOAD_URL_MUTATION = "\n  mutation CreateDocumentDownloadUrl($documentId: ID!, $type: DocumentType!) {\n    createDocumentDownloadUrl(documentId: $documentId, type: $type) {\n      url\n      expiresAt\n      filename\n    }\n  }\n";
+export declare const ORDER_INVOICES_QUERY = "\n  query OrderInvoices($orderId: ID!) {\n    orderInvoices(orderId: $orderId) { \n  id\n  invoiceNumber\n  invoicedOn\n  orderId\n  languageCode\n  storageKey\n  totalWithTax\n  currencyCode\n  note\n  voidedOn\n  reversedByCreditNoteId\n  supersededByInvoiceId\n  reissueOfInvoiceId\n  kind\n  supplementsInvoiceId\n  lines { \n  description\n  sku\n  orderLineId\n  quantity\n  unitPriceNet\n  unitPriceWithTax\n  taxRate\n  lineTotalNet\n  lineTotalWithTax\n  unitPriceBasis\n }\n  numberingProvider\n  createdAt\n }\n  }\n";
+export declare const ORDER_CREDIT_NOTES_QUERY = "\n  query OrderCreditNotes($orderId: ID!) {\n    orderCreditNotes(orderId: $orderId) { \n  id\n  creditNoteNumber\n  issuedOn\n  totalWithTax\n  currencyCode\n  reason\n  invoiceId\n  kind\n  reversalOfInvoiceId\n  returnId\n  lines { \n  description\n  sku\n  orderLineId\n  quantity\n  unitPriceNet\n  unitPriceWithTax\n  taxRate\n  lineTotalNet\n  lineTotalWithTax\n  unitPriceBasis\n }\n  refundId\n  numberingProvider\n  storageKey\n  createdAt\n }\n  }\n";
+export declare const CUSTOMER_DOCUMENTS_QUERY = "\n  query CustomerDocuments($customerId: ID!, $options: CustomerDocumentListOptions) {\n    customerDocuments(customerId: $customerId, options: $options) {\n      totalItems\n      items {\n        type\n        orderId\n        orderCode\n        invoice { \n  id\n  invoiceNumber\n  invoicedOn\n  orderId\n  languageCode\n  storageKey\n  totalWithTax\n  currencyCode\n  note\n  voidedOn\n  reversedByCreditNoteId\n  supersededByInvoiceId\n  reissueOfInvoiceId\n  kind\n  supplementsInvoiceId\n  lines { \n  description\n  sku\n  orderLineId\n  quantity\n  unitPriceNet\n  unitPriceWithTax\n  taxRate\n  lineTotalNet\n  lineTotalWithTax\n  unitPriceBasis\n }\n  numberingProvider\n  createdAt\n }\n        creditNote { \n  id\n  creditNoteNumber\n  issuedOn\n  totalWithTax\n  currencyCode\n  reason\n  invoiceId\n  kind\n  reversalOfInvoiceId\n  returnId\n  lines { \n  description\n  sku\n  orderLineId\n  quantity\n  unitPriceNet\n  unitPriceWithTax\n  taxRate\n  lineTotalNet\n  lineTotalWithTax\n  unitPriceBasis\n }\n  refundId\n  numberingProvider\n  storageKey\n  createdAt\n }\n      }\n    }\n  }\n";
 export declare const PREVIEW_INVOICE_MUTATION = "\n  mutation PreviewInvoice($orderId: ID!, $invoicedOn: String!, $languageCode: String, $note: String) {\n    previewInvoice(orderId: $orderId, invoicedOn: $invoicedOn, languageCode: $languageCode, note: $note)\n  }\n";
 export declare const SEND_INVOICE_EMAIL_MUTATION = "\n  mutation SendInvoiceEmail($input: SendInvoiceEmailInput!) {\n    sendInvoiceEmail(input: $input)\n  }\n";
-export declare const ISSUE_PARTIAL_CREDIT_NOTE_MUTATION = "\n  mutation IssuePartialCreditNote($input: IssuePartialCreditNoteInput!) {\n    issuePartialCreditNote(input: $input) { \n  id\n  creditNoteNumber\n  issuedOn\n  totalWithTax\n  currencyCode\n  reason\n  invoiceId\n  kind\n  storageKey\n  createdAt\n }\n  }\n";
-export declare const ISSUE_SUPPLEMENTARY_INVOICE_MUTATION = "\n  mutation IssueSupplementaryInvoice($input: IssueSupplementaryInvoiceInput!) {\n    issueSupplementaryInvoice(input: $input) { \n  id\n  invoiceNumber\n  invoicedOn\n  orderId\n  languageCode\n  storageKey\n  totalWithTax\n  currencyCode\n  note\n  voidedOn\n  kind\n  createdAt\n }\n  }\n";
+export declare const SEND_CREDIT_NOTE_EMAIL_MUTATION = "\n  mutation SendCreditNoteEmail($input: SendCreditNoteEmailInput!) {\n    sendCreditNoteEmail(input: $input)\n  }\n";
+export declare const ORDER_CREDIT_NOTE_EMAIL_SENDS_QUERY = "\n  query OrderCreditNoteEmailSends($orderId: ID!) {\n    orderCreditNoteEmailSends(orderId: $orderId) {\n      id\n      orderId\n      creditNoteId\n      recipientsTo\n      recipientsCc\n      createdAt\n    }\n  }\n";
+export declare const ISSUE_PARTIAL_CREDIT_NOTE_MUTATION = "\n  mutation IssuePartialCreditNote($input: IssuePartialCreditNoteInput!) {\n    issuePartialCreditNote(input: $input) { \n  id\n  creditNoteNumber\n  issuedOn\n  totalWithTax\n  currencyCode\n  reason\n  invoiceId\n  kind\n  reversalOfInvoiceId\n  returnId\n  lines { \n  description\n  sku\n  orderLineId\n  quantity\n  unitPriceNet\n  unitPriceWithTax\n  taxRate\n  lineTotalNet\n  lineTotalWithTax\n  unitPriceBasis\n }\n  refundId\n  numberingProvider\n  storageKey\n  createdAt\n }\n  }\n";
+export declare const ISSUE_SUPPLEMENTARY_INVOICE_MUTATION = "\n  mutation IssueSupplementaryInvoice($input: IssueSupplementaryInvoiceInput!) {\n    issueSupplementaryInvoice(input: $input) { \n  id\n  invoiceNumber\n  invoicedOn\n  orderId\n  languageCode\n  storageKey\n  totalWithTax\n  currencyCode\n  note\n  voidedOn\n  reversedByCreditNoteId\n  supersededByInvoiceId\n  reissueOfInvoiceId\n  kind\n  supplementsInvoiceId\n  lines { \n  description\n  sku\n  orderLineId\n  quantity\n  unitPriceNet\n  unitPriceWithTax\n  taxRate\n  lineTotalNet\n  lineTotalWithTax\n  unitPriceBasis\n }\n  numberingProvider\n  createdAt\n }\n  }\n";
+export declare const PLAN_INVOICE_CORRECTION_QUERY = "\n  query PlanInvoiceCorrection($input: InvoiceCorrectionInput!) {\n    planInvoiceCorrection(input: $input) { \n      planHash\n      ledger\n      invoice { id invoiceNumber kind totalWithTax creditable currencyCode orderIds voidedOn }\n      outcomes {\n        outcome\n        available\n        unavailableCode\n        unavailableMessage\n        document\n        needsLines\n        prefillsLines\n        needsAddresses\n        allowsRefund\n        allowsNote\n      }\n      prefill {\n        source\n        basis\n        lines { description sku orderLineId quantity unitPrice unitPriceBasis taxRate }\n        seededGross\n        billedGross\n        differs\n      }\n      outcome\n      operation\n      lineTotals { \n  net\n  tax\n  gross\n  taxSummary { taxRate net tax gross }\n }\n      documents {\n        type\n        kind\n        documentDate\n        currencyCode\n        lines { \n  description\n  sku\n  orderLineId\n  quantity\n  unitPriceNet\n  unitPriceWithTax\n  taxRate\n  lineTotalNet\n  lineTotalWithTax\n  unitPriceBasis\n }\n        totals { \n  net\n  tax\n  gross\n  taxSummary { taxRate net tax gross }\n }\n        issuer\n        numbering { provider providerLabel external ready legalEntityId testStore }\n      }\n      refund {\n        amount\n        available\n        unavailableCode\n        unavailableMessage\n        options { paymentId method amount refundable }\n        recommendedPaymentId\n      }\n      accountCredit { available unavailableCode message }\n      settlement\n      blockers { code message path }\n }\n  }\n";
+/**
+ * Its own document on purpose: `commitInvoiceCorrection` exists only on an engine with the
+ * correction commit, so on an older one this call alone fails validation.
+ */
+export declare const COMMIT_INVOICE_CORRECTION_MUTATION = "\n  mutation CommitInvoiceCorrection(\n    $input: InvoiceCorrectionInput!\n    $expectedPlanHash: String!\n    $idempotencyKey: String!\n  ) {\n    commitInvoiceCorrection(\n      input: $input\n      expectedPlanHash: $expectedPlanHash\n      idempotencyKey: $idempotencyKey\n    ) {\n      plan { \n      planHash\n      ledger\n      invoice { id invoiceNumber kind totalWithTax creditable currencyCode orderIds voidedOn }\n      outcomes {\n        outcome\n        available\n        unavailableCode\n        unavailableMessage\n        document\n        needsLines\n        prefillsLines\n        needsAddresses\n        allowsRefund\n        allowsNote\n      }\n      prefill {\n        source\n        basis\n        lines { description sku orderLineId quantity unitPrice unitPriceBasis taxRate }\n        seededGross\n        billedGross\n        differs\n      }\n      outcome\n      operation\n      lineTotals { \n  net\n  tax\n  gross\n  taxSummary { taxRate net tax gross }\n }\n      documents {\n        type\n        kind\n        documentDate\n        currencyCode\n        lines { \n  description\n  sku\n  orderLineId\n  quantity\n  unitPriceNet\n  unitPriceWithTax\n  taxRate\n  lineTotalNet\n  lineTotalWithTax\n  unitPriceBasis\n }\n        totals { \n  net\n  tax\n  gross\n  taxSummary { taxRate net tax gross }\n }\n        issuer\n        numbering { provider providerLabel external ready legalEntityId testStore }\n      }\n      refund {\n        amount\n        available\n        unavailableCode\n        unavailableMessage\n        options { paymentId method amount refundable }\n        recommendedPaymentId\n      }\n      accountCredit { available unavailableCode message }\n      settlement\n      blockers { code message path }\n }\n      documents {\n        ledger\n        type\n        id\n        number\n        kind\n        totalWithTax\n        currencyCode\n        issuedOn\n        numberingProvider\n      }\n      refund { id state total paymentId }\n      accountCredit { amount currencyCode unappliedCashIds }\n    }\n  }\n";
 export declare const DOCUMENT_EXTENSIONS_QUERY = "\n  query DocumentExtensions {\n    documentExtensions { \n  key\n  documentTypes\n  schemaVersion\n  jsonSchema\n  templateFragment\n  createdAt\n  updatedAt\n }\n  }\n";
 export declare const REGISTER_DOCUMENT_EXTENSION_MUTATION = "\n  mutation RegisterDocumentExtension($input: RegisterDocumentExtensionInput!) {\n    registerDocumentExtension(input: $input) { \n  key\n  documentTypes\n  schemaVersion\n  jsonSchema\n  templateFragment\n  createdAt\n  updatedAt\n }\n  }\n";
 export declare const DELETE_DOCUMENT_EXTENSION_MUTATION = "\n  mutation DeleteDocumentExtension($key: String!) {\n    deleteDocumentExtension(key: $key)\n  }\n";