@hartl-services/medusa-base 2.10.0 → 3.0.0

package/README.md

@@ -6,8 +6,10 @@ Admin hub under **Settings → Hartl Services Plugins** with one page per
 plugin, a Store endpoint for storefronts and helpers that plugins use to
 enforce their toggles and read their settings. Since 1.0.0 it also contains
 the shop's transactional E-Mail, order Documents (invoices, cancellations,
-packing lists) and S3 file storage, and the turnkey `medusa-config.ts` preset
-(see "E-Mail", "Dokumente", "Dateispeicher (S3)" and "Shop-Config-Preset").
+packing lists) and S3 file storage, and the turnkey `medusa-config.ts` preset,
+and since 3.0.0 the EU tax compliance (UID check, Tax provider) (see "E-Mail",
+"Dokumente", "Steuer-Compliance", "Dateispeicher (S3)" and
+"Shop-Config-Preset").
 
 ## What it does
 
@@ -54,6 +56,10 @@ packing lists) and S3 file storage, and the turnkey `medusa-config.ts` preset
   "E-Mail"), issues invoices, cancellation documents and packing lists as
   private PDFs (module `documents`, see "Dokumente") and stores files in
   S3-compatible storage behind the `/files` gateway (see "Dateispeicher (S3)").
+- Checks B2B customers' VAT IDs (FinanzOnline), provides the Medusa Tax
+  provider `tp_tax_compliance` for reverse-charge and apportioned shipping tax
+  and freezes the tax evidence of an order at checkout (module
+  `tax_compliance`, see "Steuer-Compliance").
 - Declares which login methods customers may use (module `customer_auth`:
   e-mail + password and a one-time code by e-mail), provides the `email-otp`
   auth provider and the code request route (see "Kunden-Login").
@@ -116,6 +122,17 @@ exports from the matching `@hartl-services/medusa-base` subpath. The
 `documentsEnabled` option is gone; Documents is always installed, and the
 e-mail module follows the Documents `invoices` toggle.
 
+Upgrading to 3.0.0 (Steuer-Compliance merged): remove
+`@hartl-services/medusa-tax-compliance` from `package.json` and from the
+`plugins` list and change the Tax provider resolve path to
+`@hartl-services/medusa-base/providers/tax-compliance` (the provider id
+`tp_tax_compliance`, the module key `tax_compliance`, its tables and
+migrations are unchanged, so no data migration is needed). Plugins that
+reached `tax_compliance` by container key keep working; the typed helper is
+`listCustomerAddressTaxIdentifications` (see "Steuer-Compliance"). The other
+Hartl Services plugins need the versions released with 3.0.0 (their peer
+range is `^3`).
+
 Peer dependencies are the host's Medusa 2.19 packages (`@medusajs/framework`,
 `@medusajs/medusa`, `@medusajs/admin-sdk`, `@medusajs/js-sdk`, `@medusajs/ui`, `@medusajs/icons`)
 plus React, React Router and TanStack Query in the versions the Medusa 2.19
@@ -927,7 +944,7 @@ class MyModuleService extends MedusaService({ /* … */ }) {
 
 **Ordering.** Ascending `order`, then module key, then workflow id. In use:
 Affiliate 100 (`affiliate-validate-complete-cart`,
-`finalize-affiliate-order-attribution`), tax compliance 200
+`finalize-affiliate-order-attribution`), the base's Steuer-Compliance 200
 (`freeze-tax-compliance-order-evidence`, `orderCreated` only).
 
 **Rollback semantics.**
@@ -1436,6 +1453,11 @@ Options of the `email` namespace:
   `orderNotificationEmail` mailbox. `verifyAccountUrl` (optional builder,
   like `passwordResetUrl`; the mail appends `#token=`) is the storefront page
   that confirms an account, needed while `customer_verification` is on.
+  `adminPasswordResetUrl` (optional builder, receives `{ token }`) is the
+  Medusa Admin's "choose a new password" page; without it an Admin user's
+  password reset fails with `render_failed`. `buildFoodShopConfig` sets
+  `<MEDUSA_BACKEND_URL>/app/reset-password?token=<token>` (the dashboard reads
+  the token from the query).
   `adminAffiliateApplicationsUrl` (optional builder, receives
   `{ applicationId }`) is the Admin page of the partner applications; the
   notification about a new application shows its "Im Admin prüfen" button
@@ -1539,7 +1561,7 @@ feature is switched on again.
 | --------------------- | ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------- |
 | (plugin switch)       | E-Mail                 | on      | every route under `/admin/email/*` (mail log, resends, attachments; 404); jobs `email-reconcile-attempts`, `email-reconcile-pending-messages`, `email-retry-messages`; every feature below                            | checkout and orders; already queued messages stay stored |
 | `order_mails`         | Bestell-Mails          | on      | subscribers `order-placed`, `email-shipment-created`, `email-order-canceled`, `return-requested`, `return-received`, `documents-shipment-invoice-assignment-decided`, `documents-order-cancellation-ready`, `documents-refund-ready`; route `/admin/draft-orders/:id/order-confirmation` (404) and its draft-order widget | jobs, Admin routes, already created messages             |
