@sixtyninecommerce/admin 0.10.0 → 0.11.0

package/dist/customers/groups.js

@@ -0,0 +1,438 @@
+/**
+ * Customer groups: the store's list, one group with a page of its members, create, change and
+ * delete, and which groups the store treats as trade (headless spec §9.2 `customers` "groups";
+ * W10-34). The membership doors (`add`, `remove`) and the customer master's external keys are
+ * wired beside these in `index.ts`.
+ *
+ * A group is the store's own row, or its organization's (`catalogueOwnership`): one row for every
+ * store that holds it. Its members are always the store's own customers.
+ */
+import { ConflictError, pageFromVendureList, readOffsetCursor, ValidationError, } from '@sixtyninecommerce/core';
+import { assertDeleted, CATALOGUE_OWNERSHIP_FIELDS, DELETION_FIELDS, fieldOf, } from '../catalog/types.js';
+import { redactionWatcher } from '../customer-data-redaction.js';
+import { companyOf } from './wire.js';
+/** The engine's `adminListQueryLimit`: a larger page is refused. */
+export const MAX_CUSTOMER_GROUP_LIST_TAKE = 1000;
+export const CUSTOMER_GROUP_LIST_SORT_FIELDS = ['name', 'createdAt', 'updatedAt'];
+/** The blocks a list row can add: `memberCount`, how many of the store's customers are in it. */
+export const CUSTOMER_GROUP_LIST_INCLUDES = ['memberCount'];
+const GROUP_FLAG_FIELDS = /* GraphQL */ `
+  customFields {
+    canViewIncomingStock
+    canBackorder
+  }
+`;
+/** A customer group as `get`, `create` and `update` read it. */
+export const CUSTOMER_GROUP_FIELDS = /* GraphQL */ `
+  id
+  createdAt
+  updatedAt
+  name
+  externalKey
+  ${GROUP_FLAG_FIELDS}
+  ${CATALOGUE_OWNERSHIP_FIELDS}
+`;
+export const CUSTOMER_GROUP_QUERY = /* GraphQL */ `
+  query CustomerGroup($id: ID!) {
+    customerGroup(id: $id) { ${CUSTOMER_GROUP_FIELDS} }
+  }
+`;
+export const CUSTOMER_GROUP_MEMBERS_QUERY = /* GraphQL */ `
+  query CustomerGroupWithMembers($id: ID!, $members: CustomerListOptions) {
+    customerGroup(id: $id) {
+      ${CUSTOMER_GROUP_FIELDS}
+      customers(options: $members) {
+        items {
+          id
+          createdAt
+          firstName
+          lastName
+          emailAddress
+          addresses {
+            company
+            defaultBillingAddress
+            defaultShippingAddress
+          }
+        }
+        totalItems
+      }
+    }
+  }
+`;
+const GROUP_LIST_FIELDS = /* GraphQL */ `
+  id
+  createdAt
+  updatedAt
+  name
+  ${GROUP_FLAG_FIELDS}
+`;
+/**
+ * The list document for a set of blocks. The member count is the `totalItems` of a one-row page
+ * of the group's customers: a `take` of 0 would make that page every member.
+ *
+ * The count is still not a one-row read on the engine. channel-customer's `customerGroups` and
+ * `customerGroup` resolvers carry core's bare `@Relations(CustomerGroup)`, so for a document that
+ * selects `customers` under a group they also hand the service the `customers` relation, and it
+ * loads every member of each answered group before the field resolver counts or pages them (read
+ * in the plugin and core 3.6.3, not measured; the dashboard's documents before this module had
+ * the same shape). So `memberCount` is an `include`, asked for only where a count is shown. The
+ * fix is `omit: ['customers']` on those two resolvers, which this package cannot make.
+ */
+export function customerGroupListQuery(include) {
+    const memberCount = include.includes('memberCount')
+        ? 'customers(options: { take: 1 }) { totalItems }'
+        : '';
+    return /* GraphQL */ `
+    query CustomerGroups($options: CustomerGroupListOptions) {
+      customerGroups(options: $options) {
+        items {
+          ${GROUP_LIST_FIELDS}
+          ${memberCount}
+        }
+        totalItems
+      }
+    }
+  `;
+}
+export const CREATE_CUSTOMER_GROUP_MUTATION = /* GraphQL */ `
+  mutation CreateCustomerGroup($input: CreateCustomerGroupInput!) {
+    createCustomerGroup(input: $input) { ${CUSTOMER_GROUP_FIELDS} }
+  }
+`;
+export const UPDATE_CUSTOMER_GROUP_MUTATION = /* GraphQL */ `
+  mutation UpdateCustomerGroup($input: UpdateCustomerGroupInput!) {
+    updateCustomerGroup(input: $input) { ${CUSTOMER_GROUP_FIELDS} }
+  }
+`;
+export const DELETE_CUSTOMER_GROUP_MUTATION = /* GraphQL */ `
+  mutation DeleteCustomerGroup($id: ID!) {
+    deleteCustomerGroup(id: $id) { ${DELETION_FIELDS} }
+  }
+`;
+export const DELETE_CUSTOMER_GROUPS_MUTATION = /* GraphQL */ `
+  mutation DeleteCustomerGroups($ids: [ID!]!) {
+    deleteCustomerGroups(ids: $ids) { ${DELETION_FIELDS} }
+  }
+`;
+export const B2B_CUSTOMER_GROUPS_QUERY = /* GraphQL */ `
+  query CustomerGroupRefs {
+    b2bCustomerGroups {
+      id
+      name
+    }
+  }
+`;
+export const SET_B2B_CUSTOMER_GROUPS_MUTATION = /* GraphQL */ `
+  mutation SetCustomerGroupRefs($groupIds: [ID!]!) {
+    setB2BCustomerGroups(groupIds: $groupIds) {
+      id
+      name
+    }
+  }
+`;
+const DEFAULT_PAGE_SIZE = 25;
+function invalid(code, message) {
+    return new ValidationError({ code, message, status: 400, service: 'vendure' });
+}
+const invalidListOptions = (message) => invalid('INVALID_CUSTOMER_GROUP_LIST_OPTIONS', message);
+const invalidMembersOptions = (message) => invalid('INVALID_CUSTOMER_GROUP_MEMBERS_OPTIONS', message);
+const invalidInput = (message) => invalid('INVALID_CUSTOMER_GROUP_INPUT', message);
+const isIdList = (value) => Array.isArray(value) && value.every((id) => typeof id === 'string');
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const isPageSize = (take) => typeof take === 'number' &&
+    Number.isInteger(take) &&
+    take >= 1 &&
+    take <= MAX_CUSTOMER_GROUP_LIST_TAKE;
+const isOffset = (skip) => typeof skip === 'number' && Number.isInteger(skip) && skip >= 0;
+/** Both flags are `false` unless the engine answers `true`: a group has no third state. */
+function flagsOf(wire) {
+    return {
+        canViewIncomingStock: wire.customFields?.canViewIncomingStock === true,
+        canBackorder: wire.customFields?.canBackorder === true,
+    };
+}
+function toCustomerGroup(wire) {
+    return {
+        id: wire.id,
+        createdAt: wire.createdAt,
+        updatedAt: wire.updatedAt,
+        name: wire.name,
+        externalKey: wire.externalKey,
+        ...flagsOf(wire),
+        catalogueOwnership: wire.catalogueOwnership,
+    };
+}
+function toMember(wire) {
+    const addresses = wire.addresses ?? [];
+    return {
+        id: wire.id,
+        createdAt: wire.createdAt,
+        firstName: wire.firstName,
+        lastName: wire.lastName,
+        emailAddress: wire.emailAddress,
+        addresses,
+        company: companyOf(addresses),
+    };
+}
+function toListItem(wire) {
+    return {
+        id: wire.id,
+        createdAt: wire.createdAt,
+        updatedAt: wire.updatedAt,
+        name: wire.name,
+        ...flagsOf(wire),
+        ...(wire.customers === undefined ? {} : { memberCount: wire.customers.totalItems }),
+    };
+}
+/**
+ * Members are read in one fixed order, by id. The engine orders a list with no sort however the
+ * database returns it, so two pages of one walk could repeat or skip a member; an id is unique,
+ * and is not customer data (an app below `customerData: full` is refused a sort on a field its
+ * level withholds).
+ */
+const MEMBERS_SORT = { id: 'ASC' };
+/** The Admin API's `CustomerListOptions` for a page of members; anything else is refused. */
+function membersVariables(members) {
+    if (!isObject(members))
+        throw invalidMembersOptions('members must be an object.');
+    for (const key of Object.keys(members)) {
+        if (key !== 'skip' && key !== 'take' && key !== 'filter') {
+            throw invalidMembersOptions(`members.${key} is not an option of a members page.`);
+        }
+    }
+    const take = members.take ?? DEFAULT_PAGE_SIZE;
+    const skip = members.skip ?? 0;
+    if (!isPageSize(take)) {
+        throw invalidMembersOptions(`members.take must be a whole number from 1 to ${String(MAX_CUSTOMER_GROUP_LIST_TAKE)}.`);
+    }
+    if (!isOffset(skip)) {
+        throw invalidMembersOptions('members.skip must be a whole number of 0 or more.');
+    }
+    const page = { skip, take, sort: MEMBERS_SORT };
+    const filter = members.filter;
+    if (filter === undefined)
+        return page;
+    if (!isObject(filter))
+        throw invalidMembersOptions('members.filter must be an object.');
+    for (const key of Object.keys(filter)) {
+        if (key !== 'ids')
+            throw invalidMembersOptions(`members.filter.${key} is not a members filter.`);
+    }
+    if (filter.ids === undefined)
+        return page;
+    if (!isIdList(filter.ids)) {
+        throw invalidMembersOptions('members.filter.ids must be a list of strings.');
+    }
+    return { ...page, filter: { id: { in: [...filter.ids] } } };
+}
+/** `customers.groups.get`. */
+export async function readCustomerGroup(transport, id, options) {
+    const members = options?.members === undefined ? null : membersVariables(options.members);
+    const redaction = redactionWatcher();
+    const data = await transport.graphql({
+        api: 'admin',
+        query: members === null ? CUSTOMER_GROUP_QUERY : CUSTOMER_GROUP_MEMBERS_QUERY,
+        variables: members === null ? { id } : { id, members },
+        onExtensions: redaction.onExtensions,
+    }, options);
+    const wire = data.customerGroup;
+    if (wire === null)
+        return null;
+    const group = toCustomerGroup(wire);
+    if (members === null)
+        return group;
+    const page = wire.customers ?? { items: [], totalItems: 0 };
+    return {
+        ...group,
+        members: {
+            items: page.items.map((member) => redaction.mark(toMember(member))),
+            total: page.totalItems,
+        },
+    };
+}
+function listFilter(filter) {
+    if (filter === undefined)
+        return {};
+    if (!isObject(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 (!isIdList(value))
+                    throw invalidListOptions('filter.ids must be a list of strings.');
+                out.id = { in: [...value] };
+                break;
+            case 'name':
+                if (typeof value !== 'string')
+                    throw invalidListOptions('filter.name must be a string.');
+                out.name = { contains: value };
+                break;
+            default:
+                throw invalidListOptions(`filter.${key} is not a customer group list filter.`);
+        }
+    }
+    return out;
+}
+function listRequest(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 (!isPageSize(take)) {
+        throw invalidListOptions(`take must be a whole number from 1 to ${String(MAX_CUSTOMER_GROUP_LIST_TAKE)}.`);
+    }
+    if (!isOffset(skip))
+        throw invalidListOptions('skip must be a whole number of 0 or more.');
+    const sort = options?.sort;
+    if (sort !== undefined &&
+        (!isObject(sort) ||
+            !CUSTOMER_GROUP_LIST_SORT_FIELDS.includes(sort.field) ||
+            (sort.direction !== 'ASC' && sort.direction !== 'DESC'))) {
+        throw invalidListOptions(`sort must be { field: ${CUSTOMER_GROUP_LIST_SORT_FIELDS.join(' | ')}, direction: ASC | DESC }.`);
+    }
+    const include = options?.include ?? [];
+    if (!Array.isArray(include) ||
+        !include.every((name) => CUSTOMER_GROUP_LIST_INCLUDES.includes(name))) {
+        throw invalidListOptions(`include takes a list of ${CUSTOMER_GROUP_LIST_INCLUDES.join(', ')}.`);
+    }
+    const filter = listFilter(options?.filter);
+    // The engine orders a list with no sort however the database returns it, so two pages of one
+    // walk could repeat or skip a group: every list is sorted, by name unless the caller says.
+    // ONE key only: the engine applies several in its schema's field order, never the order sent.
+    const order = sort;
+    return {
+        skip,
+        take,
+        request: {
+            query: customerGroupListQuery(include),
+            ...(Object.keys(filter).length > 0 ? { filter } : {}),
+            sort: order ? { [order.field]: order.direction } : { name: 'ASC' },
+        },
+    };
+}
+async function listPage(transport, skip, take, request, options) {
+    const data = await transport.graphql({
+        api: 'admin',
+        query: request.query,
+        variables: {
+            options: {
+                skip,
+                take,
+                sort: request.sort,
+                ...(request.filter ? { filter: request.filter, filterOperator: 'AND' } : {}),
+            },
+        },
+    }, options);
+    // Each following page re-sends the same filter, sort, blocks and per-call options.
+    return pageFromVendureList({
+        items: data.customerGroups.items.map(toListItem),
+        totalItems: data.customerGroups.totalItems,
+    }, skip, take, (cursor) => listPage(transport, readOffsetCursor(cursor), take, request, options));
+}
+/** `customers.groups.list`. A refused option rejects the promise, like an engine refusal. */
+export async function listCustomerGroups(transport, options) {
+    const { skip, take, request } = listRequest(options);
+    return listPage(transport, skip, take, request, options);
+}
+/** Only the flags the caller set travel: an omitted flag is never sent as `null`. */
+function flagFields(input) {
+    const customFields = {};
+    for (const flag of ['canViewIncomingStock', 'canBackorder']) {
+        const value = input[flag];
+        if (value === undefined)
+            continue;
+        if (typeof value !== 'boolean')
+            throw invalidInput(`${flag} must be true or false.`);
+        customFields[flag] = value;
+    }
+    return Object.keys(customFields).length > 0 ? { customFields } : {};
+}
+/** `customers.groups.create`. */
+export async function createCustomerGroup(transport, input, options) {
+    if (!isObject(input) || typeof input.name !== 'string') {
+        throw invalidInput('A customer group needs a name.');
+    }
+    if (input.customerIds !== undefined && !isIdList(input.customerIds)) {
+        throw invalidInput('customerIds must be a list of strings.');
+    }
+    const wire = await fieldOf(transport, CREATE_CUSTOMER_GROUP_MUTATION, 'createCustomerGroup', {
+        input: {
+            name: input.name,
+            ...(input.customerIds === undefined ? {} : { customerIds: [...input.customerIds] }),
+            ...flagFields(input),
+        },
+    }, options);
+    return toCustomerGroup(wire);
+}
+/** `customers.groups.update`. */
+export async function updateCustomerGroup(transport, id, input, options) {
+    if (!isObject(input))
+        throw invalidInput('The change to a customer group must be an object.');
+    if (input.name !== undefined && typeof input.name !== 'string') {
+        throw invalidInput('name must be a string.');
+    }
+    const wire = await fieldOf(transport, UPDATE_CUSTOMER_GROUP_MUTATION, 'updateCustomerGroup', {
+        input: {
+            id,
+            ...(input.name === undefined ? {} : { name: input.name }),
+            ...flagFields(input),
+        },
+    }, options);
+    return toCustomerGroup(wire);
+}
+/** `customers.groups.delete`. */
+export async function deleteCustomerGroup(transport, id, options) {
+    assertDeleted('CUSTOMER_GROUP_NOT_DELETED', [
+        await fieldOf(transport, DELETE_CUSTOMER_GROUP_MUTATION, 'deleteCustomerGroup', { id }, options),
+    ]);
+}
+/** `customers.groups.deleteMany`. */
+export async function deleteCustomerGroups(transport, ids, options) {
+    if (!isIdList(ids))
+        throw invalidInput('ids must be a list of strings.');
+    if (ids.length === 0)
+        return;
+    const responses = await fieldOf(transport, DELETE_CUSTOMER_GROUPS_MUTATION, 'deleteCustomerGroups', { ids: [...ids] }, options);
+    // One answer per id, in the order sent. A missing answer is not a deletion.
+    const kept = ids.flatMap((id, index) => {
+        const response = responses[index];
+        return response?.result === 'DELETED'
+            ? []
+            : [{ id, index, reason: response?.message ?? 'The server gave no reason.' }];
+    });
+    if (kept.length === 0)
+        return;
+    // Answered at HTTP 200, so the transport never throws for it. The groups not named here WERE
+    // deleted: the engine refuses the whole call only for a group its sharing rule protects.
+    throw new ConflictError({
+        code: 'CUSTOMER_GROUP_NOT_DELETED',
+        message: kept.length === ids.length
+            ? `No customer group was deleted: ${kept[0]?.reason ?? ''}`
+            : `${String(kept.length)} of ${String(ids.length)} customer groups were not deleted (the others were): ${kept[0]?.reason ?? ''}`,
+        status: 409,
+        service: 'vendure',
+        details: kept.map(({ id, index, reason }) => ({
+            field: `ids.${String(index)}`,
+            code: 'CUSTOMER_GROUP_NOT_DELETED',
+            message: `${id}: ${reason}`,
+        })),
+    });
+}
+export function createCustomerB2BGroupsModule(transport) {
+    return {
+        list(options) {
+            return fieldOf(transport, B2B_CUSTOMER_GROUPS_QUERY, 'b2bCustomerGroups', {}, options);
+        },
+        async set(groupIds, options) {
+            if (!isIdList(groupIds))
+                throw invalidInput('groupIds must be a list of strings.');
+            return fieldOf(transport, SET_B2B_CUSTOMER_GROUPS_MUTATION, 'setB2BCustomerGroups', 
+            // Each group once: the engine keeps one row per group and store, and a repeat fails its insert.
+            { groupIds: [...new Set(groupIds)] }, options);
+        },
+    };
+}