@endora-commerce/mod-newsletter 0.100.0

package/dist/migrations/20260830T212736_newsletter_organization_attribution.js

@@ -0,0 +1,186 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * D-187 — `newsletter_subscribers` gains its organisation, and a row that names
+ * a customer account carries one.
+ *
+ * Feature 087 Group B, class 4 of 4 and the last of the five
+ * (`specs/087-tenant-scope-enforcement/`). `NewsletterSubscriber` is
+ * `@CustomerScoped`, and until this migration the `allowed-set` arm of
+ * `customerFilterCond` had no column to grant on: a sales representative
+ * assigned to the buyer's own organisation was shown **none** of their
+ * subscribers. The column is what turns that into an answer.
+ *
+ * ## The column and the read arrive together, on purpose
+ *
+ * `customerOrganizationColumn` asks the ORM's own metadata whether the filtered
+ * entity carries `organizationId`, **per query**, so the entity property in
+ * this same merge request is what switches the grant on — there is no third
+ * artefact, no flag and no staging. At the same instant the
+ * `ORGANIZATION_ATTRIBUTION_PENDING` disclosure retires itself: it is keyed on
+ * the column's *absence*.
+ *
+ * That pairing is why this migration is not "column and backfill". From the
+ * moment the grant is live, a row inserted without an organisation is invisible
+ * to the representative who serves that organisation, on a screen that has just
+ * stopped explaining itself — and MikroORM applies no filter to `INSERT`
+ * (`r1-spike.md` §4, measured), so the filter cannot refuse it. The `CHECK`
+ * below is the only refusal an `INSERT` has.
+ *
+ * ## An implication, not an equivalence
+ *
+ * `customer_account_id is null or organization_id is not null` is FR-010 and
+ * FR-011 together and nothing wider: an **owned** row has an organisation, an
+ * **ownerless** row need not. This table is ownerless by construction for the
+ * storefront's sign-up form — `POST /api/v1/newsletter/subscribe` passes no
+ * account at all, so every subscriber who has never signed in is such a row,
+ * and on this table they are the majority rather than the exception. Who they
+ * belong to is R-6's open question. The equivalence would answer it in the
+ * schema, which D-187 declines to do.
+ *
+ * The shape the implication leaves open — an **ownerless** row still carrying
+ * an organisation — is unreachable here, for `inventory`'s reason rather than
+ * `pwa`'s. `subscriber.service.ts` writes `customer_account_id` in exactly two
+ * places and both of them *acquire* an owner: the `em.create` on first
+ * subscribe, and the adoption line that fills in the account when a subscriber
+ * who signed up anonymously later signs in. Nothing in this module ever clears
+ * it (grep of `packages/modules/newsletter/src` for `customerAccountId`: two
+ * writes, both assignments of a non-null id, the rest reads). So there is no
+ * de-association direction for the constraint to be silent about.
+ *
+ * ## The e-mail address is not a derivation
+ *
+ * `newsletter_subscribers.email` is globally unique and `customer_accounts`
+ * has an `email` too, so the backfill below could have matched them and
+ * attributed far more rows. It deliberately does not. That match would claim
+ * rows the schema does not link, silently and irreversibly, for whoever
+ * happened to sign up with the address their employer later registered — it is
+ * R-6 answer (2) guessed rather than decided. The only derivation is
+ * `customer_account_id`.
+ *
+ * ## No foreign key
+ *
+ * Matching `Cart`, `Comparison`, `PushSubscription` and
+ * `AvailabilityNotification`, none of which carries one. D-187 withdraws
+ * `r1-spike.md` §8's `on delete set null` recommendation as contradicting
+ * FR-011: it produces a row that names an account and no organisation, which is
+ * precisely the state this migration makes unreachable, and under the
+ * constraint below it would abort an unrelated organisation delete with a
+ * message about a table the operator was not touching. If one is ever taken
+ * here it must be `restrict`, and it is not this migration's decision.
+ *
+ * ## Derive, then count, then refuse — never delete
+ *
+ * The derivation is the owning account's own organisation. **On this table the
+ * refusal is a real branch, not a formality**: like `push_subscriptions` and
+ * `availability_notifications`, and unlike `comparisons`,
+ * `newsletter_subscribers` has **no foreign key** on `customer_account_id` —
+ * `20260629T200954_newsletter_init.ts` declares it `uuid null` and constrains
+ * nothing — so a row naming an account that is gone is representable here.
+ *
+ * It is nevertheless empty today, and the reason is worth knowing rather than
+ * hoping: a customer account is never hard-deleted in this tree.
+ * `customer-account-lifecycle-ports.ts` soft-deletes, restores and
+ * **anonymises** — the last one rewrites the e-mail and the name and keeps the
+ * row — and every one of those still satisfies `organization_id NOT NULL`
+ * (D-178), so it still derives. Change any of that and the count below is the
+ * only thing that would notice. The anonymise path is worth a second look on
+ * *this* table in particular, because it rewrites the very column an e-mail
+ * match would have keyed on; deriving from `customer_account_id` is unaffected
+ * by it.
+ *
+ * It raises with the count and up to twenty ids and deletes nothing (D-184), in
+ * the shape `20260825T141659_customer_accounts_organization_required.ts`
+ * established and the three Group B migrations before this one repeated.
+ * Deleting would be particularly wrong here: a subscriber row is a consent
+ * record, and dropping one destroys the evidence that the address may be
+ * mailed at all.
+ *
+ * ## Nothing to declare in the manifest
+ *
+ * `newsletter` declares `customers` in its manifest `dependencies`, whose
+ * transitive closure reaches `customer_accounts` and `organizations`, so the
+ * table this reads is created before this runs. No foreign key is added, so
+ * `fk-dependency-drift` has nothing to say either, and a migration naming
+ * another module's table is outside `check:module-boundary`'s population by
+ * that check's own rule.
+ *
+ * The standing guard is
+ * `backend/test/integration/tenancy/customer-scoped-organization-completeness.test.ts`,
+ * which derives its population from the ORM's metadata rather than from a list
+ * — so this class is covered by gaining the column, with no edit to that file.
+ */
+export class Migration20260830T212736NewsletterOrganizationAttribution extends Migration {
+    async up() {
+        // 1. The column. Nullable, because a storefront sign-up legitimately has
+        //    none (FR-011) and on this table that is the ordinary case rather than
+        //    the edge.
+        this.addSql(`alter table "newsletter_subscribers" add column "organization_id" uuid null;`);
+        // 2. Derive the organisation from the account that owns the subscription.
+        //    Every account carries one since D-178, including a soft-deleted or
+        //    anonymised one, so this is total for every row whose account is still
+        //    there. Step 3 is about the rows for which it is not.
+        this.addSql(`
+      update "newsletter_subscribers" ns
+      set "organization_id" = ca."organization_id"
+      from "customer_accounts" ca
+      where ca."id" = ns."customer_account_id"
+        and ns."organization_id" is null;
+    `);
+        // 3. Count what is left and refuse. This table has no foreign key on
+        //    `customer_account_id`, so a dangling account id is representable and
+        //    this branch is real. It deletes nothing (D-184).
+        this.addSql(`
+      do $$
+      declare
+        remaining bigint;
+        sample text;
+      begin
+        select count(*) into remaining
+          from "newsletter_subscribers"
+         where "customer_account_id" is not null
+           and "organization_id" is null;
+        if remaining > 0 then
+          select string_agg(id::text, ', ') into sample from (
+            select "id" from "newsletter_subscribers"
+             where "customer_account_id" is not null
+               and "organization_id" is null
+             order by "id" limit 20
+          ) s;
+          raise exception
+            'D-187: % newsletter_subscribers row(s) still name a customer account with organization_id IS NULL after derivation. First ids: %. Every customer account has an organization (D-178) and none is ever hard-deleted, so these rows name an account that is gone. Do not delete them - they are consent records - and do not match them by e-mail address, which is R-6 guessed. Find out how they got here.',
+            remaining, sample;
+        end if;
+      end $$;
+    `);
+        // 4. The constraint.
+        this.addSql(`
+      alter table "newsletter_subscribers"
+        add constraint "newsletter_subscribers_organization_attribution_chk"
+        check ("customer_account_id" is null or "organization_id" is not null);
+    `);
+        // 5. The index the entity property declares, named
+        //    `newsletter_subscribers_organization_idx` — **this table's own style**
+        //    and not the previous batch's. Every index the init migration wrote
+        //    here is `newsletter_subscribers_<subject>_idx`, and the one other
+        //    `*_id` column it indexes is spelled with the subject alone:
+        //    `sales_channel_id` is `newsletter_subscribers_channel_idx`, not
+        //    `..._sales_channel_id_index`. `comparisons` uses `idx_<table>_<col>`,
+        //    `pwa` uses `<table>_<col>_idx` and `inventory` uses
+        //    `<table>_<col>_index`; each followed its own table, and this follows
+        //    this one. Whole rather than partial, like every index above it here.
+        this.addSql(`
+      create index "newsletter_subscribers_organization_idx"
+        on "newsletter_subscribers" ("organization_id");
+    `);
+    }
+    async down() {
+        // The constraint, the index and the column. The organisations step 2
+        // derived go with the column they were written into — there is nothing to
+        // preserve, because each of them was already implied by the account its row
+        // names.
+        this.addSql(`alter table "newsletter_subscribers" drop constraint if exists "newsletter_subscribers_organization_attribution_chk";`);
+        this.addSql(`drop index if exists "newsletter_subscribers_organization_idx";`);
+        this.addSql(`alter table "newsletter_subscribers" drop column if exists "organization_id";`);
+    }
+}
+//# sourceMappingURL=20260830T212736_newsletter_organization_attribution.js.map

