@sixtyninecommerce/admin 0.3.1 → 0.5.0

package/dist/index.d.ts

@@ -25,15 +25,22 @@ export type { DeprecationNotice, Page, PageMeta, RateLimitInfo, RetryPolicy, } f
  */
 export { AuthenticationError, BusinessRuleError, ConflictError, type ErrorDetail, NotFoundError, PermissionDeniedError, PlatformError, type ProblemDetails, RateLimitedError, TransportError, UpstreamError, ValidationError, } from '@sixtyninecommerce/core';
 export type { ApiTokensModule, CreatedApiToken } from './api-tokens/index.js';
+export type { AppCryptoKey, AppPrivateKey } from './apps/assertion.js';
+export type { AppCredential, AppCredentialConfig } from './apps/credential.js';
+export type { App, AppInstallation, ApproveConsentInput, AppsModule, InstallAppInput, } from './apps/index.js';
 export type { AuditCall, AuditCallFilter, AuditCorrelation, AuditEvent, AuditEventFilter, AuditModule, } from './audit/index.js';
 export type { AuthModule } from './auth/index.js';
-export { type AdminClient, type AdminClientConfig, createAdminClient, type SessionConfig, } from './client.js';
+export { type AdminClient, type AdminClientConfig, type AppAuthConfig, 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 type { AppKey, PlatformAppsModule, RegisterAppResult, RegisteredApp, } from './platform/apps.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/apps.d.ts

@@ -0,0 +1,76 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import { type App } from '../apps/index.js';
+import type { AdminClientConfig } from '../client.js';
+import type { Call } from '../types.js';
+export declare const APPS_QUERY = "\n  query Apps($options: AppListOptions) {\n    apps(options: $options) {\n      totalItems\n      items { \n  \n  id\n  slug\n  name\n  ownerLabel\n  declaredPermissions\n  declaredEvents\n  declaredFieldOwnership\n  customerData\n  customerDataPurpose\n  metafieldDefinitions\n  configSchema\n  hooks\n  headTemplates\n  sandboxOnly\n  status\n  manifestVersion\n  createdAt\n  updatedAt\n\n  keys {\n    id\n    kid\n    alg\n    publicKey\n    revokedAt\n    createdAt\n  }\n  enabledChannelIds\n }\n    }\n  }\n";
+export declare const APP_QUERY = "\n  query App($id: ID!) {\n    app(id: $id) { \n  \n  id\n  slug\n  name\n  ownerLabel\n  declaredPermissions\n  declaredEvents\n  declaredFieldOwnership\n  customerData\n  customerDataPurpose\n  metafieldDefinitions\n  configSchema\n  hooks\n  headTemplates\n  sandboxOnly\n  status\n  manifestVersion\n  createdAt\n  updatedAt\n\n  keys {\n    id\n    kid\n    alg\n    publicKey\n    revokedAt\n    createdAt\n  }\n  enabledChannelIds\n }\n  }\n";
+export declare const REGISTER_MUTATION = "\n  mutation RegisterApp($manifest: JSON!) {\n    registerApp(manifest: $manifest) { \n  created\n  consentRequiredInstallationIds\n  consentReasons\n  app { \n  \n  id\n  slug\n  name\n  ownerLabel\n  declaredPermissions\n  declaredEvents\n  declaredFieldOwnership\n  customerData\n  customerDataPurpose\n  metafieldDefinitions\n  configSchema\n  hooks\n  headTemplates\n  sandboxOnly\n  status\n  manifestVersion\n  createdAt\n  updatedAt\n\n  keys {\n    id\n    kid\n    alg\n    publicKey\n    revokedAt\n    createdAt\n  }\n  enabledChannelIds\n }\n }\n  }\n";
+export declare const UPDATE_MUTATION = "\n  mutation UpdateApp($id: ID!, $manifest: JSON!) {\n    updateApp(id: $id, manifest: $manifest) { \n  created\n  consentRequiredInstallationIds\n  consentReasons\n  app { \n  \n  id\n  slug\n  name\n  ownerLabel\n  declaredPermissions\n  declaredEvents\n  declaredFieldOwnership\n  customerData\n  customerDataPurpose\n  metafieldDefinitions\n  configSchema\n  hooks\n  headTemplates\n  sandboxOnly\n  status\n  manifestVersion\n  createdAt\n  updatedAt\n\n  keys {\n    id\n    kid\n    alg\n    publicKey\n    revokedAt\n    createdAt\n  }\n  enabledChannelIds\n }\n }\n  }\n";
+export declare const ADD_KEY_MUTATION = "\n  mutation AddAppKey($appId: ID!, $kid: String!, $alg: String!, $publicKey: String!) {\n    addAppKey(appId: $appId, kid: $kid, alg: $alg, publicKey: $publicKey) {\n      id\n      kid\n      alg\n      publicKey\n      revokedAt\n      createdAt\n    }\n  }\n";
+export declare const REVOKE_KEY_MUTATION = "\n  mutation RevokeAppKey($appId: ID!, $kid: String!) {\n    revokeAppKey(appId: $appId, kid: $kid) {\n      id\n      kid\n      alg\n      revokedAt\n    }\n  }\n";
+export declare const SUSPEND_MUTATION = "\n  mutation SuspendApp($id: ID!) {\n    suspendApp(id: $id) { \n  \n  id\n  slug\n  name\n  ownerLabel\n  declaredPermissions\n  declaredEvents\n  declaredFieldOwnership\n  customerData\n  customerDataPurpose\n  metafieldDefinitions\n  configSchema\n  hooks\n  headTemplates\n  sandboxOnly\n  status\n  manifestVersion\n  createdAt\n  updatedAt\n\n  keys {\n    id\n    kid\n    alg\n    publicKey\n    revokedAt\n    createdAt\n  }\n  enabledChannelIds\n }\n  }\n";
+export declare const RESUME_MUTATION = "\n  mutation ResumeApp($id: ID!) {\n    resumeApp(id: $id) { \n  \n  id\n  slug\n  name\n  ownerLabel\n  declaredPermissions\n  declaredEvents\n  declaredFieldOwnership\n  customerData\n  customerDataPurpose\n  metafieldDefinitions\n  configSchema\n  hooks\n  headTemplates\n  sandboxOnly\n  status\n  manifestVersion\n  createdAt\n  updatedAt\n\n  keys {\n    id\n    kid\n    alg\n    publicKey\n    revokedAt\n    createdAt\n  }\n  enabledChannelIds\n }\n  }\n";
+export declare const ENABLE_MUTATION = "\n  mutation EnableAppForTenant($appId: ID!, $channelId: ID!) {\n    enableAppForTenant(appId: $appId, channelId: $channelId) { \n  \n  id\n  slug\n  name\n  ownerLabel\n  declaredPermissions\n  declaredEvents\n  declaredFieldOwnership\n  customerData\n  customerDataPurpose\n  metafieldDefinitions\n  configSchema\n  hooks\n  headTemplates\n  sandboxOnly\n  status\n  manifestVersion\n  createdAt\n  updatedAt\n\n  keys {\n    id\n    kid\n    alg\n    publicKey\n    revokedAt\n    createdAt\n  }\n  enabledChannelIds\n }\n  }\n";
+export declare const DISABLE_MUTATION = "\n  mutation DisableAppForTenant($appId: ID!, $channelId: ID!) {\n    disableAppForTenant(appId: $appId, channelId: $channelId) { \n  \n  id\n  slug\n  name\n  ownerLabel\n  declaredPermissions\n  declaredEvents\n  declaredFieldOwnership\n  customerData\n  customerDataPurpose\n  metafieldDefinitions\n  configSchema\n  hooks\n  headTemplates\n  sandboxOnly\n  status\n  manifestVersion\n  createdAt\n  updatedAt\n\n  keys {\n    id\n    kid\n    alg\n    publicKey\n    revokedAt\n    createdAt\n  }\n  enabledChannelIds\n }\n  }\n";
+/** A registered public key. Only public material is ever returned. */
+export interface AppKey {
+    id: string;
+    kid: string;
+    /** `EdDSA` | `RS256`. */
+    alg: string;
+    publicKey: string;
+    revokedAt: string | null;
+    createdAt: string;
+}
+export interface RegisteredApp extends App {
+    keys: AppKey[];
+    /** Channels a SuperAdmin has enabled this app for. */
+    enabledChannelIds: string[];
+}
+export interface RegisterAppResult {
+    app: RegisteredApp;
+    /** False when the manifest updated an app that was already registered. */
+    created: boolean;
+    /** Installations this registration moved to `needs_consent`. */
+    consentRequiredInstallationIds: string[];
+    /** Why, in the words their approvers will read. */
+    consentReasons: string[];
+}
+/**
+ * The app REGISTRY — the platform operator's surface (headless spec §6.3, §6.12).
+ *
+ * Human SuperAdmin session only, enforced twice over: the engine gates every
+ * operation on Vendure's `SuperAdmin` permission — not a custom one, because a
+ * custom permission is evaluated against the ACTIVE channel and every mutation
+ * here is platform-wide — and the SDK refuses to put a machine credential on the
+ * wire towards it at all (`requireHumanSession`). An app that could register
+ * apps could declare anything and enable itself.
+ */
+export interface PlatformAppsModule {
+    list(options?: {
+        skip?: number;
+        take?: number;
+    }, call?: Call): Promise<{
+        items: RegisteredApp[];
+        totalItems: number;
+    }>;
+    get(id: string, call?: Call): Promise<RegisteredApp | null>;
+    /** Ingest a `sixtynine.app.json`. Upserts by slug: a known slug is an update. */
+    register(manifest: Record<string, unknown>, call?: Call): Promise<RegisterAppResult>;
+    /** The same ingest addressed by id; refuses a manifest whose slug is another app's. */
+    update(id: string, manifest: Record<string, unknown>, call?: Call): Promise<RegisterAppResult>;
+    addKey(input: {
+        appId: string;
+        kid: string;
+        alg: string;
+        publicKey: string;
+    }, call?: Call): Promise<AppKey>;
+    revokeKey(appId: string, kid: string, call?: Call): Promise<AppKey>;
+    /** Suspend platform-wide and kill every installation token in one action. */
+    suspend(id: string, call?: Call): Promise<RegisteredApp>;
+    resume(id: string, call?: Call): Promise<RegisteredApp>;
+    /** Offer an app to one tenant. A tenant admin can only install what is enabled. */
+    enableForTenant(appId: string, channelId: string, call?: Call): Promise<RegisteredApp>;
+    disableForTenant(appId: string, channelId: string, call?: Call): Promise<RegisteredApp>;
+}
+export declare function createPlatformAppsModule(transport: Transport, config: AdminClientConfig): PlatformAppsModule;

package/dist/platform/apps.js

@@ -0,0 +1,153 @@
+import { APP_FIELDS } from '../apps/index.js';
+import { requireHumanSession } from './guard.js';
+const APP_WITH_KEYS_FIELDS = /* GraphQL */ `
+  ${APP_FIELDS}
+  keys {
+    id
+    kid
+    alg
+    publicKey
+    revokedAt
+    createdAt
+  }
+  enabledChannelIds
+`;
+const REGISTER_RESULT_FIELDS = /* GraphQL */ `
+  created
+  consentRequiredInstallationIds
+  consentReasons
+  app { ${APP_WITH_KEYS_FIELDS} }
+`;
+export const APPS_QUERY = /* GraphQL */ `
+  query Apps($options: AppListOptions) {
+    apps(options: $options) {
+      totalItems
+      items { ${APP_WITH_KEYS_FIELDS} }
+    }
+  }
+`;
+export const APP_QUERY = /* GraphQL */ `
+  query App($id: ID!) {
+    app(id: $id) { ${APP_WITH_KEYS_FIELDS} }
+  }
+`;
+export const REGISTER_MUTATION = /* GraphQL */ `
+  mutation RegisterApp($manifest: JSON!) {
+    registerApp(manifest: $manifest) { ${REGISTER_RESULT_FIELDS} }
+  }
+`;
+export const UPDATE_MUTATION = /* GraphQL */ `
+  mutation UpdateApp($id: ID!, $manifest: JSON!) {
+    updateApp(id: $id, manifest: $manifest) { ${REGISTER_RESULT_FIELDS} }
+  }
+`;
+export const ADD_KEY_MUTATION = /* GraphQL */ `
+  mutation AddAppKey($appId: ID!, $kid: String!, $alg: String!, $publicKey: String!) {
+    addAppKey(appId: $appId, kid: $kid, alg: $alg, publicKey: $publicKey) {
+      id
+      kid
+      alg
+      publicKey
+      revokedAt
+      createdAt
+    }
+  }
+`;
+export const REVOKE_KEY_MUTATION = /* GraphQL */ `
+  mutation RevokeAppKey($appId: ID!, $kid: String!) {
+    revokeAppKey(appId: $appId, kid: $kid) {
+      id
+      kid
+      alg
+      revokedAt
+    }
+  }
+`;
+export const SUSPEND_MUTATION = /* GraphQL */ `
+  mutation SuspendApp($id: ID!) {
+    suspendApp(id: $id) { ${APP_WITH_KEYS_FIELDS} }
+  }
+`;
+export const RESUME_MUTATION = /* GraphQL */ `
+  mutation ResumeApp($id: ID!) {
+    resumeApp(id: $id) { ${APP_WITH_KEYS_FIELDS} }
+  }
+`;
+export const ENABLE_MUTATION = /* GraphQL */ `
+  mutation EnableAppForTenant($appId: ID!, $channelId: ID!) {
+    enableAppForTenant(appId: $appId, channelId: $channelId) { ${APP_WITH_KEYS_FIELDS} }
+  }
+`;
+export const DISABLE_MUTATION = /* GraphQL */ `
+  mutation DisableAppForTenant($appId: ID!, $channelId: ID!) {
+    disableAppForTenant(appId: $appId, channelId: $channelId) { ${APP_WITH_KEYS_FIELDS} }
+  }
+`;
+export function createPlatformAppsModule(transport, config) {
+    const guarded = async (run) => {
+        requireHumanSession(config);
+        return run();
+    };
+    return {
+        list(options, call) {
+            return guarded(async () => {
+                const data = await transport.graphql({ api: 'admin', query: APPS_QUERY, variables: { options: options ?? null } }, call);
+                return data.apps;
+            });
+        },
+        get(id, call) {
+            return guarded(async () => {
+                const data = await transport.graphql({ api: 'admin', query: APP_QUERY, variables: { id } }, call);
+                return data.app;
+            });
+        },
+        register(manifest, call) {
+            return guarded(async () => {
+                const data = await transport.graphql({ api: 'admin', query: REGISTER_MUTATION, variables: { manifest } }, call);
+                return data.registerApp;
+            });
+        },
+        update(id, manifest, call) {
+            return guarded(async () => {
+                const data = await transport.graphql({ api: 'admin', query: UPDATE_MUTATION, variables: { id, manifest } }, call);
+                return data.updateApp;
+            });
+        },
+        addKey(input, call) {
+            return guarded(async () => {
+                const data = await transport.graphql({ api: 'admin', query: ADD_KEY_MUTATION, variables: input }, call);
+                return data.addAppKey;
+            });
+        },
+        revokeKey(appId, kid, call) {
+            return guarded(async () => {
+                const data = await transport.graphql({ api: 'admin', query: REVOKE_KEY_MUTATION, variables: { appId, kid } }, call);
+                return data.revokeAppKey;
+            });
+        },
+        suspend(id, call) {
+            return guarded(async () => {
+                const data = await transport.graphql({ api: 'admin', query: SUSPEND_MUTATION, variables: { id } }, call);
+                return data.suspendApp;
+            });
+        },
+        resume(id, call) {
+            return guarded(async () => {
+                const data = await transport.graphql({ api: 'admin', query: RESUME_MUTATION, variables: { id } }, call);
+                return data.resumeApp;
+            });
+        },
+        enableForTenant(appId, channelId, call) {
+            return guarded(async () => {
+                const data = await transport.graphql({ api: 'admin', query: ENABLE_MUTATION, variables: { appId, channelId } }, call);
+                return data.enableAppForTenant;
+            });
+        },
+        disableForTenant(appId, channelId, call) {
+            return guarded(async () => {
+                const data = await transport.graphql({ api: 'admin', query: DISABLE_MUTATION, variables: { appId, channelId } }, call);
+                return data.disableAppForTenant;
+            });
+        },
+    };
+}

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,
@@ -45,9 +48,12 @@ export interface Me {
 }
 /** What `auth.whoami()` reports about the calling credential. */
 export interface WhoAmI {
-    /** `api_token` never discloses the hidden administrator behind the token. */
-    kind: 'api_token' | 'user';
-    /** Present only for a token principal; null for a human session. */
+    /**
+     * A MACHINE principal (`api_token`, `app_installation`) never discloses the
+     * hidden administrator behind it.
+     */
+    kind: 'api_token' | 'user' | 'app_installation';
+    /** Present only for a personal API token; null for every other principal. */
     token: {
         id: string;
         name: string;
@@ -57,7 +63,27 @@ export interface WhoAmI {
         lastUsedAt: string | null;
         scopeKind: string;
     } | null;
-    /** Present only for a human session; null for a token principal. */
+    /** Present only for `kind: 'app_installation'`; null otherwise. */
+    app: {
+        id: string;
+        slug: string;
+        name: string;
+    } | null;
+    /** Present only for `kind: 'app_installation'`; null otherwise. */
+    installation: {
+        id: string;
+        /** `channel` today; `organization` arrives with multi-region. */
+        targetKind: string;
+        targetId: string;
+        /**
+         * `active` | `needs_consent` | `suspended` | `uninstalled`. `needs_consent`
+         * is how an app learns the merchant has to approve declarations it has since
+         * grown — this credential keeps working with the OLD grants meanwhile.
+         */
+        status: string;
+        consentVersion: number;
+    } | null;
+    /** Present only for a human session; null for a machine principal. */
     user: {
         id: string;
         identifier: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sixtyninecommerce/admin",
-  "version": "0.3.1",
+  "version": "0.5.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": {
@@ -33,7 +33,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@sixtyninecommerce/core": "^0.2.3"
+    "@sixtyninecommerce/core": "^0.2.4"
   },
   "devDependencies": {
     "@types/node": "22.19.7",