@sixtyninecommerce/admin 0.8.0 → 0.10.0

package/dist/customers/index.js

@@ -1,4 +1,7 @@
 import { errorFromErrorResult, isErrorResult, pageFromVendureList, readOffsetCursor, } 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';
 /**
  * Customers — the commerce master record (headless spec §6.5).
  *
@@ -15,6 +18,31 @@ import { errorFromErrorResult, isErrorResult, pageFromVendureList, readOffsetCur
  * 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 const CUSTOMER_FIELDS = /* GraphQL */ `
   id
@@ -71,10 +99,14 @@ export const ADDRESSES_QUERY = /* GraphQL */ `
 /**
  * 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 const CREATE_MUTATION = /* GraphQL */ `
-  mutation CreateChannelCustomer($input: CreateCustomerInput!, $password: String) {
-    createChannelCustomer(input: $input, password: $password) {
+  mutation CreateChannelCustomer($input: CreateCustomerInput!) {
+    createChannelCustomer(input: $input) {
       id
       emailAddress
       createdNew
@@ -109,6 +141,24 @@ export const RESEND_INVITE_MUTATION = /* GraphQL */ `
     }
   }
 `;
+/**
+ * "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 const INVITE_B2B_MUTATION = /* GraphQL */ `
+  mutation InviteB2BCustomers($input: InviteB2BCustomersInput) {
+    inviteB2BCustomers(input: $input) {
+      dryRun
+      total
+      eligible
+      skippedHasPassword
+      skippedPending
+      skippedUnreachable
+      jobId
+    }
+  }
+`;
 export const ERASE_MUTATION = /* GraphQL */ `
   mutation EraseCustomer(
     $customerId: ID!
@@ -143,6 +193,32 @@ export const ERASURE_QUERY = /* GraphQL */ `
     }
   }
 `;
+export const ACT_AS_MUTATION = /* GraphQL */ `
+  mutation ActAsCustomer($customerId: ID!, $reason: String!) {
+    actAsCustomer(customerId: $customerId, reason: $reason) {
+      id
+      customerId
+      token
+      expiresAt
+    }
+  }
+`;
+export const REQUEST_DATA_MUTATION = /* GraphQL */ `
+  mutation RequestCustomerData($customerId: ID!, $reason: String!, $idempotencyKey: String) {
+    requestCustomerData(customerId: $customerId, reason: $reason, idempotencyKey: $idempotencyKey) {
+      ${COMPLIANCE_REQUEST_FIELDS}
+    }
+  }
+`;
+export const END_AGENT_SESSION_MUTATION = /* GraphQL */ `
+  mutation EndCustomerAgentSession($sessionId: ID!) {
+    endCustomerAgentSession(sessionId: $sessionId) {
+      id
+      customerId
+      revokedAt
+    }
+  }
+`;
 export const ADD_TO_GROUP_MUTATION = /* GraphQL */ `
   mutation AddCustomersToGroup($customerGroupId: ID!, $customerIds: [ID!]!) {
     addCustomersToGroup(customerGroupId: $customerGroupId, customerIds: $customerIds) {
@@ -159,6 +235,111 @@ export const REMOVE_FROM_GROUP_MUTATION = /* GraphQL */ `
     }
   }
 `;
+/**
+ * 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 const CUSTOMER_EXTERNAL_REF_FIELDS = /* GraphQL */ `
+  id
+  createdAt
+  updatedAt
+  system
+  ref
+`;
+export const EXTERNAL_KEYED_GROUP_FIELDS = /* GraphQL */ `
+  id
+  name
+  externalKey
+  ${CATALOGUE_OWNERSHIP_FIELDS}
+`;
+export const BY_EXTERNAL_REF_QUERY = /* GraphQL */ `
+  query CustomerByExternalRef($system: String!, $ref: String!) {
+    customerByExternalRef(system: $system, ref: $ref) { ${CUSTOMER_FIELDS} }
+  }
+`;
+export const EXTERNAL_REFS_QUERY = /* GraphQL */ `
+  query CustomerExternalRefs($id: ID!) {
+    customer(id: $id) {
+      id
+      externalRefs { ${CUSTOMER_EXTERNAL_REF_FIELDS} }
+    }
+  }
+`;
+export const UPSERT_BY_EXTERNAL_REF_MUTATION = /* GraphQL */ `
+  mutation UpsertCustomerByExternalRef(
+    $input: UpsertCustomerByExternalRefInput!
+    $idempotencyKey: String
+  ) {
+    upsertCustomerByExternalRef(input: $input, idempotencyKey: $idempotencyKey) {
+      customer { ${CUSTOMER_FIELDS} }
+      created
+      matchedByEmail
+      updated
+    }
+  }
+`;
+export const GROUP_BY_EXTERNAL_KEY_QUERY = /* GraphQL */ `
+  query CustomerGroupByExternalKey($key: String!) {
+    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) {
+      id
+      externalKey
+    }
+  }
+`;
+export const UPSERT_GROUP_BY_EXTERNAL_KEY_MUTATION = /* GraphQL */ `
+  mutation UpsertCustomerGroupByExternalKey($key: String!, $name: String!) {
+    upsertCustomerGroupByExternalKey(key: $key, name: $name) {
+      customerGroup { ${EXTERNAL_KEYED_GROUP_FIELDS} }
+      created
+      renamed
+    }
+  }
+`;
+export const REPLACE_GROUP_MEMBERS_MUTATION = /* GraphQL */ `
+  mutation ReplaceCustomerGroupMembers(
+    $key: String!
+    $customerExternalRefs: [CustomerExternalRefInput!]!
+    $idempotencyKey: String
+  ) {
+    replaceCustomerGroupMembers(
+      key: $key
+      customerExternalRefs: $customerExternalRefs
+      idempotencyKey: $idempotencyKey
+    ) {
+      customerGroup { ${EXTERNAL_KEYED_GROUP_FIELDS} }
+      memberCount
+      added
+      removed
+      unknownRefs {
+        system
+        ref
+      }
+    }
+  }
+`;
+/** The most member keys one `customers.groups.replaceMembers` call takes. */
+export const MAX_REPLACE_GROUP_MEMBERS = 5000;
 export const CREATE_ADDRESS_MUTATION = /* GraphQL */ `
   mutation CreateCustomerAddress($customerId: ID!, $input: CreateAddressInput!) {
     createCustomerAddress(customerId: $customerId, input: $input) {
@@ -179,7 +360,14 @@ export const DELETE_ADDRESS_MUTATION = /* GraphQL */ `
 const DEFAULT_PAGE_SIZE = 25;
 export function createCustomersModule(transport) {
     const listPage = async (skip, take, options) => {
-        const data = await transport.graphql({ api: 'admin', query: LIST_QUERY, variables: { options: { skip, take } } }, options);
+        const redaction = redactionWatcher();
+        const data = await transport.graphql({
+            api: 'admin',
+            query: LIST_QUERY,
+            variables: { options: { skip, take } },
+            onExtensions: redaction.onExtensions,
+        }, options);
+        data.customers.items.forEach(redaction.mark);
         return pageFromVendureList(data.customers, skip, take, (cursor) => listPage(readOffsetCursor(cursor), take, options));
     };
     return {
@@ -191,19 +379,28 @@ export function createCustomersModule(transport) {
             return listPage(skip, take, options);
         },
         async get(id, options) {
-            const data = await transport.graphql({ api: 'admin', query: GET_QUERY, variables: { id } }, options);
-            return data.customer;
+            const redaction = redactionWatcher();
+            const data = await transport.graphql({ api: 'admin', query: GET_QUERY, variables: { id }, onExtensions: redaction.onExtensions }, options);
+            return redaction.mark(data.customer);
         },
         async create(input, options) {
+            const redaction = redactionWatcher();
             const data = await transport.graphql({
                 api: 'admin',
                 query: CREATE_MUTATION,
-                variables: { input, password: options?.password ?? null },
+                variables: { input },
+                onExtensions: redaction.onExtensions,
             }, options);
-            return data.createChannelCustomer;
+            return redaction.mark(data.createChannelCustomer);
         },
         async update(id, input, options) {
-            const data = await transport.graphql({ api: 'admin', query: UPDATE_MUTATION, variables: { input: { id, ...input } } }, options);
+            const redaction = redactionWatcher();
+            const data = await transport.graphql({
+                api: 'admin',
+                query: UPDATE_MUTATION,
+                variables: { input: { id, ...input } },
+                onExtensions: redaction.onExtensions,
+            }, options);
             // `updateCustomer` is a UNION — `Customer | EmailAddressConflictError` —
             // delivered at HTTP 200, so the transport never throws for it. Returned
             // unchecked, a rename onto an address already taken on the channel
@@ -211,7 +408,8 @@ export function createCustomersModule(transport) {
             // `Customer` whose `id` was undefined.
             if (isErrorResult(data.updateCustomer))
                 throw errorFromErrorResult(data.updateCustomer);
-            return data.updateCustomer;
+            // The Admin API redacts a mutation's answer like a read's.
+            return redaction.mark(data.updateCustomer);
         },
         async invite(id, options) {
             // `resend` picks the SEPARATE mutation rather than a flag on one: the two
@@ -223,6 +421,19 @@ 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);
         },
+        async inviteB2B(options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: INVITE_B2B_MUTATION,
+                variables: {
+                    input: {
+                        dryRun: options?.dryRun ?? null,
+                        includePending: options?.includePending ?? null,
+                    },
+                },
+            }, options);
+            return data.inviteB2BCustomers;
+        },
         async erase(id, options) {
             const data = await transport.graphql({
                 api: 'admin',
@@ -240,7 +451,85 @@ export function createCustomersModule(transport) {
             const data = await transport.graphql({ api: 'admin', query: ERASURE_QUERY, variables: { customerId: id } }, options);
             return data.customerErasure;
         },
+        async requestData(id, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: REQUEST_DATA_MUTATION,
+                variables: {
+                    customerId: id,
+                    reason: options.reason,
+                    idempotencyKey: options.idempotencyKey ?? null,
+                },
+            }, options);
+            return data.requestCustomerData;
+        },
+        async actAs(customerId, options) {
+            const data = await transport.graphql({ api: 'admin', query: ACT_AS_MUTATION, variables: { customerId, reason: options.reason } }, options);
+            return data.actAsCustomer;
+        },
+        async endAgentSession(sessionId, options) {
+            const data = await transport.graphql({ api: 'admin', query: END_AGENT_SESSION_MUTATION, variables: { sessionId } }, options);
+            return data.endCustomerAgentSession;
+        },
+        async byExternalRef(system, ref, options) {
+            const redaction = redactionWatcher();
+            const data = await transport.graphql({
+                api: 'admin',
+                query: BY_EXTERNAL_REF_QUERY,
+                variables: { system, ref },
+                onExtensions: redaction.onExtensions,
+            }, options);
+            return redaction.mark(data.customerByExternalRef);
+        },
+        async externalRefs(customerId, options) {
+            const data = await transport.graphql({ api: 'admin', query: EXTERNAL_REFS_QUERY, variables: { id: customerId } }, options);
+            return data.customer?.externalRefs ?? [];
+        },
+        async upsertByExternalRef(input, options) {
+            const redaction = redactionWatcher();
+            const data = await transport.graphql({
+                api: 'admin',
+                query: UPSERT_BY_EXTERNAL_REF_MUTATION,
+                variables: { input, idempotencyKey: options?.idempotencyKey ?? null },
+                onExtensions: redaction.onExtensions,
+            }, options);
+            const result = data.upsertCustomerByExternalRef;
+            redaction.mark(result.customer);
+            return result;
+        },
         groups: {
+            async get(id, options) {
+                const data = await transport.graphql({ api: 'admin', query: CUSTOMER_GROUP_QUERY, variables: { id } }, options);
+                return data.customerGroup;
+            },
+            async byExternalKey(key, options) {
+                const data = await transport.graphql({ api: 'admin', query: GROUP_BY_EXTERNAL_KEY_QUERY, variables: { key } }, options);
+                return data.customerGroupByExternalKey;
+            },
+            async externalKey(groupId, options) {
+                const data = await transport.graphql({ api: 'admin', query: GROUP_EXTERNAL_KEY_QUERY, variables: { id: groupId } }, options);
+                return data.customerGroup?.externalKey ?? null;
+            },
+            async upsertByExternalKey(key, name, options) {
+                const data = await transport.graphql({ api: 'admin', query: UPSERT_GROUP_BY_EXTERNAL_KEY_MUTATION, variables: { key, name } }, options);
+                return data.upsertCustomerGroupByExternalKey;
+            },
+            async replaceMembers(key, customerExternalRefs, options) {
+                const data = await transport.graphql({
+                    api: 'admin',
+                    query: REPLACE_GROUP_MEMBERS_MUTATION,
+                    variables: {
+                        key,
+                        // Only the two fields the input type declares: an extra one fails validation.
+                        customerExternalRefs: customerExternalRefs.map(({ system, ref }) => ({
+                            system,
+                            ref,
+                        })),
+                        idempotencyKey: options?.idempotencyKey ?? null,
+                    },
+                }, options);
+                return data.replaceCustomerGroupMembers;
+            },
             async add(groupId, customerIds, options) {
                 const data = await transport.graphql({
                     api: 'admin',
@@ -260,16 +549,34 @@ export function createCustomersModule(transport) {
         },
         addresses: {
             async list(customerId, options) {
-                const data = await transport.graphql({ api: 'admin', query: ADDRESSES_QUERY, variables: { id: customerId } }, options);
-                return data.customer?.addresses ?? [];
+                const redaction = redactionWatcher();
+                const data = await transport.graphql({
+                    api: 'admin',
+                    query: ADDRESSES_QUERY,
+                    variables: { id: customerId },
+                    onExtensions: redaction.onExtensions,
+                }, options);
+                return (data.customer?.addresses ?? []).map(redaction.mark);
             },
             async create(customerId, input, options) {
-                const data = await transport.graphql({ api: 'admin', query: CREATE_ADDRESS_MUTATION, variables: { customerId, input } }, options);
-                return data.createCustomerAddress;
+                const redaction = redactionWatcher();
+                const data = await transport.graphql({
+                    api: 'admin',
+                    query: CREATE_ADDRESS_MUTATION,
+                    variables: { customerId, input },
+                    onExtensions: redaction.onExtensions,
+                }, options);
+                return redaction.mark(data.createCustomerAddress);
             },
             async update(input, options) {
-                const data = await transport.graphql({ api: 'admin', query: UPDATE_ADDRESS_MUTATION, variables: { input } }, options);
-                return data.updateCustomerAddress;
+                const redaction = redactionWatcher();
+                const data = await transport.graphql({
+                    api: 'admin',
+                    query: UPDATE_ADDRESS_MUTATION,
+                    variables: { input },
+                    onExtensions: redaction.onExtensions,
+                }, options);
+                return redaction.mark(data.updateCustomerAddress);
             },
             async delete(id, options) {
                 await transport.graphql({ api: 'admin', query: DELETE_ADDRESS_MUTATION, variables: { id } }, options);