@sixtyninecommerce/admin 0.10.0 → 0.12.0

package/dist/customers/index.js

@@ -1,7 +1,20 @@
-import { errorFromErrorResult, isErrorResult, pageFromVendureList, readOffsetCursor, } from '@sixtyninecommerce/core';
+import { BusinessRuleError, errorFromErrorResult, isErrorResult, pageFromVendureList, readOffsetCursor, ValidationError, } from '@sixtyninecommerce/core';
 import { CATALOGUE_OWNERSHIP_FIELDS } from '../catalog/types.js';
 import { COMPLIANCE_REQUEST_FIELDS } from '../compliance/index.js';
 import { redactionWatcher } from '../customer-data-redaction.js';
+import { listCustomerOrders, listCustomerRecentOrders, } from '../orders/list.js';
+import { createCustomerDateOfBirthModule, readCustomerAgeVerification, } from './age-verification.js';
+import { createCustomerCreditModule } from './credit.js';
+import { createCustomerDeliveryPreferencesModule, } from './delivery-preferences.js';
+import { readCustomerDeliveryTerms } from './delivery-terms.js';
+import { createCustomerB2BGroupsModule, createCustomerGroup, deleteCustomerGroup, deleteCustomerGroups, listCustomerGroups, readCustomerGroup, updateCustomerGroup, } from './groups.js';
+import { readCustomerInvitationStatus, } from './invitation-status.js';
+import { createCustomerNotesModule } from './notes.js';
+import { createCustomerNotificationRecipientsModule, } from './notification-recipients.js';
+import { readCustomerSavedLists } from './saved-lists.js';
+import { createCustomerVatModule } from './vat.js';
+import { companyOf } from './wire.js';
+export { CUSTOMER_GROUP_FIELDS, CUSTOMER_GROUP_LIST_INCLUDES, CUSTOMER_GROUP_LIST_SORT_FIELDS, CUSTOMER_GROUP_QUERY, MAX_CUSTOMER_GROUP_LIST_TAKE, } from './groups.js';
 /**
  * Customers — the commerce master record (headless spec §6.5).
  *
@@ -75,14 +88,6 @@ export const CUSTOMER_ADDRESS_FIELDS = /* GraphQL */ `
   defaultShippingAddress
   defaultBillingAddress
 `;
