@endora-commerce/mod-taxes 0.100.0

package/dist/manifest.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Taxes 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 declare const manifest: {
+    id: string;
+    name: string;
+    version: string;
+    dependencies: string[];
+    description?: string | undefined;
+    acknowledgedDependencies?: {
+        moduleId: string;
+        port: string;
+        reason: string;
+    }[] | undefined;
+    nonBindingDependencies?: {
+        moduleId: string;
+        name: string;
+        kind: "contributes-to" | "degrades-without" | "refuses-without";
+        reason: string;
+        whenAbsent?: string | undefined;
+    }[] | undefined;
+    activation?: {
+        settingCode: string;
+        default: boolean;
+    } | {
+        nonDeactivatable: true;
+        reason: string;
+    } | undefined;
+    settings?: {
+        moduleCode: string;
+        groups: {
+            code: string;
+            name: string;
+            salesChannelCodes?: string[] | undefined;
+            isSystemProtected?: boolean | undefined;
+        }[];
+        settings: {
+            code: string;
+            name: string;
+            valueType: "string" | "number" | "boolean" | "json" | "string_list" | "secret" | "credential_ref";
+            defaultValue: unknown;
+            description?: string | undefined;
+            groupCode?: string | undefined;
+            previousDefaultValues?: unknown[] | undefined;
+            salesChannelCodes?: string[] | undefined;
+            enumOptions?: string[] | undefined;
+            configurationType?: string | undefined;
+            hidden?: boolean | undefined;
+        }[];
+    } | undefined;
+    i18n?: {
+        bundlesDir: string;
+    } | undefined;
+    docs?: false | {
+        dir: string;
+    } | undefined;
+    demo?: false | {
+        summary: string;
+        seed: (context: import("@endora-commerce/contracts").ModuleDemoContext<never>) => Promise<import("@endora-commerce/contracts").DemoSeedResult>;
+        reset: (context: import("@endora-commerce/contracts").ModuleDemoContext<never>) => Promise<import("@endora-commerce/contracts").DemoResetResult>;
+        after?: readonly string[] | undefined;
+        package?: string | undefined;
+    } | undefined;
+    actions?: {
+        id: string;
+        labelKey: string;
+        icon: "Plus" | "Sparkles" | "Settings" | "Search" | "Boxes" | "Layers" | "Menu" | "PlusCircle" | "PlusSquare" | "FilePlus" | "FolderPlus" | "Upload" | "FileUp" | "CloudUpload" | "Download" | "FileDown" | "FileText" | "BookOpen" | "Rss" | "Package" | "Tag" | "ShoppingCart" | "Receipt" | "CreditCard" | "Users" | "UserPlus" | "Inbox" | "ListChecks" | "ClipboardList" | "Image" | "Video" | "LayoutDashboard" | "PanelLeft" | "KeyRound" | "ShieldCheck" | "Edit" | "Archive" | "Box" | "Truck" | "CircleDollarSign" | "Activity" | "LineChart" | "Smartphone" | "Webhook" | "Scale" | "PlugZap" | "PercentDiamond" | "Newspaper" | "Languages" | "Eraser" | "Warehouse" | "TrendingDown" | "Bell" | "PackageOpen" | "Building2" | "Store" | "ClipboardCheck";
+        targetRoute: string;
+        keywords: string[];
+        weight: number;
+        descriptionKey?: string | undefined;
+        requiredPermission?: string | undefined;
+    }[] | undefined;
+    permissions?: {
+        code: string;
+        label: string;
+        module?: string | undefined;
+        description?: string | undefined;
+        requires?: string[] | undefined;
+    }[] | undefined;
+    transactionalEmails?: {
+        code: string;
+        name: string;
+        variables: {
+            key: string;
+            label: string;
+            sampleValue?: string | undefined;
+            description?: string | undefined;
+        }[];
+        description?: string | undefined;
+        group?: string | undefined;
+    }[] | undefined;
+    capabilities?: string[] | undefined;
+    exclusiveCapabilities?: {
+        key: string;
+        errorCode: string;
+    }[] | undefined;
+    errorCodes?: {
+        code: string;
+        tokens?: string[] | undefined;
+    }[] | undefined;
+    blocks?: {
+        name: string;
+        labelKey: string;
+        category: string;
+        contexts: ("invoice" | "email" | "cms" | "newsletter")[];
+        fields: Record<string, {
+            type: "number" | "object" | "array" | "uuid" | "text" | "textarea" | "select" | "radio" | "external" | "richtext";
+            label?: string | undefined;
+            required?: boolean | undefined;
+            options?: {
+                label: string;
+                value: string | number;
+            }[] | undefined;
+            refKind?: string | undefined;
+        }>;
+        descriptionKey?: string | undefined;
+        defaultProps?: Record<string, unknown> | undefined;
+        responsiveFields?: string[] | undefined;
+        previewIcon?: string | undefined;
+        weight?: number | undefined;
+    }[] | undefined;
+    blockCategories?: {
+        key: string;
+        titleKey: string;
+        contexts: ("invoice" | "email" | "cms" | "newsletter")[];
+        weight?: number | undefined;
+        visible?: boolean | undefined;
+    }[] | undefined;
+    env?: {
+        name: string;
+        describes: {
+            en: string;
+            pl: string;
+        };
+        requirement: {
+            kind: "required";
+        } | {
+            kind: "requiredWhen";
+            input: string;
+            equals: string;
+        } | {
+            kind: "optional";
+            without: {
+                en: string;
+                pl: string;
+            };
+        };
+        secret: boolean;
+        generable: boolean;
+        owner: {
+            kind: "platform";
+        } | {
+            kind: "application";
+            application: "admin" | "backend" | "storefront";
+        } | {
+            kind: "module";
+            moduleId: string;
+        };
+        consumers: ("admin" | "backend" | "storefront")[];
+        addressOf: "admin" | "backend" | "storefront" | null;
+    }[] | undefined;
+};
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAwBA;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoFnB,CAAC"}

