@sixtyninecommerce/admin 0.8.0 → 0.10.0

package/dist/tenant/settings-sources.d.ts

@@ -0,0 +1,103 @@
+import { type Transport } from '@sixtyninecommerce/core';
+import { type AssetFile } from '../catalog/assets.js';
+import type { Call } from '../types.js';
+/**
+ * The settings groups a member store can take from its organization (multi-region spec §5.3), in
+ * the engine's catalog order. The catalog only grows, so a newer engine may answer a group this
+ * SDK does not name yet: every field and argument that carries a group also accepts any string.
+ */
+export declare const SETTINGS_GROUPS: readonly ["settings.email", "settings.branding", "settings.returns", "settings.reviews", "settings.quotes", "settings.age_verification", "settings.tax_display", "settings.numbering_formats", "settings.seo"];
+export type SettingsGroup = (typeof SETTINGS_GROUPS)[number];
+/** Whose values a group reads: the store's own, or its organization's. */
+export type SettingsSourceKind = 'channel' | 'organization';
+/**
+ * Where one settings group of the active store comes from.
+ *
+ * The three states a settings page shows:
+ * - **Managed by the organization** — `locked`. The store reads the organization's values and
+ *   cannot keep its own; `override` and `inherit` are refused.
+ * - **Inherited from the organization** — `inheritable && !overridden`. `override` makes the
+ *   store keep its own values, starting from a copy of the organization's.
+ * - **Overridden** — `inheritable && overridden`. `inherit` goes back to the organization's.
+ *
+ * Anything else (`!inheritable && !locked`) is the store's own setting with no organization
+ * behind it: a store outside any organization, or a group its organization does not share.
+ */
+export interface ChannelSettingsSource {
+    group: SettingsGroup | (string & {});
+    /** A string on the wire: a newer engine may answer a source this SDK does not name yet. */
+    source: SettingsSourceKind | (string & {});
+    /** The organization locked the group: the store reads its values and cannot keep its own. */
+    locked: boolean;
+    /** The store keeps its own values for the group. A lock outranks it. */
+    overridden: boolean;
+    /** The organization shares the group without locking it, so the store may inherit or override. */
+    inheritable: boolean;
+    /** The store's organization. Null for a store outside any organization. */
+    organizationName: string | null;
+    /**
+     * The group's effective values, keyed by channel custom field name, read from the channel
+     * `source` names. Null for `settings.email` and `settings.numbering_formats`, which live
+     * outside the channel: their own reads (`tenant.notifications`, the numbering configs) already
+     * answer the effective values.
+     */
+    values: Record<string, unknown> | null;
+}
+/**
+ * `admin.tenant.settingsSources` — where each settings group of the ACTIVE store comes from, and
+ * the store's choice to keep its own values for a group (`override`) or take its organization's
+ * (`inherit`). No channel argument: a tenant-scoped credential reaches its own store only. A
+ * SuperAdmin reads any store the same way, with that store as the tenant.
+ *
+ * `list` needs any permission on the store beyond `Authenticated`. `override` and `inherit` need
+ * `UpdateChannel`, or `UpdateSettings` for `settings.email` and `settings.numbering_formats`. Both
+ * answer the group's state after the call and are safe to repeat: a second call changes nothing.
+ * They are Admin API mutations, so an idempotency key deduplicates nothing.
+ *
+ * **Coded refusals**, GraphQL errors mapped by `core`:
+ * - `MANAGED_BY_ORGANIZATION` → {@link BusinessRuleError} (422): the organization locked the
+ *   group. SuperAdmins are refused too.
+ * - `ORGANIZATION_SETTINGS_NOT_A_MEMBER` → {@link BusinessRuleError} (422): the store is in no
+ *   organization, or it is an organization's own workspace.
+ * - `ORGANIZATION_SETTINGS_GROUP_INVALID` → {@link ValidationError} (400): not a group the engine
+ *   knows. A blank group is refused the same way before anything is sent.
+ * - `FORBIDDEN` → {@link PermissionDeniedError} (403): the credential lacks the permission.
+ *
+ * While a store inherits a group, `override` it before changing its values. A platform release
+ * that guards settings writes refuses a write to an inherited group (for example `updateChannel`
+ * for `settings.returns`) with `ORGANIZATION_SETTINGS_INHERITED` ({@link BusinessRuleError},
+ * 422). An engine without that guard accepts the write, but the group still resolves to the
+ * organization's values.
+ */
+export interface SettingsSourcesModule {
+    /** Every settings group of the active store, in catalog order. */
+    list(call?: Call): Promise<ChannelSettingsSource[]>;
+    /**
+     * The store keeps its own values for `group` from now on. When it inherited the group, it
+     * starts from a copy of the organization's current values, so nothing changes for its
+     * customers. On a group the organization does not share, it only records the choice: the store
+     * keeps its values if the organization starts sharing the group later.
+     */
+    override(group: SettingsGroup | (string & {}), call?: Call): Promise<ChannelSettingsSource>;
+    /**
+     * The store goes back to its organization's values for `group`. Its own values stay stored but
+     * unused; a later `override` starts from a fresh copy of the organization's, not from them.
+     */
+    inherit(group: SettingsGroup | (string & {}), call?: Call): Promise<ChannelSettingsSource>;
+    /**
+     * The assets `group` uses for the active store, such as the logos and favicon of
+     * `settings.branding`, read from the channel its values come from. While the store inherits
+     * the group those are its organization's images, which the store's own library does not hold
+     * (`catalog.assets.get` answers null for them). Only assets the group's values name, in no
+     * particular order; empty for a group without images. Same permission as `list`, and an
+     * unknown group is refused like `override`'s. They carry no `catalogueOwnership`: a settings
+     * image is never edited from here, and leaving it out keeps this read working against an
+     * engine older than that field.
+     */
+    assets(group: SettingsGroup | (string & {}), call?: Call): Promise<AssetFile[]>;
+}
+export declare const CHANNEL_SETTINGS_SOURCES_QUERY = "\n  query ChannelSettingsSources {\n    channelSettingsSources { \n  group\n  source\n  locked\n  overridden\n  inheritable\n  organizationName\n  values\n }\n  }\n";
+export declare const CHANNEL_SETTINGS_ASSETS_QUERY = "\n  query ChannelSettingsAssets($group: String!) {\n    channelSettingsAssets(group: $group) { \n  id\n  createdAt\n  updatedAt\n  name\n  type\n  mimeType\n  fileSize\n  width\n  height\n  source\n  preview\n  focalPoint {\n    x\n    y\n  }\n  tags {\n    value\n  }\n }\n  }\n";
+export declare const OVERRIDE_ORGANIZATION_SETTINGS_MUTATION = "\n  mutation OverrideOrganizationSettings($group: String!) {\n    overrideOrganizationSettings(group: $group) { \n  group\n  source\n  locked\n  overridden\n  inheritable\n  organizationName\n  values\n }\n  }\n";
+export declare const INHERIT_ORGANIZATION_SETTINGS_MUTATION = "\n  mutation InheritOrganizationSettings($group: String!) {\n    inheritOrganizationSettings(group: $group) { \n  group\n  source\n  locked\n  overridden\n  inheritable\n  organizationName\n  values\n }\n  }\n";
+export declare function createSettingsSourcesModule(transport: Transport): SettingsSourcesModule;

