@sixtyninecommerce/admin 0.8.0 → 0.9.0

package/dist/customers/index.d.ts

@@ -1,4 +1,6 @@
 import { type Page, type Transport } from '@sixtyninecommerce/core';
+import { type CatalogueOwnership } from '../catalog/types.js';
+import { type ComplianceRequest } from '../compliance/index.js';
 import type { Call, ListOptions } from '../types.js';
 /**
  * Customers — the commerce master record (headless spec §6.5).
@@ -16,6 +18,31 @@ import type { Call, ListOptions } from '../types.js';
  * 2. **`erase` is a scrub, not a delete.** It removes the person and keeps the
  *    record, the orders and the documents. It is the only destructive customer
  *    operation the platform has.
+ *
+ * ## Acting inside a customer's cart: `actAs`
+ *
+ * `actAs(customerId, { reason })` answers a trusted-agent session: a Shop API
+ * bearer for that customer, valid 15 minutes and never renewed. It is usable
+ * in exactly ONE way — as the customer token of a storefront client for the
+ * same store:
+ *
+ * ```ts
+ * const session = await admin.customers.actAs(customerId, { reason: 'Phone order' });
+ * const shop = await createStorefrontClient({
+ *   storeCode: 'my-store',
+ *   cdnUrl,
+ *   customerToken: session.token, // @sixtyninecommerce/client
+ * });
+ * await shop.commerce.addToCart(variantId, 2); // the customer's own cart
+ * await admin.customers.endAgentSession(session.id);
+ * ```
+ *
+ * The Admin API, the CMS and the plugins service all refuse it. On the Shop
+ * API it may run cart and checkout only; an address-book edit, a password or
+ * email change, order history beyond the active order, or anything else is
+ * refused with `PermissionDeniedError` `AGENT_SESSION_SCOPE`. Every order row
+ * it writes records the caller as `on_behalf_of`; the customer sees the order
+ * as their own.
  */
 export declare const CUSTOMER_FIELDS = "\n  id\n  createdAt\n  updatedAt\n  title\n  firstName\n  lastName\n  emailAddress\n  phoneNumber\n  groups {\n    id\n    name\n  }\n";
 export declare const CUSTOMER_ADDRESS_FIELDS = "\n  id\n  fullName\n  company\n  streetLine1\n  streetLine2\n  city\n  province\n  postalCode\n  country {\n    code\n    name\n  }\n  phoneNumber\n  defaultShippingAddress\n  defaultBillingAddress\n";
@@ -25,15 +52,48 @@ export declare const ADDRESSES_QUERY = "\n  query CustomerAddresses($id: ID!) {\
 /**
  * The CHANNEL-SCOPED creation mutation. See the module docblock — core
  * `createCustomer` is not an option, and this SDK exposes no path to it.
+ *
+ * No `password` argument: the server ignores one (and a later release refuses
+ * it with `CUSTOMER_PASSWORD_NOT_ALLOWED`), because staff and API tokens never
+ * set a customer's password. `invite` is how a customer gets one.
  */
-export declare const CREATE_MUTATION = "\n  mutation CreateChannelCustomer($input: CreateCustomerInput!, $password: String) {\n    createChannelCustomer(input: $input, password: $password) {\n      id\n      emailAddress\n      createdNew\n    }\n  }\n";
+export declare const CREATE_MUTATION = "\n  mutation CreateChannelCustomer($input: CreateCustomerInput!) {\n    createChannelCustomer(input: $input) {\n      id\n      emailAddress\n      createdNew\n    }\n  }\n";
 export declare const UPDATE_MUTATION = "\n  mutation UpdateCustomer($input: UpdateCustomerInput!) {\n    updateCustomer(input: $input) {\n      ... on Customer { \n  id\n  createdAt\n  updatedAt\n  title\n  firstName\n  lastName\n  emailAddress\n  phoneNumber\n  groups {\n    id\n    name\n  }\n }\n      ... on ErrorResult { errorCode message }\n    }\n  }\n";
 export declare const INVITE_MUTATION = "\n  mutation InviteCustomer($customerId: ID!, $mode: CustomerInviteMode) {\n    inviteCustomer(customerId: $customerId, mode: $mode) {\n      customerId\n      emailAddress\n      mode\n      sentAt\n    }\n  }\n";
 export declare const RESEND_INVITE_MUTATION = "\n  mutation ResendCustomerInvitation($customerId: ID!, $mode: CustomerInviteMode) {\n    resendCustomerInvitation(customerId: $customerId, mode: $mode) {\n      customerId\n      emailAddress\n      mode\n      sentAt\n    }\n  }\n";