package/dist/manifest.js

@@ -0,0 +1,113 @@
+import { defineModuleManifest } from '@endora-commerce/contracts';
+/**
+ * The demo data this module owns (feature 113, T220 — contract §1.3).
+ *
+ * A typed `const` rather than an inline object literal, and that is not style:
+ * declared inline the parameter infers from the schema and is `never`, so the
+ * author loses `context.ctx: ModuleContext`.
+ *
+ * Both bodies are reached by a **relative `await import()`** (§1.4), in
+ * `cliCommands.run`'s shape and for `cliCommands`' reason: a manifest is loaded
+ * by every process that composes the platform and by the check scripts that
+ * import the generated index, so a demo body imported at the top of this file
+ * would be a service graph pulled into all of them. It needs no `exports`
+ * subpath and no `files` entry — a relative import inside the package lands in
+ * `dist` through the existing emit (§1.5).
+ */
+const demo = {
+    summary: 'The Polish standard VAT rule, so seeded prices carry tax.',
+    seed: async (context) => (await import('./backend/demo/seed.js')).seedDemo(context),
+    reset: async (context) => (await import('./backend/demo/reset.js')).resetDemo(context),
+};
+/**
+ * Taxes 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: 'taxes',
+    name: 'Taxes',
+    description: 'Tax rate configuration and order tax computation.',
+    version: '1.0.0',
+    // `auth` owns the `requireAdmin` port the admin routes are gated by;
+    // `dictionaries` owns the validator that checks country and region codes.
+    // Feature 072 made both container resolutions rather than optional arguments.
+    dependencies: ['auth', 'dictionaries'],
+    /**
+     * The module's own authority (2026-08-28).
+     *
+     * All four admin routes used to enforce `catalog:write` — the two reads
+     * included — so whoever could edit a product could read the tax table,
+     * rewrite a rate, move the default rule and delete a rule outright. A rate is
+     * the figure every price, every order total and every invoice is computed
+     * from, and this module is the one the platform refuses to switch off on the
+     * ground that a shop which cannot compute tax cannot state a lawful price;
+     * the authority over that figure was the catalogue's. `catalog:write` was
+     * real, declared and enforced, so the permission inventory's two directions
+     * were clean over the site, and `check:action-route-permissions` never looked
+     * at all: this module declares no manifest action, so the check has nothing
+     * of its own to compare.
+     *
+     * A pair and no third code, spelled `<module id>:<read|write>` like the five
+     * gateway modules, `payment_methods`, `delivery_methods`, `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 codes stay
+     * here rather than in `PERMISSION_CATALOGUE`, which is for codes spanning
+     * modules — this module owns these outright.
+     *
+     * The read half is a capability that did not exist before rather than a
+     * rename of one: there was no read gate to move, so `taxes:read` is what
+     * finally lets an operator be shown a VAT rate without being handed the
+     * authority to change it.
+     *
+     * No data migration: see `test/contract/taxes/permission-authority.test.ts`.
+     */
+    permissions: [
+        { code: 'taxes:read', label: 'View tax rules' },
+        { code: 'taxes:write', label: 'Configure tax rules' },
+    ],
+    settings: {
+        moduleCode: 'taxes',
+        groups: [{ code: 'taxes', name: 'Taxes' }],
+        // The group is kept as a reservation while the module ships no settings of
+        // its own: `taxes.enabled` was the only one, and it went with the control
+        // it backed (feature 074). Dropping the group too would only turn it into
+        // an orphan the boot reconciler warns about at every start.
+        settings: [],
+    },
+    // Feature 074 (Constitution XVII), test C2 — functional base, and one of the
+    // escalation answers. 073 read this module as "a platform without
+    // configurable tax rates is a smaller platform, not a broken one", and the
+    // deciding fact is what that reading missed: the absence does not announce
+    // itself. Every price becomes tax-free with no operator-visible signal and
+    // the invoice carries a wrong figure. A platform that cannot compute tax
+    // cannot state a lawful price, which is a different product rather than a
+    // reduced one.
+    //
+    // This closes the *operator* route to that state. The platform route — a
+    // deployment that never installs this module — is still open and is a
+    // separate follow-up, which inherits one constraint: a correctly-configured
+    // 0% rate is a legitimate answer in some jurisdictions, so absence and a
+    // configured zero must stay distinguishable.
+    //
+    // `taxes.enabled` goes with the control. The existing rows are removed by a
+    // core data migration (feature 074, FR-010a).
+    // Feature 091 (Phase 4, batch 8) — this module ships a bundle now: its
+    // sidebar entry's `labelKey` is module-relative (R8) and resolves in this
+    // module's own namespace. Its screen's copy stays in `_i18n`'s `core`
+    // scope, which is batch 4's shape and not a new one.
+    i18n: { bundlesDir: 'i18n' },
+    docs: { dir: 'docs' },
+    demo,
+    activation: {
+        nonDeactivatable: true,
+        reason: 'Absent, every price becomes tax-free with no operator-visible signal and the invoice ' +
+            'carries a wrong figure. A platform that cannot compute tax cannot state a lawful price.',
+    },
+});
+//# 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,EAA2B,MAAM,4BAA4B,CAAC;AAG3F;;;;;;;;;;;;;;GAcG;AACH,MAAM,IAAI,GAAsC;IAC9C,OAAO,EAAE,2DAA2D;IACpE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC,MAAM,MAAM,CAAC,wBAAwB,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC;IACnF,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC,MAAM,MAAM,CAAC,yBAAyB,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC;CACvF,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,oBAAoB,CAAC;IAC3C,EAAE,EAAE,OAAO;IACX,IAAI,EAAE,OAAO;IACb,WAAW,EACT,mDAAmD;IACrD,OAAO,EAAE,OAAO;IAChB,qEAAqE;IACrE,0EAA0E;IAC1E,8EAA8E;IAC9E,YAAY,EAAE,CAAC,MAAM,EAAE,cAAc,CAAC;IACtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,WAAW,EAAE;QACX,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,gBAAgB,EAAE;QAC/C,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,qBAAqB,EAAE;KACtD;IACD,QAAQ,EAAE;QACR,UAAU,EAAE,OAAO;QACnB,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;QAC1C,2EAA2E;QAC3E,0EAA0E;QAC1E,0EAA0E;QAC1E,4DAA4D;QAC5D,QAAQ,EAAE,EAAE;KACb;IACD,6EAA6E;IAC7E,kEAAkE;IAClE,2EAA2E;IAC3E,2EAA2E;IAC3E,2EAA2E;IAC3E,yEAAyE;IACzE,0EAA0E;IAC1E,eAAe;IACf,EAAE;IACF,yEAAyE;IACzE,sEAAsE;IACtE,4EAA4E;IAC5E,yEAAyE;IACzE,6CAA6C;IAC7C,EAAE;IACF,4EAA4E;IAC5E,8CAA8C;IAC9C,uEAAuE;IACvE,0EAA0E;IAC1E,sEAAsE;IACtE,qDAAqD;IACrD,IAAI,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE;IAC5B,IAAI,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE;IACrB,IAAI;IACJ,UAAU,EAAE;QACV,gBAAgB,EAAE,IAAI;QACtB,MAAM,EACJ,uFAAuF;YACvF,yFAAyF;KAC5F;CACF,CAAC,CAAC"}