package/dist/migrations/20260830T212736_newsletter_organization_attribution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260830T212736_newsletter_organization_attribution.js","sourceRoot":"","sources":["../../src/migrations/20260830T212736_newsletter_organization_attribution.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6GG;AACH,MAAM,OAAO,yDAA0D,SAAQ,SAAS;IAC7E,KAAK,CAAC,EAAE;QACf,yEAAyE;QACzE,2EAA2E;QAC3E,eAAe;QACf,IAAI,CAAC,MAAM,CAAC,8EAA8E,CAAC,CAAC;QAE5F,0EAA0E;QAC1E,wEAAwE;QACxE,2EAA2E;QAC3E,0DAA0D;QAC1D,IAAI,CAAC,MAAM,CAAC;;;;;;KAMX,CAAC,CAAC;QAEH,qEAAqE;QACrE,0EAA0E;QAC1E,sDAAsD;QACtD,IAAI,CAAC,MAAM,CAAC;;;;;;;;;;;;;;;;;;;;;;KAsBX,CAAC,CAAC;QAEH,qBAAqB;QACrB,IAAI,CAAC,MAAM,CAAC;;;;KAIX,CAAC,CAAC;QAEH,mDAAmD;QACnD,4EAA4E;QAC5E,wEAAwE;QACxE,uEAAuE;QACvE,iEAAiE;QACjE,qEAAqE;QACrE,2EAA2E;QAC3E,yDAAyD;QACzD,0EAA0E;QAC1E,0EAA0E;QAC1E,IAAI,CAAC,MAAM,CAAC;;;KAGX,CAAC,CAAC;IACL,CAAC;IAEQ,KAAK,CAAC,IAAI;QACjB,qEAAqE;QACrE,0EAA0E;QAC1E,4EAA4E;QAC5E,SAAS;QACT,IAAI,CAAC,MAAM,CACT,uHAAuH,CACxH,CAAC;QACF,IAAI,CAAC,MAAM,CAAC,iEAAiE,CAAC,CAAC;QAC/E,IAAI,CAAC,MAAM,CACT,+EAA+E,CAChF,CAAC;IACJ,CAAC;CACF"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"20260903T101752_newsletter_namespace_block_names.d.ts","sourceRoot":"","sources":["../../src/migrations/20260903T101752_newsletter_namespace_block_names.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAmDlD,qBAAa,qDAAsD,SAAQ,SAAS;IACnE,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC;IAOnB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAMrC"}

