@sixtyninecommerce/admin 0.11.0 → 0.12.0

package/dist/payments/account-credit.js

@@ -1,3 +1,4 @@
+import { customerAgreedVariable } from './customer-consent.js';
 import { STORE_CREDIT_MOVE_FIELDS } from './store-credit-fields.js';
 const UNAPPLIED_CASH_FIELDS = /* GraphQL */ `
   id
@@ -34,6 +35,25 @@ export const CREDIT_ORDER_OVERPAYMENT_TO_STORE_CREDIT_MUTATION = /* GraphQL */ `
     }
   }
 `;
+/**
+ * The same, declaring the customer's answer to store credit: sent only by a call that states it,
+ * so an engine before the argument still takes every call that does not.
+ */
+export const CREDIT_ORDER_OVERPAYMENT_TO_STORE_CREDIT_WITH_CONSENT_MUTATION = /* GraphQL */ `
+  mutation CreditOrderOverpaymentToStoreCredit(
+    $input: CreditOrderOverpaymentInput!
+    $idempotencyKey: String
+    $customerAgreed: Boolean
+  ) {
+    creditOrderOverpaymentToStoreCredit(
+      input: $input
+      idempotencyKey: $idempotencyKey
+      customerAgreed: $customerAgreed
+    ) {
+      ${STORE_CREDIT_MOVE_FIELDS}
+    }
+  }
+`;
 export const UNAPPLIED_CASH_QUERY = /* GraphQL */ `
   query ArUnappliedCash($customerId: ID!) {
     arUnappliedCash(customerId: $customerId) {
@@ -91,10 +111,13 @@ export function createAccountCreditModule(transport) {
             return data.creditOrderOverpaymentToAccount;
         },
         async creditOverpaymentToStoreCredit(input, options) {
+            const customerAgreed = customerAgreedVariable(options?.customerAgreed);
             const data = await transport.graphql({
                 api: 'admin',
-                query: CREDIT_ORDER_OVERPAYMENT_TO_STORE_CREDIT_MUTATION,
-                variables: { input, idempotencyKey: options?.idempotencyKey },
+                query: customerAgreed === undefined
+                    ? CREDIT_ORDER_OVERPAYMENT_TO_STORE_CREDIT_MUTATION
+                    : CREDIT_ORDER_OVERPAYMENT_TO_STORE_CREDIT_WITH_CONSENT_MUTATION,
+                variables: { input, idempotencyKey: options?.idempotencyKey, customerAgreed },
             }, options);
             return data.creditOrderOverpaymentToStoreCredit;
         },

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

@@ -1,5 +1,8 @@
 import type { Transport } from '@sixtyninecommerce/core';
-/** `document` without the fields above: what an engine before them accepts. */
+/**
+ * `document` without the fields above: what an engine before them accepts. `payable` is newer
+ * still (`payableAware`), so an engine without the credit fields lacks it too and it goes with them.
+ */
 export declare function withoutCreditNotedFields(document: string): string;
 /**
  * The transport, sending a document that names the credit fields once more without them when the
@@ -10,3 +13,7 @@ export declare function withoutCreditNotedFields(document: string): string;
  * that knows neither (four sends at most).
  */
 export declare function creditNotedAware(transport: Pick<Transport, 'graphql'>): Pick<Transport, 'graphql'>;
+/** `document` without `payable`: what an engine before it accepts. */
+export declare function withoutPayableField(document: string): string;
+/** The transport, sending a document that names `payable` once more without it when refused. */
+export declare function payableAware(transport: Pick<Transport, 'graphql'>): Pick<Transport, 'graphql'>;

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

@@ -7,8 +7,11 @@ import { isUnknownFieldRejection } from './store-credit-fields.js';
  * 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. */
+const CREDIT_NOTED_FIELDS = [/\bcreditNoted\b/g, /\bowed\b/g, /\bpayable\b/g];
+/**
+ * `document` without the fields above: what an engine before them accepts. `payable` is newer
+ * still (`payableAware`), so an engine without the credit fields lacks it too and it goes with them.
+ */
 export function withoutCreditNotedFields(document) {
     return CREDIT_NOTED_FIELDS.reduce((text, field) => text.replace(field, ''), document);
 }
@@ -35,3 +38,32 @@ export function creditNotedAware(transport) {
         },
     };
 }