+/**
+ * "Invite all trade customers" — the whole channel's B2B-group members in one
+ * call. Counts always come back; unless `dryRun`, a background job sends the
+ * invitations and `jobId` names it.
+ */
+export declare const INVITE_B2B_MUTATION = "\n  mutation InviteB2BCustomers($input: InviteB2BCustomersInput) {\n    inviteB2BCustomers(input: $input) {\n      dryRun\n      total\n      eligible\n      skippedHasPassword\n      skippedPending\n      skippedUnreachable\n      jobId\n    }\n  }\n";
 export declare const ERASE_MUTATION = "\n  mutation EraseCustomer(\n    $customerId: ID!\n    $reason: String!\n    $force: Boolean\n    $idempotencyKey: String\n  ) {\n    eraseCustomer(\n      customerId: $customerId\n      reason: $reason\n      force: $force\n      idempotencyKey: $idempotencyKey\n    ) {\n      customerId\n      erasedAt\n      ordersRetained\n      documentsRetained\n      forced\n      reason\n    }\n  }\n";
 export declare const ERASURE_QUERY = "\n  query CustomerErasure($customerId: ID!) {\n    customerErasure(customerId: $customerId) {\n      customerId\n      erasedAt\n      ordersRetained\n      documentsRetained\n      forced\n      reason\n    }\n  }\n";
+export declare const ACT_AS_MUTATION = "\n  mutation ActAsCustomer($customerId: ID!, $reason: String!) {\n    actAsCustomer(customerId: $customerId, reason: $reason) {\n      id\n      customerId\n      token\n      expiresAt\n    }\n  }\n";
+export declare const REQUEST_DATA_MUTATION = "\n  mutation RequestCustomerData($customerId: ID!, $reason: String!, $idempotencyKey: String) {\n    requestCustomerData(customerId: $customerId, reason: $reason, idempotencyKey: $idempotencyKey) {\n      \n  id\n  kind\n  subjectId\n  requestedBy\n  reason\n  requestedAt\n  dueAt\n  addressedInstallationIds\n  acknowledgements { id requestId installationId acknowledgedAt note }\n  overdueInstallationIds\n  overdue\n\n    }\n  }\n";
+export declare const END_AGENT_SESSION_MUTATION = "\n  mutation EndCustomerAgentSession($sessionId: ID!) {\n    endCustomerAgentSession(sessionId: $sessionId) {\n      id\n      customerId\n      revokedAt\n    }\n  }\n";
 export declare const ADD_TO_GROUP_MUTATION = "\n  mutation AddCustomersToGroup($customerGroupId: ID!, $customerIds: [ID!]!) {\n    addCustomersToGroup(customerGroupId: $customerGroupId, customerIds: $customerIds) {\n      id\n      name\n    }\n  }\n";
 export declare const REMOVE_FROM_GROUP_MUTATION = "\n  mutation RemoveCustomersFromGroup($customerGroupId: ID!, $customerIds: [ID!]!) {\n    removeCustomersFromGroup(customerGroupId: $customerGroupId, customerIds: $customerIds) {\n      id\n      name\n    }\n  }\n";
