@hartl-services/medusa-base 0.2.0 → 0.4.0

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

@@ -0,0 +1,90 @@
+export const texts = {
+    menu: {
+        label: "Hartl Services Plugins",
+    },
+    page: {
+        title: "Hartl Services Plugins",
+        description: "Plugins ein- oder ausschalten und öffnen, um Funktionen, Einstellungen und Aktionen zu verwalten. Änderungen gelten sofort; abgeschaltete Funktionen sind im Shop nicht erreichbar.",
+    },
+    states: {
+        loading: "Plugins werden geladen…",
+        error: "Plugins konnten nicht geladen werden.",
+        empty: "Keine Plugins mit Funktionsschaltern installiert.",
+        retry: "Erneut laden",
+        notFound: "Dieses Plugin ist nicht installiert.",
+    },
+    plugin: {
+        switchLabel: (label) => `${label} aktiv`,
+        open: "Öffnen",
+        openLabel: (label) => `${label} öffnen`,
+    },
+    chips: {
+        enabled: "aktiv",
+        disabled: "aus",
+        configured: "konfiguriert",
+        notConfigured: (labels) => `nicht konfiguriert: ${labels}`,
+    },
+    detail: {
+        back: "Zurück zu Hartl Services Plugins",
+    },
+    sections: {
+        features: "Funktionen",
+        settings: "Einstellungen",
+        actions: "Aktionen",
+    },
+    hints: {
+        pluginDisabled: "Das Plugin ist ausgeschaltet. Alle Funktionen sind inaktiv, ihre Einstellungen bleiben erhalten.",
+        parentDisabled: (parentLabel) => `Inaktiv, solange „${parentLabel}“ ausgeschaltet ist.`,
+        saving: "Wird gespeichert…",
+    },
+    gate: {
+        disabled: "Diese Funktion ist unter Einstellungen → Hartl Services Plugins ausgeschaltet.",
+        disabledNamed: (label) => `„${label}“ ist unter Einstellungen → Hartl Services Plugins ausgeschaltet.`,
+        openHub: "Zu Hartl Services Plugins",
+    },
+    settings: {
+        missing: (labels) => `Nicht konfiguriert: ${labels}`,
+        save: "Einstellungen speichern",
+        secretPlaceholder: "gesetzt",
+        secretClear: "Löschen",
+        secretClearPending: "Wird beim Speichern gelöscht; danach gilt der Wert aus der Konfiguration, falls vorhanden.",
+        secretClearUndo: "Nicht löschen",
+        secretClearLabel: (label) => `${label} löschen`,
+        secretClearUndoLabel: (label) => `${label} nicht löschen`,
+        invalidates: (labels) => `Beim Ändern muss ${labels} neu eingegeben werden.`,
+        required: "Pflichtfeld",
+        invalidNumber: "Bitte eine gültige Zahl eingeben.",
+        outOfRange: "Der Wert liegt außerhalb des erlaubten Bereichs.",
+        numberMin: (min) => `Mindestens ${min}.`,
+        numberMax: (max) => `Höchstens ${max}.`,
+        numberRange: (min, max) => `Zwischen ${min} und ${max}.`,
+        selectPlaceholder: "Bitte auswählen",
+        clearHint: "Ein leeres Feld speichern entfernt den gespeicherten Wert (dann gilt Konfiguration oder Standard).",
+        source: {
+            stored: "gespeichert",
+            config: "aus Konfiguration",
+            default: "Standard",
+            none: "nicht gesetzt",
+        },
+    },
+    actions: {
+        confirmTitle: (label) => `${label}?`,
+        confirm: "Ausführen",
+        cancel: "Abbrechen",
+        runningSince: (time) => `läuft seit ${time}`,
+        lastCompleted: (time) => `Zuletzt erfolgreich: ${time}`,
+        lastFailed: (time) => `Zuletzt fehlgeschlagen: ${time}`,
+    },
+    toasts: {
+        saved: "Einstellung wurde gespeichert.",
+        saveFailed: "Einstellung konnte nicht gespeichert werden.",
+        conflict: "Die Einstellungen wurden zwischenzeitlich geändert und neu geladen.",
+        actionCompleted: (label) => `„${label}“ wurde ausgeführt.`,
+        actionStarted: (label) => `„${label}“ wurde gestartet und läuft im Hintergrund.`,
+        actionFailed: (label) => `„${label}“ ist fehlgeschlagen.`,
+        actionAlreadyRunning: (label) => `„${label}“ läuft bereits; der Fortschritt wird angezeigt.`,
+    },
+    errors: {
+        unknown: "Unbekannter Fehler",
+    },
+};

