@hartl-services/medusa-base 0.3.0 → 1.0.0

package/dist/public/shop-types.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Entry of `@hartl-services/medusa-base/types`: the shop-facing types of the
+ * built-in E-Mail (shop branding, templates, SMTP) and Documents (merchant,
+ * HTML factory, wire types) modules.
+ */
+export * from "../email/types";
+export * from "../documents/types";

package/dist/public/shop-types.js

@@ -0,0 +1,23 @@
+"use strict";
+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 });
+/**
+ * Entry of `@hartl-services/medusa-base/types`: the shop-facing types of the
+ * built-in E-Mail (shop branding, templates, SMTP) and Documents (merchant,
+ * HTML factory, wire types) modules.
+ */
+__exportStar(require("../email/types"), exports);
+__exportStar(require("../documents/types"), exports);

package/dist/public/types.d.ts

@@ -1,3 +1,28 @@
+import type { DocumentPluginOptions } from "../modules/documents/domain/options";
+import type { EmailPluginOptions } from "../email/types";
+import type { FilesPluginOptions } from "../files/types";
+/**
+ * Options of the base plugin (`plugins: [{ resolve, options }]`). Medusa hands
+ * the same options object to every module of the plugin; each module service
+ * reads only its own namespace (`email`, `documents`), the `/files` routes
+ * read `files`. `{}` is valid: E-Mail then boots but does not send, the
+ * documents numbering time zone defaults to "Europe/Vienna", and the `/files`
+ * routes answer that signing is not configured.
+ */
+export type BasePluginOptions = {
+    /**
+     * Key material for stored secret settings; set it from an environment
+     * variable of the shop. Defaults to `projectConfig.http.cookieSecret`.
+     * Changing it makes stored secrets undecryptable ("nicht gesetzt").
+     */
+    readonly settingsSecret?: string;
+    /** Mail dispatch: shop branding/URLs and the JWT secret of the links. */
+    readonly email?: EmailPluginOptions;
+    /** Order documents: merchant fallback, numbering, PDF, HTML factory. */
+    readonly documents?: DocumentPluginOptions;
+    /** `/files` gateway signing; set from `createS3CacheStorageConfig`. */
+    readonly files?: FilesPluginOptions;
+};
 export type PluginFeatureDefinition<K extends string = string> = {
     readonly key: K;
     readonly label: string;
@@ -5,17 +30,75 @@ export type PluginFeatureDefinition<K extends string = string> = {
     readonly default_enabled: boolean;
     readonly parent_key?: K;
 };
-export type PluginFeatureDescriptor<K extends string = string> = {
+export type PluginSettingType = "string" | "url" | "number" | "boolean" | "secret" | "select";
+/** One allowed value of a `"select"` setting. */
+export type PluginSettingOption = {
+    readonly value: string;
+    readonly label: string;
+};
+export type PluginSettingValue = string | number | boolean;
+export type PluginSettingDefinition<S extends string = string> = {
+    readonly key: S;
+    readonly label: string;
+    readonly description?: string;
+    readonly type: PluginSettingType;
+    /** `false` when omitted. */
+    readonly required?: boolean;
+    /** Never for `"secret"`; must match `type` (and `options`/`min`/`max`). */
+    readonly default?: PluginSettingValue;
+    /** Required for `"select"` (non-empty, unique values); only there. */
+    readonly options?: readonly PluginSettingOption[];
+    /** Inclusive lower bound; only for `"number"`. */
+    readonly min?: number;
+    /** Inclusive upper bound; only for `"number"`. */
+    readonly max?: number;
+    /**
+     * Secret settings of the same plugin whose stored values are deleted when
+     * this setting's stored value changes (also when it is cleared), e.g. an
+     * API key that must not be sent to a new URL.
+     */
+    readonly invalidates?: readonly S[];
+};
+export type PluginActionMode = "sync" | "background";
+export type PluginActionDefinition<A extends string = string> = {
+    readonly key: A;
+    readonly label: string;
+    readonly description?: string;
+    /** Registered workflow the base runs for this action. */
+    readonly workflow_id: string;
+    readonly mode: PluginActionMode;
+    /** Confirmation text shown before running. */
+    readonly confirm?: string;
+};
+export type PluginFeatureDescriptor<K extends string = string, S extends string = string, A extends string = string> = {
     readonly plugin_key: string;
     readonly label: string;
     readonly description?: string;
     /** Plugin switch default, `true` when omitted. */
     readonly default_enabled?: boolean;
+    /**
+     * `false`: the plugin cannot be switched off. The Admin shows no plugin
+     * switch and `enabled` is always `true`. `true` when omitted.
+     */
+    readonly switchable?: boolean;
     readonly features: readonly PluginFeatureDefinition<K>[];
+    readonly settings?: readonly PluginSettingDefinition<S>[];
+    readonly actions?: readonly PluginActionDefinition<A>[];
+    /**
+     * The plugin's own Admin page, relative to the Admin root; the hub's
+     * "Öffnen" links there. Starts with `/settings/hartl-services/`, never with
+     * `/settings/hartl-services/plugin/` (the base's generic page, used when
+     * omitted).
+     */
+    readonly admin_page?: string;
 };
+/** Values a plugin received from medusa-config; the base shows them as source "config". */
+export type PluginSettingsFallback<S extends string = string> = Partial<Record<S, PluginSettingValue | null | undefined>>;
 /** Implemented by a plugin's module service so the base can discover it. */
 export interface PluginFeatureProvider {
     readonly pluginFeatures: PluginFeatureDescriptor;
+    /** Optional medusa-config fallback for the declared settings. */
+    readonly pluginSettingsFallback?: PluginSettingsFallback;
 }
 export type EffectivePluginFeatures = {
     plugin_key: string;
@@ -27,3 +110,32 @@ export type StoredPluginFeatures = {
     enabled: boolean;
     features: Record<string, boolean>;
 };
+/**
+ * Settings for server-side consumers. Secrets are decrypted. `values` holds
+ * every setting that has a value (stored > config > default).
+ */
+export type ResolvedPluginSettings<S extends string = string> = {
+    values: Partial<Record<S, PluginSettingValue>>;
+    /** Every required setting has a value. */
+    configured: boolean;
+    /** Keys of required settings without a value. */
+    missing: S[];
+};
+/** Input the base passes to an action's workflow. */
+export type PluginActionWorkflowInput = {
+    plugin_key: string;
+    action_key: string;
+    /** Admin user id that triggered the action. */
+    triggered_by: string;
+    /** Recorded run; pass it to `reportPluginActionProgress`. */
+    run_id: string;
+};
+/** Progress a running action reports through `reportPluginActionProgress`. */
+export type PluginActionProgressInput = {
+    /** Items (or pages) done so far; a non-negative integer. */
+    current: number;
+    /** Expected total; `null`/omitted = unknown. */
+    total?: number | null;
+    /** Short human-readable status, e.g. "Produkte: Seite 3". */
+    label?: string | null;
+};

package/dist/shop-config/build-food-shop-config.d.ts

@@ -0,0 +1,44 @@
+import { defineConfig } from "@medusajs/framework/utils";
+import { withSentryErrorReporting } from "../public/sentry-logger";
+import { type FoodShopConfigOptions } from "./options";
+type ConfigInput = Parameters<typeof defineConfig>[0];
+type ProjectConfigInput = NonNullable<Extract<NonNullable<ConfigInput>, {
+    projectConfig?: unknown;
+}>["projectConfig"]>;
+/** A plugin registration of the returned configuration. */
+export type FoodShopPlugin = {
+    resolve: string;
+    options: Record<string, unknown>;
+};
+/** A module registration of the returned configuration. */
+export type FoodShopModule = {
+    key?: string;
+    resolve: string;
+    options?: Record<string, unknown>;
+};
+/**
+ * The configuration input before `defineConfig`. `modules` and `plugins` are
+ * plain arrays so a caller (for example a test harness) can adjust them.
+ */
+export type FoodShopConfigInput = {
+    admin: {
+        path: `/${string}`;
+    };
+    logger: ReturnType<typeof withSentryErrorReporting>;
+    projectConfig: ProjectConfigInput;
+    modules: FoodShopModule[];
+    plugins: FoodShopPlugin[];
+};
+/**
+ * Builds the plain `medusa-config.ts` input of a food shop: Medusa core
+ * settings, the Redis event bus, SMTP notifications, S3 file storage, tax and
+ * Stripe payment providers, and the Hartl Services plugins (the base plugin
+ * with its E-Mail, Documents and file storage modules plus five feature
+ * plugins). Deployment
+ * values are read and validated from `environment`; a missing or invalid one
+ * fails with its name.
+ */
+export declare function buildFoodShopConfig(options: FoodShopConfigOptions, environment?: NodeJS.ProcessEnv): FoodShopConfigInput;
+/** `defineConfig(buildFoodShopConfig(options))` for `module.exports`. */
+export declare function defineFoodShopConfig(options: FoodShopConfigOptions, environment?: NodeJS.ProcessEnv): ReturnType<typeof defineConfig>;
+export {};

package/dist/shop-config/build-food-shop-config.js

@@ -0,0 +1,247 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildFoodShopConfig = buildFoodShopConfig;
+exports.defineFoodShopConfig = defineFoodShopConfig;
+const logger_1 = require("@medusajs/framework/logger");
+const utils_1 = require("@medusajs/framework/utils");
+const config_1 = require("../public/config");
+const sentry_logger_1 = require("../public/sentry-logger");
+const options_1 = require("./options");
+/**
+ * Builds the plain `medusa-config.ts` input of a food shop: Medusa core
+ * settings, the Redis event bus, SMTP notifications, S3 file storage, tax and
+ * Stripe payment providers, and the Hartl Services plugins (the base plugin
+ * with its E-Mail, Documents and file storage modules plus five feature
+ * plugins). Deployment
+ * values are read and validated from `environment`; a missing or invalid one
+ * fails with its name.
+ */
+function buildFoodShopConfig(options, environment = process.env) {
+    (0, options_1.assertFoodShopConfigOptions)(options);
+    const { merchant } = options;
+    if (options.loadEnvFile !== false) {
+        (0, utils_1.loadEnv)(process.env.NODE_ENV || "development", process.cwd());
+    }
+    const phase = environment.MEDUSA_BUILD_PHASE === "true" ? "build" : "runtime";
+    const allowInsecure = (0, config_1.allowsInsecureLocalServices)(environment, phase);
+    const env = (0, config_1.requireEnvironment)(environment, [
+        "DATABASE_URL",
+        "STORE_CORS",
+        "ADMIN_CORS",
+        "AUTH_CORS",
+        "JWT_SECRET",
+        "COOKIE_SECRET",
+        "MEDUSA_BACKEND_URL",
+        "STOREFRONT_URL",
+        ...config_1.SMTP_ENVIRONMENT_VARIABLES,
+        "STRIPE_API_KEY",
+        "STRIPE_WEBHOOK_SECRET",
+        "S3_CACHE_STORAGE_BUCKET",
+        "S3_CACHE_STORAGE_REGION",
+        "DOCUMENT_PDF_EXECUTABLE",
+    ], phase, {
+        ...config_1.MEDUSA_BUILD_PLACEHOLDERS,
+        ...config_1.SMTP_BUILD_PLACEHOLDERS,
+        ...config_1.S3_BUILD_PLACEHOLDERS,
+        ...config_1.DOCUMENTS_BUILD_PLACEHOLDERS,
+    });
+    const storefrontOrigin = (0, config_1.resolvePublicOrigin)(env.STOREFRONT_URL, "STOREFRONT_URL", allowInsecure);
+    const backendOrigin = (0, config_1.resolvePublicOrigin)(env.MEDUSA_BACKEND_URL, "MEDUSA_BACKEND_URL", allowInsecure);
+    const redis = (0, config_1.resolveRedisEventBus)(environment, phase);
+    const stripe = (0, config_1.resolveStripe)(env);
+    const storefrontPath = `/${options.storefrontCountryCode}`;
+    // S3 file storage: the File Module provider plus the `files.gateway` option
+    // of the base plugin that serves its /files routes, both from one validated
+    // configuration.
+    const s3CacheStorage = (0, config_1.createS3CacheStorageConfig)({
+        cache: {
+            cleanupIntervalMs: (0, config_1.integerEnvironment)(environment, "S3_CACHE_STORAGE_CLEANUP_INTERVAL_MS", 1, 86_400_000) ?? 900_000,
+            dir: (0, config_1.optionalEnvironment)(environment, "S3_CACHE_STORAGE_CACHE_DIR") ??
+                "./.medusa-s3-cache",
+            expirationStrategy: (0, config_1.resolveExpirationStrategy)(environment, "absolute"),
+            ttlMs: (0, config_1.integerEnvironment)(environment, "S3_CACHE_STORAGE_TTL_MS", 0, 604_800_000) ?? 3_600_000,
+        },
+        gateway: {
+            baseUrl: `${backendOrigin}/files`,
+            privateDownloadDurationSeconds: (0, config_1.integerEnvironment)(environment, "FILE_GATEWAY_PRIVATE_DOWNLOAD_DURATION_SECONDS", 1, 604_800) ?? 3_600,
+            signingSecret: env.JWT_SECRET,
+        },
+        s3: {
+            bucket: env.S3_CACHE_STORAGE_BUCKET,
+            credentials: (0, config_1.resolveS3Credentials)(environment, phase),
+            endpoint: (0, config_1.optionalEnvironment)(environment, "S3_CACHE_STORAGE_ENDPOINT"),
+            forcePathStyle: (0, config_1.booleanEnvironment)(environment, "S3_CACHE_STORAGE_FORCE_PATH_STYLE", false),
+            region: env.S3_CACHE_STORAGE_REGION,
+            storagePrefix: (0, config_1.optionalEnvironment)(environment, "S3_CACHE_STORAGE_PREFIX"),
+        },
+    });
+    const modules = [
+        ...(redis
+            ? [
+                {
+                    key: utils_1.Modules.EVENT_BUS,
+                    resolve: "@medusajs/event-bus-redis",
+                    options: {
+                        redisUrl: redis.url,
+                        jobOptions: {
+                            attempts: 3,
+                            backoff: {
+                                delay: 1_000,
+                                type: "exponential",
+                            },
+                            removeOnComplete: true,
+                            removeOnFail: {
+                                age: 3_600,
+                                count: 1_000,
+                            },
+                        },
+                    },
+                },
+            ]
+            : []),
+        (0, config_1.createSmtpNotificationModuleConfig)((0, config_1.resolveSmtp)(env, allowInsecure)),
+        s3CacheStorage.fileModule,
+        {
+            resolve: "@medusajs/medusa/tax",
+            options: {
+                providers: [
+                    {
+                        resolve: "@hartl-services/medusa-tax-compliance/providers/tax-compliance",
+                    },
+                ],
+            },
+        },
+        {
+            resolve: "@medusajs/medusa/payment",
+            options: {
+                providers: [
+                    {
+                        resolve: "@medusajs/medusa/payment-stripe",
+                        id: "stripe",
+                        options: {
+                            apiKey: stripe.apiKey,
+                            webhookSecret: stripe.webhookSecret,
+                            // Capture immediately at checkout. Several enabled payment
+                            // methods (e.g. SEPA Direct Debit, iDEAL, Klarna) do not
+                            // support a separate manual-capture step, so authorize-only is
+                            // not an option while automaticPaymentMethods exposes them.
+                            capture: true,
+                            // Which methods appear (card, SEPA, wallets, ...) is controlled
+                            // in the Stripe Dashboard under Settings -> Payment methods.
+                            automaticPaymentMethods: true,
+                        },
+                    },
+                ],
+            },
+        },
+    ];
+    const plugins = [
+        {
+            // Always first: owns the plugin feature toggles the other plugins gate
+            // on, and carries E-Mail, Documents and the /files gateway.
+            resolve: "@hartl-services/medusa-base",
+            options: {
+                email: {
+                    jwtSecret: env.JWT_SECRET,
+                    shop: {
+                        displayName: options.displayName,
+                        affiliatePortalUrl: (0, config_1.shopUrl)(storefrontOrigin, `${storefrontPath}/partnerportal`),
+                        // The Admin dashboard mounts "/invite" under admin.path ("/app").
+                        inviteUrl: ({ token }) => {
+                            const url = new URL("/app/invite", backendOrigin);
+                            url.searchParams.set("token", token);
+                            return url.toString();
+                        },
+                        orderNotificationEmail: options.orderNotificationEmail,
+                        // The e-mail module appends "#token=<token>".
+                        passwordResetUrl: () => (0, config_1.shopUrl)(storefrontOrigin, `${storefrontPath}/reset-password`),
+                    },
+                },
+                documents: {
+                    // Fallback only: the shop master data in the Admin ("Hartl Services
+                    // Plugins" -> Shop-Stammdaten) wins per field.
+                    merchant,
+                    numbering: {
+                        // Chooses the annual document-number period; matches the date the
+                        // HTML factory prints.
+                        timeZone: options.timeZone,
+                    },
+                    pdf: {
+                        executablePath: env.DOCUMENT_PDF_EXECUTABLE,
+                    },
+                },
+                files: { gateway: s3CacheStorage.gateway },
+            },
+        },
+        {
+            resolve: "@hartl-services/medusa-tax-compliance",
+            options: { merchant },
+        },
+        {
+            resolve: "@hartl-services/medusa-free-shipping",
+            options: {},
+        },
+        {
+            resolve: "@hartl-services/medusa-batch-management",
+            options: {},
+        },
+        {
+            resolve: "@hartl-services/medusa-affiliate",
+            options: {
+                consignment_reminders: {
+                    due_day: 10,
+                    timezone: options.timeZone,
+                },
+                portal: {
+                    referral_base_url: (0, config_1.shopUrl)(storefrontOrigin, storefrontPath),
+                },
+            },
+        },
+        {
+            resolve: "@hartl-services/medusa-payload-sync",
+            // URL, API key and auth collection are Admin settings of the base
+            // plugin ("Hartl Services Plugins" -> Payload-CMS-Sync); until they are
+            // stored the plugin boots "nicht konfiguriert".
+            options: {},
+        },
+    ];
+    return {
+        admin: {
+            // Kept explicit: serving the Admin SPA at "/" instead breaks its own
+            // auth, since the SPA's client-side-routing fallback then catches real
+            // API routes like /auth/user/providers too. The invite URL depends on
+            // this path.
+            path: "/app",
+        },
+        // Medusa's own HTTP error-handler middleware fully "handles" every thrown
+        // route/workflow error via logger.error(...) before it can ever reach an
+        // uncaught-exception process hook, so Sentry's default Node integrations
+        // never see it. This bridges logger.error(...) itself so those errors
+        // still reach Sentry.
+        logger: (0, sentry_logger_1.withSentryErrorReporting)(logger_1.logger),
+        projectConfig: {
+            databaseUrl: env.DATABASE_URL,
+            http: {
+                storeCors: env.STORE_CORS,
+                adminCors: env.ADMIN_CORS,
+                authCors: env.AUTH_CORS,
+                jwtSecret: env.JWT_SECRET,
+                cookieSecret: env.COOKIE_SECRET,
+            },
+            // The storefront turns its customer JWT into a Medusa browser session
+            // at login, so its browser-side cart and payment calls carry the
+            // customer's identity. Kept at the JWT's own 24h lifetime (Medusa's
+            // default is 10h) so the two never disagree about whether the customer
+            // is logged in.
+            sessionOptions: {
+                ttl: 24 * 60 * 60 * 1000,
+            },
+        },
+        modules,
+        plugins,
+    };
+}
+/** `defineConfig(buildFoodShopConfig(options))` for `module.exports`. */
+function defineFoodShopConfig(options, environment = process.env) {
+    return (0, utils_1.defineConfig)(buildFoodShopConfig(options, environment));
+}

package/dist/shop-config/options.d.ts

@@ -0,0 +1,41 @@
+import type { DocumentMerchantOption } from "../documents/types";
+/**
+ * The shop-specific facts of a food shop. Deployment values and secrets are
+ * not options: they come from the environment (see the README).
+ */
+export type FoodShopConfigOptions = Readonly<{
+    /**
+     * Fallback for the shop master data (Admin -> "Hartl Services Plugins" ->
+     * Shop-Stammdaten) that documents and tax compliance read per field. Its
+     * `legalName` is also the seeded store name.
+     */
+    merchant: DocumentMerchantOption;
+    /** Shop name in the branding of the default e-mail templates. */
+    displayName: string;
+    /** Receives the shop's order notification e-mails. */
+    orderNotificationEmail: string;
+    /**
+     * IANA time zone (e.g. "Europe/Vienna"): chooses the annual document-number
+     * period, matches the dates printed on documents, and schedules the
+     * affiliate consignment reminders.
+     */
+    timeZone: string;
+    /**
+     * Country code of the storefront route segment (e.g. "de"): e-mail links
+     * point to `/<code>/partnerportal` and `/<code>/reset-password`, and
+     * affiliate referral links to `/<code>`.
+     */
+    storefrontCountryCode: string;
+    /**
+     * Load `.env.<NODE_ENV>` from the working directory into `process.env`
+     * like `medusa-config.ts` does by default. Pass `false` when the
+     * environment is already complete (tests, isolated child processes).
+     * Defaults to `true`.
+     */
+    loadEnvFile?: boolean;
+}>;
+/**
+ * Throws a `TypeError` naming the first invalid option, so a misconfigured
+ * shop fails at boot.
+ */
+export declare function assertFoodShopConfigOptions(options: unknown): asserts options is FoodShopConfigOptions;

package/dist/shop-config/options.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertFoodShopConfigOptions = assertFoodShopConfigOptions;
+const fail = (name, expectation) => {
+    throw new TypeError(`Food shop option "${name}" must be ${expectation}.`);
+};
+const requireText = (value, name) => {
+    if (typeof value !== "string" || value.trim() === "") {
+        return fail(name, "a non-empty string");
+    }
+    return value;
+};
+const requireCountryCode = (value, name) => {
+    if (typeof value !== "string" || !/^[a-z]{2}$/.test(value)) {
+        return fail(name, 'a 2-letter lowercase country code such as "de"');
+    }
+    return value;
+};
+const requireTimeZone = (value, name) => {
+    const timeZone = requireText(value, name);
+    try {
+        new Intl.DateTimeFormat("en-US", { timeZone });
+    }
+    catch {
+        return fail(name, 'a valid IANA time zone such as "Europe/Vienna"');
+    }
+    return timeZone;
+};
+const requireEmail = (value, name) => {
+    const email = requireText(value, name);
+    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+        return fail(name, "a valid e-mail address");
+    }
+    return email;
+};
+const requireObject = (value, name) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return fail(name, "an object");
+    }
+    return value;
+};
+/**
+ * Throws a `TypeError` naming the first invalid option, so a misconfigured
+ * shop fails at boot.
+ */
+function assertFoodShopConfigOptions(options) {
+    const candidate = requireObject(options, "options");
+    const merchant = requireObject(candidate.merchant, "merchant");
+    requireText(merchant.legalName, "merchant.legalName");
+    requireCountryCode(merchant.countryCode, "merchant.countryCode");
+    if (merchant.vatNumber !== undefined) {
+        requireText(merchant.vatNumber, "merchant.vatNumber");
+    }
+    const address = requireObject(merchant.registeredAddress, "merchant.registeredAddress");
+    requireText(address.address1, "merchant.registeredAddress.address1");
+    if (address.address2 !== undefined) {
+        requireText(address.address2, "merchant.registeredAddress.address2");
+    }
+    requireText(address.city, "merchant.registeredAddress.city");
+    requireText(address.postalCode, "merchant.registeredAddress.postalCode");
+    requireCountryCode(address.countryCode, "merchant.registeredAddress.countryCode");
+    requireText(candidate.displayName, "displayName");
+    requireEmail(candidate.orderNotificationEmail, "orderNotificationEmail");
+    requireTimeZone(candidate.timeZone, "timeZone");
+    requireCountryCode(candidate.storefrontCountryCode, "storefrontCountryCode");
+    if (candidate.loadEnvFile !== undefined &&
+        typeof candidate.loadEnvFile !== "boolean") {
+        fail("loadEnvFile", "a boolean");
+    }
+}

