@endora-commerce/mod-currencies 0.100.0

package/dist/manifest.js

@@ -0,0 +1,83 @@
+import { defineModuleManifest } from '@endora-commerce/contracts';
+/**
+ * Currencies module — manifest backfill (Module Lifecycle, feature 018).
+ *
+ * Predates the lifecycle system; this manifest is the static record
+ * required so the module participates in the registry. No install /
+ * uninstall hook today — the module's schema is owned by earlier
+ * platform-wide migrations.
+ */
+export const manifest = defineModuleManifest({
+    id: 'currencies',
+    docs: { dir: 'docs' },
+    name: 'Currencies',
+    description: 'Currency reference data and per-channel currency configuration.',
+    version: '1.0.0',
+    // `auth` owns the `requireAdmin` port the admin routes added on 2026-08-29
+    // are gated by. It is the only entry, and the list stays otherwise empty for
+    // its original reason: `currencies` announces a change on the EventBus and
+    // `dictionaries` reacts by dropping its caches — a **notification**, not a
+    // query, which `contracts/module-context.md` says needs no dependency edge.
+    // Declaring one produced a real cycle (dictionaries → currencies →
+    // dictionaries) and the cycle was the design telling us the direction was
+    // wrong: a currency has no business knowing a dictionary cache exists.
+    dependencies: ['auth'],
+    /**
+     * The module's own authority (2026-08-29).
+     *
+     * `/api/v1/admin/currencies`, `/:code`, `/:code/default` and the delete were
+     * registered by `languages` and enforced `catalog:write` — all four, the list
+     * read included. So whoever could edit a product description could add a
+     * currency, deactivate one, delete one and **promote one to the shop's
+     * default**, which is the denomination every price, cart, order and invoice
+     * is stated in.
+     *
+     * Nothing could see it. `catalog:write` is real, declared and enforced, so
+     * the permission inventory's two directions were clean; D-173's `foreign-gate`
+     * sweep passes the site deliberately, because `catalog` is `nonDeactivatable`
+     * and the availability coupling that sweep asks about can never bite; and
+     * `check:action-route-permissions` never looked at all, neither this module
+     * nor `languages` declaring a manifest action. None of them asks whether
+     * `catalog:write` is the right authority for changing what a shop charges in,
+     * which is a judgement rather than a derivation, so the answer is pinned in a
+     * contract test rather than in a new check.
+     *
+     * A pair and no third code, spelled `<module id>:<read|write>` like
+     * `payment_methods`, `delivery_methods`, `taxes`, `returns` and `invoices`. A
+     * prefix that is not its owner's id is the mistake `PERMISSION_CATALOGUE`
+     * comments on twice (`integrations:manage`, `audit_log:read`), both frozen
+     * because they are persisted in role rows; getting it right on a code that
+     * does not exist yet is free.
+     *
+     * The read half is a capability that did not exist rather than a rename of
+     * one: every one of the four routes carried the write code, so listing the
+     * currencies required the authority to delete one.
+     *
+     * The **other** door to this table is `dictionaries`'
+     * `/api/v1/admin/dictionary/currencies/*`, gated on `dictionary.write`. It is
+     * out of this repair's scope and is reported rather than changed: that is the
+     * screen an operator actually uses, it is a code `dictionaries` owns rather
+     * than a borrowed one, and re-gating it is the same question asked of the
+     * whole reference-data registry (countries and languages alike) rather than
+     * of currencies.
+     *
+     * No data migration: see `test/contract/currencies/permission-authority.test.ts`.
+     */
+    permissions: [
+        { code: 'currencies:read', label: 'View currencies' },
+        { code: 'currencies:write', label: 'Configure currencies' },
+    ],
+    // Feature 074 (Constitution XVII), test C3 — platform primitive. The
+    // declaration used to carry the manifest graph as its second half ("and
+    // `dictionaries` declares this module, two edges from the tenancy root");
+    // ruling 2 withdraws that, and the business half was always the real one and
+    // stands alone. Denomination is not a business decision anyone takes: there
+    // is no price, cart, order or invoice without a currency, and no client for
+    // whom "no currencies" is a smaller platform rather than a broken one.
+    activation: {
+        nonDeactivatable: true,
+        reason: 'Every amount is denominated; there is no price, cart, order or invoice without a ' +
+            'currency.',
+    },
+});
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAElE;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,oBAAoB,CAAC;IAC3C,EAAE,EAAE,YAAY;IAChB,IAAI,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE;IACrB,IAAI,EAAE,YAAY;IAClB,WAAW,EACT,iEAAiE;IACnE,OAAO,EAAE,OAAO;IAChB,2EAA2E;IAC3E,6EAA6E;IAC7E,2EAA2E;IAC3E,2EAA2E;IAC3E,4EAA4E;IAC5E,mEAAmE;IACnE,0EAA0E;IAC1E,uEAAuE;IACvE,YAAY,EAAE,CAAC,MAAM,CAAC;IACtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwCG;IACH,WAAW,EAAE;QACX,EAAE,IAAI,EAAE,iBAAiB,EAAE,KAAK,EAAE,iBAAiB,EAAE;QACrD,EAAE,IAAI,EAAE,kBAAkB,EAAE,KAAK,EAAE,sBAAsB,EAAE;KAC5D;IACD,qEAAqE;IACrE,wEAAwE;IACxE,0EAA0E;IAC1E,6EAA6E;IAC7E,4EAA4E;IAC5E,4EAA4E;IAC5E,uEAAuE;IACvE,UAAU,EAAE;QACV,gBAAgB,EAAE,IAAI;QACtB,MAAM,EACJ,mFAAmF;YACnF,WAAW;KACd;CACF,CAAC,CAAC"}

