@hartl-services/medusa-base 0.4.0 → 1.0.0

package/dist/files/config/index.js

@@ -0,0 +1,255 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveExpirationStrategy = exports.resolveS3Credentials = exports.S3_BUILD_PLACEHOLDERS = exports.createS3CacheStorageConfig = exports.createS3CacheFileModuleConfig = exports.validateS3CacheProviderOptions = void 0;
+const PACKAGE_NAME = "medusa-s3-cache-storage";
+const DEFAULT_CACHE = {
+    cleanupIntervalMs: 900_000,
+    dir: "./.medusa-s3-cache",
+    expirationStrategy: "absolute",
+    ttlMs: 3_600_000,
+};
+const DEFAULT_PRIVATE_DOWNLOAD_DURATION_SECONDS = 3_600;
+const invalid = (message) => {
+    throw new TypeError(`${PACKAGE_NAME}: ${message}`);
+};
+const requireNonBlankString = (value, field) => {
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        if (trimmed) {
+            return trimmed;
+        }
+    }
+    return invalid(`${field} must be a non-blank string`);
+};
+const validateHttpUrl = (value, field) => {
+    const url = requireNonBlankString(value, field);
+    try {
+        const parsed = new URL(url);
+        if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+            invalid(`${field} must be an HTTP(S) URL`);
+        }
+        if (parsed.username || parsed.password || parsed.search || parsed.hash) {
+            invalid(`${field} must not include credentials, a query, or a fragment`);
+        }
+        return parsed.toString().replace(/\/$/u, "");
+    }
+    catch (error) {
+        if (error instanceof TypeError && error.message.startsWith(PACKAGE_NAME)) {
+            throw error;
+        }
+        return invalid(`${field} must be an HTTP(S) URL`);
+    }
+};
+const validateSafePrefix = (value, field) => {
+    if (value === undefined) {
+        return "";
+    }
+    const prefix = requireNonBlankString(value, field).replaceAll("\\", "/");
+    const segments = prefix.split("/");
+    if (segments.some((segment) => !segment ||
+        segment === "." ||
+        segment === ".." ||
+        /[\u0000-\u001F\u007F]/u.test(segment))) {
+        invalid(`${field} must contain only safe path segments`);
+    }
+    return segments.join("/");
+};
+const validateFiniteNumber = (value, field, minimum, maximum, defaultValue) => {
+    if (value === undefined) {
+        return defaultValue;
+    }
+    if (typeof value !== "number") {
+        return invalid(`${field} must be an integer from ${minimum} through ${maximum}`);
+    }
+    if (!Number.isFinite(value) ||
+        !Number.isInteger(value) ||
+        value < minimum ||
+        value > maximum) {
+        return invalid(`${field} must be an integer from ${minimum} through ${maximum}`);
+    }
+    return value;
+};
+const validateCacheOptions = (cache) => {
+    const expirationStrategy = cache?.expirationStrategy ?? DEFAULT_CACHE.expirationStrategy;
+    if (expirationStrategy !== "absolute" && expirationStrategy !== "sliding") {
+        invalid("cache.expirationStrategy must be 'absolute' or 'sliding'");
+    }
+    return {
+        cleanupIntervalMs: validateFiniteNumber(cache?.cleanupIntervalMs, "cache.cleanupIntervalMs", 1, 86_400_000, DEFAULT_CACHE.cleanupIntervalMs),
+        dir: cache?.dir
+            ? requireNonBlankString(cache.dir, "cache.dir")
+            : DEFAULT_CACHE.dir,
+        expirationStrategy,
+        ttlMs: validateFiniteNumber(cache?.ttlMs, "cache.ttlMs", 0, 604_800_000, DEFAULT_CACHE.ttlMs),
+    };
+};
+const validateCredentials = (credentials) => {
+    if (!credentials) {
+        return undefined;
+    }
+    const accessKeyId = credentials.accessKeyId;
+    const secretAccessKey = credentials.secretAccessKey;
+    if (!accessKeyId && !secretAccessKey && !credentials.sessionToken) {
+        invalid("s3.credentials must contain accessKeyId and secretAccessKey");
+    }
+    return {
+        accessKeyId: requireNonBlankString(accessKeyId, "s3.credentials.accessKeyId"),
+        secretAccessKey: requireNonBlankString(secretAccessKey, "s3.credentials.secretAccessKey"),
+        ...(credentials.sessionToken
+            ? {
+                sessionToken: requireNonBlankString(credentials.sessionToken, "s3.credentials.sessionToken"),
+            }
+            : {}),
+    };
+};
+const validateGatewayOptions = (gateway) => {
+    if (!gateway) {
+        return invalid("gateway options are required when enabled is true");
+    }
+    return {
+        baseUrl: validateHttpUrl(gateway.baseUrl, "gateway.baseUrl"),
+        privateDownloadDurationSeconds: validateFiniteNumber(gateway.privateDownloadDurationSeconds, "gateway.privateDownloadDurationSeconds", 1, 604_800, DEFAULT_PRIVATE_DOWNLOAD_DURATION_SECONDS),
+        signingSecret: requireNonBlankString(gateway.signingSecret, "gateway.signingSecret"),
+    };
+};
+const validateS3CacheProviderOptions = (input) => {
+    const s3 = input.s3;
+    if (!s3) {
+        return invalid("s3 options are required when enabled is true");
+    }
+    if (s3.forcePathStyle !== undefined &&
+        typeof s3.forcePathStyle !== "boolean") {
+        invalid("s3.forcePathStyle must be a boolean");
+    }
+    if (s3.endpoint !== undefined) {
+        validateHttpUrl(s3.endpoint, "s3.endpoint");
+    }
+    return {
+        cache: validateCacheOptions(input.cache),
+        gateway: validateGatewayOptions(input.gateway),
+        s3: {
+            bucket: requireNonBlankString(s3.bucket, "s3.bucket"),
+            credentials: validateCredentials(s3.credentials),
+            endpoint: s3.endpoint === undefined
+                ? undefined
+                : validateHttpUrl(s3.endpoint, "s3.endpoint"),
+            forcePathStyle: s3.forcePathStyle ?? false,
+            region: requireNonBlankString(s3.region, "s3.region"),
+            storagePrefix: validateSafePrefix(s3.storagePrefix, "s3.storagePrefix"),
+        },
+    };
+};
+exports.validateS3CacheProviderOptions = validateS3CacheProviderOptions;
+const buildLocalProviderOptions = (options) => ({
+    ...(options?.backendUrl ? { backend_url: options.backendUrl } : {}),
+    ...(options?.privateUploadDir
+        ? { private_upload_dir: options.privateUploadDir }
+        : {}),
+    ...(options?.uploadDir ? { upload_dir: options.uploadDir } : {}),
+});
+const createS3CacheFileModuleConfig = (options = {}) => {
+    if (options.enabled !== true) {
+        return {
+            options: {
+                providers: [
+                    {
+                        id: "local",
+                        options: buildLocalProviderOptions(options.local),
+                        resolve: "@medusajs/medusa/file-local",
+                    },
+                ],
+            },
+            resolve: "@medusajs/medusa/file",
+        };
+    }
+    return s3FileModule((0, exports.validateS3CacheProviderOptions)(options));
+};
+exports.createS3CacheFileModuleConfig = createS3CacheFileModuleConfig;
+const s3FileModule = (validated) => ({
+    options: {
+        providers: [
+            {
+                id: "s3-cache",
+                options: {
+                    cache: validated.cache,
+                    gateway: validated.gateway,
+                    s3: validated.s3,
+                },
+                resolve: "@hartl-services/medusa-base/providers/s3-cache",
+            },
+        ],
+    },
+    resolve: "@medusajs/medusa/file",
+});
+/**
+ * Validates the options once and returns both parts S3 Cache Storage needs:
+ * the File Module with the S3 provider (under `modules`) and the `gateway`
+ * part of the base plugin's `files` option that serves its `/files` routes.
+ * Both carry the same signing secret, so every URL the provider signs is one
+ * the routes accept.
+ */
+const createS3CacheStorageConfig = (options) => {
+    const validated = (0, exports.validateS3CacheProviderOptions)(options);
+    return {
+        fileModule: s3FileModule(validated),
+        gateway: { signingSecret: validated.gateway.signingSecret },
+    };
+};
+exports.createS3CacheStorageConfig = createS3CacheStorageConfig;
+/**
+ * `medusa build` loads the configuration without deployment secrets. These
+ * placeholders only satisfy the required-variable checks of a build; they
+ * never reach a running server.
+ */
+exports.S3_BUILD_PLACEHOLDERS = {
+    S3_CACHE_STORAGE_BUCKET: "build-bucket",
+    S3_CACHE_STORAGE_REGION: "build-placeholder",
+};
+const optionalEnvironment = (environment, name) => {
+    const value = environment[name]?.trim();
+    return value ? value : undefined;
+};
+/**
+ * Static S3 credentials are optional (the AWS credential chain applies
+ * otherwise) but must be complete when present. They are never read during
+ * a build.
+ */
+const resolveS3Credentials = (environment, phase) => {
+    if (phase === "build") {
+        return undefined;
+    }
+    const accessKeyId = optionalEnvironment(environment, "S3_CACHE_STORAGE_ACCESS_KEY_ID");
+    const secretAccessKey = optionalEnvironment(environment, "S3_CACHE_STORAGE_SECRET_ACCESS_KEY");
+    const sessionToken = optionalEnvironment(environment, "S3_CACHE_STORAGE_SESSION_TOKEN");
+    // A declared but blank key still counts: it signals intended static
+    // credentials, which must then be complete.
+    if (!("S3_CACHE_STORAGE_ACCESS_KEY_ID" in environment) &&
+        !("S3_CACHE_STORAGE_SECRET_ACCESS_KEY" in environment) &&
+        !sessionToken) {
+        return undefined;
+    }
+    const missing = [
+        accessKeyId ? undefined : "S3_CACHE_STORAGE_ACCESS_KEY_ID",
+        secretAccessKey ? undefined : "S3_CACHE_STORAGE_SECRET_ACCESS_KEY",
+    ].filter((name) => name !== undefined);
+    if (missing.length > 0) {
+        throw new TypeError(`Missing required environment variables: ${missing.join(", ")}.`);
+    }
+    return {
+        accessKeyId: accessKeyId,
+        secretAccessKey: secretAccessKey,
+        ...(sessionToken ? { sessionToken } : {}),
+    };
+};
+exports.resolveS3Credentials = resolveS3Credentials;
+const resolveExpirationStrategy = (environment, defaultValue) => {
+    const value = optionalEnvironment(environment, "S3_CACHE_STORAGE_EXPIRATION_STRATEGY");
+    if (value === undefined) {
+        return defaultValue;
+    }
+    if (value !== "absolute" && value !== "sliding") {
+        throw new TypeError('S3_CACHE_STORAGE_EXPIRATION_STRATEGY must be either "absolute" or "sliding".');
+    }
+    return value;
+};
+exports.resolveExpirationStrategy = resolveExpirationStrategy;

