@sixtyninecommerce/admin 0.5.0 → 0.7.0

package/dist/tenant/capabilities.d.ts

@@ -0,0 +1,119 @@
+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[];
+    /**
+     * The `aud` an app assertion must carry to be exchanged at this deployment —
+     * its public Vendure origin. Copy it VERBATIM into the claim; re-deriving it
+     * from a URL you hold is the drift the platform compares against as a plain
+     * string. `createAppCredential` already does this for you, so this member is
+     * for a caller signing assertions by hand.
+     *
+     * Camelised from the wire's `assertion_audience`, like every other member
+     * here. `null` means the plugins service cannot state one — which does NOT
+     * mean the exchange accepts an assertion without `aud`, since the two run as
+     * separate deployment resources; ask the operator rather than omitting it.
+     *
+     * Optional because a platform older than this field simply does not send it.
+     */
+    assertionAudience?: string | null;
+    /** 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

@@ -2,9 +2,26 @@ import type { ChannelInfo, TenantContext, TenantScope } from '@sixtyninecommerce
 /** Per-call options every admin method accepts (spec §9.2). */
 export interface Call {
     /**
-     * Sent as `Idempotency-Key` on a REST write, and ignored on a GraphQL one —
-     * the Admin API has no header for it, so an `apiTokens.*` write is never
-     * deduplicated and a repeat is a second write.
+     * Sent as `Idempotency-Key` on a REST write. On a GraphQL one it is sent as
+     * an ARGUMENT — the Admin API has no header for it — and only the mutations
+     * that declare one act on it. Today those are the money mutations
+     * `payments.record`, `orders.park`, `orders.settle` and all three
+     * `orders.surcharges.*`, plus `payments.providers.completeOnboarding` and
+     * `payments.providers.terminals.provision`. Repeating one under the same key
+     * returns the first call's result instead of moving the money again; a
+     * DIFFERENT request under the same key is refused with
+     * `IDEMPOTENCY_CONFLICT`.
+     *
+     * Two deliberate exceptions on that list. `customers.erase` takes a key but
+     * RECORDS it for provenance rather than keying on it: that mutation is
+     * idempotent on the customer itself, which is the stronger key. And
+     * `payments.providers.startOnboarding` takes none at all, because its
+     * response carries a link that can be single-use and a stored response is
+     * re-served for 24 hours.
+     *
+     * Everything else — `apiTokens.*` and the rest of the GraphQL surface —
+     * still sends the key and acts on nothing, so a repeat there is a second
+     * write.
      *
      * On REST, three of this SDK's writes are deduplicated by the service itself:
      * `content.forms.upsertBySlug` (`PUT /forms/by-slug/:slug`),

package/dist/uploads/index.d.ts

@@ -0,0 +1,146 @@
+import { type Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/**
+ * What an upload is for. It decides which permission stages it and who may
+ * consume it.
+ *
+ * `asset` is the only purpose today. `bulk` and `document` arrive with the
+ * calls that consume them, each with its own storage decision — everything
+ * staged currently lands in the public asset bucket, which is right for a media
+ * asset and not for a customer export or an order attachment.
+ */
+export type UploadPurpose = 'asset';
+export type UploadStatus = 'staged' | 'consumed' | 'expired';
+export interface StagedUpload {
+    id: string;
+    purpose: UploadPurpose;
+    status: UploadStatus;
+    mimeType: string;
+    /**
+     * The EXACT size the signature was computed for, as a string.
+     *
+     * A string because it is a 64-bit column and a JSON number is a double; use
+     * `Number(...)` if you need arithmetic, which is exact below 2^53.
+     */
+    sizeBytes: string;
+    /** The label you gave the file. It is never part of the object's location. */
+    filename: string | null;
+    /** When the RESERVATION lapses. After this nothing will accept the upload. */
+    expiresAt: string;
+    consumedAt: string | null;
+    createdAt: string;
+}
+export interface StagedUploadTicket extends StagedUpload {
+    /** PUT the bytes here. Single use. */
+    url: string;
+    method: 'PUT';
+    /**
+     * Send ALL of these, spelled exactly like this. They are part of the
+     * signature, so storage refuses a PUT that omits or changes one.
+     */
+    headers: Record<string, string>;
+    /**
+     * When the URL stops working — at most {@link StagedUpload.expiresAt}, and
+     * less than it when you re-staged an upload that was already running down.
+     */
+    urlExpiresAt: string;
+}
+export interface StageUploadInput {
+    purpose: UploadPurpose;
+    /** Checked against the platform allow-list and bound into the signature. */
+    mimeType: string;
+    /**
+     * The EXACT number of bytes you will send — not a maximum.
+     *
+     * A presigned PUT can only pin a precise `Content-Length`; there is no way to
+     * sign an upper bound. Storage refuses any other length, so this must be the
+     * real size of the body (`blob.size`, `buffer.length`, `stat.size`).
+     */
+    size: number;
+    /**
+     * Your own handle for this upload, making the call repeatable.
+     *
+     * Required. Staging is the call that hands out a URL, and a dropped response
+     * on it is the ordinary failure: without a token every retry would reserve
+     * another place and leave an object nobody ever claims. Staging twice with
+     * the same token returns the SAME upload; staging DIFFERENT terms under it is
+     * refused with `UPLOAD_TOKEN_CONFLICT`.
+     */
+    clientToken: string;
+    /** A label for humans. It never reaches the object's location. */
+    filename?: string;
+}
+/**
+ * Bytes this SDK knows how to PUT. A `Blob` in any modern runtime, or a
+ * `Uint8Array`/`ArrayBuffer` from Node.
+ */
+export type UploadBody = Blob | ArrayBuffer | ArrayBufferView;
+export interface ClaimAsAssetInput {
+    /** Place the asset in this CMS asset folder. */
+    folderId?: string;
+    altText?: string;
+}
+/**
+ * Signed direct-to-storage uploads (spec §6.11).
+ *
+ * **The shape of it.** You say what you are uploading; the platform decides
+ * WHERE it goes and signs exactly that. You never see or choose a path. The
+ * three steps are `stage` (reserve and get a URL), `put` (send the bytes
+ * straight to storage — they do not pass through the platform), and a consuming
+ * call that takes the upload's id.
+ *
+ * ```ts
+ * const bytes = await readFile('hero.png');
+ * const ticket = await admin.uploads.stage({
+ *   purpose: 'asset',
+ *   mimeType: 'image/png',
+ *   size: bytes.length,
+ *   clientToken: crypto.randomUUID(),
+ *   filename: 'hero.png',
+ * });
+ * await admin.uploads.put(ticket, bytes);
+ * const asset = await admin.uploads.claimAsAsset(ticket.id, { altText: 'Our hero' });
+ * ```
+ *
+ * **The size is exact.** `size` is the byte count storage will accept and no
+ * other — not a ceiling. Sending a different number of bytes fails at storage
+ * with a signature error, so compute it from the body you are about to send.
+ *
+ * **One use, and a window scaled to the size.** A URL writes one object, once.
+ * The reservation lasts at least fifteen minutes, and longer for a large file —
+ * enough to send it at about 1 Mbit/s — because a window too short to upload in
+ * would expire between the PUT and the claim. `expiresAt` is the reservation;
+ * `urlExpiresAt` is the signature, and never outlives it. An upload nobody
+ * consumes expires and its bytes are deleted.
+ *
+ * **It is yours alone.** An upload is visible and usable only to the principal
+ * that staged it, on the store it was staged for. Anything else answers
+ * `UPLOAD_NOT_FOUND` — the same answer as an id that never existed.
+ *
+ * **Browsers need CORS.** `put` sends a cross-origin PUT to the object store,
+ * which requires CORS rules on the bucket that this platform does not
+ * configure. Server-side callers are unaffected.
+ */
+export interface UploadsModule {
+    /** Reserve a place and get a signed URL to PUT one file to. */
+    stage(input: StageUploadInput, options?: Call): Promise<StagedUploadTicket>;
+    /**
+     * Send the bytes to storage using the ticket's URL and headers.
+     *
+     * It does NOT go through the platform and carries none of your credentials —
+     * the URL is the authorisation. Resolves on a 2xx and throws the store's
+     * status otherwise.
+     */
+    put(ticket: StagedUploadTicket, body: UploadBody): Promise<void>;
+    /** One upload's state. Unknown, or another principal's, is `UPLOAD_NOT_FOUND`. */
+    get(id: string, options?: Call): Promise<StagedUpload>;
+    /**
+     * Turn a staged upload into a CMS asset.
+     *
+     * This is the consuming call: it verifies the object is there and is what was
+     * signed, spends the upload, and ingests the bytes. An upload can be consumed
+     * once — a second call is `UPLOAD_ALREADY_CONSUMED`.
+     */
+    claimAsAsset(id: string, input?: ClaimAsAssetInput, options?: Call): Promise<unknown>;
+}
+export declare function createUploadsModule(transport: Transport, fetchImpl: typeof globalThis.fetch): UploadsModule;

package/dist/uploads/index.js

@@ -0,0 +1,72 @@
+import { PLATFORM_PASSTHROUGH_KEYS, ValidationError, } from '@sixtyninecommerce/core';
+/**
+ * `headers` carries the exact header NAMES a signature was computed over.
+ *
+ * Case-converting them would rewrite `content-type` to `contentType`, and the
+ * PUT would then go out without the header storage is checking for — a
+ * signature failure that looks like a credential problem and is not.
+ */
+const PRESERVE = new Set([...PLATFORM_PASSTHROUGH_KEYS, 'headers']);
+export function createUploadsModule(transport, fetchImpl) {
+    return {
+        async stage(input, options) {
+            if (!Number.isSafeInteger(input.size) || input.size < 1) {
+                // Refused here rather than sent: a fractional or negative size would be
+                // rejected by the service as a validation failure whose message is
+                // about a field the caller did not type, and `size: NaN` from a missing
+                // `blob.size` is the way this goes wrong in practice.
+                throw new ValidationError({
+                    code: 'UPLOAD_SIZE_INVALID',
+                    message: `size must be the exact whole number of bytes you will upload; received ${String(input.size)}.`,
+                    status: 400,
+                    service: 'plugins',
+                });
+            }
+            return await transport.rest('plugins', {
+                method: 'POST',
+                path: '/uploads/stage',
+                body: {
+                    purpose: input.purpose,
+                    mime_type: input.mimeType,
+                    size_bytes: input.size,
+                    client_token: input.clientToken,
+                    ...(input.filename === undefined ? {} : { filename: input.filename }),
+                },
+            }, { ...options, preserveKeys: PRESERVE });
+        },
+        async put(ticket, body) {
+            const response = await fetchImpl(ticket.url, {
+                method: ticket.method,
+                // Exactly what was signed, and nothing else. An extra header is
+                // harmless, but a MISSING or altered one is a signature failure.
+                headers: { ...ticket.headers },
+                body: body,
+            });
+            if (!response.ok) {
+                const detail = await response.text().catch(() => '');
+                throw new ValidationError({
+                    code: 'UPLOAD_PUT_REFUSED',
+                    message: `The object store refused the upload (HTTP ${String(response.status)}). The commonest causes are a body whose length is not the \`size\` this upload was staged for, ` +
+                        `a changed \`content-type\`, and a URL that has expired.${detail ? ` Store said: ${detail.slice(0, 300)}` : ''}`,
+                    status: response.status,
+                    service: 'plugins',
+                });
+            }
+        },
+        async get(id, options) {
+            return await transport.rest('plugins', { method: 'GET', path: `/uploads/${encodeURIComponent(id)}` }, { ...options, preserveKeys: PRESERVE });
+        },
+        async claimAsAsset(id, input, options) {
+            const body = await transport.rest('cms', {
+                method: 'POST',
+                path: '/assets/from-staged',
+                body: {
+                    staged_upload_id: id,
+                    ...(input?.folderId === undefined ? {} : { folder_id: input.folderId }),
+                    ...(input?.altText === undefined ? {} : { alt_text: input.altText }),
+                },
+            }, options);
+            return body.data;
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sixtyninecommerce/admin",
-  "version": "0.5.0",
+  "version": "0.7.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.4.0"
   },
   "devDependencies": {
     "@types/node": "22.19.7",
@@ -41,7 +41,7 @@
     "vitest": "4.1.6"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "dev": "tsc -p tsconfig.build.json --watch",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",