@sixtyninecommerce/admin 0.9.0 → 0.11.0

package/dist/payments/ar.d.ts

@@ -0,0 +1,292 @@
+import { type Page, type Transport } from '@sixtyninecommerce/core';
+import type { Call, ListOptions } from '../types.js';
+/**
+ * Money on the store's accounts-receivable ledger (`admin.payments.ar`, headless W10-30): the
+ * payments customers make against their AR invoices, the ledger itself, prepaid drawdowns, and
+ * collecting an invoice by SEPA direct debit. Unapplied cash (an order's overpayment kept on the
+ * account) is `payments.accountCredit`.
+ *
+ * Every write needs `UpdateOrder` and a store that keeps its AR ledger (else
+ * `AR_LEDGER_NOT_ENABLED`, → `BusinessRuleError`, 422); every read `ReadOrder`. A customer the
+ * store does not hold is `CUSTOMER_NOT_FOUND` (→ `NotFoundError`). Money is in integer minor units
+ * of the currency named beside it.
+ *
+ * **Keys.** `recordPayment`, `recordPrepaidDrawdown` and `directDebit.collectNow` take
+ * `options.idempotencyKey`: a repeat under the same key answers the first call's outcome instead
+ * of moving the money again; another request under the key is `IDEMPOTENCY_CONFLICT`
+ * (→ `ConflictError`, 409), one that arrives while the first still runs
+ * `IDEMPOTENCY_IN_PROGRESS`. **Without a key `recordPayment` is NOT de-duplicated**: a double
+ * submit records two payments. Use a fresh key per intended payment and reuse it only to retry
+ * that payment.
+ */
+/** A customer payment received on the AR ledger, with what it settled. */
+export interface ArPayment {
+    id: string;
+    customerId: string;
+    amount: number;
+    currencyCode: string;
+    /** `bank_transfer`, `cash`, `card`, `direct_debit` or `other`. */
+    method: string;
+    receivedOn: string;
+    reference: string | null;
+    notes: string | null;
+    allocations: Array<{
+        id: string;
+        invoiceId: string;
+        amount: number;
+    }>;
+    createdAt: string;
+}
+export type ArPaymentMethod = 'bank_transfer' | 'cash' | 'card' | 'direct_debit' | 'other';
+export interface RecordArPaymentInput {
+    customerId: string;
+    /** Minor units of `currencyCode`, above zero. */
+    amount: number;
+    method: ArPaymentMethod;
+    /** `YYYY-MM-DD`; defaults to today in the store's zone. */
+    receivedOn?: string;
+    reference?: string;
+    notes?: string;
+    /** One the store sells in; defaults to the account's currency. It settles only invoices in it. */
+    currencyCode?: string;
+    /**
+     * Where the money goes, each at most what the invoice still owes. Omitted, it is allocated
+     * oldest invoice first and the rest stays on the account.
+     */
+    allocations?: Array<{
+        invoiceId: string;
+        amount: number;
+    }>;
+}
+/** One ledger posting. */
+export interface ArLedgerEntry {
+    id: string;
+    /** `invoice_debit`, `payment_credit`, `credit_note_credit`, `prepaid_drawdown`, … */
+    entryType: string;
+    /** Signed minor units of `currencyCode`. */
+    amount: number;
+    currencyCode: string;
+    sourceType: string;
+    sourceId: string | null;
+    occurredOn: string;
+    metadata: Record<string, unknown> | null;
+    createdAt: string;
+}
+/** The drawdown already posted for an order. */
+export interface ArOrderPrepaidDrawdown {
+    entryId: string;
+    orderId: string;
+    amount: number;
+    currencyCode: string;
+    occurredOn: string;
+}
+export interface ArPrepaidDrawdownResult {
+    entryId: string;
+    customerId: string;
+    amount: number;
+    currencyCode: string;
+    occurredOn: string;
+    /** The customer's signed balance after it, in `currencyCode` only. */
+    balanceAfter: number;
+    /** True when the order had been drawn down already: nothing new was posted. */
+    alreadyRecorded: boolean;
+}
+export interface RecordArPrepaidDrawdownInput {
+    orderId: string;
+    /** `YYYY-MM-DD`; defaults to today in the store's zone. */
+    occurredOn?: string;
+}
+/** A customer's SEPA direct debit set-up. */
+export interface ArDirectDebitSettings {
+    customerId: string;
+    enabled: boolean;
+    /** Set: every collection is blocked until a person clears it. */
+    suspendedReason: string | null;
+    hasValidMandate: boolean;
+    mandateId: string | null;
+    providerMandateId: string | null;
+    /** False when the platform has no mandate provider at all. */
+    available: boolean;
+}
+export interface UpdateArDirectDebitSettingsInput {
+    enabled?: boolean;
+    /** Null lifts a suspension. */
+    suspendedReason?: string | null;
+}
+/** One attempt to collect an invoice by direct debit. */
+export interface ArCollectionAttempt {
+    id: string;
+    invoiceId: string;
+    customerId: string;
+    attemptNumber: number;
+    amount: number;
+    currencyCode: string;
+    /** `pending`, `paid`, `failed`, `reversed` or `cancelled`. */
+    status: string;
+    provider: string;
+    providerPaymentId: string | null;
+    /** The SEPA R-code when the provider gave one (`AM04`, `MD06`, …). */
+    failureCode: string | null;
+    failureReason: string | null;
+    settledAt: string | null;
+    reversedAt: string | null;
+    orderSettlementState: string;
+    lastCheckedAt: string | null;
+    createdAt: string;
+}
+/** The recorded pre-notification and the wording the merchant must send the debtor. */
+export interface ArPreNotification {
+    invoiceId: string;
+    /** The first day the collection may be taken. */
+    collectOn: string;
+    amount: number;
+    noticeTitle: string;
+    noticeBody: string;
+}
+/**
+ * What asking to collect an invoice now answered. A refusal is an ANSWER, not an error:
+ * `{ result: 'refused', refusal, message }` says why the invoice cannot be collected now (not
+ * pre-notified, no mandate, suspended, nothing outstanding, …), and nothing was asked of the
+ * bank. `declined`: the provider refused the charge at once. `already-in-flight`: a collection
+ * of the invoice is running; `attempt` is it.
+ */
+export type ArCollectResult = {
+    result: 'charged' | 'declined' | 'already-in-flight';
+    refusal: null;
+    message: null;
+    attempt: ArCollectionAttempt;
+} | {
+    result: 'refused';
+    refusal: string;
+    message: string;
+    attempt: null;
+};
+export interface ArDirectDebitModule {
+    /**
+     * A customer's direct debit settings and mandate state.
+     *
+     * @effect read
+     * @permission ReadOrder
+     */
+    settings(customerId: string, options?: Call): Promise<ArDirectDebitSettings>;
+    /**
+     * Turn direct debit on or off for a customer, or lift a suspension. Turning it on needs a valid
+     * SEPA mandate (`AR_DIRECT_DEBIT_MANDATE_REQUIRED`; an older engine answered
+     * `USER_INPUT_ERROR`). Moves no money.
+     *
+     * @effect write
+     * @permission UpdateOrder
+     */
+    update(customerId: string, input: UpdateArDirectDebitSettingsInput, options?: Call): Promise<ArDirectDebitSettings>;
+    /**
+     * Every collection attempt of one invoice, newest first (the last 50).
+     *
+     * @effect read
+     * @permission ReadOrder
+     */
+    attempts(invoiceId: string, options?: Call): Promise<ArCollectionAttempt[]>;
+    /**
+     * The newest attempt of each invoice named, in one call.
+     *
+     * @effect read
+     * @permission ReadOrder
+     */
+    latestAttempts(invoiceIds: string[], options?: Call): Promise<ArCollectionAttempt[]>;
+    /**
+     * Record that the debtor has been told the invoice will be collected, and get the exact
+     * wording to send them. It sends nothing itself: sending the notice is the merchant's legal
+     * duty, and recording it is what allows the collection. Run it again when the outstanding
+     * amount changes.
+     *
+     * Refused, coded (an older engine answered each `USER_INPUT_ERROR` with the same sentence):
+     * `AR_INVOICE_NOT_FOUND`, `AR_INVOICE_NOT_OPEN` (voided, or nothing outstanding),
+     * `AR_DIRECT_DEBIT_NOT_ENABLED`, `AR_DIRECT_DEBIT_SUSPENDED`, `AR_ACCOUNT_IN_ERP`,
+     * `AR_INVOICE_DIRECT_DEBIT_IN_FLIGHT`.
+     *
+     * @effect money
+     * @permission UpdateOrder
+     */
+    sendPreNotification(invoiceId: string, options?: Call): Promise<ArPreNotification>;
+    /**
+     * Collect a pre-notified invoice now, from the customer's SEPA mandate. A refusal is answered
+     * as `{ result: 'refused', refusal }`, NOT thrown (see {@link ArCollectResult}). Thrown:
+     * `AR_INVOICE_NOT_FOUND`, and `AR_DIRECT_DEBIT_UNAVAILABLE` (a platform fault, 500: the
+     * platform has no webhook address or charge provider for the collection; nothing is reserved).
+     *
+     * Pass `options.idempotencyKey`: a repeat under it answers the first outcome (the attempt as it
+     * is now). Once the provider was asked, a failure spends the key: a repeat answers
+     * `IDEMPOTENCY_OUTCOME_UNKNOWN` (`error.outcomeUnknown`) and asks the bank nothing; read
+     * {@link attempts} for what happened. The engine also keeps one live attempt per invoice
+     * whatever the key does.
+     *
+     * @effect money
+     * @permission UpdateOrder
+     */
+    collectNow(invoiceId: string, options?: Call): Promise<ArCollectResult>;
+}
+export interface ArPaymentsModule {
+    /**
+     * AR payments, newest first, one customer's or the store's, paged (`limit` up to 100).
+     *
+     * @effect read
+     * @permission ReadOrder
+     */
+    payments(options?: ListOptions & {
+        customerId?: string;
+    }): Promise<Page<ArPayment>>;
+    /**
+     * A customer's ledger postings, newest first, paged (`limit` up to 100).
+     *
+     * @effect read
+     * @permission ReadOrder
+     */
+    ledger(customerId: string, options?: ListOptions): Promise<Page<ArLedgerEntry>>;
+    /**
+     * Record a payment a customer made against their AR invoices: the receipt, its allocations and
+     * the ledger credit, in one transaction. **Pass `options.idempotencyKey`**: without one a
+     * repeat (a double click, a retry after a timeout) records a second payment. With one, the
+     * repeat answers the first payment as it is now.
+     *
+     * Refusals: `AR_LEDGER_NOT_ENABLED`, `CUSTOMER_NOT_FOUND`, `CURRENCY_NOT_AVAILABLE` (a currency
+     * the store does not sell in), `AR_CURRENCY_MISMATCH` (an allocation to an invoice in another
+     * currency), `AR_INVOICE_NOT_FOUND` (an allocation to an invoice not this customer's),
+     * `AR_INVOICE_NOT_OPEN` (to a voided one), `AR_ALLOCATION_EXCEEDS_OUTSTANDING` (more than the
+     * invoice still owes) and `AR_ALLOCATION_EXCEEDS_PAYMENT` (more than the payment), each a
+     * `USER_INPUT_ERROR` on an older engine; and a field refusal (`USER_INPUT_ERROR`) for an amount,
+     * a method or an allocation that is not one (a duplicate).
+     *
+     * @effect money
+     * @permission UpdateOrder
+     */
+    recordPayment(input: RecordArPaymentInput, options?: Call): Promise<ArPayment>;
+    /**
+     * The prepaid drawdown already posted for an order, or null.
+     *
+     * @effect read
+     * @permission ReadOrder
+     */
+    prepaidDrawdown(orderId: string, options?: Call): Promise<ArOrderPrepaidDrawdown | null>;
+    /**
+     * Draw a delivered order's gross total off the customer's prepaid credit. Once per order
+     * whatever happens (`alreadyRecorded` on a repeat without a key); with a key, a repeat answers
+     * the first result. Refused `ORDER_NOT_FOUND`, `AR_ORDER_HAS_NO_CUSTOMER` and
+     * `AR_ORDER_STATE_BLOCKS_DRAWDOWN` (each `USER_INPUT_ERROR` on an older engine).
+     *
+     * @effect money
+     * @permission UpdateOrder
+     */
+    recordPrepaidDrawdown(input: RecordArPrepaidDrawdownInput, options?: Call): Promise<ArPrepaidDrawdownResult>;
+    directDebit: ArDirectDebitModule;
+}
+export declare const AR_PAYMENTS_QUERY = "\n  query ArPayments($options: ArListOptions) {\n    arPayments(options: $options) {\n      items { \n  id\n  customerId\n  amount\n  currencyCode\n  method\n  receivedOn\n  reference\n  notes\n  allocations {\n    id\n    invoiceId\n    amount\n  }\n  createdAt\n }\n      totalItems\n    }\n  }\n";
+export declare const AR_LEDGER_QUERY = "\n  query ArLedgerEntries($customerId: ID!, $options: ArListOptions) {\n    arLedgerEntries(customerId: $customerId, options: $options) {\n      items {\n        id\n        entryType\n        amount\n        currencyCode\n        sourceType\n        sourceId\n        occurredOn\n        metadata\n        createdAt\n      }\n      totalItems\n    }\n  }\n";
+export declare const RECORD_AR_PAYMENT_MUTATION = "\n  mutation RecordArPayment($input: RecordArPaymentInput!, $idempotencyKey: String) {\n    recordArPayment(input: $input, idempotencyKey: $idempotencyKey) { \n  id\n  customerId\n  amount\n  currencyCode\n  method\n  receivedOn\n  reference\n  notes\n  allocations {\n    id\n    invoiceId\n    amount\n  }\n  createdAt\n }\n  }\n";
+export declare const AR_ORDER_PREPAID_DRAWDOWN_QUERY = "\n  query ArOrderPrepaidDrawdown($orderId: ID!) {\n    arOrderPrepaidDrawdown(orderId: $orderId) {\n      entryId\n      orderId\n      amount\n      currencyCode\n      occurredOn\n    }\n  }\n";
+export declare const RECORD_AR_PREPAID_DRAWDOWN_MUTATION = "\n  mutation RecordArPrepaidDrawdown($input: RecordArPrepaidDrawdownInput!, $idempotencyKey: String) {\n    recordArPrepaidDrawdown(input: $input, idempotencyKey: $idempotencyKey) {\n      entryId\n      customerId\n      amount\n      currencyCode\n      occurredOn\n      balanceAfter\n      alreadyRecorded\n    }\n  }\n";
+export declare const AR_DIRECT_DEBIT_SETTINGS_QUERY = "\n  query ArDirectDebitSettings($customerId: ID!) {\n    arDirectDebitSettings(customerId: $customerId) { \n  customerId\n  enabled\n  suspendedReason\n  hasValidMandate\n  mandateId\n  providerMandateId\n  available\n }\n  }\n";
+export declare const UPDATE_AR_DIRECT_DEBIT_SETTINGS_MUTATION = "\n  mutation UpdateArDirectDebitSettings($customerId: ID!, $input: UpdateArDirectDebitSettingsInput!) {\n    updateArDirectDebitSettings(customerId: $customerId, input: $input) {\n      \n  customerId\n  enabled\n  suspendedReason\n  hasValidMandate\n  mandateId\n  providerMandateId\n  available\n\n    }\n  }\n";
+export declare const AR_COLLECTION_ATTEMPTS_QUERY = "\n  query ArCollectionAttempts($invoiceId: ID!) {\n    arCollectionAttempts(invoiceId: $invoiceId) { \n  id\n  invoiceId\n  customerId\n  attemptNumber\n  amount\n  currencyCode\n  status\n  provider\n  providerPaymentId\n  failureCode\n  failureReason\n  settledAt\n  reversedAt\n  orderSettlementState\n  lastCheckedAt\n  createdAt\n }\n  }\n";
+export declare const AR_LATEST_COLLECTION_ATTEMPTS_QUERY = "\n  query ArLatestCollectionAttempts($invoiceIds: [ID!]!) {\n    arLatestCollectionAttempts(invoiceIds: $invoiceIds) { \n  id\n  invoiceId\n  customerId\n  attemptNumber\n  amount\n  currencyCode\n  status\n  provider\n  providerPaymentId\n  failureCode\n  failureReason\n  settledAt\n  reversedAt\n  orderSettlementState\n  lastCheckedAt\n  createdAt\n }\n  }\n";
+export declare const SEND_AR_PRE_NOTIFICATION_MUTATION = "\n  mutation SendArDirectDebitPreNotification($invoiceId: ID!) {\n    sendArDirectDebitPreNotification(invoiceId: $invoiceId) {\n      invoiceId\n      collectOn\n      amount\n      noticeTitle\n      noticeBody\n    }\n  }\n";
+export declare const COLLECT_AR_INVOICE_NOW_MUTATION = "\n  mutation CollectArInvoiceNow($invoiceId: ID!, $idempotencyKey: String) {\n    collectArInvoiceNow(invoiceId: $invoiceId, idempotencyKey: $idempotencyKey) {\n      result\n      refusal\n      message\n      attempt { \n  id\n  invoiceId\n  customerId\n  attemptNumber\n  amount\n  currencyCode\n  status\n  provider\n  providerPaymentId\n  failureCode\n  failureReason\n  settledAt\n  reversedAt\n  orderSettlementState\n  lastCheckedAt\n  createdAt\n }\n    }\n  }\n";
+export declare function createArPaymentsModule(transport: Transport): ArPaymentsModule;