package/dist/files/gateway/index.d.ts

@@ -0,0 +1,30 @@
+export declare const toPublicFileGatewayUrl: (baseUrl: string, logicalFileKey: string) => string;
+export declare const publicFileGatewayKey: (asset: string) => string;
+export declare const createPrivateFileGatewayUrl: (input: {
+    baseUrl: string;
+    durationSeconds: number;
+    fileKey: string;
+    now?: number;
+    signingSecret: string;
+}) => string;
+export declare const createFileGatewayUploadUrl: (input: {
+    baseUrl: string;
+    durationSeconds: number;
+    fileKey: string;
+    now?: number;
+    signingSecret: string;
+}) => string;
+export declare const verifyPrivateFileGatewayToken: (input: {
+    expires: number;
+    now?: number;
+    signature: string;
+    signingSecret: string;
+    token: string;
+}) => string | undefined;
+export declare const verifyFileGatewayUploadToken: (input: {
+    expires: number;
+    now?: number;
+    signature: string;
+    signingSecret: string;
+    token: string;
+}) => string | undefined;

package/dist/files/gateway/index.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyFileGatewayUploadToken = exports.verifyPrivateFileGatewayToken = exports.createFileGatewayUploadUrl = exports.createPrivateFileGatewayUrl = exports.publicFileGatewayKey = exports.toPublicFileGatewayUrl = void 0;
+const node_crypto_1 = require("node:crypto");
+const PRIVATE_SIGNATURE_VERSION = "v1";
+const safeLogicalKey = (value) => {
+    if (!value ||
+        value.startsWith("/") ||
+        value.includes("\\") ||
+        value
+            .split("/")
+            .some((segment) => !segment ||
+            segment === "." ||
+            segment === ".." ||
+            /[\u0000-\u001F\u007F]/u.test(segment))) {
+        throw new TypeError("File gateway key must be a safe relative path");
+    }
+    return value;
+};
+const gatewayUrl = (baseUrl, path) => {
+    const url = new URL(`${baseUrl.replace(/\/$/u, "")}/`);
+    url.pathname = `${url.pathname.replace(/\/$/u, "")}/${path}`;
+    return url;
+};
+const signatureFor = (input) => (0, node_crypto_1.createHmac)("sha256", input.secret)
+    .update(`${PRIVATE_SIGNATURE_VERSION}\n${input.action}\n${input.token}\n${input.expires}`)
+    .digest("base64url");
+const createPrivateCapabilityUrl = (input) => {
+    const fileKey = safeLogicalKey(input.fileKey);
+    if (input.action === "download" && fileKey.startsWith("public/")) {
+        throw new TypeError("Public files must not use private gateway URLs");
+    }
+    const token = Buffer.from(fileKey, "utf8").toString("base64url");
+    const expires = Math.floor((input.now ?? Date.now()) / 1_000) + input.durationSeconds;
+    const url = gatewayUrl(input.baseUrl, `${input.path}/${token}`);
+    url.searchParams.set("expires", String(expires));
+    url.searchParams.set("signature", signatureFor({
+        action: input.action,
+        expires,
+        secret: input.signingSecret,
+        token,
+    }));
+    return url.toString();
+};
+const verifyPrivateCapabilityToken = (input) => {
+    if (!Number.isSafeInteger(input.expires) ||
+        input.expires < Math.floor((input.now ?? Date.now()) / 1_000)) {
+        return undefined;
+    }
+    const expected = Buffer.from(signatureFor({
+        action: input.action,
+        expires: input.expires,
+        secret: input.signingSecret,
+        token: input.token,
+    }), "base64url");
+    const provided = Buffer.from(input.signature, "base64url");
+    if (provided.toString("base64url") !== input.signature ||
+        provided.length !== expected.length ||
+        !(0, node_crypto_1.timingSafeEqual)(provided, expected)) {
+        return undefined;
+    }
+    try {
+        const fileKeyBuffer = Buffer.from(input.token, "base64url");
+        if (fileKeyBuffer.toString("base64url") !== input.token) {
+            return undefined;
+        }
+        const fileKey = safeLogicalKey(fileKeyBuffer.toString("utf8"));
+        return input.action === "download" && fileKey.startsWith("public/")
+            ? undefined
+            : fileKey;
+    }
+    catch {
+        return undefined;
+    }
+};
+const toPublicFileGatewayUrl = (baseUrl, logicalFileKey) => {
+    const key = safeLogicalKey(logicalFileKey);
+    if (!key.startsWith("public/")) {
+        throw new TypeError("Only public file keys can have public gateway URLs");
+    }
+    const asset = key.slice("public/".length);
+    if (!asset || asset.includes("/")) {
+        throw new TypeError("Public gateway files must have one opaque asset name");
+    }
+    return gatewayUrl(baseUrl, encodeURIComponent(asset)).toString();
+};
+exports.toPublicFileGatewayUrl = toPublicFileGatewayUrl;
+const publicFileGatewayKey = (asset) => {
+    if (!asset || asset.includes("/") || asset.includes("\\")) {
+        throw new TypeError("Public gateway asset is invalid");
+    }
+    return safeLogicalKey(`public/${asset}`);
+};
+exports.publicFileGatewayKey = publicFileGatewayKey;
+const createPrivateFileGatewayUrl = (input) => {
+    return createPrivateCapabilityUrl({
+        ...input,
+        action: "download",
+        path: "private",
+    });
+};
+exports.createPrivateFileGatewayUrl = createPrivateFileGatewayUrl;
+const createFileGatewayUploadUrl = (input) => createPrivateCapabilityUrl({
+    ...input,
+    action: "upload",
+    path: "upload",
+});
+exports.createFileGatewayUploadUrl = createFileGatewayUploadUrl;
+const verifyPrivateFileGatewayToken = (input) => {
+    return verifyPrivateCapabilityToken({ ...input, action: "download" });
+};
+exports.verifyPrivateFileGatewayToken = verifyPrivateFileGatewayToken;
+const verifyFileGatewayUploadToken = (input) => verifyPrivateCapabilityToken({ ...input, action: "upload" });
+exports.verifyFileGatewayUploadToken = verifyFileGatewayUploadToken;

