@sixtyninecommerce/admin 0.5.0 → 0.6.0

package/README.md

@@ -388,6 +388,71 @@ had before the registry.
 Read with `ReadSettings` and written with `UpdateSettings` — the same grants that govern
 `storefrontUrl` itself. A head an app installed (`installationId` set) is managed through that app's
 declarations and is refused here with `HEAD_APP_OWNED`.
+### Capabilities
+
+`admin.tenant.capabilities()` answers what this tenant's channel can actually do — one read instead
+of a dozen probes, and the read a head should make before it decides what to render.
+
+```ts
+const manifest = await admin.tenant.capabilities();
+
+manifest.capabilities.catalog.ready;          // false on a catalog-less tenant — render no product routes
+manifest.capabilities.search.blockers;        // ['search returned 0 hits — reindex Meilisearch for this channel']
+manifest.capabilities.age_gate.ready;         // true only when the channel has a minimum age set
+manifest.capabilities.mollie?.entitled;       // is the integration licensed to this tenant
+manifest.capabilities.mollie.ready;           // …and actually connected and enabled
+manifest.capabilities.checkout.dependsOn;     // ['catalog']
+
+await admin.tenant.capabilities.refresh();    // needs UpdateSettings; skips the freshness window
+```
+
+Four fields per key, and they answer different questions:
+
+| Field | Question |
+|---|---|
+| `provisioned` | does the thing exist here — and for a merchant switch (quotes, returns, reviews, the age gate, subscription plans, B2B price lists) that means **switched on** |
+| `configured` | did the probe find no hard blocker |
+| `entitled` | does the tenant hold this plugin's entitlement |
+| `ready` | `provisioned && configured && (entitled || the key is core)` — the one to branch on |
+
+`entitled` is `false` on every CORE capability and that is not a bug: the entitlement registry has
+rows only for the catalogue's gated plugins, and `catalog`, `search`, `routes` and the rest are the
+platform itself. `ready` is what excuses them.
+
+`blockers` are the platform's own readiness evidence, in the words its preflight uses — never a
+sentence this SDK composed, and never a UI flag. **Non-empty with `ready: true` means degraded, not
+broken**: a storefront that renders anyway is correct, and a merchant still wants to see the line.
+A feature deliberately left off carries no blocker at all — nothing is wrong with it.
+
+A blocker that opens with **`not established`** is different from both: it means a dependency would
+not answer, so the server could not read that capability's state at all. Treat it as unknown rather
+than as off — and note that such a manifest is served with a much shorter `Cache-Control` window,
+so asking again shortly is worth doing.
+
+**Capability keys are data, so they keep their wire spelling** — `content_pages`, `age_gate`,
+`b2b_pricing`, `payment-links` — exactly like the meta catalogue's data-keyed maps. The fields
+*inside* each entry are camelised (`depends_on` → `dependsOn`). Core keys are `catalog`, `search`,
+`routes`, `menus`, `content_pages`, `checkout`, `branding`, `age_gate`, `reviews`, `subscriptions`,
+`b2b_pricing`, `quotes` and `returns`; beside them there is one key per entitlement-gated plugin in
+the platform catalogue. **Treat an absent key as unknown, never as `false`** — the set grows, and a
+key whose rules are not settled is held back rather than published wrong. A plugin with no cheap server-side configuration read says so in `blockers`
+and stays `ready: false` — for those, `entitled` is the only authoritative field.
+
+`b2b_pricing` answers whether the tenant does trade pricing, and it is decided by ONE thing: the
+channel's trade customer groups. That is the registry the engine itself acts on — `checkIsB2BCustomer`,
+B2B tax display, quote eligibility and credit all resolve through it, and with no trade groups
+configured it returns false for every customer, so nothing trade can execute. Neither the quotes
+switch nor the price lists an anonymous caller can see change the answer: the switch is inert
+without trade groups, and that price-list query returns only applies-to-everyone lists, which an
+ordinary retail sale also uses. Both are reported as evidence on a channel already known to be B2B.
+So this key is worth reading with its `blockers`: `ready: true` with a blocker means the tenant IS a
+B2B channel and one piece of evidence was unreadable, and a `not established` blocker means the
+platform declined to guess. `ready: false` with an empty `blockers` means the channel has no trade
+groups — note that this reads the same whether or not the quotes switch is on, so the manifest does
+not currently distinguish a plain retail channel from one where quoting is enabled but inert.
+
+The service caches the manifest 60 s per channel and serves it with an `ETag`, so polling it is
+cheap. `installedApps` is on the wire already and stays empty until the app registry ships.
 
 ### Errors
 

package/dist/client.d.ts

@@ -11,6 +11,7 @@ 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 {
@@ -76,6 +77,7 @@ export interface AdminClient {
     };
     /** The calling tenant's own settings. Always the ACTIVE channel — no channel argument. */
     tenant: {
+        capabilities: CapabilitiesModule;
         retention: RetentionModule;
     };
     /**

package/dist/client.js

@@ -11,6 +11,7 @@ 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';
 /**
@@ -331,7 +332,10 @@ function buildClient(config, overrides, resolver, shared, credential) {
         locations: createLocationsModule(transport),
         meta: createMetaModule(transport),
         seo: { redirects: createRedirectsModule(transport) },
-        tenant: { retention: createRetentionModule(transport) },
+        tenant: {
+            capabilities: createCapabilitiesModule(transport),
+            retention: createRetentionModule(transport),
+        },
         platform: {
             ...createPlatformModule(transport, config),
             apps: createPlatformAppsModule(transport, config),

package/dist/index.d.ts

@@ -42,6 +42,7 @@ 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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sixtyninecommerce/admin",
-  "version": "0.5.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.4"
+    "@sixtyninecommerce/core": "^0.3.0"
   },
   "devDependencies": {
     "@types/node": "22.19.7",