@sixtyninecommerce/admin 0.10.0 → 0.12.0

package/dist/customers/notification-recipients.d.ts

@@ -0,0 +1,97 @@
+/**
+ * A customer's additional notification recipients (headless spec §9.2 `customers` "notification
+ * recipients"; W10-33): extra addresses (accounting, purchasing, a warehouse) the store's order
+ * emails to the customer also go to. Who an order's document email goes to with them applied is
+ * `documents.emailRecipients`.
+ */
+import type { Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+export interface CustomerNotificationRecipient {
+    id: string;
+    /** ISO-8601 with offset. */
+    createdAt: string;
+    /** ISO-8601 with offset. */
+    updatedAt: string;
+    email: string;
+    label: string | null;
+    /**
+     * The notification event codes the recipient receives (`order_placed`, `order_shipped`,
+     * `invoice_generated`, …). Empty means every event a customer's contacts may receive; a
+     * security email (password reset, verification) never goes to a recipient.
+     */
+    events: string[];
+    enabled: boolean;
+    /**
+     * "Send only to this address": for its events the address takes the customer's own place
+     * instead of being copied beside it.
+     */
+    replaceCustomerEmail: boolean;
+    /**
+     * Set when the caller's customer-data level blanked `email` or `label` (an app installation
+     * below `identity`): "" or null then means "not granted". Never write such a recipient back.
+     */
+    redacted?: true;
+}
+export interface CreateNotificationRecipientInput {
+    customerId: string;
+    email: string;
+    label?: string | null;
+    /** Empty or left out: every event a customer's contacts may receive. */
+    events?: string[];
+    /** Default true. */
+    enabled?: boolean;
+    /** Default false. */
+    replaceCustomerEmail?: boolean;
+}
+export interface UpdateNotificationRecipientInput {
+    email?: string;
+    /** `null` clears the label. */
+    label?: string | null;
+    events?: string[];
+    enabled?: boolean;
+    replaceCustomerEmail?: boolean;
+}
+export interface CustomerNotificationRecipientsModule {
+    /**
+     * The customer's notification recipients in this store, oldest first; `[]` for a customer
+     * with none, and for one the store does not hold. Needs `ReadCustomer`.
+     *
+     * @effect read
+     */
+    list(customerId: string, options?: Call): Promise<CustomerNotificationRecipient[]>;
+    /**
+     * Add a recipient to a customer. Needs `UpdateCustomer`.
+     *
+     * Refused with the engine's sentence (`ValidationError`, `USER_INPUT_ERROR`, 400): a value
+     * that is not an email address, an address the customer already has as a recipient, an event
+     * code a customer's contacts may not receive, a label over 100 characters, or a customer that
+     * already has 20. A customer this store does not hold is a `NotFoundError`
+     * (`ENTITY_NOT_FOUND`); an engine older than that check saved the recipient under any id,
+     * where no read ever showed it.
+     *
+     * @effect write
+     */
+    create(input: CreateNotificationRecipientInput, options?: Call): Promise<CustomerNotificationRecipient>;
+    /**
+     * Change a recipient; what is left out is kept. Needs `UpdateCustomer`. Refused like
+     * {@link create}, and for an id that is not a recipient of this store.
+     *
+     * @effect write
+     */
+    update(id: string, input: UpdateNotificationRecipientInput, options?: Call): Promise<CustomerNotificationRecipient>;
+    /**
+     * Remove a recipient: the store's emails stop going to the address. Needs `UpdateCustomer`.
+     *
+     * Refused `CUSTOMER_NOTIFICATION_RECIPIENT_NOT_DELETED` (`ConflictError`, 409) with the
+     * engine's own reason when this store has no such recipient.
+     *
+     * @effect destructive
+     */
+    delete(id: string, options?: Call): Promise<void>;
+}
+export declare const NOTIFICATION_RECIPIENT_FIELDS = "\n  id\n  createdAt\n  updatedAt\n  email\n  label\n  events\n  enabled\n  replaceCustomerEmail\n";
+export declare const NOTIFICATION_RECIPIENTS_QUERY = "\n  query CustomerNotificationRecipients($id: ID!) {\n    customer(id: $id) {\n      id\n      notificationRecipients {\n        \n  id\n  createdAt\n  updatedAt\n  email\n  label\n  events\n  enabled\n  replaceCustomerEmail\n\n      }\n    }\n  }\n";
+export declare const CREATE_NOTIFICATION_RECIPIENT_MUTATION = "\n  mutation CreateCustomerNotificationRecipient($input: CreateCustomerNotificationRecipientInput!) {\n    createCustomerNotificationRecipient(input: $input) {\n      \n  id\n  createdAt\n  updatedAt\n  email\n  label\n  events\n  enabled\n  replaceCustomerEmail\n\n    }\n  }\n";
+export declare const UPDATE_NOTIFICATION_RECIPIENT_MUTATION = "\n  mutation UpdateCustomerNotificationRecipient($input: UpdateCustomerNotificationRecipientInput!) {\n    updateCustomerNotificationRecipient(input: $input) {\n      \n  id\n  createdAt\n  updatedAt\n  email\n  label\n  events\n  enabled\n  replaceCustomerEmail\n\n    }\n  }\n";
+export declare const DELETE_NOTIFICATION_RECIPIENT_MUTATION = "\n  mutation DeleteCustomerNotificationRecipient($id: ID!) {\n    deleteCustomerNotificationRecipient(id: $id) {\n      result\n      message\n    }\n  }\n";
+export declare function createCustomerNotificationRecipientsModule(transport: Transport): CustomerNotificationRecipientsModule;

package/dist/customers/notification-recipients.js

@@ -0,0 +1,84 @@
+import { assertDeleted, fieldOf } from '../catalog/types.js';
+import { customerDataField } from './wire.js';
+export const NOTIFICATION_RECIPIENT_FIELDS = /* GraphQL */ `
+  id
+  createdAt
+  updatedAt
+  email
+  label
+  events
+  enabled
+  replaceCustomerEmail
+`;
+export const NOTIFICATION_RECIPIENTS_QUERY = /* GraphQL */ `
+  query CustomerNotificationRecipients($id: ID!) {
+    customer(id: $id) {
+      id
+      notificationRecipients {
+        ${NOTIFICATION_RECIPIENT_FIELDS}
+      }
+    }
+  }
+`;
+export const CREATE_NOTIFICATION_RECIPIENT_MUTATION = /* GraphQL */ `
+  mutation CreateCustomerNotificationRecipient($input: CreateCustomerNotificationRecipientInput!) {
+    createCustomerNotificationRecipient(input: $input) {
+      ${NOTIFICATION_RECIPIENT_FIELDS}
+    }
+  }
+`;
+export const UPDATE_NOTIFICATION_RECIPIENT_MUTATION = /* GraphQL */ `
+  mutation UpdateCustomerNotificationRecipient($input: UpdateCustomerNotificationRecipientInput!) {
+    updateCustomerNotificationRecipient(input: $input) {
+      ${NOTIFICATION_RECIPIENT_FIELDS}
+    }
+  }
+`;
+export const DELETE_NOTIFICATION_RECIPIENT_MUTATION = /* GraphQL */ `
+  mutation DeleteCustomerNotificationRecipient($id: ID!) {
+    deleteCustomerNotificationRecipient(id: $id) {
+      result
+      message
+    }
+  }
+`;
+export function createCustomerNotificationRecipientsModule(transport) {
+    return {
+        async list(customerId, options) {
+            const { value: customer, mark } = await customerDataField(transport, NOTIFICATION_RECIPIENTS_QUERY, 'customer', { id: customerId }, options);
+            return (customer?.notificationRecipients ?? []).map(mark);
+        },
+        async create(input, options) {
+            const { value, mark } = await customerDataField(transport, CREATE_NOTIFICATION_RECIPIENT_MUTATION, 'createCustomerNotificationRecipient', {
+                input: {
+                    customerId: input.customerId,
+                    email: input.email,
+                    label: input.label,
+                    events: input.events,
+                    enabled: input.enabled,
+                    replaceCustomerEmail: input.replaceCustomerEmail,
+                },
+            }, options);
+            return mark(value);
+        },
+        async update(id, input, options) {
+            const { value, mark } = await customerDataField(transport, UPDATE_NOTIFICATION_RECIPIENT_MUTATION, 'updateCustomerNotificationRecipient', {
+                // `label: null` clears it and is sent; everything left out stays off the wire, and kept.
+                input: {
+                    id,
+                    email: input.email,
+                    label: input.label,
+                    events: input.events,
+                    enabled: input.enabled,
+                    replaceCustomerEmail: input.replaceCustomerEmail,
+                },
+            }, options);
+            return mark(value);
+        },
+        async delete(id, options) {
+            assertDeleted('CUSTOMER_NOTIFICATION_RECIPIENT_NOT_DELETED', [
+                await fieldOf(transport, DELETE_NOTIFICATION_RECIPIENT_MUTATION, 'deleteCustomerNotificationRecipient', { id }, options),
+            ]);
+        },
+    };
+}

package/dist/customers/saved-lists.d.ts

@@ -0,0 +1,42 @@
+/**
+ * A customer's saved lists (headless W10-15, spec §9.2 `customers`): the named lists of products
+ * and quantities a shopper keeps on the storefront to order again. Read-only here: the shopper
+ * writes them through the Shop API, and the back office reads them on the customer's page.
+ */
+import { type Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+export interface CustomerSavedListItem {
+    id: string;
+    productVariantId: string;
+    quantity: number;
+    /** The shopper's order of the items, lowest first; the items are answered in it. */
+    position: number;
+    /**
+     * The variant as the store holds it now, or `null` when it no longer does. A variant of a
+     * DISABLED product is still answered here: the Shop API hides it from the shopper's own list
+     * (multi-region decision 87), the back office still sees what the list holds.
+     */
+    productVariant: {
+        id: string;
+        name: string;
+        sku: string;
+    } | null;
+}
+export interface CustomerSavedList {
+    id: string;
+    /** What the shopper called the list: customer data, withheld below `customerData: full`. */
+    name: string;
+    createdAt: string;
+    updatedAt: string;
+    items: CustomerSavedListItem[];
+    /** Set when the caller's customer-data level withheld the name (an app below `full`). */
+    redacted?: true;
+}
+/**
+ * The customer's own read (`customer(id) { id }`) beside the lists: the lists' door answers `[]`
+ * for an id the store does not hold, and only the customer read tells a customer with no lists
+ * apart from a customer the store does not hold.
+ */
+export declare const CUSTOMER_SAVED_LISTS_QUERY = "\n  query CustomerSavedLists($customerId: ID!) {\n    customer(id: $customerId) {\n      id\n    }\n    savedListsForCustomer(customerId: $customerId) {\n      id\n      name\n      createdAt\n      updatedAt\n      items {\n        id\n        productVariantId\n        quantity\n        position\n        productVariant {\n          id\n          name\n          sku\n        }\n      }\n    }\n  }\n";
+/** `customers.savedLists`: see `CustomersModule.savedLists`. */
+export declare function readCustomerSavedLists(transport: Transport, customerId: string, options: Call | undefined): Promise<CustomerSavedList[] | null>;

package/dist/customers/saved-lists.js

@@ -0,0 +1,61 @@
+/**
+ * A customer's saved lists (headless W10-15, spec §9.2 `customers`): the named lists of products
+ * and quantities a shopper keeps on the storefront to order again. Read-only here: the shopper
+ * writes them through the Shop API, and the back office reads them on the customer's page.
+ */
+import { UpstreamError } from '@sixtyninecommerce/core';
+import { redactionWatcher } from '../customer-data-redaction.js';
+/**
+ * The customer's own read (`customer(id) { id }`) beside the lists: the lists' door answers `[]`
+ * for an id the store does not hold, and only the customer read tells a customer with no lists
+ * apart from a customer the store does not hold.
+ */
+export const CUSTOMER_SAVED_LISTS_QUERY = /* GraphQL */ `
+  query CustomerSavedLists($customerId: ID!) {
+    customer(id: $customerId) {
+      id
+    }
+    savedListsForCustomer(customerId: $customerId) {
+      id
+      name
+      createdAt
+      updatedAt
+      items {
+        id
+        productVariantId
+        quantity
+        position
+        productVariant {
+          id
+          name
+          sku
+        }
+      }
+    }
+  }
+`;
+/** `customers.savedLists`: see `CustomersModule.savedLists`. */
+export async function readCustomerSavedLists(transport, customerId, options) {
+    const redaction = redactionWatcher();
+    const data = await transport.graphql({
+        api: 'admin',
+        query: CUSTOMER_SAVED_LISTS_QUERY,
+        variables: { customerId },
+        onExtensions: redaction.onExtensions,
+    }, options);
+    if (data === null || typeof data !== 'object' || !Array.isArray(data.savedListsForCustomer)) {
+        throw new UpstreamError({
+            code: 'UNEXPECTED_RESPONSE',
+            message: 'The engine answered without "savedListsForCustomer".',
+            status: 502,
+            service: 'vendure',
+        });
+    }
+    if (!data.customer)
+        return null;
+    return data.savedListsForCustomer.map((list) => redaction.mark({
+        ...list,
+        // The engine keeps no order on the items; the shopper's is `position`, then the id.
+        items: [...list.items].sort((a, b) => a.position - b.position || a.id.localeCompare(b.id)),
+    }));
+}

package/dist/customers/vat.d.ts

@@ -0,0 +1,83 @@
+/**
+ * A customer's VAT number, checked against the EU's VIES service (headless spec §9.2
+ * `customers` "VAT validation"; W10-33). The stored number and its standing verdict are on
+ * `customers.get(id, { include: ['customFields'] })`.
+ */
+import type { Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/**
+ * How long {@link CustomerVatModule.validate} waits for the engine, which asks VIES up to three
+ * times (a 5 s limit each, with a pause between) before it answers.
+ */
+export declare const VAT_VALIDATION_TIMEOUT_MS = 25000;
+/**
+ * What a check of a VAT number found. Only `valid` and `invalid` say something about the
+ * number:
+ *
+ * - `valid`: VIES confirmed the number is registered.
+ * - `invalid`: VIES confirmed it is not, or the number failed a check before VIES was asked
+ *   (too short, no EU member state's prefix); `error` then says which.
+ * - `pending`: VIES could not be reached or kept failing. The number was not checked: try
+ *   again later.
+ * - `error`: VIES refused the lookup for a reason that will not pass by itself (`error`
+ *   carries it). The number was not checked.
+ * - `none`: no verdict (never answered by a check).
+ */
+export type VatValidationStatus = 'valid' | 'invalid' | 'pending' | 'error' | 'none';
+export interface CustomerVatValidation {
+    status: VatValidationStatus | (string & {});
+    /** The number as checked, normalised (upper case, no spaces). */
+    vatNumber: string;
+    /**
+     * The country the number's two-letter prefix names (Greece's `EL` reads `GR`), whether or not
+     * it is an EU member state; "" for a number too short to have one.
+     */
+    countryCode: string;
+    /** The registered name VIES answered, when it shares one. */
+    companyName: string | null;
+    /** The registered address VIES answered, when it shares one. */
+    companyAddress: string | null;
+    /** ISO-8601 with offset; when VIES confirmed the number. */
+    validatedAt: string | null;
+    /** Why the number is `invalid`, or what stopped the check. */
+    error: string | null;
+    /**
+     * Set when the caller's customer-data level blanked the number, the name and the address (an
+     * app installation below `full`): "" or null then means "not granted".
+     */
+    redacted?: true;
+}
+export interface CustomerVatModule {
+    /**
+     * Check a VAT number with the EU's VIES service and store it on the customer with the
+     * verdict. Needs `UpdateCustomer`.
+     *
+     * **The verdict is `status`, never an error.** A number VIES does not know resolves
+     * `invalid`; a VIES that cannot be reached resolves `pending`, and one that refuses the lookup
+     * `error`, neither of which says anything about the number. The number and the verdict are
+     * stored either way, with one exception: `pending` or `error` for the number the customer
+     * already has as `valid` changes nothing, so an outage never downgrades a checked number.
+     *
+     * The call can take up to {@link VAT_VALIDATION_TIMEOUT_MS} (it waits that long instead of
+     * the client's own limit); pass `signal` to give up earlier.
+     *
+     * While an app or API token owns Customer details on the store, a number that differs from
+     * the stored one is refused `FIELD_GROUP_LOCKED` (`BusinessRuleError`); checking the stored
+     * number again passes. A customer this store does not hold is a `NotFoundError`
+     * (`ENTITY_NOT_FOUND`).
+     *
+     * @effect write
+     */
+    validate(customerId: string, vatNumber: string, options?: Call): Promise<CustomerVatValidation>;
+    /**
+     * Remove the customer's VAT number and its verdict. Needs `UpdateCustomer`. Refused
+     * `FIELD_GROUP_LOCKED` like {@link validate} while the customer has a number; a customer this
+     * store does not hold is a `NotFoundError` (`ENTITY_NOT_FOUND`).
+     *
+     * @effect write
+     */
+    clear(customerId: string, options?: Call): Promise<void>;
+}
+export declare const VALIDATE_VAT_MUTATION = "\n  mutation ValidateCustomerVatNumber($customerId: ID!, $vatNumber: String!) {\n    validateCustomerVatNumber(customerId: $customerId, vatNumber: $vatNumber) {\n      status\n      vatNumber\n      countryCode\n      companyName\n      companyAddress\n      validatedAt\n      error\n    }\n  }\n";
+export declare const CLEAR_VAT_MUTATION = "\n  mutation ClearCustomerVatNumber($customerId: ID!) {\n    clearCustomerVatNumber(customerId: $customerId)\n  }\n";
+export declare function createCustomerVatModule(transport: Transport): CustomerVatModule;

package/dist/customers/vat.js

@@ -0,0 +1,46 @@
+import { fieldOf } from '../catalog/types.js';
+import { customerDataField } from './wire.js';
+/**
+ * How long {@link CustomerVatModule.validate} waits for the engine, which asks VIES up to three
+ * times (a 5 s limit each, with a pause between) before it answers.
+ */
+export const VAT_VALIDATION_TIMEOUT_MS = 25_000;
+export const VALIDATE_VAT_MUTATION = /* GraphQL */ `
+  mutation ValidateCustomerVatNumber($customerId: ID!, $vatNumber: String!) {
+    validateCustomerVatNumber(customerId: $customerId, vatNumber: $vatNumber) {
+      status
+      vatNumber
+      countryCode
+      companyName
+      companyAddress
+      validatedAt
+      error
+    }
+  }
+`;
+export const CLEAR_VAT_MUTATION = /* GraphQL */ `
+  mutation ClearCustomerVatNumber($customerId: ID!) {
+    clearCustomerVatNumber(customerId: $customerId)
+  }
+`;
+export function createCustomerVatModule(transport) {
+    return {
+        async validate(customerId, vatNumber, options) {
+            const { value, mark } = await customerDataField(transport, VALIDATE_VAT_MUTATION, 'validateCustomerVatNumber', { customerId, vatNumber }, 
+            // The method's own limit: the transport's default would give up before VIES answers.
+            { ...options, timeoutMs: VAT_VALIDATION_TIMEOUT_MS });
+            return mark({
+                status: value.status,
+                vatNumber: value.vatNumber,
+                countryCode: value.countryCode,
+                companyName: value.companyName ?? null,
+                companyAddress: value.companyAddress ?? null,
+                validatedAt: value.validatedAt ?? null,
+                error: value.error ?? null,
+            });
+        },
+        async clear(customerId, options) {
+            await fieldOf(transport, CLEAR_VAT_MUTATION, 'clearCustomerVatNumber', { customerId }, options);
+        },
+    };
+}

package/dist/customers/wire.d.ts

@@ -0,0 +1,20 @@
+import { type CallOptions, type Transport } from '@sixtyninecommerce/core';
+import { redactionWatcher } from '../customer-data-redaction.js';
+/**
+ * One Admin API document's single root field, with the call's customer-data watcher: `mark`
+ * stamps `redacted: true` on a record of the answer when the caller's level blanked anything in
+ * it (an app installation below `customerData: full`). An absent field is refused, as
+ * `fieldOf` refuses it; a null one is a real answer.
+ */
+export declare function customerDataField<T>(transport: Transport, document: string, field: string, variables: Record<string, unknown>, options: CallOptions | undefined): Promise<{
+    value: T;
+    mark: ReturnType<typeof redactionWatcher>['mark'];
+}>;
+/** The company flags of one address, as a list row carries them. */
+export interface CustomerAddressSummary {
+    company: string | null;
+    defaultBillingAddress: boolean | null;
+    defaultShippingAddress: boolean | null;
+}
+/** The company a list shows for a customer, by the dashboard's own rule (`customerCompanyOf`). */
+export declare function companyOf(addresses: readonly CustomerAddressSummary[]): string | null;

package/dist/customers/wire.js

@@ -0,0 +1,35 @@
+import { UpstreamError } from '@sixtyninecommerce/core';
+import { redactionWatcher } from '../customer-data-redaction.js';
+/**
+ * One Admin API document's single root field, with the call's customer-data watcher: `mark`
+ * stamps `redacted: true` on a record of the answer when the caller's level blanked anything in
+ * it (an app installation below `customerData: full`). An absent field is refused, as
+ * `fieldOf` refuses it; a null one is a real answer.
+ */
+export async function customerDataField(transport, document, field, variables, options) {
+    const redaction = redactionWatcher();
+    const data = await transport.graphql({ api: 'admin', query: document, variables, onExtensions: redaction.onExtensions }, options);
+    if (data === null || typeof data !== 'object' || !Object.hasOwn(data, field)) {
+        throw new UpstreamError({
+            code: 'UNEXPECTED_RESPONSE',
+            message: `The engine answered without "${field}".`,
+            status: 502,
+            service: 'vendure',
+        });
+    }
+    return { value: data[field], mark: redaction.mark };
+}
+/** The company a list shows for a customer, by the dashboard's own rule (`customerCompanyOf`). */
+export function companyOf(addresses) {
+    const candidates = [
+        addresses.find((address) => address.defaultBillingAddress === true),
+        addresses.find((address) => address.defaultShippingAddress === true),
+        ...addresses,
+    ];
+    for (const address of candidates) {
+        const company = address?.company?.trim();
+        if (company)
+            return company;
+    }
+    return null;
+}