@endora-commerce/contracts 0.100.0

package/dist/text-normalization.js

@@ -0,0 +1,205 @@
+/**
+ * One diacritic fold — and, since issue #245, one slug generator — for every
+ * package that has to compare or key two spellings of the same word.
+ *
+ * `foldDiacritics` is the fold (issue #240). `slugify` is the generator built
+ * on it, and it replaced **eight** private copies; its own doc block carries
+ * the reasons that are specific to slugs. Everything below is about the fold.
+ *
+ * ## Why this file exists rather than a helper inside one consumer
+ *
+ * The fold was correct and unreachable. It lived inside
+ * `normalizeOrganizationName` in `organizations.ts` — published from
+ * `@endora-commerce/contracts`, so importable from `backend/`, `admin/` and `storefront/`
+ * alike, but named after **one caller**. Nobody looking for "how do I compare
+ * `Łatwy` with `latwy`" searches for an organisation helper, so within a year
+ * four private copies had grown in `admin/` (repaired by !745) and two more
+ * stand in `backend/` today. Every one of them was the same one-liner and every
+ * one of them shipped the same bug.
+ *
+ * ## The bug the one-liner has
+ *
+ * ```
+ * input.normalize('NFD').replace(/\p{Diacritic}/gu, '').toLowerCase()
+ * ```
+ *
+ * reads as complete and is not. `ł` is U+0142: a single indivisible code point
+ * with **no canonical decomposition**, so NFD leaves it exactly where it was,
+ * the strip finds no combining mark to remove, and the `[^a-z0-9]+` pass a
+ * slugifier runs next deletes the letter outright — `Łatwy szablon` becomes
+ * `atwy-szablon`. The same holds for `Ø ø Đ đ Ð ð Þ þ ß Æ æ Œ œ`. The fix is one
+ * extra step, and it is the only reason this is longer than a line: map those
+ * letters explicitly.
+ *
+ * ## A function, not a port
+ *
+ * It is pure over its argument, so it cannot answer differently depending on
+ * which modules are switched on, and a gated port answering 503 `MODULE_DISABLED`
+ * to "fold these diacritics" would be a bug rather than a safety property.
+ * Node natives only (Principle IV) — a full Unicode-folding library is not worth
+ * a dependency for fifteen letters.
+ */
+/**
+ * Latin letters NFD does not decompose, and their ASCII approximations.
+ *
+ * Every entry is a **single code point** whose Unicode decomposition is empty:
+ * a stroked, hooked or ligated letter rather than a base plus a combining mark.
+ * That is precisely the set NFD cannot help with, which is why it is hand-written.
+ *
+ * Exported so a test can enumerate it and a reader can see the whole set at
+ * once — not as an invitation to write a second fold around it. Reach for
+ * `foldDiacritics` instead; a copy of the map without the decomposition step
+ * is half a fold, and half a fold is what this file exists to end.
+ */
+export const NON_DECOMPOSING_LATIN = {
+    Ł: 'L',
+    ł: 'l',
+    Ø: 'O',
+    ø: 'o',
+    Đ: 'D',
+    đ: 'd',
+    Ð: 'D',
+    ð: 'd',
+    Þ: 'Th',
+    þ: 'th',
+    ß: 'ss',
+    Æ: 'AE',
+    æ: 'ae',
+    Œ: 'OE',
+    œ: 'oe',
+};
+/**
+ * Fold a string so two spellings of the same word compare equal: diacritics
+ * removed, non-decomposing Latin letters mapped to ASCII, lowercased.
+ *
+ * In order:
+ *
+ * 1. **Decompose (NFD)** — separate every base character from its combining
+ *    marks, so `ó` becomes `o` + U+0301.
+ * 2. **Strip the combining marks** via `\p{Diacritic}`.
+ * 3. **Map what NFD could not decompose**, per `NON_DECOMPOSING_LATIN`. This
+ *    step runs **after** the decomposition on purpose: `Ǿ` (U+01FE) decomposes
+ *    to `Ø` + U+0301, so a map applied first would not see the `Ø` that step 1
+ *    is about to expose. Mapping first — as `admin/`'s copy did until issue
+ *    #240 — folds `Ǿ` to `ø` instead of `o`.
+ * 4. **Lowercase.** Callers compare case-insensitively without exception, and
+ *    the ASCII expansions above (`Th`, `AE`, `OE`) have to be lowered anyway.
+ *
+ * Whitespace is deliberately **not** touched: what counts as one space is the
+ * caller's policy, not the fold's. `normalizeOrganizationName` collapses runs
+ * and trims because it writes a search column; `admin`'s `normalize` only
+ * trims. Both compose it here rather than each folding its own way.
+ *
+ * Not a case-folding routine in the Unicode sense: it lowercases, it does not
+ * apply full case folding, and anything outside Latin (Cyrillic, CJK, Greek)
+ * passes through with its case lowered and nothing else changed.
+ */
+export function foldDiacritics(input) {
+    const stripped = input.normalize('NFD').replace(/\p{Diacritic}/gu, '');
+    let mapped = '';
+    for (const character of stripped) {
+        mapped += NON_DECOMPOSING_LATIN[character] ?? character;
+    }
+    return mapped.toLowerCase();
+}
+/** Escape a separator so it can sit inside a character class. */
+function escapeForRegExp(literal) {
+    return literal.replace(/[.*+?^${}()|[\]\\-]/g, '\\$&');
+}
+/**
+ * The repository's one slug generator (issue #245).
+ *
+ * There were **eight**: three in `backend/`, five in `admin/`, each a private
+ * four-line chain that read as obviously right. Two of them
+ * (`cms-template-layout.ts`, `pim_ergonode`'s `slugFromSourceCode`) had no fold
+ * step at all — `Żółw` produced `w` and `Świeże Ćwikła` produced `wie-e-wik-a`
+ * — and `check:diacritic-folds` was structurally blind to both, because it
+ * counts folds written *outside* the shared helper and a site that folds
+ * nothing writes none. A shared generator is what makes "does this slug fold?"
+ * a question with one answer.
+ *
+ * The steps, in order:
+ *
+ * 1. **Fold** via `foldDiacritics` — decompose, strip the combining marks, map
+ *    the letters NFD leaves standing, lowercase.
+ * 2. **Collapse** every run of `[^a-z0-9]` — minus whatever `preserve` adds to
+ *    the usable set — to the separator.
+ * 3. **Strip a leading separator**, before the slice — a leading separator can
+ *    never survive, so it must not spend a character of the caller's budget.
+ * 4. **Slice** to `maxLength`, when the caller has one.
+ * 5. **Strip trailing separators**, after the slice — the cut can *create* one,
+ *    which is the whole point (see below).
+ * 6. **Fall back** when nothing survived.
+ *
+ * ## NFD, not NFKD, and that is a decision
+ *
+ * Three of the eight normalised with `NFKD`, which additionally maps the
+ * compatibility characters: `fi` to `fi`, `²` to `2`, the full-width forms to
+ * their ASCII. Those mappings reach a slug **only** through characters that map
+ * *into* `[a-z0-9]`, and none of them is typed into a product name, a feed
+ * template name or a CMS page title. Where one does appear it now collapses to
+ * the separator rather than to a letter, so the slug stays legal and merely
+ * loses a character nobody could see in it. Against that, `ł` was being deleted
+ * out of every Polish name those three touched. The trade was taken for the
+ * admin pair in !753 and holds identically here.
+ *
+ * It has one consequence worth naming: two inputs `NFKD` kept apart can now
+ * fold together (`Kabel²` and `Kabel³` both become `kabel`). Every caller whose
+ * slug is unique-constrained already allocates against the live table —
+ * `CatalogAdminService.allocateUniqueSlug`, `pim_ergonode`'s
+ * `createWithFreeSlug` — so the second one is suffixed rather than rejected,
+ * exactly as two products sharing a plain name already are.
+ *
+ * ## The trailing strip runs after the slice, which is a change for six sites
+ *
+ * Six of the eight stripped **both** edge separators before cutting to length,
+ * so a cut landing on a separator left the slug ending in one:
+ * `...w-wersji-rozszerzona-`. Only `BlockEditor` and `PageEditor` had it right.
+ * This is the one change here that is not about diacritics; it shows only on an
+ * input long enough to be truncated, and it makes the result satisfy the kebab
+ * grammar (`^[a-z0-9]+(?:-[a-z0-9]+)*$`) that `pim_ergonode`'s own doc block
+ * already claimed for it.
+ *
+ * The **leading** strip stays where all eight had it — before the slice — for a
+ * reason that is not symmetry: a leading separator is never part of the answer,
+ * so letting it consume a character of `maxLength` would shorten every slug
+ * whose input begins with punctuation by one, in six sites at once, for no
+ * gain. Only the trailing edge can be *created* by the cut, so only the
+ * trailing strip has to run after it.
+ *
+ * Historical values are **not** migrated (owner's ruling, 2026-08-19,
+ * originally for the admin pair in !753 and extended to the rest): only two
+ * developer environments exist, so re-slugging live rows buys nobody anything,
+ * and every one of these values is computed fresh at create time rather than
+ * re-derived to look an existing row up. New values are correct from here on.
+ *
+ * **`pim_ergonode` is the exception the ruling names, and it is the reason
+ * `preserve` exists.** Its two derivations are re-derived on every import run
+ * *to find the row a previous run created*, so a changed derivation orphans the
+ * row rather than improving it. Those values are migrated (issue #260), and the
+ * migration is only affordable because the derivation change is confined to the
+ * fold — which is what `preserve` buys.
+ *
+ * `normalizeOrganizationName` is **not** a caller and must not become one: it
+ * writes the persisted `organizations.name_search` column, which is a folded
+ * name rather than a slug.
+ */
+export function slugify(input, options = {}) {
+    const separator = options.separator ?? '-';
+    const escaped = escapeForRegExp(separator);
+    const usable = escapeForRegExp(options.preserve ?? '');
+    const folded = foldDiacritics(input);
+    // Two spellings of one step, and the branch is not a micro-optimisation. The
+    // default has to stay a **literal** `.replace(/[^a-z0-9]+/g, …)`, because
+    // that expression is what `check:diacritic-folds` reads to know this file is
+    // still the slug generator it exempts: its vacuous-pass guard cannot read a
+    // pattern built from a template, and a guard that cannot see the owner
+    // reports every private copy of it as fine (issue #244's whole point).
+    const collapsed = (usable.length === 0
+        ? folded.replace(/[^a-z0-9]+/g, separator)
+        : folded.replace(new RegExp(`[^a-z0-9${usable}]+`, 'g'), separator)).replace(new RegExp(`^(?:${escaped})+`), '');
+    const sliced = options.maxLength === undefined ? collapsed : collapsed.slice(0, options.maxLength);
+    const trimmed = sliced.replace(new RegExp(`(?:${escaped})+$`), '');
+    return trimmed.length > 0 ? trimmed : (options.fallback ?? '');
+}
+//# sourceMappingURL=text-normalization.js.map