package/dist/tenant/settings-sources.js

@@ -0,0 +1,92 @@
+import { ValidationError } from '@sixtyninecommerce/core';
+import { ASSET_FILE_FIELDS, toAsset } from '../catalog/assets.js';
+/**
+ * The settings groups a member store can take from its organization (multi-region spec §5.3), in
+ * the engine's catalog order. The catalog only grows, so a newer engine may answer a group this
+ * SDK does not name yet: every field and argument that carries a group also accepts any string.
+ */
+export const SETTINGS_GROUPS = [
+    'settings.email',
+    'settings.branding',
+    'settings.returns',
+    'settings.reviews',
+    'settings.quotes',
+    'settings.age_verification',
+    'settings.tax_display',
+    'settings.numbering_formats',
+    'settings.seo',
+];
+const SOURCE_FIELDS = /* GraphQL */ `
+  group
+  source
+  locked
+  overridden
+  inheritable
+  organizationName
+  values
+`;
+export const CHANNEL_SETTINGS_SOURCES_QUERY = /* GraphQL */ `
+  query ChannelSettingsSources {
+    channelSettingsSources { ${SOURCE_FIELDS} }
+  }
+`;
+export const CHANNEL_SETTINGS_ASSETS_QUERY = /* GraphQL */ `
+  query ChannelSettingsAssets($group: String!) {
+    channelSettingsAssets(group: $group) { ${ASSET_FILE_FIELDS} }
+  }
+`;
+export const OVERRIDE_ORGANIZATION_SETTINGS_MUTATION = /* GraphQL */ `
+  mutation OverrideOrganizationSettings($group: String!) {
+    overrideOrganizationSettings(group: $group) { ${SOURCE_FIELDS} }
+  }
+`;
+export const INHERIT_ORGANIZATION_SETTINGS_MUTATION = /* GraphQL */ `
+  mutation InheritOrganizationSettings($group: String!) {
+    inheritOrganizationSettings(group: $group) { ${SOURCE_FIELDS} }
+  }
+`;
+/**
+ * Only the shape is checked here: which groups exist is the engine's call, so a group this SDK
+ * does not name still goes out. A blank one would come back `ORGANIZATION_SETTINGS_GROUP_INVALID`
+ * anyway (and a missing one as a GraphQL validation failure), so it is refused with that code now.
+ */
+function requireGroup(group) {
+    if (typeof group === 'string' && group.trim() !== '')
+        return group;
+    const code = 'ORGANIZATION_SETTINGS_GROUP_INVALID';
+    const message = `A settings group is required. Use one of: ${SETTINGS_GROUPS.join(', ')}.`;
+    throw new ValidationError({
+        code,
+        message,
+        status: 400,
+        service: 'vendure',
+        details: [{ field: 'group', code, message }],
+    });
+}
+export function createSettingsSourcesModule(transport) {
+    const write = async (field, query, group, call) => {
+        const variables = { group: requireGroup(group) };
+        const data = await transport.graphql({ api: 'admin', query, variables }, call);
+        return data[field];
+    };
+    return {
+        async list(call) {
+            const data = await transport.graphql({ api: 'admin', query: CHANNEL_SETTINGS_SOURCES_QUERY }, call);
+            return data.channelSettingsSources;
+        },
+        override(group, call) {
+            return write('overrideOrganizationSettings', OVERRIDE_ORGANIZATION_SETTINGS_MUTATION, group, call);
+        },
+        inherit(group, call) {
+            return write('inheritOrganizationSettings', INHERIT_ORGANIZATION_SETTINGS_MUTATION, group, call);
+        },
+        async assets(group, call) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: CHANNEL_SETTINGS_ASSETS_QUERY,
+                variables: { group: requireGroup(group) },
+            }, call);
+            return data.channelSettingsAssets.map((wire) => toAsset(wire));
+        },
+    };
+}

