@sixtyninecommerce/admin 0.6.0 → 0.8.0

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;

package/dist/payments/providers.js

@@ -0,0 +1,205 @@
+import { createPage } from '@sixtyninecommerce/core';
+const CONNECTION_FIELDS = /* GraphQL */ `
+  id
+  sellerId
+  provider
+  status
+  externalId
+  scopes
+  activeMethods
+  mode
+  connectedAt
+  disconnectedAt
+  createdAt
+  updatedAt
+`;
+const TERMINAL_FIELDS = /* GraphQL */ `
+  id
+  externalId
+  label
+  stockLocationId
+  status
+  lastSeenAt
+  createdAt
+  updatedAt
+`;
+const READINESS_FIELDS = /* GraphQL */ `
+  provider
+  path
+  mode
+  connected
+  adapterAvailable
+  providerReachable
+  credentialUsable
+  methodActive
+  terminalProvisioned
+  terminalUsableForLocation
+  partialSupported
+  orderPayable
+  overall
+  blockers
+`;
+export const PROVIDER_CONNECTIONS_QUERY = /* GraphQL */ `
+  query ProviderConnections {
+    providerConnections { ${CONNECTION_FIELDS} }
+  }
+`;
+export const PROVIDER_READINESS_QUERY = /* GraphQL */ `
+  query PaymentProviderReadiness($provider: String!, $orderId: ID, $locationId: ID) {
+    paymentProviderReadiness(provider: $provider, orderId: $orderId, locationId: $locationId) {
+      ${READINESS_FIELDS}
+    }
+  }
+`;
+export const PROVIDER_TERMINALS_QUERY = /* GraphQL */ `
+  query ProviderTerminals($provider: String!) {
+    providerTerminals(provider: $provider) { ${TERMINAL_FIELDS} }
+  }
+`;
+export const START_ONBOARDING_MUTATION = /* GraphQL */ `
+  mutation StartPaymentProviderOnboarding($provider: String!, $returnUrl: String!) {
+    startPaymentProviderOnboarding(provider: $provider, returnUrl: $returnUrl) {
+      url
+      state
+      mode
+    }
+  }
+`;
+export const COMPLETE_ONBOARDING_MUTATION = /* GraphQL */ `
+  mutation CompletePaymentProviderOnboarding($provider: String!, $state: String!, $code: String!, $idempotencyKey: String) {
+    completePaymentProviderOnboarding(provider: $provider, state: $state, code: $code, idempotencyKey: $idempotencyKey) {
+      ${CONNECTION_FIELDS}
+    }
+  }
+`;
+export const ACTIVATE_METHOD_MUTATION = /* GraphQL */ `
+  mutation ActivatePaymentProviderMethod($provider: String!, $method: String!) {
+    activatePaymentProviderMethod(provider: $provider, method: $method) { ${CONNECTION_FIELDS} }
+  }
+`;
+export const REFRESH_TERMINALS_MUTATION = /* GraphQL */ `
+  mutation RefreshProviderTerminals($provider: String!) {
+    refreshProviderTerminals(provider: $provider) { ${TERMINAL_FIELDS} }
+  }
+`;
+export const PROVISION_TERMINAL_MUTATION = /* GraphQL */ `
+  mutation ProvisionProviderTerminal($provider: String!, $input: ProvisionTerminalInput!, $idempotencyKey: String) {
+    provisionProviderTerminal(provider: $provider, input: $input, idempotencyKey: $idempotencyKey) {
+      ${TERMINAL_FIELDS}
+    }
+  }
+`;
+export const ASSIGN_TERMINAL_MUTATION = /* GraphQL */ `
+  mutation AssignProviderTerminal($terminalId: ID!, $locationId: ID) {
+    assignProviderTerminal(terminalId: $terminalId, locationId: $locationId) { ${TERMINAL_FIELDS} }
+  }
+`;
+export const DISCONNECT_PROVIDER_MUTATION = /* GraphQL */ `
+  mutation DisconnectPaymentProvider($provider: String!) {
+    disconnectPaymentProvider(provider: $provider)
+  }
+`;
+/** A complete array behind the SDK's page shape (spec §9.2). */
+function wholeList(items, what) {
+    return createPage(items, { nextCursor: null, hasNext: false, total: items.length }, () => {
+        throw new Error(`${what} returns a complete list; there is no next page`);
+    });
+}
+export function createProvidersModule(transport) {
+    // Hoisted rather than reached through `this`: `const { status } =
+    // admin.payments.providers` is a thing consumers do, and a method that needs
+    // its receiver would throw for them. No other module in this SDK uses `this`.
+    const listConnections = async (options) => {
+        const data = await transport.graphql({ api: 'admin', query: PROVIDER_CONNECTIONS_QUERY }, options);
+        return wholeList(data.providerConnections, 'providerConnections');
+    };
+    return {
+        list: listConnections,
+        async status(provider, options) {
+            // Filtered client-side from the complete list rather than added as a
+            // second query: the list is small (one row per provider per seller), and
+            // one server surface is one thing to keep correct.
+            const page = await listConnections(options);
+            return page.items.find((row) => row.provider === provider) ?? null;
+        },
+        async startOnboarding(provider, input, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: START_ONBOARDING_MUTATION,
+                variables: { provider, returnUrl: input.returnUrl },
+            }, options);
+            return data.startPaymentProviderOnboarding;
+        },
+        async completeOnboarding(provider, input, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: COMPLETE_ONBOARDING_MUTATION,
+                variables: {
+                    provider,
+                    state: input.state,
+                    code: input.code,
+                    idempotencyKey: options?.idempotencyKey ?? null,
+                },
+            }, options);
+            return data.completePaymentProviderOnboarding;
+        },
+        async activateMethod(provider, method, options) {
+            const data = await transport.graphql({ api: 'admin', query: ACTIVATE_METHOD_MUTATION, variables: { provider, method } }, options);
+            return data.activatePaymentProviderMethod;
+        },
+        async readiness(provider, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: PROVIDER_READINESS_QUERY,
+                variables: {
+                    provider,
+                    orderId: options?.orderId ?? null,
+                    locationId: options?.locationId ?? null,
+                },
+            }, options);
+            return data.paymentProviderReadiness;
+        },
+        async disconnect(provider, options) {
+            const data = await transport.graphql({ api: 'admin', query: DISCONNECT_PROVIDER_MUTATION, variables: { provider } }, options);
+            return data.disconnectPaymentProvider;
+        },
+        terminals: {
+            async list(provider, options) {
+                const data = await transport.graphql({ api: 'admin', query: PROVIDER_TERMINALS_QUERY, variables: { provider } }, options);
+                return wholeList(data.providerTerminals, 'providerTerminals');
+            },
+            async refresh(provider, options) {
+                const data = await transport.graphql({ api: 'admin', query: REFRESH_TERMINALS_MUTATION, variables: { provider } }, options);
+                return wholeList(data.refreshProviderTerminals, 'refreshProviderTerminals');
+            },
+            async provision(provider, input, options) {
+                const data = await transport.graphql({
+                    api: 'admin',
+                    query: PROVISION_TERMINAL_MUTATION,
+                    variables: {
+                        provider,
+                        input: { label: input.label, stockLocationId: input.stockLocationId ?? null },
+                        idempotencyKey: options?.idempotencyKey ?? null,
+                    },
+                }, options);
+                return data.provisionProviderTerminal;
+            },
+            async assign(terminalId, locationId, options) {
+                const data = await transport.graphql({ api: 'admin', query: ASSIGN_TERMINAL_MUTATION, variables: { terminalId, locationId } }, options);
+                return data.assignProviderTerminal;
+            },
+            async unassign(terminalId, options) {
+                const data = await transport.graphql({
+                    api: 'admin',
+                    query: ASSIGN_TERMINAL_MUTATION,
+                    // Explicit null rather than an omitted variable. The server reads
+                    // BOTH as "take it off the counter" — there is no "leave it"
+                    // spelling — so this is about the request being self-describing in
+                    // a proxy log, not about changing what the server does.
+                    variables: { terminalId, locationId: null },
+                }, options);
+                return data.assignProviderTerminal;
+            },
+        },
+    };
+}