+/**
+ * External keys (incentives program decision 7): when another system is the customer master it
+ * addresses this store's customers and segments by its own keys. Every key is this store's: another
+ * store's key reads as one nobody filed. Each document is its own request, so a client ahead of the
+ * engine fails only that call, never the customer page.
+ */
+export declare const CUSTOMER_EXTERNAL_REF_FIELDS = "\n  id\n  createdAt\n  updatedAt\n  system\n  ref\n";
+export declare const EXTERNAL_KEYED_GROUP_FIELDS = "\n  id\n  name\n  externalKey\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n";
+export declare const BY_EXTERNAL_REF_QUERY = "\n  query CustomerByExternalRef($system: String!, $ref: String!) {\n    customerByExternalRef(system: $system, ref: $ref) { \n  id\n  createdAt\n  updatedAt\n  title\n  firstName\n  lastName\n  emailAddress\n  phoneNumber\n  groups {\n    id\n    name\n  }\n }\n  }\n";
+export declare const EXTERNAL_REFS_QUERY = "\n  query CustomerExternalRefs($id: ID!) {\n    customer(id: $id) {\n      id\n      externalRefs { \n  id\n  createdAt\n  updatedAt\n  system\n  ref\n }\n    }\n  }\n";
+export declare const UPSERT_BY_EXTERNAL_REF_MUTATION = "\n  mutation UpsertCustomerByExternalRef(\n    $input: UpsertCustomerByExternalRefInput!\n    $idempotencyKey: String\n  ) {\n    upsertCustomerByExternalRef(input: $input, idempotencyKey: $idempotencyKey) {\n      customer { \n  id\n  createdAt\n  updatedAt\n  title\n  firstName\n  lastName\n  emailAddress\n  phoneNumber\n  groups {\n    id\n    name\n  }\n }\n      created\n      matchedByEmail\n      updated\n    }\n  }\n";
+export declare const GROUP_BY_EXTERNAL_KEY_QUERY = "\n  query CustomerGroupByExternalKey($key: String!) {\n    customerGroupByExternalKey(key: $key) { \n  id\n  name\n  externalKey\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n }\n  }\n";
+/** A customer group as {@link CustomerGroupsModule.get} reads it. */
+export declare const CUSTOMER_GROUP_FIELDS = "\n  id\n  createdAt\n  updatedAt\n  name\n  externalKey\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n";
+export declare const CUSTOMER_GROUP_QUERY = "\n  query CustomerGroup($id: ID!) {\n    customerGroup(id: $id) { \n  id\n  createdAt\n  updatedAt\n  name\n  externalKey\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n }\n  }\n";
+export declare const GROUP_EXTERNAL_KEY_QUERY = "\n  query CustomerGroupExternalKey($id: ID!) {\n    customerGroup(id: $id) {\n      id\n      externalKey\n    }\n  }\n";
+export declare const UPSERT_GROUP_BY_EXTERNAL_KEY_MUTATION = "\n  mutation UpsertCustomerGroupByExternalKey($key: String!, $name: String!) {\n    upsertCustomerGroupByExternalKey(key: $key, name: $name) {\n      customerGroup { \n  id\n  name\n  externalKey\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n }\n      created\n      renamed\n    }\n  }\n";
+export declare const REPLACE_GROUP_MEMBERS_MUTATION = "\n  mutation ReplaceCustomerGroupMembers(\n    $key: String!\n    $customerExternalRefs: [CustomerExternalRefInput!]!\n    $idempotencyKey: String\n  ) {\n    replaceCustomerGroupMembers(\n      key: $key\n      customerExternalRefs: $customerExternalRefs\n      idempotencyKey: $idempotencyKey\n    ) {\n      customerGroup { \n  id\n  name\n  externalKey\n  \n  catalogueOwnership {\n    state\n    organizationName\n    editableHere\n  }\n\n }\n      memberCount\n      added\n      removed\n      unknownRefs {\n        system\n        ref\n      }\n    }\n  }\n";
+/** The most member keys one `customers.groups.replaceMembers` call takes. */
+export declare const MAX_REPLACE_GROUP_MEMBERS = 5000;
 export declare const CREATE_ADDRESS_MUTATION = "\n  mutation CreateCustomerAddress($customerId: ID!, $input: CreateAddressInput!) {\n    createCustomerAddress(customerId: $customerId, input: $input) {\n      \n  id\n  fullName\n  company\n  streetLine1\n  streetLine2\n  city\n  province\n  postalCode\n  country {\n    code\n    name\n  }\n  phoneNumber\n  defaultShippingAddress\n  defaultBillingAddress\n\n    }\n  }\n";
 export declare const UPDATE_ADDRESS_MUTATION = "\n  mutation UpdateCustomerAddress($input: UpdateAddressInput!) {\n    updateCustomerAddress(input: $input) { \n  id\n  fullName\n  company\n  streetLine1\n  streetLine2\n  city\n  province\n  postalCode\n  country {\n    code\n    name\n  }\n  phoneNumber\n  defaultShippingAddress\n  defaultBillingAddress\n }\n  }\n";
 export declare const DELETE_ADDRESS_MUTATION = "\n  mutation DeleteCustomerAddress($id: ID!) {\n    deleteCustomerAddress(id: $id) { success }\n  }\n";
@@ -41,6 +101,93 @@ export interface CustomerGroupRef {
     id: string;
     name: string;
 }