package/dist/migrations/20260426T081516_taxes_promotions_init.d.ts

@@ -0,0 +1,14 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * Tax + Promotion init (T128, T129). Two tables, both keyed by their
+ * own UUID; `taxes.code` and `promotions.code` are unique. The default
+ * tax invariant is enforced by a partial unique index.
+ *
+ * Co-located in the `taxes` module folder to keep the migration
+ * sequence numerical.
+ */
+export declare class Migration20260426T081516TaxesPromotionsInit extends Migration {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}
+//# sourceMappingURL=20260426T081516_taxes_promotions_init.d.ts.map

package/dist/migrations/20260426T081516_taxes_promotions_init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260426T081516_taxes_promotions_init.d.ts","sourceRoot":"","sources":["../../src/migrations/20260426T081516_taxes_promotions_init.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;GAOG;AACH,qBAAa,2CAA4C,SAAQ,SAAS;IACzD,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC;IAmDnB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAIrC"}

package/dist/migrations/20260426T081516_taxes_promotions_init.js

@@ -0,0 +1,63 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * Tax + Promotion init (T128, T129). Two tables, both keyed by their
+ * own UUID; `taxes.code` and `promotions.code` are unique. The default
+ * tax invariant is enforced by a partial unique index.
+ *
+ * Co-located in the `taxes` module folder to keep the migration
+ * sequence numerical.
+ */
+export class Migration20260426T081516TaxesPromotionsInit extends Migration {
+    async up() {
+        this.addSql(`
+      create table "taxes" (
+        "id" uuid not null,
+        "code" varchar(64) not null,
+        "name" varchar(160) not null,
+        "rate" numeric(6, 4) not null,
+        "country" varchar(2) null,
+        "product_type" varchar(16) null,
+        "applies_to_vat_statuses" jsonb not null default '[]'::jsonb,
+        "is_default" boolean not null default false,
+        "priority" int not null default 0,
+        "created_at" timestamptz not null,
+        "updated_at" timestamptz not null,
+        constraint "taxes_pkey" primary key ("id"),
+        constraint "taxes_code_unique" unique ("code")
+      );
+    `);
+        this.addSql('create index "taxes_country_index" on "taxes" ("country");');
+        this.addSql('create unique index "uniq_taxes_one_default" on "taxes" ("is_default") where "is_default" = true;');
+        this.addSql(`
+      create table "promotions" (
+        "id" uuid not null,
+        "code" varchar(64) null,
+        "name" varchar(160) not null,
+        "kind" varchar(24) not null,
+        "value" numeric(14, 4) not null,
+        "currency" varchar(3) null,
+        "min_cart_subtotal" numeric(14, 2) null,
+        "valid_from" timestamptz null,
+        "valid_until" timestamptz null,
+        "organization_id" uuid null,
+        "customer_group_id" uuid null,
+        "category_id" uuid null,
+        "product_id" uuid null,
+        "is_active" boolean not null default true,
+        "created_at" timestamptz not null,
+        "updated_at" timestamptz not null,
+        constraint "promotions_pkey" primary key ("id"),
+        constraint "promotions_code_unique" unique ("code")
+      );
+    `);
+        this.addSql('create index "promotions_kind_index" on "promotions" ("kind");');
+        this.addSql('create index "promotions_organization_id_index" on "promotions" ("organization_id");');
+        this.addSql('create index "promotions_customer_group_id_index" on "promotions" ("customer_group_id");');
+        this.addSql('create index "promotions_is_active_index" on "promotions" ("is_active");');
+    }
+    async down() {
+        this.addSql('drop table if exists "promotions" cascade;');
+        this.addSql('drop table if exists "taxes" cascade;');
+    }
+}
+//# sourceMappingURL=20260426T081516_taxes_promotions_init.js.map