package/dist/files/types/index.d.ts

@@ -0,0 +1,2 @@
+export type { CacheExpirationStrategy, FileGatewayOptions, FilesPluginOptions, FileModuleConfiguration, FileModuleProviderConfiguration, LocalFileProviderOptions, S3CacheCredentials, S3CacheFileModuleConfigOptions, S3CacheOptions, S3CacheOptionsCache, S3CacheStorageConfiguration, ValidatedS3CacheCredentials, ValidatedFileGatewayOptions, ValidatedS3CacheOptions, ValidatedS3CacheProviderOptions, } from "./public";
+export { BASE_PLUGIN_RESOLVE } from "./public";

package/dist/files/types/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BASE_PLUGIN_RESOLVE = void 0;
+var public_1 = require("./public");
+Object.defineProperty(exports, "BASE_PLUGIN_RESOLVE", { enumerable: true, get: function () { return public_1.BASE_PLUGIN_RESOLVE; } });

package/dist/files/types/public.d.ts

@@ -0,0 +1,90 @@
+export type CacheExpirationStrategy = "absolute" | "sliding";
+export interface S3CacheCredentials {
+    accessKeyId?: string;
+    secretAccessKey?: string;
+    sessionToken?: string;
+}
+export interface S3CacheOptions {
+    bucket?: string;
+    credentials?: S3CacheCredentials;
+    endpoint?: string;
+    forcePathStyle?: boolean;
+    region?: string;
+    storagePrefix?: string;
+}
+export interface FileGatewayOptions {
+    baseUrl?: string;
+    privateDownloadDurationSeconds?: number;
+    signingSecret?: string;
+}
+export interface S3CacheOptionsCache {
+    cleanupIntervalMs?: number;
+    dir?: string;
+    expirationStrategy?: CacheExpirationStrategy;
+    ttlMs?: number;
+}
+export interface LocalFileProviderOptions {
+    backendUrl?: string;
+    privateUploadDir?: string;
+    uploadDir?: string;
+}
+export interface S3CacheFileModuleConfigOptions {
+    cache?: S3CacheOptionsCache;
+    enabled?: boolean;
+    gateway?: FileGatewayOptions;
+    local?: LocalFileProviderOptions;
+    s3?: S3CacheOptions;
+}
+export interface FileModuleProviderConfiguration {
+    id: string;
+    options: Record<string, unknown>;
+    resolve: string;
+}
+export interface FileModuleConfiguration {
+    options: {
+        providers: FileModuleProviderConfiguration[];
+    };
+    resolve: "@medusajs/medusa/file";
+}
+export interface ValidatedS3CacheCredentials {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+}
+export interface ValidatedS3CacheOptions {
+    bucket: string;
+    credentials?: ValidatedS3CacheCredentials;
+    endpoint?: string;
+    forcePathStyle: boolean;
+    region: string;
+    storagePrefix: string;
+}
+export interface ValidatedFileGatewayOptions {
+    baseUrl: string;
+    privateDownloadDurationSeconds: number;
+    signingSecret: string;
+}
+export interface ValidatedS3CacheProviderOptions {
+    cache: Required<S3CacheOptionsCache>;
+    gateway: ValidatedFileGatewayOptions;
+    s3: ValidatedS3CacheOptions;
+}
+/** Package name under which the gateway routes read the `files` options. */
+export declare const BASE_PLUGIN_RESOLVE = "@hartl-services/medusa-base";
+/**
+ * The `files` namespace of the base plugin options: what the `/files` gateway
+ * routes sign and verify with. `createS3CacheStorageConfig` returns it from the
+ * same validated input as the File Module provider, so every URL the provider
+ * signs is one the routes accept.
+ */
+export type FilesPluginOptions = {
+    gateway: {
+        signingSecret: string;
+    };
+};
+export interface S3CacheStorageConfiguration {
+    /** Register under `modules`: the File Module with this S3 provider. */
+    fileModule: FileModuleConfiguration;
+    /** Set as `files.gateway` in the options of the base plugin. */
+    gateway: FilesPluginOptions["gateway"];
+}

