@hartl-services/medusa-base 0.3.0 → 1.0.0

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;

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

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveDocumentPluginOptions = exports.DEFAULT_NUMBERING_TIME_ZONE = void 0;
+const utils_1 = require("@medusajs/framework/utils");
+const html_factory_1 = require("../../../documents/templates/html-factory");
+const merchant_1 = require("./merchant");
+/** Used when the `documents.numbering.timeZone` option is not given. */
+exports.DEFAULT_NUMBERING_TIME_ZONE = "Europe/Vienna";
+const resolveDocumentPluginOptions = (options) => {
+    const configuredTimeZone = options?.numbering?.timeZone;
+    const timeZone = configuredTimeZone === undefined
+        ? exports.DEFAULT_NUMBERING_TIME_ZONE
+        : configuredTimeZone.trim();
+    if (!timeZone) {
+        throw new utils_1.MedusaError(utils_1.MedusaError.Types.INVALID_DATA, "The documents plugin requires a numbering time zone.");
+    }
+    try {
+        new Intl.DateTimeFormat("en", { timeZone }).format();
+    }
+    catch {
+        throw new utils_1.MedusaError(utils_1.MedusaError.Types.INVALID_DATA, `The documents numbering time zone '${timeZone}' is invalid.`);
+    }
+    if (options?.htmlFactory !== undefined &&
+        typeof options.htmlFactory !== "function") {
+        throw new utils_1.MedusaError(utils_1.MedusaError.Types.INVALID_DATA, "The documents 'htmlFactory' option must be a function.");
+    }
+    if (options?.merchant !== undefined &&
+        (typeof options.merchant !== "object" || options.merchant === null)) {
+        throw new utils_1.MedusaError(utils_1.MedusaError.Types.INVALID_DATA, "The documents 'merchant' option must be an object.");
+    }
+    const executablePath = options?.pdf?.executablePath?.trim() || "google-chrome";
+    return {
+        htmlFactory: options?.htmlFactory ?? (0, html_factory_1.createDefaultDocumentHtmlFactory)({ timeZone }),
+        merchantFallback: (0, merchant_1.merchantOptionToFallback)(options?.merchant),
+        numbering: { timeZone },
+        pdf: { executablePath },
+    };
+};
+exports.resolveDocumentPluginOptions = resolveDocumentPluginOptions;

package/dist/public/action-progress.d.ts

@@ -0,0 +1,25 @@
+import type { MedusaContainer } from "@medusajs/framework/types";
+import type { PluginActionProgressInput } from "./types";
+/** Stored shape of a run's progress. */
+export type PluginActionProgress = {
+    current: number;
+    total: number | null;
+    label: string | null;
+};
+/** Longest stored progress label; longer labels are cut. */
+export declare const PLUGIN_ACTION_PROGRESS_LABEL_MAX_LENGTH = 200;
+/**
+ * Validates and normalizes reported progress: `current` and `total` are
+ * non-negative integers (`total` may be unknown), a blank label is `null`
+ * and a long one is cut. Throws `INVALID_DATA`.
+ */
+export declare function normalizeActionProgress(progress: PluginActionProgressInput): PluginActionProgress;
+/**
+ * Stores the progress of a running action (shown in the Admin while it
+ * runs). Call it from the action's workflow with `input.run_id`. Without a
+ * `run_id` (e.g. the same workflow run from a script) it does nothing. An
+ * unknown or finished run, a failed write and invalid progress (negative
+ * or non-integer numbers) are logged as a warning and dropped; progress
+ * never fails the action.
+ */
+export declare function reportPluginActionProgress(container: MedusaContainer, runId: string | null | undefined, progress: PluginActionProgressInput): Promise<void>;

