@endora-commerce/mod-transactional-emails 0.100.0

package/dist/migrations/20260629T113442_transactional_emails_init.js

@@ -0,0 +1,133 @@
+import { Migration } from '@mikro-orm/migrations';
+import { randomUUID } from 'crypto';
+import { DEFAULT_HEADER_BLOCK_CODE, defaultHeaderTree, } from '@endora-commerce/email-components/defaults/default-header';
+import { DEFAULT_FOOTER_BLOCK_CODE, defaultFooterTree, envelopeFromTree, } from '@endora-commerce/email-components/defaults/default-footer';
+/**
+ * Feature 047 — Transactional Emails.
+ *
+ * Creates the module schema: email definitions (`transactional_emails`),
+ * per-scope/per-language admin customizations (`transactional_email_contents`,
+ * with two partial unique indexes since Postgres treats NULL sales_channel_id as
+ * distinct), reusable email-safe blocks/templates and their sales-channel
+ * bridges, and seeds the system default header/footer blocks (FR-020).
+ */
+const DEFAULT_LANGUAGES = ['en-US', 'pl-PL'];
+function jsonbLiteral(value) {
+    return JSON.stringify(value).replace(/'/g, "''");
+}
+export class Migration20260629T113442TransactionalEmailsInit extends Migration {
+    async up() {
+        // --- Definitions + module defaults -------------------------------------
+        this.addSql(`
+      create table "transactional_emails" (
+        "id" uuid not null,
+        "code" varchar(160) not null,
+        "name" varchar(200) not null,
+        "owner_module" varchar(64) not null,
+        "description" text null,
+        "group_code" varchar(64) null,
+        "variables" jsonb not null default '[]',
+        "languages" jsonb not null default '[]',
+        "default_subject" jsonb not null default '{}',
+        "default_content" jsonb not null default '{}',
+        "active" boolean not null default true,
+        "created_at" timestamptz not null,
+        "updated_at" timestamptz not null,
+        constraint "transactional_emails_pkey" primary key ("id")
+      );
+    `);
+        this.addSql(`alter table "transactional_emails" add constraint "transactional_emails_code_unique" unique ("code");`);
+        // --- Admin customizations (per scope + language) -----------------------
+        this.addSql(`
+      create table "transactional_email_contents" (
+        "id" uuid not null,
+        "email_id" uuid not null,
+        "sales_channel_id" uuid null,
+        "language" varchar(12) not null,
+        "subject" text not null,
+        "content" jsonb not null default '{}',
+        "version" int not null default 1,
+        "created_at" timestamptz not null,
+        "updated_at" timestamptz not null,
+        constraint "transactional_email_contents_pkey" primary key ("id")
+      );
+    `);
+        this.addSql(`alter table "transactional_email_contents" add constraint "tec_email_fk" ` +
+            `foreign key ("email_id") references "transactional_emails" ("id") on delete cascade;`);
+        this.addSql(`create unique index "tec_global_unique" on "transactional_email_contents" ("email_id", "language") where "sales_channel_id" is null;`);
+        this.addSql(`create unique index "tec_channel_unique" on "transactional_email_contents" ("email_id", "sales_channel_id", "language") where "sales_channel_id" is not null;`);
+        // --- Reusable blocks + bridge ------------------------------------------
+        this.addSql(`
+      create table "email_blocks" (
+        "id" uuid not null,
+        "code" varchar(180) not null,
+        "name" varchar(200) not null,
+        "description" text null,
+        "active" boolean not null default true,
+        "content" jsonb not null default '{}',
+        "languages" jsonb not null default '[]',
+        "is_system" boolean not null default false,
+        "version" int not null default 1,
+        "created_at" timestamptz not null,
+        "updated_at" timestamptz not null,
+        constraint "email_blocks_pkey" primary key ("id")
+      );
+    `);
+        this.addSql(`create index "email_blocks_code_idx" on "email_blocks" ("code");`);
+        this.addSql(`
+      create table "email_block_sales_channels" (
+        "block_id" uuid not null,
+        "sales_channel_id" uuid not null,
+        "code" varchar(180) not null,
+        constraint "email_block_sales_channels_pkey" primary key ("block_id", "sales_channel_id")
+      );
+    `);
+        this.addSql(`alter table "email_block_sales_channels" add constraint "ebsc_block_fk" ` +
+            `foreign key ("block_id") references "email_blocks" ("id") on delete cascade;`);
+        this.addSql(`create unique index "ebsc_channel_code_unique" on "email_block_sales_channels" ("sales_channel_id", "code");`);
+        // --- Reusable templates + bridge ---------------------------------------
+        this.addSql(`
+      create table "email_templates" (
+        "id" uuid not null,
+        "code" varchar(180) not null,
+        "name" varchar(200) not null,
+        "description" text null,
+        "content" jsonb not null default '{}',
+        "languages" jsonb not null default '[]',
+        "is_system" boolean not null default false,
+        "version" int not null default 1,
+        "created_at" timestamptz not null,
+        "updated_at" timestamptz not null,
+        constraint "email_templates_pkey" primary key ("id")
+      );
+    `);
+        this.addSql(`create index "email_templates_code_idx" on "email_templates" ("code");`);
+        this.addSql(`
+      create table "email_template_sales_channels" (
+        "template_id" uuid not null,
+        "sales_channel_id" uuid not null,
+        "code" varchar(180) not null,
+        constraint "email_template_sales_channels_pkey" primary key ("template_id", "sales_channel_id")
+      );
+    `);
+        this.addSql(`alter table "email_template_sales_channels" add constraint "etsc_template_fk" ` +
+            `foreign key ("template_id") references "email_templates" ("id") on delete cascade;`);
+        this.addSql(`create unique index "etsc_channel_code_unique" on "email_template_sales_channels" ("sales_channel_id", "code");`);
+        // --- Seed system default header + footer blocks (FR-020) ---------------
+        const header = envelopeFromTree(defaultHeaderTree(), DEFAULT_LANGUAGES);
+        const footer = envelopeFromTree(defaultFooterTree(), DEFAULT_LANGUAGES);
+        this.addSql(`insert into "email_blocks" ("id", "code", "name", "active", "content", "languages", "is_system", "version", "created_at", "updated_at") ` +
+            `values ('${randomUUID()}', '${DEFAULT_HEADER_BLOCK_CODE}', 'Default header', true, '${jsonbLiteral(header)}'::jsonb, '${jsonbLiteral(DEFAULT_LANGUAGES)}'::jsonb, true, 1, now(), now());`);
+        this.addSql(`insert into "email_blocks" ("id", "code", "name", "active", "content", "languages", "is_system", "version", "created_at", "updated_at") ` +
+            `values ('${randomUUID()}', '${DEFAULT_FOOTER_BLOCK_CODE}', 'Default footer', true, '${jsonbLiteral(footer)}'::jsonb, '${jsonbLiteral(DEFAULT_LANGUAGES)}'::jsonb, true, 1, now(), now());`);
+    }
+    async down() {
+        this.addSql('drop table if exists "email_template_sales_channels" cascade;');
+        this.addSql('drop table if exists "email_templates" cascade;');
+        this.addSql('drop table if exists "email_block_sales_channels" cascade;');
+        this.addSql('drop table if exists "email_blocks" cascade;');
+        this.addSql('drop table if exists "transactional_email_contents" cascade;');
+        this.addSql('drop table if exists "transactional_emails" cascade;');
+    }
+}
+//# sourceMappingURL=20260629T113442_transactional_emails_init.js.map

package/dist/migrations/20260629T113442_transactional_emails_init.js.map

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

package/dist/migrations/20260801T111001_transactional_emails_email_defaults_reseed.d.ts

@@ -0,0 +1,6 @@
+import { Migration } from '@mikro-orm/migrations';
+export declare class Migration20260801T111001TransactionalEmailsEmailDefaultsReseed extends Migration {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}
+//# sourceMappingURL=20260801T111001_transactional_emails_email_defaults_reseed.d.ts.map

package/dist/migrations/20260801T111001_transactional_emails_email_defaults_reseed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260801T111001_transactional_emails_email_defaults_reseed.d.ts","sourceRoot":"","sources":["../../src/migrations/20260801T111001_transactional_emails_email_defaults_reseed.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAqClD,qBAAa,8DAA+D,SAAQ,SAAS;IAC5E,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC;IAsBnB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAIrC"}

package/dist/migrations/20260801T111001_transactional_emails_email_defaults_reseed.js

@@ -0,0 +1,49 @@
+import { Migration } from '@mikro-orm/migrations';
+import { defaultHeaderTree } from '@endora-commerce/email-components/defaults/default-header';
+import { defaultFooterTree, envelopeFromTree, } from '@endora-commerce/email-components/defaults/default-footer';
+/**
+ * Reseed this module's own system header/footer block trees from the current
+ * `@endora-commerce/email-components` defaults, and clear admin transactional email
+ * content overrides so boot reconcile + Reset land on the new simple layouts.
+ *
+ * Timestamped after FROZEN_THROUGH (feature 065) so it sorts after 100–106. The mis-numbered
+ * `Migration099EmailDefaultsReseed` broke `migrator.down()` loops that parse
+ * the latest migration ordinal (catalog attributes-migration-parity tests).
+ *
+ * It reseeded `newsletter`'s two system blocks as well, with two `UPDATE`s
+ * against `newsletter_email_blocks`, until
+ * `specs/120-migration-closure-bridge-ownership/` FR-019 removed them in place.
+ * Nothing replaced them here and nothing should: `newsletter` owns that table,
+ * and this module declares `activation: { nonDeactivatable: true }`, so naming
+ * `newsletter` in its `dependencies` to make the write legal would turn
+ * `newsletter`'s activation control into a dead switch. An instance that omits
+ * `newsletter` altogether — which the default module set does, it being the
+ * `nonDeactivatable` closure — could not migrate at all while they stood. The
+ * refresh of an existing database, if anyone wants one, is `newsletter`'s to
+ * ship in a `newsletter`-owned migration that needs no cross-module edge.
+ */
+const DEFAULT_LANGUAGES = ['en-US', 'pl-PL'];
+const TE_HEADER = 'default_email_header';
+const TE_FOOTER = 'default_email_footer';
+function jsonbLiteral(value) {
+    return JSON.stringify(value).replace(/'/g, "''");
+}
+export class Migration20260801T111001TransactionalEmailsEmailDefaultsReseed extends Migration {
+    async up() {
+        // Retire the mis-numbered 099 row if a previous deploy already applied it.
+        this.addSql(`delete from "mikro_orm_migrations" where "name" = 'Migration099EmailDefaultsReseed';`);
+        const header = envelopeFromTree(defaultHeaderTree(), DEFAULT_LANGUAGES);
+        const footer = envelopeFromTree(defaultFooterTree(), DEFAULT_LANGUAGES);
+        const headerJson = jsonbLiteral(header);
+        const footerJson = jsonbLiteral(footer);
+        this.addSql(`update "email_blocks" set "content" = '${headerJson}'::jsonb, "version" = "version" + 1, "updated_at" = now() where "code" = '${TE_HEADER}' and "is_system" = true;`);
+        this.addSql(`update "email_blocks" set "content" = '${footerJson}'::jsonb, "version" = "version" + 1, "updated_at" = now() where "code" = '${TE_FOOTER}' and "is_system" = true;`);
+        // Drop admin overrides so editors see the refreshed module defaults.
+        this.addSql('delete from "transactional_email_contents";');
+    }
+    async down() {
+        // Content overrides cannot be restored; block trees stay at the reseeded
+        // shape (same as up). No destructive schema change to roll back.
+    }
+}
+//# sourceMappingURL=20260801T111001_transactional_emails_email_defaults_reseed.js.map

package/dist/migrations/20260801T111001_transactional_emails_email_defaults_reseed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260801T111001_transactional_emails_email_defaults_reseed.js","sourceRoot":"","sources":["../../src/migrations/20260801T111001_transactional_emails_email_defaults_reseed.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,2DAA2D,CAAC;AAC9F,OAAO,EACL,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,2DAA2D,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,iBAAiB,GAAG,CAAC,OAAO,EAAE,OAAO,CAAU,CAAC;AAEtD,MAAM,SAAS,GAAG,sBAAsB,CAAC;AACzC,MAAM,SAAS,GAAG,sBAAsB,CAAC;AAEzC,SAAS,YAAY,CAAC,KAAc;IAClC,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AACnD,CAAC;AAED,MAAM,OAAO,8DAA+D,SAAQ,SAAS;IAClF,KAAK,CAAC,EAAE;QACf,2EAA2E;QAC3E,IAAI,CAAC,MAAM,CACT,sFAAsF,CACvF,CAAC;QAEF,MAAM,MAAM,GAAG,gBAAgB,CAAC,iBAAiB,EAAE,EAAE,iBAAiB,CAAC,CAAC;QACxE,MAAM,MAAM,GAAG,gBAAgB,CAAC,iBAAiB,EAAE,EAAE,iBAAiB,CAAC,CAAC;QACxE,MAAM,UAAU,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;QACxC,MAAM,UAAU,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;QAExC,IAAI,CAAC,MAAM,CACT,0CAA0C,UAAU,6EAA6E,SAAS,2BAA2B,CACtK,CAAC;QACF,IAAI,CAAC,MAAM,CACT,0CAA0C,UAAU,6EAA6E,SAAS,2BAA2B,CACtK,CAAC;QAEF,qEAAqE;QACrE,IAAI,CAAC,MAAM,CAAC,6CAA6C,CAAC,CAAC;IAC7D,CAAC;IAEQ,KAAK,CAAC,IAAI;QACjB,yEAAyE;QACzE,iEAAiE;IACnE,CAAC;CACF"}

package/dist/migrations/20260903T101748_transactional_emails_namespace_block_names.d.ts

@@ -0,0 +1,6 @@
+import { Migration } from '@mikro-orm/migrations';
+export declare class Migration20260903T101748TransactionalEmailsNamespaceBlockNames extends Migration {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}
+//# sourceMappingURL=20260903T101748_transactional_emails_namespace_block_names.d.ts.map

package/dist/migrations/20260903T101748_transactional_emails_namespace_block_names.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260903T101748_transactional_emails_namespace_block_names.d.ts","sourceRoot":"","sources":["../../src/migrations/20260903T101748_transactional_emails_namespace_block_names.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAmDlD,qBAAa,8DAA+D,SAAQ,SAAS;IAC5E,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC;IAQnB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAOrC"}

package/dist/migrations/20260903T101748_transactional_emails_namespace_block_names.js

@@ -0,0 +1,60 @@
+import { Migration } from '@mikro-orm/migrations';
+import { FROZEN_BLOCK_RENAMES, FROZEN_BLOCK_RENAMES_INVERSE, applyRenameFunctionSql, createRenameFunctionSql, dropRenameFunctionSql, } from '@endora-commerce/page-builder-core/migration';
+/**
+ * Namespace the Page Builder block names stored in `transactional_emails`'s 3 `jsonb` columns
+ * — feature 096, T406 (`contracts/block-name-migration.md`).
+ *
+ * **The rewrite is structural, never textual.** Twelve of the 74 renamed names
+ * are ordinary English words that occur throughout shop content — `Row`,
+ * `Text`, `Image`, `Map`, `Button` among them — so a text substitution over the
+ * column would corrupt a `RawHtml` block's markup and every `alt` attribute in
+ * the shop. `pg_temp.rename_block_names_transactional_emails` descends the document and replaces the value of a
+ * `type` property in a **node** position and nothing else; the walk is
+ * generated from `FROZEN_BLOCK_RENAMES` by
+ * `@endora-commerce/page-builder-core/migration`, so five migrations share one
+ * definition of what a node is.
+ *
+ * **This migration belongs to `transactional_emails` because `transactional_emails` owns these tables**,
+ * not because it owns the new names (`contracts/block-name-migration.md` §2).
+ * Some of the names it writes belong to other modules; that creates no
+ * obligation on them and **no new manifest `dependencies` edge**, because a
+ * block name is a string value inside a JSONB document — not a foreign key and
+ * not a table identifier.
+ *
+ * **It cannot fail on its input.** A name the map does not hold is left
+ * byte-identical: an already-namespaced one and an unrecognised one alike,
+ * because the map's domain is bare and its codomain is dotted, so the two sets
+ * are disjoint. That is also what makes a second run rewrite nothing — FR-013
+ * is a property of the map rather than an outcome a branch has to remember to
+ * produce, and no dot test appears in this SQL.
+ *
+ * `down()` applies the inverse over the identical walk and is **exact for the
+ * frozen set**. It is partial by construction: a name with no pre-migration
+ * form — a block authored after the upgrade, a third party's `acme.Banner` —
+ * has nothing to return to and is left alone. That is correct, and it is why
+ * the operator pre-flight (§6) is a backup rather than a `down()`.
+ */
+/**
+ * Named per module: the five rename migrations may run on one pooled session,
+ * and a second `create function` over the same name fails. Each drops its own
+ * when it is done, and a rollback removes it with everything else — `pg_temp`
+ * DDL is transactional.
+ */
+const FN = 'rename_block_names_transactional_emails';
+export class Migration20260903T101748TransactionalEmailsNamespaceBlockNames extends Migration {
+    async up() {
+        this.addSql(createRenameFunctionSql(FN, FROZEN_BLOCK_RENAMES));
+        this.addSql(applyRenameFunctionSql(FN, 'email_templates', 'content'));
+        this.addSql(applyRenameFunctionSql(FN, 'email_blocks', 'content'));
+        this.addSql(applyRenameFunctionSql(FN, 'transactional_email_contents', 'content'));
+        this.addSql(dropRenameFunctionSql(FN));
+    }
+    async down() {
+        this.addSql(createRenameFunctionSql(FN, FROZEN_BLOCK_RENAMES_INVERSE));
+        this.addSql(applyRenameFunctionSql(FN, 'email_templates', 'content'));
+        this.addSql(applyRenameFunctionSql(FN, 'email_blocks', 'content'));
+        this.addSql(applyRenameFunctionSql(FN, 'transactional_email_contents', 'content'));
+        this.addSql(dropRenameFunctionSql(FN));
+    }
+}
+//# sourceMappingURL=20260903T101748_transactional_emails_namespace_block_names.js.map

package/dist/migrations/20260903T101748_transactional_emails_namespace_block_names.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260903T101748_transactional_emails_namespace_block_names.js","sourceRoot":"","sources":["../../src/migrations/20260903T101748_transactional_emails_namespace_block_names.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EACL,oBAAoB,EACpB,4BAA4B,EAC5B,sBAAsB,EACtB,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,8CAA8C,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH;;;;;GAKG;AACH,MAAM,EAAE,GAAG,yCAAyC,CAAC;AAErD,MAAM,OAAO,8DAA+D,SAAQ,SAAS;IAClF,KAAK,CAAC,EAAE;QACf,IAAI,CAAC,MAAM,CAAC,uBAAuB,CAAC,EAAE,EAAE,oBAAoB,CAAC,CAAC,CAAC;QAC/D,IAAI,CAAC,MAAM,CAAC,sBAAsB,CAAC,EAAE,EAAE,iBAAiB,EAAE,SAAS,CAAC,CAAC,CAAC;QACtE,IAAI,CAAC,MAAM,CAAC,sBAAsB,CAAC,EAAE,EAAE,cAAc,EAAE,SAAS,CAAC,CAAC,CAAC;QACnE,IAAI,CAAC,MAAM,CAAC,sBAAsB,CAAC,EAAE,EAAE,8BAA8B,EAAE,SAAS,CAAC,CAAC,CAAC;QACnF,IAAI,CAAC,MAAM,CAAC,qBAAqB,CAAC,EAAE,CAAC,CAAC,CAAC;IACzC,CAAC;IAEQ,KAAK,CAAC,IAAI;QACjB,IAAI,CAAC,MAAM,CAAC,uBAAuB,CAAC,EAAE,EAAE,4BAA4B,CAAC,CAAC,CAAC;QACvE,IAAI,CAAC,MAAM,CAAC,sBAAsB,CAAC,EAAE,EAAE,iBAAiB,EAAE,SAAS,CAAC,CAAC,CAAC;QACtE,IAAI,CAAC,MAAM,CAAC,sBAAsB,CAAC,EAAE,EAAE,cAAc,EAAE,SAAS,CAAC,CAAC,CAAC;QACnE,IAAI,CAAC,MAAM,CAAC,sBAAsB,CAAC,EAAE,EAAE,8BAA8B,EAAE,SAAS,CAAC,CAAC,CAAC;QACnF,IAAI,CAAC,MAAM,CAAC,qBAAqB,CAAC,EAAE,CAAC,CAAC,CAAC;IACzC,CAAC;CACF"}

package/dist/migrations/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The `./migrations` subpath — every migration class this module owns, as one
+ * ordered `migrations` array.
+ *
+ * The array is what the platform reads when this module is **installed**:
+ * `src/packages/package-runtime.ts` takes `exported['migrations']` and refuses
+ * the package outright when it is absent (D-168).
+ *
+ * Listed in ascending timestamp, which is the order of this module's own
+ * migrations and of nothing else (feature 081): a manifest `dependencies` array
+ * is the only thing ordering this block against another module's.
+ *
+ * The **named** exports stay beside the array, and the asymmetry with
+ * `./backend` — which publishes an array and no named class (D-168) — is
+ * deliberate. `db/migrations-registry.generated.ts` imports each class by name
+ * from this specifier, and a migration class name is contract in a way an entity
+ * class name is not: `mikro_orm_migrations` persists it, so it is a string every
+ * already-migrated database holds.
+ *
+ * A class that is in neither the array nor the barrel is a migration that does
+ * not run: `migration:pending` reports nothing pending and the first symptom is
+ * a query against a table nobody created.
+ */
+import { Migration20260629T113442TransactionalEmailsInit } from './20260629T113442_transactional_emails_init.js';
+import { Migration20260801T111001TransactionalEmailsEmailDefaultsReseed } from './20260801T111001_transactional_emails_email_defaults_reseed.js';
+import { Migration20260903T101748TransactionalEmailsNamespaceBlockNames } from './20260903T101748_transactional_emails_namespace_block_names.js';
+export declare const migrations: (typeof Migration20260629T113442TransactionalEmailsInit)[];
+export { Migration20260629T113442TransactionalEmailsInit, Migration20260801T111001TransactionalEmailsEmailDefaultsReseed, Migration20260903T101748TransactionalEmailsNamespaceBlockNames, };
+//# sourceMappingURL=index.d.ts.map

package/dist/migrations/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/migrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,+CAA+C,EAAE,MAAM,gDAAgD,CAAC;AACjH,OAAO,EAAE,8DAA8D,EAAE,MAAM,iEAAiE,CAAC;AACjJ,OAAO,EAAE,8DAA8D,EAAE,MAAM,iEAAiE,CAAC;AAEjJ,eAAO,MAAM,UAAU,4DAItB,CAAC;AAEF,OAAO,EACL,+CAA+C,EAC/C,8DAA8D,EAC9D,8DAA8D,GAC/D,CAAC"}

package/dist/migrations/index.js

@@ -0,0 +1,33 @@
+/**
+ * The `./migrations` subpath — every migration class this module owns, as one
+ * ordered `migrations` array.
+ *
+ * The array is what the platform reads when this module is **installed**:
+ * `src/packages/package-runtime.ts` takes `exported['migrations']` and refuses
+ * the package outright when it is absent (D-168).
+ *
+ * Listed in ascending timestamp, which is the order of this module's own
+ * migrations and of nothing else (feature 081): a manifest `dependencies` array
+ * is the only thing ordering this block against another module's.
+ *
+ * The **named** exports stay beside the array, and the asymmetry with
+ * `./backend` — which publishes an array and no named class (D-168) — is
+ * deliberate. `db/migrations-registry.generated.ts` imports each class by name
+ * from this specifier, and a migration class name is contract in a way an entity
+ * class name is not: `mikro_orm_migrations` persists it, so it is a string every
+ * already-migrated database holds.
+ *
+ * A class that is in neither the array nor the barrel is a migration that does
+ * not run: `migration:pending` reports nothing pending and the first symptom is
+ * a query against a table nobody created.
+ */
+import { Migration20260629T113442TransactionalEmailsInit } from './20260629T113442_transactional_emails_init.js';
+import { Migration20260801T111001TransactionalEmailsEmailDefaultsReseed } from './20260801T111001_transactional_emails_email_defaults_reseed.js';
+import { Migration20260903T101748TransactionalEmailsNamespaceBlockNames } from './20260903T101748_transactional_emails_namespace_block_names.js';
+export const migrations = [
+    Migration20260629T113442TransactionalEmailsInit,
+    Migration20260801T111001TransactionalEmailsEmailDefaultsReseed,
+    Migration20260903T101748TransactionalEmailsNamespaceBlockNames,
+];
+export { Migration20260629T113442TransactionalEmailsInit, Migration20260801T111001TransactionalEmailsEmailDefaultsReseed, Migration20260903T101748TransactionalEmailsNamespaceBlockNames, };
+//# sourceMappingURL=index.js.map

package/dist/migrations/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/migrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,+CAA+C,EAAE,MAAM,gDAAgD,CAAC;AACjH,OAAO,EAAE,8DAA8D,EAAE,MAAM,iEAAiE,CAAC;AACjJ,OAAO,EAAE,8DAA8D,EAAE,MAAM,iEAAiE,CAAC;AAEjJ,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,+CAA+C;IAC/C,8DAA8D;IAC9D,8DAA8D;CAC/D,CAAC;AAEF,OAAO,EACL,+CAA+C,EAC/C,8DAA8D,EAC9D,8DAA8D,GAC/D,CAAC"}

package/docs/transactional-emails.md

@@ -0,0 +1,176 @@
+---
+title: transactional_emails
+description: Admin-editable transactional emails — subject, content and look, globally and per sales channel
+---
+
+# `transactional_emails`
+
+Admin-editable transactional emails. Lets operators change the **subject**,
+**content**, and **look** of every transactional email the platform sends —
+globally and per **Sales Channel** — from the Admin UI, using an
+email-client-safe WYSIWYG editor consistent with the CMS Page Builder. Each
+email is described by a **definition** registered by the module that owns it
+(orders, returns, organizations, inventory, …), which supplies a default
+subject + default content and the set of variables the business logic
+substitutes at send time.
+
+## Concepts
+
+- **Definition** — a registered email identified by a unique `code` (e.g.
+  `order_confirmation`). Carries the owning module, declared variables (with
+  sample values for preview), supported languages, and the module-provided
+  default subject + content. Reconciled into `transactional_emails` at boot;
+  orphaned definitions (owning module uninstalled) are pruned.
+- **Content** — the admin's per-scope, per-language customization, stored in
+  `transactional_email_contents`. Resolution at send time is
+  **per-channel → global → module default**, with a fallback to the channel's
+  default language. Absence of a row means "fall back"; **Reset** deletes it.
+- **Blocks & Templates** — reusable email-safe fragments. Blocks are embedded by
+  `code` via `EmailInsertBlock`. Email templates remain a separate admin list
+  (apply/save outside the canvas); `EmailInsertTemplate` is withdrawn from the
+  palette (legacy trees still render). The seeded system blocks
+  `default_email_header` (renders branding via `EmailLogo` / `{{var branding.logoUrl}}`) and `default_email_footer`
+  are auto-included in the default content.
+- **Branding** — header logo, accent color, and the default header/footer block
+  codes, resolved per scope through the Settings module
+  (`transactional_emails.*`). The resolved logo is exposed to every email as
+  `{{var branding.logoUrl}}`.
+- **Variables** — Magento-2-style directives over the content + subject:
+  `{{var path}}`, `{{if path}}…{{/if}}`, `{{for alias in list}}…{{/for}}`. Values
+  are HTML-escaped in the HTML body and raw in the plain-text alternative. A
+  missing value resolves to empty — an email is never sent with an unresolved
+  `{{…}}` and a missing variable never fails a send. The admin editor exposes an
+  **Insert variable** picker (subject, plain text fields, and rich text toolbar)
+  fed by the email's declared variables plus branding keys.
+
+## Email editor
+
+The transactional (and newsletter) editors share `EmailEditorPane`:
+
+- Email-safe Puck palette from `@endora-commerce/email-components` (no CMS breakpoints /
+  responsive stacking). **Row** opens a column-layout picker (1–6 columns) like
+  CMS; columns use a fixed table at send time and the CMS 12-col grid on the
+  canvas. **Column** is not listed in the palette (only inside Row). **Table** is
+  the data grid (headers + rows, like CMS SimpleTable).
+- The canvas is fixed at mail width (**600px**), with an Outline panel like CMS.
+  Use **Preview email** for a modal HTML render with sample variable data and
+  **Desktop mail (600px)** / **Narrow (320px)** options (fluid `max-width:600px`
+  shell so narrow preview does not overflow).
+  **Save as template** / **Apply template** reuse the CMS header actions against
+  transactional email templates (`email_templates`).
+- `EmailLogo` shows the branding logo (no URL field). `EmailImage` supports URL or
+  asset library, same as CMS. Color fields use the shared CMS color palette.
+  Branding logo in Settings (`*_asset_id`) uses the Assets Library picker.
+- `EmailRichText` reuses the CMS Rich Content TipTap editor (plus Variable).
+- `EmailProductCard` picks a catalog product; `EmailOrderSummary` is column/totals
+  toggles and appears in the palette only when the email declares `order.items`
+  (today: **Order confirmation** only). Order confirmation also exposes labeled
+  detail blocks: Order ID, Billing/Shipping address, Summary, Applied discounts,
+  Delivery method, Payment method (each gated on its template variable).
+- Content blocks include layout (`EmailSection`, `EmailRow`/`EmailColumn`, table,
+  spacer, divider),
+  copy (`EmailText`, `EmailRichText`, headings, callout, footer/legal), media
+  (`EmailImage`, `EmailLogo`), commerce (`EmailProductCard`, `EmailOrderSummary`
+  and the order detail blocks above), `EmailSocial` (icons + labels + per-link
+  enable), and `EmailInsertBlock`.
+
+## Rendering
+
+Rendering is performed **server-side** by the first-party `@endora-commerce/email-components`
+package (React-free): the Puck content tree is walked and emitted as
+table-based, inline-styled, email-client-safe HTML plus a plain-text
+alternative. The admin editor reuses the same email-safe component palette.
+`EmailRichText` HTML is whitelist-sanitized (`p/strong/em/u/a/ul/ol/li/br`)
+before send; directive markers in text are preserved.
+
+## Registering an email from a module
+
+```ts
+// manifest.ts
+transactionalEmails: [
+  { code: 'order_confirmation', name: 'Order confirmation', group: 'orders',
+    variables: [{ key: 'order.businessId', label: 'Order number', sampleValue: 'ORD-1042' }] },
+],
+
+// plugin.ts (default subject + content)
+emailDefaultsRegistry.register('order_confirmation', { defaultSubject, defaultContent });
+```
+
+The owning module sends through the `TransactionalEmailSender` port (injected by
+composition), preserving its existing idempotency `messageId`:
+
+```ts
+await sender.send({
+  code: 'order_confirmation',
+  salesChannelId, language, to,
+  messageId: `order_confirmation:${order.id}`,
+  variables: { order: { businessId, items: [...] }, customer: { firstName } },
+});
+```
+
+When the sender is not wired, modules fall back to their legacy in-code builders,
+so behavior is unchanged in environments without the module.
+
+## Preview
+
+`POST /api/v1/admin/transactional-emails/{code}/preview` renders an email with
+each variable's declared sample value (and any unsaved draft content), returning
+`{ subject, html, text }`. The admin opens the HTML in a new tab.
+
+## Switching an email off
+
+The module itself is **non-deactivatable**: every deployment sends account
+verification, invitations and order mail through it, so `/platform/modules`
+renders it locked with that reason rather than as a toggle. The granularity that
+*is* offered is the individual email — the list at `/transactional-emails`
+carries a per-row switch, backed by
+`POST /api/v1/admin/transactional-emails/{code}/activation` with `{ active }`.
+The flip runs through the Command Bus, so it is audited as
+`transactional_email.activation.set` and reversible; it drops no content, no
+override and no per-channel customization. A deactivated email answers
+`{ status: 'deactivated' }` at send time and **no fallback mail goes out**.
+
+Emails required to create an account or to get back into one may not be switched
+off at all: today `email_verification` and `organization_invitation`. The
+declaration lives on the owning module's registry entry
+(`EmailDefaults.nonDeactivatable`), not in a list held by this module or by the
+Admin UI, and a refused flip answers `409 TRANSACTIONAL_EMAIL_NOT_DEACTIVATABLE`
+carrying that module's own reason — the same shape the module-level refusal uses.
+
+## Delivery record
+
+Every send leaves one row in `email_deliveries`, a table owned by the `email`
+module — the transport is where a message's fate is decided, so it is where the
+record of that fate lives. The row carries the recipient, the email code, the
+sales channel, the message id, the business document the message delivered (an
+invoice, typically), the outcome and the moment it was attempted.
+
+The outcome is one of three, and the split is the point of the table:
+
+| Status | Means | Typical reason |
+| --- | --- | --- |
+| `sent` | the transport accepted the message | — |
+| `suppressed` | the platform deliberately did not send | `deactivated` (an operator switched this email off), `duplicate_message_id` |
+| `failed` | the message was meant to go out and did not | `transport_error`, `no_transport`, `no_definition` |
+
+An operator asking "did the customer get the invoice" therefore gets an answer
+that outlives a log rotation, and one that does not confuse a configuration they
+chose with an outage. This is **best-effort delivery with a durable record**, not
+guaranteed delivery: there is no retry queue and no outbox, a resend stays an
+operator action, and a message lost between the business write and the transport
+call is lost. There is no admin screen over the table yet — it is read from the
+database.
+
+## Permissions
+
+- `transactional_emails:read` — view emails, blocks, templates, branding, preview.
+- `transactional_emails:write` — edit content, branding, and manage blocks/templates.
+
+## Registered emails
+
+All pre-existing transactional emails route through this mechanism: orders
+(confirmation, comment, reorder, admin-created), returns (authorized, rejected),
+organizations (verification, invitation, new-registration), and inventory
+(low-stock, back-in-stock). Two net-new emails are also registered and dispatched
+via event subscribers: payments (`payment_status_changed`, on payment
+received/failed) and shipments (`shipment_created`, on shipment created).

package/i18n/en.json

@@ -0,0 +1,92 @@
+{
+  "actions.openTransactionalEmails.label": "Transactional emails",
+  "actions.openTransactionalEmails.description": "Edit transactional email content, look, blocks, and templates",
+  "actions.openEmailTemplates.label": "Email templates",
+  "actions.openEmailTemplates.description": "Manage transactional email layout templates",
+  "settings.logoAssetId.label": "Email header logo",
+  "settings.accentColor.label": "Email accent color",
+  "settings.headerBlockCode.label": "Default header block",
+  "settings.footerBlockCode.label": "Default footer block",
+  "page.title": "Transactional Emails",
+  "page.description": "Edit the content and look of transactional emails globally and per sales channel.",
+  "list.title": "Email templates",
+  "list.empty": "No transactional emails found.",
+  "list.search": "Search by name or code…",
+  "activation.column": "Status",
+  "activation.on": "On",
+  "activation.off": "Off",
+  "activation.locked": "Always on",
+  "activation.action.enable": "Switch on",
+  "activation.action.disable": "Switch off",
+  "editor.title": "Email",
+  "editor.subject": "Subject",
+  "editor.content": "Content",
+  "editor.save": "Save",
+  "editor.reset": "Reset to default",
+  "editor.preview": "Preview email",
+  "scope.global": "All channels (default)",
+  "scope.channel": "Sales channel",
+  "blocks.title": "Email blocks",
+  "templates.title": "Email templates",
+  "branding.title": "Branding",
+  "branding.logo": "Header logo",
+  "branding.accent": "Accent color",
+  "editor.viewport.desktop": "Desktop mail (600px)",
+  "editor.viewport.narrow": "Narrow (320px)",
+  "editor.variables.insert": "Insert variable",
+  "editor.variables.search": "Search variables…",
+  "editor.variables.button": "Variable",
+  "editor.livePreview": "Live HTML preview",
+  "components.EmailSection": "Section",
+  "components.EmailLogo": "Logo",
+  "components.EmailRichText": "Rich text",
+  "components.EmailProductCard": "Product card",
+  "components.EmailOrderSummary": "Order summary",
+  "components.EmailTable": "Table",
+  "components.EmailSocial": "Social links",
+  "components.EmailCallout": "Callout",
+  "components.EmailFooterLegal": "Footer / legal",
+  "actions.openEmailBlocks.label": "Email blocks",
+  "actions.openEmailBlocks.description": "Reusable email content blocks",
+  "nav.transactionalEmails.label": "Transactional Emails",
+  "nav.emailBlocks.label": "Email Blocks",
+  "nav.emailTemplates.label": "Email Templates",
+  "blocks.emailHeading.label": "Heading",
+  "blocks.emailHeading.description": "A heading line in an e-mail.",
+  "blocks.emailText.label": "Text",
+  "blocks.emailText.description": "A paragraph of e-mail-safe text.",
+  "blocks.emailRichText.label": "Rich text",
+  "blocks.emailRichText.description": "Formatted e-mail text edited in a rich-text editor.",
+  "blocks.emailButton.label": "Button",
+  "blocks.emailButton.description": "A call-to-action button rendered as an e-mail-safe table.",
+  "blocks.emailImage.label": "Image",
+  "blocks.emailImage.description": "A single image with alternative text.",
+  "blocks.emailLogo.label": "Logo",
+  "blocks.emailLogo.description": "The shop logo, taken from the e-mail branding settings.",
+  "blocks.emailSocial.label": "Social links",
+  "blocks.emailSocial.description": "Links to the shop social profiles.",
+  "blocks.emailCallout.label": "Callout",
+  "blocks.emailCallout.description": "A highlighted box drawing attention to one message.",
+  "blocks.emailFooterLegal.label": "Footer / legal",
+  "blocks.emailFooterLegal.description": "The legal footer with company details and an unsubscribe link.",
+  "blocks.emailSection.label": "Section",
+  "blocks.emailSection.description": "A full-width section that holds rows.",
+  "blocks.emailRow.label": "Row",
+  "blocks.emailRow.description": "A row that holds e-mail columns.",
+  "blocks.emailTable.label": "Table",
+  "blocks.emailTable.description": "A table of headers and rows.",
+  "blocks.emailDivider.label": "Divider",
+  "blocks.emailDivider.description": "A horizontal rule between blocks.",
+  "blocks.emailSpacer.label": "Spacer",
+  "blocks.emailSpacer.description": "Vertical whitespace between blocks.",
+  "blocks.emailInsertBlock.label": "Insert block",
+  "blocks.emailInsertBlock.description": "Embeds a reusable e-mail block by its code.",
+  "blocks.emailInsertTemplate.label": "Insert template",
+  "blocks.emailInsertTemplate.description": "Embeds an e-mail template by its code.",
+  "blocks.emailColumn.label": "Column",
+  "blocks.emailColumn.description": "A column inside an e-mail row. Insertable only into a row.",
+  "blocks.category.content": "Content",
+  "blocks.category.layout": "Layout",
+  "blocks.category.embeds": "Embeds",
+  "blocks.category.internal": "Internal"
+}