@sixtyninecommerce/admin 0.4.0 → 0.6.0

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/tenant/capabilities.d.ts

@@ -0,0 +1,104 @@
+import { type Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/** One capability's state on the calling tenant's channel. */
+export interface Capability {
+    /**
+     * The underlying objects exist here. For a feature a merchant switches on —
+     * quotes, returns, reviews, the age gate, subscription plans, B2B price
+     * lists — that means SWITCHED ON, not "supported by the platform".
+     */
+    provisioned: boolean;
+    /** No hard blocker in the configuration. A degradation leaves this true. */
+    configured: boolean;
+    /**
+     * The tenant holds this plugin's entitlement.
+     *
+     * FALSE ON EVERY CORE CAPABILITY, and that is not a bug: the entitlement
+     * registry has rows only for the entitlement-gated plugins of the catalogue,
+     * and `catalog`, `search`, `routes` and the rest are the platform itself.
+     * Branch on {@link ready}, never on this alone.
+     */
+    entitled: boolean;
+    /** The answer to "may I use this": provisioned, configured, and licensed. */
+    ready: boolean;
+    /** Capability keys this one needs first — what to fix when it is not ready. */
+    dependsOn: string[];
+    /**
+     * The server's evidence for anything short of a clean pass, in the words the
+     * platform's own readiness preflight uses ("search returned 0 hits — reindex
+     * Meilisearch for this channel"). Never a UI flag, and never a sentence this
+     * SDK composed.
+     *
+     * NON-EMPTY WITH `ready: true` MEANS DEGRADED, not broken — a storefront that
+     * renders anyway is correct, and a merchant still wants to see it. A feature
+     * deliberately switched off carries no blocker at all: nothing is wrong.
+     */
+    blockers: string[];
+    /** A field added after this SDK release arrives camelised and untouched. */
+    [extra: string]: unknown;
+}
+/**
+ * What the tenant's channel can do, per capability key.
+ *
+ * KEYS ARE DATA. `content_pages`, `age_gate`, `b2b_pricing`, `payment-links`
+ * are identifiers the platform matches literally, so they reach you in their
+ * wire spelling and are never camelised — the same rule the meta catalogue's
+ * data-keyed maps follow. The FIELDS inside each entry are camelised.
+ *
+ * Core keys: `catalog`, `search`, `routes`, `menus`, `content_pages`,
+ * `checkout`, `branding`, `age_gate`, `reviews`, `subscriptions`,
+ * `b2b_pricing`, `quotes`, `returns`. Beside them, one key per
+ * entitlement-gated plugin in the platform catalogue (`mollie`, `stripe`,
+ * `myparcel`, `hendriks`, `afas`, `pos`, …).
+ *
+ * THE SET GROWS, so read an absent key as UNKNOWN and never as `false`. A
+ * capability whose rules are not yet settled is held back rather than published
+ * wrong, and `b2b_pricing` — which shipped one release later than the rest, for
+ * exactly that reason — is the precedent rather than the exception.
+ */
+export interface CapabilityManifest {
+    channelId: string;
+    channelCode: string;
+    /** ISO-8601 with an offset — when the probes ran, not when this was served. */
+    generatedAt: string;
+    capabilities: Record<string, Capability>;
+    /**
+     * The tenant's installed apps. Always empty until the app registry ships, so
+     * there is no element shape yet — declaring one here would pin a contract the
+     * apps work has not written.
+     */
+    installedApps: never[];
+    /** A member added after this SDK release arrives camelised and untouched. */
+    [extra: string]: unknown;
+}
+/**
+ * `admin.tenant.capabilities()` — what this tenant's channel can actually do.
+ *
+ * One read replaces a dozen probes: whether the catalogue has products, whether
+ * search is indexed, whether checkout has an enabled method on both sides,
+ * which integrations are licensed AND connected, and for anything less than
+ * ready, the server's own evidence.
+ *
+ * Reading needs any permission on the channel — an admin credential always has
+ * one. It is cached 60 s per channel by the service, so polling it costs
+ * nothing; {@link CapabilitiesModule.refresh} is the escape when you have just
+ * changed something and want to see it.
+ */
+export interface CapabilitiesModule {
+    (options?: Call): Promise<CapabilityManifest>;
+    /**
+     * Rebuild the manifest now, ignoring the service's freshness window.
+     *
+     * Needs `UpdateSettings`: it makes the server re-probe three services, so it
+     * is not something a read-only credential may trigger at will.
+     */
+    refresh(options?: Call): Promise<CapabilityManifest>;
+}
+/**
+ * Camelise each capability entry's OWN fields (`depends_on` → `dependsOn`) and
+ * leave the map's keys alone. A field this release has never seen is renamed
+ * and passed through, which is the half that matters — nothing else would
+ * protect it.
+ */
+export declare function projectManifest(body: unknown): CapabilityManifest;
+export declare function createCapabilitiesModule(transport: Transport): CapabilitiesModule;

package/dist/tenant/capabilities.js

@@ -0,0 +1,59 @@
+import { PermissionDeniedError } from '@sixtyninecommerce/core';
+/**
+ * The `capabilities` MAP is handed back verbatim by the transport, because its
+ * keys are capability identifiers rather than structure. Camelising them would
+ * be invisible damage: `content_pages` would simply read back as `contentPages`
+ * and match no key the platform has ever published.
+ */
+const PRESERVE_CAPABILITIES = new Set(['capabilities']);
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function snakeToCamel(key) {
+    return key.replace(/_+([a-z0-9])/g, (_match, char) => char.toUpperCase());
+}
+/**
+ * Camelise each capability entry's OWN fields (`depends_on` → `dependsOn`) and
+ * leave the map's keys alone. A field this release has never seen is renamed
+ * and passed through, which is the half that matters — nothing else would
+ * protect it.
+ */
+export function projectManifest(body) {
+    if (!isRecord(body) || !isRecord(body.capabilities)) {
+        // The transport has already turned a non-2xx into a PlatformError, so
+        // anything else here is a service answering 200 with a body this module
+        // cannot read — worth saying plainly rather than crashing two frames later.
+        throw new TypeError('GET /capabilities did not answer with a capability manifest');
+    }
+    const capabilities = {};
+    for (const [key, state] of Object.entries(body.capabilities)) {
+        if (!isRecord(state))
+            continue;
+        if (!('provisioned' in state)) {
+            // The public projection: `{ ready }` and nothing else. The service serves
+            // it to a principal it did not accept for this channel, and the status is
+            // 200, so nothing else in the hierarchy would tell the caller that their
+            // credential — not their request — is the problem.
+            throw new PermissionDeniedError({
+                code: 'CAPABILITIES_PROJECTION_UNAVAILABLE',
+                message: 'The service returned the anonymous capability projection, so this credential was not accepted for the channel — it is invalid or expired, or its principal holds no permission there. Only `ready` would be available.',
+                status: 403,
+                service: 'plugins',
+            });
+        }
+        const projected = {};
+        for (const [field, value] of Object.entries(state))
+            projected[snakeToCamel(field)] = value;
+        capabilities[key] = projected;
+    }
+    return { ...body, capabilities };
+}
+export function createCapabilitiesModule(transport) {
+    const read = async (options) => projectManifest(await transport.rest('plugins', { method: 'GET', path: '/capabilities' }, { ...options, preserveKeys: PRESERVE_CAPABILITIES }));
+    // A callable module: `capabilities()` is the read a consumer makes constantly
+    // and `capabilities.refresh()` the one they make rarely, so the common case
+    // stays the shortest thing to write (spec §6.6 names it exactly this way).
+    const capabilities = ((options) => read(options));
+    capabilities.refresh = async (options) => projectManifest(await transport.rest('plugins', { method: 'POST', path: '/capabilities/refresh' }, { ...options, preserveKeys: PRESERVE_CAPABILITIES }));
+    return capabilities;
+}

package/dist/types.d.ts

@@ -48,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;
@@ -60,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.4.0",
+  "version": "0.6.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.3.0"
   },
   "devDependencies": {
     "@types/node": "22.19.7",