@sixtyninecommerce/admin 0.10.0 → 0.12.0

package/dist/tenant/email-templates.d.ts

@@ -0,0 +1,287 @@
+import { type Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+import { type EmailStylePatch } from './email-style.js';
+/** One template rendered as the store would send it, filled from the store's own records. */
+export interface EmailPreview {
+    subject: string;
+    /** The whole HTML document, ready for an `<iframe srcdoc>`. */
+    html: string;
+    /** Each recipient field resolved for the sample, as one comma-separated list ('' for none). */
+    recipients: {
+        to: string;
+        cc: string;
+        bcc: string;
+    };
+    /**
+     * `true` when the credential's customer-data level withheld part of the answer (an app
+     * installation below `customerData: full`): `subject` and `html` then read `''`, and so do the
+     * recipients below `identity`. Absent otherwise.
+     */
+    redacted?: true;
+}
+export interface EmailPreviewOptions extends Call {
+    /** The language to render the template's texts and subject in, e.g. `nl`. */
+    languageCode: string;
+    /**
+     * Style fields to preview instead of the stored ones, e.g. a form's unsaved values. Nothing is
+     * saved. A value `tenant.emailStyle.set` would refuse is not refused here: the renderer draws it
+     * with its own fallback.
+     */
+    style?: EmailStylePatch;
+}
+/**
+ * One part of a subject line or of a block's text: literal text (`{ type: 'text', value }`), or a
+ * variable the email fills in when it is sent (`{ type: 'var', key }`, a key from the template
+ * type's `variables` in {@link EmailTemplateCatalog}). A variable key the type does not offer is
+ * printed as `[key]`.
+ */
+export interface EmailTokenSegment {
+    type: 'text' | 'var';
+    /** The text of a `text` part. */
+    value?: string;
+    /** The variable of a `var` part. */
+    key?: string;
+}
+/** A block's texts in one language. */
+export interface EmailTemplateBlockContent {
+    languageCode: string;
+    /**
+     * One entry per text of the block, keyed by the block type's field names (most hold
+     * {@link EmailTokenSegment} lists). The renderer falls back to the block's defaults for a
+     * missing entry.
+     */
+    content: Record<string, unknown>;
+}
+/** One block (the engine calls them chips) of a template's body, e.g. a heading or the order lines. */
+export interface EmailTemplateBlock {
+    id: string;
+    /** The block type: one of the catalog's `blockTypes`. */
+    type: string;
+    /** Its place in the body: the blocks are answered in this order. */
+    position: number;
+    /** The block's switches and settings (e.g. `{ showImage: true }`), the same in every language. */
+    config: Record<string, unknown>;
+    /** Its texts, one entry per language the store wrote them in. */
+    contents: EmailTemplateBlockContent[];
+}
+/** A template's subject line in one language. */
+export interface EmailTemplateSubject {
+    languageCode: string;
+    segments: EmailTokenSegment[];
+}
+/** The template of one type, as the store sends it now. */
+export interface EmailTemplate {
+    /**
+     * The template's id. It changes when the store starts or stops taking `settings.email` from its
+     * organization, so the methods here address a template by its `type`; keep the id only to tell
+     * that the template a page shows was replaced.
+     */
+    id: string;
+    type: string;
+    enabled: boolean;
+    /** Who it is sent to, as recipient variables and fixed addresses. */
+    recipients: {
+        to: EmailTokenSegment[];
+        cc: EmailTokenSegment[];
+        bcc: EmailTokenSegment[];
+    };
+    /** The body, in `position` order. */
+    blocks: EmailTemplateBlock[];
+    subjects: EmailTemplateSubject[];
+}
+export interface EmailTemplateVariable {
+    key: string;
+    label: string;
+}
+export interface EmailTemplateTypeInfo {
+    type: string;
+    label: string;
+    description: string;
+    /** The variables a subject or block text of this type may use. */
+    variables: EmailTemplateVariable[];
+}
+export interface EmailBlockTypeInfo {
+    type: string;
+    label: string;
+    /** A grouping for a picker: `structural`, `content`, `commerce_data`, `action`, `cms_data`, … */
+    category: string;
+}
+/** What the template editor can offer: the same for every store. */
+export interface EmailTemplateCatalog {
+    templateTypes: EmailTemplateTypeInfo[];
+    blockTypes: EmailBlockTypeInfo[];
+    /** The variables a recipient field may use. */
+    recipientVariables: EmailTemplateVariable[];
+}
+export interface AddEmailTemplateBlockInput {
+    /** The block type: one of the catalog's `blockTypes`. */
+    type: string;
+    /**
+     * Where to put it: `0` is first, and the blocks at that place and after it move down one. At the
+     * end when omitted.
+     */
+    position?: number;
+    /** Its switches and settings; `{}` when omitted. */
+    config?: Record<string, unknown>;
+}
+/**
+ * The template writes, by template type or by block id. Every one is refused while the store takes
+ * `settings.email` from its organization (see {@link EmailTemplatesModule}).
+ *
+ * **Coded refusals shared by every write:**
+ * - `ORGANIZATION_SETTINGS_INHERITED` → `BusinessRuleError` (422): the store inherits
+ *   `settings.email`; `tenant.settingsSources.override('settings.email')` first.
+ * - `MANAGED_BY_ORGANIZATION` → `BusinessRuleError` (422): the organization locks it.
+ * - `FORBIDDEN` → `PermissionDeniedError` (403): the credential lacks `UpdateSettings`.
+ */
+export interface EmailTemplateBlocksModule {
+    /**
+     * Add a block to the template of `templateType`, and answer it (with no `contents`: a new block
+     * has no texts until `setContent`). Two requests: the template the store uses is looked up
+     * first.
+     *
+     * **Coded refusals:** `EMAIL_TEMPLATE_NOT_FOUND` → `NotFoundError` (404), no template of the
+     * type; `EMAIL_CHIP_TYPE_INVALID` → `ValidationError` (400), a block type outside the catalog;
+     * `EMAIL_CHIP_CONFIG_INVALID` (400), a `config` that is not an object; `ENTITY_NOT_FOUND` →
+     * `NotFoundError` (404), the template was replaced between the two requests (ask again).
+     *
+     * @effect write
+     * @permission UpdateSettings
+     */
+    add(templateType: string, block: AddEmailTemplateBlockInput, options?: Call): Promise<EmailTemplateBlock>;
+    /**
+     * Replace a block's `config` as a whole (send every key it keeps), and answer the block without
+     * its `contents` (`getByType` reads them).
+     *
+     * **Coded refusals:** `EMAIL_CHIP_CONFIG_INVALID` → `ValidationError` (400), a config that is not
+     * an object; `ENTITY_NOT_FOUND` → `NotFoundError` (404), no block of the store's with that id.
+     *
+     * @effect write
+     * @permission UpdateSettings
+     */
+    update(blockId: string, patch: {
+        config: Record<string, unknown>;
+    }, options?: Call): Promise<Omit<EmailTemplateBlock, 'contents'>>;
+    /**
+     * Delete a block with its texts in every language. The blocks after it move up one. There is
+     * no undo: a block added back starts from its defaults.
+     *
+     * **Coded refusal:** `ENTITY_NOT_FOUND` → `NotFoundError` (404), no block of the store's with
+     * that id.
+     *
+     * @effect destructive
+     * @permission UpdateSettings
+     */
+    remove(blockId: string, options?: Call): Promise<void>;
+    /**
+     * Put the blocks of the template of `templateType` in a new order: `blockIds` lists EVERY block
+     * of the template once, first to last. Two requests: the template is looked up first.
+     *
+     * **Coded refusals:** `EMAIL_CHIP_ORDER_INVALID` → `ValidationError` (400), a block left out,
+     * listed twice, or not one of the template's (the message names it); `EMAIL_TEMPLATE_NOT_FOUND`
+     * → `NotFoundError` (404), no template of the type; `ENTITY_NOT_FOUND` (404), the template was
+     * replaced between the two requests.
+     *
+     * @effect write
+     * @permission UpdateSettings
+     */
+    reorder(templateType: string, blockIds: readonly string[], options?: Call): Promise<void>;
+    /**
+     * Set a block's texts in one language, replacing what it had in that language (the other
+     * languages keep theirs). Answers what is stored.
+     *
+     * **Coded refusals:** `EMAIL_CHIP_CONTENT_INVALID` → `ValidationError` (400), content that is
+     * not an object; `EMAIL_LANGUAGE_CODE_INVALID` (400), a language code that is none (`en`, `nl`,
+     * `pt_BR`, …); `ENTITY_NOT_FOUND` → `NotFoundError` (404), no block of the store's with that id.
+     *
+     * @effect write
+     * @permission UpdateSettings
+     */
+    setContent(blockId: string, languageCode: string, content: Record<string, unknown>, options?: Call): Promise<EmailTemplateBlockContent>;
+}
+/**
+ * `admin.tenant.emailTemplates` — the active store's email templates (part of the `settings.email`
+ * group). Always the ACTIVE channel; no channel argument.
+ *
+ * Templates are addressed by TYPE (`order_confirmation`, `shipping_confirmation`, …): a template's
+ * id changes when the store starts or stops taking `settings.email` from its organization, its
+ * type never does. While the store inherits, every read answers the organization's template, and
+ * every write (`setSubject`, `blocks.*`) is refused (`ORGANIZATION_SETTINGS_INHERITED` or
+ * `MANAGED_BY_ORGANIZATION`, 422).
+ *
+ * A change applies to the next email of its type the store sends; an email already sent keeps
+ * what it said.
+ */
+export interface EmailTemplatesModule {
+    /**
+     * What the editor can offer: each template type with its label, description and variables, the
+     * block types, and the recipient variables. The same for every store.
+     *
+     * @effect read
+     * @permission ReadSettings
+     */
+    catalog(options?: Call): Promise<EmailTemplateCatalog>;
+    /**
+     * The template of `type` the store sends, with its blocks (in order) and subjects, or `null`
+     * for a type the engine does not know.
+     *
+     * For a store on its own settings, the first read of a known type the store has no template
+     * of yet creates it from the platform's default.
+     *
+     * @effect read
+     * @permission ReadSettings
+     */
+    getByType(type: string, options?: Call): Promise<EmailTemplate | null>;
+    /**
+     * Set the subject of the template of `templateType` in one language, replacing what it had in
+     * that language. Two requests: the template the store uses is looked up first. Answers what is
+     * stored.
+     *
+     * **Coded refusals:** `EMAIL_SUBJECT_INVALID` → `ValidationError` (400), a part that is neither
+     * text with its `value` nor a variable with its `key` (the message names it);
+     * `EMAIL_LANGUAGE_CODE_INVALID` (400), a language code that is none; `EMAIL_TEMPLATE_NOT_FOUND`
+     * → `NotFoundError` (404), no template of the type; `ENTITY_NOT_FOUND` (404), the template was
+     * replaced between the two requests. And those of {@link EmailTemplateBlocksModule}.
+     *
+     * @effect write
+     * @permission UpdateSettings
+     */
+    setSubject(templateType: string, languageCode: string, segments: readonly EmailTokenSegment[], options?: Call): Promise<EmailTemplateSubject>;
+    /** The blocks of a template's body. */
+    blocks: EmailTemplateBlocksModule;
+    /**
+     * Render the template of `type` as the store would send it now, optionally with unsaved style
+     * changes. Two requests: the template the store uses for `type` is looked up first.
+     *
+     * **The answer is customer data.** The sample is filled from the store's LATEST REAL order and
+     * customer (synthetic values only in a store with none), so `subject`, `html` and the
+     * recipients carry a real buyer's name, email and addresses. Do not log or forward them; a
+     * credential below `customerData: full` gets them withheld ({@link EmailPreview.redacted}).
+     *
+     * For a store on its own settings, the first look-up of a known type the store has no template
+     * of yet creates it from the platform's default (as the dashboard's editor does).
+     *
+     * **Coded refusals:**
+     * - `EMAIL_TEMPLATE_NOT_FOUND` → `NotFoundError` (404): no template of `type` (an unknown type).
+     * - `ENTITY_NOT_FOUND` → `NotFoundError` (404): the template changed between the two requests
+     *   (the store's `settings.email` source moved); ask again.
+     * - `FORBIDDEN` → `PermissionDeniedError` (403): the credential lacks `ReadSettings`.
+     *
+     * @effect read
+     * @permission ReadSettings
+     */
+    preview(type: string, options: EmailPreviewOptions): Promise<EmailPreview>;
+}
+export declare const EMAIL_TEMPLATE_CATALOG_QUERY = "\n  query EmailTemplateCatalog {\n    emailTemplateCatalog {\n      templateTypes { type label description variables { key label } }\n      chipTypes { type label category }\n      recipientVariables { key label }\n    }\n  }\n";
+export declare const EMAIL_TEMPLATE_BY_TYPE_QUERY = "\n  query EmailTemplateByType($type: String!) {\n    emailTemplateByType(type: $type) {\n      id\n      type\n      enabled\n      recipientTo { type value key }\n      recipientCc { type value key }\n      recipientBcc { type value key }\n      chips { id type position config translations { languageCode content } }\n      subjects { languageCode subject { type value key } }\n    }\n  }\n";
+export declare const EMAIL_TEMPLATE_ID_BY_TYPE_QUERY = "\n  query EmailTemplateIdByType($type: String!) {\n    emailTemplateByType(type: $type) { id }\n  }\n";
+/** The look-up `blocks.add` makes: the id, and where the body ends. */
+export declare const EMAIL_TEMPLATE_END_BY_TYPE_QUERY = "\n  query EmailTemplateEndByType($type: String!) {\n    emailTemplateByType(type: $type) { id chips { position } }\n  }\n";
+export declare const ADD_EMAIL_TEMPLATE_BLOCK_MUTATION = "\n  mutation AddEmailTemplateBlock($templateId: ID!, $input: AddChipInput!) {\n    addEmailTemplateChip(templateId: $templateId, input: $input) { id type position config }\n  }\n";
+export declare const UPDATE_EMAIL_TEMPLATE_BLOCK_MUTATION = "\n  mutation UpdateEmailTemplateBlock($chipId: ID!, $input: UpdateChipInput!) {\n    updateEmailTemplateChip(chipId: $chipId, input: $input) { id type position config }\n  }\n";
+export declare const REMOVE_EMAIL_TEMPLATE_BLOCK_MUTATION = "\n  mutation RemoveEmailTemplateBlock($chipId: ID!) {\n    removeEmailTemplateChip(chipId: $chipId)\n  }\n";
+export declare const REORDER_EMAIL_TEMPLATE_BLOCKS_MUTATION = "\n  mutation ReorderEmailTemplateBlocks($templateId: ID!, $input: ReorderChipsInput!) {\n    reorderEmailTemplateChips(templateId: $templateId, input: $input)\n  }\n";
+export declare const SET_EMAIL_TEMPLATE_BLOCK_CONTENT_MUTATION = "\n  mutation SetEmailTemplateBlockContent($chipId: ID!, $input: UpsertChipTranslationInput!) {\n    upsertEmailChipTranslation(chipId: $chipId, input: $input) { languageCode content }\n  }\n";
+export declare const SET_EMAIL_TEMPLATE_SUBJECT_MUTATION = "\n  mutation SetEmailTemplateSubject($templateId: ID!, $input: UpsertSubjectInput!) {\n    upsertEmailTemplateSubject(templateId: $templateId, input: $input) {\n      languageCode\n      subject { type value key }\n    }\n  }\n";
+export declare const EMAIL_PREVIEW_QUERY = "\n  query EmailPreview(\n    $templateId: ID!\n    $languageCode: String!\n    $styleOverrides: UpdateEmailStyleConfigInput\n  ) {\n    renderEmailPreview(\n      templateId: $templateId\n      languageCode: $languageCode\n      styleOverrides: $styleOverrides\n    ) {\n      subject\n      html\n      recipientTo\n      recipientCc\n      recipientBcc\n    }\n  }\n";
+export declare function createEmailTemplatesModule(transport: Transport): EmailTemplatesModule;

package/dist/tenant/email-templates.js

@@ -0,0 +1,271 @@
+import { NotFoundError } from '@sixtyninecommerce/core';
+import { customerDataField } from '../customers/wire.js';
+import { emailStyleInputOf } from './email-style.js';
+const SEGMENT_FIELDS = 'type value key';
+const BLOCK_FIELDS = `id type position config translations { languageCode content }`;
+/**
+ * A block as the two block WRITES answer it: no `translations`. An engine before 2026-10-15 saves
+ * the chip and only then fails to answer that (non-null) relation, so a write selecting it would
+ * report a failure for a change that was stored, and a retry would add the block twice.
+ */
+const WRITTEN_BLOCK_FIELDS = 'id type position config';
+export const EMAIL_TEMPLATE_CATALOG_QUERY = /* GraphQL */ `
+  query EmailTemplateCatalog {
+    emailTemplateCatalog {
+      templateTypes { type label description variables { key label } }
+      chipTypes { type label category }
+      recipientVariables { key label }
+    }
+  }
+`;
+export const EMAIL_TEMPLATE_BY_TYPE_QUERY = /* GraphQL */ `
+  query EmailTemplateByType($type: String!) {
+    emailTemplateByType(type: $type) {
+      id
+      type
+      enabled
+      recipientTo { ${SEGMENT_FIELDS} }
+      recipientCc { ${SEGMENT_FIELDS} }
+      recipientBcc { ${SEGMENT_FIELDS} }
+      chips { ${BLOCK_FIELDS} }
+      subjects { languageCode subject { ${SEGMENT_FIELDS} } }
+    }
+  }
+`;
+export const EMAIL_TEMPLATE_ID_BY_TYPE_QUERY = /* GraphQL */ `
+  query EmailTemplateIdByType($type: String!) {
+    emailTemplateByType(type: $type) { id }
+  }
+`;
+/** The look-up `blocks.add` makes: the id, and where the body ends. */
+export const EMAIL_TEMPLATE_END_BY_TYPE_QUERY = /* GraphQL */ `
+  query EmailTemplateEndByType($type: String!) {
+    emailTemplateByType(type: $type) { id chips { position } }
+  }
+`;
+export const ADD_EMAIL_TEMPLATE_BLOCK_MUTATION = /* GraphQL */ `
+  mutation AddEmailTemplateBlock($templateId: ID!, $input: AddChipInput!) {
+    addEmailTemplateChip(templateId: $templateId, input: $input) { ${WRITTEN_BLOCK_FIELDS} }
+  }
+`;
+export const UPDATE_EMAIL_TEMPLATE_BLOCK_MUTATION = /* GraphQL */ `
+  mutation UpdateEmailTemplateBlock($chipId: ID!, $input: UpdateChipInput!) {
+    updateEmailTemplateChip(chipId: $chipId, input: $input) { ${WRITTEN_BLOCK_FIELDS} }
+  }
+`;
+export const REMOVE_EMAIL_TEMPLATE_BLOCK_MUTATION = /* GraphQL */ `
+  mutation RemoveEmailTemplateBlock($chipId: ID!) {
+    removeEmailTemplateChip(chipId: $chipId)
+  }
+`;
+export const REORDER_EMAIL_TEMPLATE_BLOCKS_MUTATION = /* GraphQL */ `
+  mutation ReorderEmailTemplateBlocks($templateId: ID!, $input: ReorderChipsInput!) {
+    reorderEmailTemplateChips(templateId: $templateId, input: $input)
+  }
+`;
+export const SET_EMAIL_TEMPLATE_BLOCK_CONTENT_MUTATION = /* GraphQL */ `
+  mutation SetEmailTemplateBlockContent($chipId: ID!, $input: UpsertChipTranslationInput!) {
+    upsertEmailChipTranslation(chipId: $chipId, input: $input) { languageCode content }
+  }
+`;
+export const SET_EMAIL_TEMPLATE_SUBJECT_MUTATION = /* GraphQL */ `
+  mutation SetEmailTemplateSubject($templateId: ID!, $input: UpsertSubjectInput!) {
+    upsertEmailTemplateSubject(templateId: $templateId, input: $input) {
+      languageCode
+      subject { ${SEGMENT_FIELDS} }
+    }
+  }
+`;
+export const EMAIL_PREVIEW_QUERY = /* GraphQL */ `
+  query EmailPreview(
+    $templateId: ID!
+    $languageCode: String!
+    $styleOverrides: UpdateEmailStyleConfigInput
+  ) {
+    renderEmailPreview(
+      templateId: $templateId
+      languageCode: $languageCode
+      styleOverrides: $styleOverrides
+    ) {
+      subject
+      html
+      recipientTo
+      recipientCc
+      recipientBcc
+    }
+  }
+`;
+/** A part as stored, without the null of the field the other kind uses. */
+function segmentOf(wire) {
+    const segment = { type: wire.type };
+    if (wire.value != null)
+        segment.value = wire.value;
+    if (wire.key != null)
+        segment.key = wire.key;
+    return segment;
+}
+/** A part as the engine takes it: only the fields the caller set. */
+function segmentInputOf(segment) {
+    const input = { type: segment.type };
+    if (segment.value !== undefined)
+        input.value = segment.value;
+    if (segment.key !== undefined)
+        input.key = segment.key;
+    return input;
+}
+function contentOf(wire) {
+    return { languageCode: wire.languageCode, content: wire.content ?? {} };
+}
+function writtenBlockOf(wire) {
+    return {
+        id: String(wire.id),
+        type: wire.type,
+        position: wire.position,
+        config: wire.config ?? {},
+    };
+}
+function blockOf(wire) {
+    return { ...writtenBlockOf(wire), contents: (wire.translations ?? []).map(contentOf) };
+}
+function templateOf(wire) {
+    return {
+        id: String(wire.id),
+        type: wire.type,
+        enabled: wire.enabled,
+        recipients: {
+            to: wire.recipientTo.map(segmentOf),
+            cc: wire.recipientCc.map(segmentOf),
+            bcc: wire.recipientBcc.map(segmentOf),
+        },
+        // The engine orders them on its own rows; the inherited read builds them in code. Sorted
+        // here so the promise holds either way.
+        blocks: wire.chips.map(blockOf).sort((a, b) => a.position - b.position),
+        subjects: wire.subjects.map((row) => ({
+            languageCode: row.languageCode,
+            segments: row.subject.map(segmentOf),
+        })),
+    };
+}
+function templateNotFound(type) {
+    return new NotFoundError({
+        code: 'EMAIL_TEMPLATE_NOT_FOUND',
+        message: `The store has no email template of type "${type}".`,
+        status: 404,
+        service: 'vendure',
+    });
+}
+export function createEmailTemplatesModule(transport) {
+    /** The id of the template of `type` the store uses, or the coded not-found. */
+    const templateIdOf = async (type, call) => {
+        const found = await transport.graphql({ api: 'admin', query: EMAIL_TEMPLATE_ID_BY_TYPE_QUERY, variables: { type } }, call);
+        const templateId = found.emailTemplateByType?.id;
+        if (!templateId)
+            throw templateNotFound(type);
+        return String(templateId);
+    };
+    const blocks = {
+        async add(templateType, block, options) {
+            let templateId;
+            let position = block.position;
+            if (position === undefined) {
+                // "At the end" is after the LAST position, not the count: positions may have gaps.
+                const found = await transport.graphql({
+                    api: 'admin',
+                    query: EMAIL_TEMPLATE_END_BY_TYPE_QUERY,
+                    variables: { type: templateType },
+                }, options);
+                if (!found.emailTemplateByType)
+                    throw templateNotFound(templateType);
+                templateId = String(found.emailTemplateByType.id);
+                position = found.emailTemplateByType.chips.reduce((end, chip) => Math.max(end, chip.position + 1), 0);
+            }
+            else {
+                templateId = await templateIdOf(templateType, options);
+            }
+            const data = await transport.graphql({
+                api: 'admin',
+                query: ADD_EMAIL_TEMPLATE_BLOCK_MUTATION,
+                variables: {
+                    templateId,
+                    input: {
+                        type: block.type,
+                        position,
+                        ...(block.config !== undefined ? { config: block.config } : {}),
+                    },
+                },
+            }, options);
+            // The engine writes no texts for a new block (`addChip`), so it has none to answer.
+            return { ...writtenBlockOf(data.addEmailTemplateChip), contents: [] };
+        },
+        async update(blockId, patch, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: UPDATE_EMAIL_TEMPLATE_BLOCK_MUTATION,
+                variables: { chipId: blockId, input: { config: patch.config } },
+            }, options);
+            return writtenBlockOf(data.updateEmailTemplateChip);
+        },
+        async remove(blockId, options) {
+            await transport.graphql({
+                api: 'admin',
+                query: REMOVE_EMAIL_TEMPLATE_BLOCK_MUTATION,
+                variables: { chipId: blockId },
+            }, options);
+        },
+        async reorder(templateType, blockIds, options) {
+            const templateId = await templateIdOf(templateType, options);
+            await transport.graphql({
+                api: 'admin',
+                query: REORDER_EMAIL_TEMPLATE_BLOCKS_MUTATION,
+                variables: { templateId, input: { chipIds: [...blockIds] } },
+            }, options);
+        },
+        async setContent(blockId, languageCode, content, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: SET_EMAIL_TEMPLATE_BLOCK_CONTENT_MUTATION,
+                variables: { chipId: blockId, input: { languageCode, content } },
+            }, options);
+            return contentOf(data.upsertEmailChipTranslation);
+        },
+    };
+    return {
+        async catalog(options) {
+            const data = await transport.graphql({ api: 'admin', query: EMAIL_TEMPLATE_CATALOG_QUERY }, options);
+            const { templateTypes, chipTypes, recipientVariables } = data.emailTemplateCatalog;
+            return { templateTypes, blockTypes: chipTypes, recipientVariables };
+        },
+        async getByType(type, options) {
+            const data = await transport.graphql({ api: 'admin', query: EMAIL_TEMPLATE_BY_TYPE_QUERY, variables: { type } }, options);
+            return data.emailTemplateByType ? templateOf(data.emailTemplateByType) : null;
+        },
+        async setSubject(templateType, languageCode, segments, options) {
+            const templateId = await templateIdOf(templateType, options);
+            const data = await transport.graphql({
+                api: 'admin',
+                query: SET_EMAIL_TEMPLATE_SUBJECT_MUTATION,
+                variables: {
+                    templateId,
+                    input: { languageCode, subject: segments.map(segmentInputOf) },
+                },
+            }, options);
+            const saved = data.upsertEmailTemplateSubject;
+            return { languageCode: saved.languageCode, segments: saved.subject.map(segmentOf) };
+        },
+        blocks,
+        async preview(type, options) {
+            const { languageCode, style, ...call } = options;
+            const templateId = await templateIdOf(type, call);
+            const { value, mark } = await customerDataField(transport, EMAIL_PREVIEW_QUERY, 'renderEmailPreview', {
+                templateId,
+                languageCode,
+                ...(style !== undefined ? { styleOverrides: emailStyleInputOf(style) } : {}),
+            }, call);
+            return mark({
+                subject: value.subject,
+                html: value.html,
+                recipients: { to: value.recipientTo, cc: value.recipientCc, bcc: value.recipientBcc },
+            });
+        },
+    };
+}

