@sixtyninecommerce/admin 0.10.0 → 0.12.0

package/dist/documents/emails.d.ts

@@ -0,0 +1,150 @@
+/**
+ * `admin.documents.emails` — the store's email delivery log, its counts, a retry of one delivery,
+ * and a test send of a template (headless spec §9.2 `documents`, "email sends"; W10-103).
+ *
+ * Every call needs `UpdateSettings` on the active store. A delivery's recipients, subject, error
+ * and metadata are customer data: below `customerData: full` (an app installation) they read
+ * `''`/`null` and the row carries `redacted: true`.
+ */
+import { type Page, type Transport } from '@sixtyninecommerce/core';
+import type { Call, ListOptions } from '../types.js';
+/**
+ * Where a delivery stands. `skipped`: the store's `sender: none` for the event (the platform sent
+ * nothing, on purpose). `suppressed_sandbox`: a sandbox store withheld the customer's copy. The
+ * engine may add others; a reader keeps a default branch.
+ */
+export type EmailDeliveryStatus = 'sent' | 'failed' | 'blocked' | 'pending' | 'skipped' | 'suppressed_sandbox' | (string & {});
+/** One email the store sent, or tried to. */
+export interface EmailDelivery {
+    id: string;
+    /** The template it was rendered from (`order_confirmation`, …). */
+    templateType: string;
+    /** The notification event that sent it (`order_placed`, …). */
+    notificationEvent: string;
+    /** Comma-separated addresses. */
+    recipientTo: string;
+    recipientCc: string | null;
+    recipientBcc: string | null;
+    subject: string;
+    gatewayId: string | null;
+    status: EmailDeliveryStatus;
+    /** 1 for the first send; each retry adds one. */
+    attempt: number;
+    /** The mail provider's message id, when it took the email. */
+    messageId: string | null;
+    /** Why the last attempt failed, as the provider or the mail server said it. */
+    error: string | null;
+    durationMs: number | null;
+    /** The ids the email was rendered from (`orderId`, `invoiceId`, …) and other send facts. */
+    metadata: Record<string, unknown> | null;
+    /** ISO-8601 UTC. */
+    createdAt: string;
+    /**
+     * Set when the caller's customer-data level withheld part of the row (an app installation
+     * below `customerData: full`): the recipients, subject, error and metadata then read `''` or
+     * `null`, meaning "not granted", never "none on record".
+     */
+    redacted?: true;
+}
+/**
+ * Which deliveries a list or a count covers. The two instants need an explicit offset (`Z` or
+ * `±HH:mm`) and are refused before the request leaves without one (`INVALID_DATETIME`): a store's
+ * day is not the caller's. To cover the store's days, send the first instant of the first day as
+ * `createdFrom` and the first instant of the day AFTER the last one as `createdBefore`
+ * ({@link EmailDeliveriesModule.list}).
+ */
+export interface EmailDeliveryFilter {
+    status?: EmailDeliveryStatus;
+    templateType?: string;
+    /** Created at or after this instant. */
+    createdFrom?: string;
+    /** Created strictly before this instant. */
+    createdBefore?: string;
+}
+/** How many of the store's deliveries are in each state, over a filter. */
+export interface EmailDeliveryStats {
+    sent: number;
+    failed: number;
+    /** Never sent: every recipient is on the mail provider's suppression list. */
+    blocked: number;
+    pending: number;
+}
+export interface SendTestEmailInput {
+    /** A template type the platform renders (`admin.tenant.emailTemplates.catalog()`). */
+    templateType: string;
+    /** One email address. */
+    recipientEmail: string;
+}
+export interface EmailDeliveriesModule {
+    /**
+     * The store's deliveries, newest first, one page at a time (`limit` 1–100, 50 when omitted).
+     *
+     * **Store days.** The page that shows "from 24 to 25 October" in Europe/Amsterdam sends
+     * `createdFrom: '2026-10-24T00:00:00+02:00'` and `createdBefore: '2026-10-26T00:00:00+01:00'`:
+     * 25 October 2026 is 25 hours long there (the clocks go back), and the end is exclusive, so
+     * the whole last day is in and nothing of the next.
+     *
+     * **Coded refusals:** `INVALID_DATETIME` → `ValidationError` (400), an instant without an
+     * offset, before the request leaves; `EMAIL_DELIVERY_FILTER_INVALID` → `ValidationError`
+     * (400), a `limit` outside 1–100 or a range that ends before it starts.
+     *
+     * Rows carry `redacted: true` below `customerData: full` (see {@link EmailDelivery}).
+     *
+     * @effect read
+     * @permission UpdateSettings
+     */
+    list(filter?: EmailDeliveryFilter, options?: ListOptions): Promise<Page<EmailDelivery>>;
+    /**
+     * How many deliveries are `sent`, `failed`, `blocked` and `pending`, over the same filter as
+     * {@link list} without its `status` (a count by status). Without a filter: the store's whole
+     * log. On an engine from before this release (no filter argument) a filtered count is made
+     * from the list's totals, one read per status.
+     *
+     * @effect read
+     * @permission UpdateSettings
+     */
+    stats(filter?: Omit<EmailDeliveryFilter, 'status'>, options?: Call): Promise<EmailDeliveryStats>;
+    /**
+     * Send a `failed` or `blocked` delivery again, now, and answer the row with the new outcome:
+     * `status` is `sent`, `failed` again (with its `error`), `blocked` (the address is still on the
+     * provider's suppression list) or `suppressed_sandbox`. It resolves either way; read `status`.
+     * Synchronous: the email has been handed to the provider (or not) when it resolves.
+     *
+     * This sends the email to the CUSTOMER (or whoever it was addressed to) once more. Never call
+     * it in a loop or on a timer without a person deciding to.
+     *
+     * **Coded refusals** (nothing is sent): `EMAIL_DELIVERY_NOT_FOUND` → `NotFoundError` (404), no
+     * such delivery in this store; `EMAIL_DELIVERY_NOT_RETRYABLE` → `BusinessRuleError` (422), the
+     * delivery is not `failed` or `blocked`, it is a gift card's email (its code is not kept), or
+     * another retry of it started first.
+     *
+     * @effect irreversible
+     * @permission UpdateSettings
+     */
+    retry(id: string, options?: Call): Promise<EmailDelivery>;
+}
+export interface DocumentEmailsModule {
+    deliveries: EmailDeliveriesModule;
+    /**
+     * Render `templateType` with sample data and send it, now, through the store's own email
+     * gateway, to `recipientEmail`. It is real mail. The send writes no delivery row.
+     *
+     * **Coded refusals:** `INVALID_TEST_EMAIL_RECIPIENT` and `INVALID_TEST_EMAIL_TEMPLATE` →
+     * `ValidationError` (400), before anything is sent; `TEST_EMAIL_SEND_FAILED` →
+     * `BusinessRuleError` (422), the gateway did not take it (the message names the SMTP step or
+     * the provider's code, never the server's own words).
+     *
+     * @effect irreversible
+     * @permission UpdateSettings
+     */
+    sendTest(input: SendTestEmailInput, options?: Call): Promise<void>;
+}
+export declare const EMAIL_DELIVERIES_QUERY = "\n  query AdminEmailDeliveries($options: EmailDeliveryLogListOptions) {\n    emailDeliveryLogs(options: $options) {\n      items { \n  id\n  templateType\n  notificationEvent\n  recipientTo\n  recipientCc\n  recipientBcc\n  subject\n  gatewayId\n  status\n  attempt\n  messageId\n  error\n  durationMs\n  metadata\n  createdAt\n }\n      totalItems\n    }\n  }\n";
+export declare const EMAIL_DELIVERY_STATS_QUERY = "\n  query AdminEmailDeliveryStats($options: EmailDeliveryStatsOptions) {\n    emailDeliveryStats(options: $options) {\n      sent\n      failed\n      blocked\n      pending\n    }\n  }\n";
+/** The store's whole log, without the filter argument an older engine does not know. */
+export declare const EMAIL_DELIVERY_STATS_ALL_QUERY = "\n  query AdminEmailDeliveryStatsAll {\n    emailDeliveryStats {\n      sent\n      failed\n      blocked\n      pending\n    }\n  }\n";
+/** How many deliveries match: the older engine's way to count over a filter. */
+export declare const EMAIL_DELIVERY_COUNT_QUERY = "\n  query AdminEmailDeliveryCount($options: EmailDeliveryLogListOptions) {\n    emailDeliveryLogs(options: $options) {\n      totalItems\n    }\n  }\n";
+export declare const RETRY_EMAIL_DELIVERY_MUTATION = "\n  mutation AdminRetryEmailDelivery($id: ID!) {\n    retryEmailDelivery(id: $id) { \n  id\n  templateType\n  notificationEvent\n  recipientTo\n  recipientCc\n  recipientBcc\n  subject\n  gatewayId\n  status\n  attempt\n  messageId\n  error\n  durationMs\n  metadata\n  createdAt\n }\n  }\n";
+export declare const SEND_TEST_EMAIL_MUTATION = "\n  mutation AdminSendTestEmail($templateType: String!, $recipientEmail: String!) {\n    sendTestEmail(templateType: $templateType, recipientEmail: $recipientEmail)\n  }\n";
+export declare function createDocumentEmailsModule(transport: Transport): DocumentEmailsModule;