package/dist/text-normalization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-normalization.js","sourceRoot":"","sources":["../src/text-normalization.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAqC;IACrE,CAAC,EAAE,GAAG;IACN,CAAC,EAAE,GAAG;IACN,CAAC,EAAE,GAAG;IACN,CAAC,EAAE,GAAG;IACN,CAAC,EAAE,GAAG;IACN,CAAC,EAAE,GAAG;IACN,CAAC,EAAE,GAAG;IACN,CAAC,EAAE,GAAG;IACN,CAAC,EAAE,IAAI;IACP,CAAC,EAAE,IAAI;IACP,CAAC,EAAE,IAAI;IACP,CAAC,EAAE,IAAI;IACP,CAAC,EAAE,IAAI;IACP,CAAC,EAAE,IAAI;IACP,CAAC,EAAE,IAAI;CACR,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,MAAM,QAAQ,GAAG,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,iBAAiB,EAAE,EAAE,CAAC,CAAC;IACvE,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,MAAM,SAAS,IAAI,QAAQ,EAAE,CAAC;QACjC,MAAM,IAAI,qBAAqB,CAAC,SAAS,CAAC,IAAI,SAAS,CAAC;IAC1D,CAAC;IACD,OAAO,MAAM,CAAC,WAAW,EAAE,CAAC;AAC9B,CAAC;AAyCD,iEAAiE;AACjE,SAAS,eAAe,CAAC,OAAe;IACtC,OAAO,OAAO,CAAC,OAAO,CAAC,sBAAsB,EAAE,MAAM,CAAC,CAAC;AACzD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6EG;AACH,MAAM,UAAU,OAAO,CAAC,KAAa,EAAE,UAA0B,EAAE;IACjE,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,GAAG,CAAC;IAC3C,MAAM,OAAO,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC;IAC3C,MAAM,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;IACvD,MAAM,MAAM,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IACrC,6EAA6E;IAC7E,0EAA0E;IAC1E,6EAA6E;IAC7E,4EAA4E;IAC5E,uEAAuE;IACvE,uEAAuE;IACvE,MAAM,SAAS,GAAG,CAChB,MAAM,CAAC,MAAM,KAAK,CAAC;QACjB,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,aAAa,EAAE,SAAS,CAAC;QAC1C,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,WAAW,MAAM,IAAI,EAAE,GAAG,CAAC,EAAE,SAAS,CAAC,CACtE,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,OAAO,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;IAC9C,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;IACnG,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,MAAM,OAAO,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;IACnE,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;AACjE,CAAC"}