-export const LIST_QUERY = /* GraphQL */ `
-  query Customers($options: CustomerListOptions) {
-    customers(options: $options) {
-      items { ${CUSTOMER_FIELDS} }
-      totalItems
-    }
-  }
-`;
 export const GET_QUERY = /* GraphQL */ `
   query CustomerById($id: ID!) {
     customer(id: $id) { ${CUSTOMER_FIELDS} }
@@ -96,6 +101,94 @@ export const ADDRESSES_QUERY = /* GraphQL */ `
     }
   }
 `;
+/**
+ * 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 const CUSTOMER_LIST_FIELDS = /* GraphQL */ `
+  ${CUSTOMER_FIELDS}
+  addresses {
+    company
+    defaultBillingAddress
+    defaultShippingAddress
+  }
+`;
+/** The list document, with or without each row's order count. */
+export function customerListQuery(include = []) {
+    // `take: 1`, never 0: the engine passes 0 on and TypeORM reads a falsy limit as NO limit, so
+    // `take: 0` would load every order of every row. `totalItems` is its own COUNT either way.
+    const orderCount = include.includes('orderCount')
+        ? 'orders(options: { take: 1 }) { totalItems }'
+        : '';
+    return /* GraphQL */ `
+  query CustomersList($options: CustomerListOptions) {
+    customers(options: $options) {
+      items {
+        ${CUSTOMER_LIST_FIELDS}
+        ${orderCount}
+      }
+      totalItems
+    }
+  }
+`;
+}
+/** How many history entries `get` reads with `include: ['history']`, newest first. */
+export const CUSTOMER_HISTORY_TAKE = 20;
+/** The plugin custom fields `include: ['customFields']` reads (AFAS, VAT validation, age check). */
+export const CUSTOMER_PLUGIN_FIELDS = /* GraphQL */ `
+  afasVrId
+  afasOrgId
+  afasContactId
+  afasPersId
+  vatNumber
+  vatValidationStatus
+  vatValidatedAt
+  vatCompanyName
+  vatCompanyAddress
+  dateOfBirth
+`;
+/**
+ * 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 function customerQuery(include = []) {
+    const asked = new Set(include);
+    if (asked.size === 0)
+        return GET_QUERY;
+    const pluginFields = asked.has('customFields');
+    const blocks = [];
+    if (asked.has('addresses')) {
+        // The AFAS address id is a plugin field too, so it rides on `customFields`.
+        const addressPluginFields = pluginFields ? 'customFields { afasAddressId }' : '';
+        blocks.push(`addresses { ${CUSTOMER_ADDRESS_FIELDS} ${addressPluginFields} }`);
+    }
+    if (asked.has('user'))
+        blocks.push('user { id verified lastLogin }');
+    if (asked.has('history')) {
+        blocks.push(`history(options: { take: ${String(CUSTOMER_HISTORY_TAKE)}, sort: { createdAt: DESC } }) {
+      items {
+        id
+        type
+        isPublic
+        data
+        createdAt
+        administrator { id firstName lastName }
+      }
+      totalItems
+    }`);
+    }
+    if (pluginFields)
+        blocks.push(`customFields { ${CUSTOMER_PLUGIN_FIELDS} }`);
+    return /* GraphQL */ `
+  query CustomerById($id: ID!) {
+    customer(id: $id) {
+      ${CUSTOMER_FIELDS}
+      ${blocks.join('\n')}
+    }
+  }
+`;
+}
 /**
  * The CHANNEL-SCOPED creation mutation. See the module docblock — core
  * `createCustomer` is not an option, and this SDK exposes no path to it.
@@ -285,20 +378,6 @@ export const GROUP_BY_EXTERNAL_KEY_QUERY = /* GraphQL */ `
     customerGroupByExternalKey(key: $key) { ${EXTERNAL_KEYED_GROUP_FIELDS} }
   }
 `;
-/** A customer group as {@link CustomerGroupsModule.get} reads it. */
-export const CUSTOMER_GROUP_FIELDS = /* GraphQL */ `
-  id
-  createdAt
-  updatedAt
-  name
-  externalKey
-  ${CATALOGUE_OWNERSHIP_FIELDS}
-`;
-export const CUSTOMER_GROUP_QUERY = /* GraphQL */ `
-  query CustomerGroup($id: ID!) {
-    customerGroup(id: $id) { ${CUSTOMER_GROUP_FIELDS} }
-  }
-`;
 export const GROUP_EXTERNAL_KEY_QUERY = /* GraphQL */ `
   query CustomerGroupExternalKey($id: ID!) {
     customerGroup(id: $id) {
@@ -357,32 +436,194 @@ export const DELETE_ADDRESS_MUTATION = /* GraphQL */ `
     deleteCustomerAddress(id: $id) { success }
   }
 `;
+export const CUSTOMER_LIST_SORT_FIELDS = [
+    'createdAt',
+    'updatedAt',
+    'firstName',
+    'lastName',
+    'emailAddress',
+    'phoneNumber',
+];
+/** The blocks a list row can add: `orderCount`, each row's order count. */
+export const CUSTOMER_LIST_INCLUDES = ['orderCount'];
+/** The engine's `adminListQueryLimit`: a larger page is refused. */
+export const MAX_CUSTOMER_LIST_TAKE = 1000;
+/**
+ * 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 const CUSTOMER_INCLUDES = ['addresses', 'user', 'history', 'customFields'];
 const DEFAULT_PAGE_SIZE = 25;
+function invalidListOptions(message) {
+    return new ValidationError({
+        code: 'INVALID_CUSTOMER_LIST_OPTIONS',
+        message,
+        status: 400,
+        service: 'vendure',
+    });
+}
+function listText(value, path) {
+    if (typeof value !== 'string')
+        throw invalidListOptions(`${path} must be a string.`);
+    return value;
+}
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** The Admin API's `CustomerFilterParameter` for a typed filter; unknown keys are refused. */
+export function toCustomerFilterParameter(filter) {
+    if (filter === undefined)
+        return {};
+    if (typeof filter !== 'object' || filter === null || Array.isArray(filter)) {
+        throw invalidListOptions('filter must be an object.');
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(filter)) {
+        if (value === undefined)
+            continue;
+        switch (key) {
+            case 'ids':
+                if (!Array.isArray(value) || value.some((id) => typeof id !== 'string')) {
+                    throw invalidListOptions('filter.ids must be a list of strings.');
+                }
+                out.id = { in: [...value] };
+                break;
+            case 'emailStartsWith':
+                // The engine matches `regex` case-insensitively (`~*`), and an anchored, escaped prefix
+                // is a starts-with: `contains` would match anywhere and read `%`/`_` as wildcards.
+                out.emailAddress = { regex: `^${escapeRegex(listText(value, 'filter.emailStartsWith'))}` };
+                break;
+            case 'lastName':
+                out.lastName = { contains: listText(value, 'filter.lastName') };
+                break;
+            default:
+                throw invalidListOptions(`filter.${key} is not a customer list filter.`);
+        }
+    }
+    return out;
+}
+function customerListRequest(options) {
+    if (options?.after !== undefined && options.skip !== undefined) {
+        throw invalidListOptions('Page with after or with skip, not both.');
+    }
+    const take = options?.take ?? options?.limit ?? DEFAULT_PAGE_SIZE;
+    const skip = options?.skip ?? (options?.after === undefined ? 0 : readOffsetCursor(options.after));
+    if (!Number.isInteger(take) || take < 1 || take > MAX_CUSTOMER_LIST_TAKE) {
+        throw invalidListOptions(`take must be a whole number from 1 to ${String(MAX_CUSTOMER_LIST_TAKE)}.`);
+    }
+    if (!Number.isInteger(skip) || skip < 0) {
+        throw invalidListOptions('skip must be a whole number of 0 or more.');
+    }
+    const sort = options?.sort;
+    if (sort !== undefined &&
+        (typeof sort !== 'object' ||
+            sort === null ||
+            !CUSTOMER_LIST_SORT_FIELDS.includes(sort.field) ||
+            (sort.direction !== 'ASC' && sort.direction !== 'DESC'))) {
+        throw invalidListOptions(`sort must be { field: ${CUSTOMER_LIST_SORT_FIELDS.join(' | ')}, direction: ASC | DESC }.`);
+    }
+    const include = options?.include ?? [];
+    if (!Array.isArray(include) ||
+        !include.every((name) => CUSTOMER_LIST_INCLUDES.includes(name))) {
+        throw invalidListOptions(`include takes a list of ${CUSTOMER_LIST_INCLUDES.join(', ')}.`);
+    }
+    const filter = toCustomerFilterParameter(options?.filter);
+    return {
+        skip,
+        take,
+        request: {
+            query: customerListQuery(include),
+            ...(Object.keys(filter).length > 0 ? { filter } : {}),
+            ...(sort ? { sort: { [sort.field]: sort.direction } } : {}),
+        },
+    };
+}
+function toCustomerListItem(row) {
+    const { orders, addresses, ...customer } = row;
+    const book = addresses ?? [];
+    return {
+        ...customer,
+        addresses: book,
+        company: companyOf(book),
+        ...(orders === undefined ? {} : { orderCount: orders.totalItems }),
+    };
+}
 export function createCustomersModule(transport) {
-    const listPage = async (skip, take, options) => {
+    const listPage = async (skip, take, request, options) => {
         const redaction = redactionWatcher();
         const data = await transport.graphql({
             api: 'admin',
-            query: LIST_QUERY,
-            variables: { options: { skip, take } },
+            query: request.query,
+            variables: {
+                options: {
+                    skip,
+                    take,
+                    ...(request.filter ? { filter: request.filter, filterOperator: 'AND' } : {}),
+                    ...(request.sort ? { sort: request.sort } : {}),
+                },
+            },
             onExtensions: redaction.onExtensions,
         }, options);
-        data.customers.items.forEach(redaction.mark);
-        return pageFromVendureList(data.customers, skip, take, (cursor) => listPage(readOffsetCursor(cursor), take, options));
+        const items = data.customers.items.map((row) => redaction.mark(toCustomerListItem(row)));
+        // Each following page re-sends the same filter, sort and per-call options.
+        return pageFromVendureList({ items, totalItems: data.customers.totalItems }, skip, take, (cursor) => listPage(readOffsetCursor(cursor), take, request, options));
     };
+    async function get(id, options) {
+        // Typed callers cannot get here wrong. A JavaScript caller can, and an unknown name would
+        // otherwise be dropped in silence: the read would answer without the block it asked for.
+        const include = options?.include ?? [];
+        const known = (name) => CUSTOMER_INCLUDES.includes(name);
+        if (!Array.isArray(include) || !include.every(known)) {
+            const given = Array.isArray(include)
+                ? include.filter((name) => !known(name)).map((name) => `"${String(name)}"`)
+                : [String(include)];
+            throw new ValidationError({
+                code: 'INVALID_CUSTOMER_INCLUDE',
+                message: `\`include\` takes a list of a customer's blocks, and ${given.join(', ')} is not one. The blocks are: ${CUSTOMER_INCLUDES.join(', ')}.`,
+                status: 400,
+                service: 'vendure',
+            });
+        }
+        const redaction = redactionWatcher();
+        const data = await transport.graphql({
+            api: 'admin',
+            query: customerQuery(include),
+            variables: { id },
+            onExtensions: redaction.onExtensions,
+        }, options);
+        const customer = redaction.mark(data.customer);
+        customer?.addresses?.forEach(redaction.mark);
+        return customer;
+    }
     return {
-        list(options) {
+        async list(options) {
+            // A refused option rejects the promise, like an engine refusal, rather than throwing here.
             // The Admin API is offset-paged; the offset hides inside the cursor so a
             // consumer only ever sees `Page<T>` (spec §9.3).
-            const take = options?.limit ?? DEFAULT_PAGE_SIZE;
-            const skip = options?.after === undefined ? 0 : readOffsetCursor(options.after);
-            return listPage(skip, take, options);
+            const { skip, take, request } = customerListRequest(options);
+            return listPage(skip, take, request, options);
         },
-        async get(id, options) {
-            const redaction = redactionWatcher();
-            const data = await transport.graphql({ api: 'admin', query: GET_QUERY, variables: { id }, onExtensions: redaction.onExtensions }, options);
-            return redaction.mark(data.customer);
+        orders(customerId, options) {
+            return listCustomerOrders(transport, customerId, options);
         },
+        recentOrders(customerId, options) {
+            return listCustomerRecentOrders(transport, customerId, options);
+        },
+        savedLists(customerId, options) {
+            return readCustomerSavedLists(transport, customerId, options);
+        },
+        deliveryTerms(customerId, options) {
+            return readCustomerDeliveryTerms(transport, customerId, options);
+        },
+        // The answer holds exactly the blocks asked for; `CustomerFor` decides how many of them the
+        // caller's type of `include` may rely on. The overloads narrow this one implementation, which
+        // TypeScript cannot check for them.
+        get: get,
         async create(input, options) {
             const redaction = redactionWatcher();
             const data = await transport.graphql({
@@ -421,6 +662,12 @@ export function createCustomersModule(transport) {
             const data = await transport.graphql({ api: 'admin', query, variables: { customerId: id, mode: options?.mode ?? null } }, options);
             return (data.inviteCustomer ?? data.resendCustomerInvitation);
         },
+        invitationStatus(id, options) {
+            return readCustomerInvitationStatus(transport, id, options);
+        },
+        ageVerification(id, options) {
+            return readCustomerAgeVerification(transport, id, options);
+        },
         async inviteB2B(options) {
             const data = await transport.graphql({
                 api: 'admin',
@@ -498,10 +745,24 @@ export function createCustomersModule(transport) {
             return result;
         },
         groups: {
-            async get(id, options) {
-                const data = await transport.graphql({ api: 'admin', query: CUSTOMER_GROUP_QUERY, variables: { id } }, options);
-                return data.customerGroup;
+            list(options) {
+                return listCustomerGroups(transport, options);
+            },
+            // The overloads narrow this one implementation: with `members` the answer carries them.
+            get: ((id, options) => readCustomerGroup(transport, id, options)),
+            create(input, options) {
+                return createCustomerGroup(transport, input, options);
+            },
+            update(id, input, options) {
+                return updateCustomerGroup(transport, id, input, options);
+            },
+            delete(id, options) {
+                return deleteCustomerGroup(transport, id, options);
+            },
+            deleteMany(ids, options) {
+                return deleteCustomerGroups(transport, ids, options);
             },
+            b2b: createCustomerB2BGroupsModule(transport),
             async byExternalKey(key, options) {
                 const data = await transport.graphql({ api: 'admin', query: GROUP_BY_EXTERNAL_KEY_QUERY, variables: { key } }, options);
                 return data.customerGroupByExternalKey;
@@ -547,6 +808,12 @@ export function createCustomersModule(transport) {
                 return data.removeCustomersFromGroup;
             },
         },
+        credit: createCustomerCreditModule(transport),
+        notes: createCustomerNotesModule(transport),
+        deliveryPreferences: createCustomerDeliveryPreferencesModule(transport),
+        notificationRecipients: createCustomerNotificationRecipientsModule(transport),
+        dateOfBirth: createCustomerDateOfBirthModule(transport),
+        vat: createCustomerVatModule(transport),
         addresses: {
             async list(customerId, options) {
                 const redaction = redactionWatcher();
@@ -579,7 +846,17 @@ export function createCustomersModule(transport) {
                 return redaction.mark(data.updateCustomerAddress);
             },
             async delete(id, options) {
-                await transport.graphql({ api: 'admin', query: DELETE_ADDRESS_MUTATION, variables: { id } }, options);
+                const data = await transport.graphql({ api: 'admin', query: DELETE_ADDRESS_MUTATION, variables: { id } }, options);
+                // Answered at HTTP 200, so the transport never throws for it: returned unchecked, an
+                // address the engine kept would read as deleted.
+                if (data.deleteCustomerAddress.success !== true) {
+                    throw new BusinessRuleError({
+                        code: 'ADDRESS_NOT_DELETED',
+                        message: 'The address was not deleted. Reload the customer and try again.',
+                        status: 422,
+                        service: 'vendure',
+                    });
+                }
             },
         },
     };

package/dist/customers/invitation-status.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Whether a customer can be sent an invitation, and what the last one was (headless spec §9.2
+ * `customers` "invitations"; W10-33). The engine decides: read it before offering
+ * `customers.invite`.
+ */
+import type { Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/**
+ * Why no invitation can be sent, the first that applies in this order:
+ *
+ * - `DEFAULT_CHANNEL`: the call names the platform root channel or an organization's workspace,
+ *   not a store. Nothing of the customer is read there.
+ * - `ERASED`: the store erased the customer. Add a new customer to serve the person again.
+ * - `NO_EMAIL`: the customer has no email address.
+ * - `PLACEHOLDER_EMAIL`: the address is a stand-in under the reserved `.invalid` domain (an ERP
+ *   sync writes one for an account it has no address for). Set the real address first.
+ * - `NO_LOGIN`: a guest checkout record with no sign-in account.
+ * - `NO_STOREFRONT_URL`: the store has no storefront URL, so the link would lead nowhere.
+ */
+export type CustomerInvitationBlockedReason = 'DEFAULT_CHANNEL' | 'ERASED' | 'NO_EMAIL' | 'PLACEHOLDER_EMAIL' | 'NO_LOGIN' | 'NO_STOREFRONT_URL';
+/** What {@link CustomersModule.invitationStatus} answers. */
+export interface CustomerInvitationStatus {
+    /**
+     * Null when nothing known here stops an invitation. `customers.invite` still judges the send
+     * itself and can refuse what this read cannot see: the store's invitation email switched off
+     * or without a recipient, or a sign-in the address shares with another store
+     * (`CUSTOMER_LOGIN_ON_OTHER_STORES`).
+     */
+    blockedReason: CustomerInvitationBlockedReason | (string & {}) | null;
+    /**
+     * The newest invitation sent to the address the customer has NOW, or null. An invitation to
+     * an earlier address does not count: it never reached the current one.
+     */
+    lastInvitation: {
+        customerId: string;
+        emailAddress: string;
+        mode: 'PASSWORD_SETUP' | 'MAGIC_LINK' | (string & {});
+        /** ISO-8601 UTC. */
+        sentAt: string;
+    } | null;
+    /**
+     * ISO-8601 UTC while the cooldown of the newest invitation (to any address) still runs:
+     * `customers.invite` refuses another one until then. Null when none is running.
+     */
+    cooldownUntil: string | null;
+    /** How long a customer waits between two invitations, in seconds. */
+    cooldownSeconds: number;
+    /** `RESEND` once {@link lastInvitation} is set: pass `resend: true` to `customers.invite`. */
+    nextMode: 'SEND' | 'RESEND' | (string & {});
+    /**
+     * Set when the caller's customer-data level blanked the last invitation's address (an app
+     * installation below `identity`): "" then means "not granted".
+     */
+    redacted?: true;
+}
+export declare const INVITATION_STATUS_QUERY = "\n  query CustomerInvitationStatus($customerId: ID!) {\n    customerInvitationStatus(customerId: $customerId) {\n      blockedReason\n      lastInvitation {\n        customerId\n        emailAddress\n        mode\n        sentAt\n      }\n      cooldownUntil\n      cooldownSeconds\n      nextMode\n    }\n  }\n";
+export declare function readCustomerInvitationStatus(transport: Transport, customerId: string, options?: Call): Promise<CustomerInvitationStatus>;

package/dist/customers/invitation-status.js

@@ -0,0 +1,21 @@
+import { customerDataField } from './wire.js';
+export const INVITATION_STATUS_QUERY = /* GraphQL */ `
+  query CustomerInvitationStatus($customerId: ID!) {
+    customerInvitationStatus(customerId: $customerId) {
+      blockedReason
+      lastInvitation {
+        customerId
+        emailAddress
+        mode
+        sentAt
+      }
+      cooldownUntil
+      cooldownSeconds
+      nextMode
+    }
+  }
+`;
+export async function readCustomerInvitationStatus(transport, customerId, options) {
+    const { value, mark } = await customerDataField(transport, INVITATION_STATUS_QUERY, 'customerInvitationStatus', { customerId }, options);
+    return mark(value);
+}

package/dist/customers/notes.d.ts

@@ -0,0 +1,67 @@
+/**
+ * A customer's staff notes (headless spec §9.2 `customers`; W10-33). A note is an entry of the
+ * customer's history: `customers.get(id, { include: ['history'] })` lists it, type
+ * `CUSTOMER_NOTE`, with its id.
+ */
+import type { Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/** A staff note on a customer. */
+export interface CustomerNote {
+    id: string;
+    note: string;
+    /** Whether the customer sees it. */
+    isPublic: boolean;
+    /** ISO-8601 with offset. */
+    createdAt: string;
+    /** ISO-8601 with offset. */
+    updatedAt: string;
+    /**
+     * Set when the caller's customer-data level withheld the text (an app installation below
+     * `full`): `note` is then "", meaning "not granted".
+     */
+    redacted?: true;
+}
+export interface CustomerNoteInput {
+    note: string;
+    /** Whether the customer sees it. Default false: a note is for staff unless you say otherwise. */
+    isPublic?: boolean;
+}
+export interface CustomerNotesModule {
+    /**
+     * Add a note to the customer's history. Needs `UpdateCustomer`.
+     *
+     * It resolves with nothing: the engine answers the customer, not the note. The note's id (for
+     * `update` and `delete`) is on `customers.get(id, { include: ['history'] })`, newest first. A
+     * customer this store does not hold is a `NotFoundError` (`ENTITY_NOT_FOUND`).
+     *
+     * @effect write
+     */
+    add(customerId: string, input: CustomerNoteInput, options?: Call): Promise<void>;
+    /**
+     * Change a note's text. Needs `UpdateCustomer`. An empty text leaves the note as it is. An id
+     * that is not a note of this store is a `NotFoundError` (`ENTITY_NOT_FOUND`), the same as a
+     * missing one.
+     *
+     * The engine records an invitation as a note reading `Invitation sent (<MODE>) to <address>`,
+     * and {@link CustomersModule.invitationStatus} reads the last invitation from it: rewording or
+     * deleting that note makes the customer read as never invited.
+     *
+     * @effect write
+     */
+    update(noteId: string, input: {
+        note: string;
+    }, options?: Call): Promise<CustomerNote>;
+    /**
+     * Delete a note for good. Needs `UpdateCustomer`.
+     *
+     * Refused `CUSTOMER_NOTE_NOT_DELETED` (`ConflictError`, 409, as every `*_NOT_DELETED` of this
+     * SDK) with the engine's own reason when this store has no such note.
+     *
+     * @effect destructive
+     */
+    delete(noteId: string, options?: Call): Promise<void>;
+}
+export declare const ADD_CUSTOMER_NOTE_MUTATION = "\n  mutation AddNoteToCustomer($input: AddNoteToCustomerInput!) {\n    addNoteToCustomer(input: $input) {\n      id\n    }\n  }\n";
+export declare const UPDATE_CUSTOMER_NOTE_MUTATION = "\n  mutation UpdateCustomerNote($input: UpdateCustomerNoteInput!) {\n    updateCustomerNote(input: $input) {\n      id\n      isPublic\n      data\n      createdAt\n      updatedAt\n    }\n  }\n";
+export declare const DELETE_CUSTOMER_NOTE_MUTATION = "\n  mutation DeleteCustomerNote($id: ID!) {\n    deleteCustomerNote(id: $id) {\n      result\n      message\n    }\n  }\n";
+export declare function createCustomerNotesModule(transport: Transport): CustomerNotesModule;

package/dist/customers/notes.js

@@ -0,0 +1,51 @@
+import { assertDeleted, fieldOf } from '../catalog/types.js';
+import { customerDataField } from './wire.js';
+export const ADD_CUSTOMER_NOTE_MUTATION = /* GraphQL */ `
+  mutation AddNoteToCustomer($input: AddNoteToCustomerInput!) {
+    addNoteToCustomer(input: $input) {
+      id
+    }
+  }
+`;
+export const UPDATE_CUSTOMER_NOTE_MUTATION = /* GraphQL */ `
+  mutation UpdateCustomerNote($input: UpdateCustomerNoteInput!) {
+    updateCustomerNote(input: $input) {
+      id
+      isPublic
+      data
+      createdAt
+      updatedAt
+    }
+  }
+`;
+export const DELETE_CUSTOMER_NOTE_MUTATION = /* GraphQL */ `
+  mutation DeleteCustomerNote($id: ID!) {
+    deleteCustomerNote(id: $id) {
+      result
+      message
+    }
+  }
+`;
+export function createCustomerNotesModule(transport) {
+    return {
+        async add(customerId, input, options) {
+            await fieldOf(transport, ADD_CUSTOMER_NOTE_MUTATION, 'addNoteToCustomer', { input: { id: customerId, note: input.note, isPublic: input.isPublic ?? false } }, options);
+        },
+        async update(noteId, input, options) {
+            const { value: entry, mark } = await customerDataField(transport, UPDATE_CUSTOMER_NOTE_MUTATION, 'updateCustomerNote', { input: { noteId, note: input.note } }, options);
+            const text = entry.data?.note;
+            return mark({
+                id: entry.id,
+                note: typeof text === 'string' ? text : '',
+                isPublic: entry.isPublic,
+                createdAt: entry.createdAt,
+                updatedAt: entry.updatedAt,
+            });
+        },
+        async delete(noteId, options) {
+            assertDeleted('CUSTOMER_NOTE_NOT_DELETED', [
+                await fieldOf(transport, DELETE_CUSTOMER_NOTE_MUTATION, 'deleteCustomerNote', { id: noteId }, options),
+            ]);
+        },
+    };
+}