@sixtyninecommerce/admin 0.9.0 → 0.11.0

package/dist/customers/index.d.ts

@@ -1,7 +1,20 @@
 import { type Page, type Transport } from '@sixtyninecommerce/core';
 import { type CatalogueOwnership } from '../catalog/types.js';
 import { type ComplianceRequest } from '../compliance/index.js';
+import { type OrderListOptions, type OrderSummary, type RecentOrder, type RecentOrdersOptions } from '../orders/list.js';
 import type { Call, ListOptions } from '../types.js';
+import { type CustomerAgeVerification, type CustomerDateOfBirthModule } from './age-verification.js';
+import { type CustomerCreditModule } from './credit.js';
+import { type CustomerDeliveryPreferencesModule } from './delivery-preferences.js';
+import { type CreateCustomerGroupInput, type CustomerB2BGroupsModule, type CustomerGroup, type CustomerGroupListItem, type CustomerGroupListOptions, type CustomerGroupMembersOptions, type CustomerGroupRef, type CustomerGroupWithMembers, type UpdateCustomerGroupInput } from './groups.js';
+import { type CustomerInvitationStatus } from './invitation-status.js';
+import { type CustomerNotesModule } from './notes.js';
+import { type CustomerNotificationRecipientsModule } from './notification-recipients.js';
+import { type CustomerSavedList } from './saved-lists.js';
+import { type CustomerVatModule } from './vat.js';
+import { type CustomerAddressSummary } from './wire.js';
+export { type CreateCustomerGroupInput, CUSTOMER_GROUP_FIELDS, CUSTOMER_GROUP_LIST_INCLUDES, CUSTOMER_GROUP_LIST_SORT_FIELDS, CUSTOMER_GROUP_QUERY, type CustomerB2BGroupsModule, type CustomerGroup, type CustomerGroupListFilter, type CustomerGroupListInclude, type CustomerGroupListItem, type CustomerGroupListOptions, type CustomerGroupListSort, type CustomerGroupListSortField, type CustomerGroupMember, type CustomerGroupMembersOptions, type CustomerGroupRef, type CustomerGroupWithMembers, MAX_CUSTOMER_GROUP_LIST_TAKE, type UpdateCustomerGroupInput, } from './groups.js';
+export type { CustomerAddressSummary } from './wire.js';
 /**
  * Customers — the commerce master record (headless spec §6.5).
  *
@@ -46,9 +59,25 @@ import type { Call, ListOptions } from '../types.js';
  */
 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";
