@hartl-services/medusa-base 1.0.0 → 2.0.0

package/README.md

@@ -68,7 +68,7 @@ plugins: [
       // 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 },
+      // documents: { numbering, pdf, htmlFactory },
       // files: { gateway },
     },
   },
@@ -83,7 +83,7 @@ every module of the plugin; each module reads only its own namespace:
 |---|---|---|
 | `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`. |
+| `documents` | `documents` module | `{ 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,
@@ -318,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
@@ -477,15 +480,13 @@ settings like any plugin's:
 | `iban`, `bic` | string | no |
 | `company_register_number` (Firmenbuchnummer), `company_register_court` (Firmenbuchgericht) | string | no |
 
-Server-side code reads them with a plugin's own medusa-config values as
-fallback (stored in the Admin wins per key):
+Server-side code reads them exactly as stored in the Admin; there is no
+medusa-config fallback:
 
 ```ts
 import { getShopMasterData } from "@hartl-services/medusa-base"
 
-const { values, configured, missing } = await getShopMasterData(container, {
-  legal_name: options.merchant?.legalName,
-})
+const { values, configured, missing } = await getShopMasterData(container)
 if (!configured) {
   throw new MedusaError(
     MedusaError.Types.UNEXPECTED_STATE,
@@ -891,6 +892,10 @@ 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
@@ -1060,20 +1065,130 @@ has at most 35 characters. Email runtime-validates every contract before use.
 - Password-reset messages cannot be retried by the generic retry job or resent
   by an Admin.
 - Unknown transport outcomes are never automatically resent.
-- Shop branding is only the configured `displayName`; a shop overrides the
-  default layout or single renderers in its own configuration, not in the
-  plugin.
+- 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 and one renderer per accepted kind.
-Both show the shop only as the configured `displayName` (escaped in HTML; the
-layout header and footer, the password-reset and invite subjects). A shop
+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.
@@ -1344,12 +1459,7 @@ export default defineConfig({
     },
     {
       resolve: "@hartl-services/medusa-tax-compliance",
-      options: {
-        merchant: {
-          countryCode: process.env.MERCHANT_COUNTRY_CODE!,
-          vatNumber: process.env.MERCHANT_VAT_NUMBER!,
-        },
-      },
+      options: {},
     },
   ],
 });
@@ -1370,10 +1480,9 @@ Options of the `documents` namespace (all optional; `{}` is valid):
   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 sender (company, address, UID, contact, bank) is not an option: it comes
+only from the Shop-Stammdaten (see "Merchant data" below).
 
 The `documents` module is always registered with the base (no `documentsEnabled`
 switch); the Admin switches it off at run time through the feature toggles
@@ -1384,8 +1493,9 @@ below. `medusa db:migrate` creates its tables.
 `@hartl-services/medusa-base/config` exports, next to the environment helpers,
 build-time values for `medusa-config.ts` and tests:
 
-- `createDefaultDocumentHtmlFactory({ timeZone })` — the built-in factory, to
-  use as it is or to wrap (for example to add a header to the default HTML).
+- `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.
@@ -1393,6 +1503,44 @@ build-time values for `medusa-config.ts` and tests:
 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
@@ -1401,8 +1549,8 @@ 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.
+`company_register_court`; unset optional fields are `null`). There is no
+medusa-config fallback: what is stored in the Admin is what is printed.
 
 - `merchant` is not part of the stored snapshot: a regenerated document
   prints the master data current at regeneration time.
@@ -1482,8 +1630,8 @@ 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
+"Shop-Config-Preset"): `documents.numbering.timeZone` is its `timeZone`
+option, `documents.htmlFactory` its optional `documentHtmlFactory` 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
@@ -2151,17 +2299,6 @@ pnpm add @hartl-services/medusa-base \
 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",
@@ -2202,11 +2339,11 @@ validate the environment; a missing variable fails with the variable's name.
 
 | 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. |
+| `displayName` | Shop name in the default e-mail templates (a shop's initial seed may use it as store name). Company name, address and UID are no options: documents and tax compliance read them only from the Shop-Stammdaten (Admin, "Hartl Services Plugins"). |
 | `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

package/dist/admin-components/features/plugin-features/components/ImageSettingInput.d.ts