package/dist/payments/ar.js

@@ -0,0 +1,223 @@
+import { pageFromVendureList, readOffsetCursor, } from '@sixtyninecommerce/core';
+import { arPageWindow } from '../documents/ar.js';
+const PAYMENT_FIELDS = /* GraphQL */ `
+  id
+  customerId
+  amount
+  currencyCode
+  method
+  receivedOn
+  reference
+  notes
+  allocations {
+    id
+    invoiceId
+    amount
+  }
+  createdAt
+`;
+const ATTEMPT_FIELDS = /* GraphQL */ `
+  id
+  invoiceId
+  customerId
+  attemptNumber
+  amount
+  currencyCode
+  status
+  provider
+  providerPaymentId
+  failureCode
+  failureReason
+  settledAt
+  reversedAt
+  orderSettlementState
+  lastCheckedAt
+  createdAt
+`;
+const DIRECT_DEBIT_SETTINGS_FIELDS = /* GraphQL */ `
+  customerId
+  enabled
+  suspendedReason
+  hasValidMandate
+  mandateId
+  providerMandateId
+  available
+`;
+export const AR_PAYMENTS_QUERY = /* GraphQL */ `
+  query ArPayments($options: ArListOptions) {
+    arPayments(options: $options) {
+      items { ${PAYMENT_FIELDS} }
+      totalItems
+    }
+  }
+`;
+export const AR_LEDGER_QUERY = /* GraphQL */ `
+  query ArLedgerEntries($customerId: ID!, $options: ArListOptions) {
+    arLedgerEntries(customerId: $customerId, options: $options) {
+      items {
+        id
+        entryType
+        amount
+        currencyCode
+        sourceType
+        sourceId
+        occurredOn
+        metadata
+        createdAt
+      }
+      totalItems
+    }
+  }
+`;
+export const RECORD_AR_PAYMENT_MUTATION = /* GraphQL */ `
+  mutation RecordArPayment($input: RecordArPaymentInput!, $idempotencyKey: String) {
+    recordArPayment(input: $input, idempotencyKey: $idempotencyKey) { ${PAYMENT_FIELDS} }
+  }
+`;
+export const AR_ORDER_PREPAID_DRAWDOWN_QUERY = /* GraphQL */ `
+  query ArOrderPrepaidDrawdown($orderId: ID!) {
+    arOrderPrepaidDrawdown(orderId: $orderId) {
+      entryId
+      orderId
+      amount
+      currencyCode
+      occurredOn
+    }
+  }
+`;
+export const RECORD_AR_PREPAID_DRAWDOWN_MUTATION = /* GraphQL */ `
+  mutation RecordArPrepaidDrawdown($input: RecordArPrepaidDrawdownInput!, $idempotencyKey: String) {
+    recordArPrepaidDrawdown(input: $input, idempotencyKey: $idempotencyKey) {
+      entryId
+      customerId
+      amount
+      currencyCode
+      occurredOn
+      balanceAfter
+      alreadyRecorded
+    }
+  }
+`;
+export const AR_DIRECT_DEBIT_SETTINGS_QUERY = /* GraphQL */ `
+  query ArDirectDebitSettings($customerId: ID!) {
+    arDirectDebitSettings(customerId: $customerId) { ${DIRECT_DEBIT_SETTINGS_FIELDS} }
+  }
+`;
+export const UPDATE_AR_DIRECT_DEBIT_SETTINGS_MUTATION = /* GraphQL */ `
+  mutation UpdateArDirectDebitSettings($customerId: ID!, $input: UpdateArDirectDebitSettingsInput!) {
+    updateArDirectDebitSettings(customerId: $customerId, input: $input) {
+      ${DIRECT_DEBIT_SETTINGS_FIELDS}
+    }
+  }
+`;
+export const AR_COLLECTION_ATTEMPTS_QUERY = /* GraphQL */ `
+  query ArCollectionAttempts($invoiceId: ID!) {
+    arCollectionAttempts(invoiceId: $invoiceId) { ${ATTEMPT_FIELDS} }
+  }
+`;
+export const AR_LATEST_COLLECTION_ATTEMPTS_QUERY = /* GraphQL */ `
+  query ArLatestCollectionAttempts($invoiceIds: [ID!]!) {
+    arLatestCollectionAttempts(invoiceIds: $invoiceIds) { ${ATTEMPT_FIELDS} }
+  }
+`;
+export const SEND_AR_PRE_NOTIFICATION_MUTATION = /* GraphQL */ `
+  mutation SendArDirectDebitPreNotification($invoiceId: ID!) {
+    sendArDirectDebitPreNotification(invoiceId: $invoiceId) {
+      invoiceId
+      collectOn
+      amount
+      noticeTitle
+      noticeBody
+    }
+  }
+`;
+export const COLLECT_AR_INVOICE_NOW_MUTATION = /* GraphQL */ `
+  mutation CollectArInvoiceNow($invoiceId: ID!, $idempotencyKey: String) {
+    collectArInvoiceNow(invoiceId: $invoiceId, idempotencyKey: $idempotencyKey) {
+      result
+      refusal
+      message
+      attempt { ${ATTEMPT_FIELDS} }
+    }
+  }
+`;
+/** `undefined`, never null: `JSON.stringify` drops it, so an omitted key stays off the wire. */
+const keyOf = (options) => options?.idempotencyKey;
+export function createArPaymentsModule(transport) {
+    const paymentsPage = async (customerId, skip, take, options) => {
+        const data = await transport.graphql({
+            api: 'admin',
+            query: AR_PAYMENTS_QUERY,
+            variables: { options: { customerId, skip, take } },
+        }, options);
+        return pageFromVendureList(data.arPayments, skip, take, (cursor) => paymentsPage(customerId, readOffsetCursor(cursor), take, options));
+    };
+    const ledgerPage = async (customerId, skip, take, options) => {
+        const data = await transport.graphql({ api: 'admin', query: AR_LEDGER_QUERY, variables: { customerId, options: { skip, take } } }, options);
+        return pageFromVendureList(data.arLedgerEntries, skip, take, (cursor) => ledgerPage(customerId, readOffsetCursor(cursor), take, options));
+    };
+    return {
+        payments(options) {
+            const { skip, take } = arPageWindow(options);
+            return paymentsPage(options?.customerId, skip, take, options);
+        },
+        ledger(customerId, options) {
+            const { skip, take } = arPageWindow(options);
+            return ledgerPage(customerId, skip, take, options);
+        },
+        async recordPayment(input, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: RECORD_AR_PAYMENT_MUTATION,
+                variables: { input, idempotencyKey: keyOf(options) },
+            }, options);
+            return data.recordArPayment;
+        },
+        async prepaidDrawdown(orderId, options) {
+            const data = await transport.graphql({ api: 'admin', query: AR_ORDER_PREPAID_DRAWDOWN_QUERY, variables: { orderId } }, options);
+            return data.arOrderPrepaidDrawdown;
+        },
+        async recordPrepaidDrawdown(input, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: RECORD_AR_PREPAID_DRAWDOWN_MUTATION,
+                variables: { input, idempotencyKey: keyOf(options) },
+            }, options);
+            return data.recordArPrepaidDrawdown;
+        },
+        directDebit: {
+            async settings(customerId, options) {
+                const data = await transport.graphql({ api: 'admin', query: AR_DIRECT_DEBIT_SETTINGS_QUERY, variables: { customerId } }, options);
+                return data.arDirectDebitSettings;
+            },
+            async update(customerId, input, options) {
+                const data = await transport.graphql({
+                    api: 'admin',
+                    query: UPDATE_AR_DIRECT_DEBIT_SETTINGS_MUTATION,
+                    variables: { customerId, input },
+                }, options);
+                return data.updateArDirectDebitSettings;
+            },
+            async attempts(invoiceId, options) {
+                const data = await transport.graphql({ api: 'admin', query: AR_COLLECTION_ATTEMPTS_QUERY, variables: { invoiceId } }, options);
+                return data.arCollectionAttempts;
+            },
+            async latestAttempts(invoiceIds, options) {
+                const data = await transport.graphql({ api: 'admin', query: AR_LATEST_COLLECTION_ATTEMPTS_QUERY, variables: { invoiceIds } }, options);
+                return data.arLatestCollectionAttempts;
+            },
+            async sendPreNotification(invoiceId, options) {
+                const data = await transport.graphql({ api: 'admin', query: SEND_AR_PRE_NOTIFICATION_MUTATION, variables: { invoiceId } }, options);
+                return data.sendArDirectDebitPreNotification;
+            },
+            async collectNow(invoiceId, options) {
+                const data = await transport.graphql({
+                    api: 'admin',
+                    query: COLLECT_AR_INVOICE_NOW_MUTATION,
+                    variables: { invoiceId, idempotencyKey: keyOf(options) },
+                }, options);
+                return data.collectArInvoiceNow;
+            },
+        },
+    };
+}

