@endora-commerce/mod-sales-channels 0.100.0

package/docs/sales_channels/index.md

@@ -0,0 +1,95 @@
+---
+title: Sales Channels
+sidebar_label: Sales channels
+sidebar_position: 1
+description: Channel registry, request resolver, bidirectional membership for every channel-scoped entity
+---
+
+# Sales Channels
+
+The Sales Channels module is the platform's stable handle for "where the sale happens". Every channel-scoped piece of platform data — products, categories, customers, orders, quotes, prices, promotions, CMS pages — is bound to one or more Sales Channels and is filtered through the channel context of the incoming request. The module owns the channel registry, the bidirectional membership service, the resolver middleware that maps every HTTP request onto exactly one channel, and the lifecycle guards that keep the platform from ending up with channel-less data.
+
+## Concepts
+
+- **Sales Channel** — a named place of sale (web storefront, marketplace, brick-and-mortar location, distributor portal). Carries a unique `code`, a multilingual display name, an optional logo and theme code, an ordered list of supported languages with a default, an ordered list of supported currencies with a default, and an `active` flag. Exactly one channel platform-wide carries `system_default = true` (enforced by a partial unique index).
+
+- **System default channel** — the bootstrap channel created by the boot-time reconciler. It is the implicit owner of every channel-scoped entity created without an explicit channel selection. It is non-deletable and non-deactivatable. The env var `DEFAULT_SALES_CHANNEL_CODE` (default `default`) names the channel.
+
+- **Membership** — the M:N relationship between a channel and a channel-scoped entity. Nine entity types are tracked: `product`, `category`, `payment-method`, `delivery-method`, `organization`, `tax`, `customer`, `promotion`, `cms-page`. (`inventory-location` is reserved for when the inventory module introduces that table.)
+
+- **Attribution** — the M:1 relationship for Orders and Quote Requests. Each row is bound to exactly one channel at placement, and the binding is immutable for audit purposes.
+
+- **At-least-one-channel invariant** — every channel-scoped entity is bound to at least one channel at all times. Removing the last membership of an entity is refused unless the caller passes `fallbackToDefault=true`, in which case the entity is rebound to the system default in the same transaction.
+
+## Resolver — request → channel
+
+A Fastify `onRequest` hook runs on every `/api/v1/*` request and resolves it to exactly one channel. Resolution order:
+
+1. **`X-Sales-Channel: <code>` header** — explicit signal, always wins.
+2. **`?salesChannel=<code>` query parameter** — storefront / integration paths only; ignored on `/api/v1/admin/*` to prevent cross-channel admin bleed.
+3. **Host-based mapping** — env-configured `SALES_CHANNEL_HOST_MAP` (e.g. `serwisA.com=channel-a,serwisB.com=channel-b`).
+4. **Fallback to the system default** — for storefront / integration paths only. Admin paths refuse with `MISSING_SALES_CHANNEL_CONTEXT` when `strictAdmin` is on (off by default during the initial rollout).
+
+If a step matches a code that doesn't exist or whose channel is `active=false`, the request is refused with `UNKNOWN_SALES_CHANNEL` / `INACTIVE_SALES_CHANNEL`. The fallback never applies in those cases.
+
+Every response carries `X-Sales-Channel: <resolvedCode>` so HTTP caches can `Vary` on it.
+
+## Storefront theme
+
+A channel's `themeCode` selects which set of design tokens the storefront renders in — colour, typography, spacing, corner radius, elevation. It is chosen from a list on the channel's identity form, and the list holds the themes the storefront actually implements; a channel that names none renders in the default theme.
+
+The storefront reads it through the public channel endpoint:
+
+```text
+GET /api/v1/storefront/sales-channel
+```
+
+which returns the **resolved** channel for the request — code, display name, language and currency scopes, `themeCode` and `logoUrl` — and no admin-only field (`id`, `active`, `systemDefault`, `version`). The storefront applies the theme server-side, on the first render, so the first HTML a buyer's browser parses already carries the channel's brand.
+
+The theme changes how the storefront looks, not what it is made of: every channel renders the same pages with the same components. A per-channel page *template* is a larger question, and is deliberately not answered here.
+
+A channel configured with a theme code the storefront does not implement renders in the default theme and logs the code it was given. The page is never refused for a buyer, and no other theme is substituted by guesswork.
+
+## Bidirectional membership
+
+Memberships can be managed equivalently from either side:
+
+```text
+GET    /api/v1/admin/sales-channels/:code/:entityType
+PUT    /api/v1/admin/sales-channels/:code/:entityType/:entityId
+DELETE /api/v1/admin/sales-channels/:code/:entityType/:entityId?fallbackToDefault=true
+GET    /api/v1/admin/sales-channels/by-entity/:entityType/:entityId
+```
+
+Both sides delegate to `SalesChannelMembershipService`, which is the single mutator for every bridge table. Operators reach the same data whether they're editing a Sales Channel's membership panel or a Product's "Sales channels" widget on the entity edit page.
+
+## Lifecycle guards
+
+| Operation | Refused when… | Error code |
+|---|---|---|
+| `deactivate(default)` | always | `CANNOT_MODIFY_SYSTEM_DEFAULT` |
+| `delete(default)` | always | `CANNOT_MODIFY_SYSTEM_DEFAULT` |
+| `delete(channel)` | any Order or Quote refers to it | `SALES_CHANNEL_HAS_ATTRIBUTIONS` |
+| `delete(channel)` | any membership entity would orphan AND `fallbackToDefault=false` | `ENTITY_WOULD_HAVE_ZERO_CHANNELS` |
+| `update(channel)` | submitted `expectedVersion` is stale | `STALE_SALES_CHANNEL_WRITE` |
+| `create / update(channel)` | unknown language / currency code | `UNKNOWN_LANGUAGE_CODE` / `UNKNOWN_CURRENCY_CODE` |
+| `create / rename(channel)` | code already in use | `DUPLICATE_SALES_CHANNEL_CODE` |
+
+Hard-delete with `?fallbackToDefault=true` rebinds orphaned entities to the system default inside the same transaction before the channel row is removed; the bridge tables' `ON DELETE CASCADE` is the safety net for any membership that doesn't need explicit rebinding.
+
+## Audit trail
+
+Every identity change, lifecycle change, and membership change writes one `audit_log_entries` row synchronously inside the same transaction. The action codes live in `@endora-commerce/contracts` as `SALES_CHANNEL_AUDIT_ACTIONS`:
+
+- `sales_channel.identity.changed` — create + update.
+- `sales_channel.lifecycle.changed` — deactivate / activate / delete / system-default-promoted.
+- `sales_channel.membership.changed` — add / remove (no-op writes are not audited).
+
+## Environment variables
+
+| Name | Default | Purpose |
+|---|---|---|
+| `DEFAULT_SALES_CHANNEL_CODE` | `default` | Code of the channel the boot reconciler creates / promotes as `system_default = true`. |
+| `SALES_CHANNEL_HOST_MAP` | empty | Comma-separated `host=channelCode` pairs used by the resolver when no `X-Sales-Channel` header is provided. Example: `serwisA.com=channel-a,serwisB.com=channel-b`. |
+
+See [admin-usage](./admin-usage.md) for the day-to-day operator workflow and [developer-guide](./developer-guide.md) for cross-module integration.

