@sixtyninecommerce/admin 0.4.0 → 0.6.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,13 +1,17 @@
 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 CapabilitiesModule } from './tenant/capabilities.js';
 import { type ChannelsModule } from './tenant/channels.js';
 import { type RetentionModule } from './tenant/retention.js';
 export interface AdminClientConfig {
@@ -33,7 +37,7 @@ export interface AdminClientConfig {
         token: string;
     } | {
         session: SessionConfig;
-    };
+    } | AppAuthConfig;
     tenant?: Partial<TenantContext> & {
         scope?: TenantScope;
     };
@@ -42,9 +46,21 @@ 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: {
@@ -61,13 +77,17 @@ export interface AdminClient {
     };
     /** The calling tenant's own settings. Always the ACTIVE channel — no channel argument. */
     tenant: {
+        capabilities: CapabilitiesModule;
         retention: RetentionModule;
     };
     /**
-     * Human SuperAdmin surface. Every method refuses an API token before the
-     * request leaves the process (`PLATFORM_REQUIRES_SESSION`).
+     * Human SuperAdmin surface. Every method refuses an API token or an app
+     * credential before the request leaves the process
+     * (`PLATFORM_REQUIRES_SESSION`).
      */
-    platform: PlatformModule;
+    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,13 +1,17 @@
 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 { createCapabilitiesModule } from './tenant/capabilities.js';
 import { createChannelsModule } from './tenant/channels.js';
 import { createRetentionModule } from './tenant/retention.js';
 /**
@@ -16,7 +20,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.
@@ -24,9 +31,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',
     });
@@ -140,15 +148,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).
@@ -160,6 +254,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
@@ -191,7 +291,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 } : {}),
@@ -219,6 +324,7 @@ function buildClient(config, overrides, resolver, shared) {
             },
         }),
         apiTokens: createApiTokensModule(transport),
+        apps: createAppsModule(transport),
         audit: createAuditModule(transport),
         channels: createChannelsModule(resolver),
         content: { forms: createFormsModule(transport) },
@@ -226,8 +332,14 @@ function buildClient(config, overrides, resolver, shared) {
         locations: createLocationsModule(transport),
         meta: createMetaModule(transport),
         seo: { redirects: createRedirectsModule(transport) },
-        tenant: { retention: createRetentionModule(transport) },
-        platform: createPlatformModule(transport, config),
+        tenant: {
+            capabilities: createCapabilitiesModule(transport),
+            retention: createRetentionModule(transport),
+        },
+        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
@@ -238,7 +350,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/index.d.ts

@@ -25,19 +25,24 @@ 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 { CapabilitiesModule, Capability, CapabilityManifest, } from './tenant/capabilities.js';
 export type { ChannelsModule } from './tenant/channels.js';
 export type { ChannelRetention, RetentionHold, RetentionModule, SetRetentionInput, } from './tenant/retention.js';
 export type { ApiToken, Call, ChannelInfo, CreateApiTokenInput, ListOptions, Me, TenantContext, TenantScope, UpdateApiTokenInput, WhoAmI, } from './types.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;