@endora-commerce/mod-organizations 0.100.0

package/dist/migrations/20260912T094646_organizations_sales_channel_organizations.js

@@ -0,0 +1,44 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * The `sales_channel_organizations` sales-channel bridge — the organizations a channel is visible to.
+ *
+ * It was created by the platform's frozen `Migration20260430T170044CoreSalesChannelsPromote`
+ * until `specs/120-migration-closure-bridge-ownership/` Phase 2. Under D-226 a
+ * bridge between an always-present near side (`sales_channels`, a kernel table)
+ * and a switchable far side belongs to the far side, so this module creates it:
+ * an instance that does not install `organizations` no longer has a migration corpus
+ * naming a table nothing builds.
+ *
+ * `if not exists`, because every database that has already applied the frozen
+ * migration has this table. The storage keys on the class name and holds no
+ * checksum, so nothing is re-offered there and this migration is the no-op it
+ * reads as; on a fresh database it is the creation.
+ *
+ * The statements are the frozen ones verbatim — same columns, same primary key,
+ * same two foreign keys, same index — so the two paths reach one schema. Its
+ * position needs nothing declared: `sales_channels` is the kernel's and
+ * `organizations` is created inside the frozen prefix, which every
+ * above-watermark migration runs after.
+ */
+export class Migration20260912T094646OrganizationsSalesChannelOrganizations extends Migration {
+    async up() {
+        this.addSql(`
+      create table if not exists "sales_channel_organizations" (
+        "sales_channel_id" uuid not null,
+        "organization_id" uuid not null,
+        constraint "sales_channel_organizations_pkey"
+          primary key ("sales_channel_id", "organization_id"),
+        constraint "sales_channel_organizations_channel_fk"
+          foreign key ("sales_channel_id") references "sales_channels" ("id") on delete cascade,
+        constraint "sales_channel_organizations_organization_fk"
+          foreign key ("organization_id") references "organizations" ("id") on delete cascade
+      );
+    `);
+        this.addSql('create index if not exists "sales_channel_organizations_organization_id_index" ' +
+            'on "sales_channel_organizations" ("organization_id");');
+    }
+    async down() {
+        this.addSql('drop table if exists "sales_channel_organizations" cascade;');
+    }
+}
+//# sourceMappingURL=20260912T094646_organizations_sales_channel_organizations.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"20260912T094646_organizations_sales_channel_organizations.js","sourceRoot":"","sources":["../../src/migrations/20260912T094646_organizations_sales_channel_organizations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,OAAO,8DAA+D,SAAQ,SAAS;IAClF,KAAK,CAAC,EAAE;QACf,IAAI,CAAC,MAAM,CAAC;;;;;;;;;;;KAWX,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CACT,iFAAiF;YAC/E,uDAAuD,CAC1D,CAAC;IACJ,CAAC;IAEQ,KAAK,CAAC,IAAI;QACjB,IAAI,CAAC,MAAM,CAAC,6DAA6D,CAAC,CAAC;IAC7E,CAAC;CACF"}

package/dist/migrations/index.d.ts