package/dist/transactional-emails.d.ts

@@ -0,0 +1,459 @@
+import { z } from 'zod';
+/** Opaque Puck data tree for one language. */
+export declare const puckDataTreeSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export type PuckDataTreeDto = z.infer<typeof puckDataTreeSchema>;
+export declare const transactionalEmailCodeRe: RegExp;
+/** A variable an email declares for substitution + preview sample data. */
+export declare const emailVariableDescriptorSchema: z.ZodObject<{
+    key: z.ZodString;
+    label: z.ZodString;
+    sampleValue: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type EmailVariableDescriptor = z.infer<typeof emailVariableDescriptorSchema>;
+export declare const transactionalEmailManifestEntrySchema: z.ZodObject<{
+    code: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    group: z.ZodOptional<z.ZodString>;
+    variables: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        label: z.ZodString;
+        sampleValue: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type TransactionalEmailManifestEntry = z.infer<typeof transactionalEmailManifestEntrySchema>;
+/**
+ * Whether an operator may switch this one email off, and why not (issue #89).
+ *
+ * Deliberately the same pair of field names `ModulePresenceSchema` uses for the
+ * module axis: the two refusals are the same statement at two granularities,
+ * and an admin that renders one can render the other without learning a second
+ * vocabulary. The reason is the owning module's own sentence, carried from the
+ * `EmailDefaultsRegistry` — no frontend holds a list of protected codes.
+ */
+export declare const transactionalEmailProtectionSchema: z.ZodObject<{
+    deactivatable: z.ZodBoolean;
+    nonDeactivatableReason: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export declare const transactionalEmailSummarySchema: z.ZodObject<{
+    code: z.ZodString;
+    name: z.ZodString;
+    ownerModule: z.ZodString;
+    group: z.ZodNullable<z.ZodString>;
+    active: z.ZodBoolean;
+    languages: z.ZodArray<z.ZodString>;
+    hasGlobalOverride: z.ZodBoolean;
+    hasChannelOverride: z.ZodBoolean;
+    deactivatable: z.ZodBoolean;
+    nonDeactivatableReason: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type TransactionalEmailSummary = z.infer<typeof transactionalEmailSummarySchema>;
+export declare const transactionalEmailListResponseSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        name: z.ZodString;
+        ownerModule: z.ZodString;
+        group: z.ZodNullable<z.ZodString>;
+        active: z.ZodBoolean;
+        languages: z.ZodArray<z.ZodString>;
+        hasGlobalOverride: z.ZodBoolean;
+        hasChannelOverride: z.ZodBoolean;
+        deactivatable: z.ZodBoolean;
+        nonDeactivatableReason: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type TransactionalEmailListResponse = z.infer<typeof transactionalEmailListResponseSchema>;
+export declare const resolvedEmailContentSchema: z.ZodObject<{
+    subject: z.ZodString;
+    content: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    source: z.ZodEnum<{
+        default: "default";
+        channel: "channel";
+        global: "global";
+    }>;
+    version: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export type ResolvedEmailContent = z.infer<typeof resolvedEmailContentSchema>;
+export declare const transactionalEmailDetailSchema: z.ZodObject<{
+    code: z.ZodString;
+    name: z.ZodString;
+    ownerModule: z.ZodString;
+    group: z.ZodNullable<z.ZodString>;
+    description: z.ZodNullable<z.ZodString>;
+    active: z.ZodBoolean;
+    languages: z.ZodArray<z.ZodString>;
+    variables: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        label: z.ZodString;
+        sampleValue: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    scope: z.ZodObject<{
+        salesChannelId: z.ZodNullable<z.ZodString>;
+        language: z.ZodString;
+    }, z.core.$strip>;
+    effective: z.ZodObject<{
+        subject: z.ZodString;
+        content: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        source: z.ZodEnum<{
+            default: "default";
+            channel: "channel";
+            global: "global";
+        }>;
+        version: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>;
+    default: z.ZodObject<{
+        subject: z.ZodString;
+        content: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>;
+    hasGlobalOverride: z.ZodBoolean;
+    hasChannelOverride: z.ZodBoolean;
+    deactivatable: z.ZodBoolean;
+    nonDeactivatableReason: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type TransactionalEmailDetail = z.infer<typeof transactionalEmailDetailSchema>;
+export declare const transactionalEmailDetailQuerySchema: z.ZodObject<{
+    salesChannelId: z.ZodOptional<z.ZodString>;
+    language: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type TransactionalEmailDetailQuery = z.infer<typeof transactionalEmailDetailQuerySchema>;
+export declare const putEmailContentQuerySchema: z.ZodObject<{
+    salesChannelId: z.ZodOptional<z.ZodString>;
+    language: z.ZodString;
+}, z.core.$strip>;
+export type PutEmailContentQuery = z.infer<typeof putEmailContentQuerySchema>;
+export declare const putEmailContentRequestSchema: z.ZodObject<{
+    subject: z.ZodString;
+    content: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    expectedVersion: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type PutEmailContentRequest = z.infer<typeof putEmailContentRequestSchema>;
+/**
+ * The operator's per-email on/off switch.
+ *
+ * The module that owns this surface is non-deactivatable (issue #88), because
+ * the granularity the business wants is this one: an operator silences the
+ * back-in-stock notice without silencing account verification. The read side
+ * has honoured `active` since feature 047; this is the write side.
+ *
+ * Shaped like `ModuleActivationRequestSchema` — one boolean, stated rather than
+ * toggled, so a retry lands on the state the operator asked for instead of the
+ * opposite one.
+ */
+export declare const setTransactionalEmailActiveRequestSchema: z.ZodObject<{
+    active: z.ZodBoolean;
+}, z.core.$strip>;
+export type SetTransactionalEmailActiveRequest = z.infer<typeof setTransactionalEmailActiveRequestSchema>;
+/** The recomputed summary, so the list re-reads what the server resolved. */
+export declare const setTransactionalEmailActiveResponseSchema: z.ZodObject<{
+    code: z.ZodString;
+    name: z.ZodString;
+    ownerModule: z.ZodString;
+    group: z.ZodNullable<z.ZodString>;
+    active: z.ZodBoolean;
+    languages: z.ZodArray<z.ZodString>;
+    hasGlobalOverride: z.ZodBoolean;
+    hasChannelOverride: z.ZodBoolean;
+    deactivatable: z.ZodBoolean;
+    nonDeactivatableReason: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type SetTransactionalEmailActiveResponse = z.infer<typeof setTransactionalEmailActiveResponseSchema>;
+export declare const previewEmailRequestSchema: z.ZodObject<{
+    salesChannelId: z.ZodOptional<z.ZodString>;
+    language: z.ZodOptional<z.ZodString>;
+    draftSubject: z.ZodOptional<z.ZodString>;
+    draftContent: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type PreviewEmailRequest = z.infer<typeof previewEmailRequestSchema>;
+export declare const previewEmailResponseSchema: z.ZodObject<{
+    subject: z.ZodString;
+    html: z.ZodString;
+    text: z.ZodString;
+}, z.core.$strip>;
+export type PreviewEmailResponse = z.infer<typeof previewEmailResponseSchema>;
+export declare const emailBlockSummarySchema: z.ZodObject<{
+    id: z.ZodString;
+    code: z.ZodString;
+    name: z.ZodString;
+    active: z.ZodBoolean;
+    isSystem: z.ZodBoolean;
+    scope: z.ZodEnum<{
+        channel: "channel";
+        global: "global";
+    }>;
+    languages: z.ZodArray<z.ZodString>;
+    version: z.ZodNumber;
+}, z.core.$strip>;
+export type EmailBlockSummary = z.infer<typeof emailBlockSummarySchema>;
+export declare const emailBlockDetailSchema: z.ZodObject<{
+    id: z.ZodString;
+    code: z.ZodString;
+    name: z.ZodString;
+    active: z.ZodBoolean;
+    isSystem: z.ZodBoolean;
+    scope: z.ZodEnum<{
+        channel: "channel";
+        global: "global";
+    }>;
+    languages: z.ZodArray<z.ZodString>;
+    version: z.ZodNumber;
+    description: z.ZodNullable<z.ZodString>;
+    content: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    salesChannelIds: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type EmailBlockDetail = z.infer<typeof emailBlockDetailSchema>;
+export declare const createEmailBlockRequestSchema: z.ZodObject<{
+    code: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    active: z.ZodOptional<z.ZodBoolean>;
+    salesChannelIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    languages: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type CreateEmailBlockRequest = z.infer<typeof createEmailBlockRequestSchema>;
+export declare const patchEmailBlockRequestSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    active: z.ZodOptional<z.ZodBoolean>;
+    salesChannelIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    expectedVersion: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type PatchEmailBlockRequest = z.infer<typeof patchEmailBlockRequestSchema>;
+export declare const putEmailBlockContentRequestSchema: z.ZodObject<{
+    content: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    expectedVersion: z.ZodNumber;
+}, z.core.$strip>;
+export type PutEmailBlockContentRequest = z.infer<typeof putEmailBlockContentRequestSchema>;
+export declare const emailTemplateSummarySchema: z.ZodObject<{
+    version: z.ZodNumber;
+    languages: z.ZodArray<z.ZodString>;
+    id: z.ZodString;
+    code: z.ZodString;
+    name: z.ZodString;
+    isSystem: z.ZodBoolean;
+    scope: z.ZodEnum<{
+        channel: "channel";
+        global: "global";
+    }>;
+}, z.core.$strip>;
+export type EmailTemplateSummary = z.infer<typeof emailTemplateSummarySchema>;
+export declare const emailTemplateDetailSchema: z.ZodObject<{
+    version: z.ZodNumber;
+    languages: z.ZodArray<z.ZodString>;
+    id: z.ZodString;
+    description: z.ZodNullable<z.ZodString>;
+    code: z.ZodString;
+    name: z.ZodString;
+    isSystem: z.ZodBoolean;
+    scope: z.ZodEnum<{
+        channel: "channel";
+        global: "global";
+    }>;
+    content: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    salesChannelIds: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type EmailTemplateDetail = z.infer<typeof emailTemplateDetailSchema>;
+export declare const createEmailTemplateRequestSchema: z.ZodObject<{
+    languages: z.ZodArray<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    code: z.ZodString;
+    name: z.ZodString;
+    salesChannelIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type CreateEmailTemplateRequest = z.infer<typeof createEmailTemplateRequestSchema>;
+export declare const patchEmailTemplateRequestSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    salesChannelIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    expectedVersion: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type PatchEmailTemplateRequest = z.infer<typeof patchEmailTemplateRequestSchema>;
+export declare const emailBrandingSchema: z.ZodObject<{
+    salesChannelId: z.ZodNullable<z.ZodString>;
+    logoAssetId: z.ZodString;
+    logoUrl: z.ZodString;
+    accentColor: z.ZodString;
+    headerBlockCode: z.ZodString;
+    footerBlockCode: z.ZodString;
+    source: z.ZodEnum<{
+        default: "default";
+        channel: "channel";
+        global: "global";
+    }>;
+}, z.core.$strip>;
+export type EmailBranding = z.infer<typeof emailBrandingSchema>;
+export declare const putEmailBrandingRequestSchema: z.ZodObject<{
+    logoAssetId: z.ZodOptional<z.ZodString>;
+    accentColor: z.ZodOptional<z.ZodString>;
+    headerBlockCode: z.ZodOptional<z.ZodString>;
+    footerBlockCode: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PutEmailBrandingRequest = z.infer<typeof putEmailBrandingRequestSchema>;
+export declare const emailScopeQuerySchema: z.ZodObject<{
+    salesChannelId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type EmailScopeQuery = z.infer<typeof emailScopeQuerySchema>;
+export declare const emailPageBuilderDescriptorSchema: z.ZodObject<{
+    schemaVersion: z.ZodNumber;
+    components: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        previewIcon: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type EmailPageBuilderDescriptor = z.infer<typeof emailPageBuilderDescriptorSchema>;
+export interface TransactionalEmailSendInput {
+    code: string;
+    /**
+     * The channel whose content, branding and embeds apply, or `null` for the
+     * platform-wide ones.
+     *
+     * Widened from `string` (issue #103). The sender's own resolution chain has
+     * always been channel → global → default and has always spelled "global" as
+     * `null`; only this input type could not say it, so `invoices` passed `''`,
+     * which the settings seam guard rejects — the branding read threw, the
+     * dispatcher's `catch` absorbed it, and the invoice e-mail vanished.
+     */
+    salesChannelId: string | null;
+    language: string;
+    to: string;
+    variables: Record<string, unknown>;
+    /** Idempotency key — preserve the per-email message id used today. */
+    messageId: string;
+    /**
+     * Optional binary attachments (feature 047 invoices — PDF delivery). Uses
+     * `Uint8Array` (not Node's `Buffer`) so this shared contract stays
+     * browser-safe for the api-client; a backend `Buffer` satisfies it.
+     */
+    attachments?: Array<{
+        filename: string;
+        content: Uint8Array;
+        contentType?: string;
+    }>;
+    /**
+     * The business document this message delivers, when it delivers one (D-59).
+     * Forwarded to the transport so the delivery record is findable by the
+     * document an operator is asked about — an invoice, in the case the ruling
+     * was written for — rather than only by a recipient and a message id.
+     */
+    document?: {
+        type: string;
+        id: string;
+    };
+    meta?: Record<string, unknown>;
+}
+/**
+ * Why a send did — or did not — reach the transport.
+ *
+ * `send` used to answer `Promise<void>` for four unrelated situations, so a
+ * caller could not tell "the operator switched this email off" from "no
+ * template exists for this code yet". Only the latter justifies falling back to
+ * a caller's legacy in-code builder; the others mean the platform deliberately
+ * sent nothing and a fallback would send mail the operator did not ask for.
+ */
+export type TransactionalSendOutcome = 
+/** Handed to the transport. */
+{
+    status: 'sent';
+}
+/** The definition exists and an operator set `active = false`. */
+ | {
+    status: 'deactivated';
+}
+/** No mailer is wired in this composition — nothing can be delivered. */
+ | {
+    status: 'no_transport';
+}
+/** No definition for this code: the caller may use its own builder. */
+ | {
+    status: 'no_definition';
+};
+export interface TransactionalEmailSender {
+    /**
+     * An implementor must say which of the four happened — reporting nothing
+     * while delivering nothing is the defect this type exists to close. A
+     * deployment decoration that still answers `void` stops compiling against
+     * this interface, and that compile break is the intended signal.
+     */
+    send(input: TransactionalEmailSendInput): Promise<TransactionalSendOutcome>;
+}
+/** The subject and body a module ships for one of its own e-mails. */
+export interface EmailDefaults {
+    /** Per-language subject: `{ lang: string }`. */
+    defaultSubject: Record<string, string>;
+    /** Content envelope: `{ schema_version, languages: { lang: tree } }`. */
+    defaultContent: Record<string, unknown>;
+    /**
+     * Declared exactly when this individual e-mail may never be switched off
+     * (issue #89) — the per-e-mail twin of a manifest's
+     * `activation.nonDeactivatable`, and named after it on purpose.
+     *
+     * It lives **here**, on the contribution the owning module already pushes,
+     * rather than as a list in `transactional_emails` or in the admin app: only
+     * the module that sends the e-mail knows whether its flow survives silence,
+     * and a list anywhere else is a second source of truth that drifts the first
+     * time a module adds one.
+     *
+     * Presence carries the "true": a shape with a separate boolean and a reason
+     * has a state where the two contradict each other, and this one does not.
+     */
+    nonDeactivatable?: {
+        reason: string;
+    };
+}
+/**
+ * Container name: `emailDefaultsPort`. Owner: `transactional_emails`.
+ *
+ * A **contribution seam**, and the most-contributed-to one in the tree: seven
+ * modules push the defaults for their own e-mails from `ctx.onBoot`, and this
+ * module's boot reconciler reads the table once.
+ *
+ * The ordering is by construction rather than by luck — boot hooks run during
+ * composition and plugin bodies only when the Fastify app is built, so every
+ * contribution lands before the read. Publishing the shape must not change
+ * that, and must not gate it: a gate would throw during composition, exactly
+ * as `assetReferenceRegistry`'s did before it was un-gated.
+ *
+ * **Owner off:** nothing throws here. This is a **contribution seam**, a plain
+ * `di.register` rather than a `providePort`, so a push still lands and
+ * `transactional_emails` filters by contributor when it enumerates. Converting it to
+ * `providePort` would move every edge into it from `contributes` to
+ * `fails-closed` in the deactivation-consequence ledger, and change the
+ * sentence the operator's confirmation dialog renders.
+ */
+export interface EmailDefaultsRegistryPort {
+    register(code: string, defaults: EmailDefaults, ownerModuleId: string): void;
+    get(code: string): EmailDefaults | undefined;
+    has(code: string): boolean;
+    /** Which module contributed the code, or `undefined` when nobody did. */
+    ownerOf(code: string): string | undefined;
+    /** Every code and its contributor. */
+    owners(): ReadonlyMap<string, string>;
+    /**
+     * The reason this e-mail may never be switched off, or `null` when it may.
+     * The write path and the admin projection both read it, so the two never
+     * disagree.
+     */
+    nonDeactivatableReasonOf(code: string): string | null;
+}
+/**
+ * Container name: `templateEmailPort`. Owner: `transactional_emails`.
+ *
+ * `organizations` is the only cross-module consumer. `true` means "handled —
+ * do not use your legacy in-code builder", and it covers three outcomes: a
+ * delivered e-mail, one an operator deactivated, and a composition with no
+ * transport. In all three the platform decided what to send, and a fallback
+ * would either send mail the operator switched off or fail the same way. Only
+ * a code with no definition at all answers `false`.
+ */
+export interface TemplateEmailPort {
+    trySend(input: {
+        code: string;
+        to: string;
+        messageId: string;
+        variables: Record<string, unknown>;
+        meta?: Record<string, unknown> | undefined;
+    }): Promise<boolean>;
+}
+//# sourceMappingURL=transactional-emails.d.ts.map

package/dist/transactional-emails.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transactional-emails.d.ts","sourceRoot":"","sources":["../src/transactional-emails.ts"],"names":[],"mappings":"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"}