@hartl-services/medusa-base 2.11.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.**
@@ -2453,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({
@@ -2468,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" },
         ],
       },
     },
@@ -2490,10 +2500,6 @@ export default defineConfig({
         },
       },
     },
-    {
-      resolve: "@hartl-services/medusa-tax-compliance",
-      options: {},
-    },
   ],
 });
 ```
@@ -2608,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
@@ -3078,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
@@ -3319,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/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");

package/dist/public/tax-compliance.d.ts

@@ -0,0 +1,30 @@
+import type { MedusaContainer } from "@medusajs/framework/types";
+export declare const TAX_COMPLIANCE_STATUSES: readonly ["eligible", "ineligible", "invalid", "unavailable"];
+export type TaxComplianceStatus = (typeof TAX_COMPLIANCE_STATUSES)[number];
+export type AddressSnapshot = {
+    address1: string;
+    address2?: string | null;
+    city: string;
+    countryCode: string;
+    postalCode: string;
+};
+/** Status of the current UID check of a saved customer address whose facts still match it. */
+export type CustomerAddressTaxIdentification = {
+    customer_address_id: string;
+    status: TaxComplianceStatus;
+    customer_vat_number: string;
+    company_name: string;
+    validated_at: Date;
+    /** `eligible` or `ineligible`: the UID is real and matches company and address. */
+    verified: boolean;
+    /** The billing address the UID was checked against (`countryCode` lowercase, `address2` only when set). */
+    billing_address: AddressSnapshot;
+};
+/**
+ * The current UID check of each saved address of the customer that still
+ * matches the address as it is now, whatever its status (also `unavailable`
+ * and `invalid`). For other plugins, e.g. the Affiliate partner registration;
+ * the caller decides whether the `vat_validation` feature of `tax_compliance`
+ * is on (`isPluginFeatureEnabledByKey`).
+ */
+export declare const listCustomerAddressTaxIdentifications: (container: MedusaContainer, customerId: string) => Promise<CustomerAddressTaxIdentification[]>;

package/dist/public/tax-compliance.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listCustomerAddressTaxIdentifications = exports.TAX_COMPLIANCE_STATUSES = void 0;
+const constants_1 = require("./constants");
+exports.TAX_COMPLIANCE_STATUSES = [
+    "eligible",
+    "ineligible",
+    "invalid",
+    "unavailable",
+];
+/**
+ * The current UID check of each saved address of the customer that still
+ * matches the address as it is now, whatever its status (also `unavailable`
+ * and `invalid`). For other plugins, e.g. the Affiliate partner registration;
+ * the caller decides whether the `vat_validation` feature of `tax_compliance`
+ * is on (`isPluginFeatureEnabledByKey`).
+ */
+const listCustomerAddressTaxIdentifications = (container, customerId) => container
+    .resolve(constants_1.TAX_COMPLIANCE_MODULE)
+    .listCustomerAddressIdentifications(customerId);
+exports.listCustomerAddressTaxIdentifications = listCustomerAddressTaxIdentifications;

package/dist/shared/lib/index.d.ts

@@ -5,6 +5,7 @@ export * from "./errors";
 export * from "./hash";
 export * from "./logging";
 export * from "./money";
+export * from "./optional-registration";
 export * from "./refreshing-snapshot";
 export * from "./shipping-tax";
 export * from "./text";

package/dist/shared/lib/index.js

@@ -23,6 +23,7 @@ __exportStar(require("./errors"), exports);
 __exportStar(require("./hash"), exports);
 __exportStar(require("./logging"), exports);
 __exportStar(require("./money"), exports);
+__exportStar(require("./optional-registration"), exports);
 __exportStar(require("./refreshing-snapshot"), exports);
 __exportStar(require("./shipping-tax"), exports);
 __exportStar(require("./text"), exports);

package/dist/shared/lib/optional-registration.d.ts

@@ -0,0 +1,18 @@
+type ResolvingContainer = {
+    resolve<TValue = unknown>(name: string): TValue;
+    hasRegistration?: (name: string) => boolean;
+};
+/**
+ * Whether `error` is the container saying `name` is not registered: the
+ * awilix message Medusa throws ("Could not resolve 'name'. ...", only for the
+ * requested name itself, never a failing dependency further down the chain)
+ * or the older "Missing registration" wording.
+ */
+export declare const isMissingRegistrationError: (error: unknown, name: string) => boolean;
+/**
+ * Resolves an optional plugin's module service by its container key, or null
+ * while that plugin is not installed. A known-absent registration returns
+ * null without resolving; any other resolution failure is rethrown.
+ */
+export declare const tryResolveOptional: <T>(container: ResolvingContainer, name: string) => T | null;
+export {};

package/dist/shared/lib/optional-registration.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tryResolveOptional = exports.isMissingRegistrationError = void 0;
+/**
+ * Whether `error` is the container saying `name` is not registered: the
+ * awilix message Medusa throws ("Could not resolve 'name'. ...", only for the
+ * requested name itself, never a failing dependency further down the chain)
+ * or the older "Missing registration" wording.
+ */
+const isMissingRegistrationError = (error, name) => error instanceof Error &&
+    (error.message.includes("Missing registration") ||
+        error.message.startsWith(`Could not resolve '${name}'`));
+exports.isMissingRegistrationError = isMissingRegistrationError;
+/**
+ * Resolves an optional plugin's module service by its container key, or null
+ * while that plugin is not installed. A known-absent registration returns
+ * null without resolving; any other resolution failure is rethrown.
+ */
+const tryResolveOptional = (container, name) => {
+    if (container.hasRegistration?.(name) === false) {
+        return null;
+    }
+    try {
+        return container.resolve(name);
+    }
+    catch (error) {
+        if ((0, exports.isMissingRegistrationError)(error, name)) {
+            return null;
+        }
+        throw error;
+    }
+};
+exports.tryResolveOptional = tryResolveOptional;

package/dist/shop-config/build-food-shop-config.d.ts

@@ -33,8 +33,8 @@ export type FoodShopConfigInput = {
  * Builds the plain `medusa-config.ts` input of a food shop: Medusa core
  * settings, the Redis event bus, the mail provider (set up in the Admin), S3 file storage, tax and
  * Stripe payment providers, and the Hartl Services plugins (the base plugin
- * with its E-Mail, Documents and file storage modules plus five feature
- * plugins). Deployment
+ * with its E-Mail, Documents, Steuer-Compliance and file storage modules plus
+ * four feature plugins). Deployment
  * values are read and validated from `environment`; a missing or invalid one
  * fails with its name.
  */