+/**
+ * The payment position's `payable` (branch `murat/order-paid-measures-credit-notes`): what the
+ * order's settled money must reach before it counts as paid, its total less what a live invoice's
+ * credit notes took off. Newer than `creditNoted` and `owed`, so it falls away FIRST:
+ * `creditNotedAware(payableAware(transport))` resends without `payable` on an engine that has the
+ * credit fields and not this one (two sends), and without all three on an engine before them
+ * (three sends: the credit fallback drops `payable` too). Absent, it reads as `total`.
+ */
+const PAYABLE_FIELD = /\bpayable\b/g;
+/** `document` without `payable`: what an engine before it accepts. */
+export function withoutPayableField(document) {
+    return document.replace(PAYABLE_FIELD, '');
+}
+/** The transport, sending a document that names `payable` once more without it when refused. */
+export function payableAware(transport) {
+    return {
+        async graphql(call, options) {
+            try {
+                return await transport.graphql(call, options);
+            }
+            catch (error) {
+                const legacy = withoutPayableField(call.query);
+                if (legacy === call.query || !isUnknownFieldRejection(error))
+                    throw error;
+                return transport.graphql({ ...call, query: legacy }, options);
+            }
+        },
+    };
+}

package/dist/payments/customer-consent.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The customer's answer to store credit (incentives sprint 8, ruling Q4): on a door where staff
+ * choose to credit the customer instead of refunding them, whether the customer EXPRESSLY agreed
+ * to store credit instead of a refund to their payment (EU consumer law, CRD art. 13(1)). In a
+ * store whose book is store credit the move records it on its ledger entries
+ * (`StoredValueEntry.customerAgreed`); in an AR store, on a refund, or when nothing moves it is
+ * accepted and recorded nowhere. It is a record, never a condition: no door refuses for it.
+ *
+ * Sent only when stated. Left out, nothing of it reaches the wire, so a call that does not state
+ * it is the request it always was, and an engine before the field still takes it. A call that
+ * DOES state it needs an engine that knows the field (incentives sprint 8 PR 6a): an older one
+ * refuses the document before it runs, and that refusal is surfaced, never retried without the
+ * answer.
+ */
+/** `value` as a variable: `true` or `false` when stated, else `undefined` (off the wire). */
+export declare function customerAgreedVariable(value: unknown): boolean | undefined;
+/** `{ customerAgreed }` when stated, else nothing: spread into an input object. */
+export declare function statedCustomerAgreed(value: unknown): {
+    customerAgreed?: boolean;
+};
+/**
+ * `document` with `$customerAgreed: Boolean` declared after the line `declaration` and passed as
+ * `customerAgreed: $customerAgreed` after the line `argument` (each matched whole, trimmed), in
+ * the same indentation. Built from the document a call without the answer sends, so the two never
+ * drift; it throws at load when either line is missing.
+ */
+export declare function withCustomerAgreed(document: string, anchor: {
+    declaration: string;
+    argument: string;
+}): string;

package/dist/payments/customer-consent.js