package/dist/documents/emails.js

@@ -0,0 +1,220 @@
+/**
+ * `admin.documents.emails` — the store's email delivery log, its counts, a retry of one delivery,
+ * and a test send of a template (headless spec §9.2 `documents`, "email sends"; W10-103).
+ *
+ * Every call needs `UpdateSettings` on the active store. A delivery's recipients, subject, error
+ * and metadata are customer data: below `customerData: full` (an app installation) they read
+ * `''`/`null` and the row carries `redacted: true`.
+ */
+import { pageFromVendureList, readOffsetCursor, ValidationError, } from '@sixtyninecommerce/core';
+import { assertInstant } from '../catalog/types.js';
+import { customerDataField } from '../customers/wire.js';
+const DELIVERY_FIELDS = /* GraphQL */ `
+  id
+  templateType
+  notificationEvent
+  recipientTo
+  recipientCc
+  recipientBcc
+  subject
+  gatewayId
+  status
+  attempt
+  messageId
+  error
+  durationMs
+  metadata
+  createdAt
+`;
+export const EMAIL_DELIVERIES_QUERY = /* GraphQL */ `
+  query AdminEmailDeliveries($options: EmailDeliveryLogListOptions) {
+    emailDeliveryLogs(options: $options) {
+      items { ${DELIVERY_FIELDS} }
+      totalItems
+    }
+  }
+`;
+export const EMAIL_DELIVERY_STATS_QUERY = /* GraphQL */ `
+  query AdminEmailDeliveryStats($options: EmailDeliveryStatsOptions) {
+    emailDeliveryStats(options: $options) {
+      sent
+      failed
+      blocked
+      pending
+    }
+  }
+`;
+/** The store's whole log, without the filter argument an older engine does not know. */
+export const EMAIL_DELIVERY_STATS_ALL_QUERY = /* GraphQL */ `
+  query AdminEmailDeliveryStatsAll {
+    emailDeliveryStats {
+      sent
+      failed
+      blocked
+      pending
+    }
+  }
+`;
+/** How many deliveries match: the older engine's way to count over a filter. */
+export const EMAIL_DELIVERY_COUNT_QUERY = /* GraphQL */ `
+  query AdminEmailDeliveryCount($options: EmailDeliveryLogListOptions) {
+    emailDeliveryLogs(options: $options) {
+      totalItems
+    }
+  }
+`;
+export const RETRY_EMAIL_DELIVERY_MUTATION = /* GraphQL */ `
+  mutation AdminRetryEmailDelivery($id: ID!) {
+    retryEmailDelivery(id: $id) { ${DELIVERY_FIELDS} }
+  }
+`;
+export const SEND_TEST_EMAIL_MUTATION = /* GraphQL */ `
+  mutation AdminSendTestEmail($templateType: String!, $recipientEmail: String!) {
+    sendTestEmail(templateType: $templateType, recipientEmail: $recipientEmail)
+  }
+`;
+/** The engine's default page; the SDK states it so the cursor arithmetic knows the size. */
+const DELIVERIES_PAGE_SIZE = 50;
+function toDelivery(row) {
+    return {
+        id: String(row.id),
+        templateType: row.templateType,
+        notificationEvent: row.notificationEvent,
+        recipientTo: row.recipientTo,
+        recipientCc: row.recipientCc ?? null,
+        recipientBcc: row.recipientBcc ?? null,
+        subject: row.subject,
+        gatewayId: row.gatewayId ?? null,
+        status: row.status,
+        attempt: row.attempt,
+        messageId: row.messageId ?? null,
+        error: row.error ?? null,
+        durationMs: row.durationMs ?? null,
+        metadata: row.metadata ?? null,
+        createdAt: row.createdAt,
+    };
+}
+/** The engine's filter input: only the keys the caller set, so an older engine still answers. */
+function wireFilter(filter) {
+    if (filter === undefined)
+        return {};
+    if (filter === null || typeof filter !== 'object' || Array.isArray(filter)) {
+        throw new ValidationError({
+            code: 'EMAIL_DELIVERY_FILTER_INVALID',
+            message: 'The delivery filter must be an object.',
+            status: 400,
+            service: 'vendure',
+        });
+    }
+    assertInstant('createdFrom', filter.createdFrom);
+    assertInstant('createdBefore', filter.createdBefore);
+    return {
+        ...(filter.status ? { status: filter.status } : {}),
+        ...(filter.templateType ? { templateType: filter.templateType } : {}),
+        ...(filter.createdFrom ? { dateFrom: filter.createdFrom } : {}),
+        ...(filter.createdBefore ? { dateBefore: filter.createdBefore } : {}),
+    };
+}
+/**
+ * The engine refused the document over a field or argument it does not know: an engine from
+ * before this release (no `dateBefore`, no `emailDeliveryStats(options:)`). The dashboard can be
+ * live before vendure-server (`.claude/rules/backend.md`, additive rule), so the module falls
+ * back to the older spelling instead of failing. Matched on the names this module added, so a
+ * real refusal is never retried.
+ */
+function isOlderEngineRejection(error) {
+    if (!(error instanceof ValidationError) || error.service !== 'vendure')
+        return false;
+    // Apollo answers a document that fails validation (an unknown type or argument: the stats
+    // filter) with HTTP 400, which the transport reports as BAD_REQUEST without the engine's
+    // words; an unknown input field (dateBefore) is a variable coercion error at HTTP 200 and
+    // keeps them. Only ever asked about the documents this module added the names to.
+    return (error.code === 'BAD_REQUEST' ||
+        error.code === 'GRAPHQL_VALIDATION_FAILED' ||
+        /dateBefore|EmailDeliveryStatsOptions|Unknown argument "options"/.test(error.message));
+}
+/** The old inclusive spelling of an exclusive end: one millisecond before it. */
+function legacyFilter(filter) {
+    const { dateBefore, ...rest } = filter;
+    if (typeof dateBefore !== 'string')
+        return rest;
+    return { ...rest, dateTo: new Date(Date.parse(dateBefore) - 1).toISOString() };
+}
+const COUNTED_STATUSES = ['sent', 'failed', 'blocked', 'pending'];
+export function createDocumentEmailsModule(transport) {
+    /** Latched once the engine proved it predates `dateBefore` (one refused request per client). */
+    let olderEngine = false;
+    const listPage = async (skip, take, filter, options) => {
+        const read = (wire) => customerDataField(transport, EMAIL_DELIVERIES_QUERY, 'emailDeliveryLogs', { options: { ...wire, take, skip } }, options);
+        let answer;
+        if (olderEngine || !('dateBefore' in filter)) {
+            answer = await read(olderEngine ? legacyFilter(filter) : filter);
+        }
+        else {
+            try {
+                answer = await read(filter);
+            }
+            catch (error) {
+                if (!isOlderEngineRejection(error))
+                    throw error;
+                olderEngine = true;
+                answer = await read(legacyFilter(filter));
+            }
+        }
+        const { value, mark } = answer;
+        const items = value.items.map((row) => mark(toDelivery(row)));
+        // Each following page re-sends the same filter and per-call options.
+        return pageFromVendureList({ items, totalItems: value.totalItems }, skip, take, (cursor) => listPage(readOffsetCursor(cursor), take, filter, options));
+    };
+    return {
+        deliveries: {
+            async list(filter, options) {
+                const wire = wireFilter(filter);
+                const take = options?.limit ?? DELIVERIES_PAGE_SIZE;
+                const skip = options?.after === undefined ? 0 : readOffsetCursor(options.after);
+                return listPage(skip, take, wire, options);
+            },
+            async stats(filter, options) {
+                const { status: _status, ...counted } = wireFilter(filter);
+                if (Object.keys(counted).length === 0) {
+                    const data = await transport.graphql({ api: 'admin', query: EMAIL_DELIVERY_STATS_ALL_QUERY }, options);
+                    return data.emailDeliveryStats;
+                }
+                if (!olderEngine) {
+                    try {
+                        const data = await transport.graphql({ api: 'admin', query: EMAIL_DELIVERY_STATS_QUERY, variables: { options: counted } }, options);
+                        return data.emailDeliveryStats;
+                    }
+                    catch (error) {
+                        if (!isOlderEngineRejection(error))
+                            throw error;
+                        olderEngine = true;
+                    }
+                }
+                // An older engine counts only the whole log: count each status over the filter through
+                // the list's totals instead (one row read per status).
+                const totals = await Promise.all(COUNTED_STATUSES.map(async (status) => {
+                    const data = await transport.graphql({
+                        api: 'admin',
+                        query: EMAIL_DELIVERY_COUNT_QUERY,
+                        variables: { options: { ...legacyFilter(counted), status, take: 1, skip: 0 } },
+                    }, options);
+                    return data.emailDeliveryLogs.totalItems;
+                }));
+                const [sent = 0, failed = 0, blocked = 0, pending = 0] = totals;
+                return { sent, failed, blocked, pending };
+            },
+            async retry(id, options) {
+                const { value, mark } = await customerDataField(transport, RETRY_EMAIL_DELIVERY_MUTATION, 'retryEmailDelivery', { id }, options);
+                return mark(toDelivery(value));
+            },
+        },
+        async sendTest(input, options) {
+            await transport.graphql({
+                api: 'admin',
+                query: SEND_TEST_EMAIL_MUTATION,
+                variables: { templateType: input.templateType, recipientEmail: input.recipientEmail },
+            }, options);
+        },
+    };
+}