@sixtyninecommerce/admin 0.6.0 → 0.7.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,103 @@
+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>;
+}
+/** 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>;
+}
+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 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,55 @@
+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}
+    }
+  }
+`;
+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;
+        },
+    };
+}

package/dist/payments/providers.d.ts

@@ -0,0 +1,281 @@
+import { type Page, type Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/**
+ * Which credential a store is actually paying through.
+ *
+ * `connect` — an account the store onboarded through the platform.
+ * `legacy` — the channel's own per-provider API key, as it has always worked.
+ *   Supported indefinitely: a store moves when it chooses to, and both paths
+ *   can be fully ready.
+ * `none` — neither, so nothing can be charged.
+ */
+export type ProviderCredentialPath = 'connect' | 'legacy' | 'none';
+/** A payment provider's account, as the platform holds it for one seller. */
+export interface ProviderConnection {
+    id: string;
+    /**
+     * The legal entity this account belongs to, resolved from the channel's
+     * seller. Several stores of one seller SHARE a connection — the money lands
+     * in one place and the merchant onboards once.
+     */
+    sellerId: string;
+    /** Provider key — `test`, `mollie`, `stripe`. */
+    provider: string;
+    /** `pending` while onboarding is in flight, then `connected` or `disconnected`. */
+    status: string;
+    /**
+     * The account's PUBLIC id at the provider. Null while pending. Never a
+     * secret: credentials stay with the provider package that obtained them.
+     */
+    externalId: string | null;
+    scopes: string[];
+    /** Payment methods active on the account, as the provider reports them. */
+    activeMethods: string[];
+    /**
+     * `test` or `live`, as the provider reported it when the account was
+     * connected. REPORTED, not enforced: the rule that a sandbox store may hold
+     * only a `test` connection needs a way to identify a sandbox store, which
+     * does not exist yet. The mode is recorded now so that rule has something to
+     * act on the day it lands.
+     */
+    mode: string;
+    connectedAt: string | null;
+    /**
+     * Set when the connection ended. The row STAYS — which account a store was
+     * paid through outlives the connection, and it is the first thing anyone asks
+     * after a dispute.
+     */
+    disconnectedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** A card terminal registered against a connection. Terminals are per Location. */
+export interface ProviderTerminal {
+    id: string;
+    /** The terminal's id at the provider — the identity a re-provision reuses. */
+    externalId: string;
+    label: string;
+    /** The stock location it serves, or null while it is unassigned. */
+    stockLocationId: string | null;
+    status: string;
+    lastSeenAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Where to send the merchant, and the state to hand back on return. */
+export interface ProviderOnboardingStart {
+    url: string;
+    /** Opaque and single-use. Pass it to {@link ProvidersModule.completeOnboarding}. */
+    state: string;
+    mode: string;
+}
+/**
+ * Independently verifiable evidence that this store can be paid through this
+ * provider — never a UI flag. Each signal is a row, the provider's own answer,
+ * a count, or one piece of arithmetic on the order.
+ */
+export interface ProviderReadiness {
+    provider: string;
+    /** Which credential this verdict is about. Both `connect` and `legacy` can be ready. */
+    path: ProviderCredentialPath;
+    /** `test` or `live` when there is a connection; null on the legacy path. */
+    mode: string | null;
+    connected: boolean;
+    /**
+     * The software for this provider is loaded in the deployment you are talking
+     * to.
+     *
+     * False only for a store that IS connected through a provider package the
+     * deployment no longer runs. Nothing about the credential is known then, and
+     * it is not the merchant's to fix — show the blocker, do not offer a
+     * reconnect. A provider the server has never heard of is refused instead.
+     */
+    adapterAvailable: boolean;
+    /**
+     * The provider ANSWERED when the server asked about this account.
+     *
+     * False means the call did not come back — an outage, a timeout — so nothing
+     * else here about the credential was verified and `blockers` holds that one
+     * sentence. Retry; do NOT send the merchant to reconnect on it. Always true
+     * on the `legacy` path and with no credential, where there is no probe.
+     */
+    providerReachable: boolean;
+    /**
+     * On the `connect` path: the provider itself accepts the stored credential
+     * RIGHT NOW. On the `legacy` path it means only that the store holds a key on
+     * an enabled method — the server never reads that key here, so a legacy key
+     * the provider has since revoked still reads `true`.
+     */
+    credentialUsable: boolean;
+    methodActive: boolean;
+    terminalProvisioned: boolean;
+    /**
+     * A registered terminal serves the `locationId` you asked about — and `false`
+     * when you asked about none, since there is no location for it to be true of.
+     * Same for `orderPayable`. Neither produces a blocker or moves `overall`
+     * outside its own question, so do not render either as a problem unless you
+     * asked the question it answers.
+     */
+    terminalUsableForLocation: boolean;
+    /**
+     * The provider can take PART of an order's total. Reported, never gating: it
+     * answers your question (may I take a deposit), not whether the store can be
+     * paid at all.
+     */
+    partialSupported: boolean;
+    orderPayable: boolean;
+    /**
+     * The answer to "can this store be paid through this provider" FOR THE
+     * QUESTION ASKED. Signals outside it do not gate: a web-only store with no
+     * terminal is ready, because you did not ask about a location.
+     */
+    overall: boolean;
+    /**
+     * The server's evidence for anything short of a clean pass, one entry per
+     * failing gate, in the platform's own words. Never a sentence this SDK
+     * composed, and never a blocker for something you did not ask about.
+     */
+    blockers: string[];
+}
+export interface ProvisionTerminalInput {
+    /** What the merchant calls it — "Counter 1". At most 120 characters. */
+    label: string;
+    /** Assign it to this stock location as it is created. Must be in this channel. */
+    stockLocationId?: string | null;
+}
+export interface ReadinessOptions extends Call {
+    /** Ask about a specific order: `orderPayable` then gates the verdict. */
+    orderId?: string;
+    /** Ask about a counter sale: the terminal signals then gate the verdict. */
+    locationId?: string;
+}
+/** Terminals of one provider. */
+export interface ProviderTerminalsModule {
+    /**
+     * The terminals this platform holds. A pure read of stored rows; see
+     * {@link refresh} for reconciling with the provider.
+     *
+     * A `Page` because every list in this SDK is one (spec §9.2), not because
+     * this query pages: it answers the complete array.
+     */
+    list(provider: string, options?: Call): Promise<Page<ProviderTerminal>>;
+    /**
+     * Reconcile with the provider: new readers are recorded, known ones updated,
+     * and one the provider no longer reports is marked `inactive` so it stops
+     * counting towards readiness. Rows are never deleted — a row is the evidence
+     * that a reader existed and where it stood.
+     *
+     * A WRITE (`UpdatePaymentMethod`), because it changes what the platform holds.
+     */
+    refresh(provider: string, options?: Call): Promise<Page<ProviderTerminal>>;
+    /**
+     * Ask the provider for a terminal.
+     *
+     * Provisioning the same reader twice is the SAME reader — the provider's id
+     * is the identity — so this is safe to retry even without a key. Send
+     * `idempotencyKey` to make the whole mutation replay instead.
+     */
+    provision(provider: string, input: ProvisionTerminalInput, options?: Call): Promise<ProviderTerminal>;
+    /** Put a terminal on a location. */
+    assign(terminalId: string, locationId: string, options?: Call): Promise<ProviderTerminal>;
+    /**
+     * Take a terminal off its location. The row stays: the reader still exists.
+     *
+     * This is the ONLY way to unassign through this SDK — `assign` requires a
+     * location id. (The underlying mutation accepts a null `locationId` too; the
+     * SDK keeps the two intents as two methods so neither call has a meaningless
+     * argument.)
+     */
+    unassign(terminalId: string, options?: Call): Promise<ProviderTerminal>;
+}
+/**
+ * Payment-provider onboarding, terminals and readiness (headless spec §8.9).
+ *
+ * ## A connection belongs to the SELLER, not to the store
+ *
+ * A PSP account belongs to the legal entity that gets paid, so several stores of
+ * one seller share one connection: onboard once, and the money lands in one
+ * place. A store whose channel has no seller is refused with `SELLER_REQUIRED`
+ * rather than given a connection keyed on nothing.
+ *
+ * ## Two credential paths, both first-class
+ *
+ * A store on a raw per-channel API key is supported, not broken — there is no
+ * migration, and it moves when it chooses to. {@link readiness} reports which
+ * path it is on and treats both equally in `overall`. The per-channel key
+ * surface is deprecated in the schema and supported in the code; those are
+ * different statements and both are deliberate.
+ *
+ * ## Readiness is evidence, not a flag
+ *
+ * Every signal is something you could verify yourself, and `blockers` are the
+ * server's words. Ask the question you are about to act on: pass `locationId`
+ * for a counter sale and `orderId` for a payment, and signals outside that
+ * question are reported without gating `overall` — a web-only store has no
+ * terminal and is not broken.
+ *
+ * **Coded refusals**, delivered as GraphQL errors with `extensions.code`:
+ * `SELLER_REQUIRED`, `PAYMENT_PROVIDER_NOT_REGISTERED`, `PROVIDER_NOT_CONNECTED`,
+ * `PROVIDER_ALREADY_CONNECTED` (→ `ConflictError`; disconnect first rather than
+ * silently re-pointing a store's money), `ONBOARDING_STATE_INVALID`,
+ * `PROVIDER_CREDENTIAL_REJECTED`, `TERMINAL_NOT_FOUND` (→ `NotFoundError`),
+ * `TERMINAL_REJECTED`, `LIVE_CONNECTION_REFUSED`, and the `INVALID_*` input
+ * refusals (→ `ValidationError`). Assigning a terminal to a location of another
+ * channel answers `LOCATION_NOT_IN_CHANNEL`, the same code the rest of the
+ * platform uses for that one rule.
+ */
+export interface ProvidersModule {
+    /**
+     * Every connection of this store's seller, including disconnected ones: a
+     * seller that WAS connected and is not any more gives a different answer to
+     * one that never connected at all, and support needs to tell them apart.
+     */
+    list(options?: Call): Promise<Page<ProviderConnection>>;
+    /** One provider's connection, or null when this seller has never connected it. */
+    status(provider: string, options?: Call): Promise<ProviderConnection | null>;
+    /**
+     * Begin connecting this seller's account. Send the merchant to the `url`, and
+     * hand the `state` back to {@link completeOnboarding} when they return.
+     *
+     * Refused with `PROVIDER_ALREADY_CONNECTED` while a live connection exists.
+     *
+     * This is the one call here that takes NO `idempotencyKey`, and it needs
+     * none: a repeat replaces the pending attempt rather than creating a second
+     * account, and it answers with a FRESH url and state — which is what a
+     * merchant who lost the first link needs. Storing the answer for a day would
+     * re-serve a link that may be single-use and, once the onboarding is
+     * finished, one that can no longer be completed.
+     */
+    startOnboarding(provider: string, input: {
+        returnUrl: string;
+    }, options?: Call): Promise<ProviderOnboardingStart>;
+    /**
+     * Finish what {@link startOnboarding} began. The `state` is single-use, so a
+     * replayed callback cannot re-complete an onboarding.
+     */
+    completeOnboarding(provider: string, input: {
+        state: string;
+        code: string;
+    }, options?: Call): Promise<ProviderConnection>;
+    /** Activate one payment method on the connected account (`ideal`, `pointofsale`, …). */
+    activateMethod(provider: string, method: string, options?: Call): Promise<ProviderConnection>;
+    /** Can this store be paid through this provider, and if not, what is missing? */
+    readiness(provider: string, options?: ReadinessOptions): Promise<ProviderReadiness>;
+    /**
+     * End the connection at the provider. False when there was nothing to
+     * disconnect. The row stays, marked disconnected.
+     */
+    disconnect(provider: string, options?: Call): Promise<boolean>;
+    terminals: ProviderTerminalsModule;
+}
+export declare const PROVIDER_CONNECTIONS_QUERY = "\n  query ProviderConnections {\n    providerConnections { \n  id\n  sellerId\n  provider\n  status\n  externalId\n  scopes\n  activeMethods\n  mode\n  connectedAt\n  disconnectedAt\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const PROVIDER_READINESS_QUERY = "\n  query PaymentProviderReadiness($provider: String!, $orderId: ID, $locationId: ID) {\n    paymentProviderReadiness(provider: $provider, orderId: $orderId, locationId: $locationId) {\n      \n  provider\n  path\n  mode\n  connected\n  adapterAvailable\n  providerReachable\n  credentialUsable\n  methodActive\n  terminalProvisioned\n  terminalUsableForLocation\n  partialSupported\n  orderPayable\n  overall\n  blockers\n\n    }\n  }\n";
+export declare const PROVIDER_TERMINALS_QUERY = "\n  query ProviderTerminals($provider: String!) {\n    providerTerminals(provider: $provider) { \n  id\n  externalId\n  label\n  stockLocationId\n  status\n  lastSeenAt\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const START_ONBOARDING_MUTATION = "\n  mutation StartPaymentProviderOnboarding($provider: String!, $returnUrl: String!) {\n    startPaymentProviderOnboarding(provider: $provider, returnUrl: $returnUrl) {\n      url\n      state\n      mode\n    }\n  }\n";
+export declare const COMPLETE_ONBOARDING_MUTATION = "\n  mutation CompletePaymentProviderOnboarding($provider: String!, $state: String!, $code: String!, $idempotencyKey: String) {\n    completePaymentProviderOnboarding(provider: $provider, state: $state, code: $code, idempotencyKey: $idempotencyKey) {\n      \n  id\n  sellerId\n  provider\n  status\n  externalId\n  scopes\n  activeMethods\n  mode\n  connectedAt\n  disconnectedAt\n  createdAt\n  updatedAt\n\n    }\n  }\n";
+export declare const ACTIVATE_METHOD_MUTATION = "\n  mutation ActivatePaymentProviderMethod($provider: String!, $method: String!) {\n    activatePaymentProviderMethod(provider: $provider, method: $method) { \n  id\n  sellerId\n  provider\n  status\n  externalId\n  scopes\n  activeMethods\n  mode\n  connectedAt\n  disconnectedAt\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const REFRESH_TERMINALS_MUTATION = "\n  mutation RefreshProviderTerminals($provider: String!) {\n    refreshProviderTerminals(provider: $provider) { \n  id\n  externalId\n  label\n  stockLocationId\n  status\n  lastSeenAt\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const PROVISION_TERMINAL_MUTATION = "\n  mutation ProvisionProviderTerminal($provider: String!, $input: ProvisionTerminalInput!, $idempotencyKey: String) {\n    provisionProviderTerminal(provider: $provider, input: $input, idempotencyKey: $idempotencyKey) {\n      \n  id\n  externalId\n  label\n  stockLocationId\n  status\n  lastSeenAt\n  createdAt\n  updatedAt\n\n    }\n  }\n";
+export declare const ASSIGN_TERMINAL_MUTATION = "\n  mutation AssignProviderTerminal($terminalId: ID!, $locationId: ID) {\n    assignProviderTerminal(terminalId: $terminalId, locationId: $locationId) { \n  id\n  externalId\n  label\n  stockLocationId\n  status\n  lastSeenAt\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const DISCONNECT_PROVIDER_MUTATION = "\n  mutation DisconnectPaymentProvider($provider: String!) {\n    disconnectPaymentProvider(provider: $provider)\n  }\n";
+export declare function createProvidersModule(transport: Transport): ProvidersModule;