@hartl-services/medusa-base 0.3.0 → 0.4.0

package/dist/admin-components/features/plugin-features/hooks/usePluginFeatures.d.ts

@@ -0,0 +1,392 @@
+export declare function usePluginFeatures(): import("@tanstack/react-query").UseQueryResult<{
+    plugins: {
+        plugin_key: string;
+        label: string;
+        description: string | null;
+        default_enabled: boolean;
+        switchable: boolean;
+        enabled: boolean;
+        version: number;
+        features: {
+            key: string;
+            label: string;
+            description: string | null;
+            parent_key: string | null;
+            default_enabled: boolean;
+            enabled: boolean;
+            effective_enabled: boolean;
+        }[];
+        settings: ({
+            type: "secret";
+            key: string;
+            label: string;
+            description: string | null;
+            required: boolean;
+            is_set: boolean;
+            source: "default" | "stored" | "config" | "none";
+            invalidates: string[];
+        } | {
+            type: "select";
+            options: {
+                value: string;
+                label: string;
+            }[];
+            default: string | null;
+            value: string | null;
+            key: string;
+            label: string;
+            description: string | null;
+            required: boolean;
+            is_set: boolean;
+            source: "default" | "stored" | "config" | "none";
+            invalidates: string[];
+        } | {
+            type: "number";
+            min: number | null;
+            max: number | null;
+            default: number | null;
+            value: number | null;
+            key: string;
+            label: string;
+            description: string | null;
+            required: boolean;
+            is_set: boolean;
+            source: "default" | "stored" | "config" | "none";
+            invalidates: string[];
+        } | {
+            type: "string" | "boolean" | "url";
+            default: string | number | boolean | null;
+            value: string | number | boolean | null;
+            key: string;
+            label: string;
+            description: string | null;
+            required: boolean;
+            is_set: boolean;
+            source: "default" | "stored" | "config" | "none";
+            invalidates: string[];
+        })[];
+        configured: boolean;
+        missing: string[];
+        settings_version: number;
+        actions: {
+            key: string;
+            label: string;
+            description: string | null;
+            mode: "sync" | "background";
+            confirm: string | null;
+        }[];
+        admin_page: string | null;
+    }[];
+}, Error>;
+/**
+ * One plugin (`GET /admin/plugin-features/:plugin_key`). Shows the entry from
+ * the already loaded list right away and fetches the plugin itself, so a deep
+ * link works without the hub. Toggle, settings and action mutations of the
+ * base update this cache; invalidate `pluginFeatureKeys.detail(pluginKey)`
+ * after an own mutation that changes what the base reports.
+ */
+export declare function usePluginFeature(pluginKey: string | undefined): import("@tanstack/react-query").UseQueryResult<{
+    plugin: {
+        plugin_key: string;
+        label: string;
+        description: string | null;
+        default_enabled: boolean;
+        switchable: boolean;
+        enabled: boolean;
+        version: number;
+        features: {
+            key: string;
+            label: string;
+            description: string | null;
+            parent_key: string | null;
+            default_enabled: boolean;
+            enabled: boolean;
+            effective_enabled: boolean;
+        }[];
+        settings: ({
+            type: "secret";
+            key: string;
+            label: string;
+            description: string | null;
+            required: boolean;
+            is_set: boolean;
+            source: "default" | "stored" | "config" | "none";
+            invalidates: string[];
+        } | {
+            type: "select";
+            options: {
+                value: string;
+                label: string;
+            }[];
+            default: string | null;
+            value: string | null;
+            key: string;
+            label: string;
+            description: string | null;
+            required: boolean;
+            is_set: boolean;
+            source: "default" | "stored" | "config" | "none";
+            invalidates: string[];
+        } | {
+            type: "number";
+            min: number | null;
+            max: number | null;
+            default: number | null;
+            value: number | null;
+            key: string;
+            label: string;
+            description: string | null;
+            required: boolean;
+            is_set: boolean;
+            source: "default" | "stored" | "config" | "none";
+            invalidates: string[];
+        } | {
+            type: "string" | "boolean" | "url";
+            default: string | number | boolean | null;
+            value: string | number | boolean | null;
+            key: string;
+            label: string;
+            description: string | null;
+            required: boolean;
+            is_set: boolean;
+            source: "default" | "stored" | "config" | "none";
+            invalidates: string[];
+        })[];
+        configured: boolean;
+        missing: string[];
+        settings_version: number;
+        actions: {
+            key: string;
+            label: string;
+            description: string | null;
+            mode: "sync" | "background";
+            confirm: string | null;
+        }[];
+        admin_page: string | null;
+    };
+}, Error>;
+/** One instance per plugin card, so pending state is scoped to that plugin. */
+export declare function useUpdatePluginFeatures(): import("@tanstack/react-query").UseMutationResult<{
+    plugin: {
+        plugin_key: string;
+        label: string;
+        description: string | null;
+        default_enabled: boolean;
+        switchable: boolean;
+        enabled: boolean;
+        version: number;
+        features: {
+            key: string;
+            label: string;
+            description: string | null;
+            parent_key: string | null;
+            default_enabled: boolean;
+            enabled: boolean;
+            effective_enabled: boolean;
+        }[];
+        settings: ({
+            type: "secret";
+            key: string;
+            label: string;
+            description: string | null;
+            required: boolean;
+            is_set: boolean;
+            source: "default" | "stored" | "config" | "none";
+            invalidates: string[];
+        } | {
+            type: "select";
+            options: {
+                value: string;
+                label: string;
+            }[];
+            default: string | null;
+            value: string | null;
+            key: string;
+            label: string;
+            description: string | null;
+            required: boolean;
+            is_set: boolean;
+            source: "default" | "stored" | "config" | "none";
+            invalidates: string[];
+        } | {
+            type: "number";
+            min: number | null;
+            max: number | null;
+            default: number | null;
+            value: number | null;
+            key: string;
+            label: string;
+            description: string | null;
+            required: boolean;
+            is_set: boolean;
+            source: "default" | "stored" | "config" | "none";
+            invalidates: string[];
+        } | {
+            type: "string" | "boolean" | "url";
+            default: string | number | boolean | null;
+            value: string | number | boolean | null;
+            key: string;
+            label: string;
+            description: string | null;
+            required: boolean;
+            is_set: boolean;
+            source: "default" | "stored" | "config" | "none";
+            invalidates: string[];
+        })[];
+        configured: boolean;
+        missing: string[];
+        settings_version: number;
+        actions: {
+            key: string;
+            label: string;
+            description: string | null;
+            mode: "sync" | "background";
+            confirm: string | null;
+        }[];
+        admin_page: string | null;
+    };
+}, Error, {
+    plugin_key: string;
+    expected_version: number;
+    enabled: boolean;
+    features: Record<string, boolean>;
+}, unknown>;
+export declare function useUpdatePluginSettings(pluginKey: string): import("@tanstack/react-query").UseMutationResult<{
+    plugin: {
+        plugin_key: string;
+        label: string;
+        description: string | null;
+        default_enabled: boolean;
+        switchable: boolean;
+        enabled: boolean;
+        version: number;
+        features: {
+            key: string;
+            label: string;
+            description: string | null;
+            parent_key: string | null;
+            default_enabled: boolean;
+            enabled: boolean;
+            effective_enabled: boolean;
+        }[];
+        settings: ({
+            type: "secret";
+            key: string;
+            label: string;
+            description: string | null;
+            required: boolean;
+            is_set: boolean;
+            source: "default" | "stored" | "config" | "none";
+            invalidates: string[];
+        } | {
+            type: "select";
+            options: {
+                value: string;
+                label: string;
+            }[];
+            default: string | null;
+            value: string | null;
+            key: string;
+            label: string;
+            description: string | null;
+            required: boolean;
+            is_set: boolean;
+            source: "default" | "stored" | "config" | "none";
+            invalidates: string[];
+        } | {
+            type: "number";
+            min: number | null;
+            max: number | null;
+            default: number | null;
+            value: number | null;
+            key: string;
+            label: string;
+            description: string | null;
+            required: boolean;
+            is_set: boolean;
+            source: "default" | "stored" | "config" | "none";
+            invalidates: string[];
+        } | {
+            type: "string" | "boolean" | "url";
+            default: string | number | boolean | null;
+            value: string | number | boolean | null;
+            key: string;
+            label: string;
+            description: string | null;
+            required: boolean;
+            is_set: boolean;
+            source: "default" | "stored" | "config" | "none";
+            invalidates: string[];
+        })[];
+        configured: boolean;
+        missing: string[];
+        settings_version: number;
+        actions: {
+            key: string;
+            label: string;
+            description: string | null;
+            mode: "sync" | "background";
+            confirm: string | null;
+        }[];
+        admin_page: string | null;
+    };
+}, Error, {
+    expected_version: number;
+    values: Record<string, string | number | boolean | null>;
+}, unknown>;
+/** Poll interval while the latest run of an action is `running`. */
+export declare const PLUGIN_ACTION_RUN_POLL_MS = 2000;
+/**
+ * Latest run of one action. Polls every 2 s while it is `running` and stops
+ * when it finished.
+ */
+export declare function useLatestPluginActionRun(pluginKey: string, actionKey: string): import("@tanstack/react-query").UseQueryResult<{
+    id: string;
+    plugin_key: string;
+    action_key: string;
+    status: "failed" | "completed" | "running";
+    started_at: string;
+    finished_at: string | null;
+    triggered_by: string | null;
+    message: string | null;
+    progress: {
+        current: number;
+        total: number | null;
+        label: string | null;
+    } | null;
+    result: unknown;
+}, Error>;
+/**
+ * Runs one action. The recorded run goes into the action's run query, so a
+ * background run is polled right away. 409 (already running) shows a hint
+ * and loads the running run.
+ */
+export declare function useRunPluginAction(pluginKey: string): import("@tanstack/react-query").UseMutationResult<{
+    action: {
+        key: string;
+        status: "completed" | "started";
+        run: {
+            id: string;
+            plugin_key: string;
+            action_key: string;
+            status: "failed" | "completed" | "running";
+            started_at: string;
+            finished_at: string | null;
+            triggered_by: string | null;
+            message: string | null;
+            progress: {
+                current: number;
+                total: number | null;
+                label: string | null;
+            } | null;
+            result: unknown;
+        };
+        result?: unknown;
+    };
+}, Error, {
+    key: string;
+    label: string;
+    description: string | null;
+    mode: "sync" | "background";
+    confirm: string | null;
+}, unknown>;