@@ -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 orders **this module's own** migrations
+ * and nothing else (feature 081). Where the block sits relative to every other
+ * module's is decided by the manifest `dependencies` graph.
+ *
+ * The **named** exports stay, and the asymmetry with `./backend` — which
+ * publishes an array and no entity class by name (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 { Migration20260424T205317OrganizationsInit } from './20260424T205317_organizations_init.js';
+import { Migration20260425T051700OrganizationsInvitationsInit } from './20260425T051700_organizations_invitations_init.js';
+import { Migration20260611T140349OrganizationsConsolidation } from './20260611T140349_organizations_consolidation.js';
+import { Migration20260611T140358OrganizationsOrgOrderConfirmationEmails } from './20260611T140358_organizations_org_order_confirmation_emails.js';
+import { Migration20260611T140402OrganizationsOrgFulfilmentStrategy } from './20260611T140402_organizations_org_fulfilment_strategy.js';
+import { Migration20260717T151403OrganizationsPersonalOrganizations } from './20260717T151403_organizations_personal_organizations.js';
+import { Migration20260718T200340OrganizationsOrganizationCustomFieldValues } from './20260718T200340_organizations_organization_custom_field_values.js';
+import { Migration20260720T044254OrganizationsOrgHierarchy } from './20260720T044254_organizations_org_hierarchy.js';
+import { Migration20260912T094646OrganizationsSalesChannelOrganizations } from './20260912T094646_organizations_sales_channel_organizations.js';
+export declare const migrations: (typeof Migration20260424T205317OrganizationsInit)[];
+export { Migration20260424T205317OrganizationsInit, Migration20260425T051700OrganizationsInvitationsInit, Migration20260611T140349OrganizationsConsolidation, Migration20260611T140358OrganizationsOrgOrderConfirmationEmails, Migration20260611T140402OrganizationsOrgFulfilmentStrategy, Migration20260717T151403OrganizationsPersonalOrganizations, Migration20260718T200340OrganizationsOrganizationCustomFieldValues, Migration20260720T044254OrganizationsOrgHierarchy, Migration20260912T094646OrganizationsSalesChannelOrganizations, };
+//# 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,yCAAyC,EAAE,MAAM,yCAAyC,CAAC;AACpG,OAAO,EAAE,oDAAoD,EAAE,MAAM,qDAAqD,CAAC;AAC3H,OAAO,EAAE,kDAAkD,EAAE,MAAM,kDAAkD,CAAC;AACtH,OAAO,EAAE,+DAA+D,EAAE,MAAM,kEAAkE,CAAC;AACnJ,OAAO,EAAE,0DAA0D,EAAE,MAAM,4DAA4D,CAAC;AACxI,OAAO,EAAE,0DAA0D,EAAE,MAAM,2DAA2D,CAAC;AACvI,OAAO,EAAE,kEAAkE,EAAE,MAAM,qEAAqE,CAAC;AACzJ,OAAO,EAAE,iDAAiD,EAAE,MAAM,kDAAkD,CAAC;AACrH,OAAO,EAAE,8DAA8D,EAAE,MAAM,gEAAgE,CAAC;AAEhJ,eAAO,MAAM,UAAU,sDAUtB,CAAC;AAEF,OAAO,EACL,yCAAyC,EACzC,oDAAoD,EACpD,kDAAkD,EAClD,+DAA+D,EAC/D,0DAA0D,EAC1D,0DAA0D,EAC1D,kEAAkE,EAClE,iDAAiD,EACjD,8DAA8D,GAC/D,CAAC"}

package/dist/migrations/index.js

@@ -0,0 +1,45 @@
+/**
+ * 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 orders **this module's own** migrations
+ * and nothing else (feature 081). Where the block sits relative to every other
+ * module's is decided by the manifest `dependencies` graph.
+ *
+ * The **named** exports stay, and the asymmetry with `./backend` — which
+ * publishes an array and no entity class by name (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 { Migration20260424T205317OrganizationsInit } from './20260424T205317_organizations_init.js';
+import { Migration20260425T051700OrganizationsInvitationsInit } from './20260425T051700_organizations_invitations_init.js';
+import { Migration20260611T140349OrganizationsConsolidation } from './20260611T140349_organizations_consolidation.js';
+import { Migration20260611T140358OrganizationsOrgOrderConfirmationEmails } from './20260611T140358_organizations_org_order_confirmation_emails.js';
+import { Migration20260611T140402OrganizationsOrgFulfilmentStrategy } from './20260611T140402_organizations_org_fulfilment_strategy.js';
+import { Migration20260717T151403OrganizationsPersonalOrganizations } from './20260717T151403_organizations_personal_organizations.js';
+import { Migration20260718T200340OrganizationsOrganizationCustomFieldValues } from './20260718T200340_organizations_organization_custom_field_values.js';
+import { Migration20260720T044254OrganizationsOrgHierarchy } from './20260720T044254_organizations_org_hierarchy.js';
+import { Migration20260912T094646OrganizationsSalesChannelOrganizations } from './20260912T094646_organizations_sales_channel_organizations.js';
+export const migrations = [
+    Migration20260424T205317OrganizationsInit,
+    Migration20260425T051700OrganizationsInvitationsInit,
+    Migration20260611T140349OrganizationsConsolidation,
+    Migration20260611T140358OrganizationsOrgOrderConfirmationEmails,
+    Migration20260611T140402OrganizationsOrgFulfilmentStrategy,
+    Migration20260717T151403OrganizationsPersonalOrganizations,
+    Migration20260718T200340OrganizationsOrganizationCustomFieldValues,
+    Migration20260720T044254OrganizationsOrgHierarchy,
+    Migration20260912T094646OrganizationsSalesChannelOrganizations,
+];
+export { Migration20260424T205317OrganizationsInit, Migration20260425T051700OrganizationsInvitationsInit, Migration20260611T140349OrganizationsConsolidation, Migration20260611T140358OrganizationsOrgOrderConfirmationEmails, Migration20260611T140402OrganizationsOrgFulfilmentStrategy, Migration20260717T151403OrganizationsPersonalOrganizations, Migration20260718T200340OrganizationsOrganizationCustomFieldValues, Migration20260720T044254OrganizationsOrgHierarchy, Migration20260912T094646OrganizationsSalesChannelOrganizations, };
+//# 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,yCAAyC,EAAE,MAAM,yCAAyC,CAAC;AACpG,OAAO,EAAE,oDAAoD,EAAE,MAAM,qDAAqD,CAAC;AAC3H,OAAO,EAAE,kDAAkD,EAAE,MAAM,kDAAkD,CAAC;AACtH,OAAO,EAAE,+DAA+D,EAAE,MAAM,kEAAkE,CAAC;AACnJ,OAAO,EAAE,0DAA0D,EAAE,MAAM,4DAA4D,CAAC;AACxI,OAAO,EAAE,0DAA0D,EAAE,MAAM,2DAA2D,CAAC;AACvI,OAAO,EAAE,kEAAkE,EAAE,MAAM,qEAAqE,CAAC;AACzJ,OAAO,EAAE,iDAAiD,EAAE,MAAM,kDAAkD,CAAC;AACrH,OAAO,EAAE,8DAA8D,EAAE,MAAM,gEAAgE,CAAC;AAEhJ,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,yCAAyC;IACzC,oDAAoD;IACpD,kDAAkD;IAClD,+DAA+D;IAC/D,0DAA0D;IAC1D,0DAA0D;IAC1D,kEAAkE;IAClE,iDAAiD;IACjD,8DAA8D;CAC/D,CAAC;AAEF,OAAO,EACL,yCAAyC,EACzC,oDAAoD,EACpD,kDAAkD,EAClD,+DAA+D,EAC/D,0DAA0D,EAC1D,0DAA0D,EAC1D,kEAAkE,EAClE,iDAAiD,EACjD,8DAA8D,GAC/D,CAAC"}

package/dist/ports/index.d.ts

@@ -0,0 +1,53 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+/**
+ * The one co-transactional seam this module publishes (D-178, under D-78
+ * point 2).
+ *
+ * It is declared here rather than in `@endora-commerce/contracts` for the same
+ * reason `credit_limits`' `CreditLimitPort` and `promotions`'
+ * `PromotionUsageFinalizer` are: its signature carries the caller's MikroORM
+ * `EntityManager`, and FR-034 keeps a MikroORM type out of that package. A
+ * branded stand-in would publish the coupling instead of removing it, which
+ * D-78 refuses in writing.
+ *
+ * **What holds it co-transactional is a foreign key, not a convention.**
+ * `customer_accounts_organization_fk` (`on delete restrict`) points
+ * `customer_accounts.organization_id` at `organizations.id`, and since D-178
+ * that column is `NOT NULL`. So the account row cannot be inserted before the
+ * organisation exists, and a second transaction cannot satisfy a foreign key
+ * against a row it cannot see. The two writes are one unit of work or the
+ * invariant has a window in it — which is precisely the window D-178 was taken
+ * to close: `createStandalone` used to commit the account with a null
+ * organisation and provision the organisation afterwards, and nothing retried
+ * the second half.
+ *
+ * `customer_accounts` is the caller and it already declares `organizations` in
+ * its manifest `dependencies` — the tenancy direction feature 051 established —
+ * so the edge this seam needs is the one the foreign key already required.
+ */
+export interface PersonalOrganizationProvisionInput {
+    /**
+     * The id the account **will** carry. It is generated by the caller before the
+     * account row exists, because the personal organisation's `taxId` is derived
+     * from it and that derivation is what makes the provisioning re-runnable.
+     */
+    readonly customerAccountId: string;
+    readonly email: string;
+    readonly firstName?: string | null;
+    readonly lastName?: string | null;
+}
+export interface PersonalOrganizationProvisionApi {
+    /**
+     * Find-or-create the personal organisation for an account that is about to be
+     * written, on the caller's `EntityManager` and inside the caller's
+     * transaction. Writes nothing on `customer_accounts`: the membership column is
+     * the caller's own, and it sets it on the row it is inserting.
+     *
+     * Idempotent by `taxId`, so a retry after a rolled-back attempt re-finds
+     * rather than duplicating.
+     */
+    provisionFor(em: EntityManager, input: PersonalOrganizationProvisionInput): Promise<{
+        id: string;
+    }>;
+}
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ports/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,kCAAkC;IACjD;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,gCAAgC;IAC/C;;;;;;;;OAQG;IACH,YAAY,CACV,EAAE,EAAE,aAAa,EACjB,KAAK,EAAE,kCAAkC,GACxC,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC5B"}

package/dist/ports/index.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.js.map

package/dist/ports/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ports/index.ts"],"names":[],"mappings":""}

package/docs/organization-hierarchy.md

@@ -0,0 +1,117 @@
+---
+title: Organization hierarchy
+---
+
+# Organization hierarchy
+
+Organizations can be nested into a **tree**: a head-office organization owns
+branch organizations, which may own sub-branches. Two things flow along the
+tree — **scope** (a roll-up-enabled parent-org user or scoped sales-rep sees the
+whole subtree) and **commercial terms** (a descendant with no own price list or
+credit limit resolves the nearest ancestor's).
+
+This is an additive layer over the flat organization model. Every organization
+starts as a **root** (no parent), and a flat installation behaves byte-for-byte
+as it did before the hierarchy existed.
+
+## The tree
+
+Each organization records a nullable self-referential `parent_id` (NULL ⇒ root)
+plus a server-maintained materialized `path` (`/<rootId>/…/<thisId>/`). A single
+indexed prefix scan answers "descendants of X" and "ancestors of X" — there is
+no per-node walk.
+
+- **Assign / move a parent** — `POST /api/v1/admin/organizations/:id/parent`
+  with `{ "parentId": "<uuid>" | null }`. `null` detaches the organization back
+  to a root. The move is validated against **cycles** (a node may not become a
+  child of its own descendant) and a **maximum depth of 10 levels**, and is
+  audited through the Command Bus (`organization.set_parent` / `organization.move`,
+  both reversible).
+- **Read the subtree** — `GET /api/v1/admin/organizations/:id/subtree` returns
+  the descendants (including the node itself) pre-order, each as
+  `{ id, name, parentId, depth, status }`.
+- **Read the ancestor chain** — `GET /api/v1/admin/organizations/:id/ancestors`
+  returns the parent → … → root chain, nearest-first.
+- **Deletion is blocked** — an organization with any child cannot be deleted
+  (`409 has_children`), backed by the `parent_id … ON DELETE RESTRICT` foreign
+  key. Reassign or remove the children first.
+
+Re-parenting is **retroactive**: subtree membership, roll-up visibility, and
+term inheritance are always computed against the *current* tree, so after a move
+a branch's history becomes visible to the new parent's roll-up users and it
+inherits the new parent's terms.
+
+The admin UI exposes a parent picker plus a subtree/ancestor view on the
+organization detail page.
+
+## Roll-up scope
+
+Visibility across descendants is **permission-gated** by the
+`organizations:rollup` capability ("Act across organization descendants").
+
+- A **scoped sales-rep** holding the capability has each assignment expanded to
+  the assigned node's subtree. A descendant that carries its **own** assignment
+  overrides the inherited one for its subtree — the **nearest assignment on the
+  ancestor chain wins**. Without the capability the rep stays confined to the
+  organizations directly assigned to them.
+- A branch-only user (no roll-up) sees only their own organization.
+
+Expansion is derived **server-side** and widens the existing tenant-scope guard
+(`allowedOrganizationIds`) to exactly the subtree — never a sibling, cousin, or
+an ancestor outside the granted node. An out-of-subtree record is
+indistinguishable from "does not exist". The three admin read surfaces — orders,
+quotes, and customers — read the already-widened scope and need no change of
+their own.
+
+## Term inheritance
+
+A descendant with no own commercial term resolves the nearest ancestor's.
+
+### Price lists
+
+Price lists target organizations through their application rule (there is no
+organization foreign key). The resolver builds the org candidate set as
+`[thisOrg, …ancestors]` (nearest-first) and keeps the existing priority order
+(`organization` > `customerGroup` > `category` > `salesChannel`):
+
+- a list naming a **nearer** organization outranks one naming a farther
+  ancestor, so a **branch override always wins**;
+- an inherited ancestor org-named list still outranks a customer-group,
+  category, or sales-channel list;
+- a branch with no own list falls through to the nearest ancestor's org-named
+  list before dropping to the non-org priority levels.
+
+Only that branch diverges — siblings are unaffected. Resolution stays a single
+pass (no per-ancestor re-run).
+
+### Credit limits
+
+A descendant with no own credit limit transacts against the **nearest
+ancestor** that has one. How the ancestor's limit is consumed is a
+**per-organization mode**, set only by a platform administrator:
+
+- **`shared_pool`** — every organization in the subtree draws against one shared
+  pool on the owning ancestor's row. Concurrent draws serialize on that row, so
+  the pool can never be over-spent (no double-spend).
+- **`independent_default`** — the inherited amount is each branch's own limit;
+  every branch may draw the full inherited amount independently of its siblings.
+
+A branch with its **own** credit limit overrides the inherited one.
+
+#### The credit-inheritance-mode setting
+
+The factory default is the platform-wide Settings value
+`organizations.hierarchy.credit_inheritance_mode` (default **`shared_pool`**). A
+per-organization override is stored on the organization and set via
+`PUT /api/v1/admin/organizations/:id/credit-inheritance-mode` with
+`{ "mode": "shared_pool" | "independent_default" | null }` (`null` falls back to
+the Settings default). This endpoint is **platform-admin only** — a scoped or
+roll-up actor is rejected with `403` — and the change is audited
+(`organization.set_credit_mode`).
+
+## Flat-behavior guarantee
+
+For a root organization the subtree is `{itself}`, the price-list org chain is
+`[itself]`, and the credit owner is the organization itself (or none). All
+scope, pricing, and credit resolution therefore collapse to the pre-feature
+single-organization behavior, byte-for-byte.

package/docs/organizations.md

@@ -0,0 +1,312 @@
+---
+title: organizations
+description: Customer Organizations, registration, invitations
+---
+
+# `organizations`
+
+Customer Organizations — registration, email verification, member management,
+invitations, and the suspension state. The first user of a registering
+Organization becomes its `organization_admin`.
+
+## Public surface
+
+Org-Admin-only routes are enforced server-side via the
+`assertOrganizationAdmin` helper. Admin routes (`/api/v1/admin/*`) are
+gated by `customers:manage`.
+
+| Verb + Path | Audience | Purpose |
+| --- | --- | --- |
+| `POST /api/v1/organizations/register` | anon | Register Org + first member, email verification dispatched |
+| `POST /api/v1/auth/email-verification/verify` | anon | Redeem verification token |
+| `POST /api/v1/auth/customer/login` | anon | Customer login → sets `b2b_session` cookie; merges anonymous cart |
+| `POST /api/v1/auth/customer/logout` | customer | Destroy session |
+| `POST /api/v1/auth/password-reset/request` | anon | Always 202 (defends against account enumeration) |
+| `POST /api/v1/auth/password-reset/confirm` | anon | Redeem the emailed reset token |
+| `GET /api/v1/me` | customer | Current customer + their organization, plus `impersonation: { impersonatorAdminUserId }` when an admin is acting as the buyer |
+| `POST /api/v1/me/password` | customer | Change password (rejects wrong `currentPassword`) |
+| `GET /api/v1/organizations/mine/members` | org admin | List members |
+| `DELETE /api/v1/organizations/mine/members/:id` | org admin | Remove member (last-admin guard) |
+| `PATCH /api/v1/organizations/mine/members/:id/role` | org admin | Promote / demote (last-admin guard) |
+| `GET /api/v1/organizations/mine/invitations` | org admin | List pending invitations |
+| `POST /api/v1/organizations/mine/invitations` | org admin | Invite a new user; emails the redemption link via the injected Mailer |
+| `DELETE /api/v1/organizations/mine/invitations/:id` | org admin | Revoke a pending invitation |
+| `POST /api/v1/organizations/invitations/:token/accept` | anon | Redeem invitation, mint Customer Account |
+| `GET /api/v1/organizations/mine/addresses` | customer | List delivery / billing addresses |
+| `POST /api/v1/organizations/mine/addresses` | customer | Create address |
+| `PATCH /api/v1/organizations/mine/addresses/:id` | customer | Update |
+| `DELETE /api/v1/organizations/mine/addresses/:id` | customer | Remove |
+| `GET /api/v1/admin/organizations` | admin | List with `filter[status]` / `filter[vatStatus]` / `q` |
+| `GET /api/v1/admin/organizations/:id` | admin | Org + member roster (`updatedAt`, members include `lastLoginAt`) |
+| `PATCH /api/v1/admin/organizations/:id` | admin | Update name / `status` / `vatStatus`; optional `expectedUpdatedAt` → `409 VERSION_CONFLICT` when stale |
+| `POST /api/v1/admin/organizations/:id/members/invite` | admin | Invite by email + role (platform-scope) |
+| `POST /api/v1/admin/organizations/:id/members` | admin | Direct-create member with password |
+| `PATCH /api/v1/admin/organizations/:id/members/:customerAccountId/role` | admin | Change role; optional `expectedUpdatedAt` per member |
+| `DELETE /api/v1/admin/organizations/:id/members/:customerAccountId` | admin | Soft-remove member (last-admin guard) |
+| `POST /api/v1/admin/organizations/:id/recover-admin-access` | admin | Break-glass — promote existing member to `organization_admin` |
+
+Configure **`SMTP_URL`** in the backend environment so outbound mail uses SMTP instead of the console logger.
+
+## Entities
+
+`Organization`, `OrganizationInvitation`, `EmailVerificationToken`. Tax-ID
+uniqueness is enforced at the DB level; duplicate registrations return
+`409 ORGANIZATION_TAX_ID_EXISTS`.
+
+## Events emitted
+
+`organization.registered.v1`, `organization.verified.v1`,
+`organization.suspended.v1`, `organization.member_invited.v1`,
+`organization.member_role_changed.v1`.
+
+## Extension points
+
+- **Verification dispatch** — `email-verification-service.ts` exposes a
+  pluggable mailer interface; swap the dev-mode console mailer for a real
+  SMTP/SendGrid driver in production composition.
+- **Last-admin guard** — codified in `role-service.ts#changeRole` and
+  `invitation-service.ts#revoke`; add new "must keep at least one admin"
+  call sites here.
+
+## Commercial party and moderation
+
+Organization is a first-class commercial party. This section describes
+the runtime surface.
+
+### Lifecycle status (`pending_verification` → `active` → `blocked` / `rejected`)
+
+Every newly-registered Organization starts in `pending_verification`. The
+platform-wide setting `organizations.moderation.mode` (`manual` /
+`auto`) controls whether an admin must approve manually before the
+Organization can transact. While the status is anything other than
+`active`, the platform refuses Order placement, RFQ submission, and
+cart-line addition with HTTP 423.
+
+The legacy `suspended` status was renamed to `blocked` by migration 047
+with an audit-log breadcrumb on every remapped row.
+
+Admin endpoints:
+
+| Verb + Path | Purpose |
+| --- | --- |
+| `POST /api/v1/admin/organizations/:id/approve` | Transition `pending_verification` → `active` |
+| `POST /api/v1/admin/organizations/:id/reject` | Transition `pending_verification` → `rejected` (terminal) |
+| `POST /api/v1/admin/organizations/:id/block` | Transition `active` → `blocked` (operator lever) |
+| `POST /api/v1/admin/organizations/:id/unblock` | Transition `blocked` → `active` |
+
+Every body carries `expectedVersion: number` (optimistic-lock token from
+the `organizations.version` column) and is wrapped in
+`em.transactional`. A stale `expectedVersion` returns `409
+VERSION_CONFLICT` with the `currentVersion` in the body. A status guard
+violation (e.g. approving an already-active org) returns `422
+VALIDATION_FAILED`.
+
+Customer-side gate: the storefront receives the localized
+"why-you-can't-transact" message via `GET /api/v1/me`'s
+`organization.canTransact` + `organization.moderationMessage` fields.
+The cart and checkout pages render `<OrganizationModerationBanner>`
+above the form when `canTransact === false`.
+
+### Admin notifications
+
+A small `admin_notifications` module owns the bell surface. On every
+new Organization registration, `OrgRegistrationNotifier` writes one
+broadcast notification (`audience='all_admins'`,
+`kind='organization.registered'`) and dispatches one e-mail per entry
+in the `organizations.notifications.new_registration_recipients`
+setting. The bell polls every 30 s via
+`GET /api/v1/admin/notifications`.
+
+| Verb + Path | Purpose |
+| --- | --- |
+| `GET /api/v1/admin/notifications` | Paged feed, per-admin `isRead` resolution |
+| `POST /api/v1/admin/notifications/:id/read` | Mark one entry read |
+| `POST /api/v1/admin/notifications/mark-all-read` | Mark every visible entry read |
+
+### Per-organization commercial scoping
+
+Three allow-list bridges control what an Organization may use at
+checkout:
+
+- `organization_payment_methods` (pivot: `(organization_id, payment_method_id)`)
+- `organization_delivery_methods` (pivot: `(organization_id, delivery_method_id)`)
+- `organization_warehouses` (pivot: `(organization_id, warehouse_id)`)
+
+**Empty list ⇒ platform defaults apply.** A non-empty list filters the
+storefront `GET /api/v1/payment-methods`, `GET /api/v1/delivery-methods`,
+and inventory stock-figure endpoints intersected with the caller's
+Organization assignment.
+
+Admin endpoints:
+
+| Verb + Path | Purpose |
+| --- | --- |
+| `GET /api/v1/admin/organizations/:id/restrictions` | Read all three allow-lists + the org's `version` |
+| `PUT /api/v1/admin/organizations/:id/restrictions` | Atomic replace of all three |
+| `PATCH .../restrictions/payment-methods` | Surgical `{ add?, remove? }` |
+| `PATCH .../restrictions/delivery-methods` | Same |
+| `PATCH .../restrictions/warehouses` | Same |
+
+Storefront preflight:
+
+| Verb + Path | Purpose |
+| --- | --- |
+| `POST /api/v1/storefront/checkout/preflight` | Returns `{ canTransact, allowedPaymentMethodIds, allowedDeliveryMethodIds, assignedWarehouseIds }` or 423 when the org cannot transact |
+
+### Applicable price lists + promotion targeting
+
+`OrganizationEffectivePriceListsService.listApplicable(orgId)` reuses
+the existing `application-rule-evaluator` from the `price_lists` module
+to compute every Price List that currently applies to the Organization,
+each tagged with a `reasons[]` array
+(`direct_organization_match` / `customer_group_match` /
+`sales_channel_inheritance` / `segment_rule_match`). Surfaced at
+`GET /api/v1/admin/organizations/:id/applicable-price-lists` and
+rendered as a read-only table in the admin Organization detail page.
+
+Promotions: when a promotion targets a specific Organization
+(`promotions.organization_id` is set), the platform applies the rule
+only when the cart's Organization is `active`. The check is wired
+through `PromotionService`'s optional `resolveOrganizationStatus`
+constructor argument; composition.ts passes a raw SQL lookup.
+
+### Sales-rep ownership
+
+`organization_sales_rep_assignments` (pivot: `(organization_id,
+admin_user_id)`) binds sales reps to organizations. When the
+caller's admin role is `sales_representative`, the admin Orders list
+and RFQ list are filtered to the orgs the rep owns. Platform admins
+see everything.
+
+Three endpoints maintain the relation, and this module owns and
+registers all three:
+
+| Verb + Path | Purpose |
+| --- | --- |
+| `GET /api/v1/admin/organizations/:id/sales-reps` | List the reps assigned to an organization. |
+| `POST /api/v1/admin/organizations/:id/sales-reps` | Assign a rep. |
+| `DELETE /api/v1/admin/organizations/:id/sales-reps/:adminUserId` | Remove an assignment. |
+
+They are gated by `organizations:assign-sales-rep`. Until 2026-08 they
+were registered by the quote-requests module and gated by
+`rfqs:handle`, which meant switching quote requests off also removed
+the ability to assign a sales representative — and the code gating
+the screen disappeared from the roles matrix with it. Assigning a rep
+qualifies an organization, so it belongs here, with a code this
+module declares. The one endpoint that stayed behind is the reverse
+listing, `GET /api/v1/admin/sales-reps/:adminUserId/organizations`:
+it reports how many quote requests are open per organization, which
+is that module's fact.
+
+Other modules read the relation through this module's
+`organizationSalesRepScopePort`, never by querying the pivot.
+
+### VAT-ID / NIP validation
+
+Two production HTTP clients implement the `VatValidator` port:
+
+- `ViesClient` → `POST` against the VIES REST endpoint
+  (`/check-vat-number`). 5-second timeout; single abort on network
+  error.
+- `MinisterstwoFinansowClient` → `GET` against `wl-api.mf.gov.pl/api/search/nip/{nip}`.
+  In-process 10-rps throttle; 7-day cache key on `(nip, today)` is
+  baked into the service-side `OrganizationTaxIdValidation` history
+  (one row per attempt).
+
+`OrganizationTaxIdValidationService` auto-picks the provider per
+tax-id prefix (Polish 10-digit → MF; other ISO-2 prefix → VIES;
+anything else → format-only). When `applyAutoFill=true` AND the
+result is `validated`, the org's `legalName` is updated and `version`
+bumps so the next admin edit honors the optimistic-lock.
+
+All adapters degrade safely on provider outage:
+`outcome: 'deferred'`. The org save never fails because of a
+third-party hiccup.
+
+| Verb + Path | Purpose |
+| --- | --- |
+| `POST /api/v1/admin/organizations/:id/vat-validations` | Trigger one validation attempt (`providerHint`, `applyAutoFill`) |
+| `GET /api/v1/admin/organizations/:id/vat-validations` | History list, newest first |
+
+### Picker primitive + diacritic-insensitive search
+
+The admin app ships a reusable `<OrganizationPicker>` (single-select)
+and `<OrganizationPickerMulti>` (multi-select) on top of the existing
+`<Combobox>`. They consume `GET /api/v1/admin/organizations?q=` whose
+`q` parameter is diacritic-insensitive: a query of `lodz` finds
+"Bauhaus Łódź" via the denormalized `name_search` column populated
+by the Organization entity's `@BeforeCreate` / `@BeforeUpdate` hooks.
+`normalizeOrganizationName` is that fold plus the whitespace policy the
+column needs. The fold itself is `foldDiacritics`
+(`packages/contracts/src/text-normalization.ts`), shared with the admin
+panel: NFD decomposition, a strip of the combining
+marks, then an explicit table for the precomposed Latin letters NFD
+doesn't split (`ł`/`Ł`, `ø`/`Ø`, `đ`/`Đ`, `ð`/`Ð`, `þ`/`Þ`, `ß`, `æ`,
+`œ`). Changing that table re-folds new rows differently from old ones,
+so it is a migration of `name_search`, not an edit.
+
+### New settings (declared on the manifest)
+
+| Code | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `organizations.moderation.mode` | `string` enum | `'manual'` | `manual` ⇒ pending_verification; `auto` ⇒ active on registration |
+| `organizations.notifications.new_registration_recipients` | `json` array | `[]` | E-mail recipients for new-Organization notifications |
+
+### Migrations
+
+- `047_organizations_consolidation.ts` — adds `legal_name`, VAT-validation
+  columns, blocked / rejected / approved audit columns, `version`
+  optimistic-lock, `name_search` denormalized column, three allow-list
+  bridges, the validation-history table, the `organizations_name_search_idx`
+  B-Tree index, and remaps every `suspended` row to `blocked`.
+- `048_admin_notifications_init.ts` — adds the `admin_notifications`
+  table + the per-admin `admin_notification_reads` bridge.
+- `049_customer_accounts_organization_optional.ts` — relaxed
+  `customer_accounts.organization_id` to nullable so guest-style
+  Customer accounts were representable. **That design is
+  dead**: personal organizations replaced it and the column was re-tightened — see
+  `customer_accounts`' `20260825T141659_customer_accounts_organization_required`.
+- `089_personal_organizations.ts` — adds `organizations.is_personal`
+  and backfills a personal organization for every pre-existing no-org
+  customer account (see "Personal organizations" below).
+
+### Personal organizations (B2C)
+
+The Organization is the platform's single tenant concept. A B2C /
+individual customer is **not** a null-org special case: every standalone
+customer registration provisions a single-member **personal
+organization** (`is_personal = true`). The organization and the
+account are written **in one transaction**, by the module that owns the account
+row, on both paths that create one — self-registration and federated sign-in.
+This means:
+
+- **Transacting works unchanged.** `organization_id` is `NOT NULL`,
+  so ordering, RFQs, credit, invoices and addresses need no null-org path — and
+  the column, not a guard, is what refuses one: MikroORM applies its tenant
+  filter to `SELECT` / `UPDATE` / `DELETE` and not to `INSERT`.
+- **Isolation is structural.** The tenant guard isolates each
+  personal org as its own tenant — two B2C customers can never see each
+  other's data, with zero null-org special-casing.
+- **Individual defaults.** `status = active`, `vat_status = vat_exempt`,
+  `name` from the customer's name (falling back to the email local-part),
+  and a synthetic 32-hex `tax_id` derived from the account id (the column
+  is globally `UNIQUE`; an individual has no company tax id).
+- **Invisible in B2B admin.** Personal orgs are excluded by default from
+  the admin org list/pickers, cannot receive a sales rep, and never enter
+  the moderation queue (they are created `active`). The admin org list
+  accepts `?includePersonal=true` to surface them when needed.
+- **Per-channel gate.** Standalone (B2C) registration is controlled per
+  sales channel by the `customers.allow_registration_without_organization`
+  setting; a B2B-only channel refuses the registration and provisions
+  nothing. The setting's name is a leftover from an earlier design — what it
+  gates is registration outside a *company* organization, not registration
+  without one.
+- **Detaching a member from a company moves them here.** The admin
+  `DELETE /api/v1/admin/customers/:id/organization` used to write
+  `organization_id = NULL`; it now provisions (or re-finds) the
+  customer's own personal organization and moves them into it, keeping the
+  `customer_account.organization_unassigned` audit verb.
+
+Company (B2B) organizations are unaffected — the single-member invariant
+(`assertMembershipAllowed`) only rejects adding a second member to a
+personal org.