@hartl-services/medusa-base 0.1.0

package/README.md

@@ -0,0 +1,166 @@
+# Medusa Base
+
+Medusa v2.19 base plugin for Hartl Services shops. Every shop installs it. It
+provides per-plugin feature toggles: a generic Admin page under
+**Settings → Hartl Services Plugins**, a Store endpoint for storefronts and
+helpers that plugins use to enforce their toggles.
+
+## What it does
+
+- Discovers every registered module whose service declares `pluginFeatures`
+  (see below). No plugin has to register itself anywhere else.
+- Stores one row per plugin in `plugin_feature_state` (module
+  `plugin_features`): the plugin switch, the configured feature values and a
+  `version` for optimistic concurrency.
+- Serves the effective values to storefronts and the configured plus effective
+  values to the Admin.
+- Exports `definePluginFeatures`, `requirePluginFeature` and
+  `isPluginFeatureEnabled` from `@hartl-services/medusa-base` for plugins.
+
+## Installation in a shop
+
+```bash
+pnpm add @hartl-services/medusa-base @hartl-services/medusa-food-supplements-contracts
+```
+
+```ts
+// medusa-config.ts
+plugins: [
+  // First in the list: other plugins read their toggles through it.
+  {
+    resolve: "@hartl-services/medusa-base",
+    options: {},
+  },
+  // … all other plugins
+]
+```
+
+The plugin has no options. Run `medusa db:migrate` after installing it.
+
+Peer dependencies are the host's Medusa 2.19 packages (`@medusajs/framework`,
+`@medusajs/medusa`, `@medusajs/admin-sdk`, `@medusajs/js-sdk`, `@medusajs/ui`)
+plus React, React Router and TanStack Query in the versions the Medusa 2.19
+dashboard uses.
+
+## HTTP endpoints
+
+| Method | Path | Auth | Response |
+|---|---|---|---|
+| `GET` | `/store/plugin-features` | publishable key | `StorePluginFeaturesListResponse` |
+| `GET` | `/store/plugin-features/:plugin_key` | publishable key | `StorePluginFeaturesResponse`, 404 for an unknown plugin |
+| `GET` | `/admin/plugin-features` | Admin user | `AdminPluginFeaturesListResponse` |
+| `POST` | `/admin/plugin-features` | Admin user | `AdminPluginFeaturesResponse` |
+
+Every authenticated Admin user may change the toggles (no RBAC by design).
+`POST` takes `{ plugin_key, expected_version, enabled, features }`; `features`
+holds configured values for declared keys, missing keys keep their default and
+an unknown key is 400. An unknown `plugin_key` is 404, a stale
+`expected_version` is 409.
+
+Store values are effective values only; a storefront uses them to hide
+features. DTOs, schemas and paths come from the Contracts package:
+
+```ts
+import type { StorePluginFeaturesListResponse } from "@hartl-services/medusa-food-supplements-contracts/types/plugin-features-store"
+import { pluginFeaturesStorePaths } from "@hartl-services/medusa-food-supplements-contracts/paths/plugin-features"
+
+const { plugins } = await sdk.client.fetch<StorePluginFeaturesListResponse>(
+  pluginFeaturesStorePaths.get.list,
+  { method: "GET" }
+)
+```
+
+## Declaring features in a plugin
+
+A plugin depends on `@hartl-services/medusa-base` (peer dependency), declares
+its features once and exposes the declaration as `pluginFeatures` on its
+module service:
+
+```ts
+// src/plugin-features.ts
+import { definePluginFeatures } from "@hartl-services/medusa-base"
+
+export const demoPluginFeatures = definePluginFeatures({
+  plugin_key: "demo",
+  label: "Demo-Plugin",
+  // default_enabled: true, // plugin switch default
+  features: [
+    { key: "coupons", label: "Gutscheine", default_enabled: true },
+    {
+      key: "coupons_self_service",
+      label: "Gutscheine selbst verwalten",
+      default_enabled: false,
+      parent_key: "coupons",
+    },
+  ],
+})
+
+// src/modules/demo/service.ts
+class DemoModuleService extends MedusaService({ /* models */ }) {
+  readonly pluginFeatures = demoPluginFeatures
+}
+```
+
+Keys match `^[a-z][a-z0-9_]{0,62}$`, feature keys are unique, a `parent_key`
+must exist and only one nesting level is allowed. `definePluginFeatures`
+throws at import time otherwise.
+
+### Gating routes
+
+Put gate entries at the start of the plugin's `routes` array. An entry without
+`methods` is a prefix match and runs before every method-specific middleware:
+
+```ts
+// src/api/middlewares.ts
+import { requirePluginFeature } from "@hartl-services/medusa-base"
+
+export default defineMiddlewares({
+  routes: [
+    { matcher: "/store/demo", middlewares: [requirePluginFeature(demoPluginFeatures)] },
+    {
+      matcher: "/store/demo/coupons",
+      middlewares: [requirePluginFeature(demoPluginFeatures, "coupons")],
+    },
+    // … existing entries unchanged
+  ],
+})
+```
+
+A disabled plugin or feature answers 404. With several keys, all must be
+enabled. The toggles are read once per request.
+
+### Gating subscribers and jobs
+
+Return early:
+
+```ts
+import { isPluginFeatureEnabled } from "@hartl-services/medusa-base"
+
+if (!(await isPluginFeatureEnabled(container, demoPluginFeatures, "coupons"))) {
+  return
+}
+```
+
+A read failure throws, so the subscriber or job is retried. A missing base
+plugin fails with `UNEXPECTED_STATE` ("@hartl-services/medusa-base ist nicht in
+medusa-config registriert.").
+
+### Never on the cart path
+
+Code on the cart and checkout hot path (cart middlewares, cart workflow hooks,
+`orderCreated` handling, cart subscribers) must never read toggles. It stays
+fail-safe and independent of the database state of this plugin. Toggles
+control visibility and reachability of features, not the integrity of
+existing data.
+
+## Semantics
+
+- No stored row: every value is its declared default, `version` is 0.
+- `effective(feature) = plugin enabled && configured(feature) && effective(parent)`.
+  Turning a parent off turns its children off; their configured values stay.
+  Turning the plugin off turns every feature off.
+- Stored values for keys a plugin no longer declares are ignored; a feature
+  added later uses its default until it is saved.
+- Updates are optimistic: `expected_version` 0 creates the row, any other
+  value updates exactly that version. A concurrent change answers 409; the
+  Admin page reloads and shows a notice.

package/dist/public/constants.d.ts

@@ -0,0 +1,2 @@
+/** Container key of the base plugin's module (`Module("plugin_features", …)`). */
+export declare const PLUGIN_FEATURES_MODULE: "plugin_features";

package/dist/public/constants.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLUGIN_FEATURES_MODULE = void 0;
+/** Container key of the base plugin's module (`Module("plugin_features", …)`). */
+exports.PLUGIN_FEATURES_MODULE = "plugin_features";

package/dist/public/descriptor.d.ts

@@ -0,0 +1,11 @@
+import type { PluginFeatureDescriptor } from "./types";
+/**
+ * Checks key format, unique feature keys, existing parents and the single
+ * allowed nesting level. 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>;

package/dist/public/descriptor.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validatePluginFeatureDescriptor = validatePluginFeatureDescriptor;
+exports.definePluginFeatures = definePluginFeatures;
+const utils_1 = require("@medusajs/framework/utils");
+const KEY_PATTERN = /^[a-z][a-z0-9_]{0,62}$/;
+const invalid = (pluginKey, message) => new utils_1.MedusaError(utils_1.MedusaError.Types.INVALID_DATA, `Ungültige Funktionsschalter für Plugin "${pluginKey}": ${message}`);
+/**
+ * Checks key format, unique feature keys, existing parents and the single
+ * allowed nesting level. Throws `INVALID_DATA`.
+ */
+function validatePluginFeatureDescriptor(descriptor) {
+    const pluginKey = String(descriptor.plugin_key);
+    if (!KEY_PATTERN.test(pluginKey)) {
+        throw invalid(pluginKey, "plugin_key hat ein ungültiges Format.");
+    }
+    if (typeof descriptor.label !== "string" || !descriptor.label.trim()) {
+        throw invalid(pluginKey, "label fehlt.");
+    }
+    const byKey = new Map();
+    for (const feature of descriptor.features) {
+        if (!KEY_PATTERN.test(feature.key)) {
+            throw invalid(pluginKey, `Feature-Key "${feature.key}" hat ein ungültiges Format.`);
+        }
+        if (byKey.has(feature.key)) {
+            throw invalid(pluginKey, `Feature-Key "${feature.key}" ist doppelt.`);
+        }
+        if (typeof feature.label !== "string" || !feature.label.trim()) {
+            throw invalid(pluginKey, `Feature "${feature.key}" hat kein label.`);
+        }
+        byKey.set(feature.key, feature);
+    }
+    for (const feature of descriptor.features) {
+        if (feature.parent_key === undefined) {
+            continue;
+        }
+        const parent = byKey.get(feature.parent_key);
+        if (!parent || parent.key === feature.key) {
+            throw invalid(pluginKey, `Parent "${feature.parent_key}" von Feature "${feature.key}" existiert nicht.`);
+        }
+        if (parent.parent_key !== undefined) {
+            throw invalid(pluginKey, `Feature "${feature.key}" ist zu tief verschachtelt; erlaubt ist eine Ebene.`);
+        }
+    }
+}
+/**
+ * Declares a plugin's feature switches. Validates at import time so a broken
+ * declaration fails the boot instead of a request.
+ */
+function definePluginFeatures(descriptor) {
+    validatePluginFeatureDescriptor(descriptor);
+    return descriptor;
+}

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

@@ -0,0 +1,28 @@
+import type { EffectivePluginFeatures, PluginFeatureDefinition, PluginFeatureDescriptor, StoredPluginFeatures } from "./types";
+export type PluginFeatureState = {
+    definition: PluginFeatureDefinition;
+    /** Configured value: stored or default. */
+    enabled: boolean;
+    /** After the plugin switch and the parent rule. */
+    effective_enabled: boolean;
+};
+export type PluginFeatureStates = {
+    /** Configured plugin switch: stored or default. */
+    enabled: boolean;
+    features: PluginFeatureState[];
+};
+/**
+ * Configured and effective values of every declared feature.
+ * `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.
+ */
+export declare function resolvePluginFeatureStates(descriptor: PluginFeatureDescriptor, stored: StoredPluginFeatures | null): PluginFeatureStates;
+/** Pure rule shared by service and tests. `stored === null` means no row. */
+export declare function resolveEffectivePluginFeatures(descriptor: PluginFeatureDescriptor, stored: StoredPluginFeatures | null): EffectivePluginFeatures;
+/**
+ * Rejects configured values for keys the descriptor does not declare and
+ * returns the values to persist (declared keys only; missing keys keep their
+ * default).
+ */
+export declare function validateFeatureUpdate(descriptor: PluginFeatureDescriptor, features: Record<string, boolean>): Record<string, boolean>;

package/dist/public/effective-features.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolvePluginFeatureStates = resolvePluginFeatureStates;
+exports.resolveEffectivePluginFeatures = resolveEffectivePluginFeatures;
+exports.validateFeatureUpdate = validateFeatureUpdate;
+const utils_1 = require("@medusajs/framework/utils");
+/**
+ * Configured and effective values of every declared feature.
+ * `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;
+    const configured = new Map();
+    for (const feature of descriptor.features) {
+        const value = stored?.features[feature.key];
+        configured.set(feature.key, typeof value === "boolean" ? value : feature.default_enabled);
+    }
+    const effective = (feature) => {
+        if (!pluginEnabled || configured.get(feature.key) !== true) {
+            return false;
+        }
+        if (feature.parent_key === undefined) {
+            return true;
+        }
+        // Validated descriptors allow one nesting level, so the parent is a root.
+        return configured.get(feature.parent_key) === true;
+    };
+    return {
+        enabled: pluginEnabled,
+        features: descriptor.features.map((definition) => ({
+            definition,
+            enabled: configured.get(definition.key) === true,
+            effective_enabled: effective(definition),
+        })),
+    };
+}
+/** Pure rule shared by service and tests. `stored === null` means no row. */
+function resolveEffectivePluginFeatures(descriptor, stored) {
+    const states = resolvePluginFeatureStates(descriptor, stored);
+    const features = {};
+    for (const state of states.features) {
+        features[state.definition.key] = state.effective_enabled;
+    }
+    return {
+        plugin_key: descriptor.plugin_key,
+        enabled: states.enabled,
+        features,
+    };
+}
+/**
+ * Rejects configured values for keys the descriptor does not declare and
+ * returns the values to persist (declared keys only; missing keys keep their
+ * default).
+ */
+function validateFeatureUpdate(descriptor, features) {
+    const declared = new Set(descriptor.features.map((feature) => feature.key));
+    const unknown = Object.keys(features).filter((key) => !declared.has(key));
+    if (unknown.length) {
+        throw new utils_1.MedusaError(utils_1.MedusaError.Types.INVALID_DATA, `Unbekannte Funktionsschalter für Plugin "${descriptor.plugin_key}": ${unknown.join(", ")}.`);
+    }
+    const result = {};
+    for (const feature of descriptor.features) {
+        const value = features[feature.key];
+        if (typeof value === "boolean") {
+            result[feature.key] = value;
+        }
+    }
+    return result;
+}

package/dist/public/enforcement.d.ts

@@ -0,0 +1,13 @@
+import type { MedusaRequestHandler } from "@medusajs/framework/http";
+import type { MedusaContainer } from "@medusajs/framework/types";
+import type { PluginFeatureDescriptor } from "./types";
+/**
+ * For subscribers, jobs and workflow steps. No keys = plugin switch only;
+ * 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>;
+/**
+ * Middleware for `defineMiddlewares`. A disabled plugin or feature answers
+ * with `NOT_FOUND` (404); all given keys must be enabled.
+ */
+export declare function requirePluginFeature<K extends string>(descriptor: PluginFeatureDescriptor<K>, ...keys: K[]): MedusaRequestHandler;

package/dist/public/enforcement.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPluginFeatureEnabled = isPluginFeatureEnabled;
+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 allEnabled = (effective, keys) => effective.enabled && keys.every((key) => effective.features[key] === true);
+/**
+ * For subscribers, jobs and workflow steps. No keys = plugin switch only;
+ * several keys = all must be enabled. Read failures propagate.
+ */
+async function isPluginFeatureEnabled(container, descriptor, ...keys) {
+    const effective = await resolveReader(container).retrieveEffectiveFeatures(descriptor);
+    return allEnabled(effective, keys);
+}
+// 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();
+const effectiveForRequest = (req, descriptor) => {
+    let perRequest = requestMemo.get(req);
+    if (!perRequest) {
+        perRequest = new Map();
+        requestMemo.set(req, perRequest);
+    }
+    let pending = perRequest.get(descriptor.plugin_key);
+    if (!pending) {
+        pending = resolveReader(req.scope).retrieveEffectiveFeatures(descriptor);
+        perRequest.set(descriptor.plugin_key, pending);
+    }
+    return pending;
+};
+/**
+ * Middleware for `defineMiddlewares`. A disabled plugin or feature answers
+ * with `NOT_FOUND` (404); all given keys must be enabled.
+ */
+function requirePluginFeature(descriptor, ...keys) {
+    return async (req, _res, next) => {
+        const effective = await effectiveForRequest(req, descriptor);
+        if (!allEnabled(effective, keys)) {
+            throw new utils_1.MedusaError(utils_1.MedusaError.Types.NOT_FOUND, "Diese Funktion ist in diesem Shop nicht aktiviert.");
+        }
+        next();
+    };
+}

package/dist/public/index.d.ts

@@ -0,0 +1,5 @@
+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";

package/dist/public/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requirePluginFeature = 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");
+Object.defineProperty(exports, "definePluginFeatures", { enumerable: true, get: function () { return descriptor_1.definePluginFeatures; } });
+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, "requirePluginFeature", { enumerable: true, get: function () { return enforcement_1.requirePluginFeature; } });