package/dist/admin-components/features/plugin-features/hooks/usePluginFeatures.js

@@ -0,0 +1,128 @@
+import { toast } from "@medusajs/ui";
+import { useMutation, useQuery, useQueryClient, } from "@tanstack/react-query";
+import { texts } from "../../../i18n/texts";
+import { getErrorMessage } from "../../../lib/errors";
+import { listPluginActionRuns, listPluginFeatures, retrievePluginFeatures, runPluginAction, updatePluginFeatures, updatePluginSettings, } from "../lib/plugin-features-admin-client";
+import { pluginFeatureKeys } from "../queries/pluginFeatureKeys";
+const isConflict = (error) => typeof error === "object" &&
+    error !== null &&
+    "status" in error &&
+    error.status === 409;
+/** Writes a server response into the list and the plugin's detail cache. */
+const storePlugin = (queryClient, plugin) => {
+    queryClient.setQueryData(pluginFeatureKeys.list(), (current) => current && {
+        plugins: current.plugins.map((entry) => entry.plugin_key === plugin.plugin_key ? plugin : entry),
+    });
+    queryClient.setQueryData(pluginFeatureKeys.detail(plugin.plugin_key), { plugin });
+};
+/** Toast for a failed save; reloads the server state either way. */
+const onSaveError = async (queryClient, error) => {
+    if (isConflict(error)) {
+        toast.error(texts.toasts.conflict);
+    }
+    else {
+        toast.error(texts.toasts.saveFailed, {
+            description: getErrorMessage(error) ?? texts.errors.unknown,
+        });
+    }
+    await queryClient.invalidateQueries({ queryKey: pluginFeatureKeys.all });
+};
+export function usePluginFeatures() {
+    return useQuery({
+        queryKey: pluginFeatureKeys.list(),
+        queryFn: listPluginFeatures,
+    });
+}
+/**
+ * One plugin (`GET /admin/plugin-features/:plugin_key`). Shows the entry from
+ * the already loaded list right away and fetches the plugin itself, so a deep
+ * link works without the hub. Toggle, settings and action mutations of the
+ * base update this cache; invalidate `pluginFeatureKeys.detail(pluginKey)`
+ * after an own mutation that changes what the base reports.
+ */
+export function usePluginFeature(pluginKey) {
+    const queryClient = useQueryClient();
+    return useQuery({
+        queryKey: pluginFeatureKeys.detail(pluginKey ?? ""),
+        queryFn: () => retrievePluginFeatures(pluginKey),
+        enabled: Boolean(pluginKey),
+        placeholderData: () => {
+            const plugin = queryClient
+                .getQueryData(pluginFeatureKeys.list())
+                ?.plugins.find((entry) => entry.plugin_key === pluginKey);
+            return plugin ? { plugin } : undefined;
+        },
+    });
+}
+/** One instance per plugin card, so pending state is scoped to that plugin. */
+export function useUpdatePluginFeatures() {
+    const queryClient = useQueryClient();
+    return useMutation({
+        mutationFn: updatePluginFeatures,
+        onSuccess: ({ plugin }) => {
+            storePlugin(queryClient, plugin);
+            toast.success(texts.toasts.saved);
+        },
+        onError: (error) => onSaveError(queryClient, error),
+    });
+}
+export function useUpdatePluginSettings(pluginKey) {
+    const queryClient = useQueryClient();
+    return useMutation({
+        mutationFn: (payload) => updatePluginSettings(pluginKey, payload),
+        onSuccess: ({ plugin }) => {
+            storePlugin(queryClient, plugin);
+            toast.success(texts.toasts.saved);
+        },
+        onError: (error) => onSaveError(queryClient, error),
+    });
+}
+/** Poll interval while the latest run of an action is `running`. */
+export const PLUGIN_ACTION_RUN_POLL_MS = 2000;
+/**
+ * Latest run of one action. Polls every 2 s while it is `running` and stops
+ * when it finished.
+ */
+export function useLatestPluginActionRun(pluginKey, actionKey) {
+    return useQuery({
+        queryKey: pluginFeatureKeys.actionRuns(pluginKey, actionKey),
+        queryFn: () => listPluginActionRuns(pluginKey, actionKey, 1),
+        select: (data) => data.runs[0],
+        refetchInterval: (query) => query.state.data?.runs[0]?.status === "running"
+            ? PLUGIN_ACTION_RUN_POLL_MS
+            : false,
+    });
+}
+/**
+ * Runs one action. The recorded run goes into the action's run query, so a
+ * background run is polled right away. 409 (already running) shows a hint
+ * and loads the running run.
+ */
+export function useRunPluginAction(pluginKey) {
+    const queryClient = useQueryClient();
+    return useMutation({
+        mutationFn: (action) => runPluginAction(pluginKey, action.key),
+        onSuccess: ({ action: run }, action) => {
+            queryClient.setQueryData(pluginFeatureKeys.actionRuns(pluginKey, action.key), { runs: [run.run] });
+            if (run.status === "started") {
+                toast.info(texts.toasts.actionStarted(action.label));
+            }
+            else {
+                toast.success(texts.toasts.actionCompleted(action.label));
+            }
+        },
+        onError: async (error, action) => {
+            if (isConflict(error)) {
+                toast.info(texts.toasts.actionAlreadyRunning(action.label));
+            }
+            else {
+                toast.error(texts.toasts.actionFailed(action.label), {
+                    description: getErrorMessage(error) ?? texts.errors.unknown,
+                });
+            }
+            await queryClient.invalidateQueries({
+                queryKey: pluginFeatureKeys.actionRuns(pluginKey, action.key),
+            });
+        },
+    });
+}

