@hartl-services/medusa-base 0.3.0 → 1.0.0

package/README.md

@@ -1,9 +1,13 @@
 # Medusa Base
 
 Medusa v2.19 base plugin for Hartl Services shops. Every shop installs it. It
-provides per-plugin feature toggles: a generic Admin page under
-**Settings → Hartl Services Plugins**, a Store endpoint for storefronts and
-helpers that plugins use to enforce their toggles.
+provides per-plugin feature toggles, runtime settings and actions: a generic
+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").
 
 ## What it does
 
@@ -16,9 +20,35 @@ helpers that plugins use to enforce their toggles.
   values to the Admin.
 - Exports `definePluginFeatures`, `requirePluginFeature` and
   `isPluginFeatureEnabled` from `@hartl-services/medusa-base` for plugins.
+- Emits `plugin-features.updated.v1` after every saved Admin toggle update
+  (see "Toggle-change event").
+- Stores runtime settings that plugins declare (secrets encrypted), resolves
+  them with the medusa-config fallback and exports `getPluginSettings` (see
+  "Runtime settings").
+- Runs actions that plugins declare as workflow ids, records every run with
+  its progress and outcome and rejects a second start while one runs (see
+  "Actions").
+- Holds the shop's master data (Firmenangaben) as its own settings and
+  exports `getShopMasterData` (see "Shop-Stammdaten").
+- Exports Admin components from `@hartl-services/medusa-base/admin-components`
+  so a plugin composes the base's sections into its own page and hides
+  widgets of disabled features (see "Admin components for plugin pages").
 - Owns the `completeCartWorkflow` hooks `validate` and `orderCreated` and runs
   the workflows that plugins declare for them (see "Complete-cart hook
   composition").
+- Redirects `GET /` to the admin dashboard and repairs dangling
+  `cart_promotion` links (see "Root redirect" and "Cart-promotion link
+  repair").
+- Exports the shop's `medusa-config.ts` helpers from
+  `@hartl-services/medusa-base/config` and Sentry's `register()` from
+  `@hartl-services/medusa-base/instrumentation` (see "Config helpers" and
+  "Sentry instrumentation").
+- Sends the shop's transactional e-mails over SMTP (module `email`, see
+  "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)").
+- Builds a food 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
 
@@ -32,13 +62,49 @@ plugins: [
   // First in the list: other plugins read their toggles through it.
   {
     resolve: "@hartl-services/medusa-base",
-    options: {},
+    options: {
+      // Optional: key material for secret settings (see "Secrets").
+      settingsSecret: process.env.PLUGIN_SETTINGS_SECRET,
+      // E-Mail, Documents and the /files gateway: see the sections below
+      // (or let the Shop-Config-Preset fill them in).
+      // email: { jwtSecret, shop },
+      // documents: { merchant, numbering, pdf, htmlFactory },
+      // files: { gateway },
+    },
   },
   // … all other plugins
 ]
 ```
 
-The plugin has no options. Run `medusa db:migrate` after installing it.
+The options are `BasePluginOptions`. Medusa hands the same options object to
+every module of the plugin; each module reads only its own namespace:
+
+| Option | Read by | Meaning |
+|---|---|---|
+| `settingsSecret` | `plugin_features` module | Key material for stored secret settings. Set it from an environment variable of the shop; unset or empty, the base uses `projectConfig.http.cookieSecret`. |
+| `email` | `email` module | `{ jwtSecret, shop }`: branding, URLs and the JWT secret of the e-mail links (see "E-Mail"). Without `email.shop` the module boots but sends nothing. |
+| `documents` | `documents` module | `{ merchant?, numbering?, pdf?, htmlFactory? }` (see "Dokumente"). Defaults: numbering time zone `Europe/Vienna`, PDF executable `google-chrome`. |
+| `files` | `/files` routes | `{ gateway: { signingSecret } }`, returned by `createS3CacheStorageConfig` (see "Dateispeicher (S3)"). |
+
+`options: {}` is valid: the base then only provides the feature toggles,
+settings, actions and hooks, the e-mail module cannot dispatch, documents use
+the defaults and the `/files` routes answer that signing is not configured.
+Run `medusa db:migrate` after installing it (and after upgrading: 0.4.0 adds
+the tables `plugin_setting_state` and `plugin_action_run`; 1.0.0 brings the
+`email` and `documents` tables of the former `@hartl-services/medusa-email` and
+`@hartl-services/medusa-documents` packages with unchanged table and
+migration names, so a shop that used them needs no data migration).
+
+Upgrading from the separate packages: remove `@hartl-services/medusa-email`,
+`@hartl-services/medusa-documents`, `@hartl-services/medusa-s3-cache-storage`
+and `@hartl-services/medusa-food-shop-config` from `package.json` and
+`medusa-config.ts`, move their options into the namespaces above, change the
+provider resolve paths to `@hartl-services/medusa-base/providers/smtp` and
+`@hartl-services/medusa-base/providers/s3-cache` (the provider ids `smtp` and
+`s3-cache` are unchanged) and import their `/config`, `/types` and `/gateway`
+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.
 
 Peer dependencies are the host's Medusa 2.19 packages (`@medusajs/framework`,
 `@medusajs/medusa`, `@medusajs/admin-sdk`, `@medusajs/js-sdk`, `@medusajs/ui`)
@@ -49,12 +115,22 @@ dashboard uses.
 
 | Method | Path | Auth | Response |
 |---|---|---|---|
+| `GET` | `/` | none | 302 redirect to the configured `admin.path` (default `/app`) |
 | `GET` | `/store/plugin-features` | publishable key | `StorePluginFeaturesListResponse` |
 | `GET` | `/store/plugin-features/:plugin_key` | publishable key | `StorePluginFeaturesResponse`, 404 for an unknown plugin |
 | `GET` | `/admin/plugin-features` | Admin user | `AdminPluginFeaturesListResponse` |
 | `POST` | `/admin/plugin-features` | Admin user | `AdminPluginFeaturesResponse` |
+| `GET` | `/admin/plugin-features/:plugin_key` | Admin user | `AdminPluginFeaturesResponse`, 404 for an unknown plugin |
+| `GET` | `/admin/plugin-features/:plugin_key/settings` | Admin user | `AdminPluginSettingsResponse` |
+| `POST` | `/admin/plugin-features/:plugin_key/settings` | Admin user | `AdminPluginFeaturesResponse` |
+| `POST` | `/admin/plugin-features/:plugin_key/actions/:action_key` | Admin user | `AdminPluginActionRunResponse` (200 sync, 202 background), 409 `AdminPluginActionConflictResponse` while it runs |
+| `GET` | `/admin/plugin-features/:plugin_key/actions/:action_key/runs` | Admin user | `AdminPluginActionRunsResponse` (`?limit=`, default 1, max 20) |
 
-Every authenticated Admin user may change the toggles (no RBAC by design).
+Every authenticated Admin user may change toggles and settings and run
+actions (no RBAC by design). Admin plugin DTOs carry the toggles plus
+`settings` (with `source`, never a secret's value), `configured`, `missing`,
+`settings_version`, `actions`, `admin_page` (the plugin's own page or
+`null`) and `switchable`, so the list is one round trip for the hub.
 `POST` takes `{ plugin_key, expected_version, enabled, features }`; `features`
 holds configured values for declared keys, missing keys keep their default and
 an unknown key is 400. An unknown `plugin_key` is 404, a stale
@@ -108,6 +184,11 @@ Keys match `^[a-z][a-z0-9_]{0,62}$`, feature keys are unique, a `parent_key`
 must exist and only one nesting level is allowed. `definePluginFeatures`
 throws at import time otherwise.
 
+`switchable: false` declares a plugin that cannot be switched off (the
+base's own shop master data): the Admin shows no plugin switch, `enabled` is
+always `true` whatever is stored, and `POST /admin/plugin-features` with
+`enabled: false` is 400. It cannot be combined with `default_enabled: false`.
+
 ### Gating routes
 
 Put gate entries at the start of the plugin's `routes` array. An entry without
@@ -148,6 +229,43 @@ A read failure throws, so the subscriber or job is retried. A missing base
 plugin fails with `UNEXPECTED_STATE` ("@hartl-services/medusa-base ist nicht in
 medusa-config registriert.").
 
+To check another plugin without importing it, use its plugin key:
+`isPluginFeatureEnabledByKey(container, "documents", "invoices")`. It finds
+the descriptor among the registered modules; an unknown or uninstalled plugin
+key (and an undeclared feature key) is `false`.
+
+### Toggle-change event
+
+After a successful `POST /admin/plugin-features` the base emits
+`PLUGIN_FEATURES_UPDATED_EVENT` (`plugin-features.updated.v1`) through the
+event bus. The payload (`PluginFeaturesUpdatedEventSchema`) carries the
+plugin's effective values after the update:
+`{ plugin_key, enabled, features: { [key]: effective }, version }`. The event
+is emitted after the write committed; a failed emit is only logged and does
+not undo the write. Direct service calls (`updatePluginFeatures`) emit
+nothing.
+
+A plugin that must react right away (instead of on its next job run)
+subscribes to it and filters on its own `plugin_key`:
+
+```ts
+import {
+  PLUGIN_FEATURES_UPDATED_EVENT,
+  PluginFeaturesUpdatedEventSchema,
+} from "@hartl-services/medusa-food-supplements-contracts/events/plugin-features"
+
+export default async function onToggleChange({ event, container }: SubscriberArgs<unknown>) {
+  const payload = PluginFeaturesUpdatedEventSchema.parse(event.data)
+  if (payload.plugin_key !== demoPluginFeatures.plugin_key) return
+  // re-read the toggles and reconcile
+}
+
+export const config: SubscriberConfig = { event: PLUGIN_FEATURES_UPDATED_EVENT }
+```
+
+Events can arrive late or twice; re-read the current toggles instead of
+trusting the payload for anything that writes.
+
 ### Never on the cart path
 
 Code on the cart and checkout hot path (cart middlewares, cart workflow hooks,
@@ -156,6 +274,310 @@ fail-safe and independent of the database state of this plugin. Toggles
 control visibility and reachability of features, not the integrity of
 existing data.
 
+## Runtime settings
+
+Configuration a plugin reads at RUN time (for example an external system's
+URL and API key) is declared in the descriptor and edited on the plugin's
+Admin page. Boot-time provider configuration (SMTP, S3, Sentry, Redis) and
+function-valued options stay in `medusa-config.ts`.
+
+```ts
+export const demoPluginFeatures = definePluginFeatures({
+  plugin_key: "demo",
+  label: "Demo-Plugin",
+  features: [],
+  settings: [
+    { key: "api_url", label: "API-URL", type: "url", required: true },
+    { key: "api_key", label: "API-Key", type: "secret", required: true },
+    { key: "collection", label: "Collection", type: "string", default: "users" },
+    { key: "batch_size", label: "Batchgröße", type: "number", min: 1, max: 500, default: 100 },
+    {
+      key: "mode",
+      label: "Modus",
+      type: "select",
+      options: [
+        { value: "live", label: "Live" },
+        { value: "test", label: "Test" },
+      ],
+      default: "test",
+    },
+  ],
+})
+
+class DemoModuleService extends MedusaService({ /* models */ }) {
+  readonly pluginFeatures = demoPluginFeatures
+  // Values the plugin received from medusa-config; shown as "aus Konfiguration".
+  readonly pluginSettingsFallback: PluginSettingsFallback<"api_url" | "api_key">
+
+  constructor(cradle: unknown, options?: DemoOptions) {
+    super(...arguments)
+    this.pluginSettingsFallback = { api_url: options?.apiUrl, api_key: options?.apiKey }
+  }
+}
+```
+
+- Types: `string`, `url` (http/https), `number` (finite, optional inclusive
+  `min`/`max`), `boolean`, `secret`, `select` (`options: [{ value, label }]`,
+  non-empty, unique values; the stored value must be one of them). Keys
+  follow the feature key format and are unique. A `secret` has no default;
+  any other default must match its type, options and bounds. `options` exist
+  only on `select`, `min`/`max` only on `number`. `required` defaults to
+  `false`. `invalidates` (optional) lists secret settings of the same plugin
+  that a change of this setting deletes, e.g. `invalidates: ["api_key"]` on
+  `api_url` so a stored key is never sent to a new host. `definePluginFeatures`
+  throws at import time otherwise (also for an `invalidates` entry that is not
+  a secret of the plugin). The Admin renders a `select` as a dropdown, gives
+  number inputs their bounds and shows "Beim Ändern muss … neu eingegeben
+  werden" under a setting with `invalidates`.
+- Precedence per key: stored in the Admin > `pluginSettingsFallback`
+  (medusa-config) > declared default > not set. A value that does not fit the
+  declared type is skipped. A plugin is `configured` when every required
+  setting has a value; `missing` lists the others. A plugin must handle "nicht
+  konfiguriert" at run time (log and skip) instead of failing at boot.
+- Server-side code reads the resolved values with secrets DECRYPTED:
+
+  ```ts
+  import { getPluginSettings } from "@hartl-services/medusa-base"
+
+  const { values, configured, missing } = await getPluginSettings(
+    container, demoPluginFeatures, fallback
+  )
+  ```
+
+  A module service has no access to other modules through its own container;
+  it passes the global `container` from `@medusajs/framework`.
+- Updates (`POST …/settings` with `{ expected_version, values }`) merge
+  `values` into the stored row in one transaction: `null` clears a stored
+  value (the setting falls back to medusa-config or its default), a secret
+  that is not sent keeps its stored value, keys the plugin no longer declares
+  are dropped. When a setting with `invalidates` gets a different stored
+  value (also when it is cleared), the listed secrets are deleted in the same
+  transaction unless the update sets them anew; they appear in
+  `changed_keys`. Unknown keys and values of the wrong type, outside `min`/`max`
+  or not among a select's options answer 400 naming the key, a stale `expected_version` 409. The response is the full
+  `AdminPluginFeaturesResponse`.
+- After a saved update the base emits `PLUGIN_SETTINGS_UPDATED_EVENT`
+  (`plugin-settings.updated.v1`) with `{ plugin_key, version, changed_keys }`
+  (no values). Direct service calls emit nothing.
+
+### Secrets
+
+Secrets are stored AES-256-GCM encrypted (`{ enc: "<base64 iv|tag|ciphertext>" }`
+in `plugin_setting_state.values`) with a key derived by HKDF-SHA256 from the
+plugin option `settingsSecret`, else `projectConfig.http.cookieSecret`. The
+ciphertext is bound to `<plugin_key>:<setting key>` (AES-GCM additional
+authenticated data), so a stored value cannot be copied to another setting or
+plugin. The Admin never receives a secret's value, only whether it is set.
+**Changing the key material (`settingsSecret`, or `COOKIE_SECRET` without it)
+invalidates stored secrets:** they then count as "nicht gesetzt" (a warning is
+logged once per secret) and must be entered again; a medusa-config fallback
+applies in the meantime. Secrets saved by an unpublished development build
+before the key binding existed count as "nicht gesetzt" the same way and must
+be entered again.
+
+## Actions
+
+A plugin declares actions as registered workflow ids; the base runs them from
+the plugin's Admin page:
+
+```ts
+actions: [
+  {
+    key: "sync_now",
+    label: "Jetzt synchronisieren",
+    workflow_id: "demo-sync-catalog",
+    mode: "background", // or "sync"
+    confirm: "Den ganzen Katalog jetzt abgleichen?", // optional prompt
+  },
+],
+```
+
+The workflow receives `PluginActionWorkflowInput`
+(`{ plugin_key, action_key, triggered_by, run_id }`; `triggered_by` is the
+Admin user id, `run_id` the recorded run).
+
+- Every start is recorded in `plugin_action_run` (`running` → `completed` |
+  `failed`, `started_at`, `finished_at`, `triggered_by`, `message` of a
+  failure, `progress`, `result` when it is JSON and at most 4 KB).
+- While a run of the same action is `running`, a start answers 409
+  (`{ type: "conflict", message: "Diese Aktion läuft bereits.", run }`) and
+  starts nothing. A partial unique index enforces this also for concurrent
+  requests.
+- `sync`: the request waits for the workflow and answers
+  `{ action: { key, status: "completed", result?, run } }`. A failure goes
+  through Medusa's error pipeline (a `MedusaError` keeps its status); the run
+  is recorded as failed.
+- `background`: the run is started without waiting and the request answers
+  202 `{ action: { key, status: "started", run } }`. The outcome is recorded
+  on the run when the workflow settles; a failure is also logged.
+- A workflow that is still running when the engine returns (async steps,
+  e.g. a step retry scheduled with `retryInterval`) keeps its run `running`
+  (a second start stays 409) until the engine reports its finish; the run is
+  then recorded like a background run. A `sync` action answers 202 `started`
+  in that case.
+- Both emit `PLUGIN_ACTION_FINISHED_EVENT` (`plugin-action.finished.v1`,
+  `{ plugin_key, action_key, run_id, status: "completed" | "failed", message? }`)
+  when the run ends.
+- `GET …/actions/:action_key/runs?limit=1` returns the latest runs, newest
+  first. The Admin polls it every 2 s while the latest run is `running`.
+- Lost runs: a `running` run without start or progress for one hour (the
+  process restarted, the workflow was lost) is listed as `failed` with
+  "Abgebrochen (Neustart)" (listing never writes) and persisted as such the
+  next time the action is started. A run that reports progress regularly is
+  never affected.
+- An unknown action is 404 ("Aktion unbekannt"); a declared action whose
+  workflow is not registered is 500 (`UNEXPECTED_STATE` naming the workflow,
+  no run is recorded).
+
+### Reporting progress
+
+A long-running action reports progress from its workflow; the Admin shows it
+as a bar ("current / total") with the label:
+
+```ts
+import {
+  reportPluginActionProgress,
+  type PluginActionWorkflowInput,
+} from "@hartl-services/medusa-base"
+
+const syncPageStep = createStep(
+  "demo-sync-page",
+  async (input: PluginActionWorkflowInput & { page: number }, { container }) => {
+    // … one page of work
+    await reportPluginActionProgress(container, input.run_id, {
+      current: input.page,
+      total: 12, // or null when unknown
+      label: `Produkte: Seite ${input.page}`,
+    })
+  }
+)
+```
+
+`current` and `total` must be non-negative integers, the label is cut to 200
+characters. Without a `run_id` (the same workflow run from a script) the
+helper does nothing; invalid progress, an unknown or finished run and a
+failed write are logged as a warning and dropped, and never fail the action.
+
+## Shop-Stammdaten
+
+The base declares its own descriptor on its module service
+(`plugin_key: "shop"`, label "Shop-Stammdaten", `switchable: false`, no
+features). The hub shows it as the first card; its generic page edits the
+settings like any plugin's:
+
+| Key | Type | Required |
+|---|---|---|
+| `legal_name` (Firmenname) | string | yes |
+| `address_line1`, `address_line2` | string | line 1 |
+| `postal_code`, `city` | string | yes |
+| `country_code` | select: EU-27 plus `ch`, `gb`, `no`, `is`, `li` (lowercase ISO-2, German labels) | yes |
+| `vat_number` (UID-Nummer) | string | yes |
+| `email`, `phone` | string | no |
+| `website` | url | no |
+| `iban`, `bic` | string | no |
+| `company_register_number` (Firmenbuchnummer), `company_register_court` (Firmenbuchgericht) | string | no |
+
+Server-side code reads them with a plugin's own medusa-config values as
+fallback (stored in the Admin wins per key):
+
+```ts
+import { getShopMasterData } from "@hartl-services/medusa-base"
+
+const { values, configured, missing } = await getShopMasterData(container, {
+  legal_name: options.merchant?.legalName,
+})
+if (!configured) {
+  throw new MedusaError(
+    MedusaError.Types.UNEXPECTED_STATE,
+    `Shop-Stammdaten unvollständig: ${missing.join(", ")}`
+  )
+}
+```
+
+The base only checks presence and type; what counts as a usable value
+(for example a placeholder UID) is the consuming plugin's rule.
+
+## Admin pages
+
+- `/settings/hartl-services` (sidebar entry "Hartl Services Plugins") is the
+  hub: one card per plugin with status chips, the plugin switch (not for
+  `switchable: false`) and "Öffnen"; non-switchable plugins (Shop-Stammdaten)
+  come first.
+- The Aktionen section shows per action the progress of a running run
+  ("läuft seit …", bar, label; the button is disabled) and the outcome of the
+  last finished run; a finished run it watched and a second start ("läuft
+  bereits") are announced as toasts.
+- "Öffnen" leads to the plugin's ONE page: its `admin_page` when declared,
+  otherwise the base's generic page
+  `/settings/hartl-services/plugin/<plugin_key>` (Funktionen, Einstellungen,
+  Aktionen). The static `plugin` segment keeps it from colliding with
+  plugin-owned routes.
+- A plugin that needs more than the generic sections (its own forms, lists)
+  declares `admin_page: "/settings/hartl-services/<plugin-slug>"` and composes
+  that page from the base's components (below). Nested settings routes get no
+  sidebar entry, so the hub is the only way in. `definePluginFeatures`
+  rejects a path outside `/settings/hartl-services/` or under
+  `/settings/hartl-services/plugin/`.
+
+### Admin components for plugin pages
+
+`@hartl-services/medusa-base/admin-components` (ESM for the Admin's vite
+build, with types) exports:
+
+| Export | Purpose |
+| --- | --- |
+| `PluginPageShell({ pluginKey, children })` | Back link to the hub, the plugin's label, description and status chips, then `children`; loading, "nicht installiert" and error states instead of `children` |
+| `PluginFeatureSections({ pluginKey })` | Funktionen, Einstellungen, Aktionen exactly as on the generic page |
+| `usePluginFeature(pluginKey)` | Query of `GET /admin/plugin-features/:plugin_key` |
+| `pluginFeatureKeys` | Query key factory (`all`, `list()`, `detail(key)`) for invalidation after an own mutation |
+| `usePluginFeatureEnabled(pluginKey, ...featureKeys)` | `{ enabled, isPending, isError }` from the shared list query (30 s stale time); plugin switch and every key must be effective; `enabled` is `false` while loading and on error |
+| `PluginFeatureGate({ pluginKey, featureKeys?, fallback? })` | Renders `children` only while enabled, otherwise `fallback` (default nothing) |
+| `PluginFeatureDisabledNotice({ pluginKey, featureLabel? })` | "Diese Funktion ist unter Einstellungen → Hartl Services Plugins ausgeschaltet." with a link to the hub |
+
+```tsx
+// src/admin/routes/settings/hartl-services/demo/page.tsx
+import {
+  PluginFeatureSections,
+  PluginPageShell,
+} from "@hartl-services/medusa-base/admin-components"
+
+import { DemoMappingSection } from "../../../../features/demo/DemoMappingSection"
+
+const DemoPage = () => (
+  <PluginPageShell pluginKey="demo">
+    <PluginFeatureSections pluginKey="demo" />
+    <DemoMappingSection />
+  </PluginPageShell>
+)
+
+export default DemoPage
+```
+
+Widgets and pages of a disabled feature disappear instead of showing a 404:
+
+```tsx
+// Widget: renders nothing while the feature is off (or still loading).
+const DemoOrderWidget = () => (
+  <PluginFeatureGate pluginKey="demo" featureKeys={["order_sync"]}>
+    <DemoOrderPanel />
+  </PluginFeatureGate>
+)
+
+// Full page with a sidebar entry that cannot be hidden: explain instead.
+const DemoReportsPage = () => {
+  const { enabled, isPending } = usePluginFeatureEnabled("demo", "reports")
+  if (isPending) return null
+  return enabled ? <DemoReports /> : (
+    <PluginFeatureDisabledNotice pluginKey="demo" featureLabel="Berichte" />
+  )
+}
+```
+
+The consuming plugin lists `@hartl-services/medusa-base` in its
+`dependencies` or `peerDependencies`, so its admin build keeps the import
+external and the shop's Admin resolves one shared copy. The components use
+the host Admin's React, React Query, React Router and `@medusajs/ui`.
+
 ## Semantics
 
 - No stored row: every value is its declared default, `version` is 0.
@@ -204,9 +626,10 @@ class MyModuleService extends MedusaService({ /* … */ }) {
   finished transaction.
 - The base discovers participants like feature descriptors (every module in
   `medusa-config` that is registered in the container). Fail closed: an
-  invalid declaration (non-string or blank `workflow_id`, non-finite `order`,
-  unknown hook name, the same workflow twice for one hook) is
-  `UNEXPECTED_STATE` and blocks checkout, naming the module key.
+  invalid declaration (non-string or blank `workflow_id`, a `workflow_id` that
+  is not a registered workflow, non-finite `order`, unknown hook name, the
+  same workflow twice for one hook) is `UNEXPECTED_STATE` and blocks
+  checkout, naming the module key (and the workflow id).
 
 **Ordering.** Ascending `order`, then module key, then workflow id. In use:
 Affiliate 100 (`affiliate-validate-complete-cart`,
@@ -218,9 +641,12 @@ Affiliate 100 (`affiliate-validate-complete-cart`,
 - `validate` participants run one after another without their own transaction
   id (they write nothing). The first error stops the chain and is rethrown
   unchanged.
+- Participants run and are cancelled with an explicitly built context, like
+  Medusa's `runAsStep`: the parent's shared transaction context plus its
+  event group (`preventReleaseEvents`), never the step's parent linkage
+  (`parentStepIdempotencyKey`), so complete-cart may itself run nested.
 - `orderCreated` participants run one after another through the workflow
-  engine under the complete-cart transaction id, with the parent's event group
-  (`preventReleaseEvents`). If participant *k* fails, the base cancels
+  engine under the complete-cart transaction id. If participant *k* fails, the base cancels
   participants *k-1 … 0* in reverse order, logs every failed cancellation
   (module key, workflow id, cart, order, transaction), and rethrows the
   original error.
@@ -253,3 +679,1570 @@ module.exports = defineConfig({
 
 Initialize Sentry in `instrumentation.ts` as usual; without a `SENTRY_DSN` the
 wrapper is inert.
+
+## Root redirect
+
+Medusa serves nothing at `/`, so a deployed domain answers it with a 404. The
+base registers `GET /` and answers with a `302` to the shop's `admin.path`
+(read from the config module, fallback `/app`), so opening the bare domain
+lands on the admin dashboard in every shop and in local development without a
+reverse-proxy rule. The redirect is temporary on purpose: browsers cache a
+`301` on the bare domain essentially forever, which would be painful to undo
+should `/` ever get real content. A shop that needs its own `/` defines
+`src/api/route.ts` itself.
+
+## Cart-promotion link repair
+
+Medusa's `deletePromotionsWorkflow` only soft-deletes a promotion and leaves
+its `cart_promotion` link rows behind, so every cart that had it applied
+reads back a `null` entry inside `cart.promotions`. The base removes those
+links itself:
+
+- The `deletePromotionsWorkflow.hooks.promotionsDeleted` hook
+  (`workflows/hooks/dismiss-deleted-promotion-cart-links`) dismisses the
+  links of the deleted promotions and restores them if a later step fails.
+- The migration script `dismiss-orphaned-cart-promotion-links` runs once in
+  `medusa db:migrate` and removes the links that already dangle from earlier
+  deletions. Medusa tracks migration scripts by file name in
+  `script_migrations`, so the name must not change.
+
+Nothing to configure; `medusa db:migrate` after installing or upgrading to
+0.4.1 is enough.
+
+## Config helpers
+
+`@hartl-services/medusa-base/config` holds the generic environment helpers a
+shop's `medusa-config.ts` needs, so every shop fails at startup with the name
+of the missing variable instead of a runtime crash. The environment helpers
+have no dependency on Medusa; the subpath does not load `@sentry/node`.
+
+| Export | Purpose |
+|---|---|
+| `ConfigurationPhase` | `"build" \| "runtime"` |
+| `MEDUSA_BUILD_PLACEHOLDERS` | Placeholders for `ADMIN_CORS`, `AUTH_CORS`, `COOKIE_SECRET`, `DATABASE_URL`, `JWT_SECRET`, `MEDUSA_BACKEND_URL`, `STOREFRONT_URL`, `STORE_CORS`, `STRIPE_API_KEY`, `STRIPE_WEBHOOK_SECRET` |
+| `requireEnvironment(environment, names, phase, buildPlaceholders)` | Returns every named value (trimmed) or throws one error listing all missing names; in the build phase `buildPlaceholders` fill in for deployment values |
+| `optionalEnvironment`, `integerEnvironment`, `booleanEnvironment` | Trimmed optional string, range-checked integer, strict `"true"`/`"false"` boolean |
+| `allowsInsecureLocalServices(environment, phase)` | `true` for build, development and test |
+| `resolvePublicOrigin(value, name, allowHttp)`, `shopUrl(origin, path)` | Validate a bare HTTP(S) origin; build an absolute URL that cannot leave the origin |
+| `resolveStripe(values)` | Checks the `sk_` key and the `whsec_` webhook secret |
+| `resolveRedisEventBus(environment, phase)` | `{ url } \| undefined`: optional in development, required at runtime elsewhere, never used in a build, authenticated `rediss://` in production |
+| `createSmtpNotificationModuleConfig`, `resolveSmtp`, `SMTP_ENVIRONMENT_VARIABLES`, `SMTP_BUILD_PLACEHOLDERS`, `defineShopEmailConfiguration` | SMTP notification provider and E-Mail configuration (see "E-Mail") |
+| `createS3CacheStorageConfig`, `createS3CacheFileModuleConfig`, `resolveS3Credentials`, `resolveExpirationStrategy`, `S3_BUILD_PLACEHOLDERS` | S3 file storage (see "Dateispeicher (S3)") |
+| `createDefaultDocumentHtmlFactory`, `DOCUMENTS_BUILD_PLACEHOLDERS` | Documents markup and build placeholder (see "Dokumente") |
+
+`medusa build` loads the configuration without deployment secrets. Each
+plugin's own placeholders (SMTP, S3, PDF executable, ...) live with that
+plugin; the shop merges them:
+
+```ts
+// medusa-config.ts
+import {
+  MEDUSA_BUILD_PLACEHOLDERS,
+  requireEnvironment,
+  resolveRedisEventBus,
+  type ConfigurationPhase,
+} from "@hartl-services/medusa-base/config"
+
+const phase: ConfigurationPhase =
+  process.env.MEDUSA_BUILD_PHASE === "true" ? "build" : "runtime"
+const env = requireEnvironment(
+  process.env,
+  ["DATABASE_URL", "JWT_SECRET", "COOKIE_SECRET"],
+  phase,
+  { ...MEDUSA_BUILD_PLACEHOLDERS /* , ...other plugins' placeholders */ },
+)
+const redis = resolveRedisEventBus(process.env, phase)
+```
+
+## Sentry instrumentation
+
+`@hartl-services/medusa-base/instrumentation` exports `register()`, the hook
+Medusa's start command calls from the shop's `instrumentation.ts`. It runs
+`Sentry.init` with `SENTRY_DSN`, `SENTRY_ENVIRONMENT` (fallback `NODE_ENV`)
+and `tracesSampleRate: 0`; without a `SENTRY_DSN` Sentry stays inert. The
+shop's `instrumentation.ts` is one line:
+
+```ts
+export { register } from "@hartl-services/medusa-base/instrumentation"
+```
+
+`@sentry/node` stays an optional peer dependency of the base: a shop that uses
+this export (or `sentry-logger`) lists `@sentry/node` in its own
+`dependencies`.
+
+## E-Mail
+
+The base owns transactional e-mail for the shop: logical email messages,
+attempts, rendering, the Medusa Notification integration, SMTP transport,
+retries and e-mail-specific Admin operations. It is the `email` module, its
+SMTP notification provider (`providers/smtp`), its subscribers, jobs and
+workflows, and the Admin page `/settings/hartl-services/email`. There is no
+separate e-mail package since 1.0.0.
+
+### Configuration
+
+The SMTP notification provider is a `modules` entry built by
+`createSmtpNotificationModuleConfig` (from
+`@hartl-services/medusa-base/config`); the branding and rendering
+configuration goes into the `email` namespace of the base options:
+
+```ts
+import {
+  createSmtpNotificationModuleConfig,
+  resolveSmtp,
+  SMTP_ENVIRONMENT_VARIABLES,
+} from "@hartl-services/medusa-base/config";
+
+// Validates the seven SMTP_* variables (see "SMTP environment helpers").
+const smtp = resolveSmtp(
+  Object.fromEntries(
+    SMTP_ENVIRONMENT_VARIABLES.map((name) => [name, process.env[name] ?? ""]),
+  ) as Record<(typeof SMTP_ENVIRONMENT_VARIABLES)[number], string>,
+  process.env.NODE_ENV === "development" || process.env.NODE_ENV === "test",
+);
+
+export default defineConfig({
+  modules: [createSmtpNotificationModuleConfig(smtp)],
+  plugins: [
+    {
+      resolve: "@hartl-services/medusa-base",
+      options: {
+        email: {
+          jwtSecret: process.env.JWT_SECRET!,
+          shop: {
+            displayName: "Mein Shop",
+            affiliatePortalUrl: "https://shop.example.com/de/partner",
+            inviteUrl: ({ token }) =>
+              `https://shop.example.com/app/invite?token=${token}`,
+            orderNotificationEmail: "orders@shop.example.com",
+            passwordResetUrl: ({ locale }) =>
+              `https://shop.example.com/${locale ?? "de"}/passwort-zuruecksetzen`,
+          }, // a ShopEmailConfiguration, see `ShopEmailConfiguration` in `@hartl-services/medusa-base/types`
+        },
+      },
+    },
+  ],
+});
+```
+
+Options of the `email` namespace:
+
+- `jwtSecret` — used for Email's own tokens; typically the same secret as
+  `projectConfig.http.jwtSecret`.
+- `shop` — a `ShopEmailConfiguration` object: `displayName`,
+  `affiliatePortalUrl`, the `passwordResetUrl`/`inviteUrl` builders and the
+  `orderNotificationEmail` mailbox. `layout` and `renderers` are optional
+  overrides, see "Shop configuration and default templates".
+
+Without `email.shop` the module still boots, but it cannot dispatch: no mail
+is sent (the dispatch configuration is requested lazily and fails with
+`UNEXPECTED_STATE`). Shipment and cancellation e-mails wait for a Documents
+fact only while the Documents `invoices` feature is on when the message is
+created (with `invoices` off, or the Documents plugin switched off, Documents
+publishes no fact, so the mail is sent without a document). Refund e-mails
+come only from the Documents refund fact, so there are none while `invoices`
+is off. The former `documentsEnabled` option no longer exists: Documents is
+always part of the base.
+
+The event contracts the module consumes for shipment, cancellation, refund and
+affiliate-reminder e-mails come from
+`@hartl-services/medusa-food-supplements-contracts/events/documents` and
+`/events/affiliate`, so installing the base does not pull in Affiliate.
+
+Environment variables (all seven required outside development/test; at least
+one of `SMTP_SECURE`/`SMTP_REQUIRE_TLS` must be `true` outside
+development/test):
+
+```text
+SMTP_HOST=
+SMTP_PORT=
+SMTP_SECURE=
+SMTP_REQUIRE_TLS=
+SMTP_USER=
+SMTP_PASSWORD=
+SMTP_FROM=
+```
+
+Set `REDIS_URL` to use `@medusajs/event-bus-redis` instead of Medusa's local
+Event Bus; production requires an authenticated `rediss://` URL. See "Event
+Bus" below for retry/backoff behavior.
+
+### Feature toggles
+
+The E-Mail module declares its toggles to `@hartl-services/medusa-base` under the
+plugin key `email`. An Admin switches them under Settings → "Hartl Services
+Plugins"; Storefronts read the effective values from
+`GET /store/plugin-features/email`. A feature is only effective while the
+plugin switch (default on) is on. A gated subscriber that finds its feature
+off returns without creating a message; the event is not replayed when the
+feature is switched on again.
+
+| Key                   | Label                  | Default | Gates                                                                                                                                                                                                                    | Keeps running when off                                   |
+| --------------------- | ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------- |
+| (plugin switch)       | E-Mail                 | on      | every route under `/admin/email/*` (mail log, resends, terms versions; 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` | jobs, Admin routes, already created messages             |
+| `account_mails`       | Konto-Mails            | on      | subscribers `password-reset`, `user-invite`                                                                                                                                                                              | jobs, Admin routes, already created messages             |
+| `affiliate_reminders` | Affiliate-Erinnerungen | on      | subscriber `affiliate-consignment-reminder-due`                                                                                                                                                                          | jobs, Admin routes, already created messages             |
+
+With the plugin switched off the three jobs return immediately, so nothing
+is sent, retried or reconciled until it is switched on again; then the jobs
+pick up the stored messages (a message whose payload expired in the
+meantime, such as a password-reset link, is not sent). A toggle read
+failure fails the subscriber with its fixed sentinel (the Event Bus retries
+it) or fails the job run.
+
+Admin surfaces of a disabled feature are hidden. The E-Mail settings page
+keeps `PluginFeatureSections` visible (so the plugin can be switched back on)
+and gates the Terms PDF versions and mail log sections below it on the
+plugin switch, showing `PluginFeatureDisabledNotice` in their place while it
+is off.
+
+### Ownership
+
+- Documents owns document issuance and publishes immutable document facts.
+- Affiliate owns reminder eligibility and publishes reminder facts.
+- Email resolves recipients, renders content, attaches files, and owns delivery
+  status plus the append-only global Terms PDF history.
+- Public HTTP DTOs, schemas, and paths remain in
+  `@hartl-services/medusa-food-supplements-contracts`.
+
+The base's `/types` and `/config` exports are dedicated server integration
+surfaces for the backend. The Documents and Affiliate event contracts live in
+the Contracts package (`events/documents`, `events/affiliate`). The base exports no DML models, services,
+workflows, migrations, or generated output as a consumer contract.
+
+### Event Bus
+
+The backend owns Event Bus selection. Development without `REDIS_URL` leaves
+Medusa's local Event Bus active. Configuring `REDIS_URL` registers
+`@medusajs/event-bus-redis` 2.19.0 directly; production requires an
+authenticated `rediss://` URL unless the operator explicitly accepts private
+network transport risk with `REDIS_ALLOW_INSECURE_PRIVATE_NETWORK=true`.
+
+Redis Event Bus jobs have at most three total attempts with exponential backoff
+starting at one second. Completed jobs are removed, while failed jobs are kept
+for at most one hour and 1,000 entries. There is no custom Event Bus wrapper,
+startup capability probe, or purge job. Events are at-least-once facts and can
+be replayed, delayed, or delivered out of order.
+
+### Event Contracts
+
+All payload objects are strict. Unless noted otherwise, every string shown
+below is trimmed and non-empty. Native event names and shapes are fixed to the
+installed Medusa 2.19 exports:
+
+| Event                    | Payload                                                                                        |
+| ------------------------ | ---------------------------------------------------------------------------------------------- |
+| `order.placed`           | `{ id: string }`                                                                               |
+| `shipment.created`       | `{ id: string; no_notification?: boolean }`                                                    |
+| `order.canceled`         | `{ id: string }`                                                                               |
+| `order.return_requested` | `{ order_id: string; return_id: string }`                                                      |
+| `order.return_received`  | `{ order_id: string; return_id: string }`                                                      |
+| `auth.password_reset`    | `{ entity_id: string; actor_type: string; token: string; metadata?: Record<string, unknown> }` |
+
+The shared immutable Documents artifact is:
+
+```ts
+type DocumentsEmailArtifact = {
+  artifact_id: string;
+  document_id: string;
+  document_number: string;
+  file_id: string;
+  filename: string;
+  content_type: "application/pdf";
+};
+```
+
+The versioned project events are exact integration contracts:
+
+`documents.shipment_invoice_assignment.decided.v1`
+
+```ts
+type Payload =
+  | {
+      schema_version: 1;
+      order_id: string;
+      fulfillment_id: string;
+      decision: "non_carrier";
+    }
+  | {
+      schema_version: 1;
+      order_id: string;
+      fulfillment_id: string;
+      decision: "carrier";
+      invoice_fulfillment_id: string;
+      invoice_artifact: DocumentsEmailArtifact;
+    };
+```
+
+For `carrier`, `invoice_fulfillment_id` must equal `fulfillment_id`.
+
+`documents.order_cancellation_documents.ready.v1`
+
+```ts
+type Payload = {
+  schema_version: 1;
+  order_id: string;
+  expected_refund_ids: string[];
+  attachments: Array<{
+    payment_id: string;
+    refund_id: string;
+    artifact: DocumentsEmailArtifact;
+  }>;
+};
+```
+
+`expected_refund_ids` must be sorted and unique. Attachments must be sorted by
+unique `refund_id`, and every attachment refund must be expected.
+
+`documents.refund_document.ready.v1`
+
+```ts
+type Payload = {
+  schema_version: 1;
+  order_id: string;
+  payment_id: string;
+  refund_id: string;
+  artifact: DocumentsEmailArtifact | null;
+};
+```
+
+`affiliate.consignment_report_reminder_due.v1`
+
+```ts
+type Payload = {
+  schema_version: 1;
+  reminder_key: string;
+  affiliate_id: string;
+  customer_id: string | null;
+  affiliate_display_name: string;
+  period_start: string;
+  due_date: string;
+  locale: string | null;
+  trigger: "scheduled" | "manual";
+};
+```
+
+`period_start` is a valid `YYYY-MM-01`, `due_date` is a valid `YYYY-MM-DD`, and
+`reminder_key` is exactly
+`affiliate-consignment:<affiliate_id>:<period_start>`. `locale`, when present,
+has at most 35 characters. Email runtime-validates every contract before use.
+
+### Invariants
+
+- 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`, and
+  `affiliate.consignment_report_due`.
+- 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
+  role mailbox selected by the Shop configuration.
+- A new customer `order.received` intent snapshots the newest global Terms PDF
+  whose `effective_at` is not later than the authoritative `order.created_at`.
+  If no version is effective, the customer message is intentionally created
+  without Terms. The Shop `order.received.admin` intent never receives it.
+- Terms versions and their private files are immutable. Event replays, transport
+  retries, and explicit Admin resends reuse the original message snapshot, so a
+  later or backdated upload never changes an existing message.
+- Event payloads are runtime-validated before use and may be replayed, delayed,
+  or delivered out of order.
+- With the Documents `invoices` feature on, shipment and
+  cancellation messages remain pending until both their native Medusa fact
+  and immutable Documents fact arrive. The required facts are fixed when the
+  message is created; later facts reuse them.
+- Shipment `no_notification` suppresses the complete correlated message,
+  including any invoice attachment; refund email has no Documents-disabled
+  native fallback.
+- Recipients, rendered content, attachment bytes, SMTP responses, credentials,
+  reset tokens, and reset URLs are never logged.
+- Reset tokens and reset URLs are never persisted by Email or Notification.
+- Password-reset messages cannot be retried by the generic retry job or resent
+  by an Admin.
+- Unknown transport outcomes are never automatically resent.
+- Shop branding is only the configured `displayName`; a shop overrides the
+  default layout or single renderers in its own configuration, not in the
+  plugin.
+
+Read this section and the central design before changing Email domain behavior.
+
+### Shop configuration and default templates
+
+The E-Mail module ships a neutral German layout and one renderer per accepted kind.
+Both show the shop only as the configured `displayName` (escaped in HTML; the
+layout header and footer, the password-reset and invite subjects). A shop
+therefore needs only `displayName`, `affiliatePortalUrl`, `inviteUrl`,
+`passwordResetUrl` and `orderNotificationEmail`.
+
+- `layout` (optional) replaces the default layout completely.
+- `renderers` (optional, `Partial<EmailRendererMap>`) replaces only the listed
+  kinds; every other kind keeps its default renderer.
+
+```ts
+import { defineShopEmailConfiguration } from "@hartl-services/medusa-base/config";
+
+const shop = defineShopEmailConfiguration({
+  displayName: "Mein Shop",
+  // ...URLs and mailbox as above
+  renderers: {
+    "order.canceled": ({ order_id }) => ({
+      bodyHtml: `<p>Bestellung <strong>${order_id}</strong> storniert.</p>`,
+      subject: "Storniert",
+      text: `Bestellung ${order_id} storniert.`,
+    }),
+  },
+});
+```
+
+The defaults are merged once when the Email module boots, so an invalid
+configuration (blank `displayName`, a non-function `layout` or renderer, an
+unknown renderer kind) fails at startup and not at the first send. Custom
+renderers must escape dynamic values in `bodyHtml` themselves.
+
+### SMTP environment helpers
+
+`@hartl-services/medusa-base/config` exports helpers for the SMTP
+deployment variables:
+
+- `SMTP_ENVIRONMENT_VARIABLES` — the seven variable names.
+- `SMTP_BUILD_PLACEHOLDERS` — placeholder values for all seven variables so
+  `medusa build` can load `medusa-config.ts` without deployment secrets. Use
+  them only while building.
+- `resolveSmtp(values, allowInsecure)` — validates the values and returns the
+  `ResolvedSmtpConfiguration` for `createSmtpNotificationModuleConfig`. It
+  rejects a port outside 1–65535, a non-`"true"`/`"false"` boolean and an
+  invalid `SMTP_FROM`. `allowInsecure` permits plain SMTP (development, test,
+  build); otherwise `SMTP_SECURE` or `SMTP_REQUIRE_TLS` must be `true`.
+
+Runtime requires `SMTP_HOST`, `SMTP_PORT`, `SMTP_SECURE`, `SMTP_REQUIRE_TLS`,
+`SMTP_USER`, `SMTP_PASSWORD`, and `SMTP_FROM`. `SMTP_SECURE=true` selects
+implicit TLS; `SMTP_REQUIRE_TLS=true` requires STARTTLS. Outside development
+and test, at least one must be true. Certificate verification is never
+disabled. Development and test may set both to `false` for an isolated local
+SMTP server. SMTP endpoints and credentials never belong in the shop
+configuration.
+
+### Delivery Semantics
+
+For ordinary durable messages, only characterized connection failures,
+temporary SMTP rejections, and temporary attachment access failures are
+automatically retried. There are at most three total SMTP attempts, scheduled
+after one and five minutes. Permanent rejection and invalid content become
+terminal `failed`.
+
+`unknown` means SMTP may have accepted a message but Email cannot prove the
+outcome. A persisted successful Medusa Notification is accepted as proof of
+delivery; otherwise an expired attempt lease or uncharacterized transport
+result becomes terminal `unknown` and is never retried automatically. An Admin
+may consciously resend it as a new logical message.
+
+Business keys deduplicate logical automatic messages, attempt claims serialize
+workers, and each attempt has its own Notification idempotency key. These
+controls do not promise exact-once SMTP: a server can accept mail before the
+process persists success, and a conscious resend can produce a duplicate.
+
+Email transport retries and Event Bus retries are separate. Once an ordinary
+message outcome is persisted, its subscriber completes and the Email retry job
+owns any `retry_pending` work. Password-reset token and URL data remain
+ephemeral; password reset is excluded from the generic retry job and Admin
+resend, and retryable handling stays bounded by the original Event Bus event.
+
+### Admin API
+
+Email exposes authenticated Admin operations at:
+
+- `GET /admin/email/messages` lists safe message summaries. Pagination is
+  bounded and deterministic; `kind` and `status` accept only the published
+  allowlists.
+- `GET /admin/email/messages/:id` returns the safe message detail and delivery
+  attempts.
+- `POST /admin/email/messages/:id/resends` makes one explicit resend decision
+  using a request UUID.
+- `GET /admin/email/terms-versions` lists safe Terms version metadata in newest
+  effective order.
+- `POST /admin/email/terms-versions` idempotently stores one private PDF of at
+  most 5 MiB with its `effective_at` timestamp.
+- `GET /admin/email/terms-versions/:id/download` streams one authenticated,
+  non-cacheable PDF download.
+
+List and detail responses expose only safe identifiers and linkage metadata,
+kind/status and safe status codes, resource references, trigger, attempt
+counts, and timestamps. They never expose recipients, rendered content,
+template data, payloads, reset tokens, transport responses, or credentials.
+Terms responses expose filename, effective timestamp, byte size, SHA-256, and
+creation time, but never request IDs, file IDs, storage keys, URLs, or content.
+
+An Admin resend is accepted only for a `sent`, `unknown`, or terminal `failed`
+source. Password-reset messages can never use the generic resend operation.
+The authenticated Admin actor is derived by the server and is not accepted
+from the request body. Replaying the same request UUID returns the same resend;
+a different UUID represents a separate, conscious Admin decision. The Admin UI
+therefore retains a UUID while retrying an ambiguous failed request and creates
+a new UUID only after a new confirmation.
+
+### Admin UI
+
+The E-Mail module has one Admin page, `/settings/hartl-services/email`
+(**Settings → Hartl Services Plugins → E-Mail → Öffnen**; the descriptor's
+`admin_page` points the hub there) instead of a top-level sidebar item. It
+composes the base's `PluginPageShell` and `PluginFeatureSections` from
+`@hartl-services/medusa-base/admin-components` (the toggles above) and adds
+two operations sections below them, in this order: **AGB/PDF-Versionen** and,
+as the last section, the **E-Mail-Protokoll**. They show Terms PDF and mail
+log state to act on, not configuration the plugin reads at run time. The mail
+log provides bounded server pagination, allowlisted status/kind filters, safe
+message and attempt status, and an explicitly confirmed resend action.
+Recipient, template, and payload data are intentionally absent from the page.
+
+The `AGB/PDF-Versionen` section manages the global Terms PDFs. Admins can
+upload a PDF of at most 5 MiB with its effective date, review versions newest
+first, and download a selected version. Uploads receive a fresh request UUID;
+downloads use the configured authenticated Admin SDK and never expose storage
+file IDs or URLs in the UI.
+
+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";
+
+const response = await sdk.client.fetch<ListAdminEmailMessagesResponse>(
+  emailAdminPaths.get.list,
+);
+```
+
+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`.
+
+### Development and Rollout
+
+For local development, provide the seven SMTP variables and omit `REDIS_URL` to
+use Medusa's local Event Bus. Set `REDIS_URL` only when intentionally exercising
+the direct Redis provider. The backend HTTP runner ignores ambient Redis and
+SMTP settings and injects an isolated Redis container, unique queue, and
+token-protected SMTP fixture for every child.
+
+This architecture replaces the old Documents and Affiliate delivery baselines
+without a backfill or compatibility layer. Existing local databases from those
+baselines must be wiped once with:
+
+```bash
+pnpm --dir apps/backend db:recreate
+```
+
+The first production rollout must start from an empty database and run
+`pnpm --dir apps/backend db:migrate` before accepting traffic. This assumes no
+production business data exists; a populated database requires a separately
+reviewed migration. No old delivery rows or queued jobs are migrated or purged
+by Email.
+
+## Dokumente
+
+The base issues order documents: one total invoice per order after the final
+shipment and one negative cancellation document for each eligible payment
+refund. An Admin user can regenerate issued documents in place for exceptional
+corrections. The base ships default German document markup, so a new shop needs
+no template code; a project can optionally replace the HTML/CSS factory. PDF
+generation, private file storage, customer authorization and durable
+document-readiness facts stay inside the `documents` module. There is no
+separate documents package since 1.0.0.
+
+### What it does
+
+- Listens to Medusa's `shipment.created` event.
+- Creates an invoice only if the order is fully shipped and not cancelled.
+  Partial shipments do not create a document.
+- Saves the rendered PDF and the exact source data as a document snapshot.
+- Reads eligible B2B evidence frozen under the order ID from Tax Compliance and
+  persists the customer company, customer UID and exemption wording in that
+  same snapshot. B2C and non-eligible evidence add no tax-proof statement.
+- Freezes a tax breakdown (`totals.tax_breakdown`) grouped by the order's
+  item and shipping tax-line name and rate, as configured on the Medusa tax
+  region. Amounts are rounded to the currency and add up exactly to the
+  tax total; cancellations scale it proportionally. Snapshots issued before
+  this field existed read as an empty breakdown.
+- Persists one immutable decision per shipped Fulfillment. A leased, Order-
+  unique coordinator chooses exactly one invoice carrier without assuming
+  event delivery order; all other shipments become `non_carrier`.
+- Uses a durable per-order issuance key and token-fenced finalization, so
+  duplicate, concurrent or delayed events cannot create a second initial
+  invoice or committed carrier.
+- Allocates financial document numbers from Documents-owned, transactional
+  annual number ranges. Invoice, cancellation and future credit-note ranges are
+  independent of Medusa Order display IDs and safe across backend workers.
+- Lets an Admin regenerate the invoice in place with a fresh order and active
+  batch-allocation snapshot.
+- Listens to Medusa's successful `payment.refunded` event and issues one
+  cancellation document per persisted refund, including partial refunds.
+- Uses the immutable Refund ID as both cancellation issuance key and resolution
+  identity, so replayed payment events cannot create duplicate cancellation
+  documents or readiness facts.
+- Reconciles the complete Refund set after Order cancellation, including Medusa
+  bulk refunds that do not emit a singular refund event. A canceled Order with
+  zero Refunds still receives a final empty cancellation resolution.
+- Publishes strict versioned shipment, Refund and Order-cancellation facts only
+  after their database state and referenced immutable artifacts are committed.
+  Publication markers and periodic reconciliation close the database-to-event
+  enqueue gap.
+- Exposes only an authenticated customer Store API. A customer can list,
+  inspect and download only documents belonging to their own customer ID.
+  Guest documents deliberately have no Store lookup path.
+- Adds an Admin order-detail widget. Authenticated Admin users can view the
+  issued documents belonging to the current order as a private inline PDF.
+- Supports `invoice`, `cancellation` and `credit_note` document kinds.
+  Cancellation issuance is wired to payment refunds; `credit_note` remains a
+  reserved type for a future, distinct business process.
+- Creates one internal packing list for every physical fulfillment, including
+  optional fulfillment-scoped batch data. Partial fulfillments therefore
+  produce independent packing lists.
+- Keeps packing lists in a separate Admin-only aggregate. They have no customer
+  owner, Store route, communication artifact or customer-facing Documents event.
+- Reconciles non-canceled physical fulfillments periodically so a lost local
+  event can be repaired idempotently, including after shipment.
+
+### 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.
+
+```ts
+export default defineConfig({
+  modules: [
+    {
+      resolve: "@medusajs/medusa/tax",
+      options: {
+        providers: [
+          {
+            resolve:
+              "@hartl-services/medusa-tax-compliance/providers/tax-compliance",
+          },
+        ],
+      },
+    },
+  ],
+  plugins: [
+    {
+      resolve: "@hartl-services/medusa-base",
+      options: {
+        documents: {
+          numbering: {
+            timeZone: "Europe/Vienna", // default when omitted
+          },
+          pdf: {
+            executablePath: process.env.DOCUMENT_PDF_EXECUTABLE, // default: "google-chrome"
+          },
+        },
+      },
+    },
+    {
+      resolve: "@hartl-services/medusa-tax-compliance",
+      options: {
+        merchant: {
+          countryCode: process.env.MERCHANT_COUNTRY_CODE!,
+          vatNumber: process.env.MERCHANT_VAT_NUMBER!,
+        },
+      },
+    },
+  ],
+});
+```
+
+Options of the `documents` namespace (all optional; `{}` is valid):
+
+- `htmlFactory` — optional. A `(input: DocumentRenderInput) => string |
+  Promise<string>` function that replaces the built-in German markup; the
+  module owns PDF rendering and storage either way. When omitted, the module
+  uses `createDefaultDocumentHtmlFactory({ timeZone })` with the resolved
+  `numbering.timeZone`, so printed dates are shown in the same time zone that
+  picks the numbering period. A value that is not a function is rejected at
+  startup.
+- `numbering.timeZone` — an IANA time zone used to resolve the annual
+  numbering period and the dates printed by the default markup. Defaults to
+  `"Europe/Vienna"`; a given value (also a blank one) is validated and
+  rejected at startup when invalid.
+- `pdf.executablePath` — Chromium/Chrome executable path or command name.
+  Defaults to `"google-chrome"`.
+- `merchant` — optional fallback for the shop master data (see "Merchant
+  data" below), shape `DocumentMerchantOption`:
+  `{ countryCode, legalName, registeredAddress: { address1, address2?, city,
+  countryCode, postalCode }, vatNumber? }`.
+
+The `documents` module is always registered with the base (no `documentsEnabled`
+switch); the Admin switches it off at run time through the feature toggles
+below. `medusa db:migrate` creates its tables.
+
+### The `/config` subpath
+
+`@hartl-services/medusa-base/config` exports, next to the environment helpers,
+build-time values for `medusa-config.ts` and tests:
+
+- `createDefaultDocumentHtmlFactory({ timeZone })` — the built-in factory, to
+  use as it is or to wrap (for example to add a header to the default HTML).
+- `DOCUMENTS_BUILD_PLACEHOLDERS` — `{ DOCUMENT_PDF_EXECUTABLE: "google-chrome" }`.
+  `medusa build` evaluates `medusa-config.ts` without the runtime-only
+  environment, so spread it under the real environment while building.
+
+The document types (`DocumentMerchantOption`, `DocumentHtmlFactory`,
+`DocumentRenderInput`, ...) come from `@hartl-services/medusa-base/types`.
+
+### Merchant data
+
+The legal sender printed on every document comes from the base plugin's shop
+master data (Admin → Settings → Hartl Services Plugins → **Shop-Stammdaten**).
+Each render reads it and passes it to the `htmlFactory` as `input.merchant`
+(`DocumentMerchant`: `legal_name`, `address_line1`, `address_line2`,
+`postal_code`, `city`, `country_code`, `vat_number`, `email`, `phone`,
+`website`, `iban`, `bic`, `company_register_number`,
+`company_register_court`; unset optional fields are `null`). Per field, a
+value stored in the Admin wins over the `merchant` option.
+
+- `merchant` is not part of the stored snapshot: a regenerated document
+  prints the master data current at regeneration time.
+- The development UID `ATU00000000` arrives as `vat_number: null` and is
+  never printed.
+- Without `legal_name`, `address_line1`, `postal_code`, `city` and
+  `country_code` a document cannot be issued: issuance fails with
+  `UNEXPECTED_STATE` ("Shop-Stammdaten unvollständig: …" naming the missing
+  fields). Invoices and cancellations check this before a document number
+  and issue date are reserved, so no number is used up: the invoice workflow
+  fails (the subscriber logs it, the shipment assignment stays pending), a
+  refund resolution is marked failed. A packing list revision is marked
+  failed with the message, which the Admin order widget shows. Once the data
+  is complete, the existing paths issue it again (event redelivery,
+  reconciliation jobs, the Admin issue and retry actions). A missing UID
+  does not block issuance.
+
+Requirements/couplings:
+
+- A registered Tax Compliance module (`tax_compliance`) as shown above.
+- 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
+  its own authenticated routes, so it works with any File provider and does
+  not need the S3 file storage or its `/files` routes.
+  **With Medusa's local File provider, set `private_upload_dir` to a
+  directory outside `static/`:** its default stores private files in
+  `static/`, which Medusa serves publicly under `/static`, making every
+  invoice downloadable by its guessable file name. The base plugin still
+  starts in that case (it ships the Documents module to every shop), but logs
+  a warning at startup and refuses to write any document: issuing an invoice
+  or packing list fails until the File Module stores private files outside
+  `static/`.
+- Optionally, `@hartl-services/medusa-batch-management` 0.0.3+ for
+  batch/lot data on invoices and packing lists (see "Optional Batch
+  Management integration" below).
+
+
+### Feature toggles
+
+The Documents module declares its toggles to the base under the plugin key
+`documents`. An Admin switches them under Settings → "Hartl
+Services Plugins"; Storefronts read the effective values from
+`GET /store/plugin-features/documents`. A disabled plugin or feature answers
+its routes with HTTP 404, and its subscribers and jobs return without doing
+anything. Store routes answer 404 even without a customer login (the gate runs
+before the route's authentication); Admin routes still require an Admin login
+first, because Medusa authenticates every `/admin` request before any plugin
+middleware (401 without login, 404 afterwards). A feature is only effective while the plugin
+switch (default on) is on.
+
+| Key             | Label                | Default | Gates                                                                                                                                                                                                                                  | Keeps running when off                                                                                    |
+| --------------- | -------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| (plugin switch) | Dokumente            | on      | every Documents route (`/store/documents/*`, `/admin/orders/:id/documents/*`, `/admin/orders/:id/packing-lists/*`) and, through the two features, every subscriber and job                                                              | checkout, fulfillment and shipping; already issued documents and PDFs stay stored                         |
+| `invoices`      | Rechnungen & Stornos | on      | `/store/documents/*`, `/admin/orders/:id/documents/*`; subscribers `documents-shipment-created`, `documents-order-canceled`, `payment-refunded`; jobs `documents-fact-publication-reconciliation`, `documents-domain-resolution-reconciliation`               | packing lists; stored invoices stay stored but are not reachable through the API                          |
+| `packing_lists` | Packlisten           | on      | `/admin/orders/:id/packing-lists/*`; subscribers `packing-list-fulfillment-created`, `packing-list-fulfillment-canceled`, `packing-list-allocation-revised`; job `documents-packing-list-reconciliation`                                  | invoices, cancellations and refund documents                                                              |
+
+**Events are not replayed.** While `invoices` is off, no invoice,
+cancellation or refund document is issued for new shipments, cancellations
+or refunds, and nothing is issued later for them either once the feature is
+switched back on; issue a missing invoice by hand with
+`POST /admin/orders/:id/documents`. While `packing_lists` is off, no packing
+list is created, revised or canceled; after switching it back on, the
+periodic `documents-packing-list-reconciliation` job creates the missing
+packing lists of non-canceled physical fulfillments (cancellations that
+happened meanwhile are not replayed).
+
+Admin surfaces of a disabled feature are hidden. The Admin widgets on the
+order detail page (`order-documents`, `order-packing-lists`) stay registered
+but render nothing while their feature (`invoices`, `packing_lists`) is off,
+using `PluginFeatureGate` from
+`@hartl-services/medusa-base/admin-components`.
+
+No workflow hook and nothing on the cart, checkout or fulfillment path reads
+a toggle.
+
+### Shop integration
+
+The demo shop (`apps/backend`) gets everything from the preset (see
+"Shop-Config-Preset"): `documents.merchant` is its `merchant` option,
+`documents.numbering.timeZone` its `timeZone` option and
+`documents.pdf.executablePath` the `DOCUMENT_PDF_EXECUTABLE` variable. The
+development UID `ATU00000000` is a placeholder: Documents never prints it,
+and Tax Compliance does not transmit it to FinanzOnline. Enter the real
+merchant UID in the Shop-Stammdaten before issuing production invoices.
+
+`htmlFactory` is intentionally the only presentation extension point. It gets
+a fully typed value snapshot (`DocumentTemplateInput` or
+`PackingListTemplateInput`) plus `merchant` (see "Merchant data"), never a
+live Medusa model. Escape every dynamic value in the factory; the HTML is
+rendered by a headless Chromium process before it is stored as a private PDF.
+
+The consuming host needs a Chromium/Chrome executable and a Medusa File
+provider that supports private files. Run the Medusa process as a dedicated
+non-root user: the PDF renderer keeps Chromium's sandbox enabled and therefore
+refuses to start as root. Installation and Dokploy runtime checks are
+documented under `Chromium für Dokument-PDFs` in `apps/backend/README.md`.
+Each render uses an ephemeral Chrome profile below its private temporary
+directory and removes it afterward. The Chromium child is also disconnected
+from the user's session bus and legacy keyring socket, so it cannot access the
+operator's normal browser profile or desktop keyring, including under WSLg.
+
+### Restore check for private files
+
+After restoring the object store (or the local file directory), check that
+every issued document's PDF can be read through the active Medusa File
+provider. The read-only script lives in the base but is deliberately not a
+migration script, so `db:migrate` never runs it:
+
+```bash
+pnpm exec medusa exec ./node_modules/@hartl-services/medusa-base/.medusa/server/src/documents/scripts/verify-documents-file-storage.js
+```
+
+It fails on the first issued document without a stored file and otherwise
+logs the number of verified files and bytes.
+
+### Clean baseline and first deployment
+
+The module intentionally contains one generated eight-table baseline,
+`Migration20260827061749`. It removes the former `documents_delivery` table
+entirely and adds the Artifact, Shipment-assignment/coordinator and Refund-/
+Order-cancellation resolution tables. Old delivery rows are not migrated:
+Email now owns logical messages and attempts. The generated snapshot is not
+edited by hand, while migration-only constraints and indexes remain in the
+baseline.
+
+`Migration20260830111207` is the forward migration that adds the
+`documents_document_number_sequence` table, makes every financial document's
+number and issue date mandatory, and protects the complete document number with
+an unconditional unique index. It deliberately does not renumber legacy rows.
+A disposable local database containing pre-migration Documents rows with null
+or duplicate numbers must be recreated rather than silently backfilled.
+
+A disposable local database that has already run an older Documents baseline
+must be recreated once after stopping the backend and verifying the exact local
+`DATABASE_URL` target:
+
+```bash
+pnpm --dir apps/backend db:recreate
+```
+
+This command deletes all data and is restricted to local development. Never use
+it for staging, shared or production databases; those require an
+environment-owner-approved reset. A first production installation is supported
+only on a deliberately empty database. Run:
+
+```bash
+pnpm --dir apps/backend db:migrate
+pnpm --dir apps/backend exec medusa db:sync-links
+```
+
+`db:migrate` applies all module baselines and Medusa's pending initial seed once;
+do not invoke that seed separately. If any production database has already run
+an older Documents baseline or contains data that must survive, stop: this clean
+baseline is not a forward migration or backfill and a new forward migration is
+required instead.
+
+Apply normal pending module migrations after later changes or upgrades with
+`pnpm --dir apps/backend db:migrate`. This plugin defines no module links, so it
+does not require link synchronization by itself; `db:sync-links` above is the
+safe shop-wide first-deployment step for links owned elsewhere.
+
+### Storefront contract
+
+All three endpoints require a customer session or bearer token. There is no
+guest lookup endpoint and no direct File-provider URL.
+
+- `GET /store/documents` – document summaries for the authenticated customer.
+- `GET /store/documents/:id` – one owned document summary.
+- `GET /store/documents/:id/download` – streams the owned private PDF.
+
+The public DTO deliberately includes only the document number, kind, issue
+date, order display ID and total. It excludes the immutable snapshot, recipient
+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";
+
+const { documents: issuedDocuments } =
+  await sdk.client.fetch<ListStoreDocumentsResponse>(
+    documentsPaths.store.get.list,
+    { method: "GET" },
+  );
+const downloadPath = documentsPaths.store.get.download(issuedDocuments[0].id);
+```
+
+The Storefront should request `downloadPath` with its authenticated SDK;
+it is deliberately a protected application route rather than an exposed object
+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
+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
+not import either the plugin implementation or generated `.medusa` output.
+
+### Admin order detail
+
+When Documents is enabled, the Medusa Admin order detail shows a
+**Dokumente** widget. It lists the issued documents for that order and opens a
+private PDF preview. The widget obtains the PDF through the Medusa JS SDK, so
+both session and bearer-token Admin authentication work without exposing a
+File-provider URL.
+
+The Admin API is deliberately scoped by both order and document ID:
+
+- `GET /admin/orders/:id/documents`
+- `POST /admin/orders/:id/documents/regenerate`
+- `POST /admin/orders/:id/documents/:document_id/regenerate`
+- `GET /admin/orders/:id/documents/:document_id/download`
+
+All authenticated Admin users can inspect order documents; a document from a
+different order returns `404` from the download endpoint.
+
+#### Internal packing lists
+
+The separate **Packlisten** order widget lists every physical fulfillment in
+creation order. A ready entry can be previewed and downloaded as a private PDF;
+missing or failed entries can be generated again through the same idempotent
+workflow used by the automatic subscriber.
+
+- `GET /admin/orders/:id/packing-lists`
+- `POST /admin/orders/:id/packing-lists/:fulfillment_id/retry`
+- `GET /admin/orders/:id/packing-lists/:fulfillment_id/download`
+
+The PDF freezes the fulfillment-item title, SKU, quantity and Medusa Stock
+Location name. Managed variants with multiple inventory items are listed as
+their concrete warehouse components. Their quantity is the concrete inventory
+quantity after Medusa's `required_quantity` multiplier, not necessarily the
+commercial order-line quantity.
+
+Packing lists never pass through the Documents customer-fact pipeline. They are
+also stored outside `documents_document`, so the authenticated Store document
+queries cannot expose them accidentally.
+
+#### Regenerating an invoice
+
+Once an invoice exists, the widget changes **Rechnung ausstellen** to
+**Rechnung regenerieren**. This action retains the document ID, document number
+and original issue date, but replaces its persisted PDF and snapshot with a
+fresh render. A prior artifact that is locked by a committed communication fact
+and its private File are retained permanently. Only an unlocked superseded
+artifact File may be deleted on a best-effort basis after the replacement has
+been stored, so Storefront and Admin continue to show exactly one current PDF.
+
+Regeneration re-applies the normal completed-shipment and cancellation checks,
+then reads the current order values and active batch withdrawals. It is a
+deliberate exception workflow and does not emit a customer communication event.
+
+The document-specific regeneration route is used by the widget for every
+issued document. For invoices it has the same live-data behavior described
+above. A cancellation or future credit note is instead rendered from its
+persisted snapshot, retaining its original amount, source invoice reference,
+number and issue date. It also emits no customer communication event.
+
+#### Financial document numbers
+
+Documents assigns numbers in these annual ranges:
+
+```text
+RE-2026-1
+ST-2026-1
+GS-2026-1
+```
+
+The prefix identifies the document kind, the year is resolved in the selected
+shop's configured numbering time zone, and the final integer is allocated by a
+transactional PostgreSQL counter. A new range starts at `1` for each document
+kind and year. `order_display_id` remains a separate order reference in the
+snapshot and PDF; it never determines a financial document number.
+
+Number and issue date are reserved in the same short transaction that creates
+the processing document. PDF rendering and File I/O remain outside database
+transactions. A retry reuses the reserved identity and regeneration never
+increments a range. A permanently failed document retains its number and
+failure reason as the explanation for that range's gap; reserved numbers are
+never recycled or reassigned.
+
+#### Cancellation documents for payment refunds
+
+Medusa's refund event identifies the payment, so the plugin enumerates its
+persisted refund records and claims one cancellation document using each
+immutable refund ID. This makes delivery at-least-once safe: repeated events
+or a retry leave an already issued cancellation unchanged.
+
+When an invoice exists, the cancellation issue date is reserved when Documents
+starts issuing the cancellation and its amount is negative. Since a payment
+refund has no line-item allocation, the plugin proportionally derives the
+original invoice's subtotal and tax from the
+immutable invoice snapshot; the document has one explicit `Rückerstattung zu
+Rechnung …` line. The document, immutable artifact and final Refund resolution
+are committed in one short token-fenced transaction.
+
+For a non-canceled Refund without an existing invoice, Documents finalizes a
+`not_applicable` resolution and publishes the Refund fact without an artifact.
+It does not wait forever for a future invoice, and later invoice issuance does
+not create a second customer fact. For a canceled Order, individual Refund
+facts are suppressed in favor of the authoritative Order-cancellation
+resolution and its sorted artifact list.
+
+### Optional Batch Management integration
+
+If `@hartl-services/medusa-batch-management` version `0.0.3` or later is registered, Documents detects
+its `getOrderDocumentBatchSnapshot(orderId)` capability structurally. For every
+active withdrawal it prints the persisted **charge/lot**, **MHD** and quantity
+under the matching invoice line.
+
+These values are captured at FEFO withdrawal time. Regenerating an invoice
+reads the active withdrawals again: reverse/correct the order's allocation
+first, then regenerate to put that corrected allocation on the document.
+Renaming a Batch master record alone deliberately does not change an already
+persisted withdrawal snapshot. A shipment received before the matching durable
+batch-withdrawal run is available fails safely and can be retried. An installed
+incompatible Batch version fails explicitly before a PDF is issued; upgrade
+Batch Management and apply its migration first.
+
+Packing lists use the separate structural capability
+`getFulfillmentPackingListBatchSnapshot(fulfillmentId)`. It returns only active
+or already returned immutable LOT snapshots belonging to that exact
+fulfillment. Return receipts reconstruct the original picked quantity before a
+delayed first render. Documents validates that every managed fulfillment item's
+concrete quantity equals the sum of its LOT quantities before rendering. If
+Batch Management is not registered, the same packing list is issued without LOT
+rows. An installed but incompatible Batch version fails explicitly.
+
+A manual allocation reassignment increments the fulfillment run's allocation
+revision and emits an internal event. Documents stores a new immutable packing
+list revision and serves the newest ready PDF. Returns do not rewrite the
+historical pick instruction. Fulfillment cancellation marks the packing list as
+canceled and prevents a concurrent render from being published as active.
+
+### Document facts and artifacts
+
+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-
+cancellation resolutions each carry an `event_emitted_at` marker that is set
+only after successful enqueue.
+
+Every customer-facing attachment references an immutable `application/pdf`
+artifact. The artifact becomes permanently `communication_locked` in the same
+transaction that finalizes the fact. The publication reconciler first verifies
+the private File remains readable, and then safely republishes any final fact
+whose marker is still null. Refunds without an invoice and zero-Refund
+cancellations are the deliberate attachment-free cases.
+
+Document issuance and resolution work uses ten-minute token leases. PDF and
+File I/O runs outside database transactions. If File creation succeeds after a
+worker has lost its lease, the unreferenced private File is deleted best-effort;
+a hard process exit in that external File/database gap can leave a storage
+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
+event-name constants,
+strict Zod schemas and inferred payload types for exactly these three events:
+
+```ts
+type DocumentsEmailArtifact = {
+  artifact_id: string;
+  document_id: string;
+  document_number: string;
+  file_id: string;
+  filename: string;
+  content_type: "application/pdf";
+};
+
+type DocumentsOutgoingEmailEvent =
+  | {
+      name: "documents.shipment_invoice_assignment.decided.v1";
+      data:
+        | {
+            schema_version: 1;
+            order_id: string;
+            fulfillment_id: string;
+            decision: "non_carrier";
+          }
+        | {
+            schema_version: 1;
+            order_id: string;
+            fulfillment_id: string;
+            decision: "carrier";
+            invoice_fulfillment_id: string;
+            invoice_artifact: DocumentsEmailArtifact;
+          };
+    }
+  | {
+      name: "documents.order_cancellation_documents.ready.v1";
+      data: {
+        schema_version: 1;
+        order_id: string;
+        expected_refund_ids: string[];
+        attachments: Array<{
+          payment_id: string;
+          refund_id: string;
+          artifact: DocumentsEmailArtifact;
+        }>;
+      };
+    }
+  | {
+      name: "documents.refund_document.ready.v1";
+      data: {
+        schema_version: 1;
+        order_id: string;
+        payment_id: string;
+        refund_id: string;
+        artifact: DocumentsEmailArtifact | null;
+      };
+    };
+```
+
+Every `string` above is trimmed and non-empty. For a `carrier`,
+`invoice_fulfillment_id` must equal `fulfillment_id`. Cancellation
+`expected_refund_ids` are lexicographically sorted and unique; `attachments`
+are sorted by unique `refund_id`, and every attached Refund belongs to the
+expected set. `artifact: null` is the final no-Invoice Refund result. The events
+contain no recipient, template, Notification ID, SMTP setting or delivery
+status.
+
+Documents owns committed facts and their at-least-once publication. The E-Mail
+module owns recipient resolution, logical message deduplication, templates,
+attachments at dispatch, Medusa Notification records, SMTP attempts, status and
+explicit Admin resends. See the central
+[Email design](../../docs/superpowers/specs/2026-08-26-central-email-plugin-design.md)
+and
+[implementation plan](../../docs/superpowers/plans/2026-08-26-central-email-plugin.md).
+
+Neither event publication nor SMTP promises exactly-once delivery. Publication
+reconciliation and the Redis Event Bus may deliver a fact more than once; Email
+deduplicates the logical message by its business key. SMTP may accept a message
+before the process can persist success, so an ambiguous attempt becomes
+`unknown` and is not automatically sent again. Any later resend is an explicit
+Email Admin action and a new logical message.
+
+### Development
+
+#### Public Storefront and Admin contracts
+
+The central contracts package exports the Documents Store and Admin DTOs, Zod
+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";
+
+const response = await sdk.client.fetch<GetStoreDocumentResponse>(
+  documentsPaths.store.get.retrieve(documentId),
+  { method: "GET" },
+);
+```
+
+`@hartl-services/medusa-food-supplements-contracts/types/documents-store` and
+`@hartl-services/medusa-food-supplements-contracts/types/documents-admin` contain the
+respective type-only DTOs. Import
+`@hartl-services/medusa-food-supplements-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`
+transport DTO, while protected PDF download paths remain binary endpoints.
+
+Add a DTO schema, central contract type and path entry, HTTP integration test,
+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";
+
+const response = await sdk.client.fetch<ListAdminOrderPackingListsResponse>(
+  packingListsPaths.admin.get.listForOrder(orderId),
+  { method: "GET" },
+);
+```
+
+## Dateispeicher (S3)
+
+The base provides a Medusa File Module provider for durable S3-compatible
+asset storage with a local, TTL-based read cache (`providers/s3-cache`), and
+the `/files` gateway routes every provider URL points at. It supports AWS S3,
+MinIO and compatible endpoints through AWS SDK v3. There is no separate S3
+package since 1.0.0; the provider identifier `s3-cache` and the resolve path
+`@hartl-services/medusa-base/providers/s3-cache` replace the old one.
+
+S3 is always the source of truth. The local cache is a per-replica performance
+optimization and may be discarded at any time without data loss.
+
+### Coverage
+
+The provider covers every asset that uses Medusa's native `Modules.FILE`
+service:
+
+- public product images and other Medusa uploads;
+- private PDF documents of the Documents module, including its
+  authorized download routes and email attachments;
+- future plugins that use the same File Module.
+
+It cannot transparently back up a plugin that writes directly to its own local
+directory, own S3 client, or a third-party URL. Such integrations must be
+changed to use `Modules.FILE` or migrated explicitly.
+
+### Configuration
+
+```ts
+// medusa-config.ts
+import { createS3CacheStorageConfig } from "@hartl-services/medusa-base/config";
+
+const s3CacheStorage = createS3CacheStorageConfig({
+  s3: {
+    bucket: process.env.S3_CACHE_STORAGE_BUCKET,
+    region: process.env.S3_CACHE_STORAGE_REGION,
+    // optional: MinIO or another S3-compatible endpoint
+    endpoint: process.env.S3_CACHE_STORAGE_ENDPOINT,
+    forcePathStyle: process.env.S3_CACHE_STORAGE_ENDPOINT ? true : undefined,
+    // omit entirely to use the AWS SDK credential chain (e.g. an IAM role)
+    credentials: process.env.S3_CACHE_STORAGE_ACCESS_KEY_ID
+      ? {
+          accessKeyId: process.env.S3_CACHE_STORAGE_ACCESS_KEY_ID,
+          secretAccessKey: process.env.S3_CACHE_STORAGE_SECRET_ACCESS_KEY,
+        }
+      : undefined,
+  },
+  gateway: {
+    baseUrl: `${process.env.MEDUSA_BACKEND_URL}/files`,
+    signingSecret: process.env.FILE_GATEWAY_SIGNING_SECRET,
+  },
+});
+
+export default defineConfig({
+  modules: [s3CacheStorage.fileModule /* , ...other modules */],
+  plugins: [
+    {
+      resolve: "@hartl-services/medusa-base",
+      options: { files: { gateway: s3CacheStorage.gateway } },
+    },
+    /* , ...other plugins */
+  ],
+});
+```
+
+S3 Cache Storage needs **both** parts, which `createS3CacheStorageConfig`
+returns from one validated configuration:
+
+- `fileModule` goes under `modules`. It registers the S3 provider as Medusa's
+  File Module (`@medusajs/medusa/file`); Medusa accepts File providers only
+  there, not from a plugin.
+- `gateway` goes into the base options as `files.gateway`. It carries the
+  signing secret of the gateway routes every provider URL points at:
+  `GET /files/:asset`, `GET /files/private/:token` and
+  `PUT /files/upload/:token`. Without it, no public file, signed private
+  download or presigned upload works (the routes answer that signing is not
+  configured).
+
+Both carry the same signing secret, so the routes accept every URL the
+provider signs. Upload CORS follows Medusa's `projectConfig.http.adminCors`.
+
+`createS3CacheFileModuleConfig` remains for Medusa's stock local File Module
+(`enabled` omitted or `false`); with `enabled: true` it registers only the
+provider, without the gateway part, so use `createS3CacheStorageConfig`
+instead. The signing helpers of the routes (`createPrivateFileGatewayUrl`, ...)
+are exported from `@hartl-services/medusa-base/gateway`.
+
+Required options and environment variables:
+
+- `s3.bucket` (`S3_CACHE_STORAGE_BUCKET`) and `s3.region`
+  (`S3_CACHE_STORAGE_REGION`).
+- `gateway.baseUrl` — the public Medusa origin plus `/files`, derived from
+  `MEDUSA_BACKEND_URL`. It must never point at S3 or MinIO.
+- `gateway.signingSecret` — a strong, server-only secret used to sign private
+  file and upload URLs. Changing it invalidates every outstanding signed URL.
+
+Everything else (`s3.endpoint`, `s3.forcePathStyle`, `s3.storagePrefix`,
+`s3.credentials`, `gateway.privateDownloadDurationSeconds`, and the `cache.*`
+options) is optional; see
+[Active S3 options and defaults](#active-s3-options-and-defaults) below. The
+provider has no database migrations to run.
+
+### Environment helpers
+
+`@hartl-services/medusa-base/config` also exports small helpers for reading
+the deployment variables in `medusa-config.ts`:
+
+- `S3_BUILD_PLACEHOLDERS` — `{ S3_CACHE_STORAGE_BUCKET, S3_CACHE_STORAGE_REGION }`
+  placeholder values so `medusa build` can load the configuration without
+  deployment secrets. Use them only while building.
+- `resolveS3Credentials(process.env, phase)` — returns the static key pair
+  from `S3_CACHE_STORAGE_ACCESS_KEY_ID`, `S3_CACHE_STORAGE_SECRET_ACCESS_KEY`
+  and optional `S3_CACHE_STORAGE_SESSION_TOKEN`, or `undefined` for the AWS
+  credential chain (and always during `"build"`). A declared but incomplete
+  pair throws, naming the missing variables.
+- `resolveExpirationStrategy(process.env, defaultValue)` — reads
+  `S3_CACHE_STORAGE_EXPIRATION_STRATEGY` (`"absolute"` or `"sliding"`).
+
+### Runtime configuration
+
+The demo shop (`apps/backend`) enables S3 Cache Storage as the sole Medusa
+File Module provider through the preset; there is no per-deployment feature
+flag or local-provider fallback. Dokploy must provide
+`S3_CACHE_STORAGE_BUCKET`, `S3_CACHE_STORAGE_REGION`, and
+`MEDUSA_BACKEND_URL`. The backend URL is the public Medusa origin, for
+example `https://api.example.com`; the preset derives the `/files` gateway
+path from it. It must never point to S3 or MinIO.
+
+Set `S3_CACHE_STORAGE_ACCESS_KEY_ID` and
+`S3_CACHE_STORAGE_SECRET_ACCESS_KEY` together, or omit both to use the AWS
+credential chain. `S3_CACHE_STORAGE_SESSION_TOKEN` is valid only with that
+complete static key pair.
+
+Do not change a production shop from S3 to local storage after it has written
+S3 keys unless the matching database and storage rollback is being performed.
+The local provider cannot read S3-backed IDs. Treat a storage-provider change
+as a controlled deployment cutover, not as a runtime storage router.
+
+#### Active S3 options and defaults
+
+In this demo host, `bucket`, `region`, and the File Gateway base URL are
+required.
+Credentials are either a complete access-key pair or omitted, in which case the
+AWS SDK credential chain (for example an IAM role) is used.
+
+| Option                                   | Default              | Meaning                                                                            |
+| ---------------------------------------- | -------------------- | ---------------------------------------------------------------------------------- |
+| `s3.endpoint`                            | none                 | Internal HTTP(S) endpoint; use it for MinIO or another S3-compatible service.      |
+| `s3.forcePathStyle`                      | `false`              | Set to `true` for normal MinIO deployments.                                        |
+| `s3.storagePrefix`                       | `""`                 | Environment namespace inside the bucket, for example `production/medusa`.          |
+| `gateway.privateDownloadDurationSeconds` | `3600`               | Lifetime of signed Medusa download URLs; `1`–`604800`.                             |
+| `cache.dir`                              | `./.medusa-s3-cache` | Writable local directory belonging to one replica.                                 |
+| `cache.ttlMs`                            | `3600000`            | Cache freshness window; `0`–`604800000`.                                           |
+| `cache.expirationStrategy`               | `absolute`           | `absolute` keeps the original write timestamp; `sliding` refreshes mtime on a hit. |
+| `cache.cleanupIntervalMs`                | `900000`             | Startup cleanup plus this unreferenced timer; `1`–`86400000`.                      |
+
+URLs may use only HTTP(S), with no credentials, query string, or fragment.
+Prefixes and provider keys reject absolute paths, traversal, control
+characters, and backslashes.
+
+### Object and access model
+
+New uploads have opaque keys. The original filename is stored only as encoded
+object metadata:
+
+```text
+logical key:  public/<ULID>.<ext>   or private/<ULID>.<ext>
+S3 key:       <storagePrefix>/<logical key>
+public URL:   <MEDUSA_BACKEND_URL>/files/<ULID>.<ext>
+private URL:  <MEDUSA_BACKEND_URL>/files/private/<signed-token>
+```
+
+No provider method returns an S3 URL. Public files receive stable Medusa gateway
+URLs and `Cache-Control: public, max-age=31536000, immutable`; their keys never
+change, so browser or an optional CDN in front of Medusa may cache them safely.
+Generic private files receive short-lived HMAC-signed Medusa URLs with
+`private, no-store`. Domain files such as invoices continue to use their
+authenticated Documents routes. Gateway responses use a restrictive sandbox
+Content Security Policy so active uploaded formats cannot execute under the
+Medusa API origin.
+
+The provider sends no S3 ACL parameter. Keep the complete bucket and every
+prefix private. Only the Medusa runtime receives S3 credentials. Public and
+private presigned-upload requests receive a short-lived Medusa PUT capability
+under `/files/upload`; upload and download signatures are not interchangeable.
+The route accepts at most 100 MiB and allows configured `ADMIN_CORS` origins
+without exposing S3.
+
+Backend reads (`getDownloadStream` and `getAsBuffer`) share an atomic cache:
+cache filenames are SHA-256 hashes, concurrent misses for one object download
+once per replica, and a failed refresh never serves an expired object. A
+successful remote write/delete evicts the affected entry only after S3 has
+accepted it. Do not share the cache directory between replicas; use a bounded
+`emptyDir` or per-pod volume and monitor free disk space.
+
+### Backup and restore
+
+A complete restore requires both a PostgreSQL backup and the versioned object
+store. The cache is not a backup and is intentionally excluded.
+
+Before production use, provision a dedicated bucket and prefix per
+environment, Block Public Access, SSE-S3 or KMS encryption, least-privilege
+application IAM, versioning, and lifecycle cleanup for old versions/abandoned
+multipart uploads. For stronger recovery objectives, add cross-account or
+cross-region replication and rehearse restores.
+
+To restore on another server, restore the database and bucket/prefix, keep the
+same File Gateway base URL and signing secret, configure the provider, and let
+the replica caches start empty.
+
+The Documents module ships a read-only restore drill. It streams
+every issued PDF through the active File provider and reports the verified file
+count and total bytes without modifying data:
+
+```sh
+medusa exec ./node_modules/@hartl-services/medusa-base/.medusa/server/src/documents/scripts/verify-documents-file-storage.js
+```
+
+### HTTP contract
+
+The gateway routes expose `GET /files/:asset` for public immutable files and
+`GET /files/private/:token` for signed private capability URLs. Both call
+`Modules.FILE.getDownloadStream`, so a fresh local cache entry is always used
+before S3. The private route validates its query through the Contracts schema.
+Paths, query types, and the runtime query schema are exported from the separate
+`/paths/files`, `/types/files`, and `/schemas/files` Contracts subpaths. Clients
+normally consume the complete URL returned by Medusa and never construct a
+private URL themselves.
+
+## Shop-Config-Preset
+
+`@hartl-services/medusa-base/shop-config` turns a food 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
+assembled there; the shop supplies only its own facts. It reuses the `/config`
+helpers above for environment parsing. It is a separate subpath because it
+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`,
+`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 \
+  @hartl-services/medusa-payload-sync \
+  @medusajs/event-bus-redis @medusajs/payment-stripe \
+  @sentry/node
+```
+
+### Usage
+
+```ts
+// medusa-config.ts
+import { defineFoodShopConfig } from "@hartl-services/medusa-base/shop-config"
+
+module.exports = defineFoodShopConfig({
+  merchant: {
+    countryCode: "at",
+    legalName: "Example Shop GmbH",
+    registeredAddress: {
+      address1: "Musterstrasse 1",
+      city: "Wien",
+      countryCode: "at",
+      postalCode: "1010",
+    },
+    vatNumber: "ATU12345678",
+  },
+  displayName: "EXAMPLE SHOP",
+  orderNotificationEmail: "orders@example.com",
+  timeZone: "Europe/Vienna",
+  storefrontCountryCode: "de",
+})
+```
+
+A shop that has to adjust the result (a test harness, for example) builds the
+plain input, changes it and calls `defineConfig` itself:
+
+```ts
+import { defineConfig } from "@medusajs/framework/utils"
+import { buildFoodShopConfig } from "@hartl-services/medusa-base/shop-config"
+
+const config = buildFoodShopConfig(options)
+config.plugins = config.plugins.filter(
+  (plugin) => plugin.resolve !== "@hartl-services/medusa-batch-management",
+)
+module.exports = defineConfig(config)
+```
+
+### API
+
+- `defineFoodShopConfig(options, environment = process.env)` returns
+  `defineConfig(buildFoodShopConfig(options, environment))`.
+- `buildFoodShopConfig(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`.
+
+Both functions validate the options first and throw a `TypeError` naming the
+option (`Food 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.
+
+### Options
+
+| Option | Meaning |
+| --- | --- |
+| `merchant` | `DocumentMerchantOption` (`countryCode`, `legalName`, `registeredAddress`, optional `vatNumber`). Fallback for the Shop-Stammdaten (Admin, "Hartl Services Plugins") that documents and tax compliance read per field; `legalName` is also the seeded store name. Country codes are 2-letter lowercase. |
+| `displayName` | Shop name in the default e-mail templates. |
+| `orderNotificationEmail` | Receives order notification e-mails; must look like an e-mail address. |
+| `timeZone` | IANA time zone (validated with `Intl`). Chooses the annual document-number period, the printed dates on documents and the affiliate consignment reminder time zone. |
+| `storefrontCountryCode` | 2-letter lowercase country code of the storefront route. Links: `<STOREFRONT_URL>/<cc>/partnerportal` (affiliate portal), `<STOREFRONT_URL>/<cc>/reset-password` (the e-mail plugin appends `#token=`), referral base `<STOREFRONT_URL>/<cc>`. The Admin invite link is `<MEDUSA_BACKEND_URL>/app/invite?token=`. |
+| `loadEnvFile` | Default `true`: calls `loadEnv(NODE_ENV \|\| "development", process.cwd())`. Pass `false` when the environment is already complete (tests, isolated child processes). |
+
+### Environment variables
+
+Required at runtime (during `medusa build`, with `MEDUSA_BUILD_PHASE=true`, the
+plugins' build placeholders stand in for them):
+
+- Medusa core: `DATABASE_URL`, `STORE_CORS`, `ADMIN_CORS`, `AUTH_CORS`,
+  `JWT_SECRET`, `COOKIE_SECRET`, `MEDUSA_BACKEND_URL`, `STOREFRONT_URL` (plain
+  HTTP origins are accepted only in development and test).
+- Redis: `REDIS_URL` (optional in development, where Medusa's local event bus
+  is used; required elsewhere, `rediss://` with authentication in production
+  unless `REDIS_ALLOW_INSECURE_PRIVATE_NETWORK=true`). Never used during a
+  build.
+- SMTP: `SMTP_HOST`, `SMTP_PORT`, `SMTP_SECURE`, `SMTP_USER`, `SMTP_PASSWORD`,
+  `SMTP_FROM`, `SMTP_REQUIRE_TLS` (outside development and test either
+  `SMTP_SECURE` or `SMTP_REQUIRE_TLS` must be `true`).
+- Stripe: `STRIPE_API_KEY` (`sk_...`), `STRIPE_WEBHOOK_SECRET` (`whsec_...`).
+- S3: `S3_CACHE_STORAGE_BUCKET`, `S3_CACHE_STORAGE_REGION`.
+- Documents: `DOCUMENT_PDF_EXECUTABLE`.
+
+Optional: `S3_CACHE_STORAGE_ENDPOINT`, `S3_CACHE_STORAGE_FORCE_PATH_STYLE`,
+`S3_CACHE_STORAGE_PREFIX`, `S3_CACHE_STORAGE_ACCESS_KEY_ID`,
+`S3_CACHE_STORAGE_SECRET_ACCESS_KEY`, `S3_CACHE_STORAGE_SESSION_TOKEN` (omit
+the keys to use the AWS credential chain), `S3_CACHE_STORAGE_CACHE_DIR`
+(default `./.medusa-s3-cache`), `S3_CACHE_STORAGE_TTL_MS`,
+`S3_CACHE_STORAGE_CLEANUP_INTERVAL_MS`,
+`S3_CACHE_STORAGE_EXPIRATION_STRATEGY`,
+`FILE_GATEWAY_PRIVATE_DOWNLOAD_DURATION_SECONDS`, and `SENTRY_DSN` /
+`SENTRY_ENVIRONMENT` for error tracking (see the base's
+`/instrumentation`).
+
+### Fixed configuration
+
+Not configurable on purpose: the plugin order (base first), the Redis event
+bus job policy (3 attempts, exponential backoff from 1 s), S3 cache defaults
+(15 min cleanup, 1 h TTL, absolute expiration), Stripe immediate capture with
+automatic payment methods, the 24 h session lifetime, Admin path `/app`,
+consignment reminders due on day 10, and the Documents module always being part of the base.