@hartl-services/medusa-base 0.3.0 → 0.4.0

package/dist/public/module-access.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveBaseModule = void 0;
+const utils_1 = require("@medusajs/framework/utils");
+const constants_1 = require("./constants");
+/** Resolves the base module or fails with a clear `UNEXPECTED_STATE`. */
+const resolveBaseModule = (container) => {
+    if (!container.hasRegistration(constants_1.PLUGIN_FEATURES_MODULE)) {
+        throw new utils_1.MedusaError(utils_1.MedusaError.Types.UNEXPECTED_STATE, "@hartl-services/medusa-base ist nicht in medusa-config registriert.");
+    }
+    return container.resolve(constants_1.PLUGIN_FEATURES_MODULE);
+};
+exports.resolveBaseModule = resolveBaseModule;

package/dist/public/settings.d.ts

@@ -0,0 +1,11 @@
+import type { MedusaContainer } from "@medusajs/framework/types";
+import type { PluginFeatureDescriptor, PluginSettingsFallback, ResolvedPluginSettings } from "./types";
+/**
+ * Current settings of a plugin for server-side code (subscribers, workflow
+ * steps, jobs, scripts, module services via the global container). Secrets
+ * are DECRYPTED; never send the result to a client. Precedence per key:
+ * stored in the Admin > `fallback` (medusa-config) > declared default.
+ * A missing base plugin fails with `UNEXPECTED_STATE`; read failures
+ * propagate.
+ */
+export declare function getPluginSettings<K extends string, S extends string, A extends string>(container: MedusaContainer, descriptor: PluginFeatureDescriptor<K, S, A>, fallback?: PluginSettingsFallback<S>): Promise<ResolvedPluginSettings<S>>;

package/dist/public/settings.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPluginSettings = getPluginSettings;
+const module_access_1 = require("./module-access");
+/**
+ * Current settings of a plugin for server-side code (subscribers, workflow
+ * steps, jobs, scripts, module services via the global container). Secrets
+ * are DECRYPTED; never send the result to a client. Precedence per key:
+ * stored in the Admin > `fallback` (medusa-config) > declared default.
+ * A missing base plugin fails with `UNEXPECTED_STATE`; read failures
+ * propagate.
+ */
+async function getPluginSettings(container, descriptor, fallback) {
+    const resolved = await (0, module_access_1.resolveBaseModule)(container).resolvePluginSettings(descriptor, fallback);
+    return resolved;
+}

package/dist/public/shop-master-data.d.ts

@@ -0,0 +1,25 @@
+import type { MedusaContainer } from "@medusajs/framework/types";
+import type { PluginSettingsFallback } from "./types";
+/**
+ * The base's own descriptor: the shop's master data (Firmenangaben), edited
+ * on the generic plugin page like any plugin's settings. It cannot be
+ * switched off and declares no features.
+ */
+export declare const shopMasterDataDescriptor: import("./types").PluginFeatureDescriptor<string, "legal_name" | "address_line1" | "address_line2" | "postal_code" | "city" | "country_code" | "vat_number" | "email" | "phone" | "website" | "iban" | "bic" | "company_register_number" | "company_register_court", never>;
+/** Keys of the shop master data settings. */
+export type ShopMasterDataKey = "legal_name" | "address_line1" | "address_line2" | "postal_code" | "city" | "country_code" | "vat_number" | "email" | "phone" | "website" | "iban" | "bic" | "company_register_number" | "company_register_court";
+/** Every key that has a value (stored > fallback). All values are strings. */
+export type ShopMasterData = Partial<Record<ShopMasterDataKey, string>>;
+export type ResolvedShopMasterData = {
+    values: ShopMasterData;
+    /** Every required field has a value. */
+    configured: boolean;
+    /** Required keys without a value. */
+    missing: ShopMasterDataKey[];
+};
+/**
+ * The shop's master data for server-side code. Precedence per key: stored in
+ * the Admin > `fallback` (e.g. a plugin's own medusa-config option). A
+ * missing base plugin fails with `UNEXPECTED_STATE`; read failures propagate.
+ */
+export declare function getShopMasterData(container: MedusaContainer, fallback?: PluginSettingsFallback<ShopMasterDataKey>): Promise<ResolvedShopMasterData>;

