@sixtyninecommerce/admin 0.6.0 → 0.8.0

package/dist/orders/surcharges.d.ts

@@ -0,0 +1,121 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/**
+ * A surcharge: an adjustment on a PLACED order that is not a line — a delivery
+ * charge, a negotiated discount, a handling fee.
+ *
+ * Money is integer MINOR UNITS of the order's currency, and `price` is NEGATIVE
+ * for a discount. `priceIncludesTax` says which basis the amount is stated in;
+ * there is no default, because guessing it is a 21% error.
+ */
+export interface SurchargeInput {
+    description: string;
+    sku?: string | null;
+    /** Minor units. Negative for a discount agreed after the order was placed. */
+    price: number;
+    /** Whether `price` is gross. Required: the engine will not guess a basis. */
+    priceIncludesTax: boolean;
+    /**
+     * Percentage (21 for 21%). Omit it for no tax line at all — and never send it
+     * together with `taxClass`, which is refused rather than silently resolved
+     * one way.
+     */
+    taxRate?: number | null;
+    /**
+     * Label for the tax line. Refused together with `taxClass`: a class-priced
+     * line is named by the store's own tax setup — including names that are a
+     * policy statement, like `EU Reverse Charge (0%)` — and relabelling one would
+     * put on an invoice something the line is not.
+     */
+    taxDescription?: string | null;
+}
+/** Options for a surcharge write. */
+export interface SurchargeCall extends Call {
+    /**
+     * Price the surcharge from one of the store's tax classes (spec §8.6)
+     * instead of from an explicit `taxRate`.
+     *
+     * Resolved PER ORDER, which is the half of the platform's tax-class decision
+     * that is not write-time: a surcharge is money the platform composes, with no
+     * product variant behind it to have been priced already.
+     *
+     * **Which country, and which zone — they are two different questions.** The
+     * order's shipping COUNTRY picks the class's mapping (that is the store's own
+     * "what kind of thing is this" decision, one row per country). The order's
+     * tax ZONE picks the rate for the category that mapping names. The two can
+     * legitimately differ: a store only moves a country into its own zone by
+     * listing it in the tax-exclusive countries setting, so a Belgian order on a
+     * store that has not listed BE is still priced in the store's default zone
+     * while the BE mapping decides the category. Map a country and configure that
+     * zone's rates, or the write is refused rather than silently untaxed.
+     *
+     * **The order's own tax policy still wins.** A tax-removed order and an EU
+     * reverse charge override whatever the class resolved to, because the
+     * resolved rate is run through the same tax-line strategy the order's lines
+     * go through. The class chooses which rate is looked up, never what the line
+     * finally says. A per-line rate imported from an ERP is the one policy that
+     * does NOT carry over: it belongs to a line the ERP sent, never to a charge
+     * the merchant adds afterwards.
+     *
+     * Refusals: `TAX_CLASS_NOT_FOUND` (→ `NotFoundError`) for a key this store
+     * does not have; `TAX_CLASS_UNMAPPED` (→ `ValidationError`) when the class
+     * says nothing about the order's country and has no `*` fallback; and
+     * `TAX_CLASS_RATE_MISSING` (→ `ValidationError`) when it is mapped but that
+     * category has no rate in the order's zone. Sending it together with
+     * `input.taxRate` or `input.taxDescription` is refused as bad input.
+     */
+    taxClass?: string;
+}
+/**
+ * The order the mutation answers with, as much of it as this surface projects.
+ *
+ * The totals are re-derived and PERSISTED by every one of these calls, so the
+ * numbers here are the order's new state rather than a projection of the
+ * request.
+ */
+export interface SurchargedOrder {
+    id: string;
+    code: string;
+    currencyCode: string;
+    /** Minor units. */
+    total: number;
+    totalWithTax: number;
+    surcharges: Array<{
+        id: string;
+        description: string;
+        sku: string | null;
+        price: number;
+        priceWithTax: number;
+        taxRate: number;
+    }>;
+}
+/**
+ * Surcharges on a placed order.
+ *
+ * These exist beside Vendure's `modifyOrder`, which hard-requires a refund
+ * input for ANY downward price delta — so it cannot express "remove this
+ * discount" at all on an order with no payment to refund against. Needs
+ * `UpdateOrder`; refused once the order's invoice has been approved.
+ */
+export interface SurchargesModule {
+    /** Add a surcharge and re-total the order. */
+    add(orderId: string, input: SurchargeInput, options?: SurchargeCall): Promise<SurchargedOrder>;
+    /**
+     * Replace a surcharge in place and re-total the order. The surcharge keeps
+     * its id, so a delivery charge stays linked to the fulfillment that created
+     * it, and an omitted `sku` is left alone rather than cleared.
+     *
+     * TAX IS NOT LIKE `sku`: this is a whole replacement, so omitting BOTH
+     * `options.taxClass` and `input.taxRate` writes a surcharge with no tax line
+     * at all and lowers the order total. Re-send whichever of the two the
+     * surcharge should carry — a `taxClass` is then resolved afresh, so the rate
+     * that applies now is the one written.
+     */
+    update(orderId: string, surchargeId: string, input: SurchargeInput, options?: SurchargeCall): Promise<SurchargedOrder>;
+    /** Remove a surcharge entirely and re-total the order. */
+    remove(orderId: string, surchargeId: string, options?: Call): Promise<SurchargedOrder>;
+}
+export declare const ADD_ORDER_SURCHARGE_MUTATION = "\n  mutation AddOrderSurcharge(\n    $orderId: ID!\n    $input: SurchargeInput!\n    $taxClass: String\n    $idempotencyKey: String\n  ) {\n    addOrderSurcharge(\n      orderId: $orderId\n      input: $input\n      taxClass: $taxClass\n      idempotencyKey: $idempotencyKey\n    ) {\n      \n  id\n  code\n  currencyCode\n  total\n  totalWithTax\n  surcharges {\n    id\n    description\n    sku\n    price\n    priceWithTax\n    taxRate\n  }\n\n    }\n  }\n";
+export declare const UPDATE_ORDER_SURCHARGE_MUTATION = "\n  mutation UpdateOrderSurcharge(\n    $orderId: ID!\n    $surchargeId: ID!\n    $input: SurchargeInput!\n    $taxClass: String\n    $idempotencyKey: String\n  ) {\n    updateOrderSurcharge(\n      orderId: $orderId\n      surchargeId: $surchargeId\n      input: $input\n      taxClass: $taxClass\n      idempotencyKey: $idempotencyKey\n    ) {\n      \n  id\n  code\n  currencyCode\n  total\n  totalWithTax\n  surcharges {\n    id\n    description\n    sku\n    price\n    priceWithTax\n    taxRate\n  }\n\n    }\n  }\n";
+export declare const REMOVE_ORDER_SURCHARGE_MUTATION = "\n  mutation RemoveOrderSurcharge($orderId: ID!, $surchargeId: ID!, $idempotencyKey: String) {\n    removeOrderSurcharge(\n      orderId: $orderId\n      surchargeId: $surchargeId\n      idempotencyKey: $idempotencyKey\n    ) {\n      \n  id\n  code\n  currencyCode\n  total\n  totalWithTax\n  surcharges {\n    id\n    description\n    sku\n    price\n    priceWithTax\n    taxRate\n  }\n\n    }\n  }\n";
+export declare function createSurchargesModule(transport: Transport): SurchargesModule;

