@hartl-services/medusa-base 2.11.0 → 4.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,16 +56,20 @@ 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").
-- Builds a food shop's complete `medusa-config.ts` from a few shop facts
+- Builds a shop's complete `medusa-config.ts` from a few shop facts
   (`@hartl-services/medusa-base/shop-config`, see "Shop-Config-Preset").
 
 ## Installation in a shop
 
 ```bash
-pnpm add @hartl-services/medusa-base @hartl-services/medusa-food-supplements-contracts
+pnpm add @hartl-services/medusa-base @hartl-services/medusa-contracts
 ```
 
 ```ts
@@ -116,6 +122,27 @@ 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`).
+
+Upgrading to 4.0.0 (renames): the Contracts package is
+`@hartl-services/medusa-contracts` (1.0.0, formerly
+`@hartl-services/medusa-food-supplements-contracts`; same subpaths), and the
+Shop-Config-Preset exports are `buildShopConfig`, `defineShopConfig`,
+`ShopConfigOptions`, `ShopConfigInput`, `ShopPlugin` and `ShopModule`
+(formerly `buildFoodShopConfig` etc.). Replace the import names in
+`medusa-config.ts` and the Contracts package name in the shop and its
+Storefront; nothing else changes. The other Hartl Services plugins need the
+versions released with 4.0.0 (peer range `^4`).
+
 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