package/dist/public/shop-master-data.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shopMasterDataDescriptor = void 0;
+exports.getShopMasterData = getShopMasterData;
+const descriptor_1 = require("./descriptor");
+const settings_1 = require("./settings");
+/**
+ * The base's own descriptor: the shop's master data (Firmenangaben), edited
+ * on the generic plugin page like any plugin's settings. It cannot be
+ * switched off and declares no features.
+ */
+exports.shopMasterDataDescriptor = (0, descriptor_1.definePluginFeatures)({
+    plugin_key: "shop",
+    label: "Shop-Stammdaten",
+    description: "Firmenangaben des Shops für Rechnungen, Dokumente und Steuerprüfungen.",
+    switchable: false,
+    features: [],
+    settings: [
+        { key: "legal_name", label: "Firmenname", type: "string", required: true },
+        { key: "address_line1", label: "Adresse", type: "string", required: true },
+        { key: "address_line2", label: "Adresszusatz", type: "string" },
+        { key: "postal_code", label: "Postleitzahl", type: "string", required: true },
+        { key: "city", label: "Ort", type: "string", required: true },
+        {
+            key: "country_code",
+            label: "Land",
+            type: "select",
+            required: true,
+            // EU-27 plus CH, GB, NO, IS, LI (ISO 3166-1 alpha-2, lowercase),
+            // sorted by German label.
+            options: [
+                { value: "be", label: "Belgien" },
+                { value: "bg", label: "Bulgarien" },
+                { value: "dk", label: "Dänemark" },
+                { value: "de", label: "Deutschland" },
+                { value: "ee", label: "Estland" },
+                { value: "fi", label: "Finnland" },
+                { value: "fr", label: "Frankreich" },
+                { value: "gr", label: "Griechenland" },
+                { value: "ie", label: "Irland" },
+                { value: "is", label: "Island" },
+                { value: "it", label: "Italien" },
+                { value: "hr", label: "Kroatien" },
+                { value: "lv", label: "Lettland" },
+                { value: "li", label: "Liechtenstein" },
+                { value: "lt", label: "Litauen" },
+                { value: "lu", label: "Luxemburg" },
+                { value: "mt", label: "Malta" },
+                { value: "nl", label: "Niederlande" },
+                { value: "no", label: "Norwegen" },
+                { value: "at", label: "Österreich" },
+                { value: "pl", label: "Polen" },
+                { value: "pt", label: "Portugal" },
+                { value: "ro", label: "Rumänien" },
+                { value: "se", label: "Schweden" },
+                { value: "ch", label: "Schweiz" },
+                { value: "sk", label: "Slowakei" },
+                { value: "si", label: "Slowenien" },
+                { value: "es", label: "Spanien" },
+                { value: "cz", label: "Tschechien" },
+                { value: "hu", label: "Ungarn" },
+                { value: "gb", label: "Vereinigtes Königreich" },
+                { value: "cy", label: "Zypern" },
+            ],
+        },
+        { key: "vat_number", label: "UID-Nummer", type: "string", required: true },
+        { key: "email", label: "E-Mail", type: "string" },
+        { key: "phone", label: "Telefon", type: "string" },
+        { key: "website", label: "Website", type: "url" },
+        { key: "iban", label: "IBAN", type: "string" },
+        { key: "bic", label: "BIC", type: "string" },
+        { key: "company_register_number", label: "Firmenbuchnummer", type: "string" },
+        { key: "company_register_court", label: "Firmenbuchgericht", type: "string" },
+    ],
+});
+/**
+ * The shop's master data for server-side code. Precedence per key: stored in
+ * the Admin > `fallback` (e.g. a plugin's own medusa-config option). A
+ * missing base plugin fails with `UNEXPECTED_STATE`; read failures propagate.
+ */
+async function getShopMasterData(container, fallback) {
+    const resolved = await (0, settings_1.getPluginSettings)(container, exports.shopMasterDataDescriptor, fallback);
+    const values = {};
+    for (const [key, value] of Object.entries(resolved.values)) {
+        if (typeof value === "string") {
+            values[key] = value;
+        }
+    }
+    return {
+        values,
+        configured: resolved.configured,
+        missing: resolved.missing,
+    };
+}

package/dist/public/types.d.ts