package/dist/payments/connected-account.d.ts

@@ -0,0 +1,47 @@
+import { type Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/**
+ * The Stripe Connect account saved for the legal entity (the seller) of the store the client is
+ * on. Every store of that legal entity shares it.
+ */
+export interface StripeConnectedAccount {
+    /** The engine's id of the store's seller (its legal entity). */
+    sellerId: string;
+    /** The saved Stripe account id (`acct_…`), or null when none is saved. */
+    accountId: string | null;
+}
+/**
+ * The store's Stripe Connect account id, saved on its legal entity (the seller).
+ *
+ * **Saved, not yet used.** The engine keeps the id, but charges route to it only once Stripe
+ * Connect routing is switched on (decision B0c); until then a Stripe payment runs on the
+ * account of the method's own API key (`payments.methods.providerKeys`).
+ *
+ * The engine does not check the value's format: what is sent is stored. A head that wants the
+ * `acct_…` shape checks it itself until the engine does.
+ */
+export interface ConnectedAccountModule {
+    /**
+     * The account saved for the store's legal entity. Any signed-in caller of the store may read
+     * it (the id is not a secret).
+     *
+     * @effect read
+     */
+    get(options?: Call): Promise<StripeConnectedAccount>;
+    /**
+     * Save the account id (`null` removes it) on the store's legal entity, and answer what it then
+     * holds. Every store of that legal entity is changed with it, so the caller needs
+     * `UpdateSeller` on each of them: one they may not change refuses the whole call
+     * `SHARED_SELLER_NOT_ALLOWED` (`PermissionDeniedError`, 403), and without `UpdateSeller`
+     * here it is `FORBIDDEN` (403). `SELLER_REQUIRED` (`BusinessRuleError`, 422): the store has no
+     * seller to save it on. An empty string is refused before sending
+     * (`INVALID_CONNECTED_ACCOUNT_INPUT`, 400): `null` removes the account.
+     *
+     * @effect write
+     * @permission UpdateSeller
+     */
+    set(accountId: string | null, options?: Call): Promise<StripeConnectedAccount>;
+}
+export declare const STRIPE_CONNECTED_ACCOUNT_QUERY = "\n  query StripeConnectedAccount {\n    activeChannel {\n      id\n      seller {\n        id\n        customFields {\n          stripeConnectedAccountId\n        }\n      }\n    }\n  }\n";
+export declare const SET_STRIPE_CONNECTED_ACCOUNT_MUTATION = "\n  mutation SetStripeConnectedAccount($input: UpdateSellerInput!) {\n    updateSeller(input: $input) {\n      id\n      customFields {\n        stripeConnectedAccountId\n      }\n    }\n  }\n";
+export declare function createConnectedAccountModule(transport: Transport): ConnectedAccountModule;

package/dist/payments/connected-account.js

@@ -0,0 +1,61 @@
+import { BusinessRuleError, ValidationError } from '@sixtyninecommerce/core';
+import { fieldOf } from '../catalog/types.js';
+export const STRIPE_CONNECTED_ACCOUNT_QUERY = /* GraphQL */ `
+  query StripeConnectedAccount {
+    activeChannel {
+      id
+      seller {
+        id
+        customFields {
+          stripeConnectedAccountId
+        }
+      }
+    }
+  }
+`;
+export const SET_STRIPE_CONNECTED_ACCOUNT_MUTATION = /* GraphQL */ `
+  mutation SetStripeConnectedAccount($input: UpdateSellerInput!) {
+    updateSeller(input: $input) {
+      id
+      customFields {
+        stripeConnectedAccountId
+      }
+    }
+  }
+`;
+const toAccount = (seller) => ({
+    sellerId: seller.id,
+    accountId: seller.customFields?.stripeConnectedAccountId ?? null,
+});
+export function createConnectedAccountModule(transport) {
+    // Hoisted, as `createProvidersModule`'s functions are: a destructured method keeps working.
+    const read = async (options) => {
+        const channel = await fieldOf(transport, STRIPE_CONNECTED_ACCOUNT_QUERY, 'activeChannel', {}, options);
+        if (!channel.seller) {
+            throw new BusinessRuleError({
+                code: 'SELLER_REQUIRED',
+                message: 'This store has no seller (legal entity) to hold a Stripe account.',
+                status: 422,
+                service: 'vendure',
+            });
+        }
+        return toAccount(channel.seller);
+    };
+    return {
+        get: read,
+        async set(accountId, options) {
+            if (accountId !== null && (typeof accountId !== 'string' || accountId === '')) {
+                throw new ValidationError({
+                    code: 'INVALID_CONNECTED_ACCOUNT_INPUT',
+                    message: 'accountId must be a Stripe account id, or null to remove it.',
+                    status: 400,
+                    service: 'vendure',
+                });
+            }
+            // The seller is the store's own, read in the same tenant as the write: the id is never
+            // the caller's to name, so a head cannot save onto another legal entity by mistake.
+            const { sellerId } = await read(options);
+            return toAccount(await fieldOf(transport, SET_STRIPE_CONNECTED_ACCOUNT_MUTATION, 'updateSeller', { input: { id: sellerId, customFields: { stripeConnectedAccountId: accountId } } }, options));
+        },
+    };
+}

package/dist/payments/credit-noted-fields.d.ts

@@ -0,0 +1,12 @@
+import type { Transport } from '@sixtyninecommerce/core';
+/** `document` without the fields above: what an engine before them accepts. */
+export declare function withoutCreditNotedFields(document: string): string;
+/**
+ * The transport, sending a document that names the credit fields once more without them when the
+ * engine refused it as unknown. Safe for a mutation too: a refused document never ran. A refusal
+ * at HTTP 400 does not name the field, so a document that also carries the older store-credit
+ * fields goes through `storeCreditAware(creditNotedAware(transport))`: the newest fields fall away
+ * first (one resend on an engine that has store credit and not these), and both on an engine
+ * that knows neither (four sends at most).
+ */
+export declare function creditNotedAware(transport: Pick<Transport, 'graphql'>): Pick<Transport, 'graphql'>;

package/dist/payments/credit-noted-fields.js

@@ -0,0 +1,37 @@
+import { isUnknownFieldRejection } from './store-credit-fields.js';
+/**
+ * The payment position's credit fields (branch `murat/order-outstanding-ignores-credit-refunds`):
+ * `creditNoted`, what an invoiced order's credit notes took off its bill, and `owed`, what the
+ * customer still owes after them. An engine before them refuses a document naming either as a
+ * whole, before it runs; the same document without them reads as it did then (both absent: nothing
+ * credited, the customer owes `outstanding`). So the position reads keep working on an older
+ * engine, as `storeCreditAware` keeps the "credit the customer" answers working.
+ */
+const CREDIT_NOTED_FIELDS = [/\bcreditNoted\b/g, /\bowed\b/g];
+/** `document` without the fields above: what an engine before them accepts. */
+export function withoutCreditNotedFields(document) {
+    return CREDIT_NOTED_FIELDS.reduce((text, field) => text.replace(field, ''), document);
+}
+/**
+ * The transport, sending a document that names the credit fields once more without them when the
+ * engine refused it as unknown. Safe for a mutation too: a refused document never ran. A refusal
+ * at HTTP 400 does not name the field, so a document that also carries the older store-credit
+ * fields goes through `storeCreditAware(creditNotedAware(transport))`: the newest fields fall away
+ * first (one resend on an engine that has store credit and not these), and both on an engine
+ * that knows neither (four sends at most).
+ */
+export function creditNotedAware(transport) {
+    return {
+        async graphql(call, options) {
+            try {
+                return await transport.graphql(call, options);
+            }
+            catch (error) {
+                const legacy = withoutCreditNotedFields(call.query);
+                if (legacy === call.query || !isUnknownFieldRejection(error))
+                    throw error;
+                return transport.graphql({ ...call, query: legacy }, options);
+            }
+        },
+    };
+}