@sixtyninecommerce/admin 0.3.1 → 0.4.0

package/README.md

@@ -276,6 +276,60 @@ signal (a TanStack Query `queryFn` gets one for free) is safe: one component unm
 the catalog for the rest of the page. `refresh()` is not shared, so its `signal` cancels the request
 itself.
 
+### Heads
+
+A HEAD is one client surface a store serves — its own storefront, a native app, a trade portal, a
+POS till, an integration. The registry is what CORS, the email deep links and the payment
+return-URL allow-list are built from.
+
+```ts
+const heads = await admin.heads.list();
+
+const pos = await admin.heads.create({
+  key: 'pos',
+  kind: 'native',
+  name: 'Shop floor till',
+  origins: ['https://pos.example.com'],
+});
+
+await admin.heads.update(pos.id, { origins: ['https://pos.example.com', 'https://till.example.com'] });
+await admin.heads.delete(pos.id);
+```
+
+`list()` returns a plain array, not a `Page`: the Admin API does not paginate heads, and a cursor
+would promise a second page that cannot exist. `update()` is a PATCH — an omitted field is left as
+it is, an explicit `null` clears a nullable one.
+
+`key` is what a client sends as the `x-head` header (`tenant.head` in a `TenantContext`), and it is
+how the platform routes an identity email's deep link back to the surface the customer started on.
+
+A request with no `x-head` gets the store's default head — as long as that head is a CUSTOMER
+surface a browser can follow: `kind` `web` or `trade`, with `deepLinkScheme: 'https'`. Otherwise it
+falls through to the store's first such head; a `native` till would otherwise collect every
+shopper's magic link simply by being the first head a retail tenant registers.
+
+`x-head` may name a `web`, `trade` or `native` head — that is how a login started in the app returns
+to the app. It may **not** name a `backoffice` or `integration` head, and such a key is ignored like
+an unknown one: the header arrives on an unauthenticated mutation whose only other input is the
+recipient's address, so honouring it would let anyone have a customer's login token mailed to the
+dashboard host or to a third party's origin.
+
+There is always exactly one default once a store has any head: the first head created becomes it,
+`setDefault()` moves it, and removing it is refused (`HEAD_DEFAULT_REQUIRED`) while other heads
+remain — a store with heads but no default would resolve no link at all. `isDefault` is therefore
+absent from the update input.
+
+`Channel.customFields.storefrontUrl` remains for one release as a read-only mirror of the default
+`web` head's `deepLinkBase` (its first origin when it has none); the platform writes it on every head
+change. The base and not the bare origin, because that field is also what canonical, hreflang and
+sitemap URLs are composed on — mirroring the origin over a storefront mounted under a path would
+point them all at a 404. It is never cleared: a store that removes its last head keeps the value it
+had before the registry.
+
+Read with `ReadSettings` and written with `UpdateSettings` — the same grants that govern
+`storefrontUrl` itself. A head an app installed (`installationId` set) is managed through that app's
+declarations and is refused here with `HEAD_APP_OWNED`.
+
 ### Errors
 
 One hierarchy, all re-exported from this package so you need no direct dependency on

package/dist/client.d.ts

@@ -3,8 +3,10 @@ import { type ApiTokensModule } from './api-tokens/index.js';
 import { type AuditModule } from './audit/index.js';
 import { type AuthModule } from './auth/index.js';
 import { type FormsModule } from './content/forms.js';
+import { type HeadsModule } from './heads/index.js';
 import { type LocationsModule } from './locations/index.js';
 import { type MetaModule } from './meta/index.js';
+import { type PlatformModule } from './platform/provision-store.js';
 import { type RedirectsModule } from './seo/redirects.js';
 import { type ChannelsModule } from './tenant/channels.js';
 import { type RetentionModule } from './tenant/retention.js';