package/dist/public/action-progress.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLUGIN_ACTION_PROGRESS_LABEL_MAX_LENGTH = void 0;
+exports.normalizeActionProgress = normalizeActionProgress;
+exports.reportPluginActionProgress = reportPluginActionProgress;
+const utils_1 = require("@medusajs/framework/utils");
+const module_access_1 = require("./module-access");
+/** Longest stored progress label; longer labels are cut. */
+exports.PLUGIN_ACTION_PROGRESS_LABEL_MAX_LENGTH = 200;
+const isCount = (value) => typeof value === "number" && Number.isInteger(value) && value >= 0;
+/**
+ * Validates and normalizes reported progress: `current` and `total` are
+ * non-negative integers (`total` may be unknown), a blank label is `null`
+ * and a long one is cut. Throws `INVALID_DATA`.
+ */
+function normalizeActionProgress(progress) {
+    if (!isCount(progress?.current)) {
+        throw new utils_1.MedusaError(utils_1.MedusaError.Types.INVALID_DATA, "Fortschritt: current muss eine nicht-negative ganze Zahl sein.");
+    }
+    const total = progress.total ?? null;
+    if (total !== null && !isCount(total)) {
+        throw new utils_1.MedusaError(utils_1.MedusaError.Types.INVALID_DATA, "Fortschritt: total muss eine nicht-negative ganze Zahl oder null sein.");
+    }
+    const label = typeof progress.label === "string" && progress.label.trim()
+        ? progress.label.trim().slice(0, exports.PLUGIN_ACTION_PROGRESS_LABEL_MAX_LENGTH)
+        : null;
+    return { current: progress.current, total, label };
+}
+const warn = (container, message) => {
+    try {
+        container.resolve(utils_1.ContainerRegistrationKeys.LOGGER).warn(message);
+    }
+    catch {
+        // Progress is informational; logging must not fail the action.
+    }
+};
+/**
+ * Stores the progress of a running action (shown in the Admin while it
+ * runs). Call it from the action's workflow with `input.run_id`. Without a
+ * `run_id` (e.g. the same workflow run from a script) it does nothing. An
+ * unknown or finished run, a failed write and invalid progress (negative
+ * or non-integer numbers) are logged as a warning and dropped; progress
+ * never fails the action.
+ */
+async function reportPluginActionProgress(container, runId, progress) {
+    let normalized;
+    try {
+        normalized = normalizeActionProgress(progress);
+    }
+    catch (error) {
+        warn(container, `Ungültiger Fortschritt${runId ? ` für Aktionslauf "${runId}"` : ""} verworfen: ${error instanceof Error ? error.message : String(error)}`);
+        return;
+    }
+    if (!runId) {
+        return;
+    }
+    try {
+        const updated = await (0, module_access_1.resolveBaseModule)(container).reportPluginActionRunProgress(runId, normalized);
+        if (!updated) {
+            warn(container, `Fortschritt für Aktionslauf "${runId}" verworfen: Lauf unbekannt oder nicht mehr aktiv.`);
+        }
+    }
+    catch (error) {
+        warn(container, `Fortschritt für Aktionslauf "${runId}" konnte nicht gespeichert werden: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

package/dist/public/config.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Environment helpers for a shop's `medusa-config.ts`. The configuration
+ * itself (which plugins run, static shop facts, defaults) lives in the shop;
+ * these helpers only read and validate deployment values so a misconfigured
+ * deployment fails at startup with the variable's name.
+ */
+export type ConfigurationPhase = "build" | "runtime";
+/**
+ * Placeholders for the variables Medusa core and the Stripe payment provider
+ * need. `medusa build` loads the configuration without deployment secrets;
+ * pass these (merged with the placeholders of the shop's other plugins) as
+ * `buildPlaceholders` to `requireEnvironment` so required-variable checks pass
+ * during the build. They never reach a running server.
+ */
+export declare const MEDUSA_BUILD_PLACEHOLDERS: Readonly<Record<string, string>>;
+export declare const optionalEnvironment: (environment: NodeJS.ProcessEnv, name: string) => string | undefined;
+/**
+ * Returns every named value or throws one error listing all missing names.
+ * During the build phase, the given `buildPlaceholders` stand in for
+ * deployment values; at runtime they are ignored.
+ */
+export declare const requireEnvironment: <Name extends string>(environment: NodeJS.ProcessEnv, names: readonly Name[], phase: ConfigurationPhase, buildPlaceholders: Readonly<Record<string, string>>) => Readonly<Record<Name, string>>;
+export declare const integerEnvironment: (environment: NodeJS.ProcessEnv, name: string, minimum: number, maximum: number) => number | undefined;
+export declare const booleanEnvironment: (environment: NodeJS.ProcessEnv, name: string, defaultValue: boolean) => boolean;
+/** Local development, tests and builds may use plain HTTP and SMTP. */
+export declare const allowsInsecureLocalServices: (environment: NodeJS.ProcessEnv, phase: ConfigurationPhase) => boolean;
+export declare const resolvePublicOrigin: (value: string, name: string, allowHttp: boolean) => string;
+/**
+ * Builds an absolute URL on a validated origin from a path that may contain
+ * customer-controlled parts (e.g. a locale). Protocol-relative paths, queries,
+ * fragments and backslashes are rejected so the URL can never leave the origin.
+ */
+export declare const shopUrl: (origin: string, path: string) => string;
+export declare const resolveStripe: (values: {
+    readonly STRIPE_API_KEY: string;
+    readonly STRIPE_WEBHOOK_SECRET: string;
+}) => {
+    readonly apiKey: string;
+    readonly webhookSecret: string;
+};
+export type RedisEventBusConfiguration = {
+    readonly url: string;
+};
+/**
+ * Redis is optional in development (Medusa then uses its local Event Bus),
+ * required at runtime everywhere else, and never used during a build.
+ * Production requires authenticated `rediss://` unless an insecure private
+ * network is explicitly accepted.
+ */
+export declare const resolveRedisEventBus: (environment: NodeJS.ProcessEnv, phase: ConfigurationPhase) => RedisEventBusConfiguration | undefined;
+/**
+ * Boot-time registrations of the plugin's built-in modules, from the same
+ * `@hartl-services/medusa-base/config` entry: the SMTP notification provider
+ * (E-Mail), the S3 file storage provider with its `/files` gateway part, and
+ * the default document markup.
+ */
+export * from "../email/config";
+export * from "../files/config";
+export * from "../documents/config";

package/dist/public/config.js

@@ -0,0 +1,185 @@
+"use strict";
+/* eslint-disable @medusajs/use-medusa-error-not-generic-error -- Startup configuration errors are not HTTP responses. */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveRedisEventBus = exports.resolveStripe = exports.shopUrl = exports.resolvePublicOrigin = exports.allowsInsecureLocalServices = exports.booleanEnvironment = exports.integerEnvironment = exports.requireEnvironment = exports.optionalEnvironment = exports.MEDUSA_BUILD_PLACEHOLDERS = void 0;
+/**
+ * Placeholders for the variables Medusa core and the Stripe payment provider
+ * need. `medusa build` loads the configuration without deployment secrets;
+ * pass these (merged with the placeholders of the shop's other plugins) as
+ * `buildPlaceholders` to `requireEnvironment` so required-variable checks pass
+ * during the build. They never reach a running server.
+ */
+exports.MEDUSA_BUILD_PLACEHOLDERS = {
+    ADMIN_CORS: "http://localhost",
+    AUTH_CORS: "http://localhost",
+    COOKIE_SECRET: "build-placeholder",
+    DATABASE_URL: "postgres://build:build@localhost:5432/build",
+    JWT_SECRET: "build-placeholder",
+    MEDUSA_BACKEND_URL: "http://localhost",
+    STOREFRONT_URL: "http://localhost:8000",
+    STORE_CORS: "http://localhost",
+    STRIPE_API_KEY: "sk_test_build-placeholder",
+    STRIPE_WEBHOOK_SECRET: "whsec_build-placeholder",
+};
+const optionalEnvironment = (environment, name) => {
+    const value = environment[name]?.trim();
+    return value ? value : undefined;
+};
+exports.optionalEnvironment = optionalEnvironment;
+/**
+ * Returns every named value or throws one error listing all missing names.
+ * During the build phase, the given `buildPlaceholders` stand in for
+ * deployment values; at runtime they are ignored.
+ */
+const requireEnvironment = (environment, names, phase, buildPlaceholders) => {
+    const source = phase === "build" ? { ...environment, ...buildPlaceholders } : environment;
+    const missing = names.filter((name) => (0, exports.optionalEnvironment)(source, name) === undefined);
+    if (missing.length > 0) {
+        throw new TypeError(`Missing required environment variables: ${missing.join(", ")}.`);
+    }
+    return Object.fromEntries(names.map((name) => [name, (0, exports.optionalEnvironment)(source, name)]));
+};
+exports.requireEnvironment = requireEnvironment;
+const integerEnvironment = (environment, name, minimum, maximum) => {
+    const value = (0, exports.optionalEnvironment)(environment, name);
+    if (value === undefined) {
+        return undefined;
+    }
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < minimum || parsed > maximum) {
+        throw new TypeError(`${name} must be an integer from ${minimum} through ${maximum}.`);
+    }
+    return parsed;
+};
+exports.integerEnvironment = integerEnvironment;
+const booleanEnvironment = (environment, name, defaultValue) => {
+    const value = (0, exports.optionalEnvironment)(environment, name);
+    if (value === undefined) {
+        return defaultValue;
+    }
+    if (value !== "true" && value !== "false") {
+        throw new TypeError(`${name} must be either "true" or "false".`);
+    }
+    return value === "true";
+};
+exports.booleanEnvironment = booleanEnvironment;
+/** Local development, tests and builds may use plain HTTP and SMTP. */
+const allowsInsecureLocalServices = (environment, phase) => phase === "build" ||
+    environment.NODE_ENV === "development" ||
+    environment.NODE_ENV === "test";
+exports.allowsInsecureLocalServices = allowsInsecureLocalServices;
+const resolvePublicOrigin = (value, name, allowHttp) => {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new TypeError(`${name} must be a valid HTTP(S) origin.`);
+    }
+    if ((url.protocol !== "https:" && url.protocol !== "http:") ||
+        url.username ||
+        url.password ||
+        url.pathname !== "/" ||
+        url.search ||
+        url.hash) {
+        throw new TypeError(`${name} must be a valid HTTP(S) origin.`);
+    }
+    if (!allowHttp && url.protocol !== "https:") {
+        throw new TypeError(`${name} must use HTTPS outside development and test.`);
+    }
+    return url.origin;
+};
+exports.resolvePublicOrigin = resolvePublicOrigin;
+/**
+ * Builds an absolute URL on a validated origin from a path that may contain
+ * customer-controlled parts (e.g. a locale). Protocol-relative paths, queries,
+ * fragments and backslashes are rejected so the URL can never leave the origin.
+ */
+const shopUrl = (origin, path) => {
+    if (!path ||
+        path !== path.trim() ||
+        !path.startsWith("/") ||
+        path.startsWith("//") ||
+        path.includes("?") ||
+        path.includes("#") ||
+        path.includes("\\")) {
+        throw new TypeError(`Shop URL path "${path}" is not a plain absolute path.`);
+    }
+    return new URL(path, origin).toString();
+};
+exports.shopUrl = shopUrl;
+const resolveStripe = (values) => {
+    if (!values.STRIPE_API_KEY.startsWith("sk_")) {
+        throw new TypeError("STRIPE_API_KEY must be a Stripe secret key (sk_...), not a publishable key.");
+    }
+    if (!values.STRIPE_WEBHOOK_SECRET.startsWith("whsec_")) {
+        throw new TypeError("STRIPE_WEBHOOK_SECRET must be a Stripe webhook signing secret (whsec_...).");
+    }
+    return {
+        apiKey: values.STRIPE_API_KEY,
+        webhookSecret: values.STRIPE_WEBHOOK_SECRET,
+    };
+};
+exports.resolveStripe = resolveStripe;
+/**
+ * Redis is optional in development (Medusa then uses its local Event Bus),
+ * required at runtime everywhere else, and never used during a build.
+ * Production requires authenticated `rediss://` unless an insecure private
+ * network is explicitly accepted.
+ */
+const resolveRedisEventBus = (environment, phase) => {
+    if (phase === "build") {
+        return undefined;
+    }
+    const url = (0, exports.optionalEnvironment)(environment, "REDIS_URL");
+    if (!url) {
+        if (environment.NODE_ENV !== "development") {
+            throw new TypeError("Missing required environment variables: REDIS_URL.");
+        }
+        return undefined;
+    }
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new TypeError("REDIS_URL must be a valid Redis URL.");
+    }
+    if (parsed.protocol !== "redis:" && parsed.protocol !== "rediss:") {
+        throw new TypeError("REDIS_URL must use redis:// or rediss://.");
+    }
+    if (environment.NODE_ENV === "production") {
+        if (!parsed.password) {
+            throw new TypeError("Production REDIS_URL must include authentication.");
+        }
+        if (parsed.protocol !== "rediss:" &&
+            !(0, exports.booleanEnvironment)(environment, "REDIS_ALLOW_INSECURE_PRIVATE_NETWORK", false)) {
+            throw new TypeError("Production REDIS_URL must use rediss:// unless REDIS_ALLOW_INSECURE_PRIVATE_NETWORK=true.");
+        }
+    }
+    return { url };
+};
+exports.resolveRedisEventBus = resolveRedisEventBus;
+/**
+ * Boot-time registrations of the plugin's built-in modules, from the same
+ * `@hartl-services/medusa-base/config` entry: the SMTP notification provider
+ * (E-Mail), the S3 file storage provider with its `/files` gateway part, and
+ * the default document markup.
+ */
+__exportStar(require("../email/config"), exports);
+__exportStar(require("../files/config"), exports);
+__exportStar(require("../documents/config"), exports);

package/dist/public/descriptor.d.ts

@@ -1,11 +1,12 @@
 import type { PluginFeatureDescriptor } from "./types";
 /**
  * Checks key format, unique feature keys, existing parents and the single
- * allowed nesting level. Throws `INVALID_DATA`.
+ * allowed nesting level, plus the optional settings, actions and Admin page.
+ * Throws `INVALID_DATA`.
  */
 export declare function validatePluginFeatureDescriptor(descriptor: PluginFeatureDescriptor): void;
 /**
  * Declares a plugin's feature switches. Validates at import time so a broken
  * declaration fails the boot instead of a request.
  */
-export declare function definePluginFeatures<const K extends string>(descriptor: PluginFeatureDescriptor<K>): PluginFeatureDescriptor<K>;
+export declare function definePluginFeatures<const K extends string, const S extends string = never, const A extends string = never>(descriptor: PluginFeatureDescriptor<K, S, A>): PluginFeatureDescriptor<K, S, A>;