@sixtyninecommerce/admin 0.6.0 → 0.7.0

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 });
-    });
-}

package/dist/tax/index.d.ts

@@ -0,0 +1,128 @@
+import { type Page, type Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/**
+ * The mapping used when no mapping names the country the money is taxed in.
+ *
+ * A real row, not an absence: it is set and removed through the same two
+ * methods as any country's, so "this class says nothing about Germany" and
+ * "this class charges Germany the fallback" are different states rather than
+ * the same one read two ways.
+ */
+export declare const TAX_CLASS_FALLBACK_COUNTRY = "*";
+/** As much of a Vendure tax category as a mapping projects. */
+export interface TaxClassTaxCategory {
+    id: string;
+    name: string;
+    /** True for a category the store's own tax setup treats as the default. */
+    isDefault: boolean;
+}
+/** One country's answer for one class. */
+export interface TaxClassMapping {
+    /** ISO 3166-1 alpha-2, upper case — or `*`, the fallback. */
+    countryCode: string;
+    taxCategoryId: string;
+    taxCategory: TaxClassTaxCategory;
+}
+/**
+ * A store's own name for how something is taxed — `standard`, `reduced`,
+ * `zero-rated` (spec §8.6).
+ *
+ * Tax categories and their rates are platform-wide, shared by every store on
+ * the platform. The class is this store's indirection in front of them: the
+ * store owns the key and the label, and the mappings say which global category
+ * prices it in which country.
+ */
+export interface TaxClass {
+    id: string;
+    /**
+     * Kebab-case handle, unique in this store. The identity: it is what
+     * `ProductVariant.customFields.taxClassKey` carries, what a surcharge names,
+     * and what `tax_class.changed` puts on the event bus.
+     */
+    key: string;
+    label: string;
+    mappings: TaxClassMapping[];
+}
+/**
+ * Create a class, or re-label the one that already carries the key.
+ *
+ * There is NO rename. The key is stored on product variants and held by every
+ * consumer that has seen a `tax_class.changed`, so a merchant who wants a
+ * different key creates one and deletes the old — in that order, because the
+ * delete is refused while variants still carry it.
+ */
+export interface UpsertTaxClassInput {
+    /** Kebab-case, 1–64 characters (`INVALID_TAX_CLASS_KEY` otherwise). */
+    key: string;
+    label: string;
+}
+/**
+ * The store's tax classes and the country mappings that price them (spec §8.6).
+ *
+ * Reading needs `ReadSettings`, writing `UpdateSettings` — deliberately NOT the
+ * tax-category permissions, which govern the platform-wide table every store
+ * shares. Everything is scoped to the channel the client is on: another store's
+ * class is invisible to `get`, unwritable by `mappings.set`, and reported as
+ * absent by `delete`.
+ *
+ * **Coded refusals**, delivered as GraphQL errors with `extensions.code`:
+ * `TAX_CLASS_NOT_FOUND` (→ `NotFoundError`), which is also the answer for a
+ * class belonging to another store; `TAX_CLASS_KEY_TAKEN` (→ `ConflictError`),
+ * which a caller meets only by losing a race with a concurrent create;
+ * `TAX_CLASS_IN_USE` (→ `ConflictError`) on a delete while product variants
+ * still carry the key; `TAX_CLASS_UNMAPPED` (→ `ValidationError`) when
+ * something asks a class to price money in a country it says nothing about, and
+ * `TAX_CLASS_RATE_MISSING` (→ `ValidationError`) when it IS mapped but that
+ * category has no rate in the zone the money is taxed in;
+ * `TAX_CATEGORY_NOT_FOUND` (→ `NotFoundError`); and
+ * `INVALID_TAX_CLASS_KEY` / `INVALID_TAX_CLASS_LABEL` /
+ * `INVALID_TAX_CLASS_COUNTRY` (→ `ValidationError`).
+ */
+export interface TaxClassesModule {
+    /**
+     * Every class of this store, by key.
+     *
+     * A `Page` because every list in this SDK is one (spec §9.2), not because
+     * this query pages: `taxClasses` answers the complete array, so the page is
+     * always the last one and `total` is its length. If the endpoint ever grows a
+     * cursor, consumers walking it with `.next()` or `for await` keep working.
+     */
+    list(options?: Call): Promise<Page<TaxClass>>;
+    /**
+     * One class, or null when this store has none with that key — including a key
+     * that belongs to another store. A key that is not kebab-case at all is a
+     * different answer: it is refused with `INVALID_TAX_CLASS_KEY` rather than
+     * reported as absent.
+     */
+    get(key: string, options?: Call): Promise<TaxClass | null>;
+    upsert(input: UpsertTaxClassInput, options?: Call): Promise<TaxClass>;
+    /**
+     * True when a class was removed, false when there was none — so a repeated
+     * delete is not an error. A malformed key is still refused with
+     * `INVALID_TAX_CLASS_KEY`, and a class product variants still carry with
+     * `TAX_CLASS_IN_USE`.
+     */
+    delete(key: string, options?: Call): Promise<boolean>;
+}
+/** The country → tax category table of one class. */
+export interface TaxMappingsModule {
+    /**
+     * Point one country — or {@link TAX_CLASS_FALLBACK_COUNTRY} — at a tax
+     * category, replacing that country's mapping if it had one. Country codes are
+     * stored upper case; `nl` and `NL` are the same mapping.
+     */
+    set(key: string, countryCode: string, taxCategoryId: string, options?: Call): Promise<TaxClass>;
+    /** Drop one country's mapping. Silent when there was none. */
+    remove(key: string, countryCode: string, options?: Call): Promise<TaxClass>;
+}
+export interface TaxModule {
+    classes: TaxClassesModule;
+    mappings: TaxMappingsModule;
+}
+export declare const TAX_CLASSES_QUERY = "\n  query TaxClasses {\n    taxClasses { \n  id\n  key\n  label\n  mappings {\n    countryCode\n    taxCategoryId\n    taxCategory {\n      id\n      name\n      isDefault\n    }\n  }\n }\n  }\n";
+export declare const TAX_CLASS_QUERY = "\n  query TaxClass($key: String!) {\n    taxClass(key: $key) { \n  id\n  key\n  label\n  mappings {\n    countryCode\n    taxCategoryId\n    taxCategory {\n      id\n      name\n      isDefault\n    }\n  }\n }\n  }\n";
+export declare const UPSERT_TAX_CLASS_MUTATION = "\n  mutation UpsertTaxClass($input: UpsertTaxClassInput!) {\n    upsertTaxClass(input: $input) { \n  id\n  key\n  label\n  mappings {\n    countryCode\n    taxCategoryId\n    taxCategory {\n      id\n      name\n      isDefault\n    }\n  }\n }\n  }\n";
+export declare const DELETE_TAX_CLASS_MUTATION = "\n  mutation DeleteTaxClass($key: String!) {\n    deleteTaxClass(key: $key)\n  }\n";
+export declare const SET_TAX_CLASS_MAPPING_MUTATION = "\n  mutation SetTaxClassMapping($key: String!, $countryCode: String!, $taxCategoryId: ID!) {\n    setTaxClassMapping(key: $key, countryCode: $countryCode, taxCategoryId: $taxCategoryId) {\n      \n  id\n  key\n  label\n  mappings {\n    countryCode\n    taxCategoryId\n    taxCategory {\n      id\n      name\n      isDefault\n    }\n  }\n\n    }\n  }\n";
+export declare const REMOVE_TAX_CLASS_MAPPING_MUTATION = "\n  mutation RemoveTaxClassMapping($key: String!, $countryCode: String!) {\n    removeTaxClassMapping(key: $key, countryCode: $countryCode) { \n  id\n  key\n  label\n  mappings {\n    countryCode\n    taxCategoryId\n    taxCategory {\n      id\n      name\n      isDefault\n    }\n  }\n }\n  }\n";
+export declare function createTaxModule(transport: Transport): TaxModule;

package/dist/tax/index.js

@@ -0,0 +1,101 @@
+import { createPage } from '@sixtyninecommerce/core';
+/**
+ * The mapping used when no mapping names the country the money is taxed in.
+ *
+ * A real row, not an absence: it is set and removed through the same two
+ * methods as any country's, so "this class says nothing about Germany" and
+ * "this class charges Germany the fallback" are different states rather than
+ * the same one read two ways.
+ */
+export const TAX_CLASS_FALLBACK_COUNTRY = '*';
+const TAX_CLASS_FIELDS = /* GraphQL */ `
+  id
+  key
+  label
+  mappings {
+    countryCode
+    taxCategoryId
+    taxCategory {
+      id
+      name
+      isDefault
+    }
+  }
+`;
+export const TAX_CLASSES_QUERY = /* GraphQL */ `
+  query TaxClasses {
+    taxClasses { ${TAX_CLASS_FIELDS} }
+  }
+`;
+export const TAX_CLASS_QUERY = /* GraphQL */ `
+  query TaxClass($key: String!) {
+    taxClass(key: $key) { ${TAX_CLASS_FIELDS} }
+  }
+`;
+export const UPSERT_TAX_CLASS_MUTATION = /* GraphQL */ `
+  mutation UpsertTaxClass($input: UpsertTaxClassInput!) {
+    upsertTaxClass(input: $input) { ${TAX_CLASS_FIELDS} }
+  }
+`;
+export const DELETE_TAX_CLASS_MUTATION = /* GraphQL */ `
+  mutation DeleteTaxClass($key: String!) {
+    deleteTaxClass(key: $key)
+  }
+`;
+export const SET_TAX_CLASS_MAPPING_MUTATION = /* GraphQL */ `
+  mutation SetTaxClassMapping($key: String!, $countryCode: String!, $taxCategoryId: ID!) {
+    setTaxClassMapping(key: $key, countryCode: $countryCode, taxCategoryId: $taxCategoryId) {
+      ${TAX_CLASS_FIELDS}
+    }
+  }
+`;
+export const REMOVE_TAX_CLASS_MAPPING_MUTATION = /* GraphQL */ `
+  mutation RemoveTaxClassMapping($key: String!, $countryCode: String!) {
+    removeTaxClassMapping(key: $key, countryCode: $countryCode) { ${TAX_CLASS_FIELDS} }
+  }
+`;
+export function createTaxModule(transport) {
+    return {
+        classes: {
+            async list(options) {
+                const data = await transport.graphql({ api: 'admin', query: TAX_CLASSES_QUERY }, options);
+                const items = data.taxClasses;
+                return createPage(items, { nextCursor: null, hasNext: false, total: items.length }, () => {
+                    // Unreachable while `hasNext` is false — `Page.next()` short-circuits
+                    // — and a rejection rather than a silent re-fetch if that changes.
+                    throw new Error('taxClasses returns a complete list; there is no next page');
+                });
+            },
+            async get(key, options) {
+                const data = await transport.graphql({ api: 'admin', query: TAX_CLASS_QUERY, variables: { key } }, options);
+                return data.taxClass;
+            },
+            async upsert(input, options) {
+                const data = await transport.graphql({ api: 'admin', query: UPSERT_TAX_CLASS_MUTATION, variables: { input } }, options);
+                return data.upsertTaxClass;
+            },
+            async delete(key, options) {
+                const data = await transport.graphql({ api: 'admin', query: DELETE_TAX_CLASS_MUTATION, variables: { key } }, options);
+                return data.deleteTaxClass;
+            },
+        },
+        mappings: {
+            async set(key, countryCode, taxCategoryId, options) {
+                const data = await transport.graphql({
+                    api: 'admin',
+                    query: SET_TAX_CLASS_MAPPING_MUTATION,
+                    variables: { key, countryCode, taxCategoryId },
+                }, options);
+                return data.setTaxClassMapping;
+            },
+            async remove(key, countryCode, options) {
+                const data = await transport.graphql({
+                    api: 'admin',
+                    query: REMOVE_TAX_CLASS_MAPPING_MUTATION,
+                    variables: { key, countryCode },
+                }, options);
+                return data.removeTaxClassMapping;
+            },
+        },
+    };
+}

package/dist/tenant/capabilities.d.ts

@@ -68,6 +68,21 @@ export interface CapabilityManifest {
      * apps work has not written.
      */
     installedApps: never[];
+    /**
+     * The `aud` an app assertion must carry to be exchanged at this deployment —
+     * its public Vendure origin. Copy it VERBATIM into the claim; re-deriving it
+     * from a URL you hold is the drift the platform compares against as a plain
+     * string. `createAppCredential` already does this for you, so this member is
+     * for a caller signing assertions by hand.
+     *
+     * Camelised from the wire's `assertion_audience`, like every other member
+     * here. `null` means the plugins service cannot state one — which does NOT
+     * mean the exchange accepts an assertion without `aud`, since the two run as
+     * separate deployment resources; ask the operator rather than omitting it.
+     *
+     * Optional because a platform older than this field simply does not send it.
+     */
+    assertionAudience?: string | null;
     /** A member added after this SDK release arrives camelised and untouched. */
     [extra: string]: unknown;
 }

package/dist/types.d.ts

@@ -2,9 +2,26 @@ import type { ChannelInfo, TenantContext, TenantScope } from '@sixtyninecommerce
 /** Per-call options every admin method accepts (spec §9.2). */
 export interface Call {
     /**
-     * Sent as `Idempotency-Key` on a REST write, and ignored on a GraphQL one —
-     * the Admin API has no header for it, so an `apiTokens.*` write is never
-     * deduplicated and a repeat is a second write.
+     * Sent as `Idempotency-Key` on a REST write. On a GraphQL one it is sent as
+     * an ARGUMENT — the Admin API has no header for it — and only the mutations
+     * that declare one act on it. Today those are the money mutations
+     * `payments.record`, `orders.park`, `orders.settle` and all three
+     * `orders.surcharges.*`, plus `payments.providers.completeOnboarding` and
+     * `payments.providers.terminals.provision`. Repeating one under the same key
+     * returns the first call's result instead of moving the money again; a
+     * DIFFERENT request under the same key is refused with
+     * `IDEMPOTENCY_CONFLICT`.
+     *
+     * Two deliberate exceptions on that list. `customers.erase` takes a key but
+     * RECORDS it for provenance rather than keying on it: that mutation is
+     * idempotent on the customer itself, which is the stronger key. And
+     * `payments.providers.startOnboarding` takes none at all, because its
+     * response carries a link that can be single-use and a stored response is
+     * re-served for 24 hours.
+     *
+     * Everything else — `apiTokens.*` and the rest of the GraphQL surface —
+     * still sends the key and acts on nothing, so a repeat there is a second
+     * write.
      *
      * On REST, three of this SDK's writes are deduplicated by the service itself:
      * `content.forms.upsertBySlug` (`PUT /forms/by-slug/:slug`),