@sixtyninecommerce/admin 0.10.0 → 0.11.0

package/dist/customers/credit.d.ts

@@ -0,0 +1,263 @@
+import { type Page, type Transport } from '@sixtyninecommerce/core';
+import type { OrderPaymentTerms } from '../orders/get.js';
+import type { Call, ListOptions } from '../types.js';
+/**
+ * A customer's B2B credit: the account the store keeps them in its accounts-receivable ledger,
+ * their credit limit and payment terms, and what they owe (`admin.customers.credit`, headless
+ * W10-30). The documents of that ledger are `admin.documents.ar`; its payments
+ * `admin.payments.ar`.
+ *
+ * Everything here is for a store that keeps its own AR ledger (`settings.get().enabled`). A write
+ * on any other store is refused `AR_LEDGER_NOT_ENABLED` (→ `BusinessRuleError`, 422); a customer
+ * the store does not hold, `CUSTOMER_NOT_FOUND` (→ `NotFoundError`). Money is in integer minor
+ * units of the currency named beside it, never added across currencies.
+ */
+/** Whether the store keeps an accounts-receivable ledger at all. */
+export interface CustomerCreditSettings {
+    /** The store's B2B credit switch (`Channel.customFields.b2bCreditEnabled`). */
+    enabled: boolean;
+    /** The store's default currency, the one a new credit account is opened in. */
+    defaultCurrencyCode: string;
+}
+/** `per_order` (an invoice per placed order) or `statement` (one per period). */
+export type InvoicingMode = 'per_order' | 'statement' | (string & {});
+/** A customer's stored credit-account settings. */
+export interface CreditAccount {
+    id: string;
+    customerId: string;
+    /** Minor units of `currencyCode`; null when unlimited. */
+    creditLimit: number | null;
+    defaultPaymentTermsDays: number | null;
+    invoicingMode: InvoicingMode;
+    /** Day of the month (1-28) the statement run invoices this customer; null when it does not. */
+    statementDayOfMonth: number | null;
+    /** True when the customer is invoiced in the store's ERP, which keeps their balance. */
+    erpLinked: boolean;
+    /** The account's currency: the credit limit's. */
+    currencyCode: string;
+    externalInvoicesSyncedAt: string | null;
+    externalInvoicesSyncError: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** One currency's signed balance. */
+export interface CurrencyBalance {
+    currencyCode: string;
+    /** Signed, minor units of `currencyCode`: above 0 the customer owes, below 0 is a credit. */
+    balance: number;
+}
+/** A customer's position as the ledger states it. */
+export interface CreditAccountSummary {
+    customerId: string;
+    /** The account's currency. */
+    currencyCode: string;
+    /** The signed ledger balance in `currencyCode` only; every currency is in `balances`. */
+    balance: number;
+    balances: CurrencyBalance[];
+    creditLimit: number | null;
+    defaultPaymentTermsDays: number | null;
+    invoicingMode: InvoicingMode;
+    erpLinked: boolean;
+    openInvoiceCount: number;
+    overdueInvoiceCount: number;
+}
+/** Where a credit status's balance came from. */
+export type CreditBalanceSource = 'LOCAL_LEDGER' | 'ERP_LIVE' | 'ERP_UNLINKED';
+/**
+ * A customer's credit status: exposure (ledger balance plus what placed, not-yet-invoiced orders
+ * still owe) against the credit limit. Every figure is in `currencyCode`, other currencies
+ * converted at the store's rate. Warning only: it never blocks an order.
+ */
+export interface CreditStatus {
+    customerId: string;
+    currencyCode: string;
+    /** Signed; the ledger's balance PLUS {@link setAsideMinor}. */
+    balance: number;
+    uninvoicedOrdersTotal: number;
+    /** `balance + uninvoicedOrdersTotal`. */
+    exposure: number;
+    creditLimit: number | null;
+    /** `creditLimit - exposure`; null without a limit. */
+    available: number | null;
+    overdueInvoiceCount: number;
+    overLimit: boolean;
+    hasOverdue: boolean;
+    balanceSource: CreditBalanceSource;
+    /** The exposure per currency before conversion, the account's currency included. */
+    exposureByCurrency: Array<{
+        currencyCode: string;
+        balance: number;
+        uninvoicedOrdersTotal: number;
+    }>;
+    /** Currencies left out for want of an exchange rate (only ever without a credit limit). */
+    unconvertedCurrencies: string[];
+    /**
+     * The refund credit `balance` sets aside: the credit notes of refunds on orders not yet
+     * invoiced, which those orders' own figure already reflects. 0 on an ERP balance. Say "credit
+     * from refunds on orders not yet invoiced is left out" when this is above 0; never infer it
+     * from two balances.
+     */
+    setAsideMinor: number;
+    /**
+     * The ledger's balance in every currency, read in the SAME request as the status, so the two
+     * can be compared without a payment or invoice recorded in between.
+     */
+    ledgerBalances: CurrencyBalance[];
+}
+/** What a credit-account update may change. `null` clears a field. */
+export interface UpdateCreditAccountInput {
+    creditLimit?: number | null;
+    defaultPaymentTermsDays?: number | null;
+    invoicingMode?: InvoicingMode;
+    statementDayOfMonth?: number | null;
+    erpLinked?: boolean;
+}
+/**
+ * Payment terms as the store resolves them (an ERP's condition, else its own): the order's
+ * frozen-terms shape (`orders.get`) without what only an order carries.
+ */
+export type PaymentTerms = Omit<OrderPaymentTerms, 'resolvedAt' | 'remoteConditionCode' | 'remoteConfirmedAt' | 'remoteMismatch'>;
+/** A customer's resolved payment terms. */
+export interface CustomerPaymentTerms extends PaymentTerms {
+    customerId: string | null;
+    /**
+     * The due date (`YYYY-MM-DD`) an AR invoice issued today, in the store's zone, would carry
+     * under these terms, or null when they state no single due date: such an invoice is refused
+     * (`INVOICE_PAYMENT_TERMS_UNREPRESENTABLE`) unless it states its own terms. The engine's own
+     * judgement, the one `InvoiceableOrder.dueOn` gives an order's frozen terms; never re-judge it.
+     * It is the CUSTOMER's terms: an order that froze none may be invoiced under its own condition
+     * or days instead, so it does not decide alone whether such an order's invoice is refused.
+     */
+    dueOn: string | null;
+}
+/** A placed order an AR invoice or statement may still bill. */
+export interface InvoiceableOrder {
+    id: string;
+    code: string;
+    state: string;
+    currencyCode: string;
+    orderPlacedAt: string | null;
+    /** What an invoice of the order bills: its total with the goodwill rounding folded in. */
+    billableTotalWithTax: number;
+    /**
+     * The due date (`YYYY-MM-DD`) an AR invoice issued today, in the store's zone, would carry
+     * under the order's frozen terms. Null when it froze none (the invoice resolves the customer's
+     * terms when issued) or when they state no single due date (pass explicit terms to
+     * `documents.ar.generateInvoice`, or it is refused).
+     */
+    dueOn: string | null;
+    paymentTerms: OrderPaymentTerms | null;
+}
+export interface DefaultPaymentTermsModule {
+    /**
+     * The store's fallback payment terms in days, used only for a customer no ERP governs and
+     * whose account has none; null when the store has configured none. Needs `ReadSettings`.
+     *
+     * @effect read
+     * @permission ReadSettings
+     */
+    get(options?: Call): Promise<{
+        defaultPaymentTermsDays: number | null;
+    }>;
+    /**
+     * Set the store's fallback payment terms, 0 to 365 days, or clear them with null. Needs
+     * `UpdateSettings`.
+     *
+     * @effect write
+     * @permission UpdateSettings
+     */
+    set(defaultPaymentTermsDays: number | null, options?: Call): Promise<{
+        defaultPaymentTermsDays: number | null;
+    }>;
+}
+export interface CustomerCreditSettingsModule {
+    /**
+     * Whether the active store keeps an accounts-receivable ledger. Writing the switch is the
+     * store settings' (ruling G80: a later `.set()`).
+     *
+     * @effect read
+     */
+    get(options?: Call): Promise<CustomerCreditSettings>;
+}
+export interface CustomerCreditModule {
+    settings: CustomerCreditSettingsModule;
+    /**
+     * The customer's stored credit-account settings, or null when none were ever saved. Needs
+     * `ReadOrder`.
+     *
+     * @effect read
+     * @permission ReadOrder
+     */
+    account(customerId: string, options?: Call): Promise<CreditAccount | null>;
+    /**
+     * The customer's position as the ledger states it: the balance in the account's currency and
+     * in every other, the limit, the terms and the invoice counts. Needs `ReadOrder`. The SDK
+     * caches nothing: every call reads the ledger as it is.
+     *
+     * @effect read
+     * @permission ReadOrder
+     */
+    summary(customerId: string, options?: Call): Promise<CreditAccountSummary>;
+    /**
+     * The customer's credit status (exposure against the limit), with the ledger's balances read
+     * in the same request (`ledgerBalances`). Needs `ReadOrder`.
+     *
+     * Refused `EXCHANGE_RATE_UNAVAILABLE` (→ `BusinessRuleError`) when the customer has a credit
+     * limit and owes money in a currency with no exchange rate to the account's. An engine older
+     * than `setAsideMinor` fails the document's validation.
+     *
+     * @effect read
+     * @permission ReadOrder
+     */
+    status(customerId: string, options?: Call): Promise<CreditStatus>;
+    /**
+     * Create or change the customer's credit account: limit, terms, invoicing mode, statement
+     * day, ERP link. Needs `UpdateOrder`. `AR_LEDGER_NOT_ENABLED`, `CUSTOMER_NOT_FOUND`.
+     *
+     * A credit limit moves no money; the AI tools treat it as an ordinary write (ruling Q2,
+     * flagged for the orchestrator).
+     *
+     * @effect write
+     * @permission UpdateOrder
+     */
+    update(customerId: string, input: UpdateCreditAccountInput, options?: Call): Promise<CreditAccount>;
+    /**
+     * The customer's resolved payment terms (an ERP's condition, the account's own, else the
+     * store's default), or null when nothing resolves, with the due date an AR invoice issued today
+     * would carry under them (`dueOn`, null when they give none). Needs `ReadCustomer`.
+     * `CUSTOMER_NOT_FOUND`. An engine older than `dueOn` is asked again without it, and the
+     * answer carries `dueOn: null`.
+     *
+     * @effect read
+     * @permission ReadCustomer
+     */
+    paymentTerms(customerId: string, options?: Call): Promise<CustomerPaymentTerms | null>;
+    defaultPaymentTerms: DefaultPaymentTermsModule;
+    /**
+     * The customer's orders `documents.ar.generateInvoice` would invoice: no LIVE invoice bills them
+     * yet, on either ledger, newest placement first, paged (`limit` up to 100; walk the pages for
+     * the rest). An order is billed by one ledger, so an order a live store invoice bills is not
+     * listed. An order whose only invoice was voided is listed; a draft, a cart or a cancelled order
+     * is not, as the invoice door refuses it (`INVOICE_ORDER_STATE_BLOCKS_ISSUE`; an older engine
+     * listed a cancelled one and a store-invoiced one). Every state the door invoices is listed,
+     * a parked order included (an older engine left out every order not yet placed). Each says
+     * what its invoice would bill and the due date it would carry. Needs `ReadOrder`.
+     * `CUSTOMER_NOT_FOUND`. An engine older than this method fails the document's validation.
+     *
+     * @effect read
+     * @permission ReadOrder
+     */
+    invoiceableOrders(customerId: string, options?: ListOptions): Promise<Page<InvoiceableOrder>>;
+}
+export declare const CUSTOMER_CREDIT_SETTINGS_QUERY = "\n  query CustomerCreditSettings {\n    activeChannel {\n      id\n      defaultCurrencyCode\n      customFields {\n        b2bCreditEnabled\n      }\n    }\n  }\n";
+export declare const CREDIT_ACCOUNT_QUERY = "\n  query B2bCreditAccount($customerId: ID!) {\n    b2bCreditAccount(customerId: $customerId) { \n  id\n  customerId\n  creditLimit\n  defaultPaymentTermsDays\n  invoicingMode\n  statementDayOfMonth\n  erpLinked\n  currencyCode\n  externalInvoicesSyncedAt\n  externalInvoicesSyncError\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const CREDIT_ACCOUNT_SUMMARY_QUERY = "\n  query B2bCreditAccountSummary($customerId: ID!) {\n    b2bCreditAccountSummary(customerId: $customerId) {\n      customerId\n      currencyCode\n      balance\n      balances {\n        currencyCode\n        balance\n      }\n      creditLimit\n      defaultPaymentTermsDays\n      invoicingMode\n      erpLinked\n      openInvoiceCount\n      overdueInvoiceCount\n    }\n  }\n";
+export declare const CREDIT_STATUS_QUERY = "\n  query B2bCreditStatus($customerId: ID!) {\n    b2bCreditStatus(customerId: $customerId) {\n      customerId\n      currencyCode\n      balance\n      uninvoicedOrdersTotal\n      exposure\n      creditLimit\n      available\n      overdueInvoiceCount\n      overLimit\n      hasOverdue\n      balanceSource\n      exposureByCurrency {\n        currencyCode\n        balance\n        uninvoicedOrdersTotal\n      }\n      unconvertedCurrencies\n      setAsideMinor\n    }\n    # The ledger as of this same request, so the two answers are one moment's.\n    ledger: b2bCreditAccountSummary(customerId: $customerId) {\n      balances {\n        currencyCode\n        balance\n      }\n    }\n  }\n";
+export declare const UPDATE_CREDIT_ACCOUNT_MUTATION = "\n  mutation UpdateB2bCreditAccount($customerId: ID!, $input: UpdateB2bCreditAccountInput!) {\n    updateB2bCreditAccount(customerId: $customerId, input: $input) { \n  id\n  customerId\n  creditLimit\n  defaultPaymentTermsDays\n  invoicingMode\n  statementDayOfMonth\n  erpLinked\n  currencyCode\n  externalInvoicesSyncedAt\n  externalInvoicesSyncError\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const CUSTOMER_PAYMENT_TERMS_QUERY = "\n  query CustomerPaymentTerms($customerId: ID!) {\n    customerPaymentTerms(customerId: $customerId) {\n      customerId\n      \n  source\n  managedExternally\n  status\n  conditionCode\n  conditionDescription\n  summary\n  classification\n  paymentDays\n  paymentEndOfMonths\n  paymentMethod\n  percentage\n  discountPaymentDays\n  discountPercentage\n  paymentDiscountType\n  stale\n  syncedAt\n  error\n\n      dueOn\n    }\n  }\n";
+/** {@link CUSTOMER_PAYMENT_TERMS_QUERY} for an engine older than `dueOn`. */
+export declare const CUSTOMER_PAYMENT_TERMS_LEGACY_QUERY = "\n  query CustomerPaymentTerms($customerId: ID!) {\n    customerPaymentTerms(customerId: $customerId) {\n      customerId\n      \n  source\n  managedExternally\n  status\n  conditionCode\n  conditionDescription\n  summary\n  classification\n  paymentDays\n  paymentEndOfMonths\n  paymentMethod\n  percentage\n  discountPaymentDays\n  discountPercentage\n  paymentDiscountType\n  stale\n  syncedAt\n  error\n\n    }\n  }\n";
+export declare const DEFAULT_PAYMENT_TERMS_QUERY = "\n  query ChannelPaymentTermsDefault {\n    channelPaymentTermsDefault {\n      defaultPaymentTermsDays\n    }\n  }\n";
+export declare const SET_DEFAULT_PAYMENT_TERMS_MUTATION = "\n  mutation SetChannelPaymentTermsDefault($input: SetChannelPaymentTermsDefaultInput!) {\n    setChannelPaymentTermsDefault(input: $input) {\n      defaultPaymentTermsDays\n    }\n  }\n";
+export declare const INVOICEABLE_ORDERS_QUERY = "\n  query ArInvoiceableOrders($customerId: ID!, $options: ArListOptions) {\n    arInvoiceableOrders(customerId: $customerId, options: $options) {\n      items {\n        id\n        code\n        state\n        currencyCode\n        orderPlacedAt\n        billableTotalWithTax\n        dueOn\n        paymentTerms {\n          \n  source\n  managedExternally\n  status\n  conditionCode\n  conditionDescription\n  summary\n  classification\n  paymentDays\n  paymentEndOfMonths\n  paymentMethod\n  percentage\n  discountPaymentDays\n  discountPercentage\n  paymentDiscountType\n  stale\n  syncedAt\n  error\n\n          resolvedAt\n          remoteConditionCode\n          remoteConfirmedAt\n          remoteMismatch\n        }\n      }\n      totalItems\n    }\n  }\n";
+export declare function createCustomerCreditModule(transport: Transport): CustomerCreditModule;

package/dist/customers/credit.js

@@ -0,0 +1,244 @@
+import { pageFromVendureList, readOffsetCursor, ValidationError, } from '@sixtyninecommerce/core';
+const ACCOUNT_FIELDS = /* GraphQL */ `
+  id
+  customerId
+  creditLimit
+  defaultPaymentTermsDays
+  invoicingMode
+  statementDayOfMonth
+  erpLinked
+  currencyCode
+  externalInvoicesSyncedAt
+  externalInvoicesSyncError
+  createdAt
+  updatedAt
+`;
+const PAYMENT_TERMS_FIELDS = /* GraphQL */ `
+  source
+  managedExternally
+  status
+  conditionCode
+  conditionDescription
+  summary
+  classification
+  paymentDays
+  paymentEndOfMonths
+  paymentMethod
+  percentage
+  discountPaymentDays
+  discountPercentage
+  paymentDiscountType
+  stale
+  syncedAt
+  error
+`;
+export const CUSTOMER_CREDIT_SETTINGS_QUERY = /* GraphQL */ `
+  query CustomerCreditSettings {
+    activeChannel {
+      id
+      defaultCurrencyCode
+      customFields {
+        b2bCreditEnabled
+      }
+    }
+  }
+`;
+export const CREDIT_ACCOUNT_QUERY = /* GraphQL */ `
+  query B2bCreditAccount($customerId: ID!) {
+    b2bCreditAccount(customerId: $customerId) { ${ACCOUNT_FIELDS} }
+  }
+`;
+export const CREDIT_ACCOUNT_SUMMARY_QUERY = /* GraphQL */ `
+  query B2bCreditAccountSummary($customerId: ID!) {
+    b2bCreditAccountSummary(customerId: $customerId) {
+      customerId
+      currencyCode
+      balance
+      balances {
+        currencyCode
+        balance
+      }
+      creditLimit
+      defaultPaymentTermsDays
+      invoicingMode
+      erpLinked
+      openInvoiceCount
+      overdueInvoiceCount
+    }
+  }
+`;
+export const CREDIT_STATUS_QUERY = /* GraphQL */ `
+  query B2bCreditStatus($customerId: ID!) {
+    b2bCreditStatus(customerId: $customerId) {
+      customerId
+      currencyCode
+      balance
+      uninvoicedOrdersTotal
+      exposure
+      creditLimit
+      available
+      overdueInvoiceCount
+      overLimit
+      hasOverdue
+      balanceSource
+      exposureByCurrency {
+        currencyCode
+        balance
+        uninvoicedOrdersTotal
+      }
+      unconvertedCurrencies
+      setAsideMinor
+    }
+    # The ledger as of this same request, so the two answers are one moment's.
+    ledger: b2bCreditAccountSummary(customerId: $customerId) {
+      balances {
+        currencyCode
+        balance
+      }
+    }
+  }
+`;
+export const UPDATE_CREDIT_ACCOUNT_MUTATION = /* GraphQL */ `
+  mutation UpdateB2bCreditAccount($customerId: ID!, $input: UpdateB2bCreditAccountInput!) {
+    updateB2bCreditAccount(customerId: $customerId, input: $input) { ${ACCOUNT_FIELDS} }
+  }
+`;
+export const CUSTOMER_PAYMENT_TERMS_QUERY = /* GraphQL */ `
+  query CustomerPaymentTerms($customerId: ID!) {
+    customerPaymentTerms(customerId: $customerId) {
+      customerId
+      ${PAYMENT_TERMS_FIELDS}
+      dueOn
+    }
+  }
+`;
+/** {@link CUSTOMER_PAYMENT_TERMS_QUERY} for an engine older than `dueOn`. */
+export const CUSTOMER_PAYMENT_TERMS_LEGACY_QUERY = /* GraphQL */ `
+  query CustomerPaymentTerms($customerId: ID!) {
+    customerPaymentTerms(customerId: $customerId) {
+      customerId
+      ${PAYMENT_TERMS_FIELDS}
+    }
+  }
+`;
+/**
+ * Whether a failure is "this engine does not know that field yet": the document refused before
+ * it ran, never an execution-time refusal or a transient failure (the purchasing module's rule).
+ */
+function isUnknownFieldRejection(error) {
+    if (!(error instanceof ValidationError) || error.service !== 'vendure')
+        return false;
+    return (error.code === 'BAD_REQUEST' ||
+        error.code === 'GRAPHQL_VALIDATION_FAILED' ||
+        /Cannot query field/i.test(error.message));
+}
+export const DEFAULT_PAYMENT_TERMS_QUERY = /* GraphQL */ `
+  query ChannelPaymentTermsDefault {
+    channelPaymentTermsDefault {
+      defaultPaymentTermsDays
+    }
+  }
+`;
+export const SET_DEFAULT_PAYMENT_TERMS_MUTATION = /* GraphQL */ `
+  mutation SetChannelPaymentTermsDefault($input: SetChannelPaymentTermsDefaultInput!) {
+    setChannelPaymentTermsDefault(input: $input) {
+      defaultPaymentTermsDays
+    }
+  }
+`;
+export const INVOICEABLE_ORDERS_QUERY = /* GraphQL */ `
+  query ArInvoiceableOrders($customerId: ID!, $options: ArListOptions) {
+    arInvoiceableOrders(customerId: $customerId, options: $options) {
+      items {
+        id
+        code
+        state
+        currencyCode
+        orderPlacedAt
+        billableTotalWithTax
+        dueOn
+        paymentTerms {
+          ${PAYMENT_TERMS_FIELDS}
+          resolvedAt
+          remoteConditionCode
+          remoteConfirmedAt
+          remoteMismatch
+        }
+      }
+      totalItems
+    }
+  }
+`;
+/** The engine caps an AR list page at 100 (`clampTake`). */
+const AR_PAGE_LIMIT = 100;
+const INVOICEABLE_PAGE_SIZE = 25;
+export function createCustomerCreditModule(transport) {
+    const invoiceablePage = async (customerId, skip, take, options) => {
+        const data = await transport.graphql({
+            api: 'admin',
+            query: INVOICEABLE_ORDERS_QUERY,
+            variables: { customerId, options: { skip, take } },
+        }, options);
+        return pageFromVendureList(data.arInvoiceableOrders, skip, take, (cursor) => invoiceablePage(customerId, readOffsetCursor(cursor), take, options));
+    };
+    return {
+        settings: {
+            async get(options) {
+                const data = await transport.graphql({ api: 'admin', query: CUSTOMER_CREDIT_SETTINGS_QUERY }, options);
+                return {
+                    enabled: data.activeChannel.customFields?.b2bCreditEnabled === true,
+                    defaultCurrencyCode: data.activeChannel.defaultCurrencyCode,
+                };
+            },
+        },
+        async account(customerId, options) {
+            const data = await transport.graphql({ api: 'admin', query: CREDIT_ACCOUNT_QUERY, variables: { customerId } }, options);
+            return data.b2bCreditAccount;
+        },
+        async summary(customerId, options) {
+            const data = await transport.graphql({ api: 'admin', query: CREDIT_ACCOUNT_SUMMARY_QUERY, variables: { customerId } }, options);
+            return data.b2bCreditAccountSummary;
+        },
+        async status(customerId, options) {
+            const data = await transport.graphql({ api: 'admin', query: CREDIT_STATUS_QUERY, variables: { customerId } }, options);
+            return { ...data.b2bCreditStatus, ledgerBalances: data.ledger.balances };
+        },
+        async update(customerId, input, options) {
+            const data = await transport.graphql({ api: 'admin', query: UPDATE_CREDIT_ACCOUNT_MUTATION, variables: { customerId, input } }, options);
+            return data.updateB2bCreditAccount;
+        },
+        async paymentTerms(customerId, options) {
+            try {
+                const data = await transport.graphql({ api: 'admin', query: CUSTOMER_PAYMENT_TERMS_QUERY, variables: { customerId } }, options);
+                return data.customerPaymentTerms;
+            }
+            catch (error) {
+                // An engine older than `dueOn` refuses the whole document; the terms are still readable.
+                if (!isUnknownFieldRejection(error))
+                    throw error;
+                const data = await transport.graphql({ api: 'admin', query: CUSTOMER_PAYMENT_TERMS_LEGACY_QUERY, variables: { customerId } }, options);
+                return data.customerPaymentTerms ? { ...data.customerPaymentTerms, dueOn: null } : null;
+            }
+        },
+        defaultPaymentTerms: {
+            async get(options) {
+                const data = await transport.graphql({ api: 'admin', query: DEFAULT_PAYMENT_TERMS_QUERY }, options);
+                return data.channelPaymentTermsDefault;
+            },
+            async set(defaultPaymentTermsDays, options) {
+                const data = await transport.graphql({
+                    api: 'admin',
+                    query: SET_DEFAULT_PAYMENT_TERMS_MUTATION,
+                    variables: { input: { defaultPaymentTermsDays } },
+                }, options);
+                return data.setChannelPaymentTermsDefault;
+            },
+        },
+        invoiceableOrders(customerId, options) {
+            // The Admin API is offset-paged; the offset hides inside the cursor (spec §9.3).
+            const take = Math.min(options?.limit ?? INVOICEABLE_PAGE_SIZE, AR_PAGE_LIMIT);
+            const skip = options?.after === undefined ? 0 : readOffsetCursor(options.after);
+            return invoiceablePage(customerId, skip, take, options);
+        },
+    };
+}

package/dist/customers/delivery-preferences.d.ts

@@ -0,0 +1,120 @@
+/**
+ * A customer's saved delivery preferences (headless spec §9.2 `customers` "delivery
+ * preferences"; W10-33): reusable values for one fulfilment handler's form, which the
+ * create-fulfilment flow pre-fills from.
+ */
+import type { Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+export interface CustomerDeliveryPreference {
+    id: string;
+    /** ISO-8601 with offset. */
+    createdAt: string;
+    /** ISO-8601 with offset. */
+    updatedAt: string;
+    /** The fulfilment handler the values are for (`manual-fulfillment`, a carrier's code, …). */
+    fulfillmentHandlerCode: string;
+    name: string;
+    /** The handler's fields by name, as its schema declares them; stored and answered verbatim. */
+    values: Record<string, unknown>;
+    /** At most one preference per customer and handler is the default. */
+    isDefault: boolean;
+    /**
+     * Set when the caller's customer-data level blanked `name` and `values` (an app installation
+     * below `full`): they then mean "not granted". Never write such a preference back.
+     */
+    redacted?: true;
+}
+export interface CreateDeliveryPreferenceInput {
+    customerId: string;
+    fulfillmentHandlerCode: string;
+    /** 1 to 255 characters after trimming. */
+    name: string;
+    values: Record<string, unknown>;
+    /** Making one the default takes the mark off the customer's other one for the handler. */
+    isDefault?: boolean;
+}
+export interface UpdateDeliveryPreferenceInput {
+    name?: string;
+    /** Replaces the stored values as a whole. */
+    values?: Record<string, unknown>;
+    isDefault?: boolean;
+}
+/** One selectable value of a select field. */
+export interface DeliveryPreferenceFieldOption {
+    value: string;
+    label: string;
+}
+/** One field of a fulfilment handler's delivery preference form. */
+export interface DeliveryPreferenceField {
+    /** The key the value is stored under in a preference's `values`. */
+    name: string;
+    /** `string`, `int` or `boolean`. */
+    type: string;
+    /** A rendering hint (`text-form-input`, `select-form-input`, `switch-form-input`, …). */
+    uiComponent: string;
+    label: string;
+    /** Present for a select field. */
+    options: DeliveryPreferenceFieldOption[] | null;
+    defaultValue: string | number | boolean | null;
+}
+/** The fields one fulfilment handler saves per customer. */
+export interface DeliveryPreferenceSchema {
+    handlerCode: string;
+    fields: DeliveryPreferenceField[];
+}
+export interface CustomerDeliveryPreferencesModule {
+    /**
+     * The customer's delivery preferences in this store, oldest first; `[]` for a customer with
+     * none, and for one the store does not hold. `handlerCode` keeps one handler's. Needs
+     * `ReadCustomer`.
+     *
+     * @effect read
+     */
+    list(customerId: string, options?: Call & {
+        handlerCode?: string;
+    }): Promise<CustomerDeliveryPreference[]>;
+    /**
+     * The preference form of each fulfilment handler the platform runs: which fields a
+     * preference's `values` may carry. The same for every store. Needs `ReadOrder` or
+     * `ReadCustomer`.
+     *
+     * @effect read
+     */
+    schemas(options?: Call): Promise<DeliveryPreferenceSchema[]>;
+    /**
+     * Save a delivery preference for a customer. Needs `UpdateCustomer`.
+     *
+     * Refused with the engine's sentence (`ValidationError`, `USER_INPUT_ERROR`, 400): an empty
+     * or over-long name or handler code, or a customer that already has 50. A handler of a plugin
+     * the store does not have is `PLUGIN_ACCESS_DENIED` (`PermissionDeniedError`, 403). A customer
+     * this store does not hold is a `NotFoundError` (`ENTITY_NOT_FOUND`); an engine older than
+     * that check saved the preference under any id, where no read ever showed it.
+     *
+     * @effect write
+     */
+    create(input: CreateDeliveryPreferenceInput, options?: Call): Promise<CustomerDeliveryPreference>;
+    /**
+     * Change a preference; what is left out is kept. Needs `UpdateCustomer`. An id that is not a
+     * preference of this store is refused with the engine's sentence (`ValidationError`,
+     * `USER_INPUT_ERROR`, 400).
+     *
+     * @effect write
+     */
+    update(id: string, input: UpdateDeliveryPreferenceInput, options?: Call): Promise<CustomerDeliveryPreference>;
+    /**
+     * Remove a preference. Needs `UpdateCustomer`.
+     *
+     * Refused `CUSTOMER_DELIVERY_PREFERENCE_NOT_DELETED` (`ConflictError`, 409) with the engine's
+     * own reason when this store has no such preference.
+     *
+     * @effect destructive
+     */
+    delete(id: string, options?: Call): Promise<void>;
+}
+export declare const DELIVERY_PREFERENCE_FIELDS = "\n  id\n  createdAt\n  updatedAt\n  fulfillmentHandlerCode\n  name\n  values\n  isDefault\n";
+export declare const DELIVERY_PREFERENCES_QUERY = "\n  query CustomerDeliveryPreferences($id: ID!, $fulfillmentHandlerCode: String) {\n    customer(id: $id) {\n      id\n      deliveryPreferences(fulfillmentHandlerCode: $fulfillmentHandlerCode) {\n        \n  id\n  createdAt\n  updatedAt\n  fulfillmentHandlerCode\n  name\n  values\n  isDefault\n\n      }\n    }\n  }\n";
+export declare const DELIVERY_PREFERENCE_SCHEMAS_QUERY = "\n  query DeliveryPreferenceSchemas {\n    deliveryPreferenceSchemas {\n      handlerCode\n      fields {\n        name\n        type\n        uiComponent\n        label\n        options {\n          value\n          label\n        }\n        defaultValue\n      }\n    }\n  }\n";
+export declare const CREATE_DELIVERY_PREFERENCE_MUTATION = "\n  mutation CreateCustomerDeliveryPreference($input: CreateCustomerDeliveryPreferenceInput!) {\n    createCustomerDeliveryPreference(input: $input) {\n      \n  id\n  createdAt\n  updatedAt\n  fulfillmentHandlerCode\n  name\n  values\n  isDefault\n\n    }\n  }\n";
+export declare const UPDATE_DELIVERY_PREFERENCE_MUTATION = "\n  mutation UpdateCustomerDeliveryPreference($input: UpdateCustomerDeliveryPreferenceInput!) {\n    updateCustomerDeliveryPreference(input: $input) {\n      \n  id\n  createdAt\n  updatedAt\n  fulfillmentHandlerCode\n  name\n  values\n  isDefault\n\n    }\n  }\n";
+export declare const DELETE_DELIVERY_PREFERENCE_MUTATION = "\n  mutation DeleteCustomerDeliveryPreference($id: ID!) {\n    deleteCustomerDeliveryPreference(id: $id) {\n      result\n      message\n    }\n  }\n";
+export declare function createCustomerDeliveryPreferencesModule(transport: Transport): CustomerDeliveryPreferencesModule;