package/dist/orders/surcharges.js

@@ -0,0 +1,110 @@
+const SURCHARGED_ORDER_FIELDS = /* GraphQL */ `
+  id
+  code
+  currencyCode
+  total
+  totalWithTax
+  surcharges {
+    id
+    description
+    sku
+    price
+    priceWithTax
+    taxRate
+  }
+`;
+export const ADD_ORDER_SURCHARGE_MUTATION = /* GraphQL */ `
+  mutation AddOrderSurcharge(
+    $orderId: ID!
+    $input: SurchargeInput!
+    $taxClass: String
+    $idempotencyKey: String
+  ) {
+    addOrderSurcharge(
+      orderId: $orderId
+      input: $input
+      taxClass: $taxClass
+      idempotencyKey: $idempotencyKey
+    ) {
+      ${SURCHARGED_ORDER_FIELDS}
+    }
+  }
+`;
+export const UPDATE_ORDER_SURCHARGE_MUTATION = /* GraphQL */ `
+  mutation UpdateOrderSurcharge(
+    $orderId: ID!
+    $surchargeId: ID!
+    $input: SurchargeInput!
+    $taxClass: String
+    $idempotencyKey: String
+  ) {
+    updateOrderSurcharge(
+      orderId: $orderId
+      surchargeId: $surchargeId
+      input: $input
+      taxClass: $taxClass
+      idempotencyKey: $idempotencyKey
+    ) {
+      ${SURCHARGED_ORDER_FIELDS}
+    }
+  }
+`;
+export const REMOVE_ORDER_SURCHARGE_MUTATION = /* GraphQL */ `
+  mutation RemoveOrderSurcharge($orderId: ID!, $surchargeId: ID!, $idempotencyKey: String) {
+    removeOrderSurcharge(
+      orderId: $orderId
+      surchargeId: $surchargeId
+      idempotencyKey: $idempotencyKey
+    ) {
+      ${SURCHARGED_ORDER_FIELDS}
+    }
+  }
+`;
+/**
+ * `undefined` rather than `null` for an absent tax class: a variable explicitly
+ * set to null is still a value the engine reads, and this argument's whole
+ * contract is "omit it and the legacy `taxRate` path is untouched".
+ */
+function taxClassVariable(options) {
+    const value = options?.taxClass;
+    return typeof value === 'string' && value.trim() !== '' ? value : undefined;
+}
+export function createSurchargesModule(transport) {
+    return {
+        async add(orderId, input, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: ADD_ORDER_SURCHARGE_MUTATION,
+                variables: {
+                    orderId,
+                    input,
+                    taxClass: taxClassVariable(options),
+                    idempotencyKey: options?.idempotencyKey,
+                },
+            }, options);
+            return data.addOrderSurcharge;
+        },
+        async update(orderId, surchargeId, input, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: UPDATE_ORDER_SURCHARGE_MUTATION,
+                variables: {
+                    orderId,
+                    surchargeId,
+                    input,
+                    taxClass: taxClassVariable(options),
+                    idempotencyKey: options?.idempotencyKey,
+                },
+            }, options);
+            return data.updateOrderSurcharge;
+        },
+        async remove(orderId, surchargeId, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: REMOVE_ORDER_SURCHARGE_MUTATION,
+                variables: { orderId, surchargeId, idempotencyKey: options?.idempotencyKey },
+            }, options);
+            return data.removeOrderSurcharge;
+        },
+    };
+}