package/i18n/en.json

@@ -0,0 +1,75 @@
+{
+  "nav.salesChannels.label": "Sales channels",
+  "actions.openSalesChannels.label": "Sales channels",
+  "actions.openSalesChannels.description": "Storefront channels",
+  "actions.newSalesChannel.label": "New sales channel",
+  "actions.newSalesChannel.description": "Configure a new storefront sales channel",
+  "list.page.title": "Sales channels",
+  "list.page.description": "Each channel represents a place of sale (web storefront, marketplace, brick-and-mortar location). Products, customers, prices, and content are scoped to the channels they belong to. The “system default” channel is the implicit fallback for any entity created without explicit channel selection.",
+  "list.error.load": "Failed to load sales channels.",
+  "list.action.newChannel": "+ New channel",
+  "list.filter.activeOnly": "Show active channels only",
+  "list.loading": "Loading sales channels…",
+  "list.empty": "No channels match the filter.",
+  "list.column.code": "Code",
+  "list.column.name": "Name",
+  "list.column.defaultLangCurrency": "Default lang / currency",
+  "list.column.status": "Status",
+  "list.column.version": "Version",
+  "list.column.systemDefault": "System default",
+  "list.action.makeDefault": "Make default",
+  "list.action.makeDefault.confirm": "Make “{code}” the system-default sales channel? Entities created without an explicit channel, and every platform-wide fallback, will point at it from now on. “{previous}” stays exactly as it is and can be made the default again.",
+  "list.action.makeDefault.inactiveHelp": "An inactive channel cannot become the system default.",
+  "list.action.makeDefault.current": "Current default",
+  "list.error.makeDefault": "Failed to move the system default.",
+  "status.active": "Active",
+  "status.inactive": "Inactive",
+  "badge.systemDefault": "System default",
+  "edit.loading": "Loading channel…",
+  "identity.title.create": "New Sales Channel",
+  "identity.title.edit": "Identity",
+  "identity.code.label": "Code",
+  "identity.code.lockedHelp": "A channel code is set once, when the channel is created, and cannot be changed afterwards — deployment configuration, integrations and cached storefront responses all address the channel by it. To correct one, create a channel with the right code and delete this one. The display name stays editable.",
+  "identity.name.label": "Display name (en-US)",
+  "identity.name.placeholder": "Service A",
+  "identity.theme.label": "Storefront theme",
+  "identity.theme.placeholder": "e.g. nordic",
+  "identity.theme.pattern": "Lowercase letters, digits, hyphens and underscores, starting with a letter.",
+  "identity.theme.help": "The theme code the storefront renders this channel in. Leave it empty for the storefront's default theme. Which themes exist is the storefront's answer, not this one's: a code it does not provide renders in the default and is marked on the page as data-theme-requested, and this value is never changed for you.",
+  "identity.languages.label": "Languages",
+  "identity.languages.help": "Active Dictionary languages are available for new selections. Inactive stored values remain visible until removed.",
+  "identity.defaultLanguage.label": "Default language",
+  "identity.currencies.label": "Currencies",
+  "identity.currencies.help": "Active Dictionary currencies are available for new selections. Inactive stored values remain visible until removed.",
+  "identity.defaultCurrency.label": "Default currency",
+  "identity.pickOption": "Pick",
+  "identity.active": "Active",
+  "identity.cannotDeactivateDefault": "The system-default channel cannot be deactivated.",
+  "identity.action.cancel": "Cancel",
+  "identity.action.create": "Create channel",
+  "identity.action.save": "Save changes",
+  "identity.dictionary.inactive": "(inactive)",
+  "identity.dictionary.empty": "No Dictionary entries available.",
+  "membership.title": "Sales channels",
+  "membership.loading": "Loading memberships…",
+  "membership.empty": "This {entityType} is not in any channel. Add at least one to make it visible to a storefront.",
+  "membership.defaultSuffix": " (default)",
+  "membership.action.pickChannel": "Add to channel…",
+  "membership.action.add": "Add",
+  "membership.action.remove": "Remove",
+  "errors.UNKNOWN_SALES_CHANNEL": "Unknown Sales Channel.",
+  "errors.INACTIVE_SALES_CHANNEL": "This sales channel is inactive. Activate it first.",
+  "errors.MISSING_SALES_CHANNEL_CONTEXT": "Missing Sales Channel Context.",
+  "errors.DUPLICATE_SALES_CHANNEL_CODE": "Duplicate Sales Channel Code.",
+  "errors.UNKNOWN_LANGUAGE_CODE": "Unknown Language Code.",
+  "errors.UNKNOWN_CURRENCY_CODE": "Unknown Currency Code.",
+  "errors.CANNOT_MODIFY_SYSTEM_DEFAULT": "Cannot Modify System Default.",
+  "errors.SALES_CHANNEL_HAS_ATTRIBUTIONS": "Sales Channel Has Attributions.",
+  "errors.ENTITY_WOULD_HAVE_ZERO_CHANNELS": "Entity Would Have Zero Channels.",
+  "errors.STALE_SALES_CHANNEL_WRITE": "Stale Sales Channel Write.",
+  "errors.SALES_CHANNEL_ATTRIBUTION_IMMUTABLE": "Sales Channel Attribution Immutable.",
+  "errors.SALES_CHANNEL_CODE_IMMUTABLE": "A sales channel code is set when the channel is created and cannot be changed afterwards. Create a channel with the correct code and delete this one instead; the display name stays editable.",
+  "auditLog.sales_channel.lifecycle_changed": "Sales channel lifecycle changed",
+  "auditLog.sales_channel.membership_changed": "Sales channel membership changed",
+  "auditLog.sales_channel.set_default": "System-default sales channel moved"
+}