-| `account_mails`       | Konto-Mails            | on      | subscribers `password-reset`, `user-invite`, `customer-verification` (the last one only with `customer_verification` on as well); not the login code mail, which depends on neither this feature nor the plugin switch (see "Kunden-Login") | jobs, Admin routes, already created messages             |
+| `account_mails`       | Konto-Mails            | on      | subscribers `password-reset` (customers and Admin users), `user-invite`, `customer-verification` (the last one only with `customer_verification` on as well); not the login code mail, which depends on neither this feature nor the plugin switch (see "Kunden-Login") | jobs, Admin routes, already created messages             |
 | `customer_verification` | Kontobestätigung per E-Mail | off | Medusa's e-mail verification of customer logins (see "Kontobestätigung per E-Mail"), route `POST /store/customer-verification/resend` (404 while off), subscriber `customer-verification`; child of `account_mails` | checkout and orders; confirmed accounts stay confirmed, already created messages |
 | `affiliate_reminders` | Affiliate-Mails        | on      | subscribers `affiliate-consignment-reminder-due` (reminders to affiliates) and `affiliate-application-submitted` (notification to the shop about a new partner application)                                              | jobs, Admin routes, already created messages             |
 
@@ -1826,9 +1848,10 @@ has at most 35 characters. Email runtime-validates every contract before use.
 
 - The accepted kinds are exactly `order.received`, `order.received.admin`, `order.shipped`,
   `order.canceled`, `order.return_requested`, `order.return_received`,
-  `order.refunded`, `auth.password_reset`, `auth.verification`,
-  `auth.login_code`, `affiliate.consignment_report_due`,
-  `affiliate.application_submitted.admin` and `user.invite`.
+  `order.refunded`, `auth.password_reset`, `auth.admin_password_reset`,
+  `auth.verification`, `auth.login_code`, `affiliate.consignment_report_due`,
+  `affiliate.application_submitted.admin`, `user.invite` and
+  `system.credential_expiry.admin`.
 - Every automatic message has a deterministic business key.
 - Every placed Order creates independent customer and Shop intents. The customer
   intent honors `no_notification`; the Shop intent always targets the static
@@ -1914,7 +1937,7 @@ an info box lists number, customer, e-mail and order time, followed by an
 button is left out without it) and `timeZone` (IANA; the order time is left
 out without it). `buildFoodShopConfig` sets both (`<MEDUSA_BACKEND_URL>/app/
 orders/<id>` and its `timeZone` option). The layout receives `audience`
-(`"shop"` for this kind, `affiliate.application_submitted.admin` and `user.invite`, `"customer"` for all others) and
+(`"shop"` for this kind, `affiliate.application_submitted.admin`, `system.credential_expiry.admin`, `user.invite` and `auth.admin_password_reset`, `"customer"` for all others) and
 shows the contact line only to customers.
 
 The shipping confirmation (`order.shipped`, one per fulfillment) receives a
@@ -1978,6 +2001,20 @@ without `iat`) and a note that the mail can be ignored. The lifetime is
 passed as the ephemeral `valid_minutes` next to `reset_url` and is never
 persisted.
 