package/dist/payments/index.d.ts

@@ -0,0 +1,244 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+import { type ProvidersModule } from './providers.js';
+/**
+ * What an order has actually been paid, in minor units of its own currency.
+ *
+ * Derived from the order's payments on every read, never stored — a stored copy
+ * is a second source of truth that drifts the first time a refund lands.
+ */
+export interface OrderPaymentPosition {
+    /** The order's own gross total, carrying the order's rounding rule. */
+    total: number;
+    /** Settled plus authorized, less refunds: what is accounted for. */
+    covered: number;
+    /** Money actually taken, less refunds. This is what `orders.settle` requires. */
+    settled: number;
+    /** Money a payment handler may take and has not. */
+    authorized: number;
+    refunded: number;
+    /** `total - covered`, floored at zero. */
+    outstanding: number;
+    /**
+     * `covered - total`, floored at zero. Over-payment is refused at the door, so
+     * this is non-zero only for imported history, rows predating the guard, or a
+     * refund that landed after a second payment.
+     */
+    overpaid: number;
+    /** What a further payment may take. */
+    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,
+     * and the refusal carries the position so a till can correct itself without a
+     * second round trip.
+     */
+    amount: number;
+    /** A payment method code configured on this channel. */
+    method: string;
+    /**
+     * Free-form detail stored on the payment, MINUS two keys the platform writes
+     * itself: `attribution` (the vouched-for staff, device and register refs) and
+     * `isDeposit`. Sending either is refused with `METADATA_KEY_RESERVED` rather
+     * than merged, so no caller can invent a till or a member of staff that every
+     * later report would believe.
+     *
+     * Anything you put under `public` is visible to the storefront — Vendure's
+     * Shop API exposes `metadata.public`. The platform never writes there.
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * One payment's contribution to an order's refund position.
+ */
+export interface RefundablePayment {
+    paymentId: string;
+    /** Vendure's payment state. */
+    state: string;
+    /** The payment method code, or null when the payment carries no label. */
+    method: string | null;
+    /** Gross amount taken, minor units. */
+    amount: number;
+    /** Non-failed refunds already recorded against it. A failed refund never left. */
+    refunded: number;
+    /** `amount - refunded` when this payment took money, floored at zero; else zero. */
+    refundable: number;
+    /**
+     * Whether this payment took money at all.
+     *
+     * True for a settled payment and for an authorized one on a real gateway — a
+     * card sale at a terminal rests authorized until the webhook settles it, and
+     * that hold is real money. False for an authorized payment on an offline or
+     * net-terms method, where authorized means the money has NOT arrived.
+     */
+    tookMoney: boolean;
+}
+/**
+ * What an order may still hand back, in minor units of its own currency.
+ *
+ * A different question from {@link OrderPaymentPosition}, and the two disagree
+ * on purpose: that one nets refunds against every authorization because it
+ * answers "what is this order covered for", while this one counts only money
+ * that was actually TAKEN, because that is all a refund can return.
+ */
+export interface OrderRefundPosition {
+    /** The order's currency. Every amount here is in its minor units. */
+    currencyCode: string;
+    /** Money already given back out of money that was taken. */
+    refunded: number;
+    /**
+     * What may still be handed back for this order: the sum of every payment's
+     * own remaining headroom, each floored at zero.
+     *
+     * There is deliberately no credit-note deduction. A credit note that moved
+     * money already has its refund on the payment; one that moved none has
+     * nothing to deduct.
+     */
+    refundable: number;
+    /** Every payment on the order, NEWEST FIRST, with its own headroom. */
+    perPayment: RefundablePayment[];
+}
+/** Money handed back to a customer. */
+export interface RefundPaymentInput {
+    orderId: string;
+    /** Minor units of the order's currency. Greater than zero. */
+    amount: number;
+    /**
+     * The payment to return the money to.
+     *
+     * Omit it and the platform allocates across the order's paying payments
+     * NEWEST FIRST: it picks the most recent one whose remaining headroom can
+     * carry the WHOLE amount. A part-paid order settles its remainder last, so
+     * that is the money a merchant means by "give some of it back".
+     *
+     * **One call refunds against ONE payment.** When the order can return the
+     * amount but no single payment can, the call is refused with
+     * `REFUND_EXCEEDS_PAYMENT` and `perPayment` shows exactly how to split it —
+     * rather than the platform spilling silently onto a payment you did not name,
+     * which is what the engine would do.
+     */
+    paymentId?: string;
+    /** Free text stored on the refund. Shown to nobody automatically. */
+    reason?: string;
+}
+/** A refund, as this surface projects it. */
+export interface IssuedRefund {
+    id: string;
+    /** Minor units. */
+    total: number;
+    /** `Pending`, `Settled` or `Failed`. */
+    state: string;
+    /** The payment method the refund was booked against. */
+    method: string | null;
+    /** The gateway's own receipt, when it gave one. */
+    transactionId: string | null;
+    reason: string | null;
+}
+/** The order, as much of it as this surface projects. */
+export interface PaidOrder {
+    id: string;
+    code: string;
+    state: string;
+    currencyCode: string;
+    total: number;
+    totalWithTax: number;
+}
+/**
+ * Payments: money against an order (spec §8.2), and the provider accounts
+ * it runs through (spec §8.9).
+ *
+ * `providers` is payment-provider onboarding, terminals and readiness. The
+ * rest of this namespace is the money itself.
+ *
+ * `record` writes money the merchant HAS, which lands the payment `Settled`.
+ * There is no payment state to choose: an AUTHORIZATION is a payment method
+ * handler's business — the gateway decides whether a card may be charged later
+ * — so one cannot be created here. Authorized payments that handlers DO create
+ * are counted by `position()` all the same, under `authorized`; only the write
+ * side is narrowed.
+ *
+ * Needs `UpdateOrder` to record, `ReadOrder` to read the position.
+ */
+export interface PaymentsModule {
+    /** Provider onboarding, terminals and readiness (spec §8.9). */
+    providers: ProvidersModule;
+    /**
+     * Record part (or all) of what an order owes, and return the order.
+     *
+     * `options.idempotencyKey` is honoured: the Admin API takes it as a mutation
+     * 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`,
+     * `PAYMENT_METHOD_NOT_FOUND`, `ORDER_NOT_FOUND`.
+     */
+    record(orderId: string, input: RecordPaymentInput, options?: Call): Promise<PaidOrder>;
+    /** Read an order's payment position. */
+    position(orderId: string, options?: Call): Promise<OrderPaymentPosition>;
+    /**
+     * Hand money back to a customer, never more than the order took.
+     *
+     * The platform's own refund ceiling, and the one the four surfaces that issue
+     * refunds — returns settlement, credit notes, the till and the order importer
+     * — are measured against. Refuses `REFUND_EXCEEDS_SETTLED` when the amount is
+     * more than the whole ORDER can return, which is the check no per-payment
+     * arithmetic can make: another surface may have refunded the rest of it ten
+     * seconds ago.
+     *
+     * `options.idempotencyKey` is honoured — the Admin API takes it as a mutation
+     * argument — so a retry under the same key returns the FIRST call's refund
+     * instead of raising a second one. Use a fresh key per intended refund.
+     *
+     * **`IDEMPOTENCY_OUTCOME_UNKNOWN` is neither success nor refusal.** The engine
+     * calls the payment gateway from inside the transaction that writes the refund
+     * row, so a failure after that call leaves an outcome nobody can read off the
+     * database: the money may be on its way back with no row to show for it. You
+     * get this code on the FIRST call when that happens, and on every repeat under
+     * the same key — the key is spent rather than released, so the refund never
+     * runs again. Do NOT treat it as `REFUND_REFUSED`: read
+     * `payments.refundPosition(orderId)`, reconcile against the gateway, and only
+     * then decide. If the money did not move, issue a new request under a NEW key.
+     *
+     * (The server also attaches the position to that error, but `PlatformError`
+     * carries only `code`, `message`, `details` and `traceId`, so an SDK caller
+     * reads it with `refundPosition(orderId)` rather than off the error.)
+     *
+     * Only money that was TAKEN can come back: a settled payment, or an
+     * authorized one on a real gateway. An offline or net-terms authorization
+     * took nothing and is refused with `REFUND_PAYMENT_HOLDS_NO_MONEY`.
+     *
+     * **The refund you get back is one that moved money.** On an OFFLINE method —
+     * bank transfer, invoice, cash, an imported order's historical tender — it
+     * comes back `Settled`, because there the money moves by hand and recording
+     * it is the settlement. On a live gateway it comes back `Pending` and settles
+     * when the gateway calls back. A method whose handler cannot be resolved at
+     * all, because it is disabled or no longer on this store, is refused
+     * `REFUND_METHOD_UNAVAILABLE` before anything is created, with the payment and
+     * the method in `extensions.details`.
+     *
+     * Other refusals: `REFUND_EXCEEDS_PAYMENT` (the order can return this much,
+     * but no single payment can — split it, using `perPayment`),
+     * `REFUND_PAYMENT_NOT_FOUND`, `REFUND_AMOUNT_NOT_POSITIVE`,
+     * `REFUND_ORDER_NOT_FOUND`, and `REFUND_REFUSED` when the money was there and
+     * the engine or the gateway said no anyway. Every refusal raised once the
+     * order has been read carries that order's position in
+     * `extensions.refundPosition`, so a till can correct itself without a second
+     * round trip.
+     */
+    refund(input: RefundPaymentInput, options?: Call): Promise<IssuedRefund>;
+    /** Read what an order may still hand back. */
+    refundPosition(orderId: string, options?: Call): Promise<OrderRefundPosition>;
+}
+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  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 function createPaymentsModule(transport: Transport): PaymentsModule;
+export type { ProviderConnection, ProviderCredentialPath, ProviderOnboardingStart, ProviderReadiness, ProvidersModule, ProviderTerminal, ProviderTerminalsModule, ProvisionTerminalInput, ReadinessOptions, } from './providers.js';

package/dist/payments/index.js

@@ -0,0 +1,103 @@
+import { createProvidersModule } from './providers.js';
+const PAID_ORDER_FIELDS = /* GraphQL */ `
+  id
+  code
+  state
+  currencyCode
+  total
+  totalWithTax
+`;
+const POSITION_FIELDS = /* GraphQL */ `
+  total
+  covered
+  settled
+  authorized
+  refunded
+  outstanding
+  overpaid
+  availableToCharge
+`;
+export const RECORD_ORDER_PAYMENT_MUTATION = /* GraphQL */ `
+  mutation RecordOrderPayment($orderId: ID!, $input: RecordPaymentInput!, $idempotencyKey: String) {
+    recordOrderPayment(orderId: $orderId, input: $input, idempotencyKey: $idempotencyKey) {
+      ${PAID_ORDER_FIELDS}
+    }
+  }
+`;
+export const ORDER_PAYMENT_POSITION_QUERY = /* GraphQL */ `
+  query OrderPaymentPosition($orderId: ID!) {
+    orderPaymentPosition(orderId: $orderId) {
+      ${POSITION_FIELDS}
+    }
+  }
+`;
+const REFUND_POSITION_FIELDS = /* GraphQL */ `
+  currencyCode
+  refunded
+  refundable
+  perPayment {
+    paymentId
+    state
+    method
+    amount
+    refunded
+    refundable
+    tookMoney
+  }
+`;
+export const ORDER_REFUND_POSITION_QUERY = /* GraphQL */ `
+  query OrderRefundPosition($orderId: ID!) {
+    orderRefundPosition(orderId: $orderId) {
+      ${REFUND_POSITION_FIELDS}
+    }
+  }
+`;
+export const REFUND_ORDER_PAYMENT_MUTATION = /* GraphQL */ `
+  mutation RefundOrderPayment($input: RefundPaymentInput!, $idempotencyKey: String) {
+    refundOrderPayment(input: $input, idempotencyKey: $idempotencyKey) {
+      id
+      total
+      state
+      method
+      transactionId
+      reason
+    }
+  }
+`;
+export function createPaymentsModule(transport) {
+    return {
+        providers: createProvidersModule(transport),
+        async record(orderId, input, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: RECORD_ORDER_PAYMENT_MUTATION,
+                // Forwarded as a VARIABLE, not a header: the Admin API has no header
+                // for it, which is why the mutation takes the key as an argument.
+                // `undefined`, never an explicit null — `JSON.stringify` drops it, so
+                // an omitted key stays off the wire entirely rather than arriving as a
+                // value a future server could read as one.
+                variables: { orderId, input, idempotencyKey: options?.idempotencyKey },
+            }, options);
+            return data.recordOrderPayment;
+        },
+        async position(orderId, options) {
+            const data = await transport.graphql({ api: 'admin', query: ORDER_PAYMENT_POSITION_QUERY, variables: { orderId } }, options);
+            return data.orderPaymentPosition;
+        },
+        async refund(input, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: REFUND_ORDER_PAYMENT_MUTATION,
+                // Forwarded as a VARIABLE, not a header: the Admin API has no header
+                // for it. `undefined`, never an explicit null — `JSON.stringify` drops
+                // it, so an omitted key stays off the wire entirely.
+                variables: { input, idempotencyKey: options?.idempotencyKey },
+            }, options);
+            return data.refundOrderPayment;
+        },
+        async refundPosition(orderId, options) {
+            const data = await transport.graphql({ api: 'admin', query: ORDER_REFUND_POSITION_QUERY, variables: { orderId } }, options);
+            return data.orderRefundPosition;
+        },
+    };
+}