package/i18n/pl.json

@@ -0,0 +1,75 @@
+{
+  "nav.salesChannels.label": "Kanały sprzedaży",
+  "actions.openSalesChannels.label": "Kanały sprzedaży",
+  "actions.openSalesChannels.description": "Kanały sklepu",
+  "actions.newSalesChannel.label": "Nowy kanał sprzedaży",
+  "actions.newSalesChannel.description": "Skonfiguruj nowy kanał sprzedaży witryny",
+  "list.page.title": "Kanały sprzedaży",
+  "list.page.description": "Każdy kanał reprezentuje miejsce sprzedaży (sklep internetowy, marketplace, lokalizacja stacjonarna). Produkty, klienci, ceny i treści są zakresowane do kanałów, do których należą. Kanał „domyślny systemowo” jest niejawnym fallbackiem dla każdej encji utworzonej bez wyraźnego wyboru kanału.",
+  "list.error.load": "Nie udało się wczytać kanałów sprzedaży.",
+  "list.action.newChannel": "+ Nowy kanał",
+  "list.filter.activeOnly": "Pokaż tylko aktywne kanały",
+  "list.loading": "Wczytywanie kanałów sprzedaży…",
+  "list.empty": "Żaden kanał nie pasuje do filtra.",
+  "list.column.code": "Kod",
+  "list.column.name": "Nazwa",
+  "list.column.defaultLangCurrency": "Domyślny język / waluta",
+  "list.column.status": "Status",
+  "list.column.version": "Wersja",
+  "list.column.systemDefault": "Domyślny systemowo",
+  "list.action.makeDefault": "Ustaw jako domyślny",
+  "list.action.makeDefault.confirm": "Ustawić „{code}” jako domyślny systemowo kanał sprzedaży? Encje tworzone bez wskazania kanału oraz wszystkie odczyty ogólnoplatformowe będą od tej chwili wskazywać na niego. „{previous}” pozostaje bez zmian i może ponownie zostać kanałem domyślnym.",
+  "list.action.makeDefault.inactiveHelp": "Nieaktywny kanał nie może zostać kanałem domyślnym systemowo.",
+  "list.action.makeDefault.current": "Obecnie domyślny",
+  "list.error.makeDefault": "Nie udało się przenieść kanału domyślnego.",
+  "status.active": "Aktywny",
+  "status.inactive": "Nieaktywny",
+  "badge.systemDefault": "Domyślny systemowo",
+  "edit.loading": "Wczytywanie kanału…",
+  "identity.title.create": "Nowy kanał sprzedaży",
+  "identity.title.edit": "Tożsamość",
+  "identity.code.label": "Kod",
+  "identity.code.lockedHelp": "Kod kanału ustawiasz raz, przy tworzeniu kanału, i nie można go później zmienić — konfiguracja wdrożenia, integracje i zapisane w cache odpowiedzi storefrontu adresują kanał właśnie po nim. Aby poprawić kod, utwórz kanał z właściwym kodem i usuń ten. Nazwa wyświetlana pozostaje edytowalna.",
+  "identity.name.label": "Nazwa wyświetlana (en-US)",
+  "identity.name.placeholder": "Serwis A",
+  "identity.theme.label": "Motyw sklepu",
+  "identity.theme.placeholder": "np. nordic",
+  "identity.theme.pattern": "Małe litery, cyfry, myślniki i podkreślenia, zaczynając od litery.",
+  "identity.theme.help": "Kod motywu, w którym storefront renderuje ten kanał. Pozostaw puste, aby użyć motywu domyślnego. To storefront wie, jakie motywy istnieją, a nie ten ekran: kod, którego nie ma, renderuje się w motywie domyślnym i zostaje oznaczony na stronie jako data-theme-requested, a ta wartość nigdy nie jest zmieniana automatycznie.",
+  "identity.languages.label": "Języki",
+  "identity.languages.help": "Dostępne do wyboru są aktywne wpisy Słownika języków. Wartości przypisane wcześniej, ale obecnie nieaktywne, pozostają widoczne do usunięcia.",
+  "identity.defaultLanguage.label": "Język domyślny",
+  "identity.currencies.label": "Waluty",
+  "identity.currencies.help": "Dostępne do wyboru są aktywne wpisy Słownika walut. Wartości przypisane wcześniej, ale obecnie nieaktywne, pozostają widoczne do usunięcia.",
+  "identity.defaultCurrency.label": "Waluta domyślna",
+  "identity.pickOption": "Wybierz",
+  "identity.active": "Aktywny",
+  "identity.cannotDeactivateDefault": "Kanał domyślny systemowo nie może zostać dezaktywowany.",
+  "identity.action.cancel": "Anuluj",
+  "identity.action.create": "Utwórz kanał",
+  "identity.action.save": "Zapisz zmiany",
+  "identity.dictionary.inactive": "(nieaktywny)",
+  "identity.dictionary.empty": "Brak wpisów w Słowniku.",
+  "membership.title": "Kanały sprzedaży",
+  "membership.loading": "Wczytywanie przynależności…",
+  "membership.empty": "Ten {entityType} nie należy do żadnego kanału. Dodaj co najmniej jeden, aby był widoczny w sklepie.",
+  "membership.defaultSuffix": " (domyślny)",
+  "membership.action.pickChannel": "Dodaj do kanału…",
+  "membership.action.add": "Dodaj",
+  "membership.action.remove": "Usuń",
+  "errors.UNKNOWN_SALES_CHANNEL": "Błąd: unknown sales channel.",
+  "errors.INACTIVE_SALES_CHANNEL": "Ten kanał sprzedaży jest nieaktywny. Najpierw go aktywuj.",
+  "errors.MISSING_SALES_CHANNEL_CONTEXT": "Błąd: missing sales channel context.",
+  "errors.DUPLICATE_SALES_CHANNEL_CODE": "Błąd: duplicate sales channel code.",
+  "errors.UNKNOWN_LANGUAGE_CODE": "Błąd: unknown language code.",
+  "errors.UNKNOWN_CURRENCY_CODE": "Błąd: unknown currency code.",
+  "errors.CANNOT_MODIFY_SYSTEM_DEFAULT": "Błąd: cannot modify system default.",
+  "errors.SALES_CHANNEL_HAS_ATTRIBUTIONS": "Błąd: sales channel has attributions.",
+  "errors.ENTITY_WOULD_HAVE_ZERO_CHANNELS": "Błąd: entity would have zero channels.",
+  "errors.STALE_SALES_CHANNEL_WRITE": "Błąd: stale sales channel write.",
+  "errors.SALES_CHANNEL_ATTRIBUTION_IMMUTABLE": "Błąd: sales channel attribution immutable.",
+  "errors.SALES_CHANNEL_CODE_IMMUTABLE": "Kod kanału sprzedaży jest ustawiany przy tworzeniu kanału i nie może być później zmieniony. Utwórz kanał z właściwym kodem i usuń ten; nazwa wyświetlana pozostaje edytowalna.",
+  "auditLog.sales_channel.lifecycle_changed": "Zmieniono cykl życia kanału sprzedaży",
+  "auditLog.sales_channel.membership_changed": "Zmieniono przypisanie do kanału sprzedaży",
+  "auditLog.sales_channel.set_default": "Przeniesiono domyślny systemowo kanał sprzedaży"
+}

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@endora-commerce/mod-sales-channels",
+  "version": "0.100.0",
+  "type": "module",
+  "sideEffects": false,
+  "description": "Multi-channel storefront resolver and channel registry.",
+  "license": "MIT",
+  "endora": {
+    "type": "module",
+    "id": "sales_channels"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/endora-commerce/endora-commerce.git",
+    "directory": "packages/modules/sales_channels"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/manifest.d.ts",
+      "default": "./dist/manifest.js"
+    },
+    "./backend": {
+      "types": "./dist/backend/index.d.ts",
+      "default": "./dist/backend/index.js"
+    },
+    "./admin": {
+      "types": "./dist/admin/index.d.ts",
+      "default": "./dist/admin/index.js"
+    },
+    "./tailwind.css": "./tailwind.css",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "i18n",
+    "docs",
+    "tailwind.css"
+  ],
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "peerDependencies": {
+    "@mikro-orm/core": "^6",
+    "@mikro-orm/postgresql": "^6",
+    "fastify": "^5",
+    "react": "^19",
+    "react-router-dom": "^7",
+    "zod": "^4",
+    "@endora-commerce/admin-kit": "0.100.0",
+    "@endora-commerce/contracts": "0.100.0",
+    "@endora-commerce/platform": "0.100.0"
+  },
+  "peerDependenciesMeta": {
+    "@endora-commerce/admin-kit": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-router-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@mikro-orm/core": "^6.6.13",
+    "@mikro-orm/postgresql": "^6.6.13",
+    "@types/node": "^22.9.0",
+    "@types/react": "^19.2.14",
+    "fastify": "^5.12.5",
+    "react": "^19.2.5",
+    "react-router-dom": "^7.18.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11",
+    "zod": "^4.2.0",
+    "@endora-commerce/admin-kit": "0.100.0",
+    "@endora-commerce/contracts": "0.100.0",
+    "@endora-commerce/platform": "0.100.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.ui.json",
+    "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.ui.json --noEmit",
+    "lint": "eslint src",
+    "test": "vitest run"
+  }
+}

package/tailwind.css

@@ -0,0 +1,14 @@
+/* @endora-commerce/mod-sales-channels — AUTO-GENERATED by `pnpm --filter backend run manifests:generate`.
+ *
+ * The `@source` directives this package asks its host to scan
+ * (`specs/110-instance-repository/contracts/admin-stylesheet-composition.md` R1).
+ * They resolve relative to **this file**, so they hold wherever the package is
+ * installed — a workspace link here, `node_modules` in a client's instance.
+ *
+ * The `dist` line is what a published tarball ships and is what an instance
+ * scans; the `src` line is inert there and is what keeps `pnpm --filter admin
+ * run dev` reading source in this repository. Do not edit: run
+ * `pnpm --filter backend run manifests:generate`.
+ */
+@source "./dist/admin";
+@source "./src/admin";