package/dist/admin-components/features/plugin-features/hooks/usePluginSettingsForm.d.ts

@@ -0,0 +1,93 @@
+import type { AdminPluginFeatures } from "@hartl-services/medusa-food-supplements-contracts/types/plugin-features-admin";
+import type { FormEvent } from "react";
+import { type SettingsDraft } from "../lib/settings-draft";
+export declare function usePluginSettingsForm(plugin: AdminPluginFeatures): {
+    draft: SettingsDraft;
+    setValue: (key: string, value: string | boolean | null, badInput?: boolean) => void;
+    dirty: boolean;
+    invalid: string[];
+    submit: (event: FormEvent<HTMLFormElement>) => void;
+    mutation: import("@tanstack/react-query").UseMutationResult<{
+        plugin: {
+            plugin_key: string;
+            label: string;
+            description: string | null;
+            default_enabled: boolean;
+            switchable: boolean;
+            enabled: boolean;
+            version: number;
+            features: {
+                key: string;
+                label: string;
+                description: string | null;
+                parent_key: string | null;
+                default_enabled: boolean;
+                enabled: boolean;
+                effective_enabled: boolean;
+            }[];
+            settings: ({
+                type: "secret";
+                key: string;
+                label: string;
+                description: string | null;
+                required: boolean;
+                is_set: boolean;
+                source: "default" | "stored" | "config" | "none";
+                invalidates: string[];
+            } | {
+                type: "select";
+                options: {
+                    value: string;
+                    label: string;
+                }[];
+                default: string | null;
+                value: string | null;
+                key: string;
+                label: string;
+                description: string | null;
+                required: boolean;
+                is_set: boolean;
+                source: "default" | "stored" | "config" | "none";
+                invalidates: string[];
+            } | {
+                type: "number";
+                min: number | null;
+                max: number | null;
+                default: number | null;
+                value: number | null;
+                key: string;
+                label: string;
+                description: string | null;
+                required: boolean;
+                is_set: boolean;
+                source: "default" | "stored" | "config" | "none";
+                invalidates: string[];
+            } | {
+                type: "string" | "boolean" | "url";
+                default: string | number | boolean | null;
+                value: string | number | boolean | null;
+                key: string;
+                label: string;
+                description: string | null;
+                required: boolean;
+                is_set: boolean;
+                source: "default" | "stored" | "config" | "none";
+                invalidates: string[];
+            })[];
+            configured: boolean;
+            missing: string[];
+            settings_version: number;
+            actions: {
+                key: string;
+                label: string;
+                description: string | null;
+                mode: "sync" | "background";
+                confirm: string | null;
+            }[];
+            admin_page: string | null;
+        };
+    }, Error, {
+        expected_version: number;
+        values: Record<string, string | number | boolean | null>;
+    }, unknown>;
+};

