@sixtyninecommerce/admin 0.3.1 → 0.5.0

package/dist/apps/index.d.ts

@@ -0,0 +1,106 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+export declare const APP_FIELDS = "\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";
+export declare const INSTALLATION_FIELDS = "\n  id\n  appId\n  targetKind\n  targetId\n  grantedPermissions\n  grantedFieldOwnership\n  locationIds\n  status\n  consentVersion\n  pendingConsentReasons\n  installedAt\n  uninstalledAt\n";
+export declare const AVAILABLE_APPS_QUERY = "\n  query AvailableApps {\n    availableApps { \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  }\n";
+export declare const MY_INSTALLATIONS_QUERY = "\n  query MyInstallations {\n    myInstallations { \n  id\n  appId\n  targetKind\n  targetId\n  grantedPermissions\n  grantedFieldOwnership\n  locationIds\n  status\n  consentVersion\n  pendingConsentReasons\n  installedAt\n  uninstalledAt\n }\n  }\n";
+export declare const INSTALLATION_QUERY = "\n  query AppInstallation($id: ID!) {\n    appInstallation(id: $id) { \n  id\n  appId\n  targetKind\n  targetId\n  grantedPermissions\n  grantedFieldOwnership\n  locationIds\n  status\n  consentVersion\n  pendingConsentReasons\n  installedAt\n  uninstalledAt\n }\n  }\n";
+export declare const INSTALL_MUTATION = "\n  mutation InstallApp($input: InstallAppInput!) {\n    installApp(input: $input) { \n  id\n  appId\n  targetKind\n  targetId\n  grantedPermissions\n  grantedFieldOwnership\n  locationIds\n  status\n  consentVersion\n  pendingConsentReasons\n  installedAt\n  uninstalledAt\n }\n  }\n";
+export declare const APPROVE_MUTATION = "\n  mutation ApproveInstallationConsent($id: ID!, $input: ApproveInstallationConsentInput) {\n    approveInstallationConsent(id: $id, input: $input) { \n  id\n  appId\n  targetKind\n  targetId\n  grantedPermissions\n  grantedFieldOwnership\n  locationIds\n  status\n  consentVersion\n  pendingConsentReasons\n  installedAt\n  uninstalledAt\n }\n  }\n";
+export declare const UNINSTALL_MUTATION = "\n  mutation UninstallApp($id: ID!) {\n    uninstallApp(id: $id) { \n  id\n  appId\n  targetKind\n  targetId\n  grantedPermissions\n  grantedFieldOwnership\n  locationIds\n  status\n  consentVersion\n  pendingConsentReasons\n  installedAt\n  uninstalledAt\n }\n  }\n";
+/** A registered app, as a tenant admin sees it on the consent screen. */
+export interface App {
+    id: string;
+    slug: string;
+    name: string;
+    ownerLabel: string;
+    /** The ceiling on what an installation may be granted. */
+    declaredPermissions: string[];
+    declaredEvents: string[];
+    /** Normalised `"<entity>.<field>"` claims, e.g. `product.price`. */
+    declaredFieldOwnership: string[];
+    /** `none` | `identity` | `full`. */
+    customerData: string;
+    customerDataPurpose: string | null;
+    metafieldDefinitions: unknown[];
+    configSchema: Record<string, unknown> | null;
+    hooks: unknown[];
+    headTemplates: unknown[];
+    sandboxOnly: boolean;
+    /** `active` | `suspended`. */
+    status: string;
+    manifestVersion: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface AppInstallation {
+    id: string;
+    appId: string;
+    /** `channel` today; `organization` arrives with multi-region. */
+    targetKind: string;
+    targetId: string;
+    grantedPermissions: string[];
+    /** Normalised `"<entity>.<field>"` claims, e.g. `product.price`. */
+    grantedFieldOwnership: string[];
+    /** Null means unrestricted. */
+    locationIds: string[] | null;
+    /** `active` | `needs_consent` | `suspended` | `uninstalled`. */
+    status: string;
+    consentVersion: number;
+    /** Why consent is pending, in the approver's words. Null unless `needs_consent`. */
+    pendingConsentReasons: string[] | null;
+    installedAt: string;
+    uninstalledAt: string | null;
+}
+/** What an approver agrees to. Every field omitted means "keep what was granted". */
+export interface ApproveConsentInput {
+    grantedPermissions?: string[];
+    grantedFieldOwnership?: string[];
+    /**
+     * Replace the stock-location restriction. Omit to keep it; pass `null` to LIFT
+     * it entirely — the engine distinguishes the two, so a plain `string[]` would
+     * leave a tenant who restricted an app to one warehouse no way back short of
+     * uninstalling it.
+     */
+    locationIds?: string[] | null;
+}
+export interface InstallAppInput {
+    appId: string;
+    /** Must be a subset of the app's `declaredPermissions`, and of the caller's own. */
+    grantedPermissions?: string[];
+    grantedFieldOwnership?: string[];
+    /** Restrict the installation to these stock locations. Omit for unrestricted. */
+    locationIds?: string[];
+}
+/**
+ * Installing and managing apps on the caller's OWN store (headless spec §6.3).
+ *
+ * Needs `InstallApps` and a tenant context. Every method acts on the active
+ * channel — there is no channel parameter, because a channel-id input would have
+ * to be permission-checked against a store the caller may not belong to, and the
+ * engine refuses that shape for the same reason it does on API tokens.
+ *
+ * The REGISTRY side (registering apps, keys, suspension, enabling an app for a
+ * tenant) lives under `admin.platform.apps` and needs a human SuperAdmin session.
+ */
+export interface AppsModule {
+    /** Apps a platform operator has enabled for this store and that are not suspended. */
+    list(options?: Call): Promise<App[]>;
+    /** Consent to a subset of an app's declarations and install it. */
+    install(input: InstallAppInput, options?: Call): Promise<AppInstallation>;
+    /** This store's installations, newest first. */
+    installations(options?: Call): Promise<AppInstallation[]>;
+    installation(id: string, options?: Call): Promise<AppInstallation | null>;
+    /**
+     * Approve declarations that grew, granting what you name.
+     *
+     * Growth is granted only by naming it — omit `grants` and the installation
+     * keeps exactly what it had, which is the right default for an app that grew
+     * an event type or a metafield. Tokens already minted keep the OLD grants
+     * until this lands.
+     */
+    approveConsent(id: string, grants?: ApproveConsentInput, options?: Call): Promise<AppInstallation>;
+    /** Revoke every token and end the grant. The row is kept as provenance. */
+    uninstall(id: string, options?: Call): Promise<AppInstallation>;
+}
+export declare function createAppsModule(transport: Transport): AppsModule;

package/dist/apps/index.js

@@ -0,0 +1,92 @@
+export const APP_FIELDS = /* GraphQL */ `
+  id
+  slug
+  name
+  ownerLabel
+  declaredPermissions
+  declaredEvents
+  declaredFieldOwnership
+  customerData
+  customerDataPurpose
+  metafieldDefinitions
+  configSchema
+  hooks
+  headTemplates
+  sandboxOnly
+  status
+  manifestVersion
+  createdAt
+  updatedAt
+`;
+export const INSTALLATION_FIELDS = /* GraphQL */ `
+  id
+  appId
+  targetKind
+  targetId
+  grantedPermissions
+  grantedFieldOwnership
+  locationIds
+  status
+  consentVersion
+  pendingConsentReasons
+  installedAt
+  uninstalledAt
+`;
+export const AVAILABLE_APPS_QUERY = /* GraphQL */ `
+  query AvailableApps {
+    availableApps { ${APP_FIELDS} }
+  }
+`;
+export const MY_INSTALLATIONS_QUERY = /* GraphQL */ `
+  query MyInstallations {
+    myInstallations { ${INSTALLATION_FIELDS} }
+  }
+`;
+export const INSTALLATION_QUERY = /* GraphQL */ `
+  query AppInstallation($id: ID!) {
+    appInstallation(id: $id) { ${INSTALLATION_FIELDS} }
+  }
+`;
+export const INSTALL_MUTATION = /* GraphQL */ `
+  mutation InstallApp($input: InstallAppInput!) {
+    installApp(input: $input) { ${INSTALLATION_FIELDS} }
+  }
+`;
+export const APPROVE_MUTATION = /* GraphQL */ `
+  mutation ApproveInstallationConsent($id: ID!, $input: ApproveInstallationConsentInput) {
+    approveInstallationConsent(id: $id, input: $input) { ${INSTALLATION_FIELDS} }
+  }
+`;
+export const UNINSTALL_MUTATION = /* GraphQL */ `
+  mutation UninstallApp($id: ID!) {
+    uninstallApp(id: $id) { ${INSTALLATION_FIELDS} }
+  }
+`;
+export function createAppsModule(transport) {
+    return {
+        async list(options) {
+            const data = await transport.graphql({ api: 'admin', query: AVAILABLE_APPS_QUERY }, options);
+            return data.availableApps;
+        },
+        async install(input, options) {
+            const data = await transport.graphql({ api: 'admin', query: INSTALL_MUTATION, variables: { input } }, options);
+            return data.installApp;
+        },
+        async installations(options) {
+            const data = await transport.graphql({ api: 'admin', query: MY_INSTALLATIONS_QUERY }, options);
+            return data.myInstallations;
+        },
+        async installation(id, options) {
+            const data = await transport.graphql({ api: 'admin', query: INSTALLATION_QUERY, variables: { id } }, options);
+            return data.appInstallation;
+        },
+        async approveConsent(id, grants, options) {
+            const data = await transport.graphql({ api: 'admin', query: APPROVE_MUTATION, variables: { id, input: grants ?? null } }, options);
+            return data.approveInstallationConsent;
+        },
+        async uninstall(id, options) {
+            const data = await transport.graphql({ api: 'admin', query: UNINSTALL_MUTATION, variables: { id } }, options);
+            return data.uninstallApp;
+        },
+    };
+}

package/dist/client.d.ts

@@ -1,10 +1,15 @@
 import { type DeprecationNotice, type RateLimitInfo, type RetryPolicy, type TenantContext, type TenantScope } from '@sixtyninecommerce/core';
 import { type ApiTokensModule } from './api-tokens/index.js';
+import { type AppCredentialConfig } from './apps/credential.js';
+import { type AppsModule } from './apps/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 PlatformAppsModule } from './platform/apps.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';
@@ -31,7 +36,7 @@ export interface AdminClientConfig {
         token: string;
     } | {
         session: SessionConfig;
-    };
+    } | AppAuthConfig;
     tenant?: Partial<TenantContext> & {
         scope?: TenantScope;
     };