package/dist/public/types.d.ts

@@ -0,0 +1,29 @@
+export type PluginFeatureDefinition<K extends string = string> = {
+    readonly key: K;
+    readonly label: string;
+    readonly description?: string;
+    readonly default_enabled: boolean;
+    readonly parent_key?: K;
+};
+export type PluginFeatureDescriptor<K extends string = string> = {
+    readonly plugin_key: string;
+    readonly label: string;
+    readonly description?: string;
+    /** Plugin switch default, `true` when omitted. */
+    readonly default_enabled?: boolean;
+    readonly features: readonly PluginFeatureDefinition<K>[];
+};
+/** Implemented by a plugin's module service so the base can discover it. */
+export interface PluginFeatureProvider {
+    readonly pluginFeatures: PluginFeatureDescriptor;
+}
+export type EffectivePluginFeatures = {
+    plugin_key: string;
+    enabled: boolean;
+    features: Record<string, boolean>;
+};
+/** Configured values as persisted by the base module; `null` = no row. */
+export type StoredPluginFeatures = {
+    enabled: boolean;
+    features: Record<string, boolean>;
+};

package/dist/public/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@hartl-services/medusa-base",
+  "version": "0.1.0",
+  "description": "Base plugin for Hartl Services Medusa shops: per-plugin feature toggles with a generic Admin settings page, a Store endpoint for storefronts, and enforcement helpers for plugin routes, subscribers and jobs.",
+  "license": "MIT",
+  "files": [
+    ".medusa/server",
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/hartl-services-gmbh/services/food-supplements-e-commerce.git",
+    "directory": "plugins/base"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "sideEffects": [
+    "./.medusa/**"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/public/index.d.ts",
+      "import": "./dist/public/index.js",
+      "require": "./dist/public/index.js"
+    },
+    "./.medusa/server/src/modules/*": "./.medusa/server/src/modules/*/index.js",
+    "./.medusa/server/src/*": "./.medusa/server/src/*",
+    "./admin": {
+      "import": "./.medusa/server/src/admin/index.mjs",
+      "require": "./.medusa/server/src/admin/index.js"
+    }
+  },
+  "peerDependencies": {
+    "@medusajs/admin-sdk": "^2.19.0",
+    "@medusajs/framework": "^2.19.0",
+    "@medusajs/js-sdk": "^2.19.0",
+    "@medusajs/medusa": "^2.19.0",
+    "@medusajs/ui": "^4.2.1",
+    "@tanstack/react-query": "^5.64.2",
+    "react": "^18.3.1",
+    "react-router-dom": "^7.18.2"
+  },
+  "dependencies": {
+    "@hartl-services/medusa-food-supplements-contracts": "^0.10.0"
+  },
+  "devDependencies": {
+    "@medusajs/admin-sdk": "2.19.0",
+    "@medusajs/cli": "2.19.0",
+    "@medusajs/framework": "2.19.0",
+    "@medusajs/js-sdk": "2.19.0",
+    "@medusajs/medusa": "2.19.0",
+    "@medusajs/ui": "4.2.1",
+    "@swc/core": "^1.7.28",
+    "@swc/jest": "^0.2.39",
+    "@tanstack/react-query": "5.64.2",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^20.12.11",
+    "@types/react": "^18.3.2",
+    "@types/react-dom": "^18.2.25",
+    "jest": "^29.7.0",
+    "react": "^18.3.1",
+    "react-router-dom": "7.18.2",
+    "typescript": "^5.6.2",
+    "vite": "7.3.6",
+    "yalc": "^1.0.0-pre.53"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "medusa plugin:build && tsc -p tsconfig.public.json",
+    "dev": "medusa plugin:develop",
+    "typecheck": "tsc --noEmit",
+    "pretest:unit": "pnpm --filter @hartl-services/medusa-food-supplements-contracts build",
+    "test:unit": "jest"
+  }
+}