package/dist/admin-components/features/plugin-features/hooks/usePluginSettingsForm.js

@@ -0,0 +1,44 @@
+import { useEffect, useMemo, useState } from "react";
+import { changedSettingValues, initialSettingsDraft, invalidDraftKeys, } from "../lib/settings-draft";
+import { useUpdatePluginSettings } from "./usePluginFeatures";
+export function usePluginSettingsForm(plugin) {
+    const mutation = useUpdatePluginSettings(plugin.plugin_key);
+    const [draft, setDraft] = useState(() => initialSettingsDraft(plugin.settings));
+    // Number inputs the browser could not parse (they report "").
+    const [unparsable, setUnparsable] = useState([]);
+    // New server data (save, conflict reload, refetch) resets the form.
+    useEffect(() => {
+        setDraft(initialSettingsDraft(plugin.settings));
+        setUnparsable([]);
+    }, [plugin.settings, plugin.settings_version]);
+    const changes = useMemo(() => changedSettingValues(plugin.settings, draft, unparsable), [plugin.settings, draft, unparsable]);
+    const invalid = useMemo(() => invalidDraftKeys(plugin.settings, draft, unparsable), [plugin.settings, draft, unparsable]);
+    const dirty = Object.keys(changes).length > 0;
+    /** `badInput`: the browser could not parse the typed number. */
+    const setValue = (key, value, badInput = false) => {
+        setDraft((current) => ({ ...current, [key]: value }));
+        setUnparsable((current) => badInput
+            ? current.includes(key)
+                ? current
+                : [...current, key]
+            : current.filter((entry) => entry !== key));
+    };
+    const submit = (event) => {
+        event.preventDefault();
+        if (!dirty || invalid.length > 0 || mutation.isPending) {
+            return;
+        }
+        mutation.mutate({
+            expected_version: plugin.settings_version,
+            values: changes,
+        });
+    };
+    return {
+        draft,
+        setValue,
+        dirty,
+        invalid,
+        submit,
+        mutation,
+    };
+}