@@ -40,14 +45,28 @@ export interface AdminClientConfig {
     timeoutMs?: number;
     onDeprecation?: (notice: DeprecationNotice) => void;
 }
+/**
+ * An APP's own credential (headless spec §6.3). The SDK signs an assertion with
+ * the app's private key, exchanges it for an `s69i_` bearer, and refreshes that
+ * bearer a minute before it expires — an app never handles the token itself.
+ */
+export interface AppAuthConfig {
+    app: AppCredentialConfig;
+    /** The installation this credential acts as, from `admin.apps.install(...)`. */
+    installationId: string;
+}
 export interface AdminClient {
     auth: AuthModule;
     apiTokens: ApiTokensModule;
+    /** Installing and managing apps on the ACTIVE store. Needs `InstallApps`. */
+    apps: AppsModule;
     audit: AuditModule;
     channels: ChannelsModule;
     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 +78,14 @@ 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 or an app
+     * credential before the request leaves the process
+     * (`PLATFORM_REQUIRES_SESSION`).
+     */
+    platform: PlatformModule & {
+        apps: PlatformAppsModule;
+    };
     /** A derived client on another tenant, sharing this one's principal. */
     withTenant(tenant: Partial<TenantContext> & {
         scope?: TenantScope;

package/dist/client.js

@@ -1,10 +1,15 @@
 import { createChannelResolver, createTransport, mergeTenant, UNSCOPED_TENANT, ValidationError, } from '@sixtyninecommerce/core';
 import { createApiTokensModule } from './api-tokens/index.js';
+import { createAppCredential, } from './apps/credential.js';
+import { createAppsModule } from './apps/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 { createPlatformAppsModule } from './platform/apps.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';
@@ -14,7 +19,10 @@ import { createRetentionModule } from './tenant/retention.js';
  * the dashboard is — so the refusal is specifically about a long-lived token.
  */
 function assertNotInBrowser(auth) {
-    if (!('token' in auth))
+    // An app's PRIVATE KEY is the strongest credential this SDK accepts — it mints
+    // tokens rather than being one — so it is refused in a browser exactly as a
+    // long-lived token is, and for the same reason.
+    if (!('token' in auth) && !('app' in auth))
         return;
     // Indexed off a typed view of globalThis: this package compiles without the
     // DOM lib on purpose, so that a stray `document.` reference cannot slip in.
@@ -22,9 +30,10 @@ function assertNotInBrowser(auth) {
     const inBrowser = runtime.window !== undefined && runtime.document !== undefined;
     if (!inBrowser)
         return;
+    const credential = 'app' in auth ? "An app's private key" : 'An API token';
     throw new ValidationError({
         code: 'CREDENTIAL_IN_BROWSER',
-        message: 'An API token must never be constructed in a browser — it would ship the credential to every visitor. Use a session bearer in the browser and keep tokens server-side.',
+        message: `${credential} must never be constructed in a browser — it would ship the credential to every visitor. Use a session bearer in the browser and keep machine credentials server-side.`,
         status: 400,
         service: 'vendure',
     });
@@ -138,15 +147,101 @@ export function createAdminClient(config) {
     });
     if ('session' in config.auth)
         assertSessionIsWritable(config.auth.session);
+    else if ('app' in config.auth)
+        assertAppCredentialIsPresent(config.auth);
     else
         assertTokenIsPresent(config.auth);
     // Shared by every client `withTenant` derives, because the session store is.
     // `rotations` lets `login()` tell a bearer THIS sign-in produced apart from
     // one that merely sits in the slot already.
     const shared = { rotations: 0 };
-    return buildClient(config, config.tenant, resolver, shared);
+    // One credential per CLIENT, shared with everything `withTenant` derives:
+    // the token is minted for an installation, and an installation is one app on
+    // one store — deriving a tenant does not change which credential it is.
+    const credential = 'app' in config.auth ? appCredentialFor(config, config.auth) : undefined;
+    return buildClient(config, config.tenant, resolver, shared, credential);
 }
-function buildClient(config, overrides, resolver, shared) {
+/**
+ * Nothing about an app credential is readable live (unlike `auth.token`, which
+ * may be a getter over a secret store), so every field is checked at
+ * construction rather than on the call that would have used it.
+ */
+function assertAppCredentialIsPresent(auth) {
+    const missing = [
+        isPresent(auth.app?.appId) ? null : 'app.appId',
+        isPresent(auth.app?.kid) ? null : 'app.kid',
+        auth.app?.privateKey ? null : 'app.privateKey',
+        isPresent(auth.installationId) ? null : 'installationId',
+    ].filter((field) => field !== null);
+    if (missing.length === 0)
+        return;
+    throw new ValidationError({
+        code: 'APP_CREDENTIAL_INCOMPLETE',
+        message: `An app credential needs ${missing.join(', ')}. Without them no assertion can be signed and every call would go out unauthenticated.`,
+        status: 400,
+        service: 'vendure',
+    });
+}
+function appCredentialFor(config, auth) {
+    // The exchange is fetched DIRECTLY, never through the wrapper below: that
+    // wrapper asks this credential for a bearer, so routing the mint through it
+    // would recurse forever on the very first call.
+    const baseFetch = config.fetch ?? globalThis.fetch;
+    return createAppCredential(auth.app, auth.installationId, config.urls.vendureUrl, baseFetch);
+}
+/**
+ * Every request an app makes goes out with a LIVE bearer.
+ *
+ * Done in `fetch` rather than in `principal` because minting is asynchronous and
+ * `principal` is not: a synchronous getter cannot wait for an exchange. The
+ * header the transport built is overwritten here, which is also what makes the
+ * first call work — at that point nothing has been minted and `peek()` is empty.
+ */
+function appFetch(credential, base) {
+    const send = async (input, init, bearer) => {
+        const headers = { ...(init?.headers ?? {}) };
+        headers.Authorization = `Bearer ${bearer}`;
+        return base(input, { ...init, headers });
+    };
+    return async (input, init) => {
+        // No try/catch: a credential failure must reach the caller AS ITSELF, and it
+        // already does. `createTransport`'s `send()` opens its catch with
+        // `if (error instanceof PlatformError) throw error`, so the refusal the
+        // exchange returned — built by `errorFromResponse`, carrying the server's
+        // own `trace_id` — passes through untouched. Catching it here to re-emit a
+        // synthesized problem+json would only lose that trace id and turn a
+        // status-0 transport failure into a 503.
+        const bearer = await credential.current();
+        const response = await send(input, init, bearer);
+        // A 401 on a token this SDK believes is live means the SERVER killed it —
+        // an app suspended and resumed, a key revoked, a tenant re-consenting — and
+        // the cached bearer can be up to an hour from its natural expiry. Without
+        // this the app is simply down for that hour: `PermissionDeniedError` is not
+        // retryable, and nothing else ever calls `invalidate()`. Exactly ONE retry,
+        // and only when a fresh bearer actually differs, so a genuinely
+        // unauthorised call cannot become an exchange loop.
+        if (response.status !== 401)
+            return response;
+        // The 401 body is read and discarded: an unread body holds its socket out of
+        // the keep-alive pool, and this one is replaced by the retry's.
+        void response
+            .clone()
+            .text()
+            .catch(() => undefined);
+        // `refresh`, not invalidate-then-current: it returns a bearer a sibling has
+        // already minted, and joins a refresh already running for this same dead
+        // one, so a burst of concurrent 401s costs ONE exchange rather than one per
+        // request.
+        const fresh = await credential.refresh(bearer);
+        // Compared against the bearer THIS request used: an identical token back
+        // from the exchange (a caching proxy in front of it) must end here rather
+        // than retry forever.
+        if (fresh === bearer)
+            return response;
+        return send(input, init, fresh);
+    };
+}
+function buildClient(config, overrides, resolver, shared, credential) {
     // No scope configured leaves the client on UNSCOPED_TENANT, which only the
     // auth documents may use; the transport refuses everything else with
     // TENANT_REQUIRED (spec §15.2).
@@ -158,6 +253,12 @@ function buildClient(config, overrides, resolver, shared) {
         channels: resolver,
         tenant,
         principal: () => {
+            // The bearer the LAST mint produced, which `appFetch` overwrites with a
+            // live one before the request leaves. Empty on the very first call, and
+            // deliberately not refused for it: an app credential is complete or it
+            // was rejected at construction.
+            if (credential)
+                return { kind: 'bearer', token: credential.peek() };
             if (!store) {
                 // Read live, so a getter over a request context follows the request
                 // being served — and refuse an empty one HERE rather than sending an
@@ -189,7 +290,12 @@ function buildClient(config, overrides, resolver, shared) {
                 },
             };
         },
-        ...(config.fetch ? { fetch: config.fetch } : {}),
+        // Every app request carries a freshly minted bearer; see `appFetch`.
+        ...(credential
+            ? { fetch: appFetch(credential, config.fetch ?? globalThis.fetch) }
+            : config.fetch
+                ? { fetch: config.fetch }
+                : {}),
         ...(config.retry ? { retry: config.retry } : {}),
         ...(config.timeoutMs === undefined ? {} : { timeoutMs: config.timeoutMs }),
         ...(config.onDeprecation ? { onDeprecation: config.onDeprecation } : {}),
@@ -217,14 +323,19 @@ function buildClient(config, overrides, resolver, shared) {
             },
         }),
         apiTokens: createApiTokensModule(transport),
+        apps: createAppsModule(transport),
         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),
+            apps: createPlatformAppsModule(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
@@ -235,7 +346,7 @@ function buildClient(config, overrides, resolver, shared) {
             // Resolver and rotation count are shared, and the session store IS the
             // caller's object — so a derived client reuses the channel cache and the
             // bearer this one signed in with, in both directions and in either order.
-            return buildClient(config, mergeTenant(tenant, next), resolver, shared);
+            return buildClient(config, mergeTenant(tenant, next), resolver, shared, credential);
         },
         get rateLimit() {
             return transport.rateLimit;

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;
+        },
+    };
+}