@sixtyninecommerce/admin 0.2.0 → 0.3.1

package/README.md

@@ -108,6 +108,89 @@ For a machine credential this is the only way to learn any of it without being r
 tenant — permissions and entitlements have no meaning without a channel — and it is admin-plane
 only: a storefront principal is refused with `PermissionDeniedError`.
 
+### Locations
+
+A location profile is a Vendure stock location plus the fields a head, a POS or an order-entry
+client needs to address it. **`TenantContext.location` is a profile's `stockLocationId`** — not its
+`code` — and setting it puts `x-location` on every request.
+
+```ts
+const locations = await admin.locations.list();          // a Page; the list is complete today
+await admin.locations.upsert({
+  stockLocationId: locations.items[0]!.stockLocationId,
+  code: 'main-warehouse',                                 // kebab-case, unique per store
+  name: 'Main Warehouse',
+  timezone: 'Europe/Amsterdam',                           // IANA zone name
+  openingHours: { mon: [{ open: '09:00', close: '17:30' }] },
+  address: { streetLine1: 'Keizersgracht 1', city: 'Amsterdam', postalCode: '1015 CJ', countryCode: 'NL' },
+});
+
+const register = admin.withTenant({ location: 'the-stock-location-id' });
+```
+
+`upsert` states the **whole** profile: an omitted optional field clears it. `address` is the one
+exception — it writes through to the stock location's own field, so omit it to leave that field
+alone and pass `null` to clear it. `get()` answers `null` when a stock location has no profile, and
+`delete()` answers `false` when there was none; neither is an error. Refusals arrive as
+`LOCATION_CODE_TAKEN` (`ConflictError`), `INVALID_TIMEZONE` / `INVALID_OPENING_HOURS` /
+`INVALID_ADDRESS` (`ValidationError`) and `LOCATION_NOT_FOUND` (`NotFoundError`).
+
+An API token can be pinned to a set of them, after which it may only send an `x-location` naming
+one of those (`LOCATION_NOT_ALLOWED` otherwise, enforced on the Admin API today):
+
+```ts
+await scoped.apiTokens.create({
+  name: 'POS register 1',
+  permissions: ['ReadOrder', 'ReadStockLocation'], // no POS template exists yet
+  locationIds: ['sl-1'],
+});
+await scoped.apiTokens.update('tok-1', { locationIds: null }); // null lifts it; omitting leaves it
+```
+
+An **empty** list is refused with `INVALID_LOCATION_RESTRICTION` — "allowed nowhere" is never what a
+caller means, so pass `null` to lift the restriction instead.
+
+`auth.whoami().locations` is meant to report the same list for the credential in hand, but the
+plugins `GET /me` projection still answers `null` for every principal — read `apiTokens.list()` for
+the restriction a token actually carries until that is wired.
+
+### Retention and legal holds
+
+```ts
+await admin.tenant.retention.get();                                  // class, holdUntil, holds
+await admin.tenant.retention.set({ retentionClass: 'gdpr-7y' });     // omitting holdUntil CLEARS it
+await admin.tenant.retention.hold('litigation 2026-114');            // this principal's hold
+await admin.tenant.retention.release('litigation 2026-114');
+```
+
+Always the **active** channel — there is no channel argument, which is what lets a tenant-scoped
+token hold its own store and reach no other. `retentionClass` is free text (default `standard`) that
+the platform stores and does not interpret yet. While any hold stands, or `holdUntil` is in the
+future, a hard delete of the store is refused with `RETENTION_HOLD_ACTIVE` (`BusinessRuleError`).
+`release()` lifts only the calling principal's own hold: another's is `RETENTION_HOLD_NOT_YOURS`
+(`PermissionDeniedError`) unless you are a SuperAdmin, which releases every hold. A bad class or
+instant is `RETENTION_INPUT_INVALID` (`ValidationError`).
+
+### Audit
+
+The tenant's own forensic trail. It needs the `ReadAudit` permission, which is deliberately outside
+the "Read-only"/"Full access" token shortcuts: a platform operator mints an *Audit reader* token,
+a merchant administrator cannot.
+
+```ts
+const failures = await admin.audit.events({ outcome: 'failed', action: 'order.', limit: 50 });
+for await (const event of failures) console.log(event.occurredAt, event.action, event.errorCode);
+
+const timeline = await admin.audit.correlation(failures.items[0]!.correlationId);
+timeline.events; timeline.calls;   // one trace, both tables, oldest first
+```
+
+`events` and `calls` are cursor pages (`.next()`, `for await`) and report no `total` — the feed
+keyset-paginates and never counts. `correlation` is not a page: it is capped at 500 rows per table
+and the two arrays are meant to be read together. `metadata`, `requestBody` and `responseBody` keep
+their own key spellings, because they are evidence of what a vendor actually sent. A trace this
+tenant did not touch answers two empty arrays rather than an error.
+
 ### Tenancy
 
 A client with no `tenant.scope` may only call `auth.*` and `channels.byCode()`; every other module
@@ -126,12 +209,73 @@ write is never deduplicated.
 |---|---|
 | `content.forms.upsertBySlug` | yes — the CMS replays the first response for the same key |
 | `seo.redirects.create` | yes — the plugins service does the same |
+| `locations.*`, `tenant.retention.*`, `apiTokens.*` | no — they are Admin API writes |
 | everything else | no; the key is recorded on the wire and acts on nothing |
 
 Where it is honoured, the same key with a **different** body is refused with 409. This SDK never
 retries a write on its own, so a repeat is always one you sent: use a fresh key per intended write
 and reuse it only when retrying that exact write.
 
+### Meta catalog
+
+`admin.meta.catalog()` is the one call a UI makes before it can render anything: the labels, state
+machines, permission and plugin catalogs, and JSON Schema for the platform's opaque channel
+settings. It is readable by any authenticated principal and identical for every tenant.
+
+```ts
+const meta = await admin.meta.catalog();
+
+meta.labels.orderState.PaymentSettled;        // 'Payment Settled'
+meta.labels.returnState.items_received;       // 'Items received'
+meta.labels.paymentStatus.overdue;            // { label: 'Overdue', tone: 'danger' }
+meta.transitions.return.approved;             // ['items_received', 'settlement_pending', …]
+meta.transitions.fulfillmentRank.Packed;      // 3
+meta.permissions.catalog;                     // every permission the Admin API registers
+meta.plugins.catalog;                         // [{ key: 'myparcel', name: 'MyParcel', … }]
+meta.settingsSchemas.shipping_countries;      // a draft 2020-12 schema
+meta.settingsSchemas.ai_bot_defaults;         // …keyed by SETTING name, not camelised
+```
+
+| Member | What it holds |
+|---|---|
+| `labels` | `orderState`, `returnState`, `returnReason`, `paymentStatus`, `fulfillmentStatus`, `fulfillmentHoldReason`, `subscriptionStatus`, `quoteStatus`, `settlementMethod`, `creditNoteKind`, `auditService`, `auditCategory`, `auditEventOutcome`, `auditCallOutcome` |
+| `transitions` | `quote`, `return` (`from` → allowed `to`), `fulfillmentRank` |
+| `permissions` | `catalog`, `groups` (the role-editor grid), `roleTemplates`, `tokenTemplates` |
+| `plugins` | `catalog`, `groupLabels` |
+| `settingsSchemas` | a schema per opaque `Channel.customFields` column (ten today) |
+
+**Member names are camelCase; the keys inside them are not.** Everything below a member is keyed by
+platform data — `items_received`, `past_due`, `PaymentSettled`, `order_status_rules`, a schema's own
+`targetState` — and this SDK preserves those keys exactly as the platform spells them. Look a label
+up by the value you received on the wire, never by a camelised version of it.
+
+Three things the settings schemas do not say out loud:
+
+- each describes the **decoded** value, while the column stores `JSON.stringify` of it — so
+  validate `JSON.parse(customFields.socialLinks)` and write a string back;
+- a schema states the shape, not every rule. Only four of the ten columns are validated server-side
+  at all — for the other six a bad value is not refused on write, it is dropped or ignored on read,
+  with no error anywhere (each description says which it is). And one rule is inexpressible:
+  `shipping_countries` and `tax_exclusive_countries` both refuse `["US","us"]` on write as a
+  duplicate, which `uniqueItems` cannot see. Schema-valid means "worth sending", not "certain to be
+  accepted" — handle the `ValidationError`, and do not skip your own validation;
+- `transitions` is the state machine, not the whole gate. `return.approved → settled` is a legal
+  edge that the service still refuses when the channel requires a receipt first, and
+  `quote.approved → converted_to_order` is refused when the projected order misses the channel's
+  order minimum. Offer the action, handle the refusal.
+
+`version` is a hash of everything else and changes only when the catalog does, so the client caches
+the document for its own lifetime and the second call costs nothing. `admin.meta.refresh()` fetches
+again for a long-lived process that wants to pick up a redeploy; when the version has not moved it
+keeps the object you already hold, so identity tells you whether anything changed. A client derived
+with `withTenant()` has its own cache.
+
+Concurrent first calls share one request, and a `signal` passed to `catalog()` cancels only your own
+wait — never the shared request, and never another caller's. So handing it a framework-supplied
+signal (a TanStack Query `queryFn` gets one for free) is safe: one component unmounting cannot fail
+the catalog for the rest of the page. `refresh()` is not shared, so its `signal` cancels the request
+itself.
+
 ### Errors
 
 One hierarchy, all re-exported from this package so you need no direct dependency on