@@ -157,8 +184,8 @@ Store values are effective values only; a storefront uses them to hide
 features. DTOs, schemas and paths come from the Contracts package:
 
 ```ts
-import type { StorePluginFeaturesListResponse } from "@hartl-services/medusa-food-supplements-contracts/types/plugin-features-store"
-import { pluginFeaturesStorePaths } from "@hartl-services/medusa-food-supplements-contracts/paths/plugin-features"
+import type { StorePluginFeaturesListResponse } from "@hartl-services/medusa-contracts/types/plugin-features-store"
+import { pluginFeaturesStorePaths } from "@hartl-services/medusa-contracts/paths/plugin-features"
 
 const { plugins } = await sdk.client.fetch<StorePluginFeaturesListResponse>(
   pluginFeaturesStorePaths.get.list,
@@ -315,7 +342,7 @@ subscribes to it and filters on its own `plugin_key`:
 import {
   PLUGIN_FEATURES_UPDATED_EVENT,
   PluginFeaturesUpdatedEventSchema,
-} from "@hartl-services/medusa-food-supplements-contracts/events/plugin-features"
+} from "@hartl-services/medusa-contracts/events/plugin-features"
 
 export default async function onToggleChange({ event, container }: SubscriberArgs<unknown>) {
   const payload = PluginFeaturesUpdatedEventSchema.parse(event.data)
@@ -927,7 +954,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.**
@@ -1438,7 +1465,7 @@ Options of the `email` namespace:
   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
+  password reset fails with `render_failed`. `buildShopConfig` sets
   `<MEDUSA_BACKEND_URL>/app/reset-password?token=<token>` (the dashboard reads
   the token from the query).
   `adminAffiliateApplicationsUrl` (optional builder, receives
@@ -1460,7 +1487,7 @@ always part of the base.
 
 The event contracts the module consumes for shipment, cancellation, refund and
 affiliate-reminder and partner-application e-mails come from
-`@hartl-services/medusa-food-supplements-contracts/events/documents` and
+`@hartl-services/medusa-contracts/events/documents` and
 `/events/affiliate`, so installing the base does not pull in Affiliate.
 
 The provider reads no environment variables (since 2.9.0; the former
@@ -1641,7 +1668,7 @@ the toggle itself and follow at once. A failed read keeps the last value and
 logs a warning; before the first successful read the copy is off. The copy
 lives on `globalThis` because the preset (`dist`) and the plugin code Medusa
 loads (`.medusa/server`) are compiled separately. Only the preset
-(`buildFoodShopConfig` / `defineFoodShopConfig`) sets the getter; a shop with a
+(`buildShopConfig` / `defineShopConfig`) sets the getter; a shop with a
 hand-written config must set `authVerificationsPerActor` itself (a fixed list,
 changed by a restart) for the toggle to have any effect on logins.
 
@@ -1680,7 +1707,7 @@ Storefront contract (DTOs, schema and path from the Contracts package,
   status plus the attachment library (documents with append-only PDF
   versions).
 - Public HTTP DTOs, schemas, and paths remain in
-  `@hartl-services/medusa-food-supplements-contracts`.
+  `@hartl-services/medusa-contracts`.
 
 The base's `/types` and `/config` exports are dedicated server integration
 surfaces for the backend. The Documents and Affiliate event contracts live in
@@ -1918,7 +1945,7 @@ an info box lists number, customer, e-mail and order time, followed by an
 "Im Admin öffnen" button and the items, totals and addresses. Two optional
 `ShopEmailConfiguration` fields drive it: `adminOrderUrl({ orderId })` (the
 button is left out without it) and `timeZone` (IANA; the order time is left
-out without it). `buildFoodShopConfig` sets both (`<MEDUSA_BACKEND_URL>/app/
+out without it). `buildShopConfig` sets both (`<MEDUSA_BACKEND_URL>/app/
 orders/<id>` and its `timeZone` option). The layout receives `audience`
 (`"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.
@@ -2030,7 +2057,7 @@ Partner-Bewerbung von <Firma>" (without a company the applicant's name, then
 the e-mail address; just "Neue Partner-Bewerbung" if none is known). An info
 box lists company, name and e-mail (only the present ones), the applicant's
 message follows as an escaped paragraph, and an "Im Admin prüfen" button links
-`adminAffiliateApplicationsUrl` (left out without it; `buildFoodShopConfig`
+`adminAffiliateApplicationsUrl` (left out without it; `buildShopConfig`
 sets `<MEDUSA_BACKEND_URL>/app/affiliates/applications`). Its layout audience
 is `"shop"`. All applicant text is HTML-escaped.
 
@@ -2338,8 +2365,8 @@ Admin consumers import wire DTOs and paths only from the Contracts package and
 reuse their configured Medusa SDK:
 
 ```ts
-import type { ListAdminEmailMessagesResponse } from "@hartl-services/medusa-food-supplements-contracts/types/email-admin";
-import { emailAdminPaths } from "@hartl-services/medusa-food-supplements-contracts/paths/email";
+import type { ListAdminEmailMessagesResponse } from "@hartl-services/medusa-contracts/types/email-admin";
+import { emailAdminPaths } from "@hartl-services/medusa-contracts/paths/email";
 
 const response = await sdk.client.fetch<ListAdminEmailMessagesResponse>(
   emailAdminPaths.get.list,
@@ -2349,7 +2376,7 @@ const response = await sdk.client.fetch<ListAdminEmailMessagesResponse>(
 Do not import E-Mail module implementations, generated `.medusa` files, or
 duplicate runtime schemas in an Admin consumer. The base's own exports remain
 internal server and generated Admin integration surfaces; Email HTTP contracts
-are published only by `@hartl-services/medusa-food-supplements-contracts`.
+are published only by `@hartl-services/medusa-contracts`.
 
 ### Development and Rollout
 
@@ -2453,13 +2480,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({
@@ -2468,10 +2491,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" },
         ],
       },
     },
@@ -2490,10 +2510,6 @@ export default defineConfig({
         },
       },
     },
-    {
-      resolve: "@hartl-services/medusa-tax-compliance",
-      options: {},
-    },
   ],
 });
 ```
@@ -2608,7 +2624,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
@@ -2767,8 +2784,8 @@ address/email, file and artifact IDs, leases and resolution state.
 For a typed Storefront integration:
 
 ```ts