package/dist/tenant/notifications.d.ts

@@ -38,8 +38,8 @@ export interface NotificationEventConfig {
     event: string;
     /**
      * `false` switches the email off altogether; nothing is logged for it. Always
-     * `true` for `password_reset`, `email_change` and `account_setup`, which
-     * cannot be switched off.
+     * `true` for `password_reset`, `email_change`, `account_setup` and
+     * `gift_card_issued`, which cannot be switched off.
      */
     enabled: boolean;
     sender: NotificationSender;
@@ -60,20 +60,23 @@ export interface NotificationEventConfig {
 export interface UpdateNotificationEventConfigInput {
     /**
      * `false` is refused with `EVENT_ALWAYS_ENABLED` ({@link ValidationError}) on
-     * `password_reset`, `email_change` and `account_setup`: each is the only way
-     * a customer resets a password (or sets the first one on an imported
-     * account), confirms a new address, or finishes a storefront registration,
-     * so they are always sent. `magic_link_login` and `customer_invite` can be
-     * switched off.
+     * `password_reset`, `email_change`, `account_setup` and `gift_card_issued`:
+     * each is the only way a customer resets a password (or sets the first one
+     * on an imported account), confirms a new address, finishes a storefront
+     * registration, or receives the code of a gift card they paid for (the
+     * platform keeps only its hash), so they are always sent. `magic_link_login`
+     * and `customer_invite` can be switched off.
      */
     enabled?: boolean;
     /**
      * `none` is refused on the identity emails — the `account` category:
      * password reset, magic link, invitation, email change, email and chat
-     * verification — with `EVENT_ALWAYS_PLATFORM_SENT` ({@link ValidationError}).
-     * Each carries a one-time credential only the platform can issue, and no
-     * platform event carries one, so there is no event your system could send it
-     * from. What you control there is where its link lands (your head's URL).
+     * verification — and on `gift_card_issued`, with `EVENT_ALWAYS_PLATFORM_SENT`
+     * ({@link ValidationError}). Each carries a one-time credential, or a gift
+     * card's code, only the platform can issue, and no platform event carries
+     * one (`stored_value.gift_card.issued` names the card, never its code), so
+     * there is no event your system could send it from. What you control there
+     * is where its link lands (your head's URL).
      *
      * `none` is also refused on an email whose `replacementEventTypes` is `null`,
      * with `NO_REPLACEMENT_EVENT` ({@link ValidationError}): no platform event is
@@ -87,6 +90,8 @@ export interface UpdateNotificationEventConfigInput {
      * links or codes, and one login serves the person in every store, so they go to
      * the account holder alone: `to` is the `customer_email` variable, `cc` and
      * `bcc` are empty, and `list` answers exactly that whatever was stored before.
+     * So does `gift_card_issued`: whoever holds a copy of its code can spend the
+     * card, so it goes to the buyer alone.
      * Any other list on them is refused with `IDENTITY_EMAIL_RECIPIENTS_FIXED`
      * ({@link ValidationError}); resending the lists `list` answered is accepted.
      */
@@ -119,18 +124,19 @@ export interface UpdateNotificationEventConfigInput {
  *
  * **Coded refusals**, GraphQL errors mapped by `core`:
  * - `EVENT_ALWAYS_PLATFORM_SENT` → {@link ValidationError}: `sender: 'none'` on
- *   an identity email. The message names the event; `details[0].field` is
- *   `/sender`.
+ *   an identity email or `gift_card_issued`. The message names the event;
+ *   `details[0].field` is `/sender`.
  * - `EVENT_ALWAYS_ENABLED` → {@link ValidationError}: `enabled: false` on
- *   `password_reset`, `email_change` or `account_setup`. The message names the
- *   event and why it cannot be switched off; `details[0].field` is `/enabled`.
+ *   `password_reset`, `email_change`, `account_setup` or `gift_card_issued`.
+ *   The message names the event and why it cannot be switched off;
+ *   `details[0].field` is `/enabled`.
  * - `NO_REPLACEMENT_EVENT` → {@link ValidationError}: `sender: 'none'` on an
  *   email no emitted platform event replaces (`replacementEventTypes: null`).
  *   The message names the event, and the event planned to replace it when one
  *   is; `details[0].field` is `/sender`.
  * - `IDENTITY_EMAIL_RECIPIENTS_FIXED` → {@link ValidationError}: a recipient
- *   list on an identity email (or `new_customer`) that names anyone but the
- *   account holder. `details[].field` names each offending list
+ *   list on an identity email (or `new_customer`, or `gift_card_issued`) that
+ *   names anyone but the account holder. `details[].field` names each offending list
  *   (`/recipientTo`, `/recipientCc`, `/recipientBcc`).
  * - `INVALID_NOTIFICATION_SENDER` → {@link ValidationError}.
  * - `NOTIFICATION_EVENT_NOT_FOUND` → {@link NotFoundError}: no such event key.

package/dist/tenant/settings-sources.d.ts

@@ -97,7 +97,7 @@ export interface SettingsSourcesModule {
     assets(group: SettingsGroup | (string & {}), call?: Call): Promise<AssetFile[]>;
 }
 export declare const CHANNEL_SETTINGS_SOURCES_QUERY = "\n  query ChannelSettingsSources {\n    channelSettingsSources { \n  group\n  source\n  locked\n  overridden\n  inheritable\n  organizationName\n  values\n }\n  }\n";
-export declare const CHANNEL_SETTINGS_ASSETS_QUERY = "\n  query ChannelSettingsAssets($group: String!) {\n    channelSettingsAssets(group: $group) { \n  id\n  createdAt\n  updatedAt\n  name\n  type\n  mimeType\n  fileSize\n  width\n  height\n  source\n  preview\n  focalPoint {\n    x\n    y\n  }\n  tags {\n    value\n  }\n }\n  }\n";
+export declare const CHANNEL_SETTINGS_ASSETS_QUERY = "\n  query ChannelSettingsAssets($group: String!) {\n    channelSettingsAssets(group: $group) { \n  id\n  createdAt\n  updatedAt\n  name\n  type\n  mimeType\n  fileSize\n  width\n  height\n  source\n  preview\n  focalPoint {\n    x\n    y\n  }\n  tags {\n    value\n  }\n  customFields {\n    altText\n  }\n }\n  }\n";
 export declare const OVERRIDE_ORGANIZATION_SETTINGS_MUTATION = "\n  mutation OverrideOrganizationSettings($group: String!) {\n    overrideOrganizationSettings(group: $group) { \n  group\n  source\n  locked\n  overridden\n  inheritable\n  organizationName\n  values\n }\n  }\n";
 export declare const INHERIT_ORGANIZATION_SETTINGS_MUTATION = "\n  mutation InheritOrganizationSettings($group: String!) {\n    inheritOrganizationSettings(group: $group) { \n  group\n  source\n  locked\n  overridden\n  inheritable\n  organizationName\n  values\n }\n  }\n";
 export declare function createSettingsSourcesModule(transport: Transport): SettingsSourcesModule;

package/dist/tenant/time-zone.d.ts

@@ -0,0 +1,17 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/**
+ * `admin.tenant.timeZone(call?)`: the ACTIVE store's IANA time zone (`Europe/Amsterdam`,
+ * `America/New_York`, …) as the engine resolves it: the store's own setting, or
+ * `Europe/Amsterdam` when it has none or an invalid one. It is the zone the API counts calendar
+ * days in (a requested delivery day, "shipped today", an invoice date), so render dates and
+ * "today" in it, never in the browser's or the server's own zone, and never re-check the
+ * setting yourself: the engine owns the rule.
+ *
+ * Any signed-in caller of the store may read it. No channel argument: the tenant is the store.
+ *
+ * @effect read
+ */
+export type TenantTimeZoneReader = (call?: Call) => Promise<string>;
+export declare const STORE_TIME_ZONE_QUERY = "\n  query StoreTimeZone {\n    storeTimeZone\n  }\n";
+export declare function createTenantTimeZoneReader(transport: Transport): TenantTimeZoneReader;