package/dist/files/types/public.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BASE_PLUGIN_RESOLVE = void 0;
+/** Package name under which the gateway routes read the `files` options. */
+exports.BASE_PLUGIN_RESOLVE = "@hartl-services/medusa-base";

package/dist/modules/documents/domain/merchant.d.ts

@@ -0,0 +1,22 @@
+import type { DocumentMerchant, DocumentMerchantOption } from "../../../documents/types/documents";
+/** Shop master data keys (base plugin, `plugin_key: "shop"`) documents read. */
+export type DocumentMerchantKey = keyof DocumentMerchant;
+export type DocumentMerchantValues = Partial<Record<DocumentMerchantKey, string>>;
+/** Without these a financial document or packing list has no legal sender. */
+export declare const DOCUMENT_MERCHANT_REQUIRED_FIELDS: readonly ["legal_name", "address_line1", "postal_code", "city", "country_code"];
+/** Development placeholder UID: never printed on a document. */
+export declare const MERCHANT_VAT_PLACEHOLDER = "ATU00000000";
+/**
+ * The plugin's `merchant` option as a per-field fallback for the shop master
+ * data. Empty values are left out so they never shadow a declared default.
+ */
+export declare const merchantOptionToFallback: (option: DocumentMerchantOption | undefined) => DocumentMerchantValues;
+export type DocumentMerchantResolution = {
+    merchant: DocumentMerchant;
+    missing: [];
+} | {
+    merchant: null;
+    missing: DocumentMerchantKey[];
+};
+/** Maps resolved shop master data to the render input's `merchant`. */
+export declare const toDocumentMerchant: (values: DocumentMerchantValues) => DocumentMerchantResolution;