package/dist/migrations/20260426T081516_taxes_promotions_init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260426T081516_taxes_promotions_init.js","sourceRoot":"","sources":["../../src/migrations/20260426T081516_taxes_promotions_init.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;GAOG;AACH,MAAM,OAAO,2CAA4C,SAAQ,SAAS;IAC/D,KAAK,CAAC,EAAE;QACf,IAAI,CAAC,MAAM,CAAC;;;;;;;;;;;;;;;;KAgBX,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CAAC,4DAA4D,CAAC,CAAC;QAC1E,IAAI,CAAC,MAAM,CACT,mGAAmG,CACpG,CAAC;QAEF,IAAI,CAAC,MAAM,CAAC;;;;;;;;;;;;;;;;;;;;;KAqBX,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CAAC,gEAAgE,CAAC,CAAC;QAC9E,IAAI,CAAC,MAAM,CAAC,sFAAsF,CAAC,CAAC;QACpG,IAAI,CAAC,MAAM,CAAC,0FAA0F,CAAC,CAAC;QACxG,IAAI,CAAC,MAAM,CAAC,0EAA0E,CAAC,CAAC;IAC1F,CAAC;IAEQ,KAAK,CAAC,IAAI;QACjB,IAAI,CAAC,MAAM,CAAC,4CAA4C,CAAC,CAAC;QAC1D,IAAI,CAAC,MAAM,CAAC,uCAAuC,CAAC,CAAC;IACvD,CAAC;CACF"}

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

