@hartl-services/medusa-base 0.2.0 → 0.4.0

package/README.md

@@ -1,9 +1,10 @@
 # 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.
+provides per-plugin feature toggles, runtime settings and actions: a generic
+Admin hub under **Settings → Hartl Services Plugins** with one page per
+plugin, a Store endpoint for storefronts and helpers that plugins use to
+enforce their toggles and read their settings.
 
 ## What it does
 
@@ -16,6 +17,19 @@ helpers that plugins use to enforce their toggles.
   values to the Admin.
 - Exports `definePluginFeatures`, `requirePluginFeature` and
   `isPluginFeatureEnabled` from `@hartl-services/medusa-base` for plugins.
+- Emits `plugin-features.updated.v1` after every saved Admin toggle update
+  (see "Toggle-change event").
+- Stores runtime settings that plugins declare (secrets encrypted), resolves
+  them with the medusa-config fallback and exports `getPluginSettings` (see
+  "Runtime settings").
+- Runs actions that plugins declare as workflow ids, records every run with
+  its progress and outcome and rejects a second start while one runs (see
+  "Actions").
+- Holds the shop's master data (Firmenangaben) as its own settings and
+  exports `getShopMasterData` (see "Shop-Stammdaten").
+- Exports Admin components from `@hartl-services/medusa-base/admin-components`
+  so a plugin composes the base's sections into its own page and hides
+  widgets of disabled features (see "Admin components for plugin pages").
 - Owns the `completeCartWorkflow` hooks `validate` and `orderCreated` and runs
   the workflows that plugins declare for them (see "Complete-cart hook
   composition").
@@ -32,13 +46,21 @@ plugins: [
   // First in the list: other plugins read their toggles through it.
   {
     resolve: "@hartl-services/medusa-base",
-    options: {},
+    options: {
+      // Optional: key material for secret settings (see "Secrets").
+      settingsSecret: process.env.PLUGIN_SETTINGS_SECRET,
+    },
   },
   // … all other plugins
 ]
 ```
 
-The plugin has no options. Run `medusa db:migrate` after installing it.
+The only option is `settingsSecret` (`BasePluginOptions`, optional): the key
+material for stored secret settings. Set it from an environment variable of
+the shop; unset or empty, the base uses `projectConfig.http.cookieSecret`.
+Run `medusa db:migrate` after installing it (and
+after upgrading: 0.4.0 adds the tables `plugin_setting_state` and
+`plugin_action_run`).
 
 Peer dependencies are the host's Medusa 2.19 packages (`@medusajs/framework`,
 `@medusajs/medusa`, `@medusajs/admin-sdk`, `@medusajs/js-sdk`, `@medusajs/ui`)
@@ -53,8 +75,17 @@ dashboard uses.
 | `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).