package/dist/admin-components/features/plugin-features/lib/action-runs.d.ts

@@ -0,0 +1,19 @@
+import type { PluginActionRun, PluginActionRunProgress } from "@hartl-services/medusa-food-supplements-contracts/types/plugin-features-admin";
+/**
+ * One line for a finished run's result: a string result, else its `summary`
+ * or `message`, else its primitive top-level fields (`key: value, …`).
+ * `null` when nothing readable is there.
+ */
+export declare const summarizeActionResult: (result: unknown) => string | null;
+/** Share done in percent (0–100); `null` when the total is unknown. */
+export declare const progressPercent: (progress: PluginActionRunProgress | null) => number | null;
+/** "3 / 10" or "3" (unknown total); `null` without progress. */
+export declare const progressCount: (progress: PluginActionRunProgress | null) => string | null;
+/** Short German date and time. */
+export declare const formatRunTime: (iso: string | null) => string;
+export type RunTransition = "completed" | "failed" | null;
+/**
+ * Whether the latest run just finished while this page watched it: the same
+ * run was `running` before and is `completed`/`failed` now.
+ */
+export declare const runTransition: (previous: Pick<PluginActionRun, "id" | "status"> | undefined, current: Pick<PluginActionRun, "id" | "status"> | undefined) => RunTransition;