package/dist/admin-components/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Entry of `@hartl-services/medusa-base/admin-components` (built by
+ * `tsconfig.admin-components.json` into `dist/admin-components`). Not an
+ * Admin extension: routes and widgets live in `routes/`.
+ *
+ * Other plugins compose these into their own Admin page. Everything here
+ * uses the host Admin's React, React Query, React Router and `@medusajs/ui`.
+ */
+export { PluginPageShell } from "./features/plugin-features/components/PluginPageShell";
+export { PluginFeatureSections } from "./features/plugin-features/components/PluginFeatureSections";
+export { PluginFeatureDisabledNotice, PluginFeatureGate, } from "./features/plugin-features/components/PluginFeatureGate";
+export { usePluginFeature } from "./features/plugin-features/hooks/usePluginFeatures";
+export { usePluginFeatureEnabled, type PluginFeatureEnabledState, } from "./features/plugin-features/hooks/usePluginFeatureEnabled";
+export { pluginFeatureKeys } from "./features/plugin-features/queries/pluginFeatureKeys";

package/dist/admin-components/index.js

@@ -0,0 +1,14 @@
+/**
+ * Entry of `@hartl-services/medusa-base/admin-components` (built by
+ * `tsconfig.admin-components.json` into `dist/admin-components`). Not an
+ * Admin extension: routes and widgets live in `routes/`.
+ *
+ * Other plugins compose these into their own Admin page. Everything here
+ * uses the host Admin's React, React Query, React Router and `@medusajs/ui`.
+ */
+export { PluginPageShell } from "./features/plugin-features/components/PluginPageShell";
+export { PluginFeatureSections } from "./features/plugin-features/components/PluginFeatureSections";
+export { PluginFeatureDisabledNotice, PluginFeatureGate, } from "./features/plugin-features/components/PluginFeatureGate";
+export { usePluginFeature } from "./features/plugin-features/hooks/usePluginFeatures";
+export { usePluginFeatureEnabled, } from "./features/plugin-features/hooks/usePluginFeatureEnabled";
+export { pluginFeatureKeys } from "./features/plugin-features/queries/pluginFeatureKeys";

package/dist/admin-components/lib/errors.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Extracts a human-readable message from an unknown thrown value / failed
+ * response. Returns `undefined` when nothing usable is found so callers can
+ * fall back to a localized "unknown error" string instead of a hard-coded one.
+ */
+export declare const getErrorMessage: (error: unknown) => string | undefined;

package/dist/admin-components/lib/errors.js

@@ -0,0 +1,27 @@
+/**
+ * Extracts a human-readable message from an unknown thrown value / failed
+ * response. Returns `undefined` when nothing usable is found so callers can
+ * fall back to a localized "unknown error" string instead of a hard-coded one.
+ */
+export const getErrorMessage = (error) => {
+    if (error instanceof Error && error.message) {
+        return error.message;
+    }
+    if (typeof error !== "object" || error === null) {
+        return undefined;
+    }
+    const candidate = error;
+    for (const value of [
+        candidate.response?.data?.message,
+        candidate.response?.data?.error,
+        candidate.body?.message,
+        candidate.body?.error,
+        candidate.message,
+        candidate.statusText,
+    ]) {
+        if (typeof value === "string" && value.trim()) {
+            return value;
+        }
+    }
+    return undefined;
+};

package/dist/admin-components/lib/sdk.d.ts

@@ -0,0 +1,2 @@
+import Medusa from "@medusajs/js-sdk";
+export declare const sdk: Medusa;