package/dist/migrations/20260903T101752_newsletter_namespace_block_names.js

@@ -0,0 +1,58 @@
+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 `newsletter`'s 2 `jsonb` columns
+ * — feature 096, T407 (`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_newsletter` 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 `newsletter` because `newsletter` 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_newsletter';
+export class Migration20260903T101752NewsletterNamespaceBlockNames extends Migration {
+    async up() {
+        this.addSql(createRenameFunctionSql(FN, FROZEN_BLOCK_RENAMES));
+        this.addSql(applyRenameFunctionSql(FN, 'newsletter_campaigns', 'content'));
+        this.addSql(applyRenameFunctionSql(FN, 'newsletter_email_blocks', 'content'));
+        this.addSql(dropRenameFunctionSql(FN));
+    }
+    async down() {
+        this.addSql(createRenameFunctionSql(FN, FROZEN_BLOCK_RENAMES_INVERSE));
+        this.addSql(applyRenameFunctionSql(FN, 'newsletter_campaigns', 'content'));
+        this.addSql(applyRenameFunctionSql(FN, 'newsletter_email_blocks', 'content'));
+        this.addSql(dropRenameFunctionSql(FN));
+    }
+}
+//# sourceMappingURL=20260903T101752_newsletter_namespace_block_names.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"20260903T101752_newsletter_namespace_block_names.js","sourceRoot":"","sources":["../../src/migrations/20260903T101752_newsletter_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,+BAA+B,CAAC;AAE3C,MAAM,OAAO,qDAAsD,SAAQ,SAAS;IACzE,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,sBAAsB,EAAE,SAAS,CAAC,CAAC,CAAC;QAC3E,IAAI,CAAC,MAAM,CAAC,sBAAsB,CAAC,EAAE,EAAE,yBAAyB,EAAE,SAAS,CAAC,CAAC,CAAC;QAC9E,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,sBAAsB,EAAE,SAAS,CAAC,CAAC,CAAC;QAC3E,IAAI,CAAC,MAAM,CAAC,sBAAsB,CAAC,EAAE,EAAE,yBAAyB,EAAE,SAAS,CAAC,CAAC,CAAC;QAC9E,IAAI,CAAC,MAAM,CAAC,qBAAqB,CAAC,EAAE,CAAC,CAAC,CAAC;IACzC,CAAC;CACF"}

package/dist/migrations/20260912T125702_newsletter_subscriber_tenant_scope_index.d.ts

@@ -0,0 +1,23 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * The tenant-key index on `newsletter_subscribers.customer_account_id`
+ * (feature 050, research §R5).
+ *
+ * It was created by the platform's frozen
+ * `Migration20260717T134752CoreTenantScopeIndexes` until
+ * `specs/120-migration-closure-bridge-ownership/` Phase 3. Under D-226 the
+ * platform declares no dependencies and so can never name a module's table:
+ * an instance that omits `newsletter` had a frozen corpus indexing a table
+ * nothing builds. `newsletter_subscribers` is this module's own table, so
+ * the closure here is trivial.
+ *
+ * The statement is the frozen one verbatim, `if not exists` and all. A
+ * database that has already applied the frozen migration is offered nothing
+ * from it — the storage keys on the class name and holds no checksum — and
+ * this one is the no-op it already reads as.
+ */
+export declare class Migration20260912T125702NewsletterSubscriberTenantScopeIndex extends Migration {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}
+//# sourceMappingURL=20260912T125702_newsletter_subscriber_tenant_scope_index.d.ts.map

package/dist/migrations/20260912T125702_newsletter_subscriber_tenant_scope_index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260912T125702_newsletter_subscriber_tenant_scope_index.d.ts","sourceRoot":"","sources":["../../src/migrations/20260912T125702_newsletter_subscriber_tenant_scope_index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,4DAA6D,SAAQ,SAAS;IAC1E,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC;IAMnB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAGrC"}

package/dist/migrations/20260912T125702_newsletter_subscriber_tenant_scope_index.js

@@ -0,0 +1,27 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * The tenant-key index on `newsletter_subscribers.customer_account_id`
+ * (feature 050, research §R5).
+ *
+ * It was created by the platform's frozen
+ * `Migration20260717T134752CoreTenantScopeIndexes` until
+ * `specs/120-migration-closure-bridge-ownership/` Phase 3. Under D-226 the
+ * platform declares no dependencies and so can never name a module's table:
+ * an instance that omits `newsletter` had a frozen corpus indexing a table
+ * nothing builds. `newsletter_subscribers` is this module's own table, so
+ * the closure here is trivial.
+ *
+ * The statement is the frozen one verbatim, `if not exists` and all. A
+ * database that has already applied the frozen migration is offered nothing
+ * from it — the storage keys on the class name and holds no checksum — and
+ * this one is the no-op it already reads as.
+ */
+export class Migration20260912T125702NewsletterSubscriberTenantScopeIndex extends Migration {
+    async up() {
+        this.addSql('create index if not exists "newsletter_subscribers_customer_account_id_index" on "newsletter_subscribers" ("customer_account_id");');
+    }
+    async down() {
+        this.addSql('drop index if exists "newsletter_subscribers_customer_account_id_index";');
+    }
+}
+//# sourceMappingURL=20260912T125702_newsletter_subscriber_tenant_scope_index.js.map

package/dist/migrations/20260912T125702_newsletter_subscriber_tenant_scope_index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260912T125702_newsletter_subscriber_tenant_scope_index.js","sourceRoot":"","sources":["../../src/migrations/20260912T125702_newsletter_subscriber_tenant_scope_index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,4DAA6D,SAAQ,SAAS;IAChF,KAAK,CAAC,EAAE;QACf,IAAI,CAAC,MAAM,CACT,oIAAoI,CACrI,CAAC;IACJ,CAAC;IAEQ,KAAK,CAAC,IAAI;QACjB,IAAI,CAAC,MAAM,CAAC,0EAA0E,CAAC,CAAC;IAC1F,CAAC;CACF"}

package/dist/migrations/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 { Migration20260629T200954NewsletterInit } from './20260629T200954_newsletter_init.js';
+import { Migration20260830T212736NewsletterOrganizationAttribution } from './20260830T212736_newsletter_organization_attribution.js';
+import { Migration20260903T101752NewsletterNamespaceBlockNames } from './20260903T101752_newsletter_namespace_block_names.js';
+import { Migration20260912T125702NewsletterSubscriberTenantScopeIndex } from './20260912T125702_newsletter_subscriber_tenant_scope_index.js';
+export declare const migrations: (typeof Migration20260629T200954NewsletterInit)[];
+export { Migration20260629T200954NewsletterInit, Migration20260830T212736NewsletterOrganizationAttribution, Migration20260903T101752NewsletterNamespaceBlockNames, Migration20260912T125702NewsletterSubscriberTenantScopeIndex, };
+//# 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,sCAAsC,EAAE,MAAM,sCAAsC,CAAC;AAC9F,OAAO,EAAE,yDAAyD,EAAE,MAAM,0DAA0D,CAAC;AACrI,OAAO,EAAE,qDAAqD,EAAE,MAAM,uDAAuD,CAAC;AAC9H,OAAO,EAAE,4DAA4D,EAAE,MAAM,+DAA+D,CAAC;AAE7I,eAAO,MAAM,UAAU,mDAKtB,CAAC;AAEF,OAAO,EACL,sCAAsC,EACtC,yDAAyD,EACzD,qDAAqD,EACrD,4DAA4D,GAC7D,CAAC"}

package/dist/migrations/index.js

@@ -0,0 +1,35 @@
+/**
+ * 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 { Migration20260629T200954NewsletterInit } from './20260629T200954_newsletter_init.js';
+import { Migration20260830T212736NewsletterOrganizationAttribution } from './20260830T212736_newsletter_organization_attribution.js';
+import { Migration20260903T101752NewsletterNamespaceBlockNames } from './20260903T101752_newsletter_namespace_block_names.js';
+import { Migration20260912T125702NewsletterSubscriberTenantScopeIndex } from './20260912T125702_newsletter_subscriber_tenant_scope_index.js';
+export const migrations = [
+    Migration20260629T200954NewsletterInit,
+    Migration20260830T212736NewsletterOrganizationAttribution,
+    Migration20260903T101752NewsletterNamespaceBlockNames,
+    Migration20260912T125702NewsletterSubscriberTenantScopeIndex,
+];
+export { Migration20260629T200954NewsletterInit, Migration20260830T212736NewsletterOrganizationAttribution, Migration20260903T101752NewsletterNamespaceBlockNames, Migration20260912T125702NewsletterSubscriberTenantScopeIndex, };
+//# 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,sCAAsC,EAAE,MAAM,sCAAsC,CAAC;AAC9F,OAAO,EAAE,yDAAyD,EAAE,MAAM,0DAA0D,CAAC;AACrI,OAAO,EAAE,qDAAqD,EAAE,MAAM,uDAAuD,CAAC;AAC9H,OAAO,EAAE,4DAA4D,EAAE,MAAM,+DAA+D,CAAC;AAE7I,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,sCAAsC;IACtC,yDAAyD;IACzD,qDAAqD;IACrD,4DAA4D;CAC7D,CAAC;AAEF,OAAO,EACL,sCAAsC,EACtC,yDAAyD,EACzD,qDAAqD,EACrD,4DAA4D,GAC7D,CAAC"}

package/docs/newsletter.md

@@ -0,0 +1,94 @@
+---
+title: newsletter
+description: Own-infrastructure newsletter — subscriber list, tags, segments, one-off campaigns and multi-step automations with per-channel opt-in
+---
+
+# `newsletter`
+
+Own-infrastructure newsletter sending. Lets operators grow a subscriber list,
+segment it with **tags** and **custom fields**, and reach it through one-off
+**campaigns** and multi-step **automations** (linear send/wait sequences).
+Storefront visitors and signed-in customers subscribe with a per-Sales-Channel
+**opt-in** model; every email carries a working unsubscribe link. Content reuses
+the email-safe renderer and `{{var}}/{{if}}/{{for}}` directive engine from the
+`transactional_emails` stack (`@endora-commerce/email-components`). Bulk delivery goes
+through the module's own configurable **sending provider** (an SMTP adapter that
+reaches Amazon SES SMTP, Mailgun, or any relay), independent of the
+transactional-email transport. The whole module can be **enabled/disabled** so
+it never collides with an external ESP (MailerLite, GetResponse, …).
+
+## Concepts
+
+- **Subscriber** — keyed by email (global identity). Status is `pending` →
+  `active` → `unsubscribed` / `deactivated`. Re-submitting an email merges tags
+  and custom fields rather than duplicating. A separate **suppression** list
+  (unsubscribe / bounce / complaint), keyed by email, survives deletion and
+  overrides all targeting.
+- **Opt-in** — per Sales Channel via Settings `newsletter.opt_in_mode`
+  (`single` | `double`). Double opt-in issues a signed, TTL-bounded confirmation
+  link; unconfirmed `pending` subscribers expire after
+  `newsletter.confirm_ttl_hours`.
+- **Tags & custom fields** — operator-defined; tags drive campaign targeting and
+  automation triggers, custom fields enrich subscribers (set via API, Admin UI,
+  or signup) and feed automation criteria.
+- **Campaign** — a one-off send to `all` / a manual `group` / a `tag` / a
+  `tag_list`. Authored in the shared email Page Builder (same palette as
+  transactional emails) with subject + Puck content tree + variables; previewed
+  with sample data; sent now or scheduled.
+- **Automation** — a linear `send` / `wait N days` sequence triggered by
+  all/tag/tag-list. Send steps use the same email Page Builder. The step model
+  is designed to extend to conditional branching later without rework.
+- **Email blocks** — reusable email-safe fragments edited with the same Puck
+  editor and embeddable via `EmailInsertBlock` where configured.
+- **Variables** — newsletter catalogue includes `subscriber.email`,
+  `customFields.*`, `unsubscribeUrl`, `webviewUrl`, `channel.id`, plus branding
+  keys; the admin **Insert variable** picker works on subject and content.
+- **Provider** — selected + configured in the Admin UI; the SMTP password is
+  stored as a Settings `secret` (AES-256-GCM, write-only at the boundary).
+
+## Delivery
+
+Dispatch is queue-backed on Redis/BullMQ:
+
+- `newsletter.campaign.plan` — resolves the audience and **atomically claims** a
+  `newsletter_send_records` row per recipient (`INSERT … ON CONFLICT DO
+  NOTHING`), then enqueues a send job for each freshly-claimed recipient.
+- `newsletter.send` — renders + dispatches one recipient, idempotent on the
+  send-record id (used as the provider `messageId`), throttled by the
+  send-worker rate limiter (`newsletter.rate_limit_per_second`).
+- `newsletter.automation.step` — executes a step; `wait` steps schedule the next
+  step as a BullMQ **delayed job**. A run self-cancels if its subscriber
+  unsubscribes mid-sequence.
+
+Workers run under the separable `worker.ts` entrypoint and pause when the module
+is disabled. Producers only enqueue — never inline-execute — so N≥2 workers
+never double-send.
+
+## Engagement
+
+Open tracking uses a 1×1 pixel; click tracking rewrites links through a signed
+redirect. Per-campaign counts of sent / delivered / failed / opened / clicked
+(plus per-link clicks) are aggregated from `newsletter_send_records` and
+`newsletter_engagement_events`. Tracking can be disabled per campaign.
+
+## Permissions
+
+- `newsletter:read` — view subscribers, campaigns, automations, stats.
+- `newsletter:write` — manage subscribers, campaigns, automations, blocks, and
+  the sending provider.
+
+## Storefront
+
+A reusable signup component (server action, tag-attachable), a double-opt-in
+confirmation landing, an unsubscribe page (optional reason), and an account
+panel showing subscription status + tags with subscribe/unsubscribe actions.
+
+## Schema
+
+Migration `083_newsletter_init.ts` creates `newsletter_subscribers`,
+`newsletter_tags`, `newsletter_subscriber_tags`, `newsletter_custom_fields`,
+`newsletter_suppressions`, `newsletter_email_blocks`(+ channel bridge),
+`newsletter_campaigns`(+ group bridge), `newsletter_send_records`,
+`newsletter_engagement_events`, `newsletter_automations`, and
+`newsletter_automation_runs`. Provider config + opt-in mode live in the
+**Settings** module (no bespoke credential table).

package/i18n/en.json

@@ -0,0 +1,27 @@
+{
+  "actions.openNewsletter.label": "Newsletter",
+  "actions.openNewsletter.description": "Manage newsletter subscribers, campaigns, and automations",
+  "actions.newCampaign.label": "New newsletter campaign",
+  "actions.newCampaign.description": "Create and send a new newsletter campaign",
+  "newsletter.nav.subscribers": "Subscribers",
+  "newsletter.nav.campaigns": "Campaigns",
+  "newsletter.nav.automations": "Automations",
+  "newsletter.nav.tags": "Tags",
+  "newsletter.nav.customFields": "Custom fields",
+  "newsletter.nav.provider": "Sending provider",
+  "newsletter.editor.viewportDesktop": "Desktop mail (600px)",
+  "newsletter.editor.viewportNarrow": "Narrow (320px)",
+  "newsletter.editor.insertVariable": "Insert variable",
+  "newsletter.editor.variable": "Variable",
+  "newsletter.editor.livePreview": "Live HTML preview",
+  "actions.openCampaigns.label": "Newsletter campaigns",
+  "actions.openCampaigns.description": "Newsletter campaigns & sends",
+  "actions.openAutomations.label": "Newsletter automations",
+  "actions.openAutomations.description": "Automated newsletter workflows",
+  "nav.subscribers.label": "Subscribers",
+  "nav.campaigns.label": "Campaigns",
+  "nav.automations.label": "Automations",
+  "nav.tags.label": "Tags & Fields",
+  "nav.blocks.label": "Blocks",
+  "nav.provider.label": "Provider"
+}

package/i18n/pl.json

@@ -0,0 +1,27 @@
+{
+  "actions.openNewsletter.label": "Newsletter",
+  "actions.openNewsletter.description": "Zarządzaj subskrybentami, kampaniami i automatyzacjami newslettera",
+  "actions.newCampaign.label": "Nowa kampania newslettera",
+  "actions.newCampaign.description": "Utwórz i wyślij nową kampanię newslettera",
+  "newsletter.nav.subscribers": "Subskrybenci",
+  "newsletter.nav.campaigns": "Kampanie",
+  "newsletter.nav.automations": "Automatyzacje",
+  "newsletter.nav.tags": "Tagi",
+  "newsletter.nav.customFields": "Pola dodatkowe",
+  "newsletter.nav.provider": "Usługa wysyłki",
+  "newsletter.editor.viewportDesktop": "Mail desktop (600px)",
+  "newsletter.editor.viewportNarrow": "Wąski (320px)",
+  "newsletter.editor.insertVariable": "Wstaw zmienną",
+  "newsletter.editor.variable": "Zmienna",
+  "newsletter.editor.livePreview": "Podgląd HTML na żywo",
+  "actions.openCampaigns.label": "Kampanie newslettera",
+  "actions.openCampaigns.description": "Kampanie newslettera i wysyłki",
+  "actions.openAutomations.label": "Automatyzacje newslettera",
+  "actions.openAutomations.description": "Automatyczne procesy newslettera",
+  "nav.subscribers.label": "Subskrybenci",
+  "nav.campaigns.label": "Kampanie",
+  "nav.automations.label": "Automatyzacje",
+  "nav.tags.label": "Tagi i pola",
+  "nav.blocks.label": "Bloki",
+  "nav.provider.label": "Usługa wysyłki"
+}