@@ -1,3 +1,12 @@
+/** Options of the base plugin (`plugins: [{ resolve, options }]`). */
+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;
+};
 export type PluginFeatureDefinition<K extends string = string> = {
     readonly key: K;
     readonly label: string;
@@ -5,17 +14,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 +94,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/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;

package/dist/utils/discover-plugin-features.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listRegisteredModules = listRegisteredModules;
+exports.discoverPluginFeatureDescriptors = discoverPluginFeatureDescriptors;
+exports.discoverPluginFeatureProviders = discoverPluginFeatureProviders;
+exports.findPluginFeatureDescriptor = findPluginFeatureDescriptor;
+exports.findPluginFeatureProvider = findPluginFeatureProvider;
+exports.readPluginSettingsFallback = readPluginSettingsFallback;
+const utils_1 = require("@medusajs/framework/utils");
+const descriptor_1 = require("../public/descriptor");
+// Keyed by the app's config object: stable for the process lifetime, unlike
+// `req.scope`, which is a new scope per request.
+const discovered = new WeakMap();
+const registeredModules = (container, configModule) => Object.keys(configModule.modules ?? {})
+    .filter((moduleKey) => container.hasRegistration(moduleKey))
+    .map((moduleKey) => ({
+    key: moduleKey,
+    service: container.resolve(moduleKey),
+}));
+/** Every module listed in medusa-config that is registered in the container. */
+function listRegisteredModules(container) {
+    return registeredModules(container, container.resolve(utils_1.ContainerRegistrationKeys.CONFIG_MODULE));
+}
+const readDescriptor = (service) => service !== null && typeof service === "object" && "pluginFeatures" in service
+    ? service.pluginFeatures
+    : undefined;
+const discover = (container) => {
+    const configModule = container.resolve(utils_1.ContainerRegistrationKeys.CONFIG_MODULE);
+    const memo = discovered.get(configModule);
+    if (memo) {
+        return memo;
+    }
+    const byPluginKey = new Map();
+    for (const { key: moduleKey, service } of registeredModules(container, configModule)) {
+        const candidate = readDescriptor(service);
+        if (candidate === undefined) {
+            continue;
+        }
+        const descriptor = candidate;
+        try {
+            (0, descriptor_1.validatePluginFeatureDescriptor)(descriptor);
+        }
+        catch (error) {
+            throw new utils_1.MedusaError(utils_1.MedusaError.Types.UNEXPECTED_STATE, `Modul "${moduleKey}" deklariert ungültige Funktionsschalter: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (byPluginKey.has(descriptor.plugin_key)) {
+            throw new utils_1.MedusaError(utils_1.MedusaError.Types.UNEXPECTED_STATE, `Plugin-Key "${descriptor.plugin_key}" wird von mehreren Modulen deklariert.`);
+        }
+        byPluginKey.set(descriptor.plugin_key, {
+            module_key: moduleKey,
+            descriptor,
+            service,
+        });
+    }
+    const providers = [...byPluginKey.values()].sort((left, right) => left.descriptor.plugin_key.localeCompare(right.descriptor.plugin_key));
+    const result = {
+        providers,
+        descriptors: providers.map((provider) => provider.descriptor),
+    };
+    discovered.set(configModule, result);
+    return result;
+};
+/**
+ * Finds every registered module whose service declares `pluginFeatures`.
+ * Fails closed: an invalid or duplicate declaration is `UNEXPECTED_STATE`.
+ */
+function discoverPluginFeatureDescriptors(container) {
+    return discover(container).descriptors;
+}
+/** Like `discoverPluginFeatureDescriptors`, with the declaring service. */
+function discoverPluginFeatureProviders(container) {
+    return discover(container).providers;
+}
+function findPluginFeatureDescriptor(container, pluginKey) {
+    return findPluginFeatureProvider(container, pluginKey)?.descriptor;
+}
+function findPluginFeatureProvider(container, pluginKey) {
+    return discover(container).providers.find((provider) => provider.descriptor.plugin_key === pluginKey);
+}
+/**
+ * The medusa-config fallback a provider exposes as `pluginSettingsFallback`.
+ * Read on every call, since a service may compute it lazily.
+ */
+function readPluginSettingsFallback(provider) {
+    const service = provider.service;
+    if (service === null ||
+        typeof service !== "object" ||
+        !("pluginSettingsFallback" in service)) {
+        return undefined;
+    }
+    const fallback = service
+        .pluginSettingsFallback;
+    return fallback !== null && typeof fallback === "object"
+        ? fallback
+        : undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hartl-services/medusa-base",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Base plugin for Hartl Services Medusa shops: per-plugin feature toggles with a generic Admin settings page, a Store endpoint for storefronts, enforcement helpers, the complete-cart hook composition, and the Sentry logger wrapper.",
   "license": "MIT",
   "files": [
@@ -33,6 +33,10 @@
       "import": "./dist/public/sentry-logger.js",
       "require": "./dist/public/sentry-logger.js"
     },
+    "./admin-components": {
+      "types": "./dist/admin-components/index.d.ts",
+      "import": "./dist/admin-components/index.js"
+    },
     "./.medusa/server/src/modules/*": "./.medusa/server/src/modules/*/index.js",
     "./.medusa/server/src/*": "./.medusa/server/src/*",
     "./admin": {
@@ -52,7 +56,7 @@
     "react-router-dom": "^7.18.2"
   },
   "dependencies": {
-    "@hartl-services/medusa-food-supplements-contracts": "^0.11.0"
+    "@hartl-services/medusa-food-supplements-contracts": "^0.12.0"
   },
   "devDependencies": {
     "@medusajs/admin-sdk": "2.19.0",
@@ -85,7 +89,7 @@
     }
   },
   "scripts": {
-    "build": "medusa plugin:build && tsc -p tsconfig.public.json",
+    "build": "medusa plugin:build && tsc -p tsconfig.public.json && tsc -p tsconfig.admin-components.json",
     "dev": "medusa plugin:develop",
     "typecheck": "tsc --noEmit",
     "pretest:unit": "pnpm --filter @hartl-services/medusa-food-supplements-contracts build",