@@ -48,6 +50,8 @@ export interface AdminClient {
     content: {
         forms: FormsModule;
     };
+    /** The store's head registry: every client surface it serves (spec §6.7). */
+    heads: HeadsModule;
     /** Stock-location profiles (spec §8.7); `TenantContext.location` names one by id. */
     locations: LocationsModule;
     /** Labels, transitions, permission and plugin catalogs, settings schemas. */
@@ -59,8 +63,11 @@ export interface AdminClient {
     tenant: {
         retention: RetentionModule;
     };
-    /** Human SuperAdmin surface. Empty in phase 0. */
-    platform: Record<string, never>;
+    /**
+     * Human SuperAdmin surface. Every method refuses an API token before the
+     * request leaves the process (`PLATFORM_REQUIRES_SESSION`).
+     */
+    platform: PlatformModule;
     /** A derived client on another tenant, sharing this one's principal. */
     withTenant(tenant: Partial<TenantContext> & {
         scope?: TenantScope;

package/dist/client.js

@@ -3,8 +3,10 @@ import { createApiTokensModule } from './api-tokens/index.js';
 import { createAuditModule } from './audit/index.js';
 import { createAuthModule } from './auth/index.js';
 import { createFormsModule } from './content/forms.js';
+import { createHeadsModule } from './heads/index.js';
 import { createLocationsModule } from './locations/index.js';
 import { createMetaModule } from './meta/index.js';
+import { createPlatformModule } from './platform/provision-store.js';
 import { createRedirectsModule } from './seo/redirects.js';
 import { createChannelsModule } from './tenant/channels.js';
 import { createRetentionModule } from './tenant/retention.js';
@@ -220,11 +222,12 @@ function buildClient(config, overrides, resolver, shared) {
         audit: createAuditModule(transport),
         channels: createChannelsModule(resolver),
         content: { forms: createFormsModule(transport) },
+        heads: createHeadsModule(transport),
         locations: createLocationsModule(transport),
         meta: createMetaModule(transport),
         seo: { redirects: createRedirectsModule(transport) },
         tenant: { retention: createRetentionModule(transport) },
-        platform: {},
+        platform: createPlatformModule(transport, config),
         withTenant(next) {
             // `mergeTenant`, not a spread: it merges `actor` FIELD BY FIELD, so a
             // derived client that names only a registerRef keeps the staffRef this

package/dist/heads/index.d.ts

@@ -0,0 +1,103 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/**
+ * A HEAD: one client surface a store serves — its own storefront, a native app,
+ * a trade portal, a POS till, an integration (spec §6.7).
+ *
+ * The registry is what CORS, the email deep links and the payment return-URL
+ * allow-list are built from. `Channel.customFields.storefrontUrl` remains for
+ * one release as a read-only mirror of the default `web` head's deep-link base
+ * (its first origin when it has none).
+ */
+export interface Head {
+    id: string;
+    channelId: string;
+    /**
+     * The app installation that owns this head, or null for a head the merchant
+     * owns. An app-owned head is managed through that app's declarations and is
+     * refused here with `HEAD_APP_OWNED`.
+     */
+    installationId: string | null;
+    /** Kebab-case handle, unique in this store. What a client sends as `x-head`. */
+    key: string;
+    /** One of: `web`, `native`, `trade`, `backoffice`, `integration`. */
+    kind: string;
+    name: string;
+    /** Browser origins, `scheme://host[:port]` — what a browser sends as `Origin`. */
+    origins: string[];
+    /** Base every email link is composed onto. Null means "use the first origin". */
+    deepLinkBase: string | null;
+    /** One of: `https`, `app`. */
+    deepLinkScheme: string;
+    /** One of: `CONSUMER`, `TRADE`. Null means the store's own default applies. */
+    defaultOrderScope: string | null;
+    eventSubscriptionId: string | null;
+    /**
+     * The store's default head; at most one per store.
+     *
+     * A request that sends no `x-head` resolves to it only when it is a CUSTOMER
+     * surface a browser can follow: `kind` `'web'` or `'trade'`, and
+     * `deepLinkScheme: 'https'`. Otherwise the request falls through to the
+     * store's first such head — a `native` till would otherwise collect every
+     * shopper's login link by being the first head a retail tenant registers.
+     *
+     * `x-head` may name a `web`, `trade` or `native` head, which is how a native
+     * client gets its own deep links. It may NOT name a `backoffice` or
+     * `integration` head: that header arrives on an unauthenticated mutation, and
+     * honouring it would let anyone mail a customer's login token to the
+     * dashboard host or to a third party's origin.
+     */
+    isDefault: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CreateHeadInput {
+    key: string;
+    kind: string;
+    name: string;
+    /** At least one absolute URL; the server stores each as its origin. */
+    origins: string[];
+    deepLinkBase?: string | null;
+    deepLinkScheme?: string | null;
+    defaultOrderScope?: string | null;
+    /**
+     * The store's FIRST head is always its default whatever this says — a store
+     * with heads but no default resolves no deep link at all.
+     */
+    isDefault?: boolean;
+}
+/** A PATCH: an omitted field is left as it is, an explicit null clears a nullable one. */
+export interface UpdateHeadInput {
+    key?: string;
+    kind?: string;
+    name?: string;
+    origins?: string[];
+    deepLinkBase?: string | null;
+    deepLinkScheme?: string;
+    defaultOrderScope?: string | null;
+}
+export declare const HEAD_FIELDS = "\n  id\n  channelId\n  installationId\n  key\n  kind\n  name\n  origins\n  deepLinkBase\n  deepLinkScheme\n  defaultOrderScope\n  eventSubscriptionId\n  isDefault\n  createdAt\n  updatedAt\n";
+export declare const LIST_QUERY = "\n  query ChannelHeads {\n    channelHeads { \n  id\n  channelId\n  installationId\n  key\n  kind\n  name\n  origins\n  deepLinkBase\n  deepLinkScheme\n  defaultOrderScope\n  eventSubscriptionId\n  isDefault\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const GET_QUERY = "\n  query ChannelHead($id: ID!) {\n    channelHead(id: $id) { \n  id\n  channelId\n  installationId\n  key\n  kind\n  name\n  origins\n  deepLinkBase\n  deepLinkScheme\n  defaultOrderScope\n  eventSubscriptionId\n  isDefault\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const CREATE_MUTATION = "\n  mutation CreateChannelHead($input: CreateChannelHeadInput!) {\n    createChannelHead(input: $input) { \n  id\n  channelId\n  installationId\n  key\n  kind\n  name\n  origins\n  deepLinkBase\n  deepLinkScheme\n  defaultOrderScope\n  eventSubscriptionId\n  isDefault\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const UPDATE_MUTATION = "\n  mutation UpdateChannelHead($id: ID!, $input: UpdateChannelHeadInput!) {\n    updateChannelHead(id: $id, input: $input) { \n  id\n  channelId\n  installationId\n  key\n  kind\n  name\n  origins\n  deepLinkBase\n  deepLinkScheme\n  defaultOrderScope\n  eventSubscriptionId\n  isDefault\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const DELETE_MUTATION = "\n  mutation DeleteChannelHead($id: ID!) {\n    deleteChannelHead(id: $id)\n  }\n";
+export declare const SET_DEFAULT_MUTATION = "\n  mutation SetDefaultChannelHead($id: ID!) {\n    setDefaultChannelHead(id: $id) { \n  id\n  channelId\n  installationId\n  key\n  kind\n  name\n  origins\n  deepLinkBase\n  deepLinkScheme\n  defaultOrderScope\n  eventSubscriptionId\n  isDefault\n  createdAt\n  updatedAt\n }\n  }\n";
+/**
+ * The store's head registry (spec §6.7).
+ *
+ * `list` returns a plain array, not a `Page`: the Admin API does not paginate
+ * heads, and wrapping a handful of rows in a cursor would promise a second page
+ * that can never exist. Read and written with the settings permissions.
+ */
+export interface HeadsModule {
+    list(options?: Call): Promise<Head[]>;
+    get(id: string, options?: Call): Promise<Head | null>;
+    create(input: CreateHeadInput, options?: Call): Promise<Head>;
+    update(id: string, input: UpdateHeadInput, options?: Call): Promise<Head>;
+    /** True when the head was removed. Removing the default is refused while others remain. */
+    delete(id: string, options?: Call): Promise<boolean>;
+    /** Move the store's default head. There is no way to unset one, only to move it. */
+    setDefault(id: string, options?: Call): Promise<Head>;
+}
+export declare function createHeadsModule(transport: Transport): HeadsModule;

package/dist/heads/index.js

@@ -0,0 +1,74 @@
+export const HEAD_FIELDS = /* GraphQL */ `
+  id
+  channelId
+  installationId
+  key
+  kind
+  name
+  origins
+  deepLinkBase
+  deepLinkScheme
+  defaultOrderScope
+  eventSubscriptionId
+  isDefault
+  createdAt
+  updatedAt
+`;
+export const LIST_QUERY = /* GraphQL */ `
+  query ChannelHeads {
+    channelHeads { ${HEAD_FIELDS} }
+  }
+`;
+export const GET_QUERY = /* GraphQL */ `
+  query ChannelHead($id: ID!) {
+    channelHead(id: $id) { ${HEAD_FIELDS} }
+  }
+`;
+export const CREATE_MUTATION = /* GraphQL */ `
+  mutation CreateChannelHead($input: CreateChannelHeadInput!) {
+    createChannelHead(input: $input) { ${HEAD_FIELDS} }
+  }
+`;
+export const UPDATE_MUTATION = /* GraphQL */ `
+  mutation UpdateChannelHead($id: ID!, $input: UpdateChannelHeadInput!) {
+    updateChannelHead(id: $id, input: $input) { ${HEAD_FIELDS} }
+  }
+`;
+export const DELETE_MUTATION = /* GraphQL */ `
+  mutation DeleteChannelHead($id: ID!) {
+    deleteChannelHead(id: $id)
+  }
+`;
+export const SET_DEFAULT_MUTATION = /* GraphQL */ `
+  mutation SetDefaultChannelHead($id: ID!) {
+    setDefaultChannelHead(id: $id) { ${HEAD_FIELDS} }
+  }
+`;
+export function createHeadsModule(transport) {
+    return {
+        async list(options) {
+            const data = await transport.graphql({ api: 'admin', query: LIST_QUERY }, options);
+            return data.channelHeads;
+        },
+        async get(id, options) {
+            const data = await transport.graphql({ api: 'admin', query: GET_QUERY, variables: { id } }, options);
+            return data.channelHead;
+        },
+        async create(input, options) {
+            const data = await transport.graphql({ api: 'admin', query: CREATE_MUTATION, variables: { input } }, options);
+            return data.createChannelHead;
+        },
+        async update(id, input, options) {
+            const data = await transport.graphql({ api: 'admin', query: UPDATE_MUTATION, variables: { id, input } }, options);
+            return data.updateChannelHead;
+        },
+        async delete(id, options) {
+            const data = await transport.graphql({ api: 'admin', query: DELETE_MUTATION, variables: { id } }, options);
+            return data.deleteChannelHead;
+        },
+        async setDefault(id, options) {
+            const data = await transport.graphql({ api: 'admin', query: SET_DEFAULT_MUTATION, variables: { id } }, options);
+            return data.setDefaultChannelHead;
+        },
+    };
+}

package/dist/index.d.ts

@@ -30,10 +30,13 @@ export type { AuthModule } from './auth/index.js';
 export { type AdminClient, type AdminClientConfig, createAdminClient, type SessionConfig, } from './client.js';
 export type { Form, FormField, FormFieldInput, FormFieldTranslation, FormFieldTranslationInput, FormInput, FormsModule, FormTranslation, FormTranslationInput, } from './content/forms.js';
 export { AdminProjectionError } from './errors.js';
+export type { CreateHeadInput, Head, HeadsModule, UpdateHeadInput, } from './heads/index.js';
 export type { LocationProfile, LocationStockLocation, LocationsModule, OpeningHours, OpeningHoursDay, OpeningHoursInterval, StockLocationAddress, StockLocationAddressInput, UpsertLocationProfileInput, } from './locations/index.js';
 export { OPENING_HOURS_DAYS } from './locations/index.js';
 export type { ApiTokenTemplate, JsonSchema, LabelMap, MetaCatalog, MetaCatalogLabels, MetaCatalogPermissions, MetaCatalogPlugins, MetaCatalogTransitions, MetaModule, PermissionGroup, PluginCatalogEntry, RoleTemplate, StatusMetaMap, StatusTone, TransitionMap, } from './meta/index.js';
 export { requireHumanSession } from './platform/guard.js';
+export type { JobHandle, PlatformModule, ProvisionProfile, ProvisionRun, ProvisionRunStatus, ProvisionStep, ProvisionStepStatus, ProvisionStoreInput, ProvisionStoreResult, WaitOptions, } from './platform/provision-store.js';
+export { PROVISION_PROFILES } from './platform/provision-store.js';
 export type { Redirect, RedirectCreateInput, RedirectsModule, RedirectUpdateInput, } from './seo/redirects.js';
 export type { ChannelsModule } from './tenant/channels.js';
 export type { ChannelRetention, RetentionHold, RetentionModule, SetRetentionInput, } from './tenant/retention.js';

package/dist/index.js

@@ -21,3 +21,4 @@ export { createAdminClient, } from './client.js';
 export { AdminProjectionError } from './errors.js';
 export { OPENING_HOURS_DAYS } from './locations/index.js';
 export { requireHumanSession } from './platform/guard.js';
+export { PROVISION_PROFILES } from './platform/provision-store.js';

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

@@ -0,0 +1,157 @@
+import { type Transport } from '@sixtyninecommerce/core';
+import type { AdminClientConfig } from '../client.js';
+import type { Call } from '../types.js';
+/**
+ * Which objects a new store is provisioned with.
+ *
+ * Mirrors the server's list; the server is the enforcer, so an unknown value is
+ * refused with `VALIDATION_FAILED` naming the accepted ones rather than failing
+ * here.
+ */
+export type ProvisionProfile = 'cms-only' | 'catalog' | 'commerce' | 'pos-commerce' | 'full';
+/** Every profile, for a caller that renders a picker. */
+export declare const PROVISION_PROFILES: readonly ProvisionProfile[];
+export interface ProvisionStoreInput {
+    /** Human store name — becomes the Seller name and the store's business name. */
+    name: string;
+    /**
+     * Lowercase kebab-case. It is also the object-storage prefix, the CMS key and
+     * the order-number namespace, and it can only be changed later by a rename
+     * job — so it is worth getting right.
+     */
+    code: string;
+    /** Defaults to `commerce`, which is the full webshop. */
+    profile?: ProvisionProfile;
+    defaultLanguageCode: string;
+    availableLanguageCodes?: string[];
+    defaultCurrencyCode: string;
+    availableCurrencyCodes?: string[];
+    pricesIncludeTax?: boolean;
+    /**
+     * The store's tax and shipping zones. Send BOTH or NEITHER — a request naming
+     * one is refused, because the other would then be derived and the store would
+     * quietly end up with two different zones.
+     *
+     * Omitted, both are resolved from `country`: the SMALLEST zone that actually
+     * CONTAINS that country wins (ties broken by name, then id). A country in no
+     * zone is an error, not a guess — the old heuristic matched zone NAMES and
+     * fell back to Europe/EU, which is how a US store ended up on European VAT.
+     */
+    defaultTaxZoneId?: string;
+    defaultShippingZoneId?: string;
+    addressLine1: string;
+    addressLine2?: string;
+    city: string;
+    postalCode: string;
+    province?: string;
+    /** ISO 3166-1 alpha-2. */
+    country: string;
+    /** IANA zone. Every day-resolution comparison for this store uses it. */
+    timezone: string;
+    legalName: string;
+    vatNumber?: string;
+    registrationNumber?: string;
+    /**
+     * Invite a merchant administrator to the new store. SOFT-FAIL: a bounced
+     * invitation never fails the provisioning — it lands in
+     * {@link ProvisionRun.warnings} and the store is still built.
+     */
+    invite?: {
+        email: string;
+    };
+    /**
+     * Reserved. Refused today with `SANDBOX_NOT_AVAILABLE` (a
+     * {@link ValidationError}) until the sandbox channel flag ships.
+     */
+    sandbox?: boolean;
+    /** An organization code. Refused with `ORGANIZATIONS_NOT_AVAILABLE`. */
+    organization?: string;
+    /** A Seller id. Refused with `ORGANIZATIONS_NOT_AVAILABLE`. */
+    legalEntity?: string;
+}
+export type ProvisionRunStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'compensated';
+export type ProvisionStepStatus = 'pending' | 'running' | 'succeeded' | 'failed' | 'skipped' | 'compensated';
+export interface ProvisionStep {
+    /** `zones`, `seller`, `channel`, `shipping-methods`, `stock-location`, `roles`, `cms-channel`, `cms-content`, `invite`. */
+    name: string;
+    /** `skipped` is a DECISION — the profile did not ask for this object. */
+    status: ProvisionStepStatus;
+    /** ISO-8601 UTC, or null for a step that never started. */
+    startedAt: string | null;
+    finishedAt: string | null;
+    error?: string;
+}
+export interface ProvisionStoreResult {
+    channelId: string;
+    channelCode: string;
+    /** The new store's channel token — what a storefront and this SDK address it by. */
+    channelToken: string;
+    sellerId: string;
+    /** The role a merchant invitation attaches to. */
+    adminRoleId: string;
+}
+export interface ProvisionRun {
+    id: string;
+    status: ProvisionRunStatus;
+    /** The step running now, or the one that failed. Null when nothing is running. */
+    step: string | null;
+    profile: string;
+    channelCode: string;
+    steps: ProvisionStep[];
+    /** Present only on a `succeeded` run. */
+    result?: ProvisionStoreResult;
+    /** Non-fatal notes. A merchant invite that bounced is the only one today. */
+    warnings: string[];
+    error?: string;
+    createdAt: string;
+    startedAt: string | null;
+    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
+     * location, roles, CMS registration and the default CMS menus and forms —
+     * which of them depends on `profile`.
+     *
+     * Returns as soon as the run is accepted. The work runs server-side as a saga
+     * with recorded compensation, so a failure half-way leaves nothing behind.
+     *
+     * `options.idempotencyKey` makes a retry return the run already in flight
+     * instead of starting a second one — send one, and reuse it only for retries
+     * of that same call.
+     *
+     * Needs a human SuperAdmin session: an API token is refused before it leaves
+     * the process (`PLATFORM_REQUIRES_SESSION`).
+     */
+    provisionStore(input: ProvisionStoreInput, options?: Call): Promise<JobHandle<ProvisionStoreResult>>;
+    /** One provisioning run, by the id `provisionStore` returned. */
+    provisionRun(runId: string, options?: Call): Promise<ProvisionRun>;
+}
+export declare function createPlatformModule(transport: Transport, config: AdminClientConfig): PlatformModule;

package/dist/platform/provision-store.js

@@ -0,0 +1,140 @@
+import { BusinessRuleError, TransportError } from '@sixtyninecommerce/core';
+import { requireHumanSession } from './guard.js';
+/** Every profile, for a caller that renders a picker. */
+export const PROVISION_PROFILES = [
+    'cms-only',
+    'catalog',
+    'commerce',
+    'pos-commerce',
+    '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);
+        return transport.rest('plugins', { method: 'GET', path: `/platform/provision-runs/${encodeURIComponent(runId)}` }, 
+        // Provisioning is cross-tenant: it creates a channel that does not exist
+        // yet, so the call must not be scoped to one.
+        { ...options, allowUnscoped: true });
+    }
+    return {
+        provisionRun,
+        async provisionStore(input, options) {
+            requireHumanSession(config);
+            const accepted = await transport.rest('plugins', { method: 'POST', path: '/platform/provision-store', body: input }, { ...options, allowUnscoped: true });
+            const runId = accepted.runId;
+            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);
+                    }
+                },
+            };
+        },
+    };
+}
+function resultOf(run) {
+    if (run.status === 'succeeded') {
+        if (run.result)
+            return run.result;
+        throw new BusinessRuleError({
+            code: 'PROVISION_RUN_INCOMPLETE',
+            message: `Provisioning run ${run.id} reports success but carries no store. Read the run for its steps.`,
+            status: 422,
+            service: 'plugins',
+        });
+    }
+    // `compensated` and `failed` differ in ONE way that matters to a caller:
+    // whether anything was left behind. Retrying is safe after the first and
+    // needs an operator after the second, so they are different codes.
+    //
+    // The detail is the failing step's own words — usually a service's message,
+    // which may or may not be a sentence — so it is punctuated here rather than
+    // run into the sentence that follows it.
+    const raw = run.error ?? `Provisioning failed at step "${run.step ?? 'unknown'}"`;
+    const detail = /[.!?]$/.test(raw.trim()) ? raw.trim() : `${raw.trim()}.`;
+    throw new BusinessRuleError({
+        code: run.status === 'compensated' ? 'PROVISION_RUN_COMPENSATED' : 'PROVISION_RUN_FAILED',
+        message: run.status === 'compensated'
+            ? `${detail} Everything it had built was removed, so nothing is left behind. (That does not mean the code is free: the most common cause is a code another store already owns.)`
+            : `${detail} The cleanup did not finish — an operator has to remove what the message names.`,
+        status: 422,
+        service: 'plugins',
+    });
+}
+function timedOut(runId, run) {
+    const at = run
+        ? `while it was at "${run.step ?? run.status}"`
+        : 'without reading it successfully';
+    return new TransportError({
+        code: 'PROVISION_RUN_TIMEOUT',
+        message: `Stopped waiting for provisioning run ${runId} ${at}. The run may still be going — poll platform.provisionRun("${runId}") to follow it.`,
+        status: 0,
+        service: 'plugins',
+        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/types.d.ts

@@ -6,12 +6,15 @@ export interface Call {
      * the Admin API has no header for it, so an `apiTokens.*` write is never
      * deduplicated and a repeat is a second write.
      *
-     * On REST, two of this SDK's writes are deduplicated by the service itself:
-     * `content.forms.upsertBySlug` (`PUT /forms/by-slug/:slug`) and
-     * `seo.redirects.create` (`POST /redirects`). Repeating one under the same
-     * key replays the first response instead of running it again; sending the
-     * same key with a DIFFERENT body is refused with 409. Everything else
-     * records the key on the wire and acts on nothing.
+     * On REST, three of this SDK's writes are deduplicated by the service itself:
+     * `content.forms.upsertBySlug` (`PUT /forms/by-slug/:slug`),
+     * `seo.redirects.create` (`POST /redirects`) and
+     * `platform.provisionStore` (`POST /platform/provision-store`). Repeating one
+     * under the same key replays the first response instead of running it again
+     * — for `provisionStore` that means the run already in flight, not a second
+     * store on a code that is now taken; sending the same key with a DIFFERENT
+     * body is refused with 409. Everything else records the key on the wire and
+     * acts on nothing.
      *
      * Use a fresh key per intended write — a UUIDv7 is ideal — and reuse it only
      * when retrying that same write. This SDK never retries a write on its own,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sixtyninecommerce/admin",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Back-office SDK for sixtynine-commerce: every capability of the platform as a method",
   "homepage": "https://github.com/SIXTYNINE-digital/sixtynine-commerce-engine/tree/main/packages/admin-client#readme",
   "repository": {