package/dist/platform/provision-store.d.ts

@@ -1,6 +1,15 @@
 import { type Transport } from '@sixtyninecommerce/core';
 import type { AdminClientConfig } from '../client.js';
+import { type JobHandle } from '../jobs/index.js';
 import type { Call } from '../types.js';
+/**
+ * `JobHandle` and `WaitOptions` LIVE in `../jobs` now — every long-running
+ * operation returns one, not just this resource (spec §6.11). They are
+ * re-exported here so that every consumer written against
+ * `platform/provision-store` keeps compiling: the type is the same type, not a
+ * copy.
+ */
+export type { JobHandle, WaitOptions } from '../jobs/index.js';
 /**
  * Which objects a new store is provisioned with.
  *
@@ -108,32 +117,6 @@ export interface ProvisionRun {
     completedAt: string | null;
     [extra: string]: unknown;
 }
-export interface WaitOptions {
-    /** How often to poll. Default 2000 ms; anything below 250 ms is raised to it. */
-    intervalMs?: number;
-    /** Give up after this long. Default 300000 ms (5 minutes). */
-    timeoutMs?: number;
-    signal?: AbortSignal;
-}
-/**
- * A long-running operation in flight (spec §6.11). `runId` is the receipt: it
- * outlives this process, so a caller that cannot wait can hand it on and poll
- * `provisionRun(runId)` later.
- */
-export interface JobHandle<T> {
-    runId: string;
-    /**
-     * Poll until the run reaches a terminal status.
-     *
-     * Resolves with the result on success. Throws `PROVISION_RUN_COMPENSATED`
-     * when the run failed and the platform undid everything it had built (no
-     * store, no leftovers — retrying is safe), and `PROVISION_RUN_FAILED` when
-     * the cleanup ITSELF could not finish, whose message names what is left
-     * behind for an operator. `PROVISION_RUN_TIMEOUT` means only that waiting
-     * stopped: the run is still going, and {@link runId} still resolves it.
-     */
-    wait(options?: WaitOptions): Promise<T>;
-}
 export interface PlatformModule {
     /**
      * Build a whole store: seller, channel, zones, shipping methods, stock

package/dist/platform/provision-store.js

@@ -1,4 +1,5 @@
 import { BusinessRuleError, TransportError } from '@sixtyninecommerce/core';
+import { pollUntilTerminal } from '../jobs/index.js';
 import { requireHumanSession } from './guard.js';
 /** Every profile, for a caller that renders a picker. */
 export const PROVISION_PROFILES = [
@@ -9,22 +10,6 @@ export const PROVISION_PROFILES = [
     'full',
 ];
 const TERMINAL = new Set(['succeeded', 'failed', 'compensated']);
-const DEFAULT_INTERVAL_MS = 2_000;
-const MIN_INTERVAL_MS = 250;
-const DEFAULT_TIMEOUT_MS = 300_000;
-/**
- * Consecutive failed READS tolerated while waiting. A poll is a read of a run
- * that is still building a store: one 503 from a rolling restart must not
- * report a failure for work that is going fine. Reset by any successful read,
- * so only a sustained outage gives up — and a refusal that is ABOUT the run
- * (not found, no permission) is not retried at all.
- */
-const MAX_CONSECUTIVE_POLL_FAILURES = 3;
-/** A read that failed for a reason polling again cannot fix. */
-function isTerminalPollError(error) {
-    const status = error?.status;
-    return typeof status === 'number' && status >= 400 && status < 500 && status !== 429;
-}
 export function createPlatformModule(transport, config) {
     async function provisionRun(runId, options) {
         requireHumanSession(config);
@@ -42,39 +27,13 @@ export function createPlatformModule(transport, config) {
             return {
                 runId,
                 async wait(waitOptions) {
-                    const intervalMs = Math.max(waitOptions?.intervalMs ?? DEFAULT_INTERVAL_MS, MIN_INTERVAL_MS);
-                    const deadline = Date.now() + (waitOptions?.timeoutMs ?? DEFAULT_TIMEOUT_MS);
-                    let consecutiveFailures = 0;
-                    let lastSeen;
-                    for (;;) {
-                        let run;
-                        try {
-                            run = await provisionRun(runId, {
-                                ...options,
-                                ...(waitOptions?.signal ? { signal: waitOptions.signal } : {}),
-                            });
-                            consecutiveFailures = 0;
-                        }
-                        catch (error) {
-                            if (waitOptions?.signal?.aborted === true)
-                                throw error;
-                            consecutiveFailures += 1;
-                            if (isTerminalPollError(error) ||
-                                consecutiveFailures > MAX_CONSECUTIVE_POLL_FAILURES) {
-                                throw error;
-                            }
-                            if (Date.now() >= deadline)
-                                throw timedOut(runId, lastSeen);
-                            await delay(intervalMs, waitOptions?.signal);
-                            continue;
-                        }
-                        lastSeen = run;
-                        if (TERMINAL.has(run.status))
-                            return resultOf(run);
-                        if (Date.now() >= deadline)
-                            throw timedOut(runId, run);
-                        await delay(intervalMs, waitOptions?.signal);
-                    }
+                    const run = await pollUntilTerminal({
+                        read: (signal) => provisionRun(runId, { ...options, ...(signal ? { signal } : {}) }),
+                        isTerminal: (candidate) => TERMINAL.has(candidate.status),
+                        onTimeout: (lastSeen) => timedOut(runId, lastSeen),
+                        ...waitOptions,
+                    });
+                    return resultOf(run);
                 },
             };
         },
@@ -121,20 +80,3 @@ function timedOut(runId, run) {
         retryable: true,
     });
 }
-function delay(ms, signal) {
-    return new Promise((resolve, reject) => {
-        if (signal?.aborted) {
-            reject(signal.reason instanceof Error ? signal.reason : new Error('Aborted'));
-            return;
-        }
-        const timer = setTimeout(() => {
-            signal?.removeEventListener('abort', onAbort);
-            resolve();
-        }, ms);
-        function onAbort() {
-            clearTimeout(timer);
-            reject(signal?.reason instanceof Error ? signal.reason : new Error('Aborted'));
-        }
-        signal?.addEventListener('abort', onAbort, { once: true });
-    });
-}