@@ -0,0 +1,15 @@
+type ImageSettingInputProps = {
+    id: string;
+    hintId: string;
+    label: string;
+    /** Public URL of the current image; `""` = none. */
+    value: string;
+    disabled: boolean;
+    onChange: (url: string) => void;
+};
+/**
+ * Uploads an image to the public File Module storage and hands its URL to
+ * the settings draft; the form stores it on save like any other value.
+ */
+export declare const ImageSettingInput: ({ id, hintId, label, value, disabled, onChange, }: ImageSettingInputProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/admin-components/features/plugin-features/components/ImageSettingInput.js

@@ -0,0 +1,42 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button, Hint, Text } from "@medusajs/ui";
+import { useMutation } from "@tanstack/react-query";
+import { useRef, useState } from "react";
+import { texts } from "../../../i18n/texts";
+import { sdk } from "../../../lib/sdk";
+import { validateSettingImage } from "../lib/image-upload";
+/**
+ * Uploads an image to the public File Module storage and hands its URL to
+ * the settings draft; the form stores it on save like any other value.
+ */
+export const ImageSettingInput = ({ id, hintId, label, value, disabled, onChange, }) => {
+    const fileInput = useRef(null);
+    const [error, setError] = useState(null);
+    const upload = useMutation({
+        mutationFn: async (file) => {
+            const { files } = await sdk.admin.upload.create({ files: [file] });
+            const url = files[0]?.url;
+            if (!url) {
+                throw new Error("upload returned no file");
+            }
+            return url;
+        },
+        onSuccess: (url) => onChange(url),
+        onError: () => setError(texts.settings.imageUploadFailed),
+    });
+    const busy = disabled || upload.isPending;
+    const selectFile = (file) => {
+        if (!file) {
+            return;
+        }
+        const invalid = validateSettingImage(file);
+        setError(invalid);
+        if (!invalid) {
+            upload.mutate(file);
+        }
+    };
+    return (_jsxs("div", { className: "grid gap-2", children: [value && (_jsx("div", { className: "bg-ui-bg-subtle flex items-center justify-center rounded-md border p-4", children: _jsx("img", { src: value, alt: texts.settings.imagePreviewAlt(label), className: "max-h-24 max-w-full object-contain" }) })), _jsx("input", { ref: fileInput, id: id, "aria-describedby": hintId, type: "file", accept: "image/png,image/jpeg", className: "hidden", onChange: (event) => {
+                    selectFile(event.target.files?.[0]);
+                    event.target.value = "";
+                } }), _jsxs("div", { className: "flex items-center gap-2", children: [_jsx(Button, { type: "button", size: "small", variant: "secondary", isLoading: upload.isPending, disabled: busy, onClick: () => fileInput.current?.click(), children: value ? texts.settings.imageReplace : texts.settings.imageUpload }), value && (_jsx(Button, { type: "button", size: "small", variant: "transparent", disabled: busy, onClick: () => onChange(""), children: texts.settings.imageRemove })), !value && (_jsx(Text, { size: "small", className: "text-ui-fg-muted", children: texts.settings.imageNone }))] }), error && _jsx(Hint, { variant: "error", children: error })] }));
+};

package/dist/admin-components/features/plugin-features/components/PluginSettingsForm.js

@@ -2,6 +2,7 @@ import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
 import { Alert, Button, Container, Heading, Hint, Input, Label, Select, Switch, Text, } from "@medusajs/ui";
 import { texts } from "../../../i18n/texts";
 import { usePluginSettingsForm } from "../hooks/usePluginSettingsForm";
+import { ImageSettingInput } from "./ImageSettingInput";
 const fieldId = (pluginKey, key) => `plugin-setting-${pluginKey}-${key}`;
 export const missingLabels = (plugin) => plugin.missing
     .map((key) => plugin.settings.find((setting) => setting.key === key)?.label ?? key)