package/dist/admin-components/lib/sdk.js

@@ -0,0 +1,13 @@
+import Medusa from "@medusajs/js-sdk";
+// The Admin's vite build defines these globals; `typeof` keeps the module
+// loadable where they are not defined (e.g. unit tests).
+export const sdk = new Medusa({
+    baseUrl: (typeof __BACKEND_URL__ === "undefined" ? undefined : __BACKEND_URL__) ?? "/",
+    auth: {
+        type: (typeof __AUTH_TYPE__ === "undefined" ? undefined : __AUTH_TYPE__) ??
+            "session",
+        jwtTokenStorageKey: (typeof __JWT_TOKEN_STORAGE_KEY__ === "undefined"
+            ? undefined
+            : __JWT_TOKEN_STORAGE_KEY__) || undefined,
+    },
+});

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/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>;

package/dist/public/descriptor.js

@@ -4,10 +4,190 @@ exports.validatePluginFeatureDescriptor = validatePluginFeatureDescriptor;
 exports.definePluginFeatures = definePluginFeatures;
 const utils_1 = require("@medusajs/framework/utils");
 const KEY_PATTERN = /^[a-z][a-z0-9_]{0,62}$/;
+const SETTING_TYPES = new Set([
+    "string",
+    "url",
+    "number",
+    "boolean",
+    "secret",
+    "select",
+]);
+const ACTION_MODES = new Set(["sync", "background"]);
+const ADMIN_PAGE_PREFIX = "/settings/hartl-services/";
+const BASE_PAGE_PREFIX = "/settings/hartl-services/plugin/";
+const ADMIN_PAGE_PATTERN = /^\/settings\/hartl-services(\/[a-z0-9][a-z0-9_-]*)+$/;
+const isHttpUrl = (value) => {
+    try {
+        const url = new URL(value);
+        return url.protocol === "http:" || url.protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+};
 const invalid = (pluginKey, message) => new utils_1.MedusaError(utils_1.MedusaError.Types.INVALID_DATA, `Ungültige Funktionsschalter für Plugin "${pluginKey}": ${message}`);
+const hasText = (value) => typeof value === "string" && value.trim().length > 0;
+const defaultMatchesType = (setting) => {
+    const value = setting.default;
+    switch (setting.type) {
+        case "string":
+            return hasText(value);
+        case "url":
+            return typeof value === "string" && isHttpUrl(value);
+        case "number":
+            return typeof value === "number" && Number.isFinite(value);
+        case "boolean":
+            return typeof value === "boolean";
+        case "select":
+            return (typeof value === "string" &&
+                (setting.options ?? []).some((option) => option.value === value));
+        default:
+            return false;
+    }
+};
+const withinBounds = (setting) => typeof setting.default !== "number" ||
+    ((setting.min === undefined || setting.default >= setting.min) &&
+        (setting.max === undefined || setting.default <= setting.max));
+const isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
+/** `options` only (and required) for select, `min`/`max` only for number. */
+const validateTypeExtras = (pluginKey, setting) => {
+    if (setting.type === "select") {
+        const options = setting.options;
+        if (!Array.isArray(options) || options.length === 0) {
+            throw invalid(pluginKey, `Auswahl "${setting.key}" braucht mindestens eine Option.`);
+        }
+        const values = new Set();
+        for (const option of options) {
+            if (!hasText(option?.value) || !hasText(option?.label)) {
+                throw invalid(pluginKey, `Auswahl "${setting.key}" hat eine Option ohne value oder label.`);
+            }
+            if (values.has(option.value)) {
+                throw invalid(pluginKey, `Auswahl "${setting.key}" hat die Option "${option.value}" doppelt.`);
+            }
+            values.add(option.value);
+        }
+    }
+    else if (setting.options !== undefined) {
+        throw invalid(pluginKey, `Einstellung "${setting.key}": options gibt es nur bei "select".`);
+    }
+    if (setting.type !== "number") {
+        if (setting.min !== undefined || setting.max !== undefined) {
+            throw invalid(pluginKey, `Einstellung "${setting.key}": min/max gibt es nur bei "number".`);
+        }
+        return;
+    }
+    for (const [name, bound] of [
+        ["min", setting.min],
+        ["max", setting.max],
+    ]) {
+        if (bound !== undefined && !isFiniteNumber(bound)) {
+            throw invalid(pluginKey, `Einstellung "${setting.key}": ${name} muss eine endliche Zahl sein.`);
+        }
+    }
+    if (setting.min !== undefined &&
+        setting.max !== undefined &&
+        setting.min > setting.max) {
+        throw invalid(pluginKey, `Einstellung "${setting.key}": min ist größer als max.`);
+    }
+};
+/**
+ * `invalidates` lists secrets of the same plugin that a change of this
+ * setting deletes (e.g. an API key that must not go to a new URL).
+ */
+const validateInvalidates = (pluginKey, setting, settings) => {
+    const invalidates = setting.invalidates;
+    if (invalidates === undefined) {
+        return;
+    }
+    if (!Array.isArray(invalidates) || invalidates.length === 0) {
+        throw invalid(pluginKey, `Einstellung "${setting.key}": invalidates muss eine nicht-leere Liste sein.`);
+    }
+    const seen = new Set();
+    for (const key of invalidates) {
+        const target = settings.find((candidate) => candidate.key === key);
+        if (typeof key !== "string" || !target || target.type !== "secret") {
+            throw invalid(pluginKey, `Einstellung "${setting.key}": invalidates nennt "${String(key)}", das keine geheime Einstellung dieses Plugins ist.`);
+        }
+        if (key === setting.key || seen.has(key)) {
+            throw invalid(pluginKey, `Einstellung "${setting.key}": invalidates nennt "${key}" doppelt oder sich selbst.`);
+        }
+        seen.add(key);
+    }
+};
+const validateSettings = (pluginKey, settings) => {
+    const seen = new Set();
+    for (const setting of settings) {
+        if (!KEY_PATTERN.test(setting.key)) {
+            throw invalid(pluginKey, `Einstellungs-Key "${setting.key}" hat ein ungültiges Format.`);
+        }
+        if (seen.has(setting.key)) {
+            throw invalid(pluginKey, `Einstellungs-Key "${setting.key}" ist doppelt.`);
+        }
+        seen.add(setting.key);
+        if (!hasText(setting.label)) {
+            throw invalid(pluginKey, `Einstellung "${setting.key}" hat kein label.`);
+        }
+        if (!SETTING_TYPES.has(setting.type)) {
+            throw invalid(pluginKey, `Einstellung "${setting.key}" hat einen unbekannten Typ.`);
+        }
+        if (setting.required !== undefined && typeof setting.required !== "boolean") {
+            throw invalid(pluginKey, `Einstellung "${setting.key}": required muss boolean sein.`);
+        }
+        validateTypeExtras(pluginKey, setting);
+        validateInvalidates(pluginKey, setting, settings);
+        if (setting.default === undefined) {
+            continue;
+        }
+        if (setting.type === "secret") {
+            throw invalid(pluginKey, `Geheime Einstellung "${setting.key}" darf keinen Standardwert haben.`);
+        }
+        if (!defaultMatchesType(setting)) {
+            throw invalid(pluginKey, `Standardwert von Einstellung "${setting.key}" passt nicht zum Typ "${setting.type}".`);
+        }
+        if (!withinBounds(setting)) {
+            throw invalid(pluginKey, `Standardwert von Einstellung "${setting.key}" liegt außerhalb von min/max.`);
+        }
+    }
+};
+const validateActions = (pluginKey, actions) => {
+    const seen = new Set();
+    for (const action of actions) {
+        if (!KEY_PATTERN.test(action.key)) {
+            throw invalid(pluginKey, `Aktions-Key "${action.key}" hat ein ungültiges Format.`);
+        }
+        if (seen.has(action.key)) {
+            throw invalid(pluginKey, `Aktions-Key "${action.key}" ist doppelt.`);
+        }
+        seen.add(action.key);
+        if (!hasText(action.label)) {
+            throw invalid(pluginKey, `Aktion "${action.key}" hat kein label.`);
+        }
+        if (!hasText(action.workflow_id)) {
+            throw invalid(pluginKey, `Aktion "${action.key}" hat keine workflow_id.`);
+        }
+        if (!ACTION_MODES.has(action.mode)) {
+            throw invalid(pluginKey, `Aktion "${action.key}" hat einen unbekannten Modus.`);
+        }
+        if (action.confirm !== undefined && !hasText(action.confirm)) {
+            throw invalid(pluginKey, `Aktion "${action.key}": confirm ist leer.`);
+        }
+    }
+};
+const validateAdminPage = (pluginKey, path) => {
+    if (path === undefined) {
+        return;
+    }
+    if (typeof path !== "string" ||
+        !path.startsWith(ADMIN_PAGE_PREFIX) ||
+        path.startsWith(BASE_PAGE_PREFIX) ||
+        !ADMIN_PAGE_PATTERN.test(path)) {
+        throw invalid(pluginKey, `admin_page "${String(path)}" muss unter "${ADMIN_PAGE_PREFIX}<plugin>" liegen und darf nicht mit "${BASE_PAGE_PREFIX}" beginnen.`);
+    }
+};
 /**
  * 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`.
  */
 function validatePluginFeatureDescriptor(descriptor) {
     const pluginKey = String(descriptor.plugin_key);
@@ -17,6 +197,17 @@ function validatePluginFeatureDescriptor(descriptor) {
     if (typeof descriptor.label !== "string" || !descriptor.label.trim()) {
         throw invalid(pluginKey, "label fehlt.");
     }
+    if (descriptor.switchable !== undefined &&
+        typeof descriptor.switchable !== "boolean") {
+        throw invalid(pluginKey, "switchable muss boolean sein.");
+    }
+    if (descriptor.default_enabled !== undefined &&
+        typeof descriptor.default_enabled !== "boolean") {
+        throw invalid(pluginKey, "default_enabled muss boolean sein.");
+    }
+    if (descriptor.switchable === false && descriptor.default_enabled === false) {
+        throw invalid(pluginKey, "Ein nicht abschaltbares Plugin (switchable: false) kann nicht default_enabled: false haben.");
+    }
     const byKey = new Map();
     for (const feature of descriptor.features) {
         if (!KEY_PATTERN.test(feature.key)) {
@@ -28,6 +219,9 @@ function validatePluginFeatureDescriptor(descriptor) {
         if (typeof feature.label !== "string" || !feature.label.trim()) {
             throw invalid(pluginKey, `Feature "${feature.key}" hat kein label.`);
         }
+        if (typeof feature.default_enabled !== "boolean") {
+            throw invalid(pluginKey, `Feature "${feature.key}": default_enabled muss boolean sein.`);
+        }
         byKey.set(feature.key, feature);
     }
     for (const feature of descriptor.features) {
@@ -42,6 +236,9 @@ function validatePluginFeatureDescriptor(descriptor) {
             throw invalid(pluginKey, `Feature "${feature.key}" ist zu tief verschachtelt; erlaubt ist eine Ebene.`);
         }
     }
+    validateSettings(pluginKey, descriptor.settings ?? []);
+    validateActions(pluginKey, descriptor.actions ?? []);
+    validateAdminPage(pluginKey, descriptor.admin_page);
 }
 /**
  * Declares a plugin's feature switches. Validates at import time so a broken

package/dist/public/effective-features.d.ts

@@ -12,7 +12,8 @@ export type PluginFeatureStates = {
     features: PluginFeatureState[];
 };
 /**
- * Configured and effective values of every declared feature.
+ * Configured and effective values of every declared feature. A descriptor
+ * with `switchable: false` is always enabled.
  * `effective(f) = pluginEnabled && configured(f) && effective(parent(f))`.
  * Stored keys the descriptor no longer declares are ignored; declared keys
  * without a stored value fall back to their default.

package/dist/public/effective-features.js

@@ -5,15 +5,19 @@ exports.resolveEffectivePluginFeatures = resolveEffectivePluginFeatures;
 exports.validateFeatureUpdate = validateFeatureUpdate;
 const utils_1 = require("@medusajs/framework/utils");
 /**
- * Configured and effective values of every declared feature.
+ * Configured and effective values of every declared feature. A descriptor
+ * with `switchable: false` is always enabled.
  * `effective(f) = pluginEnabled && configured(f) && effective(parent(f))`.
  * Stored keys the descriptor no longer declares are ignored; declared keys
  * without a stored value fall back to their default.
  */
 function resolvePluginFeatureStates(descriptor, stored) {
-    const pluginEnabled = stored
-        ? stored.enabled
-        : descriptor.default_enabled ?? true;
+    // A plugin that cannot be switched off is always on, whatever is stored.
+    const pluginEnabled = descriptor.switchable === false
+        ? true
+        : stored
+            ? stored.enabled
+            : descriptor.default_enabled ?? true;
     const configured = new Map();
     for (const feature of descriptor.features) {
         const value = stored?.features[feature.key];

package/dist/public/enforcement.d.ts

@@ -6,6 +6,13 @@ import type { PluginFeatureDescriptor } from "./types";
  * several keys = all must be enabled. Read failures propagate.
  */
 export declare function isPluginFeatureEnabled<K extends string>(container: MedusaContainer, descriptor: PluginFeatureDescriptor<K>, ...keys: K[]): Promise<boolean>;
+/**
+ * Like `isPluginFeatureEnabled`, for another plugin known only by its key
+ * (no import of that plugin): finds its descriptor among the registered
+ * modules. An unknown or uninstalled plugin key is `false`, as is an
+ * undeclared feature key. Read failures propagate.
+ */
+export declare function isPluginFeatureEnabledByKey(container: MedusaContainer, pluginKey: string, ...featureKeys: string[]): Promise<boolean>;
 /**
  * Middleware for `defineMiddlewares`. A disabled plugin or feature answers
  * with `NOT_FOUND` (404); all given keys must be enabled.

package/dist/public/enforcement.js

@@ -1,15 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isPluginFeatureEnabled = isPluginFeatureEnabled;
+exports.isPluginFeatureEnabledByKey = isPluginFeatureEnabledByKey;
 exports.requirePluginFeature = requirePluginFeature;
 const utils_1 = require("@medusajs/framework/utils");
-const constants_1 = require("./constants");
-const resolveReader = (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);
-};
+const discover_plugin_features_1 = require("../utils/discover-plugin-features");
+const module_access_1 = require("./module-access");
+const resolveReader = (container) => (0, module_access_1.resolveBaseModule)(container);
 const allEnabled = (effective, keys) => effective.enabled && keys.every((key) => effective.features[key] === true);
 /**
  * For subscribers, jobs and workflow steps. No keys = plugin switch only;
@@ -19,6 +16,19 @@ async function isPluginFeatureEnabled(container, descriptor, ...keys) {
     const effective = await resolveReader(container).retrieveEffectiveFeatures(descriptor);
     return allEnabled(effective, keys);
 }
+/**
+ * Like `isPluginFeatureEnabled`, for another plugin known only by its key
+ * (no import of that plugin): finds its descriptor among the registered
+ * modules. An unknown or uninstalled plugin key is `false`, as is an
+ * undeclared feature key. Read failures propagate.
+ */
+async function isPluginFeatureEnabledByKey(container, pluginKey, ...featureKeys) {
+    const descriptor = (0, discover_plugin_features_1.findPluginFeatureDescriptor)(container, pluginKey);
+    if (!descriptor) {
+        return false;
+    }
+    return isPluginFeatureEnabled(container, descriptor, ...featureKeys);
+}
 // Keyed by the request object, so one request reads each plugin's toggles once
 // even when several gate middlewares match it.
 const requestMemo = new WeakMap();

package/dist/public/index.d.ts

@@ -1,6 +1,9 @@
 export { PLUGIN_FEATURES_MODULE } from "./constants";
 export { definePluginFeatures } from "./descriptor";
 export { resolveEffectivePluginFeatures } from "./effective-features";
-export { isPluginFeatureEnabled, requirePluginFeature } from "./enforcement";
-export type { EffectivePluginFeatures, PluginFeatureDefinition, PluginFeatureDescriptor, PluginFeatureProvider, } from "./types";
+export { isPluginFeatureEnabled, isPluginFeatureEnabledByKey, requirePluginFeature, } from "./enforcement";
+export { getPluginSettings } from "./settings";
+export { getShopMasterData, shopMasterDataDescriptor, type ResolvedShopMasterData, type ShopMasterData, type ShopMasterDataKey, } from "./shop-master-data";
+export { reportPluginActionProgress, type PluginActionProgress, } from "./action-progress";
+export type { BasePluginOptions, EffectivePluginFeatures, PluginActionDefinition, PluginActionMode, PluginActionProgressInput, PluginActionWorkflowInput, PluginFeatureDefinition, PluginFeatureDescriptor, PluginFeatureProvider, PluginSettingDefinition, PluginSettingOption, PluginSettingsFallback, PluginSettingType, PluginSettingValue, ResolvedPluginSettings, } from "./types";
 export type { CompleteCartHookDeclarations, CompleteCartHookName, CompleteCartOrderCreatedInput, CompleteCartParticipant, CompleteCartParticipantStep, CompleteCartValidateInput, } from "./complete-cart";

package/dist/public/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.requirePluginFeature = exports.isPluginFeatureEnabled = exports.resolveEffectivePluginFeatures = exports.definePluginFeatures = exports.PLUGIN_FEATURES_MODULE = void 0;
+exports.reportPluginActionProgress = exports.shopMasterDataDescriptor = exports.getShopMasterData = exports.getPluginSettings = exports.requirePluginFeature = exports.isPluginFeatureEnabledByKey = exports.isPluginFeatureEnabled = exports.resolveEffectivePluginFeatures = exports.definePluginFeatures = exports.PLUGIN_FEATURES_MODULE = void 0;
 var constants_1 = require("./constants");
 Object.defineProperty(exports, "PLUGIN_FEATURES_MODULE", { enumerable: true, get: function () { return constants_1.PLUGIN_FEATURES_MODULE; } });
 var descriptor_1 = require("./descriptor");
@@ -9,4 +9,12 @@ var effective_features_1 = require("./effective-features");
 Object.defineProperty(exports, "resolveEffectivePluginFeatures", { enumerable: true, get: function () { return effective_features_1.resolveEffectivePluginFeatures; } });
 var enforcement_1 = require("./enforcement");
 Object.defineProperty(exports, "isPluginFeatureEnabled", { enumerable: true, get: function () { return enforcement_1.isPluginFeatureEnabled; } });
+Object.defineProperty(exports, "isPluginFeatureEnabledByKey", { enumerable: true, get: function () { return enforcement_1.isPluginFeatureEnabledByKey; } });
 Object.defineProperty(exports, "requirePluginFeature", { enumerable: true, get: function () { return enforcement_1.requirePluginFeature; } });
+var settings_1 = require("./settings");
+Object.defineProperty(exports, "getPluginSettings", { enumerable: true, get: function () { return settings_1.getPluginSettings; } });
+var shop_master_data_1 = require("./shop-master-data");
+Object.defineProperty(exports, "getShopMasterData", { enumerable: true, get: function () { return shop_master_data_1.getShopMasterData; } });
+Object.defineProperty(exports, "shopMasterDataDescriptor", { enumerable: true, get: function () { return shop_master_data_1.shopMasterDataDescriptor; } });
+var action_progress_1 = require("./action-progress");
+Object.defineProperty(exports, "reportPluginActionProgress", { enumerable: true, get: function () { return action_progress_1.reportPluginActionProgress; } });

package/dist/public/module-access.d.ts

@@ -0,0 +1,3 @@
+import type { MedusaContainer } from "@medusajs/framework/types";
+/** Resolves the base module or fails with a clear `UNEXPECTED_STATE`. */
+export declare const resolveBaseModule: <T>(container: MedusaContainer) => T;