@hartl-services/medusa-base 2.6.0 → 2.7.0

package/dist/public/descriptor.js

@@ -4,6 +4,7 @@ exports.validatePluginFeatureDescriptor = validatePluginFeatureDescriptor;
 exports.definePluginFeatures = definePluginFeatures;
 const utils_1 = require("@medusajs/framework/utils");
 const lib_1 = require("../shared/lib");
+const plugin_icons_1 = require("./plugin-icons");
 const KEY_PATTERN = /^[a-z][a-z0-9_]{0,62}$/;
 const SETTING_TYPES = new Set([
     "string",
@@ -20,6 +21,10 @@ 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 ICON_NAMES = new Set(plugin_icons_1.PLUGIN_ICON_NAMES);
+const SETTING_WIDTHS = new Set(["full", "half"]);
+/** Types an input placeholder makes no sense for. */
+const NO_PLACEHOLDER_TYPES = new Set(["boolean", "select", "image", "color"]);
 const invalid = (pluginKey, message) => new utils_1.MedusaError(utils_1.MedusaError.Types.INVALID_DATA, `Ungültige Funktionsschalter für Plugin "${pluginKey}": ${message}`);
 const defaultMatchesType = (setting) => {
     const value = setting.default;
@@ -32,7 +37,9 @@ const defaultMatchesType = (setting) => {
         case "color":
             return typeof value === "string" && HEX_COLOR_PATTERN.test(value);
         case "number":
-            return typeof value === "number" && Number.isFinite(value);
+            return (typeof value === "number" &&
+                Number.isFinite(value) &&
+                (setting.integer !== true || Number.isInteger(value)));
         case "boolean":
             return typeof value === "boolean";
         case "select":
@@ -46,7 +53,10 @@ 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. */
+/**
+ * `options` only (and required) for select, `min`/`max`/`integer` only for
+ * number.
+ */
 const validateTypeExtras = (pluginKey, setting) => {
     if (setting.type === "select") {
         const options = setting.options;
@@ -68,11 +78,16 @@ const validateTypeExtras = (pluginKey, setting) => {
         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".`);
+        if (setting.min !== undefined ||
+            setting.max !== undefined ||
+            setting.integer !== undefined) {
+            throw invalid(pluginKey, `Einstellung "${setting.key}": min/max/integer gibt es nur bei "number".`);
         }
         return;
     }
+    if (setting.integer !== undefined && typeof setting.integer !== "boolean") {
+        throw invalid(pluginKey, `Einstellung "${setting.key}": integer muss boolean sein.`);
+    }
     for (const [name, bound] of [
         ["min", setting.min],
         ["max", setting.max],
@@ -111,6 +126,28 @@ const validateInvalidates = (pluginKey, setting, settings) => {
         seen.add(key);
     }
 };
+/** `hint`, `placeholder`, `section` and `width` of one setting. */
+const validateDisplayFields = (pluginKey, setting) => {
+    for (const name of ["hint", "placeholder", "section"]) {
+        const value = setting[name];
+        if (value !== undefined && !(0, lib_1.isNonEmptyString)(value)) {
+            throw invalid(pluginKey, `Einstellung "${setting.key}": ${name} muss ein nicht-leerer Text sein.`);
+        }
+    }
+    if (setting.placeholder !== undefined && NO_PLACEHOLDER_TYPES.has(setting.type)) {
+        throw invalid(pluginKey, `Einstellung "${setting.key}": placeholder gibt es nicht bei "${setting.type}".`);
+    }
+    const width = setting.width;
+    if (width === undefined) {
+        return;
+    }
+    if (typeof width !== "string" || !SETTING_WIDTHS.has(width)) {
+        throw invalid(pluginKey, `Einstellung "${setting.key}": width muss "full" oder "half" sein.`);
+    }
+    if (setting.type === "boolean") {
+        throw invalid(pluginKey, `Einstellung "${setting.key}": width gibt es nicht bei "boolean".`);
+    }
+};
 const validateSettings = (pluginKey, settings) => {
     const seen = new Set();
     for (const setting of settings) {
@@ -134,6 +171,7 @@ const validateSettings = (pluginKey, settings) => {
             throw invalid(pluginKey, `Einstellung "${setting.key}": required muss boolean sein.`);
         }
         validateTypeExtras(pluginKey, setting);
+        validateDisplayFields(pluginKey, setting);
         validateInvalidates(pluginKey, setting, settings);
         if (setting.default === undefined) {
             continue;
@@ -184,6 +222,78 @@ const validateAdminPage = (pluginKey, path) => {
         throw invalid(pluginKey, `admin_page "${String(path)}" muss unter "${ADMIN_PAGE_PREFIX}<plugin>" liegen und darf nicht mit "${BASE_PAGE_PREFIX}" beginnen.`);
     }
 };
+/**
+ * Metadata per settings group: unique names, each used by a setting's
+ * `group`, `requires_feature` a declared feature key.
+ */
+const validateSettingGroups = (pluginKey, groups, settings, featureKeys) => {
+    if (groups === undefined) {
+        return;
+    }
+    if (!Array.isArray(groups)) {
+        throw invalid(pluginKey, "setting_groups muss eine Liste sein.");
+    }
+    const usedGroups = new Set(settings.map((setting) => setting.group));
+    const seen = new Set();
+    for (const group of groups) {
+        if (!(0, lib_1.isNonEmptyString)(group?.name)) {
+            throw invalid(pluginKey, "Eine Einstellungsgruppe hat keinen name.");
+        }
+        if (seen.has(group.name)) {
+            throw invalid(pluginKey, `Einstellungsgruppe "${group.name}" ist doppelt.`);
+        }
+        seen.add(group.name);
+        if (!usedGroups.has(group.name)) {
+            throw invalid(pluginKey, `Einstellungsgruppe "${group.name}" wird von keiner Einstellung verwendet.`);
+        }
+        for (const name of ["description", "note"]) {
+            if (group[name] !== undefined && !(0, lib_1.isNonEmptyString)(group[name])) {
+                throw invalid(pluginKey, `Einstellungsgruppe "${group.name}": ${name} muss ein nicht-leerer Text sein.`);
+            }
+        }
+        if (group.requires_feature !== undefined &&
+            !featureKeys.has(group.requires_feature)) {
+            throw invalid(pluginKey, `Einstellungsgruppe "${group.name}": requires_feature "${String(group.requires_feature)}" ist kein Feature dieses Plugins.`);
+        }
+    }
+};
+/** Optional texts and icon of the plugin's Admin page. */
+const validatePresentation = (pluginKey, descriptor) => {
+    const icon = descriptor.icon;
+    if (icon !== undefined && (typeof icon !== "string" || !ICON_NAMES.has(icon))) {
+        throw invalid(pluginKey, `icon "${String(icon)}" ist kein bekannter Icon-Name.`);
+    }
+    for (const name of [
+        "summary",
+        "disable_hint",
+        "disable_confirm",
+        "features_heading",
+        "features_note",
+        "all_off_warning",
+    ]) {
+        const value = descriptor[name];
+        if (value !== undefined && !(0, lib_1.isNonEmptyString)(value)) {
+            throw invalid(pluginKey, `${name} muss ein nicht-leerer Text sein.`);
+        }
+    }
+    if (descriptor.switchable === false &&
+        (descriptor.disable_hint !== undefined ||
+            descriptor.disable_confirm !== undefined)) {
+        throw invalid(pluginKey, "disable_hint und disable_confirm gibt es nur bei abschaltbaren Plugins.");
+    }
+    if (descriptor.all_off_warning !== undefined && descriptor.features.length === 0) {
+        throw invalid(pluginKey, "all_off_warning braucht mindestens ein Feature.");
+    }
+    const requireEnabled = descriptor.require_enabled_feature;
+    if (requireEnabled !== undefined) {
+        if (requireEnabled !== true) {
+            throw invalid(pluginKey, "require_enabled_feature muss true sein.");
+        }
+        if (!descriptor.features.some((feature) => feature.parent_key === undefined && feature.default_enabled)) {
+            throw invalid(pluginKey, "require_enabled_feature braucht mindestens ein Feature ohne parent_key mit default_enabled: true.");
+        }
+    }
+};
 /**
  * Checks key format, unique feature keys, existing parents and the single
  * allowed nesting level, plus the optional settings, actions and Admin page.
@@ -236,7 +346,9 @@ function validatePluginFeatureDescriptor(descriptor) {
             throw invalid(pluginKey, `Feature "${feature.key}" ist zu tief verschachtelt; erlaubt ist eine Ebene.`);
         }
     }
+    validatePresentation(pluginKey, descriptor);
     validateSettings(pluginKey, descriptor.settings ?? []);
+    validateSettingGroups(pluginKey, descriptor.setting_groups, descriptor.settings ?? [], new Set(byKey.keys()));
     validateActions(pluginKey, descriptor.actions ?? []);
     validateAdminPage(pluginKey, descriptor.admin_page);
 }

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

@@ -27,3 +27,13 @@ export declare function resolveEffectivePluginFeatures(descriptor: PluginFeature
  * default).
  */
 export declare function validateFeatureUpdate(descriptor: PluginFeatureDescriptor, features: Record<string, boolean>): Record<string, boolean>;
+/**
+ * For a descriptor with `require_enabled_feature`: rejects (`INVALID_DATA`)
+ * an update that switches off the last enabled top-level feature. `features`
+ * are the values to persist (`validateFeatureUpdate`; a key without a value
+ * counts by its default), `current` the configured values before the update
+ * (`resolvePluginFeatureStates`). An update that does not reduce the enabled
+ * set is always allowed, so an already stored all-off state can be left and
+ * the plugin switch can be flipped with unchanged features.
+ */
+export declare function assertRequiredFeatureEnabled(descriptor: PluginFeatureDescriptor, features: Record<string, boolean>, current: Record<string, boolean>): void;

package/dist/public/effective-features.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolvePluginFeatureStates = resolvePluginFeatureStates;
 exports.resolveEffectivePluginFeatures = resolveEffectivePluginFeatures;
 exports.validateFeatureUpdate = validateFeatureUpdate;
+exports.assertRequiredFeatureEnabled = assertRequiredFeatureEnabled;
 const utils_1 = require("@medusajs/framework/utils");
 /**
  * Configured and effective values of every declared feature. A descriptor
@@ -75,3 +76,23 @@ function validateFeatureUpdate(descriptor, features) {
     }
     return result;
 }
+/**
+ * For a descriptor with `require_enabled_feature`: rejects (`INVALID_DATA`)
+ * an update that switches off the last enabled top-level feature. `features`
+ * are the values to persist (`validateFeatureUpdate`; a key without a value
+ * counts by its default), `current` the configured values before the update
+ * (`resolvePluginFeatureStates`). An update that does not reduce the enabled
+ * set is always allowed, so an already stored all-off state can be left and
+ * the plugin switch can be flipped with unchanged features.
+ */
+function assertRequiredFeatureEnabled(descriptor, features, current) {
+    if (descriptor.require_enabled_feature !== true) {
+        return;
+    }
+    const topLevel = descriptor.features.filter((feature) => feature.parent_key === undefined);
+    const anyOnAfter = topLevel.some((feature) => (features[feature.key] ?? feature.default_enabled) === true);
+    const anyOnBefore = topLevel.some((feature) => current[feature.key] === true);
+    if (!anyOnAfter && anyOnBefore) {
+        throw new utils_1.MedusaError(utils_1.MedusaError.Types.INVALID_DATA, "Mindestens eine Funktion muss eingeschaltet bleiben.");
+    }
+}

package/dist/public/index.d.ts

@@ -3,8 +3,9 @@ export { definePluginFeatures } from "./descriptor";
 export { resolveEffectivePluginFeatures } from "./effective-features";
 export { isOwnPluginEvent, isPluginFeatureEnabled, isPluginFeatureEnabledByKey, pluginFeatureGate, requirePluginFeature, } from "./enforcement";
 export { isBasePluginRegistered, resolveBaseModule } from "./module-access";
+export { PLUGIN_ICON_NAMES } from "./plugin-icons";
 export { getPluginSettings } from "./settings";
 export { getShopAppearance, getShopMasterData, shopMasterDataDescriptor, type ResolvedShopMasterData, type ShopAppearance, type ShopAppearanceColors, 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 { BasePluginOptions, EffectivePluginFeatures, PluginActionDefinition, PluginActionMode, PluginActionProgressInput, PluginActionWorkflowInput, PluginFeatureDefinition, PluginFeatureDescriptor, PluginFeatureProvider, PluginIconName, PluginSettingDefinition, PluginSettingGroupDefinition, 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.reportPluginActionProgress = exports.shopMasterDataDescriptor = exports.getShopMasterData = exports.getShopAppearance = exports.getPluginSettings = exports.resolveBaseModule = exports.isBasePluginRegistered = exports.requirePluginFeature = exports.pluginFeatureGate = exports.isPluginFeatureEnabledByKey = exports.isPluginFeatureEnabled = exports.isOwnPluginEvent = exports.resolveEffectivePluginFeatures = exports.definePluginFeatures = exports.PLUGIN_FEATURES_MODULE = void 0;
+exports.reportPluginActionProgress = exports.shopMasterDataDescriptor = exports.getShopMasterData = exports.getShopAppearance = exports.getPluginSettings = exports.PLUGIN_ICON_NAMES = exports.resolveBaseModule = exports.isBasePluginRegistered = exports.requirePluginFeature = exports.pluginFeatureGate = exports.isPluginFeatureEnabledByKey = exports.isPluginFeatureEnabled = exports.isOwnPluginEvent = 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");
@@ -16,6 +16,8 @@ Object.defineProperty(exports, "requirePluginFeature", { enumerable: true, get:
 var module_access_1 = require("./module-access");
 Object.defineProperty(exports, "isBasePluginRegistered", { enumerable: true, get: function () { return module_access_1.isBasePluginRegistered; } });
 Object.defineProperty(exports, "resolveBaseModule", { enumerable: true, get: function () { return module_access_1.resolveBaseModule; } });
+var plugin_icons_1 = require("./plugin-icons");
+Object.defineProperty(exports, "PLUGIN_ICON_NAMES", { enumerable: true, get: function () { return plugin_icons_1.PLUGIN_ICON_NAMES; } });
 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");

package/dist/public/plugin-icons.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Names of `@medusajs/icons` components a plugin descriptor may use as `icon`.
+ * A plain list so the server needs no icon package; the Admin maps the name to
+ * the component and falls back to a default icon for an unknown one. Every
+ * name is an export of `@medusajs/icons`.
+ */
+export declare const PLUGIN_ICON_NAMES: readonly ["ArchiveBox", "ArrowPath", "BuildingStorefront", "Buildings", "ClockSolid", "CogSixTooth", "CreditCard", "DocumentText", "Envelope", "ReceiptPercent", "ShieldCheck", "ShoppingCart", "SquaresPlus", "Tag", "TruckFast", "Users"];

package/dist/public/plugin-icons.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLUGIN_ICON_NAMES = void 0;
+/**
+ * Names of `@medusajs/icons` components a plugin descriptor may use as `icon`.
+ * A plain list so the server needs no icon package; the Admin maps the name to
+ * the component and falls back to a default icon for an unknown one. Every
+ * name is an export of `@medusajs/icons`.
+ */
+exports.PLUGIN_ICON_NAMES = [
+    "ArchiveBox",
+    "ArrowPath",
+    "BuildingStorefront",
+    "Buildings",
+    "ClockSolid",
+    "CogSixTooth",
+    "CreditCard",
+    "DocumentText",
+    "Envelope",
+    "ReceiptPercent",
+    "ShieldCheck",
+    "ShoppingCart",
+    "SquaresPlus",
+    "Tag",
+    "TruckFast",
+    "Users",
+];

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

@@ -7,6 +7,10 @@ const descriptor_1 = require("./descriptor");
 const settings_1 = require("./settings");
 const COMPANY = "Firmendaten";
 const APPEARANCE = "Erscheinungsbild";
+const ADDRESS = "Adresse";
+const TAX_CONTACT = "Steuer und Kontakt";
+const BANK_REGISTER = "Bank und Firmenbuch";
+const COLORS = "Farben";
 const DEFAULT_COLOR_HINT = "Leer lassen für die Standardfarbe von E-Mails und Dokumenten.";
 /**
  * The base's own descriptor: the shop's master data (Firmenangaben) and its
@@ -18,18 +22,22 @@ exports.shopMasterDataDescriptor = (0, descriptor_1.definePluginFeatures)({
     plugin_key: "shop",
     label: "Shop-Stammdaten",
     description: "Firmenangaben des Shops für E-Mails, Rechnungen, Dokumente und Steuerprüfungen sowie Logo und Farben von E-Mails und Dokumenten.",
+    summary: "Firmenangaben, Logo und Farben für E-Mails, Rechnungen, Dokumente und Steuerprüfungen.",
+    icon: "Buildings",
     switchable: false,
     features: [],
     settings: [
-        { key: "legal_name", group: COMPANY, label: "Firmenname", type: "string", required: true },
-        { key: "address_line1", group: COMPANY, label: "Adresse", type: "string", required: true },
-        { key: "address_line2", group: COMPANY, label: "Adresszusatz", type: "string" },
-        { key: "postal_code", group: COMPANY, label: "Postleitzahl", type: "string", required: true },
-        { key: "city", group: COMPANY, label: "Ort", type: "string", required: true },
+        { key: "legal_name", group: COMPANY, section: ADDRESS, label: "Firmenname", type: "string", required: true },
+        { key: "address_line1", group: COMPANY, section: ADDRESS, width: "half", label: "Adresse", type: "string", required: true },
+        { key: "address_line2", group: COMPANY, section: ADDRESS, width: "half", label: "Adresszusatz", type: "string" },
+        { key: "postal_code", group: COMPANY, section: ADDRESS, width: "half", label: "Postleitzahl", type: "string", required: true },
+        { key: "city", group: COMPANY, section: ADDRESS, width: "half", label: "Ort", type: "string", required: true },
         {
             key: "country_code",
             group: COMPANY,
             label: "Land",
+            section: ADDRESS,
+            width: "half",
             type: "select",
             required: true,
             // EU-27 plus CH, GB, NO, IS, LI (ISO 3166-1 alpha-2, lowercase),
@@ -69,24 +77,27 @@ exports.shopMasterDataDescriptor = (0, descriptor_1.definePluginFeatures)({
                 { value: "cy", label: "Zypern" },
             ],
         },
-        { key: "vat_number", group: COMPANY, label: "UID-Nummer", type: "string", required: true },
-        { key: "email", group: COMPANY, label: "E-Mail", type: "string" },
-        { key: "phone", group: COMPANY, label: "Telefon", type: "string" },
-        { key: "website", group: COMPANY, label: "Website", type: "url" },
-        { key: "iban", group: COMPANY, label: "IBAN", type: "string" },
-        { key: "bic", group: COMPANY, label: "BIC", type: "string" },
-        { key: "company_register_number", group: COMPANY, label: "Firmenbuchnummer", type: "string" },
-        { key: "company_register_court", group: COMPANY, label: "Firmenbuchgericht", type: "string" },
+        { key: "vat_number", group: COMPANY, section: TAX_CONTACT, width: "half", label: "UID-Nummer", type: "string", required: true },
+        { key: "email", group: COMPANY, section: TAX_CONTACT, width: "half", label: "E-Mail", type: "string" },
+        { key: "phone", group: COMPANY, section: TAX_CONTACT, width: "half", label: "Telefon", type: "string" },
+        { key: "website", group: COMPANY, section: TAX_CONTACT, width: "half", label: "Website", type: "url" },
+        { key: "iban", group: COMPANY, section: BANK_REGISTER, width: "half", label: "IBAN", type: "string" },
+        { key: "bic", group: COMPANY, section: BANK_REGISTER, width: "half", label: "BIC", type: "string" },
+        { key: "company_register_number", group: COMPANY, section: BANK_REGISTER, width: "half", label: "Firmenbuchnummer", type: "string" },
+        { key: "company_register_court", group: COMPANY, section: BANK_REGISTER, width: "half", label: "Firmenbuchgericht", type: "string" },
         {
             key: "logo",
             group: APPEARANCE,
             label: "Logo",
             description: "PNG oder JPG, erscheint oben in den E-Mails und auf Rechnungen und Lieferscheinen. Ohne Logo steht dort der Firmenname bzw. Shopname.",
+            hint: "PNG oder JPG, ohne Logo erscheint der Firmenname.",
             type: "image",
         },
         {
             key: "color_accent",
             group: APPEARANCE,
+            section: COLORS,
+            width: "half",
             label: "Akzentfarbe",
             description: `Buttons, Überschriften und Links. ${DEFAULT_COLOR_HINT}`,
             type: "color",
@@ -94,6 +105,8 @@ exports.shopMasterDataDescriptor = (0, descriptor_1.definePluginFeatures)({
         {
             key: "color_text",
             group: APPEARANCE,
+            section: COLORS,
+            width: "half",
             label: "Textfarbe",
             description: `Fließtext und Beträge. ${DEFAULT_COLOR_HINT}`,
             type: "color",
@@ -101,6 +114,8 @@ exports.shopMasterDataDescriptor = (0, descriptor_1.definePluginFeatures)({
         {
             key: "color_muted",
             group: APPEARANCE,
+            section: COLORS,
+            width: "half",
             label: "Nebentextfarbe",
             description: `Beschriftungen, Hinweise und Fußzeilen. ${DEFAULT_COLOR_HINT}`,
             type: "color",
@@ -108,6 +123,8 @@ exports.shopMasterDataDescriptor = (0, descriptor_1.definePluginFeatures)({
         {
             key: "color_line",
             group: APPEARANCE,
+            section: COLORS,
+            width: "half",
             label: "Linienfarbe",
             description: `Rahmen und Trennlinien. ${DEFAULT_COLOR_HINT}`,
             type: "color",
@@ -115,6 +132,8 @@ exports.shopMasterDataDescriptor = (0, descriptor_1.definePluginFeatures)({
         {
             key: "color_surface",
             group: APPEARANCE,
+            section: COLORS,
+            width: "half",
             label: "Flächenfarbe",
             description: `Hinterlegte Flächen wie Infoboxen und Tabellenköpfe. ${DEFAULT_COLOR_HINT}`,
             type: "color",

package/dist/public/types.d.ts

@@ -1,6 +1,7 @@
 import type { DocumentPluginOptions } from "../modules/documents/domain/options";
 import type { EmailPluginOptions } from "../email/types";
 import type { FilesPluginOptions } from "../files/types";
+import type { PLUGIN_ICON_NAMES } from "./plugin-icons";
 /**
  * Options of the base plugin (`plugins: [{ resolve, options }]`). Medusa hands
  * the same options object to every module of the plugin; each module service
@@ -23,6 +24,8 @@ export type BasePluginOptions = {
     /** `/files` gateway signing; set from `createS3CacheStorageConfig`. */
     readonly files?: FilesPluginOptions;
 };
+/** `@medusajs/icons` component name a plugin may use as its icon. */
+export type PluginIconName = (typeof PLUGIN_ICON_NAMES)[number];
 export type PluginFeatureDefinition<K extends string = string> = {
     readonly key: K;
     readonly label: string;
@@ -53,7 +56,7 @@ export type PluginSettingDefinition<S extends string = string> = {
     readonly type: PluginSettingType;
     /** `false` when omitted. */
     readonly required?: boolean;
-    /** Never for `"secret"`; must match `type` (and `options`/`min`/`max`). */
+    /** Never for `"secret"`; must match `type` (and `options`/`min`/`max`/`integer`). */
     readonly default?: PluginSettingValue;
     /** Required for `"select"` (non-empty, unique values); only there. */
     readonly options?: readonly PluginSettingOption[];
@@ -61,12 +64,44 @@ export type PluginSettingDefinition<S extends string = string> = {
     readonly min?: number;
     /** Inclusive upper bound; only for `"number"`. */
     readonly max?: number;
+    /** Only whole numbers are accepted; only for `"number"`. */
+    readonly integer?: boolean;
     /**
      * 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[];
+    /**
+     * Short text under the field; the Admin shows `hint ?? description`.
+     */
+    readonly hint?: string;
+    /** Input placeholder; not for boolean, select, image and color. */
+    readonly placeholder?: string;
+    /**
+     * `"half"`: consecutive half-width settings share one two-column row.
+     * `"full"` when omitted. Not for boolean (always a full-width switch row).
+     */
+    readonly width?: "full" | "half";
+    /**
+     * Sub-heading inside the group; consecutive settings with the same section
+     * share one sub-heading.
+     */
+    readonly section?: string;
+};
+/** Metadata of one settings group, keyed by the `group` name of its settings. */
+export type PluginSettingGroupDefinition<K extends string = string> = {
+    /** Equals the `group` of at least one setting; unique per plugin. */
+    readonly name: string;
+    /** Explanatory text under the group heading. */
+    readonly description?: string;
+    /** Short note shown on the right of the group heading. */
+    readonly note?: string;
+    /**
+     * Feature that must be on for the group to apply; the Admin dims the group
+     * (still editable) while the feature is not effectively enabled.
+     */
+    readonly requires_feature?: K;
 };
 export type PluginActionMode = "sync" | "background";
 export type PluginActionDefinition<A extends string = string> = {
@@ -100,6 +135,33 @@ export type PluginFeatureDescriptor<K extends string = string, S extends string
      * omitted).
      */
     readonly admin_page?: string;
+    /** `@medusajs/icons` component name for the hub card and the page header. */
+    readonly icon?: PluginIconName;
+    /** One short sentence: hub card text and page subtitle (Admin falls back to `description`). */
+    readonly summary?: string;
+    /** Line under the plugin switch, e.g. what stops working when it is off. Only when switchable. */
+    readonly disable_hint?: string;
+    /** Body of the confirmation shown before the plugin is switched off. Only when switchable. */
+    readonly disable_confirm?: string;
+    /** Heading of the features card; "Funktionen" when omitted. */
+    readonly features_heading?: string;
+    /** Note on the right of the features card header. */
+    readonly features_note?: string;
+    /** Warning shown while every top-level feature is off. Needs at least one feature. */
+    readonly all_off_warning?: string;
+    /**
+     * `true`: at least one top-level feature (without `parent_key`) must stay
+     * enabled; an update that would switch all of them off is rejected with
+     * `INVALID_DATA` and the Admin locks the last enabled switch. Needs at least
+     * one top-level feature with `default_enabled: true`. Only an update that
+     * switches off the last enabled one is rejected: a stored state that already
+     * violates the rule (everything off) can still be read and left, and an
+     * update that does not reduce the enabled set (e.g. the plugin switch) is
+     * always allowed.
+     */
+    readonly require_enabled_feature?: true;
+    /** Metadata for the groups used in `settings[].group`. */
+    readonly setting_groups?: readonly PluginSettingGroupDefinition<K>[];
 };
 /** 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>>;

package/dist/shared/lib/index.d.ts

@@ -5,6 +5,7 @@ export * from "./errors";
 export * from "./hash";
 export * from "./logging";
 export * from "./money";
+export * from "./refreshing-snapshot";
 export * from "./text";
 export * from "./transaction";
 export * from "./wire-response";

package/dist/shared/lib/index.js

@@ -23,6 +23,7 @@ __exportStar(require("./errors"), exports);
 __exportStar(require("./hash"), exports);
 __exportStar(require("./logging"), exports);
 __exportStar(require("./money"), exports);
+__exportStar(require("./refreshing-snapshot"), exports);
 __exportStar(require("./text"), exports);
 __exportStar(require("./transaction"), exports);
 __exportStar(require("./wire-response"), exports);

package/dist/shared/lib/refreshing-snapshot.d.ts

@@ -0,0 +1,52 @@
+/**
+ * In-memory copy of one value for the places that cannot await it: Medusa
+ * reads some `projectConfig.http` settings synchronously on every login, and
+ * the shop preset puts a getter backed by such a copy there, so a change in
+ * the Admin takes effect without a restart.
+ *
+ * - Boot: `start` loads the value once.
+ * - Afterwards an unref'd timer refreshes every 30 s, so a change reaches an
+ *   idle instance too. A read that finds the copy older than 30 s (a blocked
+ *   timer, say) also starts one refresh in the background
+ *   (stale-while-revalidate) and still answers from the copy. A change thus
+ *   reaches a running instance within about 30 s plus the duration of the
+ *   read.
+ * - A failed read keeps the last value (initially `initial`) and is logged;
+ *   the next attempt waits another 30 s. Neither a throwing reader nor a
+ *   throwing logger escapes.
+ *
+ * The state lives on `globalThis` under a `Symbol.for(key)`: the preset
+ * (`dist`) and the Medusa-loaded plugin code (`.medusa/server`) are compiled
+ * separately and would otherwise each hold their own copy.
+ */
+export declare const SNAPSHOT_REFRESH_MS = 30000;
+export type RefreshingSnapshot<T> = Readonly<{
+    /**
+     * Registers the reader, loads the value once and keeps it fresh every 30 s
+     * (application start). `warn` is the container logger. Starting again
+     * replaces the reader and the timer. Never rejects.
+     */
+    start: (input: Readonly<{
+        read: () => Promise<T>;
+        warn: (message: string) => void;
+    }>) => Promise<void>;
+    /** Reads the value once; never rejects. Concurrent calls share one read. */
+    refresh: () => Promise<void>;
+    /** Stops the periodic refresh (application shutdown). The value stays. */
+    stop: () => void;
+    /** Synchronous; starts a background refresh when the copy is stale. Never throws. */
+    current: () => T;
+    /**
+     * Test hook: sets the value and counts as just refreshed, so it holds for
+     * 30 s without a reader; `null` forgets reader and value (back to `initial`).
+     */
+    setForTests: (value: T | null) => void;
+}>;
+export declare const createRefreshingSnapshot: <T>(options: Readonly<{
+    /** Global registry key; one key = one shared state per process. */
+    key: string;
+    /** Start and fallback value: used until the first read and after a failed one. */
+    initial: T;
+    /** What the value is, for the failure log. */
+    describe: (value: T) => string;
+}>) => RefreshingSnapshot<T>;