@@ -27,13 +28,14 @@ const SettingField = ({ pluginKey, setting, invalidatesLabels, value, invalid, d
                             ? texts.settings.secretClearUndoLabel(setting.label)
                             : texts.settings.secretClearLabel(setting.label), onClick: () => onChange(clearPending ? "" : null), children: clearPending
                             ? texts.settings.secretClearUndo
-                            : texts.settings.secretClear }))] })) : setting.type === "select" ? (_jsxs(Select, { value: typeof value === "string" ? value : "", disabled: disabled, onValueChange: (next) => onChange(next), children: [_jsx(Select.Trigger, { id: id, "aria-describedby": hintId, children: _jsx(Select.Value, { placeholder: texts.settings.selectPlaceholder }) }), _jsx(Select.Content, { children: setting.options.map((option) => (_jsx(Select.Item, { value: option.value, children: option.label }, option.value))) })] })) : setting.type === "number" ? (_jsx(Input, { id: id, "aria-describedby": hintId, "aria-invalid": invalid, type: "number", step: "any", min: setting.min ?? undefined, max: setting.max ?? undefined, value: typeof value === "string" ? value : "", disabled: disabled, onChange: (event) => onChange(event.target.value, event.target.validity.badInput) })) : (_jsx(Input, { id: id, "aria-describedby": hintId, "aria-invalid": invalid, type: setting.type === "url" ? "url" : "text", value: typeof value === "string" ? value : "", disabled: disabled, onChange: (event) => onChange(event.target.value) })), _jsxs("div", { id: hintId, className: "grid gap-1", children: [setting.description && (_jsx(Text, { size: "small", className: "text-ui-fg-subtle", children: setting.description })), clearPending && (_jsx(Hint, { variant: "info", children: texts.settings.secretClearPending })), invalidatesLabels && (_jsx(Text, { size: "small", className: "text-ui-fg-muted", children: texts.settings.invalidates(invalidatesLabels) })), bounds && !invalid && (_jsx(Text, { size: "small", className: "text-ui-fg-muted", children: bounds })), invalid && (_jsx(Hint, { variant: "error", children: bounds ?? texts.settings.invalidNumber }))] })] }));
+                            : texts.settings.secretClear }))] })) : setting.type === "select" ? (_jsxs(Select, { value: typeof value === "string" ? value : "", disabled: disabled, onValueChange: (next) => onChange(next), children: [_jsx(Select.Trigger, { id: id, "aria-describedby": hintId, children: _jsx(Select.Value, { placeholder: texts.settings.selectPlaceholder }) }), _jsx(Select.Content, { children: setting.options.map((option) => (_jsx(Select.Item, { value: option.value, children: option.label }, option.value))) })] })) : setting.type === "image" ? (_jsx(ImageSettingInput, { id: id, hintId: hintId, label: setting.label, value: typeof value === "string" ? value : "", disabled: disabled, onChange: (url) => onChange(url) })) : setting.type === "number" ? (_jsx(Input, { id: id, "aria-describedby": hintId, "aria-invalid": invalid, type: "number", step: "any", min: setting.min ?? undefined, max: setting.max ?? undefined, value: typeof value === "string" ? value : "", disabled: disabled, onChange: (event) => onChange(event.target.value, event.target.validity.badInput) })) : (_jsx(Input, { id: id, "aria-describedby": hintId, "aria-invalid": invalid, type: setting.type === "url" ? "url" : "text", value: typeof value === "string" ? value : "", disabled: disabled, onChange: (event) => onChange(event.target.value) })), _jsxs("div", { id: hintId, className: "grid gap-1", children: [setting.description && (_jsx(Text, { size: "small", className: "text-ui-fg-subtle", children: setting.description })), clearPending && (_jsx(Hint, { variant: "info", children: texts.settings.secretClearPending })), invalidatesLabels && (_jsx(Text, { size: "small", className: "text-ui-fg-muted", children: texts.settings.invalidates(invalidatesLabels) })), bounds && !invalid && (_jsx(Text, { size: "small", className: "text-ui-fg-muted", children: bounds })), invalid && (_jsx(Hint, { variant: "error", children: bounds ?? texts.settings.invalidNumber }))] })] }));
 };
 export const PluginSettingsForm = ({ plugin }) => {
     const form = usePluginSettingsForm(plugin);
     const pending = form.mutation.isPending;
     const hasTextFields = plugin.settings.some((setting) => setting.type !== "boolean" &&
         setting.type !== "secret" &&
-        setting.type !== "select");
+        setting.type !== "select" &&
+        setting.type !== "image");
     return (_jsxs(Container, { className: "divide-y p-0", "aria-busy": pending, children: [_jsxs("div", { className: "px-6 py-4", children: [_jsx(Heading, { level: "h2", children: texts.sections.settings }), hasTextFields && (_jsx(Text, { size: "small", className: "text-ui-fg-subtle", children: texts.settings.clearHint }))] }), _jsxs("form", { onSubmit: form.submit, className: "grid gap-5 px-6 py-5", children: [!plugin.configured && (_jsx(Alert, { variant: "warning", children: texts.settings.missing(missingLabels(plugin)) })), plugin.settings.map((setting) => (_jsx(SettingField, { pluginKey: plugin.plugin_key, setting: setting, invalidatesLabels: invalidatesLabels(plugin, setting), value: form.draft[setting.key], invalid: form.invalid.includes(setting.key), disabled: pending, onChange: (value, badInput) => form.setValue(setting.key, value, badInput) }, setting.key))), _jsx("div", { className: "flex justify-end", children: _jsx(Button, { type: "submit", size: "small", isLoading: pending, disabled: !form.dirty || form.invalid.length > 0 || pending, children: texts.settings.save }) })] })] }));
 };