package/dist/types.d.ts

@@ -6,11 +6,19 @@ export interface Call {
      * 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
+     * `orders.surcharges.*`, plus `payments.providers.completeOnboarding`,
+     * `payments.providers.terminals.provision`, `stock.adjust`,
+     * `hooks.assignments.assign`, `customers.upsertByExternalRef`,
+     * `customers.groups.replaceMembers`, `pricing.coupons.apply` / `remove`,
+     * `orders.setLinePrices` / `setOneTimeDiscounts`,
+     * `pos.sale.applyCouponCode` / `removeCouponCode`, `storedValue.issue` / `adjust` /
+     * `redeem`, `apps.releaseFieldGroup`, `catalog.products.bulk` and `orders.bulk` (both mint
+     * one when omitted), and `catalog.products.save`. 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`.
+     * DIFFERENT request under the same key is refused with a `ConflictError`
+     * (409) coded `IDEMPOTENCY_CONFLICT`, and a repeat that arrives while the
+     * first call is still running with one coded `IDEMPOTENCY_IN_PROGRESS` —
+     * the same classes the REST services answer.
      *
      * Two deliberate exceptions on that list. `customers.erase` takes a key but
      * RECORDS it for provenance rather than keying on it: that mutation is
@@ -46,16 +54,26 @@ export interface ListOptions extends Call {
     after?: string;
     limit?: number;
 }
+/** One channel the signed-in principal holds a role on. */
+export interface MeChannel {
+    id: string;
+    code: string;
+    token: string;
+    permissions: string[];
+    /**
+     * `store` or `hub` — an organization's workspace, which is never a store. A
+     * string on the wire: read any value other than `hub` as a store. The
+     * bootstrap root (`__default_channel__`) reads `store`; tell it by its code.
+     */
+    channelKind: 'store' | 'hub' | (string & {});
+    /** The organization a store belongs to, or whose workspace a hub is; null for neither. */
+    organizationId: string | null;
+}
 /** The signed-in principal, as the Admin API reports it. */
 export interface Me {
     id: string;
     identifier: string;
-    channels: Array<{
-        id: string;
-        code: string;
-        token: string;
-        permissions: string[];
-    }>;
+    channels: MeChannel[];
     administrator: {
         id: string;
         firstName: string;
@@ -85,6 +103,15 @@ export interface WhoAmI {
         id: string;
         slug: string;
         name: string;
+        /**
+         * The customer-data level this installation reads at — its approval,
+         * lowered to what the app declares now (a raise waits for the merchant's
+         * approval; a drop applies at once). Below `full` the Admin API blanks the
+         * customer fields it withholds (see `Customer.redacted`) and refuses a
+         * filter, sort or search on them (`CUSTOMER_DATA_NOT_GRANTED`). Absent from
+         * a server that predates it.
+         */
+        customerData?: 'none' | 'identity' | 'full';
     } | null;
     /** Present only for `kind: 'app_installation'`; null otherwise. */
     installation: {
@@ -122,6 +149,13 @@ export interface WhoAmI {
     locations: string[] | null;
     /** Effective permissions on the ACTIVE channel, not the union of all of them. */
     permissions: string[];
+    /**
+     * The field groups this credential owns on its store (`price`, `stock`, `product_details`,
+     * `customer_details`): an API token's or an app installation's. Null for a human session,
+     * which never owns one, and absent or null from a server that predates it. While a group is
+     * owned, other writers will be refused it.
+     */
+    fieldOwnership?: string[] | null;
     /** Connected plugin-catalogue keys for the active channel. */
     entitlements: string[];
     /** Reserved for per-token rate limits; always null until they exist. */
@@ -153,12 +187,40 @@ export interface ApiToken {
     lastUsedAt: string | null;
     revokedAt: string | null;
     createdAt: string;
+    /**
+     * The field groups this token owns on its store, by key: `price` (Price), `stock` (Stock),
+     * `product_details` (Product details), `customer_details` (Customer details). A store hands
+     * each group to one app or token at a time (`tenant.fieldGroupOwners()`); empty when it owns
+     * none.
+     */
+    fieldOwnership: string[];
 }
+/**
+ * The field-group grant on `apiTokens.create` / `update` (and on `apps.install` /
+ * `approveConsent`) is judged by the engine, which refuses with:
+ * - `FIELD_GROUP_INVALID` (`ValidationError`) — a value that is not one of the four keys;
+ * - `FIELD_GROUP_PERMISSION_MISSING` (`BusinessRuleError`) — the token (or app) holds no
+ *   permission that changes that group's data: Price and Product details need
+ *   `UpdateCatalog` or `UpdateProduct`, Stock one of those or `AdjustStock` or
+ *   `UpdateStockLocation`, Customer details `UpdateCustomer`;
+ * - `FIELD_GROUP_GRANT_NOT_ALLOWED` (`PermissionDeniedError`) — you cannot change that data
+ *   yourself;
+ * - `FIELD_GROUP_OWNER_CONFLICT` (`ConflictError`) — another app or token owns it on the store
+ *   (release it there first, `apps.releaseFieldGroup`);
+ * - `FIELD_GROUP_ERP_SYNCED` (`BusinessRuleError`) — a built-in writer writes it into the
+ *   store: Exact Online (all four groups), or the store's organization (Price and Product
+ *   details). `tenant.fieldGroupSyncSources()` lists them.
+ */
+export type FieldGroupGrantRefusalCode = 'FIELD_GROUP_INVALID' | 'FIELD_GROUP_PERMISSION_MISSING' | 'FIELD_GROUP_GRANT_NOT_ALLOWED' | 'FIELD_GROUP_OWNER_CONFLICT' | 'FIELD_GROUP_ERP_SYNCED';
 export interface CreateApiTokenInput {
     name: string;
     /** Explicit grants. Union with whatever `templateKeys` expands to. */
     permissions?: string[];
-    /** Named presets from the platform's permission catalogue. */
+    /**
+     * Named presets from the platform's permission catalogue. A preset marked
+     * `sandbox` in `meta.catalog()` (`sandbox-full`) is minted on a sandbox store
+     * only; elsewhere the engine refuses it with `SANDBOX_ONLY_TEMPLATE`.
+     */
     templateKeys?: string[];
     /**
      * ISO-8601 instant WITH an offset; the engine refuses a past date. Wins over
@@ -180,6 +242,11 @@ export interface CreateApiTokenInput {
      * `LOCATION_NOT_IN_CHANNEL`.
      */
     locationIds?: string[] | null;
+    /**
+     * Field groups the token will own on its store, by key (see `ApiToken.fieldOwnership`).
+     * Omit for none. Refusals: {@link FieldGroupGrantRefusalCode}.
+     */
+    fieldOwnership?: string[] | null;
 }
 /** Expiry is absent on purpose: it is fixed at creation (ADR 2026-07-29). */
 export interface UpdateApiTokenInput {
@@ -192,5 +259,13 @@ export interface UpdateApiTokenInput {
      * on create.
      */
     locationIds?: string[] | null;
+    /**
+     * Replace the field groups the token owns. Omit or pass null to keep them (a group the
+     * token's new permissions cannot change is dropped); `[]` releases them all. A group the
+     * token does not own yet is judged as on create ({@link FieldGroupGrantRefusalCode}); one it
+     * owns already is kept as it is. To release one group from any owner in one step, use
+     * `apps.releaseFieldGroup`.
+     */
+    fieldOwnership?: string[] | null;
 }
 export type { ChannelInfo, TenantContext, TenantScope };

package/dist/uploads/index.d.ts

@@ -1,15 +1,19 @@
 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.
+ * What an upload is for. It decides which permission stages it, WHICH BUCKET it
+ * lands in, 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.
+ * - `asset` — a media file for the CMS library. It lands in the public asset
+ *   bucket, which is what an asset is for: anything in it is readable by path.
+ * - `bulk` — a JSONL file for `admin.bulk.import`. It lands in PRIVATE storage,
+ *   because a bulk file is a store's customers and orders, and it is reachable
+ *   only through a signed link this platform mints.
+ *
+ * `document` (an order attachment) arrives with the call that consumes it, with
+ * its own storage decision.
  */
-export type UploadPurpose = 'asset';
+export type UploadPurpose = 'asset' | 'bulk';
 export type UploadStatus = 'staged' | 'consumed' | 'expired';
 export interface StagedUpload {
     id: string;

package/dist/users/index.d.ts

@@ -0,0 +1,104 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/**
+ * What `users.ensure` did. A newer engine may name an outcome this SDK does not know yet; it is
+ * passed through, lower-cased, rather than dropped.
+ */
+export type EnsureUserOutcome = 'created' | 'attached' | 'restored' | 'unchanged';
+/**
+ * One role, by store role template (`admin`, `orders`, `warehouse`, `catalog`, `content`,
+ * `viewer`: the store's `<store code>-<template>` role, created from the template the first time
+ * a store needs it) or by the id of a role of the active store.
+ */
+export type UserRoleRequest = {
+    template: string;
+} | {
+    roleId: string;
+};
+export interface EnsureUserInput {
+    /** The person's login. Compared and stored lower-cased. */
+    emailAddress: string;
+    /** Only for a new account; defaults to the part of the address before the `@`. */
+    firstName?: string;
+    /** Only for a new account. */
+    lastName?: string;
+    /**
+     * The person's roles in the active store, at least one and at most ten. Their other roles of
+     * this store are replaced; roles in other stores, and roles spanning several stores (an
+     * organization's), are kept.
+     */
+    roles: UserRoleRequest[];
+}
+/** A staff member as these methods answer them. */
+export interface StaffUser {
+    id: string;
+    firstName: string;
+    lastName: string;
+    emailAddress: string;
+    /** Every role the account holds, in every store. */
+    roles: Array<{
+        id: string;
+        code: string;
+    }>;
+}
+export interface EnsureUserResult {
+    outcome: EnsureUserOutcome | (string & {});
+    administrator: StaffUser;
+    /** Whether an invitation (a link to set a password) was mailed to the address. */
+    invitationSent: boolean;
+}
+export interface UpdateUserInput {
+    /** The administrator's id. */
+    id: string;
+    firstName?: string;
+    lastName?: string;
+    /** The login email: refused to an API token (`TOKEN_CREDENTIAL_NOT_ALLOWED`). */
+    emailAddress?: string;
+}
+/**
+ * `admin.users` — the active store's staff (headless spec §7 `users.ensure`). Store-only: an
+ * organization's workspace refuses `ensure` with `ORGANIZATION_WORKSPACE_NOT_A_STORE` (422),
+ * because its `<code>-admin` role IS the organization admin role.
+ */
+export interface UsersModule {
+    /**
+     * Bring a person to exactly these roles in the active store, as one call that can be repeated:
+     *
+     * - `created`: a new address; an account is made and invited;
+     * - `attached`: an existing account; its roles of this store alone are replaced, every other
+     *   role kept. Invited when it is the person's first role here; someone who already works in
+     *   the store and only changes role is not mailed;
+     * - `restored`: a removed member of this store; brought back with these roles and invited again;
+     * - `unchanged`: the account already holds exactly these roles here. Nothing is written, nothing
+     *   mailed, so a retry of a call whose answer was lost is always safe.
+     *
+     * Adding someone (a new account, a first role in the store, a removed member restored) needs
+     * `CreateAdministrator`, and so does a template role the store does not have yet (it is
+     * created); changing the roles of someone who already works here needs `UpdateAdministrator`
+     * (else `FORBIDDEN`, 403; without `CreateAdministrator` every address that is not a member here
+     * answers that same `FORBIDDEN`). The caller must hold every permission of every role handed out
+     * (`ROLE_CEILING_NOT_ALLOWED`, 403), and of the account it changes; an account it may not touch
+     * (another store's, one above the caller, a platform administrator's, an API token's or app's
+     * sign-in) is `ADMINISTRATOR_INVITE_NOT_ALLOWED` (403). An API token may only invite a NEW
+     * address, with roles within its own permissions and with no location restriction
+     * (`TOKEN_INVITE_NOT_ALLOWED`, 403); its repeat of an invite the account already satisfies
+     * answers `unchanged`. Other refusals: `ADMINISTRATOR_ENSURE_INPUT_INVALID` (400, `details`
+     * names each field), `ROLE_TEMPLATE_NOT_FOUND` (404), a role id the store does not hold
+     * `ENTITY_NOT_FOUND` (404), `INVITATION_EMAIL_NOT_SENT` (422: nothing was changed, repeat the
+     * call).
+     *
+     * Requires a platform release that serves `ensureAdministrator`; an older engine refuses the
+     * call before running it, as a GraphQL validation failure (`ValidationError` `BAD_REQUEST`, 400).
+     */
+    ensure(input: EnsureUserInput, call?: Call): Promise<EnsureUserResult>;
+    /**
+     * Change a staff member's names or login email (core `updateAdministrator`; roles go through
+     * `ensure`). Needs `UpdateAdministrator`, and every permission the person holds, in every store
+     * they work in (`ADMINISTRATOR_CEILING_NOT_ALLOWED` / `SHARED_ADMINISTRATOR_NOT_ALLOWED`, 403).
+     * Someone outside the active store answers `ENTITY_NOT_FOUND`.
+     */
+    update(input: UpdateUserInput, call?: Call): Promise<StaffUser>;
+}
+export declare const ENSURE_ADMINISTRATOR_MUTATION = "\n  mutation EnsureAdministrator($input: EnsureAdministratorInput!) {\n    ensureAdministrator(input: $input) {\n      outcome\n      invitationSent\n      administrator { \n  id\n  firstName\n  lastName\n  emailAddress\n  user {\n    roles {\n      id\n      code\n    }\n  }\n }\n    }\n  }\n";
+export declare const UPDATE_ADMINISTRATOR_MUTATION = "\n  mutation UpdateStaffUser($input: UpdateAdministratorInput!) {\n    updateAdministrator(input: $input) { \n  id\n  firstName\n  lastName\n  emailAddress\n  user {\n    roles {\n      id\n      code\n    }\n  }\n }\n  }\n";
+export declare function createUsersModule(transport: Transport): UsersModule;

package/dist/users/index.js

@@ -0,0 +1,80 @@
+const STAFF_USER_FIELDS = /* GraphQL */ `
+  id
+  firstName
+  lastName
+  emailAddress
+  user {
+    roles {
+      id
+      code
+    }
+  }
+`;
+export const ENSURE_ADMINISTRATOR_MUTATION = /* GraphQL */ `
+  mutation EnsureAdministrator($input: EnsureAdministratorInput!) {
+    ensureAdministrator(input: $input) {
+      outcome
+      invitationSent
+      administrator { ${STAFF_USER_FIELDS} }
+    }
+  }
+`;
+export const UPDATE_ADMINISTRATOR_MUTATION = /* GraphQL */ `
+  mutation UpdateStaffUser($input: UpdateAdministratorInput!) {
+    updateAdministrator(input: $input) { ${STAFF_USER_FIELDS} }
+  }
+`;
+function staffUserOf(wire) {
+    return {
+        id: wire.id,
+        firstName: wire.firstName,
+        lastName: wire.lastName,
+        emailAddress: wire.emailAddress,
+        roles: (wire.user?.roles ?? []).map((role) => ({ id: role.id, code: role.code })),
+    };
+}
+/** Only the keys the caller set: an absent name is "leave it", never "clear it". */
+function defined(input) {
+    return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined));
+}
+export function createUsersModule(transport) {
+    return {
+        async ensure(input, call) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: ENSURE_ADMINISTRATOR_MUTATION,
+                variables: {
+                    input: {
+                        ...defined({
+                            emailAddress: input.emailAddress,
+                            firstName: input.firstName,
+                            lastName: input.lastName,
+                        }),
+                        roles: input.roles.map((role) => 'template' in role ? { template: role.template } : { roleId: role.roleId }),
+                    },
+                },
+            }, call);
+            const result = data.ensureAdministrator;
+            return {
+                outcome: result.outcome.toLowerCase(),
+                administrator: staffUserOf(result.administrator),
+                invitationSent: result.invitationSent,
+            };
+        },
+        async update(input, call) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: UPDATE_ADMINISTRATOR_MUTATION,
+                variables: {
+                    input: defined({
+                        id: input.id,
+                        firstName: input.firstName,
+                        lastName: input.lastName,
+                        emailAddress: input.emailAddress,
+                    }),
+                },
+            }, call);
+            return staffUserOf(data.updateAdministrator);
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sixtyninecommerce/admin",
-  "version": "0.8.0",
+  "version": "0.10.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,10 +33,11 @@
     "access": "public"
   },
   "dependencies": {
-    "@sixtyninecommerce/core": "^0.4.0"
+    "@sixtyninecommerce/core": "^0.5.0"
   },
   "devDependencies": {
     "@types/node": "22.19.7",
+    "graphql": "16.14.0",
     "typescript": "5.9.3",
     "vitest": "4.1.6"
   },