@@ -0,0 +1,49 @@
+/**
+ * The customer's answer to store credit (incentives sprint 8, ruling Q4): on a door where staff
+ * choose to credit the customer instead of refunding them, whether the customer EXPRESSLY agreed
+ * to store credit instead of a refund to their payment (EU consumer law, CRD art. 13(1)). In a
+ * store whose book is store credit the move records it on its ledger entries
+ * (`StoredValueEntry.customerAgreed`); in an AR store, on a refund, or when nothing moves it is
+ * accepted and recorded nowhere. It is a record, never a condition: no door refuses for it.
+ *
+ * Sent only when stated. Left out, nothing of it reaches the wire, so a call that does not state
+ * it is the request it always was, and an engine before the field still takes it. A call that
+ * DOES state it needs an engine that knows the field (incentives sprint 8 PR 6a): an older one
+ * refuses the document before it runs, and that refusal is surfaced, never retried without the
+ * answer.
+ */
+/** `value` as a variable: `true` or `false` when stated, else `undefined` (off the wire). */
+export function customerAgreedVariable(value) {
+    return typeof value === 'boolean' ? value : undefined;
+}
+/** `{ customerAgreed }` when stated, else nothing: spread into an input object. */
+export function statedCustomerAgreed(value) {
+    const stated = customerAgreedVariable(value);
+    return stated === undefined ? {} : { customerAgreed: stated };
+}
+/**
+ * `document` with `$customerAgreed: Boolean` declared after the line `declaration` and passed as
+ * `customerAgreed: $customerAgreed` after the line `argument` (each matched whole, trimmed), in
+ * the same indentation. Built from the document a call without the answer sends, so the two never
+ * drift; it throws at load when either line is missing.
+ */
+export function withCustomerAgreed(document, anchor) {
+    let declared = false;
+    let passed = false;
+    const lines = document.split('\n').flatMap((line) => {
+        const indent = /^\s*/.exec(line)?.[0] ?? '';
+        if (!declared && line.trim() === anchor.declaration) {
+            declared = true;
+            return [line, `${indent}$customerAgreed: Boolean`];
+        }
+        if (declared && !passed && line.trim() === anchor.argument) {
+            passed = true;
+            return [line, `${indent}customerAgreed: $customerAgreed`];
+        }
+        return [line];
+    });
+    if (!declared || !passed) {
+        throw new Error(`withCustomerAgreed: "${anchor.declaration}" or "${anchor.argument}" is not a line of the document`);
+    }
+    return lines.join('\n');
+}

package/dist/payments/index.d.ts