-export declare const LIST_QUERY = "\n  query Customers($options: CustomerListOptions) {\n    customers(options: $options) {\n      items { \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      totalItems\n    }\n  }\n";
 export declare const GET_QUERY = "\n  query CustomerById($id: ID!) {\n    customer(id: $id) { \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 ADDRESSES_QUERY = "\n  query CustomerAddresses($id: ID!) {\n    customer(id: $id) {\n      id\n      addresses { \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";
+/**
+ * A list row: the customer, plus what a list shows beside the name (the address book's company
+ * flags, for {@link CustomerListItem.company}). The order count is its own block: the engine
+ * counts each row's orders in a query of its own, so a list asks for it only when it shows it.
+ */
+export declare const CUSTOMER_LIST_FIELDS = "\n  \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  addresses {\n    company\n    defaultBillingAddress\n    defaultShippingAddress\n  }\n";
+/** The list document, with or without each row's order count. */
+export declare function customerListQuery(include?: readonly CustomerListInclude[]): string;
+/** How many history entries `get` reads with `include: ['history']`, newest first. */
+export declare const CUSTOMER_HISTORY_TAKE = 20;
+/** The plugin custom fields `include: ['customFields']` reads (AFAS, VAT validation, age check). */
+export declare const CUSTOMER_PLUGIN_FIELDS = "\n  afasVrId\n  afasOrgId\n  afasContactId\n  afasPersId\n  vatNumber\n  vatValidationStatus\n  vatValidatedAt\n  vatCompanyName\n  vatCompanyAddress\n  dateOfBirth\n";
+/**
+ * The document `get` sends for a set of blocks. It depends on the SET only, never on the order
+ * the caller listed them in. Without blocks it is {@link GET_QUERY}.
+ */
+export declare function customerQuery(include?: readonly CustomerInclude[]): string;
 /**
  * The CHANNEL-SCOPED creation mutation. See the module docblock — core
  * `createCustomer` is not an option, and this SDK exposes no path to it.
@@ -86,9 +115,6 @@ export declare const BY_EXTERNAL_REF_QUERY = "\n  query CustomerByExternalRef($s
 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";
@@ -97,10 +123,6 @@ 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";
-export interface CustomerGroupRef {
-    id: string;
-    name: string;
-}
 /** Another system's key for a customer of this store. */
 export interface CustomerExternalRef {
     id: string;
@@ -147,23 +169,6 @@ export interface UpsertedCustomer {
     /** 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;
@@ -233,6 +238,135 @@ export interface CustomerAddress {
      */
     redacted?: true;
 }
+/** One customer as `list` answers it. */
+export interface CustomerListItem extends Customer {
+    /** The company flags of every address in the customer's book. */
+    addresses: CustomerAddressSummary[];
+    /**
+     * The customer's company: the default billing address's, else the default shipping address's,
+     * else the first address that names one; `null` when none does. Blanked addresses (`redacted`)
+     * read `null` here too.
+     */
+    company: string | null;
+    /**
+     * How many orders the customer has in this store, present only when the call asked for
+     * `include: ['orderCount']`. An open cart counts too; an order still in the `Draft` state (a
+     * back-office draft) does not: the engine leaves drafts out of a customer's orders.
+     */
+    orderCount?: number;
+}
+/** What a customer list can be narrowed by. Several keys combine with AND. */
+export interface CustomerListFilter {
+    /** These customers only. An empty list matches nothing. */
+    ids?: readonly string[];
+    /** The email address begins with this, ignoring case. */
+    emailStartsWith?: string;
+    /**
+     * The last name contains this, ignoring case. The engine trims it, and reads `%` and `_` in it
+     * as wildcards.
+     */
+    lastName?: string;
+}
+export declare const CUSTOMER_LIST_SORT_FIELDS: readonly ["createdAt", "updatedAt", "firstName", "lastName", "emailAddress", "phoneNumber"];
+export type CustomerListSortField = (typeof CUSTOMER_LIST_SORT_FIELDS)[number];
+export interface CustomerListSort {
+    field: CustomerListSortField;
+    direction: 'ASC' | 'DESC';
+}
+/** The blocks a list row can add: `orderCount`, each row's order count. */
+export declare const CUSTOMER_LIST_INCLUDES: readonly ["orderCount"];
+export type CustomerListInclude = (typeof CUSTOMER_LIST_INCLUDES)[number];
+/** The engine's `adminListQueryLimit`: a larger page is refused. */
+export declare const MAX_CUSTOMER_LIST_TAKE = 1000;
+export interface CustomerListOptions extends ListOptions {
+    filter?: CustomerListFilter;
+    /** The engine's order (creation, oldest first) when omitted. */
+    sort?: CustomerListSort;
+    /** Rows to skip, 0 when omitted. Not together with `after`. */
+    skip?: number;
+    /** Rows per page, 1 to {@link MAX_CUSTOMER_LIST_TAKE}; `limit`, else 25, when omitted. */
+    take?: number;
+    include?: readonly CustomerListInclude[];
+}
+/**
+ * The blocks `get` can add to a customer, each asked for by name in `include`:
+ *
+ * - `addresses`: the address book.
+ * - `user`: the sign-in account (`null` for a guest customer).
+ * - `history`: the {@link CUSTOMER_HISTORY_TAKE} most recent history entries, newest first.
+ * - `customFields`: the fields the AFAS, VAT-validation and age-check plugins keep on the customer
+ *   (and, with `addresses`, each address's AFAS id).
+ */
+export declare const CUSTOMER_INCLUDES: readonly ["addresses", "user", "history", "customFields"];
+export type CustomerInclude = (typeof CUSTOMER_INCLUDES)[number];
+export interface CustomerUser {
+    id: string;
+    /** Whether the account's email address was verified. */
+    verified: boolean;
+    /** ISO-8601; null when the account never signed in. */
+    lastLogin: string | null;
+}
+export interface CustomerHistoryEntry {
+    id: string;
+    /** The engine's entry type (`CUSTOMER_NOTE`, `CUSTOMER_REGISTERED`, …). */
+    type: string;
+    isPublic: boolean;
+    data: Record<string, unknown>;
+    createdAt: string;
+    /** The staff member who wrote it; null for the system or the customer. */
+    administrator: {
+        id: string;
+        firstName: string;
+        lastName: string;
+    } | null;
+}
+/**
+ * The plugin fields of a customer. A field is null when the customer has no value, and also when
+ * the caller's customer-data level withholds it (`redacted` on the customer).
+ */
+export interface CustomerPluginFields {
+    afasVrId: string | null;
+    afasOrgId: string | null;
+    afasContactId: string | null;
+    afasPersId: string | null;
+    vatNumber: string | null;
+    vatValidationStatus: string | null;
+    vatValidatedAt: string | null;
+    vatCompanyName: string | null;
+    vatCompanyAddress: string | null;
+    /** ISO-8601 instant of the date of birth the age check recorded. */
+    dateOfBirth: string | null;
+}
+/** An address read with `include: ['addresses', 'customFields']`. */
+export interface CustomerBookAddress extends CustomerAddress {
+    /** Present only when the read included `customFields`. */
+    customFields?: {
+        afasAddressId: string | null;
+    } | null;
+}
+/** What each `get` block adds to a customer. */
+export interface CustomerBlocks {
+    addresses: CustomerBookAddress[];
+    user: CustomerUser | null;
+    /** The most recent entries (`items`) and how many the customer has in all (`totalItems`). */
+    history: {
+        items: CustomerHistoryEntry[];
+        totalItems: number;
+    };
+    customFields: CustomerPluginFields | null;
+}
+/** True for a union of two or more types. */
+type IsUnion<T, U = T> = T extends unknown ? ([U] extends [T] ? false : true) : never;
+/** A list element that names ONE block for sure; one that may be one of several names none. */
+type SureBlock<E> = [E] extends [never] ? never : true extends IsUnion<E> ? never : E;
+/**
+ * The customer a `get` with this `include` answers, as the list's TYPE says it is: a literal list
+ * of fixed length promises its blocks; a list of no fixed length (`CustomerInclude[]`), or an
+ * element that may be one of several blocks, promises none for sure (each may be on the answer).
+ */
+export type CustomerFor<L extends readonly CustomerInclude[]> = number extends L['length'] ? Customer & Partial<CustomerBlocks> : Customer & Pick<CustomerBlocks, {
+    [K in keyof L]: SureBlock<L[K]>;
+}[number]> & Partial<CustomerBlocks>;
 export interface CreateCustomerInput {
     emailAddress: string;
     firstName: string;
@@ -378,32 +512,162 @@ export interface ActAsCustomerOptions extends Call {
     reason: string;
 }
 export interface CustomerAddressesModule {
+    /**
+     * A customer's address book; `[]` for a customer with none, and for one the store does not
+     * hold. Needs `ReadCustomer`.
+     *
+     * @effect read
+     */
     list(customerId: string, options?: Call): Promise<CustomerAddress[]>;
+    /**
+     * Add an address to a customer's book. Needs `CreateCustomer`. Refused `FIELD_GROUP_LOCKED`
+     * while an app or API token owns Customer details (see {@link CustomersModule.update}).
+     *
+     * @effect write
+     */
     create(customerId: string, input: Record<string, unknown>, options?: Call): Promise<CustomerAddress>;
+    /**
+     * Change one address. Needs `UpdateCustomer`. Refused like {@link create}.
+     *
+     * @effect write
+     */
     update(input: {
         id: string;
     } & Record<string, unknown>, options?: Call): Promise<CustomerAddress>;
+    /**
+     * Delete one address from its customer's book. Needs `DeleteCustomer`. Refused like
+     * {@link create}, and `ADDRESS_NOT_DELETED` (`BusinessRuleError`, 422) when the engine answers
+     * that it deleted nothing.
+     *
+     * @effect destructive
+     */
     delete(id: string, options?: Call): Promise<void>;
 }
 export interface CustomerGroupsModule {
     /**
-     * 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.
+     * One page of the store's customer groups, with `total` the exact count of every group the
+     * filter matches. Needs `ReadCustomer` or `ReadCustomerGroup`.
+     *
+     * - Page with `after` (the cursor of `page.next()`) and `limit`, or with `skip` and `take`; not
+     *   `after` and `skip` together. Sorted by name, A to Z, unless `sort` says otherwise.
+     * - `include: ['memberCount']` adds how many of the store's customers each group holds. It
+     *   needs `ReadCustomer` too: without it the engine refuses the whole call. Ask for it only
+     *   where the count is shown: today's engine reads every member of each listed group to answer
+     *   it.
+     * - A group the store holds from its organization is listed like its own; `get` says whose it
+     *   is (`catalogueOwnership`).
+     * - To search by text, find ids with `search.index('customer_groups', …)`, then list them with
+     *   `filter: { ids }`.
+     *
+     * Refused before anything is asked: `INVALID_CUSTOMER_GROUP_LIST_OPTIONS` (`ValidationError`,
+     * 400) for a filter key it does not list, a sort field it does not list, `take`/`skip` out of
+     * range, `after` with `skip`, or an `include` name it does not know.
+     *
+     * @effect read
+     */
+    list(options?: CustomerGroupListOptions): Promise<Page<CustomerGroupListItem>>;
+    /**
+     * One of the ACTIVE store's customer groups by id, its flags and 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.
+     *
+     * With `members`, the answer also carries one page of the group's members in this store and
+     * their count ({@link CustomerGroupWithMembers.members}), in a fixed order (by id);
+     * `members.filter.ids` asks which of those customers are members. Reading members needs `ReadCustomer`: without it the engine
+     * refuses the whole call. An app installation below `customerData: full` reads each member
+     * with the fields its level withholds blanked (`redacted: true`). A page option out of range
+     * or unknown is refused `INVALID_CUSTOMER_GROUP_MEMBERS_OPTIONS` (`ValidationError`, 400)
+     * before anything is asked. However small the page or the `filter.ids` list, today's engine
+     * reads every member of the group to answer it.
+     *
+     * @effect read
      */
+    get(id: string, options: Call & {
+        members: CustomerGroupMembersOptions;
+    }): Promise<CustomerGroupWithMembers | null>;
     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.
+     * Create a customer group in this store. Needs `CreateCustomerGroup`. `customerIds` puts
+     * customers of the store in it at once; an id the store does not hold is left out, not
+     * refused. The engine does not judge the name: an empty one is saved as it is. Input of the
+     * wrong type is refused `INVALID_CUSTOMER_GROUP_INPUT` (`ValidationError`, 400) before it is
+     * sent.
+     *
+     * @effect write
+     */
+    create(input: CreateCustomerGroupInput, options?: Call): Promise<CustomerGroup>;
+    /**
+     * Rename a group or change its flags; an absent field keeps what the group has. Needs
+     * `UpdateCustomerGroup`.
+     *
+     * A group is ONE row for every store that holds it, so the change shows in each of them.
+     * Refused `MANAGED_BY_ORGANIZATION` (`BusinessRuleError`, 422) for a group the store holds from
+     * its organization (change it in the workspace; `catalogueOwnership.editableHere` is false),
+     * `SHARED_CUSTOMER_GROUP_NOT_ALLOWED` (`PermissionDeniedError`) for a group other stores hold
+     * too unless the caller has `UpdateCustomerGroup` in each of them, and `ENTITY_NOT_FOUND`
+     * (`NotFoundError`) for a group the store does not hold.
+     *
+     * @effect write
+     */
+    update(id: string, input: UpdateCustomerGroupInput, options?: Call): Promise<CustomerGroup>;
+    /**
+     * Delete a group for good. Its members stay customers of the store, and a product whose
+     * visibility named the group no longer names it. Deleting an organization's group in its
+     * workspace takes it out of every member store that holds it. Needs `DeleteCustomerGroup`.
+     *
+     * Refused like {@link update} for an organization's group (`MANAGED_BY_ORGANIZATION`) and for
+     * one other stores hold too (`SHARED_CUSTOMER_GROUP_NOT_ALLOWED`, asking `DeleteCustomerGroup`
+     * in each), and `CUSTOMER_GROUP_NOT_DELETED` (`ConflictError`, 409) with the engine's own
+     * reason for a group the store does not hold.
+     *
+     * @effect destructive
+     */
+    delete(id: string, options?: Call): Promise<void>;
+    /**
+     * Delete several groups in one call. Needs `DeleteCustomerGroup`. An empty list does nothing.
+     *
+     * All or nothing for the engine's sharing rule: ONE group it protects (an organization's, or
+     * one other stores hold without the caller's permission there) refuses the whole call, as
+     * {@link delete} does, and no group is deleted. An id the store does not hold is different:
+     * the other groups ARE deleted, and the call then rejects `CUSTOMER_GROUP_NOT_DELETED`
+     * (`ConflictError`, 409) whose `details` name each id that was not (`field: 'ids.<index>'`).
+     *
+     * @effect destructive
+     */
+    deleteMany(ids: readonly string[], options?: Call): Promise<void>;
+    /**
+     * Add customers to a group. Needs `UpdateCustomerGroup`. 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. A customer the store does not hold is left out, and a group
+     * it does not hold is `ENTITY_NOT_FOUND` (`NotFoundError`).
+     *
+     * @effect write
      */
     add(groupId: string, customerIds: string[], options?: Call): Promise<CustomerGroupRef>;
+    /**
+     * Take customers out of a group; they stay customers of the store. Needs
+     * `UpdateCustomerGroup`. Emits one `customer.group_changed` per customer removed. Naming a
+     * customer of the store who is not a member refuses the whole call (`ValidationError`,
+     * `USER_INPUT_ERROR`); a customer the store does not hold is left out.
+     *
+     * @effect destructive
+     */
     remove(groupId: string, customerIds: string[], options?: Call): Promise<CustomerGroupRef>;
-    /** The store's group under the master system's segment key, or `null`. Needs `ReadCustomerGroup`. */
+    /**
+     * The store's group under the master system's segment key, or `null`. Needs `ReadCustomerGroup`.
+     *
+     * @effect read
+     */
     byExternalKey(key: string, options?: Call): Promise<ExternalKeyedCustomerGroup | null>;
-    /** This store's external key for a group, or `null` when no master keys it. */
+    /**
+     * This store's external key for a group, or `null` when no master keys it.
+     *
+     * @effect read
+     */
     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.
@@ -412,6 +676,8 @@ export interface CustomerGroupsModule {
      * 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).
+     *
+     * @effect write
      */
     upsertByExternalKey(key: string, name: string, options?: Call): Promise<UpsertedCustomerGroup>;
     /**
@@ -425,17 +691,69 @@ export interface CustomerGroupsModule {
      * 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.
+     *
+     * @effect destructive
      */
     replaceMembers(key: string, customerExternalRefs: CustomerExternalRefKey[], options?: Call): Promise<ReplacedCustomerGroupMembers>;
+    /** Which of the store's groups are trade (B2B) groups. */
+    b2b: CustomerB2BGroupsModule;
 }
 export interface CustomersModule {
-    list(options?: ListOptions): Promise<Page<Customer>>;
+    /**
+     * One page of the store's customers, with `total` the exact count of every customer the filter
+     * matches. Needs `ReadCustomer`.
+     *
+     * - Page with `after` (the cursor of `page.next()`) and `limit`, or with `skip` and `take`; not
+     *   `after` and `skip` together.
+     * - Each row carries its address book's company flags and {@link CustomerListItem.company};
+     *   `include: ['orderCount']` adds each row's order count (carts count; `Draft`-state orders do not).
+     * - To search by text (a name, part of an address, a phone number), find ids with
+     *   `search.index('customers', …)`, then list them with `filter: { ids }`.
+     *
+     * An app installation below `customerData: full` reads every row with the fields its level
+     * withholds blanked (`redacted: true` on each), and the engine refuses it a filter or sort on a
+     * withheld field (`CUSTOMER_DATA_NOT_GRANTED`).
+     *
+     * Refused before anything is asked: `INVALID_CUSTOMER_LIST_OPTIONS` (`ValidationError`, 400)
+     * for a filter key it does not list, a sort field it does not list, `take`/`skip` out of
+     * range, `after` with `skip`, or an `include` name it does not know.
+     *
+     * @effect read
+     */
+    list(options?: CustomerListOptions): Promise<Page<CustomerListItem>>;
+    /**
+     * One customer of this store, or `null` when the store holds no customer with that id (another
+     * store's customer answers `null` too). Needs `ReadCustomer`.
+     *
+     * Without `include` the answer is the customer record itself. Each name in `include` adds one
+     * block ({@link CUSTOMER_INCLUDES}) to the answer and to its type: pass a literal list to have
+     * those blocks on the type. The customer's orders are {@link CustomersModule.orders}.
+     *
+     * `customFields` reads the fields the AFAS, VAT-validation and age-check plugins add to a
+     * customer. The engine serves them because those plugins are installed on it; a value is null
+     * for a customer the plugin never wrote. An app installation below `customerData: full` reads
+     * the customer, the addresses, the account and the plugin fields with what its level withholds
+     * blanked, and the answer says so (`redacted: true`).
+     *
+     * An `include` name this version does not know is refused with a `ValidationError`
+     * (`INVALID_CUSTOMER_INCLUDE`) before anything is asked.
+     *
+     * @effect read
+     */
     get(id: string, options?: Call): Promise<Customer | null>;
+    get<const L extends readonly CustomerInclude[]>(id: string, options: Call & {
+        include: L;
+    }): Promise<CustomerFor<L> | null>;
     /**
      * 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.
+     *
+     * An address this store's customers already use is not refused: the answer is THAT customer,
+     * with `createdNew: false`. A caller that meant a new customer reads that as "address in use".
+     *
+     * @effect write
      */
     create(input: CreateCustomerInput, options?: Call): Promise<CreatedCustomer>;
     /**
@@ -451,18 +769,57 @@ export interface CustomersModule {
      * `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.
+     *
+     * @effect write
      */
     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.
+     * Mail the customer a way in: a set-password link, or a magic-link sign-in. Needs
+     * `UpdateCustomer`. Ask {@link invitationStatus} first: it says whether an invitation can be
+     * sent, and `resend` is its `nextMode`.
      *
      * Not the storefront's forgot-password screen, which mails a password RESET
      * — something a customer who has never had an account did not ask for.
+     *
+     * Refused with the engine's sentence (`ValidationError`, `USER_INPUT_ERROR`, 400) for each
+     * blocked reason of the status, during the cooldown ("An invitation was sent less than a
+     * minute ago"), and while the store's invitation email is switched off or has no recipient.
+     * Refused `CUSTOMER_LOGIN_ON_OTHER_STORES` (`BusinessRuleError`) when the sign-in the address
+     * needs is one another store uses too.
+     *
+     * @effect write
      */
     invite(id: string, options?: Call & {
         mode?: CustomerInviteMode;
         resend?: boolean;
     }): Promise<CustomerInvitation>;
+    /**
+     * Whether an invitation can be sent to this customer now, what the last one was, and until
+     * when its cooldown runs. Needs `ReadCustomer`.
+     *
+     * The last invitation and the cooldown are read from the record each invitation leaves on the
+     * customer's history (a staff-visible note, among the customer's 100 newest), so a reworded
+     * or deleted record reads as "never invited". The send itself is judged by {@link invite}.
+     *
+     * A customer this store does not hold is a `NotFoundError` (`ENTITY_NOT_FOUND`). Requires a
+     * platform release that serves `customerInvitationStatus`: an older engine refuses the call
+     * as a whole (a `ValidationError`, 400).
+     *
+     * @effect read
+     */
+    invitationStatus(id: string, options?: Call): Promise<CustomerInvitationStatus>;
+    /**
+     * The age check of one customer: whether the store checks age, its minimum, the customer's
+     * date of birth, their age today and whether it meets the minimum. Needs `ReadCustomer`.
+     *
+     * The engine answers a status for any id: a customer the store does not hold reads
+     * `verified: false` with no date of birth, like a customer with none. `null` is reserved for
+     * an engine that answers none. Requires a platform release that answers the age: an older
+     * engine refuses the call as a whole (a `ValidationError`, 400).
+     *
+     * @effect read
+     */
+    ageVerification(id: string, options?: Call): Promise<CustomerAgeVerification | null>;
     /**
      * 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
@@ -630,7 +987,60 @@ export interface CustomersModule {
      * and the address rules of {@link update}.
      */
     upsertByExternalRef(input: UpsertCustomerByExternalRefInput, options?: Call): Promise<UpsertedCustomer>;
+    /**
+     * One page of a customer's orders in this store, or `null` when the store holds no customer
+     * with that id. The same rows, filter, sort, paging and refusals as `orders.list`, including its
+     * two traps: the customer's open cart is one of the orders unless the filter leaves it out, and
+     * `orderPlacedAt` descending lists the never-placed rows first. Needs `ReadCustomer` (the engine
+     * asks nothing more for the customer's orders).
+     *
+     * @effect read
+     */
+    orders(customerId: string, options?: OrderListOptions): Promise<Page<OrderSummary> | null>;
+    /**
+     * The customer's last PLACED orders in this store, newest first, each with its lines: what was
+     * bought, how many, and the unit price a line stated in place of the catalogue's, with the
+     * basis it is stated in. `null` when the store holds no customer with that id. Carts and drafts are never among them. What an "order it again"
+     * picker and a "recently ordered" list read; `orders` is the paged list, without lines.
+     *
+     * A line names the variant as it is now. Before offering one as a product, read it through
+     * `catalog.variants.find({ ids })`: that leaves out a variant the store no longer holds and
+     * the hidden carrier variant behind an externally priced line.
+     *
+     * Needs `ReadCustomer`. Refused before anything is asked: `INVALID_ORDER_LIST_OPTIONS`
+     * (`ValidationError`, 400) for a `take` outside 1 to 20 (`MAX_RECENT_ORDERS`).
+     *
+     * @effect read
+     */
+    recentOrders(customerId: string, options?: RecentOrdersOptions): Promise<RecentOrder[] | null>;
+    /**
+     * The customer's saved lists in this store (the lists of products and quantities a shopper
+     * keeps on the storefront to order again), most recently changed first, each with its items in
+     * the shopper's order. `null` when the store holds no customer with that id (another store's
+     * included); `[]` for a customer with none. Read-only: the shopper writes them through the Shop
+     * API. A variant of a disabled product is still listed (the Shop API hides it from the shopper,
+     * multi-region decision 87); a variant the store no longer holds reads `productVariant: null`.
+     * The list's name is customer data, withheld below `customerData: full` (`redacted`). Needs
+     * `ReadCustomer`.
+     *
+     * @effect read
+     */
+    savedLists(customerId: string, options?: Call): Promise<CustomerSavedList[] | null>;
     groups: CustomerGroupsModule;
     addresses: CustomerAddressesModule;
+    /** A customer's B2B credit: account, limit, terms, status and what may be invoiced. */
+    credit: CustomerCreditModule;
+    /** A customer's staff notes: add, change, delete. */
+    notes: CustomerNotesModule;
+    /** A customer's saved delivery preferences, and the handlers' preference forms. */
+    deliveryPreferences: CustomerDeliveryPreferencesModule;
+    /** The extra addresses a customer's order emails also go to. */
+    notificationRecipients: CustomerNotificationRecipientsModule;
+    /** A customer's date of birth, as a calendar date. */
+    dateOfBirth: CustomerDateOfBirthModule;
+    /** A customer's VAT number: check it with VIES, or clear it. */
+    vat: CustomerVatModule;
 }
+/** The Admin API's `CustomerFilterParameter` for a typed filter; unknown keys are refused. */
+export declare function toCustomerFilterParameter(filter: CustomerListFilter | undefined): Record<string, unknown>;
 export declare function createCustomersModule(transport: Transport): CustomersModule;