package/dist/modules/documents/domain/merchant.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toDocumentMerchant = exports.merchantOptionToFallback = exports.MERCHANT_VAT_PLACEHOLDER = exports.DOCUMENT_MERCHANT_REQUIRED_FIELDS = void 0;
+/** Without these a financial document or packing list has no legal sender. */
+exports.DOCUMENT_MERCHANT_REQUIRED_FIELDS = [
+    "legal_name",
+    "address_line1",
+    "postal_code",
+    "city",
+    "country_code",
+];
+/** Development placeholder UID: never printed on a document. */
+exports.MERCHANT_VAT_PLACEHOLDER = "ATU00000000";
+const text = (value) => {
+    if (typeof value !== "string") {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed ? trimmed : null;
+};
+const vatNumber = (value) => {
+    const normalized = text(value);
+    return normalized &&
+        normalized.replace(/\s+/g, "").toUpperCase() === exports.MERCHANT_VAT_PLACEHOLDER
+        ? null
+        : normalized;
+};
+/**
+ * The plugin's `merchant` option as a per-field fallback for the shop master
+ * data. Empty values are left out so they never shadow a declared default.
+ */
+const merchantOptionToFallback = (option) => {
+    if (!option) {
+        return {};
+    }
+    const address = option.registeredAddress;
+    const entries = [
+        ["legal_name", option.legalName],
+        ["address_line1", address?.address1],
+        ["address_line2", address?.address2],
+        ["postal_code", address?.postalCode],
+        ["city", address?.city],
+        [
+            "country_code",
+            text(address?.countryCode ?? option.countryCode)?.toLowerCase(),
+        ],
+        ["vat_number", option.vatNumber],
+    ];
+    const fallback = {};
+    for (const [key, value] of entries) {
+        const normalized = text(value);
+        if (normalized) {
+            fallback[key] = normalized;
+        }
+    }
+    return fallback;
+};
+exports.merchantOptionToFallback = merchantOptionToFallback;
+/** Maps resolved shop master data to the render input's `merchant`. */
+const toDocumentMerchant = (values) => {
+    const missing = exports.DOCUMENT_MERCHANT_REQUIRED_FIELDS.filter((key) => !text(values[key]));
+    if (missing.length > 0) {
+        return { merchant: null, missing };
+    }
+    return {
+        merchant: {
+            legal_name: text(values.legal_name),
+            address_line1: text(values.address_line1),
+            address_line2: text(values.address_line2),
+            postal_code: text(values.postal_code),
+            city: text(values.city),
+            country_code: text(values.country_code).toLowerCase(),
+            vat_number: vatNumber(values.vat_number),
+            email: text(values.email),
+            phone: text(values.phone),
+            website: text(values.website),
+            iban: text(values.iban),
+            bic: text(values.bic),
+            company_register_number: text(values.company_register_number),
+            company_register_court: text(values.company_register_court),
+        },
+        missing: [],
+    };
+};
+exports.toDocumentMerchant = toDocumentMerchant;

package/dist/modules/documents/domain/options.d.ts

@@ -0,0 +1,34 @@
+import type { DocumentHtmlFactory } from "../../../documents/types/html-factory";
+import type { DocumentMerchantOption, DocumentPdfOptions } from "../../../documents/types/documents";
+import { type DocumentMerchantValues } from "./merchant";
+/** Used when the `documents.numbering.timeZone` option is not given. */
+export declare const DEFAULT_NUMBERING_TIME_ZONE = "Europe/Vienna";
+/** The `documents` namespace of the base plugin options. */
+export type DocumentPluginOptions = {
+    /**
+     * Replaces the built-in German document markup. Omit it to use
+     * `createDefaultDocumentHtmlFactory` with the `numbering.timeZone`.
+     */
+    htmlFactory?: DocumentHtmlFactory;
+    /**
+     * Fallback for the shop master data of the base plugin: used per field
+     * only where no value is stored there.
+     */
+    merchant?: DocumentMerchantOption;
+    numbering?: {
+        timeZone?: string;
+    };
+    pdf?: DocumentPdfOptions;
+};
+export type ResolvedDocumentPluginOptions = {
+    htmlFactory: DocumentHtmlFactory;
+    /** The `merchant` option keyed by shop master data field. */
+    merchantFallback: DocumentMerchantValues;
+    numbering: {
+        timeZone: string;
+    };
+    pdf: {
+        executablePath: string;
+    };
+};
+export declare const resolveDocumentPluginOptions: (options: DocumentPluginOptions | undefined) => ResolvedDocumentPluginOptions;