@@ -0,0 +1,27 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * The `sales_channel_taxes` sales-channel bridge — the tax classes a channel applies.
+ *
+ * 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 `taxes` 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
+ * `taxes` is created inside the frozen prefix, which every
+ * above-watermark migration runs after.
+ */
+export declare class Migration20260912T094654TaxesSalesChannelTaxes extends Migration {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}
+//# sourceMappingURL=20260912T094654_taxes_sales_channel_taxes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"20260912T094654_taxes_sales_channel_taxes.d.ts","sourceRoot":"","sources":["../../src/migrations/20260912T094654_taxes_sales_channel_taxes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,8CAA+C,SAAQ,SAAS;IAC5D,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC;IAmBnB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAGrC"}

package/dist/migrations/20260912T094654_taxes_sales_channel_taxes.js

@@ -0,0 +1,44 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * The `sales_channel_taxes` sales-channel bridge — the tax classes a channel applies.
+ *
+ * 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 `taxes` 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
+ * `taxes` is created inside the frozen prefix, which every
+ * above-watermark migration runs after.
+ */
+export class Migration20260912T094654TaxesSalesChannelTaxes extends Migration {
+    async up() {
+        this.addSql(`
+      create table if not exists "sales_channel_taxes" (
+        "sales_channel_id" uuid not null,
+        "tax_id" uuid not null,
+        constraint "sales_channel_taxes_pkey"
+          primary key ("sales_channel_id", "tax_id"),
+        constraint "sales_channel_taxes_channel_fk"
+          foreign key ("sales_channel_id") references "sales_channels" ("id") on delete cascade,
+        constraint "sales_channel_taxes_tax_fk"
+          foreign key ("tax_id") references "taxes" ("id") on delete cascade
+      );
+    `);
+        this.addSql('create index if not exists "sales_channel_taxes_tax_id_index" ' +
+            'on "sales_channel_taxes" ("tax_id");');
+    }
+    async down() {
+        this.addSql('drop table if exists "sales_channel_taxes" cascade;');
+    }
+}
+//# sourceMappingURL=20260912T094654_taxes_sales_channel_taxes.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"20260912T094654_taxes_sales_channel_taxes.js","sourceRoot":"","sources":["../../src/migrations/20260912T094654_taxes_sales_channel_taxes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,OAAO,8CAA+C,SAAQ,SAAS;IAClE,KAAK,CAAC,EAAE;QACf,IAAI,CAAC,MAAM,CAAC;;;;;;;;;;;KAWX,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CACT,gEAAgE;YAC9D,sCAAsC,CACzC,CAAC;IACJ,CAAC;IAEQ,KAAK,CAAC,IAAI;QACjB,IAAI,CAAC,MAAM,CAAC,qDAAqD,CAAC,CAAC;IACrE,CAAC;CACF"}