package/docs/currencies.md

@@ -0,0 +1,59 @@
+---
+title: currencies
+description: Pool of accepted ISO 4217 currencies + default
+---
+
+# `currencies`
+
+The installation-wide pool of accepted ISO 4217 currency codes. Mirrors the
+`languages` module.
+
+## Public surface
+
+| Verb + Path | Permission | Purpose |
+| --- | --- | --- |
+| `GET /api/v1/admin/currencies` | `currencies:read` | Full list |
+| `PUT /api/v1/admin/currencies/:code` | `currencies:write` | Upsert |
+| `POST /api/v1/admin/currencies/:code/default` | `currencies:write` | Promote to default (atomically demotes the prior default) |
+| `DELETE /api/v1/admin/currencies/:code` | `currencies:write` | Remove (rejected for the default) |
+
+`GET /api/v1/i18n/config` also answers with the active currencies and the
+default, and is **`languages`'** route rather than this module's: it composes
+both catalogues into one public payload and reads this module's half over
+`currencyReadPort`. See [languages](./languages.md).
+
+## Permissions
+
+`currencies:read` and `currencies:write`, this module's own since 2026-08-29.
+
+The four routes above lived in `languages` until then and enforced
+`catalog:write` — all four, the list read included — so whoever could edit a
+product description could add a currency, deactivate one, delete one and
+promote one to the shop's default. Nothing in this repository calls these
+routes: the admin currency screen is `dictionaries`'
+(`/api/v1/admin/dictionary/currencies/*`, gated on `dictionary.write`), which is
+a second door to this table and a separate question.
+
+`test/contract/currencies/permission-authority.test.ts` pins both directions —
+a role holding the catalogue codes is refused, a role holding the pair is
+served — and asserts that the in-process `currencyReadPort` every other module
+reads a currency through is untouched by the move.
+
+## Defaults
+
+Same partial-unique-index pattern as `languages`. The migration bootstrap
+seeds `PLN` (default) and `EUR`; symbol values are stored via Postgres
+Unicode literals so the migration source stays ASCII.
+
+## Entities
+
+`Currency` — natural primary key on the ISO 4217 code; `label`,
+`symbol`, `isDefault`, `isActive`, `sortOrder`.
+
+## Extension points
+
+- **Per-Sales-Channel default** — when a Sales Channel ships its own
+  currency, gate `priceFor(cart)` in the orders module on the channel's
+  configured currency rather than the global default.
+- **Exchange-rate provider** — out of scope here; integrate via the
+  `integrations` module when a real adapter is needed.

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@endora-commerce/mod-currencies",
+  "version": "0.100.0",
+  "type": "module",
+  "sideEffects": false,
+  "description": "Currency reference data and per-channel currency configuration.",
+  "license": "MIT",
+  "endora": {
+    "type": "module",
+    "id": "currencies"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/endora-commerce/endora-commerce.git",
+    "directory": "packages/modules/currencies"
+  },
+  "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"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "docs"
+  ],
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "peerDependencies": {
+    "@mikro-orm/core": "^6",
+    "@mikro-orm/postgresql": "^6",
+    "fastify": "^5",
+    "@endora-commerce/contracts": "0.100.0",
+    "@endora-commerce/platform": "0.100.0"
+  },
+  "devDependencies": {
+    "@fastify/type-provider-zod": "^1.0.0",
+    "@mikro-orm/core": "^6.6.13",
+    "@mikro-orm/postgresql": "^6.6.13",
+    "@types/node": "^22.9.0",
+    "fastify": "^5.12.5",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11",
+    "@endora-commerce/contracts": "0.100.0",
+    "@endora-commerce/platform": "0.100.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "lint": "eslint src",
+    "test": "vitest run"
+  }
+}