+/** Another system's key for a customer of this store. */
+export interface CustomerExternalRef {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    /** The master system's name: a lower-case slug such as `visos`. */
+    system: string;
+    /** The master system's own id for the customer, compared exactly. */
+    ref: string;
+    [extra: string]: unknown;
+}
+/** A customer key as sent: which system, and its id there. */
+export interface CustomerExternalRefKey {
+    system: string;
+    ref: string;
+}
+/**
+ * A customer as the master system holds it. Every field but the key is a PATCH: absent or `null`
+ * keeps what the store has.
+ */
+export interface UpsertCustomerByExternalRefInput {
+    /** A lower-case slug: letters, digits, `.`, `_`, `-`, at most 64 characters. */
+    system: string;
+    /** At most 255 characters; compared exactly, surrounding whitespace trimmed. */
+    ref: string;
+    /**
+     * Required when the store does not know the key yet. A customer of this store with this address
+     * (any letter case) is LINKED to the key rather than duplicated. On a customer the key already
+     * names, a changed address follows {@link UpdateCustomerInput.emailAddress}'s rules.
+     */
+    emailAddress?: string | null;
+    firstName?: string | null;
+    lastName?: string | null;
+    phoneNumber?: string | null;
+    title?: string | null;
+}
+/** What {@link CustomersModule.upsertByExternalRef} answers. */
+export interface UpsertedCustomer {
+    customer: Customer;
+    /** A customer was created for this store. */
+    created: boolean;
+    /** The key was unknown and linked to the store's existing customer with the address. */
+    matchedByEmail: boolean;
+    /** Fields of an existing customer were written. */
+    updated: boolean;
+}
+/** One of the store's customer groups, as {@link CustomerGroupsModule.get} answers it. */
+export interface CustomerGroup {
+    id: string;
+    /** ISO-8601 UTC. */
+    createdAt: string;
+    /** ISO-8601 UTC. */
+    updatedAt: string;
+    name: string;
+    /** This store's key for the group in the customer master, or `null` when no master keys it. */
+    externalKey: string | null;
+    /**
+     * The store's own group, or its organization's (shared while the organization shares
+     * `customer_groups`); see {@link CatalogueOwnership}. `editableHere` false: rename it in the
+     * workspace.
+     */
+    catalogueOwnership: CatalogueOwnership;
+}
+/** A customer group with this store's external key, or `null` for a group nobody keyed. */
+export interface ExternalKeyedCustomerGroup {
+    id: string;
+    name: string;
+    externalKey: string | null;
+    /** The store's own group, or its organization's; see {@link CatalogueOwnership}. */
+    catalogueOwnership: CatalogueOwnership;
+}
+/** What {@link CustomerGroupsModule.upsertByExternalKey} answers. */
+export interface UpsertedCustomerGroup {
+    customerGroup: ExternalKeyedCustomerGroup;
+    created: boolean;
+    renamed: boolean;
+}
+/** What {@link CustomerGroupsModule.replaceMembers} answers. */
+export interface ReplacedCustomerGroupMembers {
+    customerGroup: ExternalKeyedCustomerGroup;
+    /** The group's members in this store after the call. */
+    memberCount: number;
+    added: number;
+    removed: number;
+    /** Keys no customer of this store carries, in the order sent. Reported, never created. */
+    unknownRefs: CustomerExternalRefKey[];
+}
 export interface Customer {
     id: string;
     createdAt: string;
@@ -51,6 +198,14 @@ export interface Customer {
     emailAddress: string;
     phoneNumber: string | null;
     groups: CustomerGroupRef[];
+    /**
+     * Set when this customer was read by an app installation below `customerData:
+     * full`: the fields its level withholds came back blanked — `null`, or `""`
+     * where the field is never null (`firstName`, `lastName`, `emailAddress`). An
+     * empty string here means "not granted", not "none on record". Absent for a
+     * customer nothing was withheld from.
+     */
+    redacted?: true;
     /** Forward-compat: fields a later release adds arrive camelised and untouched. */
     [extra: string]: unknown;
 }
@@ -71,6 +226,12 @@ export interface CustomerAddress {
     defaultShippingAddress: boolean | null;
     defaultBillingAddress: boolean | null;
     [extra: string]: unknown;
+    /**
+     * Set when the caller's customer-data level blanked this address (an app
+     * installation below `full` reads only its country): `null`/`""` then means
+     * "not granted", not "none on record". Never write such an address back.
+     */
+    redacted?: true;
 }
 export interface CreateCustomerInput {
     emailAddress: string;
@@ -85,6 +246,23 @@ export interface UpdateCustomerInput {
     firstName?: string;
     lastName?: string;
     phoneNumber?: string;
+    /**
+     * A new address for the customer in THIS store. For a customer with an account, the store's
+     * customer (orders, addresses, groups, prices, credit, ERP links) moves to the account of the
+     * new address: the one that already exists for it on the platform, else a new one with no
+     * password. No account is ever renamed, nothing is mailed, and the old address stops signing in
+     * to this store; send `invite` for the new address to sign in. The customer's records in other
+     * stores keep their address and account. A guest customer (no account) simply gets the address.
+     * Sending the current address back unchanged (any letter case) is not a change and passes.
+     *
+     * Refused, for every caller: `PermissionDeniedError` `CUSTOMER_EMAIL_CHANGE_NOT_ALLOWED` for an
+     * erased customer (add a new customer instead), `PermissionDeniedError`
+     * `SHARED_CUSTOMER_NOT_ALLOWED` for one customer record another store holds too, and
+     * `BusinessRuleError` `EMAIL_ADDRESS_CONFLICT_ERROR` when something else in this store already
+     * answers to the address (another customer, or another account's sign-in), and
+     * `ValidationError` `CUSTOMER_EMAIL_INVALID` for a value that is not an email address given to a
+     * customer with an account, or any value longer than 255 characters.
+     */
     emailAddress?: string;
     customFields?: Record<string, unknown>;
 }
@@ -98,6 +276,11 @@ export interface CreatedCustomer {
      * whole point of the channel-scoped mutation.
      */
     createdNew: boolean;
+    /**
+     * Set when the caller's customer-data level blanked `emailAddress` (an app
+     * installation below `identity`): "" then means "not granted".
+     */
+    redacted?: true;
 }
 export type CustomerInviteMode = 'PASSWORD_SETUP' | 'MAGIC_LINK';
 export interface CustomerInvitation {
@@ -106,6 +289,32 @@ export interface CustomerInvitation {
     mode: CustomerInviteMode;
     sentAt: string;
 }
+export interface InviteB2BCustomersOptions extends Call {
+    /** Count only; send nothing and start no job. */
+    dryRun?: boolean;
+    /**
+     * Also invite customers who already hold a live, unexpired set-password link.
+     * Their link is re-sent, not replaced, so the one already in their inbox keeps
+     * working. Off by default: they are counted as `skippedPending` instead.
+     */
+    includePending?: boolean;
+}
+/** What {@link CustomersModule.inviteB2B} answers. */
+export interface InviteB2BCustomersResult {
+    dryRun: boolean;
+    /** B2B-group customers on this store, one per login account. */
+    total: number;
+    /** Customers who would be (dry run) or were queued for an invitation. */
+    eligible: number;
+    /** Already have a password. */
+    skippedHasPassword: number;
+    /** Hold a live, unexpired set-password link; always 0 with `includePending`. */
+    skippedPending: number;
+    /** No email address, a `*.invalid` placeholder address, or no login account. */
+    skippedUnreachable: number;
+    /** The background job sending the invitations; `null` on a dry run or when `eligible` is 0. */
+    jobId: string | null;
+}
 /** The record of an erasure. See {@link CustomersModule.erase}. */
 export interface CustomerErasureRecord {
     customerId: string;
@@ -137,6 +346,37 @@ export interface EraseCustomerOptions extends Call {
     /** Your own request id, recorded for provenance. */
     idempotencyKey?: string;
 }
+/** A trusted-agent session. See {@link CustomersModule.actAs}. */
+export interface CustomerAgentSession {
+    /** What {@link CustomersModule.endAgentSession} takes. */
+    id: string;
+    customerId: string;
+    /**
+     * The Shop API bearer, shown once. Pass it as `customerToken` to
+     * `createStorefrontClient` from `@sixtyninecommerce/client` — the only way it works.
+     */
+    token: string;
+    /** ISO-8601. Fixed: refused from this instant on, and nothing renews it. */
+    expiresAt: string;
+}
+/** The answer to {@link CustomersModule.endAgentSession}. */
+export interface EndedCustomerAgentSession {
+    id: string;
+    customerId: string;
+    /** ISO-8601. Ending an ended session answers the first end. */
+    revokedAt: string;
+}
+export interface RequestCustomerDataOptions extends Call {
+    /**
+     * Why — recorded on the request, never sent to apps, blanked if the customer
+     * is later erased. 1–1000 characters.
+     */
+    reason: string;
+}
+export interface ActAsCustomerOptions extends Call {
+    /** Why — stored on the session and required. Free text, 1–1000 characters. */
+    reason: string;
+}
 export interface CustomerAddressesModule {
     list(customerId: string, options?: Call): Promise<CustomerAddress[]>;
     create(customerId: string, input: Record<string, unknown>, options?: Call): Promise<CustomerAddress>;
@@ -146,20 +386,72 @@ export interface CustomerAddressesModule {
     delete(id: string, options?: Call): Promise<void>;
 }
 export interface CustomerGroupsModule {
-    /** Add customers to a group. Emits one `customer.group_changed` per customer. */
+    /**
+     * One of the ACTIVE store's customer groups by id, its `catalogueOwnership` included, or `null`
+     * for a group the store does not hold (another store's, a deleted one, an unknown id), the same
+     * for each, like every other entity `get` here. A badge shows `null` as "not found", never as
+     * the store's own group. An id that is not a uuid is refused before the engine looks with core's
+     * `ENTITY_NOT_FOUND`: branch on the `NotFoundError` class, not the code. Needs `ReadCustomer` or `ReadCustomerGroup`. Requires
+     * a platform release that serves `catalogueOwnership`: an older engine fails the call as a whole.
+     */
+    get(id: string, options?: Call): Promise<CustomerGroup | null>;
+    /**
+     * Add customers to a group. Emits one `customer.group_changed` per customer added; a customer
+     * already in the group is left as it is and emits nothing, so naming only members emits none.
+     */
     add(groupId: string, customerIds: string[], options?: Call): Promise<CustomerGroupRef>;
     remove(groupId: string, customerIds: string[], options?: Call): Promise<CustomerGroupRef>;
+    /** The store's group under the master system's segment key, or `null`. Needs `ReadCustomerGroup`. */
+    byExternalKey(key: string, options?: Call): Promise<ExternalKeyedCustomerGroup | null>;
+    /** This store's external key for a group, or `null` when no master keys it. */
+    externalKey(groupId: string, options?: Call): Promise<string | null>;
+    /**
+     * Create the store's group for a segment key, or rename the one it names. Twice is ONE group.
+     * Creating needs `CreateCustomerGroup`; renaming needs `UpdateCustomerGroup`, and for a group
+     * other stores hold too, that permission in each of them (`SHARED_CUSTOMER_GROUP_NOT_ALLOWED`).
+     * Renaming a group a member store holds from its organization's workspace is refused
+     * `MANAGED_BY_ORGANIZATION` (422 `BusinessRuleError`): rename it in the workspace
+     * (`catalogueOwnership.editableHere` is false).
+     */
+    upsertByExternalKey(key: string, name: string, options?: Call): Promise<UpsertedCustomerGroup>;
+    /**
+     * Make the group under `key` hold EXACTLY the customers these keys name, in one transaction.
+     * At most {@link MAX_REPLACE_GROUP_MEMBERS} keys (`CUSTOMER_GROUP_MEMBERS_TOO_MANY`); a key no
+     * customer of this store carries comes back in `unknownRefs` and is never created; only this
+     * store's customers are added or removed. Needs `UpdateCustomerGroup`. A repeat under the same
+     * `idempotencyKey` answers the first call. Emits one `customer.group_changed` per customer
+     * added or removed, and a promotion on the group follows on the order's next recalculation.
+     *
+     * Known limit: atomic against other replaces and upserts of the same key, not against
+     * `add`/`remove` (core's membership doors) running at the same moment, which do not take the
+     * key's lock: a membership edit made by hand meanwhile can survive the replace or be undone.
+     */
+    replaceMembers(key: string, customerExternalRefs: CustomerExternalRefKey[], options?: Call): Promise<ReplacedCustomerGroupMembers>;
 }
 export interface CustomersModule {
     list(options?: ListOptions): Promise<Page<Customer>>;
     get(id: string, options?: Call): Promise<Customer | null>;
     /**
-     * Create a customer ON THIS CHANNEL. Never creates credentials — `invite`
-     * does that.
+     * Create a customer ON THIS CHANNEL, with no usable login: the customer
+     * cannot sign in until they set a password through the link `invite` mails
+     * them (or sign in with a magic link). Staff and API tokens never set a
+     * customer's password, so there is no option for one.
+     */
+    create(input: CreateCustomerInput, options?: Call): Promise<CreatedCustomer>;
+    /**
+     * Update a customer of this store. A changed `emailAddress` of a customer with an account moves
+     * the store's customer to the account of the new address, and is refused for an erased customer
+     * (`CUSTOMER_EMAIL_CHANGE_NOT_ALLOWED`), for one record another store also holds
+     * (`SHARED_CUSTOMER_NOT_ALLOWED`), both `PermissionDeniedError`s, and for an address the store
+     * already uses (`EMAIL_ADDRESS_CONFLICT_ERROR`, a `BusinessRuleError`); see
+     * {@link UpdateCustomerInput.emailAddress}.
+     *
+     * While an app or API token owns Customer details on the store, a change of the customer's
+     * title, name, email address, phone number or VAT number by anyone else is refused
+     * `FIELD_GROUP_LOCKED` (`BusinessRuleError`); an unchanged value passes. So is adding,
+     * changing or removing one of their addresses (`addresses.*`), and deleting the customer.
+     * Creating a customer is never refused.
      */
-    create(input: CreateCustomerInput, options?: Call & {
-        password?: string;
-    }): Promise<CreatedCustomer>;
     update(id: string, input: UpdateCustomerInput, options?: Call): Promise<Customer>;
     /**
      * Mail the customer a way in: a set-password link, or a magic-link sign-in.
@@ -171,6 +463,26 @@ export interface CustomersModule {
         mode?: CustomerInviteMode;
         resend?: boolean;
     }): Promise<CustomerInvitation>;
+    /**
+     * Invite every trade (B2B) customer on this store to set a password: the
+     * members of the store's configured B2B customer groups, one per login
+     * account. Needs `UpdateCustomer`.
+     *
+     * Always answers the counts. Skipped, by reason: customers who already have a
+     * password, customers who cannot be reached (no email address, a `*.invalid`
+     * placeholder, no login account), and customers holding a live set-password
+     * link (unless `includePending`). With `dryRun` nothing is sent. Otherwise a
+     * background job sends the invitations one at a time, paced, and `jobId`
+     * names it; it checks every customer again when it reaches them, so what it
+     * finally sends can differ from `eligible`. Its result is
+     * `{ sent, skippedHasPassword, skippedPending, skippedUnreachable, failed }`,
+     * and one customer failing never stops the rest.
+     *
+     * Refused on the platform root channel, and — unless `dryRun` — when the store
+     * has no storefront URL or its customer-invitation email is switched off or
+     * has no recipient: the same refusals as {@link invite}.
+     */
+    inviteB2B(options?: InviteB2BCustomersOptions): Promise<InviteB2BCustomersResult>;
     /**
      * GDPR erasure: scrub the person, keep the record.
      *
@@ -187,17 +499,53 @@ export interface CustomersModule {
      * that name no customer at all, which is how an invoice email log kept an
      * erased person's address.
      *
-     * Refused while a retention hold is active (`RETENTION_HOLD_ACTIVE`), while
-     * the customer is party to an open unpaid order (`CUSTOMER_HAS_OPEN_ORDERS`;
+     * Vendure's own JOB PAYLOADS go too, classified per queue rather than by one
+     * verdict over a column that has forty-five shapes: a declared JSON path
+     * anchored on the customer id or their address; the whole serialized Express
+     * request clone of any job that is theirs, emptied rather than picked over
+     * because its body carries the GraphQL document the shopper sent; the session
+     * token and principal identifier of a job the erased person themselves
+     * triggered (a review or a magic-link login carries their own); and an
+     * exact-address sweep for the payloads whose contracts are open. A match by
+     * ADDRESS only reaches a row whose payload names this store's channel (the
+     * table has no channel column); a match by customer id reaches it whichever
+     * channel it names, because an id belongs to one person. A row that
+     * names them ONLY as a substring inside that document, with no id to anchor
+     * on, is left alone — a substring decision about personal data in a write
+     * path is what this feature's own security review forbade.
+     * Unbounded, because settled job rows are pruned by
+     * COUNT — the newest thousand survive indefinitely — and an unsettled row is
+     * never pruned at all. Two gaps, both stated: a job that is RUNNING at that
+     * instant holds its payload in memory and writes it back when it settles, and
+     * a job's RESULT is retained (a warehouse document job returns a storage key
+     * for a PDF that renders the shipping address).
+     *
+     * Refused while a legal hold placed with `placeRetentionHold` is active
+     * (`RETENTION_HOLD_ACTIVE`; the store's retention window, `holdUntil`, does
+     * not refuse), while the customer is party to an open unpaid order (`CUSTOMER_HAS_OPEN_ORDERS`;
      * a SuperAdmin may pass `force`), while they hold a subscription that has not
-     * ended (`CUSTOMER_HAS_ACTIVE_SUBSCRIPTIONS`), when their login is shared with
-     * another store on the platform (`CUSTOMER_SHARED_ACROSS_STORES`), and when
-     * the tenant context names the platform root channel rather than the
-     * customer's own (`CUSTOMER_ERASURE_CHANNEL_INVALID`).
+     * ended (`CUSTOMER_HAS_ACTIVE_SUBSCRIPTIONS`), while the store still holds
+     * their money as unapplied cash on their account
+     * (`CUSTOMER_HAS_UNAPPLIED_CASH`: pay it back or apply it to an invoice first
+     * and wait for the payout's refund to complete, `payments.accountCredit.list`
+     * shows what is held; `force` does not override it), when other stores on the
+     * platform hold them and the caller cannot delete customers in all of those
+     * stores (`CUSTOMER_SHARED_ACROSS_STORES`), and when the tenant context names
+     * the platform root channel rather than the customer's own
+     * (`CUSTOMER_ERASURE_CHANNEL_INVALID`).
+     *
+     * A customer other stores hold too (their login backs a customer there, or the
+     * row sits there too) is erased on EVERY one of those stores in the same call,
+     * because the login it scrubs is theirs as well. That takes a SuperAdmin, or
+     * `DeleteCustomer` on each of those stores. Every store's hold, unpaid orders
+     * and subscriptions are checked first (a refusal names the store that blocks),
+     * and each store gets its own record and `customer.deleted`. The answer is this
+     * store's record. When the login also backs a record on the platform root,
+     * outside any store, only a SuperAdmin may erase (same code, its own message).
      *
-     * `force` overrides the OPEN-ORDER refusal and nothing else. A live payment
-     * mandate will charge this person again next cycle, and a shared login belongs
-     * to a merchant who asked for nothing — neither is a SuperAdmin's to waive.
+     * `force` overrides the OPEN-ORDER refusal and nothing else: a live payment
+     * mandate will charge this person again next cycle, which is not a
+     * SuperAdmin's to waive.
      *
      * Idempotent: erasing an already-erased customer returns the original record.
      *
@@ -214,11 +562,74 @@ export interface CustomersModule {
      *
      * That event keeps its ids and its `external_refs`: it is the one moment an
      * ESP, ERP, CRM or PSP can erase its own copy of the person, and blanking it
-     * would destroy the only keys to them.
+     * would destroy the only keys to them. Beside the custom-field ids, each
+     * store's event carries the keys a customer master filed there, by system
+     * name ({@link upsertByExternalRef}: `{ visos: 'P-123' }`), which the erasure
+     * then deletes: a master that knows the person only by its own key finds the
+     * record to erase, and its next sync of that key makes a NEW customer.
      */
     erase(id: string, options: EraseCustomerOptions): Promise<CustomerErasureRecord>;
+    /**
+     * A SUBJECT-ACCESS REQUEST: ask every app installed on this store for the
+     * personal data it holds about this customer. Emits `customer.data_requested`,
+     * which every app installation receives whatever its event filters say; each
+     * acknowledges it within 30 days through `admin.compliance.acknowledge`, and
+     * `admin.compliance.list` shows who has not. Needs `ReadCustomer` and
+     * `UpdateCustomer`. Refused for an erased customer (`CUSTOMER_ERASED`). A
+     * repeat under the same `idempotencyKey` answers the first request.
+     */
+    requestData(id: string, options: RequestCustomerDataOptions): Promise<ComplianceRequest>;
     /** The erasure record, or `null` if this customer has not been erased. */
     erasure(id: string, options?: Call): Promise<CustomerErasureRecord | null>;
+    /**
+     * Act inside a customer's cart: a 15-minute, non-renewable Shop API session
+     * for them, bounded to cart and checkout (headless spec §6.5). Needs
+     * `UpdateCustomer` AND `UpdateOrder`. Emits `customer.agent_session_started`.
+     *
+     * THE HANDOFF: the returned `token` is usable only as the `customerToken` of a
+     * storefront client for the same store — `createStorefrontClient({ storeCode,
+     * cdnUrl, customerToken: session.token })` from `@sixtyninecommerce/client`.
+     * The Admin API, the CMS and the plugins service refuse it; on the Shop API
+     * anything beyond cart and checkout is refused with `PermissionDeniedError`
+     * `AGENT_SESSION_SCOPE`.
+     *
+     * NOT idempotent, deliberately: every call mints a new session and a new
+     * token — the answer carries a credential, and an idempotency store would
+     * keep and replay it. Retrying after a timeout at worst leaves an unused
+     * session that expires on its own; end the one you are not using.
+     *
+     * Refused for an erased customer (`CUSTOMER_ERASED`), a guest record with no
+     * login (`CUSTOMER_HAS_NO_ACCOUNT`), a customer of another store
+     * (`NotFoundError` `CUSTOMER_NOT_FOUND`), the platform root channel and a
+     * location-restricted credential (`AGENT_SESSION_LOCATION_NOT_ALLOWED`).
+     */
+    actAs(customerId: string, options: ActAsCustomerOptions): Promise<CustomerAgentSession>;
+    /**
+     * End an agent session now. The next Shop API call with its token answers 401.
+     * Ending an ended session answers the first end.
+     */
+    endAgentSession(sessionId: string, options?: Call): Promise<EndedCustomerAgentSession>;
+    /**
+     * The store's customer under another system's key, or `null` (an unknown key, another store's,
+     * or one whose customer was deleted). Needs `ReadCustomer`.
+     */
+    byExternalRef(system: string, ref: string, options?: Call): Promise<Customer | null>;
+    /** This store's external keys for a customer; `[]` for none or for a customer it does not hold. */
+    externalRefs(customerId: string, options?: Call): Promise<CustomerExternalRef[]>;
+    /**
+     * Create the store's customer for a master system's key, or update the one it names. Never a
+     * second customer: not on a repeat under the same `idempotencyKey`, not on a concurrent call,
+     * and not for an address the store already has (that customer is linked, `matchedByEmail`).
+     * Creating needs `CreateCustomer`; linking or changing an existing customer `UpdateCustomer`;
+     * answering a customer the key already names `ReadCustomer` or `UpdateCustomer`.
+     *
+     * Refusals: `CUSTOMER_EXTERNAL_REF_INVALID` (a malformed key),
+     * `CUSTOMER_EXTERNAL_REF_EMAIL_INVALID` (a new customer without a usable address),
+     * `CUSTOMER_EXTERNAL_REF_CONFLICT` (the customer with that address already carries another key
+     * of the same system), `CUSTOMER_EXTERNAL_REF_WRITE_CONFLICT` (a concurrent call won; send it again),
+     * and the address rules of {@link update}.
+     */
+    upsertByExternalRef(input: UpsertCustomerByExternalRefInput, options?: Call): Promise<UpsertedCustomer>;
     groups: CustomerGroupsModule;
     addresses: CustomerAddressesModule;
 }