-import type { ListStoreDocumentsResponse } from "@hartl-services/medusa-food-supplements-contracts/types/documents-store";
-import { documentsPaths } from "@hartl-services/medusa-food-supplements-contracts/paths/documents";
+import type { ListStoreDocumentsResponse } from "@hartl-services/medusa-contracts/types/documents-store";
+import { documentsPaths } from "@hartl-services/medusa-contracts/paths/documents";
 
 const { documents: issuedDocuments } =
   await sdk.client.fetch<ListStoreDocumentsResponse>(
@@ -2784,10 +2801,10 @@ storage URL.
 
 The same Contracts boundary applies to all Documents and Tax Compliance public
 routes: import transport DTOs only from
-`@hartl-services/medusa-food-supplements-contracts/types/<feature>`, paths only from
-`@hartl-services/medusa-food-supplements-contracts/paths/<feature>`, and call the
+`@hartl-services/medusa-contracts/types/<feature>`, paths only from
+`@hartl-services/medusa-contracts/paths/<feature>`, and call the
 Storefront's configured Medusa SDK. A consumer that needs a runtime guard may
-opt in to `@hartl-services/medusa-food-supplements-contracts/schemas/<feature>`; it must
+opt in to `@hartl-services/medusa-contracts/schemas/<feature>`; it must
 not import either the plugin implementation or generated `.medusa` output.
 
 ### Admin order detail
@@ -2935,7 +2952,7 @@ canceled and prevents a concurrent render from being published as active.
 
 Documents owns no Notification or delivery state. Its integration boundary is
 the strict versioned event contract exported from
-`@hartl-services/medusa-food-supplements-contracts/events/documents`. Shipment assignments, standalone Refund resolutions and Order-
+`@hartl-services/medusa-contracts/events/documents`. Shipment assignments, standalone Refund resolutions and Order-
 cancellation resolutions each carry an `event_emitted_at` marker that is set
 only after successful enqueue.
 
@@ -2955,7 +2972,7 @@ orphan but cannot commit another Artifact, carrier or resolution.
 #### Exact outgoing event contracts
 
 The server-only Contracts subpath
-`@hartl-services/medusa-food-supplements-contracts/events/documents` exports the
+`@hartl-services/medusa-contracts/events/documents` exports the
 event-name constants,
 strict Zod schemas and inferred payload types for exactly these three events:
 
@@ -3045,8 +3062,8 @@ schemas and route paths, but no second Storefront client. Consumers use their
 own Medusa SDK instance:
 
 ```ts
-import type { GetStoreDocumentResponse } from "@hartl-services/medusa-food-supplements-contracts/types/documents-store";
-import { documentsPaths } from "@hartl-services/medusa-food-supplements-contracts/paths/documents";
+import type { GetStoreDocumentResponse } from "@hartl-services/medusa-contracts/types/documents-store";
+import { documentsPaths } from "@hartl-services/medusa-contracts/paths/documents";
 
 const response = await sdk.client.fetch<GetStoreDocumentResponse>(
   documentsPaths.store.get.retrieve(documentId),
@@ -3054,10 +3071,10 @@ const response = await sdk.client.fetch<GetStoreDocumentResponse>(
 );
 ```
 
-`@hartl-services/medusa-food-supplements-contracts/types/documents-store` and
-`@hartl-services/medusa-food-supplements-contracts/types/documents-admin` contain the
+`@hartl-services/medusa-contracts/types/documents-store` and
+`@hartl-services/medusa-contracts/types/documents-admin` contain the
 respective type-only DTOs. Import
-`@hartl-services/medusa-food-supplements-contracts/schemas/documents` only for explicit
+`@hartl-services/medusa-contracts/schemas/documents` only for explicit
 runtime validation. The common Storefront case imports only types, which are
 erased by TypeScript, and the path module; it never imports the plugin's Medusa
 server code. Store and Admin responses use the same safe `DocumentSummary`
@@ -3069,8 +3086,8 @@ and README note together when introducing another Documents route.
 Packing-list consumers stay Admin-only:
 
 ```ts
-import type { ListAdminOrderPackingListsResponse } from "@hartl-services/medusa-food-supplements-contracts/types/documents-admin";
-import { packingListsPaths } from "@hartl-services/medusa-food-supplements-contracts/paths/documents";
+import type { ListAdminOrderPackingListsResponse } from "@hartl-services/medusa-contracts/types/documents-admin";
+import { packingListsPaths } from "@hartl-services/medusa-contracts/paths/documents";
 
 const response = await sdk.client.fetch<ListAdminOrderPackingListsResponse>(
   packingListsPaths.admin.get.listForOrder(orderId),
@@ -3078,6 +3095,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-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-contracts`:
+
+```ts
+import type { SubmitTaxIdentificationResponse } from "@hartl-services/medusa-contracts/types/tax-compliance-store";
+import { taxCompliancePaths } from "@hartl-services/medusa-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-contracts/types/tax-compliance-store";
+import { taxCompliancePaths } from "@hartl-services/medusa-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
@@ -3309,7 +3642,7 @@ private URL themselves.
 
 ## Shop-Config-Preset
 
-`@hartl-services/medusa-base/shop-config` turns a food shop's configuration
+`@hartl-services/medusa-base/shop-config` turns a shop's configuration
 from about 290 lines into about 30: the plugin list and order, the Redis event
 bus, SMTP notifications, S3 file storage, the tax and Stripe payment providers,
 the Admin path, the Sentry logger bridge and the environment validation are
@@ -3319,15 +3652,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 \
@@ -3340,9 +3672,9 @@ pnpm add @hartl-services/medusa-base \
 
 ```ts
 // medusa-config.ts
-import { defineFoodShopConfig } from "@hartl-services/medusa-base/shop-config"
+import { defineShopConfig } from "@hartl-services/medusa-base/shop-config"
 
-module.exports = defineFoodShopConfig({
+module.exports = defineShopConfig({
   displayName: "EXAMPLE SHOP",
   orderNotificationEmail: "orders@example.com",
   timeZone: "Europe/Vienna",
@@ -3355,9 +3687,9 @@ plain input, changes it and calls `defineConfig` itself:
 
 ```ts
 import { defineConfig } from "@medusajs/framework/utils"
-import { buildFoodShopConfig } from "@hartl-services/medusa-base/shop-config"
+import { buildShopConfig } from "@hartl-services/medusa-base/shop-config"
 
-const config = buildFoodShopConfig(options)
+const config = buildShopConfig(options)
 config.plugins = config.plugins.filter(
   (plugin) => plugin.resolve !== "@hartl-services/medusa-batch-management",
 )
@@ -3366,16 +3698,16 @@ module.exports = defineConfig(config)
 
 ### API
 
-- `defineFoodShopConfig(options, environment = process.env)` returns
-  `defineConfig(buildFoodShopConfig(options, environment))`.
-- `buildFoodShopConfig(options, environment = process.env)` returns the plain
+- `defineShopConfig(options, environment = process.env)` returns
+  `defineConfig(buildShopConfig(options, environment))`.
+- `buildShopConfig(options, environment = process.env)` returns the plain
   config input (`admin`, `logger`, `projectConfig`, `modules`, `plugins`)
   before `defineConfig`. `modules` and `plugins` are ordinary arrays.
-- Types: `FoodShopConfigOptions`, `FoodShopConfigInput`, `FoodShopPlugin`,
-  `FoodShopModule`.
+- Types: `ShopConfigOptions`, `ShopConfigInput`, `ShopPlugin`,
+  `ShopModule`.
 
 Both functions validate the options first and throw a `TypeError` naming the
-option (`Food shop option "timeZone" must be ...`), so a misconfigured shop
+option (`Shop option "timeZone" must be ...`), so a misconfigured shop
 fails at boot. They then load the `.env` file (unless disabled) and read and
 validate the environment; a missing variable fails with the variable's name.