@hartl-services/medusa-base 0.4.0 → 1.1.0

package/README.md

@@ -4,7 +4,10 @@ Medusa v2.19 base plugin for Hartl Services shops. Every shop installs it. It
 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.
+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
 
@@ -33,6 +36,19 @@ enforce their toggles and read their settings.
 - 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
 
@@ -49,18 +65,46 @@ plugins: [
     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 only option is `settingsSecret` (`BasePluginOptions`, optional): the key
-material for stored secret settings. Set it from an environment variable of
-the shop; unset or empty, the base uses `projectConfig.http.cookieSecret`.
-Run `medusa db:migrate` after installing it (and
-after upgrading: 0.4.0 adds the tables `plugin_setting_state` and
-`plugin_action_run`).
+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`)
@@ -71,6 +115,7 @@ 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` |
@@ -273,7 +318,10 @@ class DemoModuleService extends MedusaService({ /* models */ }) {
 
 - 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
+  non-empty, unique values; the stored value must be one of them), `image`
+  (the http(s) URL of a PNG/JPEG of at most 2 MiB that the Admin uploads
+  through Medusa's `/admin/uploads` into the public File Module storage and
+  previews; replacing or removing it leaves the old file in storage). 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
@@ -634,3 +682,1724 @@ 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.
+
+The plugin declares one setting, edited in the Einstellungen section of its
+Admin page: `logo` (type `image`, optional), the PNG/JPG shown on top of every
+mail. It is not a Shop-Stammdaten field; Documents has its own `logo`.
+
+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 the configured `displayName` plus the `logo` setting of
+  the E-Mail plugin and the company details of the Shop-Stammdaten; 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 in grey tones (table-based,
+inline styles) and one renderer per accepted kind. The layout shows, from top
+to bottom: the `logo` centered (an `image` setting of the E-Mail plugin,
+edited on its Admin page; without one, the configured `displayName`), a white card with the subject as heading and the
+renderer's body, a contact line ("Fragen? Dann schreib uns an … oder ruf uns
+an unter …", only with `email`/`phone`), and a footer with the company details
+(`legal_name` or `displayName`, address, UID, Firmenbuchnummer and
+Firmenbuchgericht, website) plus "Diese E-Mail wurde automatisch versendet.".
+Missing master data fields are left out. Email reads the logo and the
+Shop-Stammdaten when it sends a mail, so a change applies to the next mail; if
+a read fails the mail is sent without that part (logo or company details)
+instead of failing. Besides
+the layout, `displayName` appears in the password-reset and invite subjects.
+A custom `layout` receives the same data as `shop` (`EmailShopDetails`, every
+field optional) next to `bodyHtml`, `preheader` and `subject`. A shop
+therefore needs only `displayName`, `affiliatePortalUrl`, `inviteUrl`,
+`passwordResetUrl` and `orderNotificationEmail`.
+
+The order confirmation (`order.received`) receives an `OrderSummary` as
+`summary`: the display ID, the items with quantity and gross amount, the
+shipping method names, subtotal, shipping, discount, included tax and total,
+plus the billing and shipping address. Email freezes it when the order is
+placed, so a resend shows the order as it was placed. `summary` is absent for
+messages stored before the summary existed; a custom renderer must handle
+that case.
+
+The shop's order notification (`order.received.admin`) receives the same
+`summary` (with the order's `email` and `placed_at`). Its subject names the
+order number and the customer ("Neue Bestellung #1042 von Ada Beispiel"),
+an info box lists number, customer, e-mail and order time, followed by an
+"Im Admin öffnen" button and the items, totals and addresses. Two optional
+`ShopEmailConfiguration` fields drive it: `adminOrderUrl({ orderId })` (the
+button is left out without it) and `timeZone` (IANA; the order time is left
+out without it). `buildFoodShopConfig` sets both (`<MEDUSA_BACKEND_URL>/app/
+orders/<id>` and its `timeZone` option). The layout receives `audience`
+(`"shop"` for this kind and `user.invite`, `"customer"` for all others) and
+shows the contact line only to customers.
+
+The shipping confirmation (`order.shipped`, one per fulfillment) receives a
+`ShipmentSummary` as `shipment`, frozen when the shipment fact arrives: the
+display ID, the shipping option name, the tracking numbers and URLs entered
+at shipping, the parcel's items (title and variant of the order line,
+shipped quantity), the delivery address and `more_to_follow` (some ordered
+quantity is not shipped yet). `invoice_attached` is `true` when Documents chose
+this shipment for the invoice PDF. Its subject is "Deine Bestellung bei
+<displayName> ist unterwegs"; a single http(s) tracking URL becomes a
+"Sendung verfolgen" button, several become one link each. A fulfillment that
+cannot be read is confirmed without `shipment`, like a message stored before
+the snapshot existed.
+
+The cancellation confirmation (`order.canceled`) receives the same
+`OrderSummary` as `summary` plus `canceled_at`, frozen when the cancellation
+fact arrives, and `cancellation_attached` (`true` when Documents attached at
+least one cancellation document). Its subject is "Deine Bestellung #1042 bei
+<displayName> wurde storniert"; an info box lists the order number and the
+cancellation date (left out without `timeZone`), followed by a fixed refund
+note and the canceled items and totals without addresses. An order that
+cannot be summarized is confirmed without `summary` and without its internal
+ID.
+
+The return confirmation (`order.return_requested`) receives a `ReturnSummary`
+as `summary`, frozen when the return is requested: return and order numbers,
+the return shipping method, the items to send back (title and variant of the
+order line, quantity, return reason label) and the return address. It is
+the stock location's address, addressed to the location's company or else
+the master data's `legal_name`; without a location address it falls back to
+the master data's company address. Its subject is "Deine Rücksendung zur
+Bestellung #1042 bei <displayName>"; the mail asks the customer to enclose
+the return number (`#R5`). A return that cannot be read is confirmed without
+`summary` and without internal IDs.
+
+The return receipt (`order.return_received`, sent once the return is
+completely received) receives a `ReturnReceivedSummary` as `summary`: return
+and order numbers, `received_at` and the received items (title and variant
+of the order line, received quantity and the damaged part of it). Its subject
+is "Deine Rücksendung zur Bestellung #1042 bei <displayName> ist
+eingetroffen"; the arrival date needs `timeZone`, damaged units are noted per
+item, and a fixed sentence says that an eventual refund follows on the
+original payment method, without promising a separate mail (`order.refunded`
+only exists with Documents).
+
+The refund confirmation (`order.refunded`, one per non-cancellation refund,
+Documents only) receives a `RefundSummary` as `summary`, frozen when the
+Documents refund fact arrives and read through the refund's payment: order
+number, refunded gross amount and currency, `refunded_at` and the Admin's
+refund reason label. `cancellation_attached` is `true` when Documents attached
+a cancellation document. Its subject is "Deine Erstattung zur Bestellung #1042
+bei <displayName>"; the info box shows number, amount, date (needs
+`timeZone`) and reason, followed by a fixed note on bank processing times.
+Without `summary` the mail keeps the intro and the attachment note.
+
+The password reset (`auth.password_reset`) has the subject "Neues Passwort
+für dein Kundenkonto bei <displayName>", a "Neues Passwort festlegen" button,
+the link as copyable text below it, the link's lifetime ("Der Link ist 15
+Minuten gültig.", computed from the token's `exp` − `iat` and left out
+without `iat`) and a note that the mail can be ignored. The lifetime is
+passed as the ephemeral `valid_minutes` next to `reset_url` and is never
+persisted.
+
+The affiliate reminder (`affiliate.consignment_report_due`) greets the
+affiliate by `affiliate_display_name`, names the report month ("September
+2026", Austrian month names) and the due date ("10.10.2026") as calendar
+values formatted in UTC so no time zone shifts them, explains that the counted
+stock determines the billed sales, links `affiliatePortalUrl` as a "Zum
+Partnerbereich" button and says the mail can be ignored once the report is
+submitted. The button leads to a 404 while the affiliate plugin's
+`partner_portal` toggle is off.
+
+The Admin invite (`user.invite`) has the subject "Einladung ins Admin-Team von
+<displayName>", an "Einladung annehmen" button with the link as copyable text,
+the invite's current expiry ("Die Einladung ist gültig bis 02.10.2026, 01:40
+Uhr.", needs `timeZone`; read from the invite at send time, so a resend shows
+its new expiry) and a note that the mail can be ignored. The expiry is passed
+as the ephemeral `expires_at` next to `invite_url`. The invite goes to the
+shop's team, so its layout audience is `"shop"` (no contact line).
+
+- `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, theme? })` — the built-in
+  factory, to use as it is, with a shop theme (see "Layout, logo, payment
+  terms and shop theme" below) or to wrap.
+- `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`.
+
+### Layout, logo, payment terms and shop theme
+
+The default markup prints an A4 letterhead: logo top left, document title and
+key data (number, order, date, customer UID for exempt B2B supplies) on the
+right, the billing address on the left, the item table with batch and
+best-before date per line, the totals below the price columns and a
+three-column footer (sender with UID and company register, contact, bank) on
+every page. Packing lists show only the sender in the footer. Every page
+carries "Seite x von y" bottom right in an 8 mm bottom page margin
+(`@page { @bottom-right }`; the page count exists only in page margin boxes).
+
+Settings under Settings → "Hartl Services Plugins" → **Dokumente**, read on
+every render and passed as `input.settings` (`DocumentRenderSettings`). Like
+the merchant data they are not part of the snapshot: a regenerated document
+shows the current values.
+
+- **Logo** (`logo`, PNG or JPG): each render downloads it (10 s timeout, at
+  most 2 MiB) and passes it inline as `settings.logo_src` (`data:` URL), so
+  Chromium never waits on the network. Without a logo, or when the download
+  fails (logged as a warning), the document shows the merchant's legal name;
+  a logo never blocks issuance.
+- **Zahlungskonditionen** (`payment_terms`, text): printed below the totals
+  of invoices only (not on cancellations or credit notes); blank means none.
+  Line breaks in the text are kept.
+
+**Theme:** `createDefaultDocumentHtmlFactory({ timeZone, theme })` keeps the
+content and markup and changes only the look. `theme.stylesheet` is CSS
+appended after the default stylesheet (later rules win; the defaults use the
+custom properties `--accent`, `--text`, `--muted`, `--line`, `--table-head`,
+`--page-x`, `--page-top`, `--footer-height`). Put a watermark or other
+full-page image into `@page { background: ... / 210mm 297mm }`: it covers the
+whole sheet on every page, whereas Chromium clips fixed elements at the page
+margin and sizes an inline `<svg>` in them wrongly from the second page on.
+Restyle the page number with `@page { @bottom-right { ... } }`. Embed web
+fonts as `data:` URLs; the container's Chromium has only its system fonts. A
+shop passes its factory through the preset option `documentHtmlFactory` (see
+"Shop-Config-Preset").
+
+### 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=`. |
+| `documentHtmlFactory` | Optional `DocumentHtmlFactory` that replaces the default document markup, typically `createDefaultDocumentHtmlFactory({ timeZone, theme })` from `/config` with the shop's CSS and watermark (see "Layout, logo, payment terms and shop theme"). Must be a function. |
+| `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.