+| `GET` | `/admin/plugin-features/:plugin_key` | Admin user | `AdminPluginFeaturesResponse`, 404 for an unknown plugin |
+| `GET` | `/admin/plugin-features/:plugin_key/settings` | Admin user | `AdminPluginSettingsResponse` |
+| `POST` | `/admin/plugin-features/:plugin_key/settings` | Admin user | `AdminPluginFeaturesResponse` |
+| `POST` | `/admin/plugin-features/:plugin_key/actions/:action_key` | Admin user | `AdminPluginActionRunResponse` (200 sync, 202 background), 409 `AdminPluginActionConflictResponse` while it runs |
+| `GET` | `/admin/plugin-features/:plugin_key/actions/:action_key/runs` | Admin user | `AdminPluginActionRunsResponse` (`?limit=`, default 1, max 20) |
+
+Every authenticated Admin user may change toggles and settings and run
+actions (no RBAC by design). Admin plugin DTOs carry the toggles plus
+`settings` (with `source`, never a secret's value), `configured`, `missing`,
+`settings_version`, `actions`, `admin_page` (the plugin's own page or
+`null`) and `switchable`, so the list is one round trip for the hub.
 `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
@@ -108,6 +139,11 @@ 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.
 
+`switchable: false` declares a plugin that cannot be switched off (the
+base's own shop master data): the Admin shows no plugin switch, `enabled` is
+always `true` whatever is stored, and `POST /admin/plugin-features` with
+`enabled: false` is 400. It cannot be combined with `default_enabled: false`.
+
 ### Gating routes
 
 Put gate entries at the start of the plugin's `routes` array. An entry without
@@ -148,6 +184,43 @@ 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.").
 
+To check another plugin without importing it, use its plugin key:
+`isPluginFeatureEnabledByKey(container, "documents", "invoices")`. It finds
+the descriptor among the registered modules; an unknown or uninstalled plugin
+key (and an undeclared feature key) is `false`.
+
+### Toggle-change event
+
+After a successful `POST /admin/plugin-features` the base emits
+`PLUGIN_FEATURES_UPDATED_EVENT` (`plugin-features.updated.v1`) through the
+event bus. The payload (`PluginFeaturesUpdatedEventSchema`) carries the
+plugin's effective values after the update:
+`{ plugin_key, enabled, features: { [key]: effective }, version }`. The event
+is emitted after the write committed; a failed emit is only logged and does
+not undo the write. Direct service calls (`updatePluginFeatures`) emit
+nothing.
+
+A plugin that must react right away (instead of on its next job run)
+subscribes to it and filters on its own `plugin_key`:
+
+```ts
+import {
+  PLUGIN_FEATURES_UPDATED_EVENT,
+  PluginFeaturesUpdatedEventSchema,
+} from "@hartl-services/medusa-food-supplements-contracts/events/plugin-features"
+
+export default async function onToggleChange({ event, container }: SubscriberArgs<unknown>) {
+  const payload = PluginFeaturesUpdatedEventSchema.parse(event.data)
+  if (payload.plugin_key !== demoPluginFeatures.plugin_key) return
+  // re-read the toggles and reconcile
+}
+
+export const config: SubscriberConfig = { event: PLUGIN_FEATURES_UPDATED_EVENT }
+```
+
+Events can arrive late or twice; re-read the current toggles instead of
+trusting the payload for anything that writes.
+
 ### Never on the cart path
 
 Code on the cart and checkout hot path (cart middlewares, cart workflow hooks,
@@ -156,6 +229,310 @@ fail-safe and independent of the database state of this plugin. Toggles
 control visibility and reachability of features, not the integrity of
 existing data.
 
+## Runtime settings
+
+Configuration a plugin reads at RUN time (for example an external system's
+URL and API key) is declared in the descriptor and edited on the plugin's
+Admin page. Boot-time provider configuration (SMTP, S3, Sentry, Redis) and
+function-valued options stay in `medusa-config.ts`.
+
+```ts
+export const demoPluginFeatures = definePluginFeatures({
+  plugin_key: "demo",
+  label: "Demo-Plugin",
+  features: [],
+  settings: [
+    { key: "api_url", label: "API-URL", type: "url", required: true },
+    { key: "api_key", label: "API-Key", type: "secret", required: true },
+    { key: "collection", label: "Collection", type: "string", default: "users" },
+    { key: "batch_size", label: "Batchgröße", type: "number", min: 1, max: 500, default: 100 },
+    {
+      key: "mode",
+      label: "Modus",
+      type: "select",
+      options: [
+        { value: "live", label: "Live" },
+        { value: "test", label: "Test" },
+      ],
+      default: "test",
+    },
+  ],
+})
+
+class DemoModuleService extends MedusaService({ /* models */ }) {
+  readonly pluginFeatures = demoPluginFeatures
+  // Values the plugin received from medusa-config; shown as "aus Konfiguration".
+  readonly pluginSettingsFallback: PluginSettingsFallback<"api_url" | "api_key">
+
+  constructor(cradle: unknown, options?: DemoOptions) {
+    super(...arguments)
+    this.pluginSettingsFallback = { api_url: options?.apiUrl, api_key: options?.apiKey }
+  }
+}
+```
+
+- Types: `string`, `url` (http/https), `number` (finite, optional inclusive
+  `min`/`max`), `boolean`, `secret`, `select` (`options: [{ value, label }]`,
+  non-empty, unique values; the stored value must be one of them). Keys
+  follow the feature key format and are unique. A `secret` has no default;
+  any other default must match its type, options and bounds. `options` exist
+  only on `select`, `min`/`max` only on `number`. `required` defaults to
+  `false`. `invalidates` (optional) lists secret settings of the same plugin
+  that a change of this setting deletes, e.g. `invalidates: ["api_key"]` on
+  `api_url` so a stored key is never sent to a new host. `definePluginFeatures`
+  throws at import time otherwise (also for an `invalidates` entry that is not
+  a secret of the plugin). The Admin renders a `select` as a dropdown, gives
+  number inputs their bounds and shows "Beim Ändern muss … neu eingegeben
+  werden" under a setting with `invalidates`.
+- Precedence per key: stored in the Admin > `pluginSettingsFallback`
+  (medusa-config) > declared default > not set. A value that does not fit the
+  declared type is skipped. A plugin is `configured` when every required
+  setting has a value; `missing` lists the others. A plugin must handle "nicht
+  konfiguriert" at run time (log and skip) instead of failing at boot.
+- Server-side code reads the resolved values with secrets DECRYPTED:
+
+  ```ts
+  import { getPluginSettings } from "@hartl-services/medusa-base"
+
+  const { values, configured, missing } = await getPluginSettings(
+    container, demoPluginFeatures, fallback
+  )
+  ```
+
+  A module service has no access to other modules through its own container;
+  it passes the global `container` from `@medusajs/framework`.
+- Updates (`POST …/settings` with `{ expected_version, values }`) merge
+  `values` into the stored row in one transaction: `null` clears a stored
+  value (the setting falls back to medusa-config or its default), a secret
+  that is not sent keeps its stored value, keys the plugin no longer declares
+  are dropped. When a setting with `invalidates` gets a different stored
+  value (also when it is cleared), the listed secrets are deleted in the same
+  transaction unless the update sets them anew; they appear in
+  `changed_keys`. Unknown keys and values of the wrong type, outside `min`/`max`
+  or not among a select's options answer 400 naming the key, a stale `expected_version` 409. The response is the full
+  `AdminPluginFeaturesResponse`.
+- After a saved update the base emits `PLUGIN_SETTINGS_UPDATED_EVENT`
+  (`plugin-settings.updated.v1`) with `{ plugin_key, version, changed_keys }`
+  (no values). Direct service calls emit nothing.
+
+### Secrets
+
+Secrets are stored AES-256-GCM encrypted (`{ enc: "<base64 iv|tag|ciphertext>" }`
+in `plugin_setting_state.values`) with a key derived by HKDF-SHA256 from the
+plugin option `settingsSecret`, else `projectConfig.http.cookieSecret`. The
+ciphertext is bound to `<plugin_key>:<setting key>` (AES-GCM additional
+authenticated data), so a stored value cannot be copied to another setting or
+plugin. The Admin never receives a secret's value, only whether it is set.
+**Changing the key material (`settingsSecret`, or `COOKIE_SECRET` without it)
+invalidates stored secrets:** they then count as "nicht gesetzt" (a warning is
+logged once per secret) and must be entered again; a medusa-config fallback
+applies in the meantime. Secrets saved by an unpublished development build
+before the key binding existed count as "nicht gesetzt" the same way and must
+be entered again.
+
+## Actions
+
+A plugin declares actions as registered workflow ids; the base runs them from
+the plugin's Admin page:
+
+```ts
+actions: [
+  {
+    key: "sync_now",
+    label: "Jetzt synchronisieren",
+    workflow_id: "demo-sync-catalog",
+    mode: "background", // or "sync"
+    confirm: "Den ganzen Katalog jetzt abgleichen?", // optional prompt
+  },
+],
+```
+
+The workflow receives `PluginActionWorkflowInput`
+(`{ plugin_key, action_key, triggered_by, run_id }`; `triggered_by` is the
+Admin user id, `run_id` the recorded run).
+
+- Every start is recorded in `plugin_action_run` (`running` → `completed` |
+  `failed`, `started_at`, `finished_at`, `triggered_by`, `message` of a
+  failure, `progress`, `result` when it is JSON and at most 4 KB).
+- While a run of the same action is `running`, a start answers 409
+  (`{ type: "conflict", message: "Diese Aktion läuft bereits.", run }`) and
+  starts nothing. A partial unique index enforces this also for concurrent
+  requests.
+- `sync`: the request waits for the workflow and answers
+  `{ action: { key, status: "completed", result?, run } }`. A failure goes
+  through Medusa's error pipeline (a `MedusaError` keeps its status); the run
+  is recorded as failed.
+- `background`: the run is started without waiting and the request answers
+  202 `{ action: { key, status: "started", run } }`. The outcome is recorded
+  on the run when the workflow settles; a failure is also logged.
+- A workflow that is still running when the engine returns (async steps,
+  e.g. a step retry scheduled with `retryInterval`) keeps its run `running`
+  (a second start stays 409) until the engine reports its finish; the run is
+  then recorded like a background run. A `sync` action answers 202 `started`
+  in that case.
+- Both emit `PLUGIN_ACTION_FINISHED_EVENT` (`plugin-action.finished.v1`,
+  `{ plugin_key, action_key, run_id, status: "completed" | "failed", message? }`)
+  when the run ends.
+- `GET …/actions/:action_key/runs?limit=1` returns the latest runs, newest
+  first. The Admin polls it every 2 s while the latest run is `running`.
+- Lost runs: a `running` run without start or progress for one hour (the
+  process restarted, the workflow was lost) is listed as `failed` with
+  "Abgebrochen (Neustart)" (listing never writes) and persisted as such the
+  next time the action is started. A run that reports progress regularly is
+  never affected.
+- An unknown action is 404 ("Aktion unbekannt"); a declared action whose
+  workflow is not registered is 500 (`UNEXPECTED_STATE` naming the workflow,
+  no run is recorded).
+
+### Reporting progress
+
+A long-running action reports progress from its workflow; the Admin shows it
+as a bar ("current / total") with the label:
+
+```ts
+import {
+  reportPluginActionProgress,
+  type PluginActionWorkflowInput,
+} from "@hartl-services/medusa-base"
+
+const syncPageStep = createStep(
+  "demo-sync-page",
+  async (input: PluginActionWorkflowInput & { page: number }, { container }) => {
+    // … one page of work
+    await reportPluginActionProgress(container, input.run_id, {
+      current: input.page,
+      total: 12, // or null when unknown
+      label: `Produkte: Seite ${input.page}`,
+    })
+  }
+)
+```
+
+`current` and `total` must be non-negative integers, the label is cut to 200
+characters. Without a `run_id` (the same workflow run from a script) the
+helper does nothing; invalid progress, an unknown or finished run and a
+failed write are logged as a warning and dropped, and never fail the action.
+
+## Shop-Stammdaten
+
+The base declares its own descriptor on its module service
+(`plugin_key: "shop"`, label "Shop-Stammdaten", `switchable: false`, no
+features). The hub shows it as the first card; its generic page edits the
+settings like any plugin's:
+
+| Key | Type | Required |
+|---|---|---|
+| `legal_name` (Firmenname) | string | yes |
+| `address_line1`, `address_line2` | string | line 1 |
+| `postal_code`, `city` | string | yes |
+| `country_code` | select: EU-27 plus `ch`, `gb`, `no`, `is`, `li` (lowercase ISO-2, German labels) | yes |
+| `vat_number` (UID-Nummer) | string | yes |
+| `email`, `phone` | string | no |
+| `website` | url | no |
+| `iban`, `bic` | string | no |
+| `company_register_number` (Firmenbuchnummer), `company_register_court` (Firmenbuchgericht) | string | no |
+
+Server-side code reads them with a plugin's own medusa-config values as
+fallback (stored in the Admin wins per key):
+
+```ts
+import { getShopMasterData } from "@hartl-services/medusa-base"
+
+const { values, configured, missing } = await getShopMasterData(container, {
+  legal_name: options.merchant?.legalName,
+})
+if (!configured) {
+  throw new MedusaError(
+    MedusaError.Types.UNEXPECTED_STATE,
+    `Shop-Stammdaten unvollständig: ${missing.join(", ")}`
+  )
+}
+```
+
+The base only checks presence and type; what counts as a usable value
+(for example a placeholder UID) is the consuming plugin's rule.
+
+## Admin pages
+
+- `/settings/hartl-services` (sidebar entry "Hartl Services Plugins") is the
+  hub: one card per plugin with status chips, the plugin switch (not for
+  `switchable: false`) and "Öffnen"; non-switchable plugins (Shop-Stammdaten)
+  come first.
+- The Aktionen section shows per action the progress of a running run
+  ("läuft seit …", bar, label; the button is disabled) and the outcome of the
+  last finished run; a finished run it watched and a second start ("läuft
+  bereits") are announced as toasts.
+- "Öffnen" leads to the plugin's ONE page: its `admin_page` when declared,
+  otherwise the base's generic page
+  `/settings/hartl-services/plugin/<plugin_key>` (Funktionen, Einstellungen,
+  Aktionen). The static `plugin` segment keeps it from colliding with
+  plugin-owned routes.
+- A plugin that needs more than the generic sections (its own forms, lists)
+  declares `admin_page: "/settings/hartl-services/<plugin-slug>"` and composes
+  that page from the base's components (below). Nested settings routes get no
+  sidebar entry, so the hub is the only way in. `definePluginFeatures`
+  rejects a path outside `/settings/hartl-services/` or under
+  `/settings/hartl-services/plugin/`.
+
+### Admin components for plugin pages
+
+`@hartl-services/medusa-base/admin-components` (ESM for the Admin's vite
+build, with types) exports:
+
+| Export | Purpose |
+| --- | --- |
+| `PluginPageShell({ pluginKey, children })` | Back link to the hub, the plugin's label, description and status chips, then `children`; loading, "nicht installiert" and error states instead of `children` |
+| `PluginFeatureSections({ pluginKey })` | Funktionen, Einstellungen, Aktionen exactly as on the generic page |
+| `usePluginFeature(pluginKey)` | Query of `GET /admin/plugin-features/:plugin_key` |
+| `pluginFeatureKeys` | Query key factory (`all`, `list()`, `detail(key)`) for invalidation after an own mutation |
+| `usePluginFeatureEnabled(pluginKey, ...featureKeys)` | `{ enabled, isPending, isError }` from the shared list query (30 s stale time); plugin switch and every key must be effective; `enabled` is `false` while loading and on error |
+| `PluginFeatureGate({ pluginKey, featureKeys?, fallback? })` | Renders `children` only while enabled, otherwise `fallback` (default nothing) |
+| `PluginFeatureDisabledNotice({ pluginKey, featureLabel? })` | "Diese Funktion ist unter Einstellungen → Hartl Services Plugins ausgeschaltet." with a link to the hub |
+
+```tsx
+// src/admin/routes/settings/hartl-services/demo/page.tsx
+import {
+  PluginFeatureSections,
+  PluginPageShell,
+} from "@hartl-services/medusa-base/admin-components"
+
+import { DemoMappingSection } from "../../../../features/demo/DemoMappingSection"
+
+const DemoPage = () => (
+  <PluginPageShell pluginKey="demo">
+    <PluginFeatureSections pluginKey="demo" />
+    <DemoMappingSection />
+  </PluginPageShell>
+)
+
+export default DemoPage
+```
+
+Widgets and pages of a disabled feature disappear instead of showing a 404:
+
+```tsx
+// Widget: renders nothing while the feature is off (or still loading).
+const DemoOrderWidget = () => (
+  <PluginFeatureGate pluginKey="demo" featureKeys={["order_sync"]}>
+    <DemoOrderPanel />
+  </PluginFeatureGate>
+)
+
+// Full page with a sidebar entry that cannot be hidden: explain instead.
+const DemoReportsPage = () => {
+  const { enabled, isPending } = usePluginFeatureEnabled("demo", "reports")
+  if (isPending) return null
+  return enabled ? <DemoReports /> : (
+    <PluginFeatureDisabledNotice pluginKey="demo" featureLabel="Berichte" />
+  )
+}
+```
+
+The consuming plugin lists `@hartl-services/medusa-base` in its
+`dependencies` or `peerDependencies`, so its admin build keeps the import
+external and the shop's Admin resolves one shared copy. The components use
+the host Admin's React, React Query, React Router and `@medusajs/ui`.
+
 ## Semantics
 
 - No stored row: every value is its declared default, `version` is 0.
@@ -204,9 +581,10 @@ class MyModuleService extends MedusaService({ /* … */ }) {
   finished transaction.
 - The base discovers participants like feature descriptors (every module in
   `medusa-config` that is registered in the container). Fail closed: an
-  invalid declaration (non-string or blank `workflow_id`, non-finite `order`,
-  unknown hook name, the same workflow twice for one hook) is
-  `UNEXPECTED_STATE` and blocks checkout, naming the module key.
+  invalid declaration (non-string or blank `workflow_id`, a `workflow_id` that
+  is not a registered workflow, non-finite `order`, unknown hook name, the
+  same workflow twice for one hook) is `UNEXPECTED_STATE` and blocks
+  checkout, naming the module key (and the workflow id).
 
 **Ordering.** Ascending `order`, then module key, then workflow id. In use:
 Affiliate 100 (`affiliate-validate-complete-cart`,
@@ -218,9 +596,12 @@ Affiliate 100 (`affiliate-validate-complete-cart`,
 - `validate` participants run one after another without their own transaction
   id (they write nothing). The first error stops the chain and is rethrown
   unchanged.
+- Participants run and are cancelled with an explicitly built context, like
+  Medusa's `runAsStep`: the parent's shared transaction context plus its
+  event group (`preventReleaseEvents`), never the step's parent linkage
+  (`parentStepIdempotencyKey`), so complete-cart may itself run nested.
 - `orderCreated` participants run one after another through the workflow
-  engine under the complete-cart transaction id, with the parent's event group
-  (`preventReleaseEvents`). If participant *k* fails, the base cancels
+  engine under the complete-cart transaction id. If participant *k* fails, the base cancels
   participants *k-1 … 0* in reverse order, logs every failed cancellation
   (module key, workflow id, cart, order, transaction), and rethrows the
   original error.
@@ -230,3 +611,26 @@ Affiliate 100 (`affiliate-validate-complete-cart`,
   instead of silently leaving partial state.
 - The base never swallows a participant error and never reads toggles here.
 
+
+## Sentry logger wrapper
+
+`@hartl-services/medusa-base/sentry-logger` exports `withSentryErrorReporting(logger)`,
+formerly published as `@hartl-services/medusa-sentry-logger`. Medusa's HTTP
+error handler catches thrown route and workflow errors and only logs them, so
+Sentry's default Node integrations never see them; wrapping the logger reports
+every `logger.error(...)` and every `Error` passed to `logger.warn(...)` (at
+level `warning`). It is a plain library import for `medusa-config.ts`, not a
+Medusa plugin feature, and needs `@sentry/node` (an optional peer dependency):
+
+```ts
+import { logger } from "@medusajs/framework/logger";
+import { withSentryErrorReporting } from "@hartl-services/medusa-base/sentry-logger";
+
+module.exports = defineConfig({
+  logger: withSentryErrorReporting(logger),
+  // ...
+});
+```
+
+Initialize Sentry in `instrumentation.ts` as usual; without a `SENTRY_DSN` the
+wrapper is inert.

package/dist/admin-components/features/plugin-features/components/PluginActionsSection.d.ts

@@ -0,0 +1,6 @@
+import type { AdminPluginFeatures } from "@hartl-services/medusa-food-supplements-contracts/types/plugin-features-admin";
+type PluginActionsSectionProps = {
+    plugin: AdminPluginFeatures;
+};
+export declare const PluginActionsSection: ({ plugin }: PluginActionsSectionProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/admin-components/features/plugin-features/components/PluginActionsSection.js

@@ -0,0 +1,66 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button, Container, Heading, Text, toast, usePrompt } from "@medusajs/ui";
+import { useEffect, useRef } from "react";
+import { texts } from "../../../i18n/texts";
+import { useLatestPluginActionRun, useRunPluginAction, } from "../hooks/usePluginFeatures";
+import { formatRunTime, progressCount, progressPercent, runTransition, summarizeActionResult, } from "../lib/action-runs";
+/** Progress of a running run: label, "current / total", bar and start time. */
+const RunProgress = ({ run }) => {
+    const percent = progressPercent(run.progress);
+    const count = progressCount(run.progress);
+    const label = run.progress?.label;
+    return (_jsxs("div", { className: "mt-2 flex flex-col gap-y-1", role: "status", children: [(label || count) && (_jsx(Text, { size: "small", children: [label, count].filter(Boolean).join(" · ") })), percent !== null && (_jsx("div", { className: "bg-ui-border-base w-full overflow-hidden rounded-full", style: { height: 6 }, role: "progressbar", "aria-valuemin": 0, "aria-valuemax": 100, "aria-valuenow": percent, children: _jsx("div", { className: "bg-ui-fg-interactive h-full rounded-full", style: { width: `${percent}%`, height: "100%" } }) })), _jsx(Text, { size: "small", className: "text-ui-fg-muted", children: texts.actions.runningSince(formatRunTime(run.started_at)) })] }));
+};
+/** Outcome of the last finished run. */
+const RunStatusLine = ({ run }) => {
+    if (run.status === "completed") {
+        const summary = summarizeActionResult(run.result);
+        return (_jsxs("div", { className: "mt-1", children: [_jsx(Text, { size: "small", className: "text-ui-fg-subtle", children: texts.actions.lastCompleted(formatRunTime(run.finished_at ?? run.started_at)) }), summary && (_jsx(Text, { size: "small", className: "text-ui-fg-subtle", children: summary }))] }));
+    }
+    return (_jsxs("div", { className: "mt-1", children: [_jsx(Text, { size: "small", className: "text-ui-fg-error", children: texts.actions.lastFailed(formatRunTime(run.finished_at ?? run.started_at)) }), run.message && (_jsx(Text, { size: "small", className: "text-ui-fg-error", children: run.message }))] }));
+};
+const PluginActionRow = ({ pluginKey, action, starting, blocked, onRun, }) => {
+    const { data: run } = useLatestPluginActionRun(pluginKey, action.key);
+    const previous = useRef(undefined);
+    const running = run?.status === "running";
+    // Toast when a run this page watched while running has finished.
+    useEffect(() => {
+        const transition = runTransition(previous.current, run);
+        previous.current = run;
+        if (transition === "completed") {
+            toast.success(texts.toasts.actionCompleted(action.label), {
+                description: summarizeActionResult(run?.result) ?? undefined,
+            });
+        }
+        else if (transition === "failed") {
+            toast.error(texts.toasts.actionFailed(action.label), {
+                description: run?.message ?? texts.errors.unknown,
+            });
+        }
+    }, [run, action.label]);
+    return (_jsxs("div", { className: "flex items-start justify-between gap-4 px-6 py-4", children: [_jsxs("div", { className: "min-w-0 flex-1", children: [_jsx(Text, { size: "small", weight: "plus", children: action.label }), action.description && (_jsx(Text, { size: "small", className: "text-ui-fg-subtle", children: action.description })), run && (running ? _jsx(RunProgress, { run: run }) : _jsx(RunStatusLine, { run: run }))] }), _jsx(Button, { size: "small", variant: "secondary", className: "shrink-0", isLoading: starting || running, disabled: blocked || starting || running, onClick: () => onRun(action), children: action.label })] }));
+};
+export const PluginActionsSection = ({ plugin }) => {
+    const mutation = useRunPluginAction(plugin.plugin_key);
+    const prompt = usePrompt();
+    const startingKey = mutation.isPending ? mutation.variables?.key : undefined;
+    const run = async (action) => {
+        if (mutation.isPending) {
+            return;
+        }
+        if (action.confirm) {
+            const confirmed = await prompt({
+                title: texts.actions.confirmTitle(action.label),
+                description: action.confirm,
+                confirmText: texts.actions.confirm,
+                cancelText: texts.actions.cancel,
+                variant: "confirmation",
+            });
+            if (!confirmed) {
+                return;
+            }
+        }
+        mutation.mutate(action);
+    };
+    return (_jsxs(Container, { className: "divide-y p-0", children: [_jsx("div", { className: "px-6 py-4", children: _jsx(Heading, { level: "h2", children: texts.sections.actions }) }), plugin.actions.map((action) => (_jsx(PluginActionRow, { pluginKey: plugin.plugin_key, action: action, starting: startingKey === action.key, blocked: mutation.isPending && startingKey !== action.key, onRun: (entry) => void run(entry) }, action.key)))] }));
+};

package/dist/admin-components/features/plugin-features/components/PluginDetailPage.d.ts

@@ -0,0 +1,2 @@
+/** The base's generic page of a plugin without an own `admin_page`. */
+export declare const PluginDetailPage: () => import("react/jsx-runtime").JSX.Element;

package/dist/admin-components/features/plugin-features/components/PluginDetailPage.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useParams } from "react-router-dom";
+import { PluginFeatureSections } from "./PluginFeatureSections";
+import { PluginPageShell } from "./PluginPageShell";
+/** The base's generic page of a plugin without an own `admin_page`. */
+export const PluginDetailPage = () => {
+    const { plugin_key: pluginKey = "" } = useParams();
+    return (_jsx(PluginPageShell, { pluginKey: pluginKey, children: _jsx(PluginFeatureSections, { pluginKey: pluginKey }) }));
+};

package/dist/admin-components/features/plugin-features/components/PluginFeatureGate.d.ts

@@ -0,0 +1,22 @@
+import type { ReactNode } from "react";
+type PluginFeatureGateProps = {
+    pluginKey: string;
+    /** All must be on; none = plugin switch only. */
+    featureKeys?: readonly string[];
+    /** Rendered while loading, on error and when disabled; `null` by default. */
+    fallback?: ReactNode;
+    children: ReactNode;
+};
+/** Renders `children` only while the plugin and all `featureKeys` are on. */
+export declare const PluginFeatureGate: ({ pluginKey, featureKeys, fallback, children, }: PluginFeatureGateProps) => import("react/jsx-runtime").JSX.Element;
+type PluginFeatureDisabledNoticeProps = {
+    pluginKey: string;
+    /** Named in the text when given. */
+    featureLabel?: string;
+};
+/**
+ * For a full page whose sidebar entry cannot be hidden: says the feature is
+ * off and links to the hub.
+ */
+export declare const PluginFeatureDisabledNotice: ({ pluginKey, featureLabel, }: PluginFeatureDisabledNoticeProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/admin-components/features/plugin-features/components/PluginFeatureGate.js

@@ -0,0 +1,18 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Container, Text } from "@medusajs/ui";
+import { Link } from "react-router-dom";
+import { texts } from "../../../i18n/texts";
+import { usePluginFeatureEnabled } from "../hooks/usePluginFeatureEnabled";
+import { PLUGIN_HUB_PATH } from "../lib/plugin-paths";
+/** Renders `children` only while the plugin and all `featureKeys` are on. */
+export const PluginFeatureGate = ({ pluginKey, featureKeys = [], fallback = null, children, }) => {
+    const { enabled } = usePluginFeatureEnabled(pluginKey, ...featureKeys);
+    return _jsx(_Fragment, { children: enabled ? children : fallback });
+};
+/**
+ * For a full page whose sidebar entry cannot be hidden: says the feature is
+ * off and links to the hub.
+ */
+export const PluginFeatureDisabledNotice = ({ pluginKey, featureLabel, }) => (_jsxs(Container, { className: "flex flex-col gap-2 px-6 py-4", "data-plugin-key": pluginKey, children: [_jsx(Text, { className: "text-ui-fg-subtle", children: featureLabel
+                ? texts.gate.disabledNamed(featureLabel)
+                : texts.gate.disabled }), _jsx("div", { children: _jsx(Link, { to: PLUGIN_HUB_PATH, className: "text-ui-fg-interactive hover:text-ui-fg-interactive-hover txt-compact-small-plus", children: texts.gate.openHub }) })] }));

package/dist/admin-components/features/plugin-features/components/PluginFeatureSections.d.ts

@@ -0,0 +1,11 @@
+type PluginFeatureSectionsProps = {
+    pluginKey: string;
+};
+/**
+ * The base's sections of one plugin: Funktionen (unless the plugin has
+ * neither a switch nor features), Einstellungen (when the plugin declares
+ * settings) and Aktionen (when it declares actions). Renders
+ * nothing until the plugin is loaded; `PluginPageShell` shows that state.
+ */
+export declare const PluginFeatureSections: ({ pluginKey }: PluginFeatureSectionsProps) => import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/admin-components/features/plugin-features/components/PluginFeatureSections.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { texts } from "../../../i18n/texts";
+import { usePluginFeature } from "../hooks/usePluginFeatures";
+import { PluginActionsSection } from "./PluginActionsSection";
+import { PluginFeaturesCard } from "./PluginFeaturesCard";
+import { PluginSettingsForm } from "./PluginSettingsForm";
+/**
+ * The base's sections of one plugin: Funktionen (unless the plugin has
+ * neither a switch nor features), Einstellungen (when the plugin declares
+ * settings) and Aktionen (when it declares actions). Renders
+ * nothing until the plugin is loaded; `PluginPageShell` shows that state.
+ */
+export const PluginFeatureSections = ({ pluginKey }) => {
+    const plugin = usePluginFeature(pluginKey).data?.plugin;
+    if (!plugin) {
+        return null;
+    }
+    return (_jsxs(_Fragment, { children: [(plugin.switchable || plugin.features.length > 0) && (_jsx(PluginFeaturesCard, { plugin: plugin, title: texts.sections.features })), plugin.settings.length > 0 && _jsx(PluginSettingsForm, { plugin: plugin }), plugin.actions.length > 0 && _jsx(PluginActionsSection, { plugin: plugin })] }));
+};