package/dist/admin-components/features/plugin-features/hooks/usePluginFeatureEnabled.d.ts

@@ -74,7 +74,7 @@ export declare const pluginFeatureEnabledQueryOptions: (pluginKey: string, featu
                 source: "default" | "stored" | "config" | "none";
                 invalidates: string[];
             } | {
-                type: "string" | "boolean" | "url";
+                type: "string" | "boolean" | "url" | "image";
                 default: string | number | boolean | null;
                 value: string | number | boolean | null;
                 key: string;

package/dist/admin-components/features/plugin-features/hooks/usePluginFeatures.d.ts

@@ -54,7 +54,7 @@ export declare function usePluginFeatures(): import("@tanstack/react-query").Use
             source: "default" | "stored" | "config" | "none";
             invalidates: string[];
         } | {
-            type: "string" | "boolean" | "url";
+            type: "string" | "boolean" | "url" | "image";
             default: string | number | boolean | null;
             value: string | number | boolean | null;
             key: string;
@@ -141,7 +141,7 @@ export declare function usePluginFeature(pluginKey: string | undefined): import(
             source: "default" | "stored" | "config" | "none";
             invalidates: string[];
         } | {
-            type: "string" | "boolean" | "url";
+            type: "string" | "boolean" | "url" | "image";
             default: string | number | boolean | null;
             value: string | number | boolean | null;
             key: string;
@@ -222,7 +222,7 @@ export declare function useUpdatePluginFeatures(): import("@tanstack/react-query
             source: "default" | "stored" | "config" | "none";
             invalidates: string[];
         } | {
-            type: "string" | "boolean" | "url";
+            type: "string" | "boolean" | "url" | "image";
             default: string | number | boolean | null;
             value: string | number | boolean | null;
             key: string;
@@ -307,7 +307,7 @@ export declare function useUpdatePluginSettings(pluginKey: string): import("@tan
             source: "default" | "stored" | "config" | "none";
             invalidates: string[];
         } | {
-            type: "string" | "boolean" | "url";
+            type: "string" | "boolean" | "url" | "image";
             default: string | number | boolean | null;
             value: string | number | boolean | null;
             key: string;

package/dist/admin-components/features/plugin-features/hooks/usePluginSettingsForm.d.ts

@@ -63,7 +63,7 @@ export declare function usePluginSettingsForm(plugin: AdminPluginFeatures): {
                 source: "default" | "stored" | "config" | "none";
                 invalidates: string[];
             } | {
-                type: "string" | "boolean" | "url";
+                type: "string" | "boolean" | "url" | "image";
                 default: string | number | boolean | null;
                 value: string | number | boolean | null;
                 key: string;

package/dist/admin-components/features/plugin-features/lib/image-upload.d.ts

@@ -0,0 +1,6 @@
+/** Largest image an `image` setting accepts in the Admin. */
+export declare const SETTING_IMAGE_MAX_BYTES: number;
+type ImageSelection = Pick<File, "size" | "type">;
+/** Why `file` cannot be uploaded for an `image` setting; `null` = valid. */
+export declare const validateSettingImage: (file: ImageSelection) => string | null;
+export {};

package/dist/admin-components/features/plugin-features/lib/image-upload.js

@@ -0,0 +1,17 @@
+/** Largest image an `image` setting accepts in the Admin. */
+export const SETTING_IMAGE_MAX_BYTES = 2 * 1024 * 1024;
+// Gmail and Outlook do not display SVG or WebP in e-mails.
+const IMAGE_TYPES = new Set(["image/png", "image/jpeg"]);
+/** Why `file` cannot be uploaded for an `image` setting; `null` = valid. */
+export const validateSettingImage = (file) => {
+    if (!IMAGE_TYPES.has(file.type)) {
+        return "Bitte eine PNG- oder JPG-Datei auswählen.";
+    }
+    if (file.size === 0) {
+        return "Die Bilddatei ist leer.";
+    }
+    if (file.size > SETTING_IMAGE_MAX_BYTES) {
+        return "Die Bilddatei darf maximal 2 MiB groß sein.";
+    }
+    return null;
+};

package/dist/admin-components/features/plugin-features/lib/plugin-features-admin-client.d.ts

@@ -55,7 +55,7 @@ export declare const listPluginFeatures: () => Promise<{
             source: "default" | "stored" | "config" | "none";
             invalidates: string[];
         } | {
-            type: "string" | "boolean" | "url";
+            type: "string" | "boolean" | "url" | "image";
             default: string | number | boolean | null;
             value: string | number | boolean | null;
             key: string;
@@ -135,7 +135,7 @@ export declare const retrievePluginFeatures: (pluginKey: string) => Promise<{
             source: "default" | "stored" | "config" | "none";
             invalidates: string[];
         } | {
-            type: "string" | "boolean" | "url";
+            type: "string" | "boolean" | "url" | "image";
             default: string | number | boolean | null;
             value: string | number | boolean | null;
             key: string;
@@ -215,7 +215,7 @@ export declare const updatePluginFeatures: (payload: UpdatePluginFeaturesPayload
             source: "default" | "stored" | "config" | "none";
             invalidates: string[];
         } | {
-            type: "string" | "boolean" | "url";
+            type: "string" | "boolean" | "url" | "image";
             default: string | number | boolean | null;
             value: string | number | boolean | null;
             key: string;
@@ -295,7 +295,7 @@ export declare const updatePluginSettings: (pluginKey: string, payload: UpdatePl
             source: "default" | "stored" | "config" | "none";
             invalidates: string[];
         } | {
-            type: "string" | "boolean" | "url";
+            type: "string" | "boolean" | "url" | "image";
             default: string | number | boolean | null;
             value: string | number | boolean | null;
             key: string;

package/dist/admin-components/i18n/texts.d.ts

@@ -59,6 +59,12 @@ export declare const texts: {
         numberMax: (max: number) => string;
         numberRange: (min: number, max: number) => string;
         selectPlaceholder: string;
+        imageUpload: string;
+        imageReplace: string;
+        imageRemove: string;
+        imageNone: string;
+        imageUploadFailed: string;
+        imagePreviewAlt: (label: string) => string;
         clearHint: string;
         source: {
             stored: string;

package/dist/admin-components/i18n/texts.js

@@ -59,6 +59,12 @@ export const texts = {
         numberMax: (max) => `Höchstens ${max}.`,
         numberRange: (min, max) => `Zwischen ${min} und ${max}.`,
         selectPlaceholder: "Bitte auswählen",
+        imageUpload: "Bild hochladen",
+        imageReplace: "Anderes Bild hochladen",
+        imageRemove: "Entfernen",
+        imageNone: "Kein Bild hinterlegt",
+        imageUploadFailed: "Das Bild konnte nicht hochgeladen werden.",
+        imagePreviewAlt: (label) => `Vorschau ${label}`,
         clearHint: "Ein leeres Feld speichern entfernt den gespeicherten Wert (dann gilt Konfiguration oder Standard).",
         source: {
             stored: "gespeichert",

package/dist/documents/templates/financial-document.d.ts

@@ -1,3 +1,3 @@
-import type { DocumentTemplateInput } from "../types";
-import type { DocumentLayout } from "./layout";
-export declare const renderFinancialDocument: (input: DocumentTemplateInput, layout: DocumentLayout, timeZone: string) => string;
+import type { FinancialDocumentRenderInput } from "../types";
+import { type DocumentLayout } from "./layout";
+export declare const renderFinancialDocument: (input: FinancialDocumentRenderInput, layout: DocumentLayout, timeZone: string) => string;