package/dist/utils/discover-plugin-features.d.ts

@@ -0,0 +1,28 @@
+import type { MedusaContainer } from "@medusajs/framework/types";
+import type { PluginFeatureDescriptor, PluginSettingsFallback } from "../public/types";
+export type RegisteredModule = {
+    key: string;
+    service: unknown;
+};
+/** A discovered declaring module service. */
+export type PluginFeatureProviderEntry = {
+    module_key: string;
+    descriptor: PluginFeatureDescriptor;
+    service: unknown;
+};
+/** Every module listed in medusa-config that is registered in the container. */
+export declare function listRegisteredModules(container: MedusaContainer): RegisteredModule[];
+/**
+ * Finds every registered module whose service declares `pluginFeatures`.
+ * Fails closed: an invalid or duplicate declaration is `UNEXPECTED_STATE`.
+ */
+export declare function discoverPluginFeatureDescriptors(container: MedusaContainer): PluginFeatureDescriptor[];
+/** Like `discoverPluginFeatureDescriptors`, with the declaring service. */
+export declare function discoverPluginFeatureProviders(container: MedusaContainer): PluginFeatureProviderEntry[];
+export declare function findPluginFeatureDescriptor(container: MedusaContainer, pluginKey: string): PluginFeatureDescriptor | undefined;
+export declare function findPluginFeatureProvider(container: MedusaContainer, pluginKey: string): PluginFeatureProviderEntry | undefined;
+/**
+ * The medusa-config fallback a provider exposes as `pluginSettingsFallback`.
+ * Read on every call, since a service may compute it lazily.
+ */
+export declare function readPluginSettingsFallback(provider: PluginFeatureProviderEntry): PluginSettingsFallback | undefined;