+The same Medusa event with `actor_type: "user"` (the Admin's "Passwort
+zurücksetzen" at `/app/reset-password`) becomes its own kind,
+`auth.admin_password_reset`, with its own Admin template: subject "Neues
+Passwort für den Admin-Bereich von <displayName>", the same button, link text,
+lifetime and ignore note, and the link from `adminPasswordResetUrl` (the token
+in the query). It is sent only when exactly one Admin user has the address:
+the `emailpass` identity is shared by all actor types, so a customer could ask
+for an Admin reset of their own identity, and that request is ignored
+(`no_admin_user`). A token whose `actor_type` differs from the event's is
+ignored as `invalid_token`; every other actor type stays `invalid_event`. Like
+the customer reset it is gated by `account_mails`, ephemeral (never resent or
+retried by the generic job) and stored with `resource_type` `"user"`; its
+layout audience is `"shop"`.
+
 The account confirmation (`auth.verification`) has the subject "Bestätige
 deine E-Mail-Adresse", a "E-Mail-Adresse bestätigen" button, the link as
 copyable text, a note that the link is only valid for a limited time (a new
@@ -2433,13 +2470,9 @@ separate documents package since 1.0.0.
 
 ### Configuration
 
-`@hartl-services/medusa-tax-compliance` is a required *registered plugin*,
-intentionally not a package dependency of the base: install it and list it in
-`medusa-config.ts` yourself. The invoice workflow resolves the
-`tax_compliance` module with no fallback; a shop that does not register Tax
-Compliance fails at invoice issuance time (the first `shipment.created`
-event) with an `UNEXPECTED_STATE` error naming the missing plugin, not at
-startup.
+The invoice workflow reads the order's frozen B2B evidence from the base's own
+`tax_compliance` module (see "Steuer-Compliance"); register the Tax provider
+`@hartl-services/medusa-base/providers/tax-compliance` as shown there.
 
 ```ts
 export default defineConfig({
@@ -2448,10 +2481,7 @@ export default defineConfig({
       resolve: "@medusajs/medusa/tax",
       options: {
         providers: [
-          {
-            resolve:
-              "@hartl-services/medusa-tax-compliance/providers/tax-compliance",
-          },
+          { resolve: "@hartl-services/medusa-base/providers/tax-compliance" },
         ],
       },
     },
@@ -2470,10 +2500,6 @@ export default defineConfig({
         },
       },
     },
-    {
-      resolve: "@hartl-services/medusa-tax-compliance",
-      options: {},
-    },
   ],
 });
 ```
@@ -2588,7 +2614,8 @@ medusa-config fallback: what is stored in the Admin is what is printed.
 
 Requirements/couplings:
 
-- A registered Tax Compliance module (`tax_compliance`) as shown above.
+- The Tax provider `tp_tax_compliance` of the base's Steuer-Compliance on the
+  regions, so orders carry UID-based exemptions.
 - A Chromium/Chrome executable and a Medusa File provider that supports
   private files (see "Development" below for the sandbox/non-root note).
   Documents stores PDFs through `Modules.FILE` and streams them only through
@@ -3058,6 +3085,322 @@ const response = await sdk.client.fetch<ListAdminOrderPackingListsResponse>(
 );
 ```
 
+## Steuer-Compliance
+
+There is no separate `@hartl-services/medusa-tax-compliance` package since
+3.0.0: the EU tax compliance (module `tax_compliance`, the Tax Module provider
+`tp_tax_compliance`, the UID check routes, the order-evidence freeze and the
+apportioned shipping tax) is part of the base. The module owns the durable
+validation evidence; a Storefront never imports its implementation, only
+`@hartl-services/medusa-food-supplements-contracts`.
+
+### Configuration
+
+Register the Tax Module provider in `medusa-config.ts` (the Shop-Config-Preset
+does this); the module itself boots with the base and has no options:
+
+```ts
+modules: [
+  {
+    resolve: "@medusajs/medusa/tax",
+    options: {
+      providers: [
+        { resolve: "@hartl-services/medusa-base/providers/tax-compliance" },
+      ],
+    },
+  },
+],
+```
+
+The provider is configured without a secondary `id`, so Medusa registers its
+class identifier `tax_compliance` as exactly `tp_tax_compliance`; regions
+select it as their tax provider. `medusa db:migrate` creates the tables
+`tax_compliance_validation` and `tax_compliance_state` (unchanged names and
+migrations of the former package, so an upgraded shop needs no data
+migration).
+
+The merchant's own country and VAT number come only from the Shop-Stammdaten
+(fields `country_code` and `vat_number`); there is no config fallback. They
+select the qualified VAT validator (currently only the Austrian FinanzOnline
+adapter). While either is missing, carts get ordinary B2C tax.
+
+### Runtime settings
+
+Declared on the Steuer-Compliance descriptor and edited on its Admin page
+(Settings → Hartl Services Plugins → Steuer-Compliance):
+
+| Key                           | Label          | Type   | Required |
+| ----------------------------- | -------------- | ------ | -------- |
+| `finanzonline_participant_id` | Teilnehmer-ID  | string | yes      |
+| `finanzonline_user_id`        | Benutzer-ID    | string | yes      |
+| `finanzonline_password`       | PIN            | secret | yes      |
+
+All three sit in the group "FinanzOnline" ("Webservice-Benutzer für die
+qualifizierte UID-Abfrage.").
+
+- Read per validation, only for an Austrian merchant with a real UID. There
+  is no environment or medusa-config fallback; `FINANZONLINE_*` variables are
+  ignored.
+- All three are needed as a set. While any is missing the plugin page shows
+  "nicht konfiguriert", one warning is logged per process and not-configured
+  state, and the qualified check answers `unavailable`
+  (`missing_credentials`) without calling FinanzOnline.
+- A failing settings read is logged (`logger.error`, reported to Sentry by
+  the base logger wrapper) and handled like missing credentials.
+- Merchant country and UID are read from the shop master data. On the cart
+  tax path (tax-context hook) and in the Store route a failing read is logged
+  and treated as "no merchant": ordinary B2C tax, and the route answers 500
+  as before for a missing merchant profile. The cart tax path and the
+  order-evidence freeze read the master data only for a cart that has a
+  current UID validation record, so B2C carts never touch the settings and
+  an outage does not log an error per tax calculation. The order-evidence
+  freeze at checkout lets a read failure propagate, so a zero-rated order
+  fails and an ordinarily taxed one continues.
+- Both are read at app level, never by the module service (a module does not
+  reach into other modules): `src/tax-compliance/lib/tax-runtime-settings.ts`
+  provides `resolveMerchantProfile(container, { failSafe })` and
+  `resolveFinanzOnlineCredentials(container)`, called with the application
+  container of the Store route, the validation and freeze workflow steps and
+  the cart tax-context hook. The service takes the results as parameters:
+  `validateCart(input, credentials)` (the step reads the credentials only
+  when `requiresFinanzOnlineCredentials(input)` says so, and never passes
+  them as workflow input), `getCurrentValidationId(cart, loadMerchant)` and
+  `freezeOrderEvidence(orderId, cart, loadMerchant)` (the loader runs only
+  after a current validation record was found) and
+  `isValidationEligibleForTax(validationId, countryCode, merchant)`.
+- The cart tax-context hook puts the merchant profile it checked the
+  evidence against into `additional_context.tax_compliance_merchant`, next to
+  the validation ID. The tax provider runs in the Tax Module's isolated
+  container and reads the merchant only from that context; without one it
+  answers ordinary B2C rates. The order tax path needs no merchant: it checks
+  the evidence frozen under the order ID.
+
+### Feature toggles
+
+Steuer-Compliance declares its switch and three features under the plugin key
+`tax_compliance` (`TAX_COMPLIANCE_PLUGIN_KEY` / `TAX_COMPLIANCE_FEATURES` from
+the Contracts `/paths/tax-compliance` subpath). An Admin switches them under
+Settings → "Hartl Services Plugins"; Storefronts read the effective values
+from `GET /store/plugin-features/tax_compliance`. All features default to on.
+The plugin switch off counts as all three features off.
+
+| Key              | Label                    | Default | Off means                                                                                                                                                                                                                                               |
+| ---------------- | ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `vat_validation` | UID-Prüfung erlauben     | on      | `POST /store/customers/me/addresses/:address_id/tax-identification`, `GET /store/customers/me/tax-identifications` and the Admin re-check answer 404; Affiliate partner registration takes VAT IDs unchecked. Also switches `b2b` off. The FinanzOnline settings are dimmed. |
+| `b2b`            | B2B-Verkauf im Checkout  | on      | `POST /store/carts/:id/tax-identification` answers 404 (before body validation); carts get no reverse charge, even with evidence checked earlier today; completing an ordinarily taxed order freezes no evidence. Child of `vat_validation`. Storefronts keep the company name and hide the VAT id. |
+| `shipping_tax`   | Versandsteuer-Compliance | on      | Shipping is taxed at the shipping option's own rate (Medusa's default) instead of the net-value-weighted item rate, for carts and order recalculations.                                                                                                  |
+
+With `shipping_tax` on, a cart with items at several rates gets one shipping
+tax line "Anteilige Versandsteuer" (code `APPORTIONED_SHIPPING_TAX_CODE` from
+`/lib`) at the items' rates weighted by their net amount after discounts
+(computed like Medusa's line totals), which yields the same tax as splitting
+the shipping by that amount onto each rate. Medusa taxes a cart before it
+applies promotions and a code redeemed through `POST /store/carts/:id/promotions`
+recalculates no tax, so the cart's rate can lag behind its discounts; the
+`orderCreated` participant therefore sets the order's rate again from its
+final discounts (tax-inclusive shipping only, whose paid gross amount stays
+the same; on error the order keeps the cart's rate and a warning is logged).
+Medusa stores the rate with six decimals. The invoice (see "Dokumente")
+splits that line back onto the item rates by the same key.
+
+`GET /store/tax-identification-policy` follows only the plugin switch.
+Evidence frozen under an order that was zero-rated keeps counting for that
+order whatever the toggles say now.
+
+The tax hooks and the order-evidence freeze never read a toggle. The
+`tax_compliance_state` row mirrors the effective `b2b` and `shipping_tax`
+values; the `plugin-features.updated.v1` subscriber and the
+`tax-compliance-state-sync` job (every 5 minutes) write it. Before the first
+sync (no row) both count as on; when the row cannot be read both count as
+off (ordinary B2C rates, Medusa's shipping tax).
+
+### UID check in the checkout
+
+Public Store request, response, schema, and path imports belong to
+`@hartl-services/medusa-food-supplements-contracts`:
+
+```ts
+import type { SubmitTaxIdentificationResponse } from "@hartl-services/medusa-food-supplements-contracts/types/tax-compliance-store";
+import { taxCompliancePaths } from "@hartl-services/medusa-food-supplements-contracts/paths/tax-compliance";
+
+const result = await sdk.client.fetch<SubmitTaxIdentificationResponse>(
+  taxCompliancePaths.store.carts.taxIdentification(cartId),
+  { method: "POST", body: {} },
+);
+```
+
+The module persists normalized cart validation evidence and selects qualified
+VAT validators by merchant country. Austrian merchants use the isolated
+FinanzOnline stage-2 adapter. Missing credentials, the development UID
+placeholder `ATU00000000`, technical/rate-limit responses, and unsupported
+merchant countries produce local `unavailable` evidence. Tax calculation
+interprets missing, stale, invalid, ineligible, and unavailable evidence as the
+normal B2C outcome. Cart tax calculation only accepts same-day `eligible`
+evidence whose current cart and merchant fingerprints still match, whose UID
+prefix matches the delivery country, and whose delivery country is
+cross-border. Once evidence is frozen, order tax calculation instead verifies
+the exact evidence-ID/order-ID binding and its frozen facts; it deliberately
+does not reopen current-cart or current-day eligibility. Eligible calculations
+receive explicit zero-percent item and shipping tax lines.
+
+`ATU00000000` is a development-only Austrian UID placeholder: the registry
+treats it as missing (`merchant_uid_sentinel`, never sent to FinanzOnline)
+and Documents never prints it. Enter the real UID in the Shop-Stammdaten
+before issuing production invoices.
+
+The Store route is:
+
+```text
+POST /store/carts/:id/tax-identification
+```
+
+The UID belongs to the cart's billing address: company plus
+`metadata.vat_number` (`TAX_IDENTIFICATION_METADATA_KEY`), set by the
+storefront like any other address field, for guests too. The cart evidence
+fingerprint reads the UID from the current billing address, so changing or
+removing it ends the exemption. Medusa itself recomputes taxes only when the
+shipping address changes, so a storefront calls this route (empty body) after
+the addresses changed and before it initiates payment.
+
+It requires a publishable key scoped to the cart's sales channel. With a UID
+on a billing address outside the merchant country (Shop-Stammdaten) it
+performs one qualified validation; without one, or for a company in the
+merchant country, it answers `status: null` without any query and only
+recomputes when the cart still has a current check record (an earlier
+exemption falls away). It then forces tax-line recomputation, reconciles an
+existing payment collection with the new cart total, and returns only the
+public status, optional user message, and safe cart totals. The deprecated
+body (`company_name` and `vat_number` together) is still accepted: the route
+writes both into the billing address first. Provider facts, evidence IDs,
+credentials, sessions, and SOAP data are never part of the response. When the
+total changed, the reconciliation deletes the cart's payment sessions, so a
+storefront re-initiates payment after the call.
+
+The adapter requires a dedicated FinanzOnline web-service user whose
+credentials are entered as runtime settings (see above). The PIN is stored
+encrypted and never sent to the Admin or a Storefront. SOAP clients are
+validation-scoped, scrub their node-soap transport state after every
+operation, and always attempt logout after a successful login. Every
+`unavailable` answer from the adapter logs one warning with the failing step
+(login or UID query) and FinanzOnline's return code and message, or the
+exception message (PIN masked), so a rejected web-service user shows up in
+the server log while the shopper only sees the generic message. Same-day
+provider facts are serialized and reused by normalized merchant UID, customer
+UID, and UTC date across carts and saved addresses. Every subject still
+receives its own evidence row and fingerprint; changed company or address
+submissions are re-evaluated locally against the structured provider facts
+without another remote request. Only records FinanzOnline actually answered
+for (provider facts, valid or not) are reused: an `unavailable` without an
+answer (missing credentials, the placeholder UID, an outage or login failure)
+is checked again on the next submission instead of blocking the UID for the
+rest of the day. Transaction-scoped PostgreSQL advisory locks cover both the
+normalized subject and the UID/day reuse key. Partial unique indexes permit
+only one current evidence row per cart and per saved address, while a
+separate lookup index supports cross-subject reuse.
+
+A domestic company never qualifies for a tax-free intra-Community supply, so
+its UID is neither checked nor stored as evidence. Storefronts ask for the UID
+only outside the merchant country and read that country from:
+
+```text
+GET /store/tax-identification-policy   →   { merchant_country_code: "at" | null }
+```
+
+`null` while the master data name no country (or cannot be read): the
+storefront then asks for every country.
+
+```ts
+import type { GetTaxIdentificationPolicyResponse } from "@hartl-services/medusa-food-supplements-contracts/types/tax-compliance-store";
+import { taxCompliancePaths } from "@hartl-services/medusa-food-supplements-contracts/paths/tax-compliance";
+
+const { merchant_country_code } = await sdk.client.fetch<GetTaxIdentificationPolicyResponse>(
+  taxCompliancePaths.store.taxIdentificationPolicy,
+  { method: "GET" },
+);
+```
+
+Login and UID query share a 10 s budget (WSDL downloads included) and logout
+gets 3 s, so the request stays below a storefront's 15 s checkout wait and the
+database transaction holding the UID lock never waits on a hanging
+FinanzOnline call; a timeout answers `unavailable` (`technical_error`).
+
+### Saved customer addresses
+
+A saved customer address carries its UID in `metadata.vat_number`
+(`TAX_IDENTIFICATION_METADATA_KEY` in the Contracts). A logged-in customer
+checks it with
+
+```text
+POST /store/customers/me/addresses/:address_id/tax-identification
+GET  /store/customers/me/tax-identifications
+```
+
+Company, UID and address are read from the stored address, never from the
+request; the address's own country stands in for the delivery country.
+`verified` (status `eligible` or `ineligible`) means the UID is real and
+matches company and address. The GET route only reports evidence whose
+fingerprint still matches the address as it is now: editing company, UID or
+address drops the status until the address is checked again. Metadata alone
+never proves a check. Both routes follow the `vat_validation` feature (404
+while off) and require a customer login.
+
+Other plugins read the same current evidence, whatever its status (also
+`unavailable` and `invalid`), through
+`listCustomerAddressTaxIdentifications(container, customerId)` from
+`@hartl-services/medusa-base` (typed `CustomerAddressTaxIdentification` with
+the checked `billing_address`); the caller decides with
+`isPluginFeatureEnabledByKey(container, "tax_compliance", "vat_validation")`
+whether the check is on. The Affiliate partner registration uses it.
+
+An Admin checks any customer's saved address again with
+
+```text
+POST /admin/tax-compliance/customer-addresses/:address_id/tax-identification
+```
+
+(admin login, `vat_validation` feature; answers like the Store route,
+`SubmitCustomerAddressTaxIdentificationResponse`, path
+`taxCompliancePaths.admin.customerAddressTaxIdentification(addressId)`). The
+Affiliate plugin uses it to re-check a partner application whose check was
+unavailable.
+
+All three FinanzOnline settings are required as a set. Otherwise the service
+stores `unavailable` evidence and checkout continues with B2C tax; the Store
+response returns the checkout warning "Die UID-Prüfung ist derzeit nicht
+verfügbar. Bitte versuchen Sie es später erneut." Invalid or ineligible B2B
+facts likewise receive ordinary B2C tax, without a warning. The registry is
+country-based: it currently provides only the Austrian FinanzOnline adapter;
+an unsupported merchant country deliberately resolves to `unavailable`.
+
+### Frozen order evidence
+
+Cart tax workflows pass only the opaque current evidence ID and the merchant
+profile (country and UID) to the provider. Order tax workflows use evidence
+frozen under the order ID by the workflow
+`freeze-tax-compliance-order-evidence`, which the base runs as an
+`orderCreated` participant with `order` 200 (see "Complete-cart hook
+composition"), after Affiliate's attribution (100) when Affiliate is
+installed. After the freeze the same workflow sets the order's apportioned
+shipping rate from its final discounts (see "Feature toggles" above).
+Compensation runs in reverse (tax, then Affiliate); if the freeze fails, the
+base cancels Affiliate's already finished attribution. Tax-only module lookup
+and context failures remain fail-closed to ordinary B2C. The freeze step
+decides itself whether a failure is fatal: an auxiliary freeze failure is
+logged and contained for an ordinarily taxed B2C cart, but a zero-rated cart
+cannot complete unless its evidence was durably frozen under the order ID.
+Zero-rated means the provider set a line to 0 % although its configured tax
+rate is not 0 % (UID-based exemption); a line that is 0 % because its
+configured tax rate is 0 % (e.g. the small-business exemption) is ordinary
+taxation and needs no evidence. Freeze-compensation persistence failures are
+logged and propagated so workflow cancellation stays failed instead of
+silently leaving a stale order binding.
+
+Documents reads that frozen eligible B2B evidence when an invoice is issued,
+so the document snapshot contains the company, customer UID and exemption
+wording from the completed order (see "Dokumente"). A later cart change or
+validation cannot alter an already issued document; B2C, invalid, ineligible
+and unavailable evidence adds no tax-proof wording.
+
 ## Dateispeicher (S3)
 
 The base provides a Medusa File Module provider for durable S3-compatible
@@ -3299,15 +3642,14 @@ loads the Sentry logger wrapper and with it `@sentry/node`; `/config` stays
 free of it.
 
 The preset registers the base (with its E-Mail, Documents and `/files`
-options) plus five feature plugins, in this order: `medusa-base`,
-`medusa-tax-compliance`, `medusa-free-shipping`, `medusa-batch-management`,
+options, and its Tax provider) plus four feature plugins, in this order:
+`medusa-base`, `medusa-free-shipping`, `medusa-batch-management`,
 `medusa-affiliate`, `medusa-payload-sync`.
 
 ### Installation in a shop
 
 ```bash
 pnpm add @hartl-services/medusa-base \
-  @hartl-services/medusa-tax-compliance \
   @hartl-services/medusa-free-shipping \
   @hartl-services/medusa-batch-management \
   @hartl-services/medusa-affiliate \

package/dist/email/types/email-kinds.d.ts

@@ -1,5 +1,5 @@
 import { z } from "@medusajs/framework/zod";
-export declare const EMAIL_KINDS: readonly ["order.received", "order.received.admin", "order.shipped", "order.canceled", "order.return_requested", "order.return_received", "order.refunded", "auth.password_reset", "affiliate.consignment_report_due", "affiliate.application_submitted.admin", "user.invite", "auth.verification", "auth.login_code", "system.credential_expiry.admin"];
+export declare const EMAIL_KINDS: readonly ["order.received", "order.received.admin", "order.shipped", "order.canceled", "order.return_requested", "order.return_received", "order.refunded", "auth.password_reset", "affiliate.consignment_report_due", "affiliate.application_submitted.admin", "user.invite", "auth.verification", "auth.login_code", "system.credential_expiry.admin", "auth.admin_password_reset"];
 export declare const EmailKindSchema: z.ZodEnum<{
     "order.received": "order.received";
     "order.received.admin": "order.received.admin";
@@ -15,6 +15,7 @@ export declare const EmailKindSchema: z.ZodEnum<{
     "auth.verification": "auth.verification";
     "auth.login_code": "auth.login_code";
     "system.credential_expiry.admin": "system.credential_expiry.admin";
+    "auth.admin_password_reset": "auth.admin_password_reset";
 }>;
 export type EmailKind = (typeof EMAIL_KINDS)[number];
 /**
@@ -22,5 +23,5 @@ export type EmailKind = (typeof EMAIL_KINDS)[number];
  * subscriber builds the mail from the event, so neither the generic retry
  * job, the automatic dispatch nor an Admin resend may touch them.
  */
-export declare const EPHEMERAL_EMAIL_KINDS: readonly ["auth.password_reset", "auth.verification", "auth.login_code"];
+export declare const EPHEMERAL_EMAIL_KINDS: readonly ["auth.password_reset", "auth.admin_password_reset", "auth.verification", "auth.login_code"];
 export declare const isEphemeralEmailKind: (kind: EmailKind) => boolean;

package/dist/email/types/email-kinds.js

@@ -17,6 +17,7 @@ exports.EMAIL_KINDS = [
     "auth.verification",
     "auth.login_code",
     "system.credential_expiry.admin",
+    "auth.admin_password_reset",
 ];
 exports.EmailKindSchema = zod_1.z.enum(exports.EMAIL_KINDS);
 /**
@@ -26,6 +27,7 @@ exports.EmailKindSchema = zod_1.z.enum(exports.EMAIL_KINDS);
  */
 exports.EPHEMERAL_EMAIL_KINDS = [
     "auth.password_reset",
+    "auth.admin_password_reset",
     "auth.verification",
     "auth.login_code",
 ];

package/dist/email/types/shop-configuration.d.ts

@@ -48,6 +48,14 @@ export type ShopEmailConfiguration = Readonly<{
     adminAffiliateApplicationsUrl?: (input: Readonly<{
         applicationId: string;
     }>) => string;
+    /**
+     * The Medusa Admin's "choose a new password" page with the reset token
+     * (`/app/reset-password?token=<token>`). Without it an Admin user's
+     * password reset sends no mail.
+     */
+    adminPasswordResetUrl?: (input: Readonly<{
+        token: string;
+    }>) => string;
     affiliatePortalUrl: string;
     displayName: string;
     inviteUrl: (input: Readonly<{

package/dist/email/types/template-data.d.ts

@@ -381,6 +381,7 @@ export declare const EmailPersistedDataSchemas: {
         client_id: z.ZodString;
         expires_on: z.ZodString;
     }, z.core.$strict>;
+    readonly "auth.admin_password_reset": z.ZodObject<{}, z.core.$strict>;
 };
 export declare const EmailRenderDataSchemas: {
     readonly "auth.password_reset": z.ZodObject<{
@@ -388,6 +389,10 @@ export declare const EmailRenderDataSchemas: {
         reset_url: z.ZodString;
         valid_minutes: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>;
+    readonly "auth.admin_password_reset": z.ZodObject<{
+        reset_url: z.ZodString;
+        valid_minutes: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
     readonly "user.invite": z.ZodObject<{
         invite_url: z.ZodString;
         expires_at: z.ZodOptional<z.ZodString>;
@@ -635,7 +640,7 @@ export type EmailPersistedDataMap = {
 };
 type EmptyRenderContext = Readonly<Record<never, never>>;
 export type EmailEphemeralRenderContextMap = {
-    readonly [Kind in EmailKind]: Kind extends "auth.password_reset" ? Readonly<{
+    readonly [Kind in EmailKind]: Kind extends "auth.password_reset" | "auth.admin_password_reset" ? Readonly<{
         reset_url: string;
         valid_minutes?: number;
     }> : Kind extends "user.invite" ? Readonly<{

package/dist/email/types/template-data.js

@@ -240,6 +240,8 @@ exports.EmailPersistedDataSchemas = {
         expires_on: affiliate_1.CalendarDateSchema,
     })
         .strict(),
+    // The Admin dashboard is German only, so no locale; the link is ephemeral.
+    "auth.admin_password_reset": zod_1.z.object({}).strict(),
 };
 exports.EmailRenderDataSchemas = {
     ...exports.EmailPersistedDataSchemas,
@@ -248,6 +250,11 @@ exports.EmailRenderDataSchemas = {
         /** How long the reset link is valid, from the token; `undefined` if unknown. */
         valid_minutes: zod_1.z.number().int().positive().optional(),
     }),
+    "auth.admin_password_reset": exports.EmailPersistedDataSchemas["auth.admin_password_reset"].extend({
+        reset_url: zod_1.z.string().url(),
+        /** How long the reset link is valid, from the token; `undefined` if unknown. */
+        valid_minutes: zod_1.z.number().int().positive().optional(),
+    }),
     "user.invite": exports.EmailPersistedDataSchemas["user.invite"].extend({
         invite_url: zod_1.z.string().url(),
         /** When the invite expires (ISO 8601), from the current invite. */

package/dist/public/constants.d.ts

@@ -1,2 +1,4 @@
 /** Container key of the base plugin's module (`Module("plugin_features", …)`). */
 export declare const PLUGIN_FEATURES_MODULE: "plugin_features";
+/** Container key of the base plugin's Steuer-Compliance module (`Module("tax_compliance", …)`). */
+export declare const TAX_COMPLIANCE_MODULE: "tax_compliance";

package/dist/public/constants.js

@@ -1,5 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PLUGIN_FEATURES_MODULE = void 0;
+exports.TAX_COMPLIANCE_MODULE = exports.PLUGIN_FEATURES_MODULE = void 0;
 /** Container key of the base plugin's module (`Module("plugin_features", …)`). */
 exports.PLUGIN_FEATURES_MODULE = "plugin_features";
+/** Container key of the base plugin's Steuer-Compliance module (`Module("tax_compliance", …)`). */
+exports.TAX_COMPLIANCE_MODULE = "tax_compliance";

package/dist/public/index.d.ts

@@ -1,4 +1,5 @@
-export { PLUGIN_FEATURES_MODULE } from "./constants";
+export { PLUGIN_FEATURES_MODULE, TAX_COMPLIANCE_MODULE } from "./constants";
+export { listCustomerAddressTaxIdentifications, TAX_COMPLIANCE_STATUSES, type AddressSnapshot, type CustomerAddressTaxIdentification, type TaxComplianceStatus, } from "./tax-compliance";
 export { definePluginFeatures } from "./descriptor";
 export { resolveEffectivePluginFeatures } from "./effective-features";
 export { isOwnPluginEvent, isPluginFeatureEnabled, isPluginFeatureEnabledByKey, pluginFeatureGate, requirePluginFeature, } from "./enforcement";

package/dist/public/index.js

@@ -1,8 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.reportPluginActionProgress = exports.shopMasterDataDescriptor = exports.getShopMasterData = exports.getShopAppearance = exports.getPluginSettings = exports.PLUGIN_ICON_NAMES = exports.resolveBaseModule = exports.isBasePluginRegistered = exports.requirePluginFeature = exports.pluginFeatureGate = exports.isPluginFeatureEnabledByKey = exports.isPluginFeatureEnabled = exports.isOwnPluginEvent = exports.resolveEffectivePluginFeatures = exports.definePluginFeatures = exports.PLUGIN_FEATURES_MODULE = void 0;
+exports.reportPluginActionProgress = exports.shopMasterDataDescriptor = exports.getShopMasterData = exports.getShopAppearance = exports.getPluginSettings = exports.PLUGIN_ICON_NAMES = exports.resolveBaseModule = exports.isBasePluginRegistered = exports.requirePluginFeature = exports.pluginFeatureGate = exports.isPluginFeatureEnabledByKey = exports.isPluginFeatureEnabled = exports.isOwnPluginEvent = exports.resolveEffectivePluginFeatures = exports.definePluginFeatures = exports.TAX_COMPLIANCE_STATUSES = exports.listCustomerAddressTaxIdentifications = exports.TAX_COMPLIANCE_MODULE = exports.PLUGIN_FEATURES_MODULE = void 0;
 var constants_1 = require("./constants");
 Object.defineProperty(exports, "PLUGIN_FEATURES_MODULE", { enumerable: true, get: function () { return constants_1.PLUGIN_FEATURES_MODULE; } });
+Object.defineProperty(exports, "TAX_COMPLIANCE_MODULE", { enumerable: true, get: function () { return constants_1.TAX_COMPLIANCE_MODULE; } });
+var tax_compliance_1 = require("./tax-compliance");
+Object.defineProperty(exports, "listCustomerAddressTaxIdentifications", { enumerable: true, get: function () { return tax_compliance_1.listCustomerAddressTaxIdentifications; } });
+Object.defineProperty(exports, "TAX_COMPLIANCE_STATUSES", { enumerable: true, get: function () { return tax_compliance_1.TAX_COMPLIANCE_STATUSES; } });
 var descriptor_1 = require("./descriptor");
 Object.defineProperty(exports, "definePluginFeatures", { enumerable: true, get: function () { return descriptor_1.definePluginFeatures; } });
 var effective_features_1 = require("./effective-features");