@@ -52,9 +52,20 @@ export interface OrderPaymentPosition {
      */
     owed?: number;
     /**
-     * `total - covered`, floored at zero: what the payments are short of the order's total, and
-     * what `record` caps a payment at. On an order whose credit notes took part of its bill off,
-     * `owed` is what the customer still owes.
+     * What the order's SETTLED money must reach before it counts as paid: `total` less what a live
+     * invoice's credit notes took off it. An order paid down to what its invoice bills net of its
+     * credit notes is paid in full: `orders.settle`, the staff move into `PaymentSettled` and the
+     * platform's own settlement all measure this figure. Equals `total` when nothing was credited,
+     * and also when the order's only invoice was cancelled with nothing in its place (it owes
+     * nothing more, `owed`, but counts as paid only once it is invoiced again or cancelled). Read by
+     * {@link PaymentsModule.position} and `orders.paymentPosition`; against an engine that does not
+     * serve it those calls resend without it, and an absent `payable` reads as `total`.
+     */
+    payable?: number;
+    /**
+     * `total - covered`, floored at zero: what the payments are short of the order's total. On an
+     * order whose credit notes took part of its bill off, `owed` is what the customer still owes,
+     * and what `record` caps a payment at.
      */
     outstanding: number;
     /**
@@ -67,14 +78,19 @@ export interface OrderPaymentPosition {
      * (`payments.accountCredit.creditOverpayment`) no longer counts here.
      */
     overpaid: number;
-    /** What a further payment may take. */
+    /**
+     * What a further payment may take: what is still owed once the credit notes are counted
+     * (`owed`; `outstanding` when nothing was credited). An engine before the credit-noted caps
+     * answers `outstanding` here.
+     */
     availableToCharge: number;
 }
 /** Money the merchant HAS, recorded against an order. */
 export interface RecordPaymentInput {
     /**
-     * Minor units of the order's currency. Greater than zero, and at most the
-     * order's `outstanding` — an over-payment is refused rather than accepted,
+     * Minor units of the order's currency. Greater than zero, and at most what the
+     * order still owes (its position's `owed`: `outstanding` less what its credit
+     * notes took off its bill) — an over-payment is refused rather than accepted,
      * and the refusal carries the position so a till can correct itself without a
      * second round trip.
      */
@@ -306,6 +322,36 @@ export interface OrderPaymentRecord {
     /** The provider's reference for the payment, when it gave one. */
     transactionId: string | null;
 }
+/** A coded refusal "mark as paid" would answer now ({@link PaymentsModule.settlePreview}). */
+export interface PaymentSettleRefusal {
+    /**
+     * `PAYMENT_CAPTURE_EXCEEDS_BILLED`, `ORDER_CANCELLED_PAYMENT_CONFLICT` or
+     * `PAYMENT_STATE_TRANSITION_ERROR`: the code {@link PaymentsModule.settle} would throw.
+     */
+    code: string;
+    /** The engine's sentence for staff: why, and what to do instead. */
+    message: string;
+}
+/**
+ * What {@link PaymentsModule.settle} would do to an authorized payment as its order stands now
+ * ({@link PaymentsModule.settlePreview}). Nothing was written. Minor units of the order's currency.
+ */
+export interface PaymentSettlePreview {
+    paymentId: string;
+    /** The payment's amount as it stands: what it authorized. */
+    authorized: number;
+    /**
+     * What the capture records now: `authorized`, or less on an order whose credit notes lowered
+     * what it bills (the rest of a promise whose money moves by hand is dropped). 0 when refused.
+     */
+    records: number;
+    /** What the order's credit notes took off what it bills; 0 when the capture is whole. */
+    creditNoted: number;
+    /** The numbers of the credit notes behind `records` or the refusal, oldest first. */
+    creditNotes: string[];
+    /** Null when the capture may run; else the coded refusal it would answer now. */
+    refusal: PaymentSettleRefusal | null;
+}
 /** What a payment app reports happened to a payment it took (`reportAppPayment`). */
 export type AppPaymentReportState = 'Authorized' | 'Settled' | 'Declined' | 'Cancelled';
 /** An app's report on one of its payments. */
@@ -417,11 +463,15 @@ export interface PaymentsModule {
      * argument, so a retry under the same key returns the first call's order
      * rather than taking the money twice. Use a fresh key per intended payment.
      *
-     * Refusals: `AMOUNT_EXCEEDS_OUTSTANDING` (over-payment, with the position
-     * attached), `AMOUNT_NOT_POSITIVE`, `ORDER_NOT_RECORDABLE` (the order's state
-     * cannot take a payment), `DEPOSITS_NOT_ENABLED` — a PARTIAL payment on a
-     * store that has not turned deposits on; paying the whole outstanding balance
-     * is not a deposit and always works — `METADATA_KEY_RESERVED`,
+     * Refusals: `AMOUNT_EXCEEDS_OUTSTANDING` (more than the order still owes,
+     * `owed`, with the position attached; its message names the credit notes that
+     * lowered it), `AMOUNT_NOT_POSITIVE`, `ORDER_NOT_RECORDABLE` (the order's state
+     * cannot take a payment), `DEPOSITS_NOT_ENABLED` — a PARTIAL payment (less
+     * than `owed`) on a store that has not turned deposits on; paying all it owes
+     * is not a deposit and always works, and neither is a stored-value payment (a
+     * gift card or store credit) on an order still arranging payment: that part is
+     * taken whatever the deposit policy, and the order is placed only once its
+     * money covers it — `METADATA_KEY_RESERVED`,
      * `PAYMENT_METHOD_NOT_FOUND`, `ORDER_NOT_FOUND`.
      *
      * @effect money
@@ -429,7 +479,8 @@ export interface PaymentsModule {
     record(orderId: string, input: RecordPaymentInput, options?: Call): Promise<PaidOrder>;
     /**
      * Read an order's payment position: what it bills, what was paid and refunded, what its credit
-     * notes took off (`creditNoted`) and what the customer still owes after them (`owed`).
+     * notes took off (`creditNoted`), what the customer still owes after them (`owed`) and what its
+     * settled money must reach before it counts as paid (`payable`).
      *
      * @effect read
      */
@@ -551,15 +602,38 @@ export interface PaymentsModule {
      *   order could not move on as it stands.
      * - `ORDER_CANCELLED_PAYMENT_CONFLICT` (409): the payment's order is cancelled, and a cancelled
      *   order is never paid. Cancel the payment instead to release it.
+     * - `PAYMENT_CAPTURE_EXCEEDS_BILLED` (422): the order's credit notes lowered what it bills, and
+     *   the payment would take more: its provider can only capture it in full, the order's other
+     *   payments already cover the bill, or its only invoice was cancelled with nothing in its
+     *   place. Nothing was captured; the error's `extensions.leftToPay` is what is left to pay
+     *   without this payment (the bill after its credit notes, less the order's other payments),
+     *   and the message names the credit notes and what to do instead.
      * - `PAYMENT_SETTLE_CONFLICT` (409): the payment moved while it was being captured. Read it
      *   again.
      * - `ENTITY_NOT_FOUND` (404): no payment of an order of this store has that id.
      *
+     * On such an order, a promise whose money moves by hand (bank transfer, invoice, net terms) is
+     * recorded at what the order still bills: the returned payment's `amount` is that figure, and
+     * the rest of the promise is dropped. {@link settlePreview} says which before you call this.
+     *
      * Needs `UpdateOrder`.
      *
      * @effect money
      */
     settle(paymentId: string, options?: Call): Promise<OrderPaymentRecord>;
+    /**
+     * What {@link settle} would do to this authorized payment now, without doing it: the amount it
+     * records, or the coded refusal it would answer (`refusal`). Nothing is written, nothing is
+     * locked and no provider is asked, so {@link settle} still judges again (and the provider may
+     * still decline it).
+     *
+     * Refuses `ENTITY_NOT_FOUND` (404) for a payment of no order of this store. An engine older
+     * than this method answers a GraphQL validation error: treat that as "no preview" and let
+     * {@link settle} judge. Needs `ReadOrder`.
+     *
+     * @effect read
+     */
+    settlePreview(paymentId: string, options?: Call): Promise<PaymentSettlePreview>;
     /**
      * Void an authorized payment (release the hold), and return the payment.
      *
@@ -700,7 +774,7 @@ export interface PaymentsModule {
     appPayments(orderId: string, options?: Call): Promise<AppPayment[]>;
 }
 export declare const RECORD_ORDER_PAYMENT_MUTATION = "\n  mutation RecordOrderPayment($orderId: ID!, $input: RecordPaymentInput!, $idempotencyKey: String) {\n    recordOrderPayment(orderId: $orderId, input: $input, idempotencyKey: $idempotencyKey) {\n      \n  id\n  code\n  state\n  currencyCode\n  total\n  totalWithTax\n\n    }\n  }\n";
-export declare const ORDER_PAYMENT_POSITION_QUERY = "\n  query OrderPaymentPosition($orderId: ID!) {\n    orderPaymentPosition(orderId: $orderId) {\n      \n  total\n  covered\n  settled\n  authorized\n  refunded\n  creditNoted\n  owed\n  outstanding\n  overpaid\n  availableToCharge\n\n    }\n  }\n";
+export declare const ORDER_PAYMENT_POSITION_QUERY = "\n  query OrderPaymentPosition($orderId: ID!) {\n    orderPaymentPosition(orderId: $orderId) {\n      \n  total\n  covered\n  settled\n  authorized\n  refunded\n  creditNoted\n  owed\n  payable\n  outstanding\n  overpaid\n  availableToCharge\n\n    }\n  }\n";
 export declare const ORDER_REFUND_POSITION_QUERY = "\n  query OrderRefundPosition($orderId: ID!) {\n    orderRefundPosition(orderId: $orderId) {\n      \n  currencyCode\n  refunded\n  refundable\n  perPayment {\n    paymentId\n    state\n    method\n    amount\n    refunded\n    refundable\n    tookMoney\n  }\n\n    }\n  }\n";
 export declare const REFUND_ORDER_PAYMENT_MUTATION = "\n  mutation RefundOrderPayment($input: RefundPaymentInput!, $idempotencyKey: String) {\n    refundOrderPayment(input: $input, idempotencyKey: $idempotencyKey) {\n      id\n      total\n      state\n      method\n      transactionId\n      reason\n    }\n  }\n";
 export declare const UNRECONCILED_REFUNDS_QUERY = "\n  query UnreconciledRefunds($orderId: ID!) {\n    orderRefundPosition(orderId: $orderId) {\n      unreconciled {\n        refundId\n        paymentId\n        amount\n        createdAt\n      }\n    }\n  }\n";
@@ -709,10 +783,11 @@ export declare const REFUND_CREDIT_NOTE_REQUIREMENT_QUERY = "\n  query RefundCre
 export declare const RECONCILE_REFUND_OUTCOME_MUTATION = "\n  mutation ReconcileRefundOutcome($input: ReconcileRefundOutcomeInput!, $idempotencyKey: String) {\n    reconcileRefundOutcome(input: $input, idempotencyKey: $idempotencyKey) {\n      id\n      total\n      state\n      method\n      transactionId\n      reason\n    }\n  }\n";
 export declare const SETTLE_PAYMENT_MUTATION = "\n  mutation SettlePayment($id: ID!) {\n    settlePayment(id: $id) {\n      __typename\n      ... on Payment {\n        \n  id\n  state\n  method\n  amount\n  transactionId\n\n      }\n      ... on SettlePaymentError {\n        paymentErrorMessage\n      }\n      ... on PaymentStateTransitionError {\n        transitionError\n      }\n      ... on OrderStateTransitionError {\n        transitionError\n      }\n      ... on ErrorResult {\n        errorCode\n        message\n      }\n    }\n  }\n";
 export declare const CANCEL_PAYMENT_MUTATION = "\n  mutation CancelPayment($id: ID!) {\n    cancelPayment(id: $id) {\n      __typename\n      ... on Payment {\n        \n  id\n  state\n  method\n  amount\n  transactionId\n\n      }\n      ... on CancelPaymentError {\n        paymentErrorMessage\n      }\n      ... on PaymentStateTransitionError {\n        transitionError\n      }\n      ... on ErrorResult {\n        errorCode\n        message\n      }\n    }\n  }\n";
+export declare const SETTLE_PAYMENT_PREVIEW_QUERY = "\n  query SettlePaymentPreview($paymentId: ID!) {\n    settlePaymentPreview(paymentId: $paymentId) {\n      paymentId\n      authorized\n      records\n      creditNoted\n      creditNotes\n      refusal {\n        code\n        message\n      }\n    }\n  }\n";
 export declare const REPORT_APP_PAYMENT_MUTATION = "\n  mutation ReportAppPayment(\n    $paymentId: ID!\n    $input: ReportAppPaymentInput!\n    $idempotencyKey: String!\n  ) {\n    reportAppPayment(paymentId: $paymentId, input: $input, idempotencyKey: $idempotencyKey) {\n      id\n      state\n      amount\n      method\n      transactionId\n    }\n  }\n";
 export declare const APP_PAYMENTS_QUERY = "\n  query AppPayments($orderId: ID!) {\n    appPayments(orderId: $orderId) {\n      id\n      orderId\n      orderCode\n      state\n      amount\n      currencyCode\n      providerReference\n      methodCode\n      outcomeUnknown\n      createdAt\n    }\n  }\n";
 export declare function createPaymentsModule(transport: Transport): PaymentsModule;
-export type { AccountCreditModule, ApplyUnappliedCashInput, CreditOverpaymentInput, OrderMoneyOnAccount, RefundUnappliedCashInput, StoreCreditMove, UnappliedCash, UnappliedCashRefund, } from './account-credit.js';
+export type { AccountCreditModule, ApplyUnappliedCashInput, CreditOverpaymentInput, CreditOverpaymentToStoreCreditCall, OrderMoneyOnAccount, RefundUnappliedCashInput, StoreCreditMove, UnappliedCash, UnappliedCashRefund, } from './account-credit.js';
 export type { ConnectedAccountModule, StripeConnectedAccount, } from './connected-account.js';
 export type { CreatePaymentMethodInput, PaymentMethod, PaymentMethodCredential, PaymentMethodCredentialPath, PaymentMethodsModule, PaymentMethodTranslation, PaymentMethodTranslationInput, UpdatePaymentMethodInput, } from './methods.js';
 export type { MollieDiagnosis, MollieDiagnosisMethod, MollieDiagnosisVerdict, MollieDirectDebitDiagnosis, MollieMethod, MollieMethodList, MollieMethodsModule, MollieProbeError, MollieProbeErrorKind, SetMollieMethodsInput, } from './mollie-methods.js';

package/dist/payments/index.js

@@ -1,7 +1,7 @@
 import { BusinessRuleError, errorFromErrorResult, isErrorResult, } from '@sixtyninecommerce/core';
 import { createAccountCreditModule } from './account-credit.js';
 import { createArPaymentsModule } from './ar.js';
-import { creditNotedAware } from './credit-noted-fields.js';
+import { creditNotedAware, payableAware } from './credit-noted-fields.js';
 import { createPaymentMethodsModule } from './methods.js';
 import { createPaymentLinksModule } from './payment-links.js';
 import { createProvidersModule } from './providers.js';
@@ -22,6 +22,7 @@ const POSITION_FIELDS = /* GraphQL */ `
   refunded
   creditNoted
   owed
+  payable
   outstanding
   overpaid
   availableToCharge
@@ -175,6 +176,21 @@ export const CANCEL_PAYMENT_MUTATION = /* GraphQL */ `
     }
   }
 `;
+export const SETTLE_PAYMENT_PREVIEW_QUERY = /* GraphQL */ `
+  query SettlePaymentPreview($paymentId: ID!) {
+    settlePaymentPreview(paymentId: $paymentId) {
+      paymentId
+      authorized
+      records
+      creditNoted
+      creditNotes
+      refusal {
+        code
+        message
+      }
+    }
+  }
+`;
 /** The union members that mean "the provider said no", renamed so a caller branches on intent. */
 const DECLINE_CODES = {
     SETTLE_PAYMENT_ERROR: 'PAYMENT_SETTLE_DECLINED',
@@ -251,7 +267,7 @@ export function createPaymentsModule(transport) {
         },
         async position(orderId, options) {
             // The credit fields fall away on an engine before them: the position itself still reads.
-            const data = await creditNotedAware(transport).graphql({ api: 'admin', query: ORDER_PAYMENT_POSITION_QUERY, variables: { orderId } }, options);
+            const data = await creditNotedAware(payableAware(transport)).graphql({ api: 'admin', query: ORDER_PAYMENT_POSITION_QUERY, variables: { orderId } }, options);
             return data.orderPaymentPosition;
         },
         async refund(input, options) {
@@ -269,6 +285,10 @@ export function createPaymentsModule(transport) {
             const data = await transport.graphql({ api: 'admin', query: SETTLE_PAYMENT_MUTATION, variables: { id: paymentId } }, options);
             return paymentOrThrow(data.settlePayment);
         },
+        async settlePreview(paymentId, options) {
+            const data = await transport.graphql({ api: 'admin', query: SETTLE_PAYMENT_PREVIEW_QUERY, variables: { paymentId } }, options);
+            return data.settlePaymentPreview;
+        },
         async cancel(paymentId, options) {
             const data = await transport.graphql({ api: 'admin', query: CANCEL_PAYMENT_MUTATION, variables: { id: paymentId } }, options);
             return paymentOrThrow(data.cancelPayment);

package/dist/payments/requests.d.ts

@@ -10,13 +10,16 @@ export type PaymentRequestStatus = (typeof PAYMENT_REQUEST_STATUSES)[number];
 /**
  * Why a payment request closed: `PAID` (its payment landed), `EXPIRED`,
  * `CANCELLED` (by staff, `requests.cancel`), `ORDER_SETTLED` (the order's
- * balance reached zero through another payment), `ORDER_CANCELLED`, or
+ * balance reached zero through another payment), `ORDER_CANCELLED`,
  * `ORDER_CURRENCY_CHANGED` (the order is now billed in another currency than
- * the request asked in: send a new one).
+ * the request asked in: send a new one), or `ORDER_CREDITED` (a credit note
+ * lowered what the order still owes below the request's amount, so it was
+ * withdrawn: send a new one, which asks what is owed now). An older engine never
+ * answers the last one.
  */
 export type PaymentRequestCloseReason = (typeof PAYMENT_REQUEST_CLOSE_REASONS)[number];
 /** Every close reason, in the engine's order (`OrderPaymentRequestCloseReason`). */
-export declare const PAYMENT_REQUEST_CLOSE_REASONS: readonly ["PAID", "EXPIRED", "CANCELLED", "ORDER_SETTLED", "ORDER_CANCELLED", "ORDER_CURRENCY_CHANGED"];
+export declare const PAYMENT_REQUEST_CLOSE_REASONS: readonly ["PAID", "EXPIRED", "CANCELLED", "ORDER_SETTLED", "ORDER_CANCELLED", "ORDER_CURRENCY_CHANGED", "ORDER_CREDITED"];
 /**
  * How long a request's link works when `create` names no `expiresAt`: this many days from the
  * moment the engine creates it. The engine's own default, pinned to it by this package's spec.

package/dist/payments/requests.js

@@ -11,6 +11,7 @@ export const PAYMENT_REQUEST_CLOSE_REASONS = [
     'ORDER_SETTLED',
     'ORDER_CANCELLED',
     'ORDER_CURRENCY_CHANGED',
+    'ORDER_CREDITED',
 ];
 /**
  * How long a request's link works when `create` names no `expiresAt`: this many days from the

package/dist/pickups/index.d.ts

@@ -4,11 +4,13 @@ import type { Call } from '../types.js';
  * Store pickup (click & collect, POS C1/33): webshop orders a shopper collects at one of the
  * store's shops. Placing such an order writes its pickup (`preparing`); "ready" starts the hold
  * and emails the customer once; the shop's till hands it over (`collected`); a ready pickup not
- * collected within the location's hold days goes back to stock (`expired`), and the pickup of a
- * cancelled order is `cancelled`. A location's settings are `admin.locations.pickup/setPickup`.
+ * collected within the location's hold days goes back to stock (`expired`), an expired one the
+ * shop's till took off its queue is `archived` (its order is unchanged: cancel or refund it here;
+ * a late customer still collects it), and the pickup of a cancelled order is `cancelled`. A
+ * location's settings are `admin.locations.pickup/setPickup`.
  */
 /** The statuses a pickup has today. More may come: read any other value as itself. */
-export declare const STORE_PICKUP_STATUSES: readonly ["preparing", "ready", "collected", "expired", "cancelled"];
+export declare const STORE_PICKUP_STATUSES: readonly ["preparing", "ready", "collected", "expired", "archived", "cancelled"];
 export type StorePickupStatus = (typeof STORE_PICKUP_STATUSES)[number];
 /**
  * Why the release at expiry moved nothing (D23): `invoice_locked`, the order is invoiced and

package/dist/pickups/index.js

@@ -3,8 +3,10 @@ import { redactionWatcher } from '../customer-data-redaction.js';
  * Store pickup (click & collect, POS C1/33): webshop orders a shopper collects at one of the
  * store's shops. Placing such an order writes its pickup (`preparing`); "ready" starts the hold
  * and emails the customer once; the shop's till hands it over (`collected`); a ready pickup not
- * collected within the location's hold days goes back to stock (`expired`), and the pickup of a
- * cancelled order is `cancelled`. A location's settings are `admin.locations.pickup/setPickup`.
+ * collected within the location's hold days goes back to stock (`expired`), an expired one the
+ * shop's till took off its queue is `archived` (its order is unchanged: cancel or refund it here;
+ * a late customer still collects it), and the pickup of a cancelled order is `cancelled`. A
+ * location's settings are `admin.locations.pickup/setPickup`.
  */
 /** The statuses a pickup has today. More may come: read any other value as itself. */
 export const STORE_PICKUP_STATUSES = [
@@ -12,6 +14,7 @@ export const STORE_PICKUP_STATUSES = [
     'ready',
     'collected',
     'expired',
+    'archived',
     'cancelled',
 ];
 /**