package/dist/migrations/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 { Migration20260426T081516TaxesPromotionsInit } from './20260426T081516_taxes_promotions_init.js';
+import { Migration20260912T094654TaxesSalesChannelTaxes } from './20260912T094654_taxes_sales_channel_taxes.js';
+export declare const migrations: (typeof Migration20260426T081516TaxesPromotionsInit)[];
+export { Migration20260426T081516TaxesPromotionsInit, Migration20260912T094654TaxesSalesChannelTaxes, };
+//# 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,2CAA2C,EAAE,MAAM,4CAA4C,CAAC;AACzG,OAAO,EAAE,8CAA8C,EAAE,MAAM,gDAAgD,CAAC;AAEhH,eAAO,MAAM,UAAU,wDAGtB,CAAC;AAEF,OAAO,EACL,2CAA2C,EAC3C,8CAA8C,GAC/C,CAAC"}

package/dist/migrations/index.js

@@ -0,0 +1,31 @@
+/**
+ * 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 { Migration20260426T081516TaxesPromotionsInit } from './20260426T081516_taxes_promotions_init.js';
+import { Migration20260912T094654TaxesSalesChannelTaxes } from './20260912T094654_taxes_sales_channel_taxes.js';
+export const migrations = [
+    Migration20260426T081516TaxesPromotionsInit,
+    Migration20260912T094654TaxesSalesChannelTaxes,
+];
+export { Migration20260426T081516TaxesPromotionsInit, Migration20260912T094654TaxesSalesChannelTaxes, };
+//# 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,2CAA2C,EAAE,MAAM,4CAA4C,CAAC;AACzG,OAAO,EAAE,8CAA8C,EAAE,MAAM,gDAAgD,CAAC;AAEhH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,2CAA2C;IAC3C,8CAA8C;CAC/C,CAAC;AAEF,OAAO,EACL,2CAA2C,EAC3C,8CAA8C,GAC/C,CAAC"}

package/docs/taxes.md

@@ -0,0 +1,75 @@
+---
+title: taxes
+description: Tax-rate resolver narrowed by country / product type / VAT status
+---
+
+# `taxes`
+
+Tax-rate resolution. Each `Tax` row is a rule
+narrowed by zero or more of `country`, `productType`, `appliesToVatStatuses`.
+
+## Public surface
+
+| Verb + Path | Audience | Purpose |
+| --- | --- | --- |
+| `GET /api/v1/admin/taxes` | admin (`taxes:read`) | List rules |
+| `PUT /api/v1/admin/taxes/:code` | admin (`taxes:write`) | Upsert |
+| `DELETE /api/v1/admin/taxes/:id` | admin (`taxes:write`) | Remove |
+| `GET /api/v1/admin/taxes/preview?country&productType&vatStatus` | admin (`taxes:read`) | Resolve effective rate |
+
+Every one of the four enforced `catalog:write` until 2026-08-28 — the two reads
+included, so seeing a VAT rate required the authority to change it. The module
+now owns `taxes:read` and `taxes:write`, declared in its manifest and therefore
+grantable on `/admin-roles`. It is a **clean break**: a role that reached the tax
+table through the catalogue's write code is granted `taxes:read` (and
+`taxes:write`, to edit) explicitly. See
+`backend/test/contract/taxes/permission-authority.test.ts`.
+
+Nothing else reads a rate through these routes: `orders`, `carts`,
+`product_feeds` and `quote_requests` resolve one in process through the
+`taxService` port, which the permission change does not touch.
+
+## Resolution algorithm
+
+`TaxService.taxRateFor({ country, productType, vatStatus })`:
+
+1. A rule **matches** when each narrowing field is either null
+   (unconstrained) or equal to the input.
+2. Among matching rules, the one with the **most narrowed fields** wins.
+3. Specificity ties → `priority` desc → `createdAt` asc.
+4. When no rule matches, the row with `isDefault=true` wins.
+5. When no default exists either, the resolver returns `{ source: 'none' }` —
+   an answer with **no `rate` field at all**.
+
+Point 5 is a type, not a convention. A configured 0% rate is a
+legitimate answer in some jurisdictions, so it comes back as
+`{ source: 'default', rate: 0, taxId }` and prices an order like any other rate.
+"Nothing is configured" is not an answer, so it carries no number a caller could
+spend by accident: `ResolvedTax` is a discriminated union and `.rate` does not
+compile until the caller narrows on `source`. The two used to share one shape,
+`{ rate: 0, source: 'none' }`, and every consumer read `.rate` — which is how an
+unconfigured deployment quoted 0% VAT onto real invoices.
+
+A third state — the `taxes` module being absent — is deliberately not in the
+union. Absence is not a value: the port gate raises the 503 `MODULE_DISABLED`
+envelope before a resolution runs, so an order the platform cannot tax is
+refused rather than taxed at a figure nobody chose.
+
+The "at most one default" invariant is enforced by a partial unique index
+`(is_default) WHERE is_default = true`. `upsertByCode` demotes any prior
+default before promoting the new one so the swap stays consistent.
+
+## Entities
+
+`Tax` — `code`, `name`, `rate` (0..1), nullable `country` /
+`productType`, JSONB `appliesToVatStatuses`, `isDefault`, `priority`.
+
+## Extension points
+
+- **VAT-OSS / one-stop-shop** — model the buyer's status separately and
+  emit different rates per country pair.
+- **Reduced-rate triggers** — the `appliesToVatStatuses` array is the
+  natural place to add buyer-side discriminators (e.g. consumer vs B2B).
+- **Per-currency rates** — today the rate is currency-agnostic. For VAT
+  in different reporting currencies, add a `currency` column and route
+  the resolver based on the order's currency.

package/i18n/en.json

@@ -0,0 +1,3 @@
+{
+  "nav.taxes.label": "Taxes"
+}

package/i18n/pl.json

@@ -0,0 +1,3 @@
+{
+  "nav.taxes.label": "Podatki"
+}