@hartl-services/medusa-base 2.4.0 → 2.6.0

package/README.md

@@ -31,7 +31,8 @@ packing lists) and S3 file storage, and the turnkey `medusa-config.ts` preset
 - Holds the shop's master data (Firmenangaben) as its own settings and
   exports `getShopMasterData` (see "Shop-Stammdaten").
 - Exports Admin components from `@hartl-services/medusa-base/admin-components`
-  so a plugin composes the base's sections into its own page and hides
+  (also `sdk`, `getErrorMessage` and the rich-text editor) and server helpers
+  from `@hartl-services/medusa-base/lib` (`toWireResponse`) so a plugin composes the base's sections into its own page and hides
   widgets of disabled features (see "Admin components for plugin pages").
 - Owns the `completeCartWorkflow` hooks `validate` and `orderCreated` and runs
   the workflows that plugins declare for them (see "Complete-cart hook
@@ -112,7 +113,7 @@ exports from the matching `@hartl-services/medusa-base` subpath. 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`)
+`@medusajs/medusa`, `@medusajs/admin-sdk`, `@medusajs/js-sdk`, `@medusajs/ui`, `@medusajs/icons`)
 plus React, React Router and TanStack Query in the versions the Medusa 2.19
 dashboard uses.
 
@@ -216,6 +217,9 @@ export default defineMiddlewares({
 })
 ```
 
+`pluginFeatureGate(demoPluginFeatures)` returns the same entries as a short
+`gate("/store/demo/coupons", "coupons")`.
+
 A disabled plugin or feature answers 404. With several keys, all must be
 enabled. The toggles are read once per request.
 
@@ -329,7 +333,11 @@ class DemoModuleService extends MedusaService({ /* models */ }) {
   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
+  previews; replacing or removing it leaves the old file in storage), `color`
+  (a hex color `#rrggbb`, stored lowercase; the Admin shows a hex field with a
+  color picker and checks the format before saving). An optional `group`
+  (non-empty text) is a section heading: the Admin starts a new section with
+  that heading whenever the group changes from one setting to the next. 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
@@ -488,6 +496,22 @@ settings like any plugin's:
 | `iban`, `bic` | string | no |
 | `company_register_number` (Firmenbuchnummer), `company_register_court` (Firmenbuchgericht) | string | no |
 
+These company fields form the section "Firmendaten". The section
+"Erscheinungsbild" below them holds the look of the default e-mail and
+document layouts; all of it is optional:
+
+| Key | Type | Used by the default e-mail layout | Used by the default document layout |
+|---|---|---|---|
+| `logo` | image | on top of every mail (else the `displayName`) | top left (else the legal name) |
+| `color_accent` (Akzentfarbe) | color | buttons, heading, logo fallback text, tracking links | `--accent` |
+| `color_text` (Textfarbe) | color | body text, values, item titles, totals | `--text` |
+| `color_muted` (Nebentextfarbe) | color | labels, links, variants, footer | `--muted` |
+| `color_line` (Linienfarbe) | color | borders and dividers | `--line` |
+| `color_surface` (Flächenfarbe) | color | page background, info box | `--table-head` |
+
+An empty color keeps the default of that output, so without any value mails
+and documents look as before. Button text and the mail card stay white.
+
 Server-side code reads them exactly as stored in the Admin; there is no
 medusa-config fallback:
 
@@ -503,9 +527,24 @@ if (!configured) {
 }
 ```
 
+The appearance is read separately and holds only what is set:
+
+```ts
+import { getShopAppearance } from "@hartl-services/medusa-base"
+
+const { logo, colors } = await getShopAppearance(container)
+// colors: { accent?, text?, muted?, line?, surface? } as lowercase #rrggbb
+```
+
 The base only checks presence and type; what counts as a usable value
 (for example a placeholder UID) is the consuming plugin's rule.
 
+The migration script `move-logo-to-shop-appearance` (run once by
+`medusa db:migrate`) moved the former `logo` settings of the E-Mail and the
+Documents plugin into the appearance: the Documents logo, else the E-Mail
+logo; a `logo` stored in the Shop-Stammdaten by an earlier release is kept
+only when neither plugin had one.
+
 ## Admin pages
 
 - `/settings/hartl-services` (sidebar entry "Hartl Services Plugins") is the
@@ -542,6 +581,28 @@ build, with types) exports:
 | `usePluginFeatureEnabled(pluginKey, ...featureKeys)` | `{ enabled, isPending, isError }` from the shared list query (30 s stale time); plugin switch and every key must be effective; `enabled` is `false` while loading and on error |
 | `PluginFeatureGate({ pluginKey, featureKeys?, fallback? })` | Renders `children` only while enabled, otherwise `fallback` (default nothing) |
 | `PluginFeatureDisabledNotice({ pluginKey, featureLabel? })` | "Diese Funktion ist unter Einstellungen → Hartl Services Plugins ausgeschaltet." with a link to the hub |
+| `sdk` | The Admin's configured Medusa JS SDK client (`sdk.client.fetch(path, { query })`); use it instead of a per-plugin copy |
+| `getErrorMessage(error, fallback?)` | Readable message from an unknown error (SDK `response.data.message`, `body.message`, `Error.message`), else `fallback` |
+| `ADMIN_LOCALE` (`de-AT`), `ADMIN_DASH`, `formatDate(value, { timeZone? })`, `formatDateTime(value, { timeZone? })`, `formatAmount(amount, currencyCode)`, `getTodayInputDate({ utc? })` | The one Admin locale and formatters; `"-"` for empty or invalid values; pass `{ timeZone: "UTC" }` for date-only values stored at UTC midnight |
+| `useDebouncedValue(value, delayMs)` | Debounced copy of a value |
+| `fetchPdfObjectUrl(path)` | Loads a PDF through `sdk` and returns an object URL; the caller revokes it |
+| `usePdfPreview()` | Returns `{ isOpen, url, isLoading, error, open(load, errorMessage), close() }` for a `PdfPreviewModal`; `load` returns an object URL (e.g. `() => fetchPdfObjectUrl(path)`). Drops stale responses and revokes the URL on close, replacement and unmount |
+| `dateFromInputValue(value)`, `inputValueFromDate(date)` | `"yyyy-mm-dd"` calendar-date string state <-> local `Date` for `DatePicker` (which reads and emits local dates); `null` / `""` for empty or invalid |
+| `validateFile(file, { maxBytes, types, extensions?, messages })` | Pure check of a picked file: `messages.wrongType` / `empty` / `tooLarge` (German text of the caller) or `null`. With `extensions` the name must end with one and an empty MIME type is tolerated |
+| `dateTimeFromInputValue(value)`, `inputValueFromDateTime(date)` | Same for `"yyyy-mm-ddThh:mm"` with `DatePicker granularity="minute"` |
+| `SectionHeader({ title, description?, actions?, level? })` | Heading, subtle description and actions at the top of a `Container className="divide-y p-0"` section |
+| `QueryState({ isLoading, error?, isError?, isEmpty?, loadingText?, errorText?, emptyText?, children? })` | Loading, error and empty body (`px-6 py-8`), otherwise `children`; `errorText` may be a function of the error message |
+| `BackLink({ to, label })` | Arrow icon (`ArrowLongLeft`) + label link above a page |
+| `PluginFeatureRoute({ pluginKey, featureKey?, featureLabel?, hideOnError?, children })` | Route body: nothing while pending, `children` when enabled, otherwise `PluginFeatureDisabledNotice` |
+| `SearchableReferenceField<T>(props)`, type `SearchableReferenceFieldProps` | Search input with a debounced overlay result list (opens on focus/typing, closes on select, Escape or outside click), optional selected card with optional clear button; the caller runs its query on `onDebouncedQueryChange` |
+| `PdfPreviewModal({ open, onOpenChange, title, url, isLoading?, error? })` | `FocusModal` with an iframe for a PDF object URL |
+| `AdminDatePicker(props)` | Medusa `DatePicker` pinned to `ADMIN_LOCALE` (de-AT) via `I18nProvider`; the dashboard language would otherwise show "MM/DD/YYYY". Use it instead of `DatePicker` (importing that from `@medusajs/ui` is a lint error) |
+| `DateRangeFilter({ from, to, onChange, fromLabel?, toLabel? })` | "Von" / "Bis" `AdminDatePicker` pair on `yyyy-mm-dd` strings; `onChange({ from, to })`. Renders the two fields as a fragment, the caller sets the layout. No from > to check (caller's job); an external reset needs a `key` |
+| `FilePickerButton({ accept, label, disabled?, isLoading?, id?, onFileSelected })` | Medusa `Button` that opens the file dialog of a hidden `<input type="file">`; calls `onFileSelected(file)` and resets the input |
+| `OffsetTablePagination({ count, offset, limit, onOffsetChange, maxOffset? })` | German `Table.Pagination` footer for an offset/limit list ("1 - 20 von 45 Ergebnisse", "Zurück", "Weiter") |
+| `MappedStatusBadge({ value, map, fallback? })` | `StatusBadge` from a `value → { label, color }` map; empty value renders `ADMIN_DASH` |
+| `useRichTextEditor(config, initialContent, deps)`, `RichTextEditor`, `InsertMenu`, `filterSlashItems`, `normalizeLinkHref`, `isDefaultAllowedHref`, types `RichTextEditorConfig`, `SlashItem`, `SlashContext`, `NestedContainer` | Generic TipTap editor, see "Rich-text editor" |
+| `Node`, `Mark`, `Extension`, `mergeAttributes`, `ReactNodeViewRenderer`, `NodeViewWrapper`, `NodeViewContent`, `useEditorState`, `Plugin`, `PluginKey`, `NodeSelection`, `TextSelection`, types `AnyExtension`, `ChainedCommands`, `Editor`, `JSONContent`, `NodeViewProps`, `Range` | Re-exported TipTap and ProseMirror building blocks for editor extensions; a plugin needs no own `@tiptap/*` dependency |
 
 ```tsx
 // src/admin/routes/settings/hartl-services/demo/page.tsx
@@ -587,6 +648,151 @@ The consuming plugin lists `@hartl-services/medusa-base` in its
 external and the shop's Admin resolves one shared copy. The components use
 the host Admin's React, React Query, React Router and `@medusajs/ui`.
 
+#### Rich-text editor
+
+`useRichTextEditor(config, initialContent, deps)` returns the TipTap
+`Editor | null` (`null` until it exists), `<RichTextEditor editor
+linkInvalidMessage? className? styles? toolbarExtra? />` renders toolbar and
+content. `config` (`RichTextEditorConfig`, all optional):
+
+| Key | Meaning |
+| --- | --- |
+| `starterKit` | `Partial<StarterKitOptions>`; disable what the document may not contain (the starter kit's own link is always off) |
+| `link` | `false` leaves the link mark and its toolbar button out; `{ isAllowedHref }` sets the link policy; omitted: http(s) and mailto (`isDefaultAllowedHref`). The policy is stored on the editor, so the Link mark, the toolbar and the link prompt always use the same function |
+| `extensions` | The owner's nodes and marks, added after the starter kit and link |
+| `slashItems({ query, editor })` | Returns the entries of the "/" menu (`SlashItem[]`, already filtered by `query`); the menu exists only with it |
+| `dragHandle` | `true` for a grip left of each block, or `{ nestedContainers: [{ nodeName, contentSelector }] }` to give children of a container their own grip |
+| `ariaLabel` | Accessible name of the writing area |
+| `editorProps` | ProseMirror props; `attributes` must be an object, it is merged over the base's `role` and `aria-label` |
+
+`SlashItem<T>` is `{ id, label, hint?, data: T, run(editor, range) }`;
+`filterSlashItems(items, query)` keeps the entries whose label contains the
+query. `normalizeLinkHref(input, isAllowed)` turns a typed target into an
+allowed href (`mailto:` for a bare address, `https://` for a bare host) or
+`null`. `InsertMenu({ label, options, labels, onSelect })` is a toolbar
+dropdown for `toolbarExtra`. The e-mail template editor
+(`features/email/template-editor/use-template-editor.ts`) is the reference
+extension.
+
+```tsx
+import {
+  Node,
+  RichTextEditor,
+  filterSlashItems,
+  mergeAttributes,
+  useRichTextEditor,
+  type JSONContent,
+  type RichTextEditorConfig,
+  type SlashItem,
+} from "@hartl-services/medusa-base/admin-components"
+import { Button } from "@medusajs/ui"
+
+const Callout = Node.create({
+  name: "callout",
+  group: "block",
+  content: "inline*",
+  parseHTML: () => [{ tag: "div[data-callout]" }],
+  renderHTML: ({ HTMLAttributes }) => [
+    "div",
+    mergeAttributes(HTMLAttributes, { "data-callout": "" }),
+    0,
+  ],
+})
+
+const calloutItems: SlashItem[] = [
+  {
+    id: "callout",
+    label: "Hinweisbox",
+    data: null,
+    run: (editor, range) =>
+      editor.chain().focus().deleteRange(range).setNode("callout").run(),
+  },
+]
+
+const config = {
+  extensions: [Callout],
+  slashItems: ({ query }) => filterSlashItems(calloutItems, query),
+  ariaLabel: "Text",
+} satisfies RichTextEditorConfig
+
+export const NoteEditor = ({ initial }: { initial: JSONContent }) => {
+  const editor = useRichTextEditor(config, initial, [])
+  if (!editor) return null
+  return (
+    <RichTextEditor
+      editor={editor}
+      toolbarExtra={
+        <Button size="small" variant="secondary" onClick={() => editor.commands.setNode("callout")}>
+          Hinweisbox
+        </Button>
+      }
+    />
+  )
+}
+```
+
+Stability: the editor is created once and re-created only when `deps`
+change (it then starts from the `config` and `initialContent` of that
+render, so the cursor is lost). `starterKit`, `extensions`, which features are
+on (`link`, `slashItems`, `dragHandle`), `ariaLabel` and `editorProps` are
+read at creation; changing them has an effect only together with a change of
+`deps` (for example the id of the loaded document). `slashItems` and the link
+policy (`link.isAllowedHref`) are read on every use and always see the latest
+render, so they need no stable reference. Pass `[]` for an editor that lives as
+long as its component.
+
+### Server helpers
+
+`@hartl-services/medusa-base/lib` (server and isomorphic code; a separate
+subpath because unit tests mock `@hartl-services/medusa-base` wholesale)
+exports:
+
+| Export | Purpose |
+| --- | --- |
+| `toWireResponse(schema, value)` | Serializes `value` as HTTP JSON does (`JSON.parse(JSON.stringify(value))`), then `schema.parse`s it with a Contracts Zod schema, which strips fields outside the public response contract; returns `z.infer<typeof schema>`. Use it for `res.json(...)` in custom routes |
+| `toNumericAmount(value)` | Finite number from a number, numeric string, Medusa `BigNumber` (by shape, not `instanceof`), bignumber.js value or raw `{ value }`; `null` for anything else (blank, `NaN`, `Infinity`) |
+| `getCurrencyDecimalPlaces(currencyCode)` | Minor-unit digits from Medusa's currency table (EUR 2, JPY 0, KWD 3); 2 for an unknown currency |
+| `SqlManager` (type) | Raw SQL surface of a module's transaction manager: `execute(query, params?, method?)`, optional `flush()` |
+| `requireTransactionManager(sharedContext, message?)` | `sharedContext.transactionManager`; throws `UNEXPECTED_STATE` without one (no fallback to `manager`) |
+| `acquireAdvisoryXactLock(manager, key)` | `select pg_advisory_xact_lock(hashtext(?))` with a string key; serializes work per business key until commit |
+| `isUniqueConstraintViolation(error)` | `true` for Postgres 23505 (also in `cause` / `driverError`) or the `INVALID_DATA` MedusaError "... with <field>: <value>, already exists." |
+| `describeError(error)` | Message of an `Error` or error-like object, else `String(error)` |
+| `resolveOptionalLogger(source)` | Logger with `warn` from a container (`resolve("logger")`) or a module cradle (`cradle.logger`), else `undefined`; never throws |
+| `createWarnOnce()` | Returns `warnOnce(key, signature, warn)`: runs `warn` unless the last warning for `key` had the same `signature` (returns whether it ran); `warnOnce.reset(key?)` re-arms |
+| `sha256Hex(value)` | Lower-case hex SHA-256 of a string (UTF-8) or bytes |
+| `toValidDate(value, message?)` | `Date` from `Date` / string / number; throws `INVALID_DATA` for an invalid date |
+| `startOfUtcDate(value)` / `toIsoDate(value)` | Midnight UTC of the UTC day / its `yyyy-mm-dd`; throw for an invalid date |
+| `toWireDate(value)` / `toOptionalWireDate(value)` | ISO-8601 string for a response (throws for an invalid date) / `null` for `null` and `undefined` |
+| `isValidTimeZone(value)` | `true` for a non-blank IANA time zone the runtime knows |
+| `normalizeVatNumber(value)`, `VAT_NUMBER_PLACEHOLDER` | Whitespace removed and upper-cased; the development placeholder UID `ATU00000000` |
+| `normalizeEmail(value)` | Trimmed and lower-cased; `null` for blank or malformed (no "@", leading or trailing "@") so the caller decides whether to throw |
+| `escapeLikePattern(value)` | Escapes `\`, `%` and `_` for `LIKE` / `ILIKE` |
+| `escapeHtml(value)` | Escapes `& < > " '`; accepts numbers, `null` and `undefined` (empty string) |
+| `isHttpUrl(value)` / `isNonEmptyString(value)` | Absolute `http:` / `https:` URL; string with a non-whitespace character (both type guards) |
+| `chunk(items, size)` / `sleep(ms)` | Slices of at most `size` (positive integer, else `INVALID_DATA`) / promise resolved after `ms` |
+| `asRecord(value)` / `asRecordOrNull(value)` | Plain object (arrays excluded), else `{}` / `null` |
+| `asText(value)` | Trimmed string, `null` for blank or non-string |
+| `asArray(value)` | The array, else `[]` |
+| `asOptionalString(value, { allowBlank? })` | The string as is (not trimmed), `null` for non-strings and, unless `allowBlank`, blank strings |
+| `asFiniteNumber(value)` | The number if finite, else `null` (no parsing) |
+
+Admin code never imports from `/lib`; it uses `/admin-components`.
+
+The main entry (`@hartl-services/medusa-base`) additionally exports, next to
+`requirePluginFeature`:
+
+| Export | Purpose |
+| --- | --- |
+| `pluginFeatureGate(descriptor)` | Returns `gate(matcher, ...featureKeys)`, a `defineMiddlewares` route entry (no `methods`, so a prefix match before authentication) whose middleware is `requirePluginFeature(descriptor, ...featureKeys)` |
+| `isOwnPluginEvent(data, pluginKey)` | `true` when the event payload's `plugin_key` is `pluginKey`; never throws. For subscribers of `plugin-features.updated.v1` and `plugin-settings.updated.v1` |
+| `isBasePluginRegistered(container)` / `resolveBaseModule(container)` | Whether the base module is registered (boot-time check) / its service, or `UNEXPECTED_STATE` |
+
+`/admin-components` is built (after `medusa plugin:build`) into
+`.medusa/server/src/admin/admin-components`, not into `dist`: the host Admin's
+Tailwind scans only `.medusa/server/src/admin/**` of a plugin, so the classes of
+the shared components are generated there. Do not move the outDir of
+`tsconfig.admin-components.json`.
+
 ## Semantics
 
 - No stored row: every value is its declared default, `version` is 0.
@@ -665,6 +871,25 @@ Affiliate 100 (`affiliate-validate-complete-cart`,
   instead of silently leaving partial state.
 - The base never swallows a participant error and never reads toggles here.
 
+**Refunded payment.** Before any `validate` participant, the base refuses a
+cart whose payment collection already has a refund (`NOT_ALLOWED`, "Die
+Zahlung für diesen Warenkorb wurde bereits erstattet. Bitte bestelle
+erneut."). With Stripe's `capture: true` a completion failing after the
+confirmation makes Medusa 2.19.0 refund the payment and keep the cart open
+with the captured session (the succeeded PaymentIntent cannot be cancelled);
+completing that cart later would place an order on the refunded payment. A
+storefront replaces such a cart with a fresh one.
+
+**Completion check.** `POST /store/carts/:id/completion-check` (contracts
+`paths/checkout`, `types/checkout-store`) runs the same checks without
+completing: it loads the cart with Medusa's own complete-cart field list,
+refuses a completed or refunded cart and runs every `validate` participant.
+It answers `{ cart_id, ready: true }` or the error the completion would
+answer with, and writes nothing. Stripe captures on confirmation, so a
+Storefront calls it right before confirming a payment. Plugins that guard
+`/store/carts/:id/complete` with a middleware register it for this route too
+(the affiliate plugin's registered-email gate does).
+
 
 ## Sentry logger wrapper
 
@@ -949,7 +1174,7 @@ 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 |
+| (plugin switch)       | E-Mail                 | on      | every route under `/admin/email/*` (mail log, resends, attachments; 404); jobs `email-reconcile-attempts`, `email-reconcile-pending-messages`, `email-retry-messages`; every feature below                            | checkout and orders; already queued messages stay stored |
 | `order_mails`         | Bestell-Mails          | on      | subscribers `order-placed`, `email-shipment-created`, `email-order-canceled`, `return-requested`, `return-received`, `documents-shipment-invoice-assignment-decided`, `documents-order-cancellation-ready`, `documents-refund-ready`; route `/admin/draft-orders/:id/order-confirmation` (404) and its draft-order widget | jobs, Admin routes, already created messages             |
 | `account_mails`       | Konto-Mails            | on      | subscribers `password-reset`, `user-invite`, `customer-verification` (the last one only with `customer_verification` on as well)                                                                                          | jobs, Admin routes, already created messages             |
 | `customer_verification` | Kontobestätigung per E-Mail | off | Medusa's e-mail verification of customer logins (see "Kontobestätigung per E-Mail"), route `POST /store/customer-verification/resend` (404 while off), subscriber `customer-verification`; child of `account_mails` | checkout and orders; confirmed accounts stay confirmed, already created messages |
@@ -962,15 +1187,14 @@ 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`.
+The plugin declares no settings. Its logo and colors come from the
+Shop-Stammdaten (section "Erscheinungsbild").
 
 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.
+and gates the Anhänge card above it, the mail log section below it and the
+Anhänge sub-page on the plugin switch, showing `PluginFeatureDisabledNotice`
+in place of the mail log and the sub-page while it is off.
 
 ### Kontobestätigung per E-Mail
 
@@ -1083,7 +1307,8 @@ Storefront contract (DTOs, schema and path from the Contracts package,
 - Affiliate owns reminder eligibility and publishes reminder and application
   facts.
 - Email resolves recipients, renders content, attaches files, and owns delivery
-  status plus the append-only global Terms PDF history.
+  status plus the attachment library (documents with append-only PDF
+  versions).
 - Public HTTP DTOs, schemas, and paths remain in
   `@hartl-services/medusa-food-supplements-contracts`.
 
@@ -1243,13 +1468,25 @@ has at most 35 characters. Email runtime-validates every contract before use.
 - 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.
+- Library attachments (see "Mail attachments") can be assigned to the customer
+  kinds `order.received`, `order.shipped`, `order.canceled`,
+  `order.return_requested`, `order.return_received` and `order.refunded`
+  (`EMAIL_ATTACHABLE_KINDS`). When a message of such a kind is first created,
+  it snapshots, for every document assigned to its kind, the newest version
+  whose `effective_at` is not later than the reference time: the
+  authoritative `order.created_at` for `order.received`, the creation time of
+  the message otherwise. `order.return_received` is created together with the
+  return request and so freezes the state of that moment. A document without
+  an effective version is skipped. Shop, account and affiliate mails never
+  receive library attachments.
+- A message lists Documents artifacts (invoice, cancellation) first, then its
+  library attachments by document name, whichever correlated fact created it.
+- Attachment 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 or a changed assignment never
+  changes an existing message. A missing or altered library file fails the
+  message terminally (`attachment_unavailable`/`attachment_invalid`); it is
+  never sent without it.
 - 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
@@ -1266,29 +1503,32 @@ has at most 35 characters. Email runtime-validates every contract before use.
 - Password-reset and account-confirmation 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.
+- Shop branding is the configured `displayName` plus the company details and
+  the Erscheinungsbild (logo, colors) 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
+inline styles) and one renderer per accepted kind; the colors of the
+Erscheinungsbild replace the grey tones where set (see "Shop-Stammdaten").
+The layout shows, from top to bottom: the `logo` of the Erscheinungsbild
+centered (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
+Missing master data fields are left out. Email reads the Shop-Stammdaten and
+the Erscheinungsbild when it sends a mail, so a change applies to the next
+mail; if a read fails the mail is sent without that part (company details, or
+logo and colors) 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
+A custom `layout` receives the same data as `shop` (`EmailShopDetails`: the
+master data, `logo` and `colors`, every field optional) next to `bodyHtml`,
+`preheader` and `subject`; a renderer receives it as its second argument. A shop
 therefore needs only `displayName`, `affiliatePortalUrl`, `inviteUrl`,
 `passwordResetUrl` and `orderNotificationEmail`.
 
@@ -1496,12 +1736,44 @@ Email exposes authenticated Admin operations at:
   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.
+- `GET /admin/email/attachments` lists every attachment document by name with
+  its safe version metadata, newest effective version first.
+- `POST /admin/email/attachments` idempotently (per `request_id`) creates a
+  document with a name and its assigned `mail_kinds`; `POST
+  /admin/email/attachments/:id` renames it and, when `mail_kinds` is sent,
+  replaces its assignments (left out = unchanged). An empty `mail_kinds` lets
+  the document rest. Kinds outside `EMAIL_ATTACHABLE_KINDS` answer 400.
+- `POST /admin/email/attachments/:id/mail-kinds` (`{ kind, attached }`)
+  attaches the document to one mail kind or detaches it. The kinds are read
+  and changed under the document's row lock, so two toggles of different
+  kinds both persist; repeating a request is harmless. A kind outside
+  `EMAIL_ATTACHABLE_KINDS` answers 400, an unknown document 404. Answers like
+  the update route (`{ created: false, attachment }`).
+- `POST /admin/email/attachments/:id/versions` idempotently stores one private
+  PDF of at most 5 MiB with its `effective_at` timestamp; replaying a
+  `request_id` with other data or for another document answers 409.
+- `GET /admin/email/attachments/:id/versions/:version_id/download` streams one
+  authenticated, non-cacheable PDF download (404 when the version does not
+  belong to the document).
+- `GET /admin/email/templates` lists the editable mails
+  (`EMAIL_EDITABLE_KINDS`) with `customized` (a template is stored) and
+  `code_override` (the shop's code configuration overrides the kind).
+  `GET /admin/email/templates/:kind` returns the stored template or the
+  default one, `POST` stores one (`{ subject, document }`, validated against
+  `EmailTemplateDocumentSchema` and the kind's `EMAIL_TEMPLATE_CATALOG`, at
+  most 256 KiB; 400 otherwise) and `DELETE` goes back to the default. `POST
+  /admin/email/templates/:kind/preview` renders `{ subject, document }` with
+  sample data in the current layout and appearance (`{ subject, html, text }`;
+  not allowed while e-mail is not configured). Other kinds answer 404. `POST
+  /admin/email/templates/:kind/send-test` (`{ subject, document, to,
+  order_display_id?, source_id?, include_attachments? }`) renders the same
+  preview, with sample data or the data of a real order, and sends it to
+  `to` (`{ sent: true, to, subject, attachments }`, `attachments` = number of
+  attached files). `GET
+  /admin/email/templates/:kind/test-sources?order_display_id=N` lists the
+  shipments, returns or refunds of that order a test of the mail can use
+  (`{ sources: [{ id, occurred_at, amount, currency_code, latest }] }`);
+  see "Testmail" under "Mail templates".
 - `GET /admin/draft-orders/:id/order-confirmation` returns
   `AdminDraftOrderConfirmationResponse` (`{ draft_order_id,
   send_order_confirmation }`); `POST` with
@@ -1512,8 +1784,9 @@ 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.
+Attachment responses expose name, assigned kinds and, per version, 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.
@@ -1529,10 +1802,12 @@ 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
+`@hartl-services/medusa-base/admin-components` (the toggles above). Above
+them sits the **Anhänge** card (documents and the mails they are assigned to,
+"Bearbeiten" opens the sub-page) and the **Vorlagen** card (the editable
+mails with "Standard"/"angepasst", "Bearbeiten" opens the template editor,
+see "Mail templates"); below them, as the last section, the
+**E-Mail-Protokoll**. The mail
 log provides bounded server pagination, allowlisted status/kind filters, a
 search by the exact resource ID (e.g. `order_…`, `cus_…`, as pasted from
 elsewhere), safe message and attempt status, and an explicitly confirmed
@@ -1545,11 +1820,123 @@ switch "An Kunden senden" starts off and decides whether the customer receives
 the order confirmation when the draft is converted (see "Draft orders and
 0 € orders").
 
-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.
+The sub-page `/settings/hartl-services/email/attachments` manages the
+attachment library: "Neuer Anhang" creates a document (name, assigned mails,
+first PDF with its effective date), each document can be renamed and
+reassigned ("Bearbeiten") and gets further versions ("Neue Version"; PDF of
+at most 5 MiB). Versions are listed newest effective first, marked
+"aktuell" or "geplant", and can be downloaded. Every create and upload sends
+a fresh request UUID; downloads use the configured authenticated Admin SDK
+and never expose storage file IDs or URLs in the UI. There is no delete:
+removing every assigned mail lets a document rest.
+
+### Mail templates
+
+All twelve mails (`EMAIL_EDITABLE_KINDS`) are block templates an Admin edits
+on the E-Mail page (card **Vorlagen**, grouped into Bestell-, Konto- and
+Affiliate-Mails → editor page `/settings/hartl-services/email/templates/:kind`).
+The editor offers a toolbar, slash commands ("/" lists what the mail
+allows), a drag handle to move top-level blocks, a live preview, a test mail
+and, for the six customer order mails, the attachment checkboxes of the
+mail (`POST /admin/email/attachments/:id/mail-kinds`, one kind at a time;
+the Anhänge page's edit dialog likewise saves the name only when it changed
+and then each changed mail kind on its own).
+
+- **Document:** a subset of the editor's ProseMirror JSON
+  (`EmailTemplateDocumentSchema` in Contracts): paragraphs with bold, italic,
+  http(s)/mailto links and line breaks, bullet lists, placeholders, a
+  **Hinweis** box (`notice`), a **Nur wenn …** section (`conditional`) and
+  the dynamic blocks of the kind (`EMAIL_TEMPLATE_CATALOG`): `details`
+  (Eckdaten), `order_summary` (items and totals, optional heading),
+  `item_list` (items without prices, optional heading), `address`,
+  `tracking`, `button` (the mail's action link: target fixed per kind from
+  the data or the configuration, label editable; nothing without a URL),
+  `link_fallback` (the plain link, HTML only), `validity` and `message` (the
+  partner application's text). Dynamic blocks render the mail's real data at
+  send time and render nothing without it. Conditions: `invoice_attached`,
+  `cancellation_attached`, `more_to_follow`, `return_number`. Password reset,
+  account confirmation and admin invite must contain the `button` block
+  (`required_blocks`); a template without it is rejected.
+- **Placeholders** (`shop_name`, `order_number`, `customer_name`,
+  `return_number`, `refund_amount`, `affiliate_name`, `report_month`,
+  `applicant_name`, per kind as in the catalog) are escaped in
+  the HTML and raw in subject and text; a missing value is empty. A custom
+  subject writes them as `{{key}}`; blank subject = the default subject.
+- **Defaults:** without a stored template a mail renders its default
+  document, which produces exactly the former code output. Messages stored
+  before order snapshots existed keep their code fallback. Password reset,
+  account confirmation and invite read the stored template in their own
+  handlers, the other mails at dispatch.
+- **When it applies:** templates are read at send time, so a saved template
+  also applies to queued, retried and resent mails; attachments are fixed
+  when the mail is created. An invalid stored template or a failed read sends
+  the default (logged as a warning); a template never fails a mail.
+- **Precedence:** a shop's code `renderers[kind]` > Admin template > default.
+  The editor shows when a code override is active.
+- Stored in `email_template` (one row per kind, upsert on save).
+- **Testmail:** the editor sends the current draft to one address
+  (`POST /admin/email/templates/:kind/send-test`). The subject starts with
+  `[Test] `. The mail goes straight through the Notification module: it is
+  not recorded as an email message, is neither retried nor deduplicated, never
+  goes to the customer, and can be sent again freely. A rejected address, an
+  unreachable mail server or an unclear outcome answers a German message
+  without the provider's own text; while e-mail is not configured the route
+  answers 400 (`not_allowed`).
+  - **Data:** sample data by default. For the seven order mails,
+    `order_display_id` (the order number, e.g. `14`) renders the data of that
+    real, non-draft order instead, so the mail contains real customer data:
+    the order itself (confirmation, shop notification; cancellation only for
+    a canceled order), or one of its shipments (shipped, not canceled),
+    returns (not canceled), received returns (status `received`) or refunds
+    (over all payments). In the editor's dialog the order field searches by
+    number, e-mail or name and offers up to eight orders.
+  - **Source:** `GET …/test-sources?order_display_id=N` lists the candidates
+    of shipping, return and refund mails with the same filters, newest first
+    (by `shipped_at`, `created_at`, `received_at` or the refund's
+    `created_at`; refunds with `amount` and `currency_code`, otherwise
+    `null`); `latest` marks the default. Other mails list none (`[]`), an
+    unknown order answers 404. `send-test` takes the chosen `source_id`;
+    without it the newest is used. `source_id` without `order_display_id`,
+    for a mail without candidates („Diese Mail hat keine Vorgänge zur
+    Auswahl.“) or not among the order's candidates („Dieser Vorgang gehört
+    nicht zu Bestellung #14 oder passt nicht zu dieser Mail.“) answers 400.
+    An unknown order answers 404, a missing event 400 (e.g. „Bestellung #14
+    hat keinen Versand.“), an order number for an account or affiliate mail
+    400. The Notification of such a test carries `resource_type: "order"`,
+    the order id and `data: { admin_id }`; otherwise
+    `resource_type: "email_template"`.
+  - **Attachments:** `include_attachments` (default `true`) attaches the
+    library documents currently assigned to the mail, each in the version
+    effective at the cut-off date: the order's placing for the order
+    confirmation with a real order (like the real mail), otherwise now. It is
+    ignored for mails that cannot carry attachments.
+  - **Receipts from the real mail:** with a real order and
+    `include_attachments`, a shipping, cancellation or refund test carries
+    exactly the receipts (invoice, cancellation document) the real mail of
+    that shipment, cancellation or refund carried — found by its business
+    key (`order-shipped:<fulfillment>`, `order-canceled:<order>`,
+    `refund:<refund>`), its non-library attachments in their originally sent
+    version — and sets `invoice_attached` / `cancellation_attached` as that
+    mail had it, so its receipt hint shows. Without a real mail (e.g. the
+    refund of a canceled order, whose receipt went with the cancellation, or
+    receipts were switched off then) there is no receipt and no hint, as for
+    the customer; the current Documents switches play no role. With
+    `include_attachments: false` neither receipts, library documents nor the
+    hint are sent. Receipts come first, then library documents; `attachments`
+    counts both. A missing or changed file answers 400 („Anhang „X“ fehlt
+    bzw. ist beschädigt.“), any other read failure „Anhang „X“ konnte
+    gerade nicht geladen werden.“
+
+### Mail attachments
+
+The global Terms PDFs (`AGB`), the EU legal-guarantee notice or a flyer are
+documents of the attachment library. A document has a name, the customer
+mail kinds it is attached to and immutable PDF versions, each valid from its
+`effective_at`. Which version a mail carries is decided once, when the mail
+is created (see the rules above). Migration `Migration20261009083539` turned
+the former Terms PDF versions into the document `AGB` (id `eatd_terms`,
+assigned to `order.received`, version ids kept) and rewrote every stored
+message snapshot accordingly; it cannot be reverted.
 
 Admin consumers import wire DTOs and paths only from the Contracts package and
 reuse their configured Medusa SDK:
@@ -1750,16 +2137,21 @@ 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
+Settings under Settings → "Hartl Services Plugins" → **Dokumente** and the
+Erscheinungsbild of the Shop-Stammdaten, 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.
+- **Logo** (the `logo` of the Shop-Stammdaten, section "Erscheinungsbild"):
+  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.
+- **Colors** (the colors of the Erscheinungsbild, `settings.colors`): the set
+  ones override `--accent`, `--text`, `--muted`, `--line` and `--table-head`
+  in a `:root` block after the default stylesheet and before the shop
+  theme's stylesheet, so a shop theme still wins.
 - **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.