package/dist/api-tokens/index.d.ts

@@ -1,10 +1,10 @@
 import { type Page, type Transport } from '@sixtyninecommerce/core';
 import type { ApiToken, Call, CreateApiTokenInput, ListOptions, UpdateApiTokenInput } from '../types.js';
-export declare const API_TOKEN_FIELDS = "\n  id\n  name\n  tokenPrefix\n  permissions\n  channelId\n  expiresAt\n  lastUsedAt\n  revokedAt\n  createdAt\n";
-export declare const LIST_QUERY = "\n  query ApiTokens($options: ApiTokenListOptions) {\n    apiTokens(options: $options) {\n      totalItems\n      items { \n  id\n  name\n  tokenPrefix\n  permissions\n  channelId\n  expiresAt\n  lastUsedAt\n  revokedAt\n  createdAt\n }\n    }\n  }\n";
-export declare const CREATE_MUTATION = "\n  mutation CreateApiToken($input: CreateApiTokenInput!) {\n    createApiToken(input: $input) {\n      token\n      apiToken { \n  id\n  name\n  tokenPrefix\n  permissions\n  channelId\n  expiresAt\n  lastUsedAt\n  revokedAt\n  createdAt\n }\n    }\n  }\n";
-export declare const UPDATE_MUTATION = "\n  mutation UpdateApiToken($input: UpdateApiTokenInput!) {\n    updateApiToken(input: $input) { \n  id\n  name\n  tokenPrefix\n  permissions\n  channelId\n  expiresAt\n  lastUsedAt\n  revokedAt\n  createdAt\n }\n  }\n";
-export declare const REVOKE_MUTATION = "\n  mutation RevokeApiToken($id: ID!) {\n    revokeApiToken(id: $id) { \n  id\n  name\n  tokenPrefix\n  permissions\n  channelId\n  expiresAt\n  lastUsedAt\n  revokedAt\n  createdAt\n }\n  }\n";
+export declare const API_TOKEN_FIELDS = "\n  id\n  name\n  tokenPrefix\n  permissions\n  channelId\n  locationIds\n  expiresAt\n  lastUsedAt\n  revokedAt\n  createdAt\n";
+export declare const LIST_QUERY = "\n  query ApiTokens($options: ApiTokenListOptions) {\n    apiTokens(options: $options) {\n      totalItems\n      items { \n  id\n  name\n  tokenPrefix\n  permissions\n  channelId\n  locationIds\n  expiresAt\n  lastUsedAt\n  revokedAt\n  createdAt\n }\n    }\n  }\n";
+export declare const CREATE_MUTATION = "\n  mutation CreateApiToken($input: CreateApiTokenInput!) {\n    createApiToken(input: $input) {\n      token\n      apiToken { \n  id\n  name\n  tokenPrefix\n  permissions\n  channelId\n  locationIds\n  expiresAt\n  lastUsedAt\n  revokedAt\n  createdAt\n }\n    }\n  }\n";
+export declare const UPDATE_MUTATION = "\n  mutation UpdateApiToken($input: UpdateApiTokenInput!) {\n    updateApiToken(input: $input) { \n  id\n  name\n  tokenPrefix\n  permissions\n  channelId\n  locationIds\n  expiresAt\n  lastUsedAt\n  revokedAt\n  createdAt\n }\n  }\n";
+export declare const REVOKE_MUTATION = "\n  mutation RevokeApiToken($id: ID!) {\n    revokeApiToken(id: $id) { \n  id\n  name\n  tokenPrefix\n  permissions\n  channelId\n  locationIds\n  expiresAt\n  lastUsedAt\n  revokedAt\n  createdAt\n }\n  }\n";
 export declare const DELETE_MUTATION = "\n  mutation DeleteApiTokens($ids: [ID!]!) {\n    deleteApiTokens(ids: $ids) {\n      result\n      message\n    }\n  }\n";
 /** The raw token is shown exactly once, at creation. */
 export interface CreatedApiToken {

package/dist/api-tokens/index.js

@@ -5,6 +5,7 @@ export const API_TOKEN_FIELDS = /* GraphQL */ `
   tokenPrefix
   permissions
   channelId
+  locationIds
   expiresAt
   lastUsedAt
   revokedAt

package/dist/audit/index.d.ts

@@ -0,0 +1,168 @@
+import { type Page, type Transport } from '@sixtyninecommerce/core';
+import type { Call, ListOptions } from '../types.js';
+/**
+ * One row of the tenant's own audit trail — who did what, to which record, and
+ * whether it worked.
+ *
+ * Every field the platform writes is typed; the index signature is there
+ * because the endpoint answers `SELECT *` over a partitioned table that gains
+ * columns additively (`error_code` arrived that way), so a consumer on an older
+ * SDK still receives them.
+ */
+export interface AuditEvent {
+    id: string;
+    /** ISO-8601 UTC. */
+    occurredAt: string;
+    /** Always the caller's own channel on these routes; null for a platform-level row. */
+    channelId: string | null;
+    /** `vendure` | `cms` | `plugins` | `dashboard`. */
+    service: string;
+    /** `admin_action` | `customer_action` | `auth` | `integration` | `job` | `webhook` | `system`. */
+    category: string;
+    /** `domain.resource.verb`, e.g. `afas.invoice.push`. */
+    action: string;
+    /** `user` | `customer` | `api_token` | `system` | `service` | `anonymous`. */
+    actorType: string;
+    actorId: string | null;
+    /** A token's name or a human's email. Never both — see the actor rules in the audit ADR. */
+    actorLabel: string | null;
+    onBehalfOfId: string | null;
+    targetType: string | null;
+    targetId: string | null;
+    targetLabel: string | null;
+    /** `succeeded` | `failed` | `partial` | `skipped` | `rejected`. */
+    outcome: string;
+    /** The failure taxonomy alerting groups on (`data_validation`, `transient`, …). */
+    errorClass: string | null;
+    /** The specific SCREAMING_SNAKE reason. */
+    errorCode: string | null;
+    /** Operator text, sanitized by the writer. Never a customer-facing message. */
+    errorDetail: string | null;
+    /** W3C trace id — the key {@link AuditModule.correlation} takes. */
+    correlationId: string;
+    durationMs: number | null;
+    /** `merchant_visible` | `internal`. Every row is `internal` today (no emit site sets it). */
+    sensitivity: string;
+    /**
+     * Free-form bag written by the emitting site. Its own keys are NEVER
+     * case-converted (`preserveKeys`), so they read exactly as they were stored.
+     */
+    metadata: Record<string, unknown> | null;
+    [extra: string]: unknown;
+}
+/** One call record: the evidence of a single request to or from an integration. */
+export interface AuditCall {
+    id: string;
+    /** ISO-8601 UTC. */
+    occurredAt: string;
+    channelId: string | null;
+    correlationId: string;
+    service: string;
+    /** `afas` | `exactonline` | `mollie` | `meilisearch` | … */
+    integration: string;
+    /** `outbound` | `inbound`. */
+    direction: string;
+    /** `http` | `sdk` | `graphql` | `soap` | `sftp` | `smtp`. */
+    transport: string;
+    operation: string;
+    /** Query strings are stripped before persistence. */
+    endpoint: string | null;
+    /** The REAL upstream status, or null for a transport that has none (SDK, SFTP). */
+    statusCode: number | null;
+    /** `succeeded` | `failed` | `timeout`. */
+    outcome: string;
+    /** The remote receipt (an AFAS V-number, a Mollie payment id, a Meili task uid). */
+    remoteRef: string | null;
+    attempt: number;
+    durationMs: number | null;
+    /** Redacted and capped by the writer; keys preserved verbatim. */
+    requestBody: unknown;
+    responseBody: unknown;
+    error: string | null;
+    errorCode: string | null;
+    metadata: Record<string, unknown> | null;
+    [extra: string]: unknown;
+}
+/**
+ * Filters for {@link AuditModule.events}. Every one is an exact match except
+ * `action` (prefix, so `order.` finds the whole family) and `q` (free text over
+ * action, target label, error detail and actor label).
+ *
+ * `dateFrom`/`dateTo` are inclusive ISO-8601. A value with no offset is read as
+ * UTC by the service, and a bare date covers that whole UTC day — so pass an
+ * explicit offset whenever the tenant's own day is what you mean.
+ *
+ * `limit` is 1–200, default 50. A larger value is REJECTED with
+ * `ValidationError`, not clamped — a silently short page would read as "that is
+ * everything". Walk the pages with `.next()` or `for await` instead of asking
+ * for a bigger one.
+ */
+export interface AuditEventFilter extends ListOptions {
+    service?: string;
+    category?: string;
+    /** Prefix match, e.g. `order.` */
+    action?: string;
+    actorId?: string;
+    targetType?: string;
+    targetId?: string;
+    outcome?: string;
+    errorClass?: string;
+    correlationId?: string;
+    /** Free text over action, target label, error detail and actor label. */
+    q?: string;
+    dateFrom?: string;
+    dateTo?: string;
+}
+/**
+ * Filters for {@link AuditModule.calls}. See {@link AuditEventFilter} for the
+ * date rules and the 1–200 `limit` cap, which are the same here.
+ */
+export interface AuditCallFilter extends ListOptions {
+    integration?: string;
+    direction?: string;
+    outcome?: string;
+    /** The real upstream HTTP status. */
+    statusCode?: number;
+    correlationId?: string;
+    /** Free text over operation, error and receipt. */
+    q?: string;
+    dateFrom?: string;
+    dateTo?: string;
+}
+/** Everything one trace touched inside this tenant, oldest first. */
+export interface AuditCorrelation {
+    events: AuditEvent[];
+    calls: AuditCall[];
+}
+/**
+ * The tenant's own audit trail (`GET /audit/mine/*`).
+ *
+ * **What it is not.** These are not the platform operator's cross-tenant
+ * forensic routes (`/audit/*`), and they are not a merchant Activity feed
+ * either: they serve every row of this channel, `internal` sensitivity
+ * included. The permission that opens them, `ReadAudit`, is deliberately
+ * outside `PERMISSION_GROUPS`, so it is not in the "Read-only" or "Full access"
+ * token shortcuts and a merchant administrator cannot mint it — an operator
+ * mints an "Audit reader" token and hands it over. A credential without it is
+ * refused with `PermissionDeniedError`.
+ *
+ * **Freshness.** The routes are `@FreshAuth()`: revoking the token stops these
+ * reads at once rather than up to a permission-cache later. That costs one
+ * extra round trip per call, which is why these are poller routes, not
+ * something to put behind a table a browser repaints.
+ */
+export interface AuditModule {
+    events(filter?: AuditEventFilter): Promise<Page<AuditEvent>>;
+    calls(filter?: AuditCallFilter): Promise<Page<AuditCall>>;
+    /**
+     * Both tables for one W3C trace id, capped at 500 rows each and NOT paged —
+     * a trace is a bounded thing, and the two arrays are meant to be read
+     * together as one timeline.
+     *
+     * A trace can legitimately span tenants (a platform job touching several).
+     * Only this channel's rows come back, so an unrelated trace id answers with
+     * two empty arrays rather than an error.
+     */
+    correlation(traceId: string, options?: Call): Promise<AuditCorrelation>;
+}
+export declare function createAuditModule(transport: Transport): AuditModule;

package/dist/audit/index.js

@@ -0,0 +1,71 @@
+import { createPage, PLATFORM_PASSTHROUGH_KEYS, readRestPage, } from '@sixtyninecommerce/core';
+/**
+ * The audit rows carry three JSONB bags — `metadata`, `request_body`,
+ * `response_body` — whose keys are a vendor's or an emitting site's own. All
+ * three are in the platform passthrough set, so their subtrees survive the
+ * camelisation that the surrounding row goes through.
+ */
+const AUDIT_PASSTHROUGH = PLATFORM_PASSTHROUGH_KEYS;
+/**
+ * The wire cursor is `?before=`, because these lists run newest-first and the
+ * keyset walks backwards through `(occurred_at, id)`. The SDK's name for "the
+ * cursor the previous page handed me" is `after` on every list it has
+ * (`ListOptions.after`), and the value is opaque either way — so the direction
+ * stays the endpoint's business and consumers keep one vocabulary.
+ */
+function pageQuery(filter) {
+    return { before: filter?.after, limit: filter?.limit };
+}
+export function createAuditModule(transport) {
+    async function events(filter) {
+        const body = await transport.rest('plugins', {
+            method: 'GET',
+            path: '/audit/mine/events',
+            query: {
+                ...pageQuery(filter),
+                service: filter?.service,
+                category: filter?.category,
+                action: filter?.action,
+                actor_id: filter?.actorId,
+                target_type: filter?.targetType,
+                target_id: filter?.targetId,
+                outcome: filter?.outcome,
+                error_class: filter?.errorClass,
+                correlation_id: filter?.correlationId,
+                q: filter?.q,
+                date_from: filter?.dateFrom,
+                date_to: filter?.dateTo,
+            },
+        }, { ...filter, preserveKeys: AUDIT_PASSTHROUGH });
+        // No `total`: the endpoint keyset-paginates and never counts, so `Page.total`
+        // is absent here rather than zero.
+        const { items, meta } = readRestPage(body);
+        return createPage(items, meta, (cursor) => events({ ...filter, after: cursor }));
+    }
+    async function calls(filter) {
+        const body = await transport.rest('plugins', {
+            method: 'GET',
+            path: '/audit/mine/calls',
+            query: {
+                ...pageQuery(filter),
+                integration: filter?.integration,
+                direction: filter?.direction,
+                outcome: filter?.outcome,
+                status_code: filter?.statusCode,
+                correlation_id: filter?.correlationId,
+                q: filter?.q,
+                date_from: filter?.dateFrom,
+                date_to: filter?.dateTo,
+            },
+        }, { ...filter, preserveKeys: AUDIT_PASSTHROUGH });
+        const { items, meta } = readRestPage(body);
+        return createPage(items, meta, (cursor) => calls({ ...filter, after: cursor }));
+    }
+    return {
+        events,
+        calls,
+        correlation(traceId, options) {
+            return transport.rest('plugins', { method: 'GET', path: `/audit/mine/correlation/${encodeURIComponent(traceId)}` }, { ...options, preserveKeys: AUDIT_PASSTHROUGH });
+        },
+    };
+}

package/dist/client.d.ts

@@ -1,9 +1,13 @@
 import { type DeprecationNotice, type RateLimitInfo, type RetryPolicy, type TenantContext, type TenantScope } from '@sixtyninecommerce/core';
 import { type ApiTokensModule } from './api-tokens/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 LocationsModule } from './locations/index.js';
+import { type MetaModule } from './meta/index.js';
 import { type RedirectsModule } from './seo/redirects.js';
 import { type ChannelsModule } from './tenant/channels.js';
+import { type RetentionModule } from './tenant/retention.js';
 export interface AdminClientConfig {
     urls: {
         vendureUrl: string;
@@ -39,13 +43,22 @@ export interface AdminClientConfig {
 export interface AdminClient {
     auth: AuthModule;
     apiTokens: ApiTokensModule;
+    audit: AuditModule;
     channels: ChannelsModule;
     content: {
         forms: FormsModule;
     };
+    /** Stock-location profiles (spec §8.7); `TenantContext.location` names one by id. */
+    locations: LocationsModule;
+    /** Labels, transitions, permission and plugin catalogs, settings schemas. */
+    meta: MetaModule;
     seo: {
         redirects: RedirectsModule;
     };
+    /** The calling tenant's own settings. Always the ACTIVE channel — no channel argument. */
+    tenant: {
+        retention: RetentionModule;
+    };
     /** Human SuperAdmin surface. Empty in phase 0. */
     platform: Record<string, never>;
     /** A derived client on another tenant, sharing this one's principal. */

package/dist/client.js

@@ -1,9 +1,13 @@
 import { createChannelResolver, createTransport, mergeTenant, UNSCOPED_TENANT, ValidationError, } from '@sixtyninecommerce/core';
 import { createApiTokensModule } from './api-tokens/index.js';
+import { createAuditModule } from './audit/index.js';
 import { createAuthModule } from './auth/index.js';
 import { createFormsModule } from './content/forms.js';
+import { createLocationsModule } from './locations/index.js';
+import { createMetaModule } from './meta/index.js';
 import { createRedirectsModule } from './seo/redirects.js';
 import { createChannelsModule } from './tenant/channels.js';
+import { createRetentionModule } from './tenant/retention.js';
 /**
  * An admin credential in a browser is a credential the whole internet can read
  * (spec §18 amendment 3, §15.21). A SESSION bearer is fine there — that is what
@@ -213,9 +217,13 @@ function buildClient(config, overrides, resolver, shared) {
             },
         }),
         apiTokens: createApiTokensModule(transport),
+        audit: createAuditModule(transport),
         channels: createChannelsModule(resolver),
         content: { forms: createFormsModule(transport) },
+        locations: createLocationsModule(transport),
+        meta: createMetaModule(transport),
         seo: { redirects: createRedirectsModule(transport) },
+        tenant: { retention: createRetentionModule(transport) },
         platform: {},
         withTenant(next) {
             // `mergeTenant`, not a spread: it merges `actor` FIELD BY FIELD, so a

package/dist/index.d.ts

@@ -2,9 +2,10 @@
  * `@sixtyninecommerce/admin` — the back-office SDK.
  *
  * Every capability of the platform is a method here (the parity rule, spec §5).
- * Phase 0 ships the skeleton: auth, personal API tokens, channel resolution,
- * CMS forms and SEO redirects, plus the `platform` guard every cross-tenant
- * method added later runs through.
+ * Shipped so far: auth, personal API tokens, channel resolution, CMS forms, SEO
+ * redirects, the meta catalog, the tenant's own audit trail, its retention
+ * policy and its stock location profiles — plus the `platform` guard every
+ * cross-tenant method added later runs through.
  *
  * Server-side by default. A session bearer is welcome in a browser — the
  * dashboard is one — but constructing a client with an API token there throws
@@ -24,11 +25,16 @@ 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 { 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 { Form, FormField, FormFieldInput, FormFieldTranslation, FormFieldTranslationInput, FormInput, FormsModule, FormTranslation, FormTranslationInput, } from './content/forms.js';
 export { AdminProjectionError } from './errors.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 { requireHumanSession } from './platform/guard.js';
 export type { Redirect, RedirectCreateInput, RedirectsModule, RedirectUpdateInput, } from './seo/redirects.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/index.js

@@ -2,9 +2,10 @@
  * `@sixtyninecommerce/admin` — the back-office SDK.
  *
  * Every capability of the platform is a method here (the parity rule, spec §5).
- * Phase 0 ships the skeleton: auth, personal API tokens, channel resolution,
- * CMS forms and SEO redirects, plus the `platform` guard every cross-tenant
- * method added later runs through.
+ * Shipped so far: auth, personal API tokens, channel resolution, CMS forms, SEO
+ * redirects, the meta catalog, the tenant's own audit trail, its retention
+ * policy and its stock location profiles — plus the `platform` guard every
+ * cross-tenant method added later runs through.
  *
  * Server-side by default. A session bearer is welcome in a browser — the
  * dashboard is one — but constructing a client with an API token there throws
@@ -18,4 +19,5 @@
 export { AuthenticationError, BusinessRuleError, ConflictError, NotFoundError, PermissionDeniedError, PlatformError, RateLimitedError, TransportError, UpstreamError, ValidationError, } from '@sixtyninecommerce/core';
 export { createAdminClient, } from './client.js';
 export { AdminProjectionError } from './errors.js';
+export { OPENING_HOURS_DAYS } from './locations/index.js';
 export { requireHumanSession } from './platform/guard.js';

package/dist/locations/index.d.ts

@@ -0,0 +1,138 @@
+import { type Page, type Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/** `openingHours` keys: lowercase, three letters, Monday first. */
+export declare const OPENING_HOURS_DAYS: readonly ["mon", "tue", "wed", "thu", "fri", "sat", "sun"];
+export type OpeningHoursDay = (typeof OPENING_HOURS_DAYS)[number];
+export interface OpeningHoursInterval {
+    /** `HH:mm`, 24-hour. */
+    open: string;
+    /** `HH:mm`, 24-hour. May be EARLIER than `open`: that is an overnight shift, and it is allowed. */
+    close: string;
+}
+/**
+ * Trading hours, shape-validated only — the platform does not compute an "open
+ * now" from them, and a day may carry at most 12 intervals. A missing day means
+ * "nothing stated", not "closed".
+ */
+export type OpeningHours = Partial<Record<OpeningHoursDay, OpeningHoursInterval[]>>;
+/**
+ * The postal address, read from and written to
+ * `StockLocation.customFields.address`. There is no second copy.
+ *
+ * Every field is optional on the way OUT because that column predates this API
+ * and holds whatever earlier writers put there.
+ */
+export interface StockLocationAddress {
+    contactName?: string | null;
+    company?: string | null;
+    streetLine1?: string | null;
+    streetLine2?: string | null;
+    city?: string | null;
+    province?: string | null;
+    postalCode?: string | null;
+    /** ISO 3166-1 alpha-2, upper case. */
+    countryCode?: string | null;
+    phoneNumber?: string | null;
+}
+/** On the way IN street, city, postal code and country are required; the server refuses less. */
+export interface StockLocationAddressInput {
+    contactName?: string | null;
+    streetLine1: string;
+    streetLine2?: string | null;
+    city: string;
+    province?: string | null;
+    postalCode: string;
+    /** ISO 3166-1 alpha-2; stored upper case. */
+    countryCode: string;
+    company?: string | null;
+    phoneNumber?: string | null;
+}
+/** The stock location a profile belongs to, as much of it as the profile selects. */
+export interface LocationStockLocation {
+    id: string;
+    name: string;
+    description: string;
+}
+/**
+ * A physical place: a Vendure `StockLocation` plus the fields a head, a POS or
+ * an order-entry client needs to address it.
+ *
+ * **`TenantContext.location` is the `stockLocationId` of one of these** — not
+ * the `code`. Set it on the client (`createAdminClient({ tenant: { location } })`,
+ * `withTenant({ location })`, or per call) and every request carries
+ * `x-location`; the server refuses an id that does not belong to the request's
+ * channel, and an API token restricted with `locationIds` is refused for any
+ * location outside its list.
+ */
+export interface LocationProfile {
+    stockLocationId: string;
+    /** Kebab-case handle, unique among this store's locations. */
+    code: string;
+    name: string;
+    address: StockLocationAddress | null;
+    /** IANA zone name; null means the store's own time zone applies. */
+    timezone: string | null;
+    phone: string | null;
+    openingHours: OpeningHours | null;
+    stockLocation: LocationStockLocation;
+}
+/**
+ * The WHOLE profile, not a patch: an omitted optional field CLEARS it.
+ *
+ * `address` is the one exception, because it writes through to the stock
+ * location's own field: omit it to leave that field alone, pass `null` to clear
+ * it.
+ */
+export interface UpsertLocationProfileInput {
+    stockLocationId: string;
+    /** Kebab-case, 1–64 characters, unique per channel (`LOCATION_CODE_TAKEN` otherwise). */
+    code: string;
+    name: string;
+    /** IANA zone name, validated by constructing an `Intl.DateTimeFormat` (`INVALID_TIMEZONE`). */
+    timezone?: string | null;
+    phone?: string | null;
+    openingHours?: OpeningHours | null;
+    address?: StockLocationAddressInput | null;
+}
+/**
+ * Location profiles for the active channel (spec §8.7).
+ *
+ * Reading needs `ReadStockLocation`, writing `UpdateStockLocation`. Everything
+ * is scoped to the channel the client is on: a stock location belonging to
+ * another tenant is invisible to `list`/`get` and unwritable by `upsert`.
+ *
+ * **Coded refusals**, delivered as GraphQL errors with `extensions.code`:
+ * `LOCATION_NOT_FOUND` (→ `NotFoundError`) — which is also the answer for a
+ * stock location belonging to another tenant, deliberately worded so a caller
+ * cannot probe another store's ids; `LOCATION_CODE_TAKEN` (→ `ConflictError`);
+ * and `INVALID_LOCATION_CODE` / `INVALID_LOCATION_NAME` /
+ * `INVALID_LOCATION_PHONE` / `INVALID_TIMEZONE` / `INVALID_OPENING_HOURS` /
+ * `INVALID_ADDRESS` (→ `ValidationError`).
+ *
+ * `LOCATION_NOT_IN_CHANNEL` is NOT one of these: it belongs to the two places
+ * that take a location id from outside this surface — `apiTokens.create`/
+ * `update` with a foreign `locationIds` entry, and the `x-location` gate — and
+ * arrives as a `ValidationError` from both.
+ */
+export interface LocationsModule {
+    /**
+     * Every profile of the active channel.
+     *
+     * A `Page` because every list in this SDK is one (spec §9.2), not because
+     * this query pages: `locationProfiles` answers the complete array, so the
+     * page is always the last one and `total` is its length. If the endpoint ever
+     * grows a cursor, consumers walking it with `.next()` or `for await` keep
+     * working unchanged.
+     */
+    list(options?: Call): Promise<Page<LocationProfile>>;
+    /** The profile of one stock location, or null when it has none (or is not this channel's). */
+    get(stockLocationId: string, options?: Call): Promise<LocationProfile | null>;
+    upsert(input: UpsertLocationProfileInput, options?: Call): Promise<LocationProfile>;
+    /** True when a profile was removed, false when there was none. The stock location survives. */
+    delete(stockLocationId: string, options?: Call): Promise<boolean>;
+}
+export declare const LOCATION_PROFILES_QUERY = "\n  query LocationProfiles {\n    locationProfiles { \n  stockLocationId\n  code\n  name\n  timezone\n  phone\n  openingHours\n  address {\n    contactName\n    company\n    streetLine1\n    streetLine2\n    city\n    province\n    postalCode\n    countryCode\n    phoneNumber\n  }\n  stockLocation {\n    id\n    name\n    description\n  }\n }\n  }\n";
+export declare const LOCATION_PROFILE_QUERY = "\n  query LocationProfile($stockLocationId: ID!) {\n    locationProfile(stockLocationId: $stockLocationId) { \n  stockLocationId\n  code\n  name\n  timezone\n  phone\n  openingHours\n  address {\n    contactName\n    company\n    streetLine1\n    streetLine2\n    city\n    province\n    postalCode\n    countryCode\n    phoneNumber\n  }\n  stockLocation {\n    id\n    name\n    description\n  }\n }\n  }\n";
+export declare const UPSERT_LOCATION_PROFILE_MUTATION = "\n  mutation UpsertLocationProfile($input: UpsertLocationProfileInput!) {\n    upsertLocationProfile(input: $input) { \n  stockLocationId\n  code\n  name\n  timezone\n  phone\n  openingHours\n  address {\n    contactName\n    company\n    streetLine1\n    streetLine2\n    city\n    province\n    postalCode\n    countryCode\n    phoneNumber\n  }\n  stockLocation {\n    id\n    name\n    description\n  }\n }\n  }\n";
+export declare const DELETE_LOCATION_PROFILE_MUTATION = "\n  mutation DeleteLocationProfile($stockLocationId: ID!) {\n    deleteLocationProfile(stockLocationId: $stockLocationId)\n  }\n";
+export declare function createLocationsModule(transport: Transport): LocationsModule;

package/dist/locations/index.js

@@ -0,0 +1,72 @@
+import { createPage } from '@sixtyninecommerce/core';
+/** `openingHours` keys: lowercase, three letters, Monday first. */
+export const OPENING_HOURS_DAYS = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun'];
+const LOCATION_PROFILE_FIELDS = /* GraphQL */ `
+  stockLocationId
+  code
+  name
+  timezone
+  phone
+  openingHours
+  address {
+    contactName
+    company
+    streetLine1
+    streetLine2
+    city
+    province
+    postalCode
+    countryCode
+    phoneNumber
+  }
+  stockLocation {
+    id
+    name
+    description
+  }
+`;
+export const LOCATION_PROFILES_QUERY = /* GraphQL */ `
+  query LocationProfiles {
+    locationProfiles { ${LOCATION_PROFILE_FIELDS} }
+  }
+`;
+export const LOCATION_PROFILE_QUERY = /* GraphQL */ `
+  query LocationProfile($stockLocationId: ID!) {
+    locationProfile(stockLocationId: $stockLocationId) { ${LOCATION_PROFILE_FIELDS} }
+  }
+`;
+export const UPSERT_LOCATION_PROFILE_MUTATION = /* GraphQL */ `
+  mutation UpsertLocationProfile($input: UpsertLocationProfileInput!) {
+    upsertLocationProfile(input: $input) { ${LOCATION_PROFILE_FIELDS} }
+  }
+`;
+export const DELETE_LOCATION_PROFILE_MUTATION = /* GraphQL */ `
+  mutation DeleteLocationProfile($stockLocationId: ID!) {
+    deleteLocationProfile(stockLocationId: $stockLocationId)
+  }
+`;
+export function createLocationsModule(transport) {
+    return {
+        async list(options) {
+            const data = await transport.graphql({ api: 'admin', query: LOCATION_PROFILES_QUERY }, options);
+            const items = data.locationProfiles;
+            return createPage(items, { nextCursor: null, hasNext: false, total: items.length }, () => {
+                // Unreachable while `hasNext` is false — `Page.next()` short-circuits —
+                // and a rejection rather than a silent re-fetch if that ever changes.
+                throw new Error('locationProfiles returns a complete list; there is no next page');
+            });
+        },
+        async get(stockLocationId, options) {
+            const data = await transport.graphql({ api: 'admin', query: LOCATION_PROFILE_QUERY, variables: { stockLocationId } }, options);
+            return data.locationProfile;
+        },
+        async upsert(input, options) {
+            const data = await transport.graphql({ api: 'admin', query: UPSERT_LOCATION_PROFILE_MUTATION, variables: { input } }, options);
+            return data.upsertLocationProfile;
+        },
+        async delete(stockLocationId, options) {
+            const data = await transport.graphql({ api: 'admin', query: DELETE_LOCATION_PROFILE_MUTATION, variables: { stockLocationId } }, options);
+            return data.deleteLocationProfile;
+        },
+    };
+}

package/dist/meta/index.d.ts

@@ -0,0 +1,146 @@
+import { type Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/** A wire value (`items_received`, `PaymentSettled`) to its merchant-facing English. */
+export type LabelMap = Record<string, string>;
+/** The semantic colour intent a UI renders a status with. */
+export type StatusTone = 'neutral' | 'muted' | 'info' | 'success' | 'warning' | 'danger';
+/** A label that also carries a tone — the two order-status axes use these. */
+export type StatusMetaMap = Record<string, {
+    label: string;
+    tone: StatusTone;
+}>;
+/** `from` state to the states it may move to. An empty array means terminal. */
+export type TransitionMap = Record<string, string[]>;
+/** A JSON Schema document (draft 2020-12). Deliberately loose: it is data. */
+export type JsonSchema = Record<string, unknown>;
+export interface MetaCatalogLabels {
+    /** Vendure order states. `Draft` and `Created` are absent — render those raw. */
+    orderState: LabelMap;
+    returnState: LabelMap;
+    returnReason: LabelMap;
+    paymentStatus: StatusMetaMap;
+    fulfillmentStatus: StatusMetaMap;
+    fulfillmentHoldReason: LabelMap;
+    subscriptionStatus: LabelMap;
+    quoteStatus: LabelMap;
+    settlementMethod: LabelMap;
+    creditNoteKind: LabelMap;
+    auditService: LabelMap;
+    auditCategory: LabelMap;
+    auditEventOutcome: LabelMap;
+    auditCallOutcome: LabelMap;
+    /**
+     * A vocabulary added after this SDK release arrives camelised, with its map
+     * untouched.
+     */
+    [extra: string]: unknown;
+}
+export interface MetaCatalogTransitions {
+    quote: TransitionMap;
+    /** `return` is the wire name; it is not a reserved word in a property position. */
+    return: TransitionMap;
+    /**
+     * Forward order of the fulfillment lifecycle. `Cancelled` is terminal and
+     * UNRANKED, so it is absent — treat "no rank" as "no forward move", never 0.
+     */
+    fulfillmentRank: Record<string, number>;
+    [extra: string]: unknown;
+}
+export interface PermissionGroup {
+    label: string;
+    /** Four CRUD slots in order — Create, Read, Update, Delete — `null` where one does not apply. */
+    permissions: Array<string | null>;
+}
+export interface RoleTemplate {
+    /** Role codes are `{channelCode}-{suffix}`. */
+    suffix: string;
+    label: string;
+    description: string;
+    permissions: string[];
+}
+export interface ApiTokenTemplate {
+    key: string;
+    label: string;
+    description: string;
+    permissions: string[];
+}
+export interface MetaCatalogPermissions {
+    /** Every permission name the Admin API registers. */
+    catalog: string[];
+    /** The role-editor grid. */
+    groups: PermissionGroup[];
+    roleTemplates: RoleTemplate[];
+    tokenTemplates: ApiTokenTemplate[];
+    [extra: string]: unknown;
+}
+export interface PluginCatalogEntry {
+    key: string;
+    name: string;
+    group: string;
+    /** `system` plugins are always on; `external` ones need an entitlement. */
+    kind: string;
+}
+export interface MetaCatalogPlugins {
+    catalog: PluginCatalogEntry[];
+    groupLabels: Record<string, string>;
+    [extra: string]: unknown;
+}
+export interface MetaCatalog {
+    /**
+     * A short hash of everything else. It changes only when the catalog's content
+     * does, so it is safe to cache against indefinitely — this client does.
+     */
+    version: string;
+    labels: MetaCatalogLabels;
+    transitions: MetaCatalogTransitions;
+    permissions: MetaCatalogPermissions;
+    plugins: MetaCatalogPlugins;
+    /**
+     * Draft 2020-12 schemas for the opaque `Channel.customFields` columns, keyed
+     * by SETTING NAME — `social_links`, `order_status_rules`, … — which stay in
+     * their wire spelling because they are identifiers, not structure.
+     *
+     * Two things each schema does not say out loud: it describes the DECODED
+     * value while the column stores `JSON.stringify` of it, and its property
+     * names are the camelCase keys really stored inside (`targetState`), not DTO
+     * shape.
+     */
+    settingsSchemas: Record<string, JsonSchema>;
+    /**
+     * A member added after this SDK release arrives with its NAME camelised and
+     * its contents untouched — the half that matters, since a member this build
+     * has never seen is the one nothing else would protect.
+     */
+    [extra: string]: unknown;
+}
+export interface MetaModule {
+    /**
+     * The platform's labels, state machines, permission and plugin catalogs and
+     * settings schemas.
+     *
+     * Fetched once per client and then served from memory: the document changes
+     * only when the platform is redeployed, and its `version` says so. Concurrent
+     * first calls share one request, and each caller's `signal` cancels only its
+     * own wait — never the shared request, and never anyone else's. A client
+     * derived with `withTenant` has its own cache; the catalog is the same for
+     * every tenant, so that costs one extra request and never a wrong answer.
+     */
+    catalog(options?: Call): Promise<MetaCatalog>;
+    /**
+     * Fetch it again, ignoring the cache — for a long-lived process that wants to
+     * pick up a redeploy without restarting.
+     *
+     * When the version comes back unchanged the CACHED OBJECT is kept, so a
+     * consumer holding a reference can tell by identity alone whether the
+     * platform has been redeployed under it.
+     */
+    refresh(options?: Call): Promise<MetaCatalog>;
+}
+/**
+ * Rename the group names inside `labels`/`transitions`/`permissions`/`plugins`
+ * and leave every value alone. A member this release does not know about is
+ * passed through whole — the transport has already camelised its name, and its
+ * contents were preserved, which is the half that carries data.
+ */
+export declare function projectCatalog(body: unknown): MetaCatalog;
+export declare function createMetaModule(transport: Transport): MetaModule;

package/dist/meta/index.js

@@ -0,0 +1,142 @@
+import { TransportError } from '@sixtyninecommerce/core';
+/**
+ * A set that contains every key.
+ *
+ * `Transport.rest` camelises every response key whose subtree is not preserved,
+ * and it renames a preserved key while leaving its VALUE untouched. Handing it
+ * this makes the conversion exactly one level deep: the catalog's top-level
+ * members are camelised (`settings_schemas` → `settingsSchemas`) and everything
+ * below them survives byte for byte.
+ *
+ * That matters more here than anywhere else in this SDK, because almost every
+ * value in this document is a map KEYED BY DATA — `items_received`,
+ * `past_due`, `order_status_rules`, a JSON Schema's own property names. A
+ * generic camelisation would rewrite all of them, and the damage would be
+ * invisible: `items_received` would simply read back as `itemsReceived` and
+ * match no state the platform has ever heard of.
+ *
+ * Naming a fixed list of members instead would leave a member added after this
+ * release unprotected — the one case where nobody is watching.
+ */
+class EveryKeySet extends Set {
+    has() {
+        return true;
+    }
+}
+const PRESERVE_EVERY_SUBTREE = new EveryKeySet();
+/**
+ * The members whose OWN keys are structure (group names), so those keys are
+ * camelised one level further. `settings_schemas` is deliberately not one of
+ * them: its keys name settings, which are data.
+ */
+const GROUPED_MEMBERS = new Set(['labels', 'transitions', 'permissions', 'plugins']);
+function snakeToCamel(key) {
+    return key.replace(/_+([a-z0-9])/g, (_match, char) => char.toUpperCase());
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function camelKeys(value) {
+    const out = {};
+    for (const [key, entry] of Object.entries(value))
+        out[snakeToCamel(key)] = entry;
+    return out;
+}
+/**
+ * Rename the group names inside `labels`/`transitions`/`permissions`/`plugins`
+ * and leave every value alone. A member this release does not know about is
+ * passed through whole — the transport has already camelised its name, and its
+ * contents were preserved, which is the half that carries data.
+ */
+export function projectCatalog(body) {
+    if (!isRecord(body)) {
+        // The transport already turned a non-2xx into a PlatformError, so anything
+        // that is not an object here is a service answering 200 with a body this
+        // module cannot read — worth saying plainly rather than crashing on
+        // `catalog.version` two frames later.
+        throw new TypeError('GET /meta/catalog did not answer with a JSON object');
+    }
+    const out = {};
+    for (const [member, value] of Object.entries(body)) {
+        // `member` arrives camelised from the transport. The four structural names
+        // are single words, so both spellings are the same — checked anyway, so a
+        // member that ever gains an underscore does not quietly stop being handled.
+        const structural = GROUPED_MEMBERS.has(member) || GROUPED_MEMBERS.has(snakeToCamel(member));
+        out[member] = structural && isRecord(value) ? camelKeys(value) : value;
+    }
+    return out;
+}
+function abortedError() {
+    return new TransportError({
+        code: 'REQUEST_ABORTED',
+        message: 'The request was aborted by the caller.',
+        status: 0,
+        service: 'plugins',
+        retryable: false,
+    });
+}
+/**
+ * Settle when `promise` does, or reject as soon as THIS caller's signal aborts.
+ *
+ * The shared request is deliberately not cancelled: the other callers waiting
+ * on it did not ask for that. The rejection is the same `REQUEST_ABORTED`
+ * TransportError the transport raises for a signal it owns, so a consumer
+ * branching on `error.code` cannot tell the two apart — and should not have to.
+ */
+function abortable(promise, signal) {
+    if (signal === undefined)
+        return promise;
+    if (signal.aborted) {
+        // Still attach a handler, or the shared request's own rejection becomes an
+        // unhandled one when this caller is the only waiter.
+        promise.catch(() => undefined);
+        return Promise.reject(abortedError());
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(abortedError());
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then(resolve, reject).finally(() => {
+            signal.removeEventListener('abort', onAbort);
+        });
+    });
+}
+export function createMetaModule(transport) {
+    let cached = null;
+    /** Shared by every caller that arrives while the first request is still out. */
+    let inFlight = null;
+    async function fetchCatalog(options) {
+        const body = await transport.rest('plugins', { method: 'GET', path: '/meta/catalog' }, { ...options, preserveKeys: PRESERVE_EVERY_SUBTREE });
+        const next = projectCatalog(body);
+        // Same version means the same document, so the object a consumer is already
+        // holding stays the one this client serves.
+        if (cached !== null && cached.version === next.version)
+            return cached;
+        cached = next;
+        return next;
+    }
+    return {
+        catalog(options) {
+            if (cached !== null)
+                return Promise.resolve(cached);
+            if (inFlight === null) {
+                // The SHARED request carries no caller's signal. One that did would let
+                // whichever consumer happened to arrive first cancel the catalog for
+                // every other consumer waiting on the same promise — and would leave
+                // every later caller's own `signal` silently inert, because it was
+                // never wired to the request it is waiting on.
+                // `createChannelResolver` shares its resolutions the same way, with a
+                // controller of its own.
+                const { signal: _ignored, ...shared } = options ?? {};
+                inFlight = fetchCatalog(shared).finally(() => {
+                    inFlight = null;
+                });
+            }
+            return abortable(inFlight, options?.signal);
+        },
+        refresh(options) {
+            // Not shared: one request per call, so the caller's signal cancels the
+            // request it actually owns.
+            return fetchCatalog(options);
+        },
+    };
+}

package/dist/tenant/retention.d.ts

@@ -0,0 +1,81 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/** One principal's standing claim that this store's data must not be destroyed. */
+export interface RetentionHold {
+    /** `api_token` or `user` — the kind of principal that placed it. */
+    holderType: string;
+    /** The api-token id or the user id. A token holds on its own behalf, never on its operator's. */
+    holderId: string;
+    reason: string;
+    /** ISO-8601. Restating a hold updates its reason and leaves this alone. */
+    placedAt: string;
+}
+export interface ChannelRetention {
+    channelId: string;
+    /**
+     * Free text, default `standard`. The platform stores it and does not
+     * interpret it: no schedule is attached to a class yet.
+     */
+    retentionClass: string;
+    /**
+     * A time-based hold, independent of {@link holds}. While it is in the future
+     * the store cannot be hard-deleted, with no holder involved.
+     */
+    holdUntil: string | null;
+    holds: RetentionHold[];
+}
+/**
+ * The WHOLE policy, not a patch. Omitting `holdUntil` CLEARS it — that is the
+ * mutation's own PUT semantics, not something this SDK adds. Holder holds are
+ * untouched either way.
+ */
+export interface SetRetentionInput {
+    retentionClass: string;
+    /** ISO-8601 with an explicit offset. Omit or pass null to clear the time-based hold. */
+    holdUntil?: string | null;
+}
+/**
+ * Retention class and legal holds for the ACTIVE channel (`admin.tenant.retention`).
+ *
+ * No channel argument anywhere: these read and write the tenant the client is
+ * scoped to, which is what lets a tenant-scoped API token hold its own store.
+ * Reading needs `ReadSettings`, writing `UpdateSettings`.
+ *
+ * **Coded refusals**, all delivered as GraphQL errors with `extensions.code`
+ * and mapped by `core` onto the error hierarchy:
+ * - `RETENTION_HOLD_ACTIVE` → {@link BusinessRuleError}: `hardDeleteChannel`
+ *   refused because a hold stands. It is thrown by the delete, not by these
+ *   methods.
+ * - `RETENTION_HOLD_NOT_YOURS` → {@link PermissionDeniedError}: `release()`
+ *   called by a principal that holds none while another's hold stands. A
+ *   SuperAdmin overrides and releases every hold.
+ * - `RETENTION_INPUT_INVALID` → {@link ValidationError}: an empty or
+ *   over-long class, or a `holdUntil` that is not an ISO-8601 instant.
+ *
+ * A CLOSED store answers 403 `CHANNEL_SOFT_DELETED` to almost everything — but
+ * not to these four for a SuperAdmin, which is the one exemption that makes a
+ * hold usable at the moment it matters (a store must be closed before it can be
+ * hard-deleted). A merchant has to reopen the store first.
+ */
+export interface RetentionModule {
+    /** The active channel's retention state. A channel never configured answers the defaults. */
+    get(options?: Call): Promise<ChannelRetention>;
+    set(input: SetRetentionInput, options?: Call): Promise<ChannelRetention>;
+    /**
+     * Place the CALLING principal's hold. Idempotent per holder: restating
+     * updates the reason and leaves `placedAt` where it was.
+     */
+    hold(reason: string, options?: Call): Promise<ChannelRetention>;
+    /**
+     * Release the calling principal's own hold. Releasing when nothing is held is
+     * a no-op; a caller holding none while somebody else's hold stands is refused
+     * with `RETENTION_HOLD_NOT_YOURS` unless it is a SuperAdmin, which releases
+     * every hold as an override.
+     */
+    release(reason: string, options?: Call): Promise<ChannelRetention>;
+}
+export declare const RETENTION_QUERY = "\n  query ChannelRetention {\n    channelRetention { \n  channelId\n  retentionClass\n  holdUntil\n  holds {\n    holderType\n    holderId\n    reason\n    placedAt\n  }\n }\n  }\n";
+export declare const SET_RETENTION_MUTATION = "\n  mutation SetChannelRetention($retentionClass: String!, $holdUntil: DateTime) {\n    setChannelRetention(retentionClass: $retentionClass, holdUntil: $holdUntil) {\n      \n  channelId\n  retentionClass\n  holdUntil\n  holds {\n    holderType\n    holderId\n    reason\n    placedAt\n  }\n\n    }\n  }\n";
+export declare const PLACE_HOLD_MUTATION = "\n  mutation PlaceRetentionHold($reason: String!) {\n    placeRetentionHold(reason: $reason) { \n  channelId\n  retentionClass\n  holdUntil\n  holds {\n    holderType\n    holderId\n    reason\n    placedAt\n  }\n }\n  }\n";
+export declare const RELEASE_HOLD_MUTATION = "\n  mutation ReleaseRetentionHold($reason: String!) {\n    releaseRetentionHold(reason: $reason) { \n  channelId\n  retentionClass\n  holdUntil\n  holds {\n    holderType\n    holderId\n    reason\n    placedAt\n  }\n }\n  }\n";
+export declare function createRetentionModule(transport: Transport): RetentionModule;

package/dist/tenant/retention.js

@@ -0,0 +1,61 @@
+const RETENTION_FIELDS = /* GraphQL */ `
+  channelId
+  retentionClass
+  holdUntil
+  holds {
+    holderType
+    holderId
+    reason
+    placedAt
+  }
+`;
+export const RETENTION_QUERY = /* GraphQL */ `
+  query ChannelRetention {
+    channelRetention { ${RETENTION_FIELDS} }
+  }
+`;
+export const SET_RETENTION_MUTATION = /* GraphQL */ `
+  mutation SetChannelRetention($retentionClass: String!, $holdUntil: DateTime) {
+    setChannelRetention(retentionClass: $retentionClass, holdUntil: $holdUntil) {
+      ${RETENTION_FIELDS}
+    }
+  }
+`;
+export const PLACE_HOLD_MUTATION = /* GraphQL */ `
+  mutation PlaceRetentionHold($reason: String!) {
+    placeRetentionHold(reason: $reason) { ${RETENTION_FIELDS} }
+  }
+`;
+export const RELEASE_HOLD_MUTATION = /* GraphQL */ `
+  mutation ReleaseRetentionHold($reason: String!) {
+    releaseRetentionHold(reason: $reason) { ${RETENTION_FIELDS} }
+  }
+`;
+export function createRetentionModule(transport) {
+    return {
+        async get(options) {
+            const data = await transport.graphql({ api: 'admin', query: RETENTION_QUERY }, options);
+            return data.channelRetention;
+        },
+        async set(input, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: SET_RETENTION_MUTATION,
+                // `holdUntil` is sent as null when the caller omits it, on purpose:
+                // this mutation states the whole policy, so "not mentioned" and
+                // "cleared" are the same thing and hiding that behind an absent
+                // variable would only make the wire disagree with the signature.
+                variables: { retentionClass: input.retentionClass, holdUntil: input.holdUntil ?? null },
+            }, options);
+            return data.setChannelRetention;
+        },
+        async hold(reason, options) {
+            const data = await transport.graphql({ api: 'admin', query: PLACE_HOLD_MUTATION, variables: { reason } }, options);
+            return data.placeRetentionHold;
+        },
+        async release(reason, options) {
+            const data = await transport.graphql({ api: 'admin', query: RELEASE_HOLD_MUTATION, variables: { reason } }, options);
+            return data.releaseRetentionHold;
+        },
+    };
+}

package/dist/types.d.ts

@@ -68,7 +68,14 @@ export interface WhoAmI {
         code: string;
         permissions: string[];
     }>;
-    /** Null means unrestricted — location restriction is not implemented yet. */
+    /**
+     * The stock locations this credential may address, or null when it is
+     * unrestricted — a human session is always null.
+     *
+     * The plugins `GET /me` projection hardcoded null for every principal until
+     * 2026-09-16; a server older than that describes a restricted token as
+     * unrestricted, and `apiTokens.list()` is the reliable read against one.
+     */
     locations: string[] | null;
     /** Effective permissions on the ACTIVE channel, not the union of all of them. */
     permissions: string[];
@@ -83,6 +90,17 @@ export interface ApiToken {
     tokenPrefix: string;
     permissions: string[];
     channelId: string;
+    /**
+     * Stock locations this token may name in `x-location`
+     * (`TenantContext.location`). Null means unrestricted; the platform never
+     * stores an empty list.
+     *
+     * Enforced on `/admin-api` only today. The `x-location` header itself is
+     * checked on both APIs — a location outside the request's channel is refused
+     * everywhere — but the per-token restriction is not yet mounted on
+     * `/shop-api`, because nothing consumes `req.locationId` there.
+     */
+    locationIds: string[] | null;
     /**
      * ISO-8601 instant, or null for a token that never expires — the Admin API
      * models `expiresAt` as nullable and the service returns null when neither
@@ -108,11 +126,28 @@ export interface CreateApiTokenInput {
     expiresInDays?: number;
     /** Defaults to the client's own tenant channel. */
     channelId?: string;
+    /**
+     * Restrict the token to these stock locations: it may then only send an
+     * `x-location` naming one of them, and each id must belong to the token's
+     * channel.
+     *
+     * Omit or pass null to leave it unrestricted. An EMPTY list is refused with
+     * `INVALID_LOCATION_RESTRICTION` (a `ValidationError`) — "allowed nowhere" is
+     * never what a caller means — and an id outside the token's channel with
+     * `LOCATION_NOT_IN_CHANNEL`.
+     */
+    locationIds?: string[] | null;
 }
 /** Expiry is absent on purpose: it is fixed at creation (ADR 2026-07-29). */
 export interface UpdateApiTokenInput {
     name?: string;
     permissions?: string[];
     templateKeys?: string[];
+    /**
+     * Replace the location restriction. Omit to leave it as it is; null lifts it
+     * entirely. An empty list is refused with `INVALID_LOCATION_RESTRICTION`, as
+     * on create.
+     */
+    locationIds?: string[] | null;
 }
 export type { ChannelInfo, TenantContext, TenantScope };

package/package.json

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