@rapidmx/web-client 0.31.0 → 0.32.0

package/apps/shared/components/admin/diagnostics/InformationPanel.tsx

@@ -41,13 +41,13 @@ export default function InformationPanel({ versions, plugins, information }: Inf
                             <SettingsTable
                                 id="diagnostics-environment"
                                 title="Environment variables"
-                                description="The server process's environment. Only variables known to be harmless show their value; the value of a secret, or of anything unrecognized, is withheld by the server and never sent."
+                                description="The server process's environment. Every variable shows its value except those on the server's list of hidden settings, whose value is withheld by the server and never sent."
                                 settings={information.data.environment ?? []}
                             />
                             <SettingsTable
                                 id="diagnostics-configuration"
                                 title="Configuration"
-                                description="The effective settings the server runs with: the environment, saved plugin settings and defaults combined. Passwords, tokens, keys, certificates and the credentials in URLs are withheld by the server and never sent."
+                                description="The effective settings the server runs with: the environment, saved plugin settings and defaults combined. Settings on the server's list of hidden settings, such as passwords, tokens and keys, are withheld by the server and never sent, and so are the credentials in URLs."
                                 settings={information.data.configuration ?? []}
                             />
                         </>

package/apps/shared/components/admin/diagnostics/diagnosticsApi.ts

@@ -76,8 +76,8 @@ export interface DiagnosticsVersions {
 }
 
 /**
- * One environment variable or configuration setting. A `redacted` one has no `value`: the server withholds every secret-like
- * or unrecognized value and never sends it, so there is nothing for the client to hide.
+ * One environment variable or configuration setting. A `redacted` one has no `value`: the server withholds the value of every setting on its
+ * hidden list and never sends it, so there is nothing for the client to hide.
  */
 export interface DiagnosticsSetting {
     name: string;

package/apps/shared/components/admin/settings/PluginsManager.tsx

@@ -33,7 +33,9 @@ import {
     retryPluginPurge,
     searchPlugins,
     updatePlugin,
+    uploadPlugin,
 } from "../../../../../lib/admin/pluginsApi.js";
+import { ApiRequestError } from "../../../../../lib/util/api.js";
 import Alert from "../ActionAlert.js";
 import Button from "../../../../../lib/components/buttons/Button.js";
 import Modal from "../../../../../lib/components/overlays/Modal.js";
@@ -84,6 +86,21 @@ function purgeFailure(purge: PluginPurgeInfo): string {
 /** A day, in the administrator's own format. */
 const formatDate = (iso: string): string => new Date(iso).toLocaleDateString(undefined, { dateStyle: "medium" });
 
+/** The file names an uploaded plugin may have: what `npm pack` produces (`<name>-<version>.tgz`), or the same gzipped. */
+const PLUGIN_PACK_NAME = /\.(tgz|tar\.gz|gz)$/i;
+
+/** What the server answers (409) an upload of a plugin that is already installed, which the administrator may replace. */
+const ALREADY_INSTALLED = /already installed/i;
+
+/** An upload the administrator is being asked to let replace the plugin of the same name. */
+interface PendingReplace {
+    file: File;
+    /** What the replacement would do, as a question. */
+    question: string;
+    /** Why the server refused, in its words. */
+    reason: string;
+}
+
 /** A change waiting for the administrator to confirm the other plugins it also installs or enables. */
 interface PendingChange {
     displayName: string;
@@ -225,6 +242,11 @@ export default function PluginsManager({ embedded = false }: PluginsManagerProps
     const [confirmingBulkUninstall, setConfirmingBulkUninstall] = useState<Plugin[] | null>(null);
     /** How many changes (or the lookups that come before them) are waiting on the server. */
     const [working, setWorking] = useState(0);
+    /** Set while an uploaded plugin is being sent to the server. */
+    const [uploading, setUploading] = useState(false);
+    /** An upload that would replace an installed plugin, waiting for the administrator to confirm it. */
+    const [replacing, setReplacing] = useState<PendingReplace | null>(null);
+    const fileInput = useRef<HTMLInputElement>(null);
     const statusRequest = useRef<Promise<void> | null>(null);
     /** The state each data deletion was last seen in, so a notification is raised when one that was under way ends. */
     const seenPurges = useRef<Map<string, PluginPurgeState>>(new Map());
@@ -517,6 +539,54 @@ export default function PluginsManager({ embedded = false }: PluginsManagerProps
         return onRow(plugin, () => changeVersion(plugin, packageVersion));
     }
 
+    /** Sends `file` to the server as a plugin to install - replacing the installed plugin of that name only when `replace` is set. A plugin that is
+     * already installed isn't an error but a question, asked of the administrator before it is replaced. */
+    async function runUpload(file: File, replace: boolean) {
+        setUploading(true);
+        setError(null);
+        setRetryEnableUid(null);
+        try {
+            const uploaded: Plugin = await track(uploadPlugin(file, { replace }));
+            applied(uploaded);
+            notify({
+                kind: "success",
+                title: `${uploaded.name}@${uploaded.packageVersion} uploaded`,
+                message: "The servers restart one at a time to load it.",
+            });
+        } catch (err) {
+            if (!replace && err instanceof ApiRequestError && err.status === 409 && ALREADY_INSTALLED.test(err.message)) {
+                const installed: Plugin | undefined = plugins.find((plugin) => err.message.includes(plugin.name));
+                setReplacing({
+                    file,
+                    question: installed
+                        ? `Replace ${installed.name} ${installed.packageVersion} with the uploaded pack?`
+                        : "Replace the installed plugin with the uploaded pack?",
+                    reason: err.message,
+                });
+            } else if (err instanceof ApiRequestError && err.status === 413) {
+                setError("That file is too large for the server to accept.");
+            } else {
+                setError(errorMessage(err, "Could not upload the plugin."));
+            }
+        }
+        setUploading(false);
+    }
+
+    /** Takes the file the administrator chose, unless it can't be what `npm pack` produces. */
+    function onFileChosen(e: React.ChangeEvent<HTMLInputElement>) {
+        const file: File | undefined = e.target.files?.[0];
+        // So choosing the same file again (after fixing what was wrong) still counts as a change.
+        e.target.value = "";
+        if (!file) {
+            return;
+        }
+        if (!PLUGIN_PACK_NAME.test(file.name)) {
+            setError(`${file.name} isn't a plugin pack. Choose the .tgz file that npm pack produces.`);
+            return;
+        }
+        void runUpload(file, false);
+    }
+
     /** Installs an uninstalled plugin again, at its latest version - as adding it by name would. */
     function reinstall(purge: PluginPurgeInfo) {
         const displayName: string = purgeName(purge);
@@ -682,12 +752,34 @@ export default function PluginsManager({ embedded = false }: PluginsManagerProps
     const displayNameOf = (name: string): string => plugins.find((plugin) => plugin.name === name)?.manifest.displayName ?? name;
 
     const SectionHeading = embedded ? "h3" : "h2";
+    const bulkBusy: boolean = bulk !== null;
     const addButton = (
-        <Button type="button" variant="secondary" className="!w-auto shrink-0" onClick={() => setAdding(true)}>
-            Add by name
-        </Button>
+        <div className="flex flex-wrap gap-2 shrink-0">
+            <input
+                ref={fileInput}
+                type="file"
+                className="hidden"
+                accept=".tgz,.tar.gz,application/gzip,application/x-gzip"
+                aria-label="Plugin pack file"
+                tabIndex={-1}
+                onChange={onFileChosen}
+            />
+            <Button
+                type="button"
+                variant="secondary"
+                className="!w-auto"
+                title="Install a plugin from the .tgz file that npm pack produces"
+                loading={uploading}
+                disabled={uploading || bulkBusy}
+                onClick={() => fileInput.current?.click()}
+            >
+                {uploading ? "Uploading\u2026" : "Upload"}
+            </Button>
+            <Button type="button" variant="secondary" className="!w-auto" onClick={() => setAdding(true)}>
+                Add by name
+            </Button>
+        </div>
     );
-    const bulkBusy: boolean = bulk !== null;
 
     return (
         <>
@@ -741,24 +833,18 @@ export default function PluginsManager({ embedded = false }: PluginsManagerProps
                     </div>
                 </Alert>
             )}
-            {error && (
-                <Alert>
-                    {error}
-                    {retryEnable && (
-                        <>
-                            {" "}
-                            <Button
-                                type="button"
-                                variant="text"
-                                className="!w-auto !p-0"
-                                onClick={() => void toggle(retryEnable)}
-                            >
-                                Try again
-                            </Button>
-                        </>
-                    )}
-                </Alert>
-            )}
+            {/* A message on its own is a plain string child, which is what lets the alert offer to confirm the identity again. */}
+            {error &&
+                (retryEnable ? (
+                    <Alert>
+                        {error}{" "}
+                        <Button type="button" variant="text" className="!w-auto !p-0" onClick={() => void toggle(retryEnable)}>
+                            Try again
+                        </Button>
+                    </Alert>
+                ) : (
+                    <Alert>{error}</Alert>
+                ))}
             <RolloutBanner status={status} />
             {statusStale && status && (
                 <p className="mb-4 text-xs text-text-muted">Couldn&apos;t refresh server status. Showing the last status reported.</p>
@@ -871,7 +957,9 @@ export default function PluginsManager({ embedded = false }: PluginsManagerProps
                         <tbody role="rowgroup" className="block lg:table-row-group">
                             {plugins.map((plugin) => {
                                 const update: PluginUpdateInfo | undefined = updates.get(plugin.uid);
-                                const latest: string | undefined = update?.updateAvailable ? update.latestVersion : undefined;
+                                const uploaded: boolean = plugin.source === "upload";
+                                // An uploaded pack has no registry version to be newer than.
+                                const latest: string | undefined = !uploaded && update?.updateAvailable ? update.latestVersion : undefined;
                                 const busy: boolean = busyUids.has(plugin.uid) || confirming?.uid === plugin.uid || bulkBusy;
                                 const requires: string[] = Object.keys(plugin.manifest.requires ?? {}).map(displayNameOf);
                                 const requiredBy: string[] = plugins
@@ -895,6 +983,13 @@ export default function PluginsManager({ embedded = false }: PluginsManagerProps
                                                     {plugin.manifest.description && (
                                                         <div className="text-xs text-text-muted mt-1 max-w-md">{plugin.manifest.description}</div>
                                                     )}
+                                                    {uploaded && (
+                                                        <div className="text-xs text-text-muted mt-1 break-words">
+                                                            <span className={`${BADGE_CLASS} bg-surface-alt text-text-muted`}>Uploaded</span>{" "}
+                                                            {plugin.uploadFilename}
+                                                            {plugin.uploadedAt ? `, ${formatDate(plugin.uploadedAt)}` : ""}
+                                                        </div>
+                                                    )}
                                                     {requires.length > 0 && <div className="text-xs text-text-muted mt-1">Requires: {requires.join(", ")}</div>}
                                                     {requiredBy.length > 0 && (
                                                         <div className="text-xs text-text-muted mt-1">Required by: {requiredBy.join(", ")}</div>
@@ -942,7 +1037,7 @@ export default function PluginsManager({ embedded = false }: PluginsManagerProps
                                                 </div>
                                                 <div className="flex flex-wrap gap-x-4 lg:justify-end">
                                                     <Button variant="text" type="button" onClick={() => setUpgrading(plugin)}>
-                                                        Change version
+                                                        {uploaded ? "Install the registry version" : "Change version"}
                                                     </Button>
                                                     <Button variant="text" type="button" onClick={() => setRemoving(plugin)}>
                                                         Uninstall
@@ -1002,6 +1097,28 @@ export default function PluginsManager({ embedded = false }: PluginsManagerProps
                     }}
                 />
             )}
+            {replacing && (
+                <Modal open onClose={() => setReplacing(null)} title="Replace plugin?">
+                    <p className="text-sm mb-2">{replacing.question}</p>
+                    <p className="text-sm text-text-muted mb-4 break-words">{replacing.reason}</p>
+                    <div className="flex gap-2 justify-end">
+                        <Button type="button" variant="secondary" className="!w-auto" onClick={() => setReplacing(null)}>
+                            Cancel
+                        </Button>
+                        <Button
+                            type="button"
+                            className="!w-auto"
+                            onClick={() => {
+                                const { file } = replacing;
+                                setReplacing(null);
+                                void runUpload(file, true);
+                            }}
+                        >
+                            Replace
+                        </Button>
+                    </div>
+                </Modal>
+            )}
             {confirming && (
                 <ConfirmDependenciesModal
                     change={confirming}
@@ -1570,15 +1687,20 @@ function ChangeVersionModal({
     const [selected, setSelected] = useState(plugin.packageVersion);
     const [error, setError] = useState<string | null>(null);
     const [busy, setBusy] = useState(false);
+    // An uploaded pack isn't a registry version, so any registry version is a change from it - the newest is offered first.
+    const uploaded: boolean = plugin.source === "upload";
 
     useEffect(() => {
         lookupPluginPackage(plugin.name, undefined, { prerelease })
             .then((found) => {
                 setVersions(found.package.versions);
                 setLatest(found.package.latest);
+                if (uploaded && found.package.latest) {
+                    setSelected(found.package.latest);
+                }
             })
             .catch((err) => setError(errorMessage(err, "Could not load the available versions.")));
-    }, [plugin.name, prerelease]);
+    }, [plugin.name, prerelease, uploaded]);
 
     async function save() {
         setBusy(true);
@@ -1591,12 +1713,17 @@ function ChangeVersionModal({
     }
 
     return (
-        <Modal open onClose={onClose} title={`${plugin.manifest.displayName} version`}>
+        <Modal open onClose={onClose} title={uploaded ? `Install the registry version of ${plugin.manifest.displayName}` : `${plugin.manifest.displayName} version`}>
             {error && <Alert>{error}</Alert>}
             {versions === null ? (
                 !error && <p className="text-sm text-text-muted">Loading&hellip;</p>
             ) : (
                 <div className="flex flex-col gap-3">
+                    {uploaded && (
+                        <p className="text-sm text-text-muted">
+                            {plugin.manifest.displayName} {plugin.packageVersion} was uploaded as {plugin.uploadFilename}. This replaces it with the version from the registry.
+                        </p>
+                    )}
                     <label className="flex flex-col gap-1.5 text-sm">
                         <span className="font-semibold">Version</span>
                         <select aria-label="Version" className={INPUT_CLASS} value={selected} onChange={(e) => setSelected(e.target.value)}>
@@ -1604,7 +1731,7 @@ function ChangeVersionModal({
                                 <option key={version} value={version}>
                                     {version}
                                     {version === latest ? " (latest)" : ""}
-                                    {version === plugin.packageVersion ? " (installed)" : ""}
+                                    {!uploaded && version === plugin.packageVersion ? " (installed)" : ""}
                                 </option>
                             ))}
                         </select>
@@ -1617,10 +1744,10 @@ function ChangeVersionModal({
                             type="button"
                             className="!w-auto"
                             loading={busy}
-                            disabled={busy || selected === plugin.packageVersion}
+                            disabled={busy || (!uploaded && selected === plugin.packageVersion)}
                             onClick={() => void save()}
                         >
-                            Save
+                            {uploaded ? "Install" : "Save"}
                         </Button>
                     </div>
                 </div>

package/dist/apps/shared/components/admin/diagnostics/InformationPanel.js

@@ -12,5 +12,5 @@ import SettingsTable from "./SettingsTable.js";
  */
 export default function InformationPanel({ versions, plugins, information }) {
     const { data, error, loading } = versions;
-    return (_jsxs("div", { className: "space-y-6", children: [error && _jsx(Alert, { children: error }), !data && loading && _jsx("p", { className: "text-sm text-text-muted", children: "Loading\u2026" }), data && (_jsxs(_Fragment, { children: [_jsx(ServerVersionCard, { server: data.server }), _jsx(ComponentsTable, { components: data.components ?? [], kubernetes: data.kubernetes ?? { available: false } }), _jsx(InstalledPlugins, { data: plugins.data, error: plugins.error, loading: plugins.loading }), information.error && _jsx(Alert, { children: information.error }), !information.data && information.loading && _jsx("p", { className: "text-sm text-text-muted", children: "Loading the environment\u2026" }), information.data && (_jsxs(_Fragment, { children: [_jsx(SettingsTable, { id: "diagnostics-environment", title: "Environment variables", description: "The server process's environment. Only variables known to be harmless show their value; the value of a secret, or of anything unrecognized, is withheld by the server and never sent.", settings: information.data.environment ?? [] }), _jsx(SettingsTable, { id: "diagnostics-configuration", title: "Configuration", description: "The effective settings the server runs with: the environment, saved plugin settings and defaults combined. Passwords, tokens, keys, certificates and the credentials in URLs are withheld by the server and never sent.", settings: information.data.configuration ?? [] })] })), _jsx(PackagesTable, { packages: data.packages ?? [] })] }))] }));
+    return (_jsxs("div", { className: "space-y-6", children: [error && _jsx(Alert, { children: error }), !data && loading && _jsx("p", { className: "text-sm text-text-muted", children: "Loading\u2026" }), data && (_jsxs(_Fragment, { children: [_jsx(ServerVersionCard, { server: data.server }), _jsx(ComponentsTable, { components: data.components ?? [], kubernetes: data.kubernetes ?? { available: false } }), _jsx(InstalledPlugins, { data: plugins.data, error: plugins.error, loading: plugins.loading }), information.error && _jsx(Alert, { children: information.error }), !information.data && information.loading && _jsx("p", { className: "text-sm text-text-muted", children: "Loading the environment\u2026" }), information.data && (_jsxs(_Fragment, { children: [_jsx(SettingsTable, { id: "diagnostics-environment", title: "Environment variables", description: "The server process's environment. Every variable shows its value except those on the server's list of hidden settings, whose value is withheld by the server and never sent.", settings: information.data.environment ?? [] }), _jsx(SettingsTable, { id: "diagnostics-configuration", title: "Configuration", description: "The effective settings the server runs with: the environment, saved plugin settings and defaults combined. Settings on the server's list of hidden settings, such as passwords, tokens and keys, are withheld by the server and never sent, and so are the credentials in URLs.", settings: information.data.configuration ?? [] })] })), _jsx(PackagesTable, { packages: data.packages ?? [] })] }))] }));
 }

package/dist/apps/shared/components/admin/diagnostics/diagnosticsApi.d.ts

@@ -63,8 +63,8 @@ export interface DiagnosticsVersions {
     };
 }
 /**
- * One environment variable or configuration setting. A `redacted` one has no `value`: the server withholds every secret-like
- * or unrecognized value and never sends it, so there is nothing for the client to hide.
+ * One environment variable or configuration setting. A `redacted` one has no `value`: the server withholds the value of every setting on its
+ * hidden list and never sends it, so there is nothing for the client to hide.
  */
 export interface DiagnosticsSetting {
     name: string;

package/dist/apps/shared/components/admin/settings/PluginsManager.js

@@ -4,7 +4,8 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
 import { useCallback, useEffect, useId, useRef, useState } from "react";
-import { addPlugin, expectedPlanOf, getPluginStatus, getPluginUpdates, isSecretSetting, isSecretSettingKey, listPluginNamespaces, listPlugins, lookupPluginPackage, planPluginChange, removePlugin, retryPluginPurge, searchPlugins, updatePlugin, } from "../../../../../lib/admin/pluginsApi.js";
+import { addPlugin, expectedPlanOf, getPluginStatus, getPluginUpdates, isSecretSetting, isSecretSettingKey, listPluginNamespaces, listPlugins, lookupPluginPackage, planPluginChange, removePlugin, retryPluginPurge, searchPlugins, updatePlugin, uploadPlugin, } from "../../../../../lib/admin/pluginsApi.js";
+import { ApiRequestError } from "../../../../../lib/util/api.js";
 import Alert from "../ActionAlert.js";
 import Button from "../../../../../lib/components/buttons/Button.js";
 import Modal from "../../../../../lib/components/overlays/Modal.js";
@@ -43,6 +44,10 @@ function purgeFailure(purge) {
 }
 /** A day, in the administrator's own format. */
 const formatDate = (iso) => new Date(iso).toLocaleDateString(undefined, { dateStyle: "medium" });
+/** The file names an uploaded plugin may have: what `npm pack` produces (`<name>-<version>.tgz`), or the same gzipped. */
+const PLUGIN_PACK_NAME = /\.(tgz|tar\.gz|gz)$/i;
+/** What the server answers (409) an upload of a plugin that is already installed, which the administrator may replace. */
+const ALREADY_INSTALLED = /already installed/i;
 const BULK_WORDS = {
     upgrade: { doing: "Upgrading", done: "upgraded" },
     disable: { doing: "Disabling", done: "disabled" },
@@ -136,6 +141,11 @@ export default function PluginsManager({ embedded = false } = {}) {
     const [confirmingBulkUninstall, setConfirmingBulkUninstall] = useState(null);
     /** How many changes (or the lookups that come before them) are waiting on the server. */
     const [working, setWorking] = useState(0);
+    /** Set while an uploaded plugin is being sent to the server. */
+    const [uploading, setUploading] = useState(false);
+    /** An upload that would replace an installed plugin, waiting for the administrator to confirm it. */
+    const [replacing, setReplacing] = useState(null);
+    const fileInput = useRef(null);
     const statusRequest = useRef(null);
     /** The state each data deletion was last seen in, so a notification is raised when one that was under way ends. */
     const seenPurges = useRef(new Map());
@@ -373,6 +383,55 @@ export default function PluginsManager({ embedded = false } = {}) {
     function upgrade(plugin, packageVersion) {
         return onRow(plugin, () => changeVersion(plugin, packageVersion));
     }
+    /** Sends `file` to the server as a plugin to install - replacing the installed plugin of that name only when `replace` is set. A plugin that is
+     * already installed isn't an error but a question, asked of the administrator before it is replaced. */
+    async function runUpload(file, replace) {
+        setUploading(true);
+        setError(null);
+        setRetryEnableUid(null);
+        try {
+            const uploaded = await track(uploadPlugin(file, { replace }));
+            applied(uploaded);
+            notify({
+                kind: "success",
+                title: `${uploaded.name}@${uploaded.packageVersion} uploaded`,
+                message: "The servers restart one at a time to load it.",
+            });
+        }
+        catch (err) {
+            if (!replace && err instanceof ApiRequestError && err.status === 409 && ALREADY_INSTALLED.test(err.message)) {
+                const installed = plugins.find((plugin) => err.message.includes(plugin.name));
+                setReplacing({
+                    file,
+                    question: installed
+                        ? `Replace ${installed.name} ${installed.packageVersion} with the uploaded pack?`
+                        : "Replace the installed plugin with the uploaded pack?",
+                    reason: err.message,
+                });
+            }
+            else if (err instanceof ApiRequestError && err.status === 413) {
+                setError("That file is too large for the server to accept.");
+            }
+            else {
+                setError(errorMessage(err, "Could not upload the plugin."));
+            }
+        }
+        setUploading(false);
+    }
+    /** Takes the file the administrator chose, unless it can't be what `npm pack` produces. */
+    function onFileChosen(e) {
+        const file = e.target.files?.[0];
+        // So choosing the same file again (after fixing what was wrong) still counts as a change.
+        e.target.value = "";
+        if (!file) {
+            return;
+        }
+        if (!PLUGIN_PACK_NAME.test(file.name)) {
+            setError(`${file.name} isn't a plugin pack. Choose the .tgz file that npm pack produces.`);
+            return;
+        }
+        void runUpload(file, false);
+    }
     /** Installs an uninstalled plugin again, at its latest version - as adding it by name would. */
     function reinstall(purge) {
         const displayName = purgeName(purge);
@@ -523,9 +582,10 @@ export default function PluginsManager({ embedded = false } = {}) {
     const retryEnable = plugins.find((plugin) => plugin.uid === retryEnableUid && !plugin.enabled);
     const displayNameOf = (name) => plugins.find((plugin) => plugin.name === name)?.manifest.displayName ?? name;
     const SectionHeading = embedded ? "h3" : "h2";
-    const addButton = (_jsx(Button, { type: "button", variant: "secondary", className: "!w-auto shrink-0", onClick: () => setAdding(true), children: "Add by name" }));
     const bulkBusy = bulk !== null;
-    return (_jsxs(_Fragment, { children: [(working > 0 || pending) && _jsx(PluginProgressBar, { label: working > 0 ? "Working on plugins" : "Applying plugin changes" }), embedded ? (_jsx("p", { className: "text-sm text-text-muted mb-5 max-w-3xl", children: "Changes are applied by restarting the servers one at a time, so mail keeps flowing. Plugins run with full access to the server, so only add ones you trust." })) : (_jsxs(_Fragment, { children: [_jsxs("div", { className: "flex items-center justify-between gap-4 mb-2", children: [_jsx("h1", { className: "text-xl font-bold uppercase tracking-wide", children: "Plugins" }), addButton] }), _jsx("p", { className: "text-sm text-text-muted mb-6 max-w-3xl", children: "Plugins add protocols and features to every server. Changes are applied by restarting the servers one at a time, so mail keeps flowing. Plugins run with full access to the server, so only add ones you trust." })] })), _jsxs("label", { className: "flex items-start gap-2 text-sm mb-5 max-w-3xl cursor-pointer", children: [_jsx("input", { type: "checkbox", className: "mt-0.5 h-4 w-4 shrink-0", checked: allowPrerelease, onChange: (e) => changePrerelease(e.target.checked) }), _jsxs("span", { className: "flex flex-col gap-0.5", children: [_jsx("span", { className: "font-semibold", children: "Allow pre-release versions" }), _jsx("span", { className: "text-xs text-text-muted", children: "Also offer beta and other pre-release builds, such as 1.0.0-beta.2, as updates and as versions to install. They can be unstable. This is remembered in this browser." })] })] }), bulkFailure && (_jsx(Alert, { children: _jsxs("div", { children: [bulkFailure.title, _jsx("ul", { className: "list-disc pl-5 mt-1", children: bulkFailure.reasons.map((reason) => (_jsx("li", { className: "break-words", children: reason }, reason))) })] }) })), error && (_jsxs(Alert, { children: [error, retryEnable && (_jsxs(_Fragment, { children: [" ", _jsx(Button, { type: "button", variant: "text", className: "!w-auto !p-0", onClick: () => void toggle(retryEnable), children: "Try again" })] }))] })), _jsx(RolloutBanner, { status: status }), statusStale && status && (_jsx("p", { className: "mb-4 text-xs text-text-muted", children: "Couldn't refresh server status. Showing the last status reported." })), listStale && (_jsxs("p", { className: "mb-4 text-xs text-text-muted", children: ["Couldn't re-read the plugin list, so it may be out of date.", " ", _jsx(Button, { type: "button", variant: "text", className: "!w-auto !p-0 !text-xs", onClick: () => void reload(), children: "Retry" })] })), _jsxs("div", { className: "flex items-center justify-between gap-4 mb-2", children: [_jsx(SectionHeading, { className: "text-sm font-bold uppercase tracking-wide", children: "Installed plugins" }), embedded && addButton] }), loading ? (_jsx("p", { className: "text-sm text-text-muted", children: "Loading\u2026" })) : plugins.length === 0 && purges.length === 0 ? (_jsx("p", { className: "text-sm text-text-muted", children: "No plugins installed." })) : (_jsxs("div", { className: "overflow-x-auto", children: [plugins.length > 0 && (_jsxs("div", { role: "toolbar", "aria-label": "Actions for several plugins", className: "flex flex-wrap items-center gap-2 py-2", children: [_jsxs("label", { className: "flex items-center gap-2 text-sm mr-2 cursor-pointer", children: [_jsx("input", { type: "checkbox", className: "h-4 w-4 shrink-0", "aria-label": "Select all plugins", checked: allSelected, disabled: bulkBusy, ref: (input) => {
+    const addButton = (_jsxs("div", { className: "flex flex-wrap gap-2 shrink-0", children: [_jsx("input", { ref: fileInput, type: "file", className: "hidden", accept: ".tgz,.tar.gz,application/gzip,application/x-gzip", "aria-label": "Plugin pack file", tabIndex: -1, onChange: onFileChosen }), _jsx(Button, { type: "button", variant: "secondary", className: "!w-auto", title: "Install a plugin from the .tgz file that npm pack produces", loading: uploading, disabled: uploading || bulkBusy, onClick: () => fileInput.current?.click(), children: uploading ? "Uploading\u2026" : "Upload" }), _jsx(Button, { type: "button", variant: "secondary", className: "!w-auto", onClick: () => setAdding(true), children: "Add by name" })] }));
+    return (_jsxs(_Fragment, { children: [(working > 0 || pending) && _jsx(PluginProgressBar, { label: working > 0 ? "Working on plugins" : "Applying plugin changes" }), embedded ? (_jsx("p", { className: "text-sm text-text-muted mb-5 max-w-3xl", children: "Changes are applied by restarting the servers one at a time, so mail keeps flowing. Plugins run with full access to the server, so only add ones you trust." })) : (_jsxs(_Fragment, { children: [_jsxs("div", { className: "flex items-center justify-between gap-4 mb-2", children: [_jsx("h1", { className: "text-xl font-bold uppercase tracking-wide", children: "Plugins" }), addButton] }), _jsx("p", { className: "text-sm text-text-muted mb-6 max-w-3xl", children: "Plugins add protocols and features to every server. Changes are applied by restarting the servers one at a time, so mail keeps flowing. Plugins run with full access to the server, so only add ones you trust." })] })), _jsxs("label", { className: "flex items-start gap-2 text-sm mb-5 max-w-3xl cursor-pointer", children: [_jsx("input", { type: "checkbox", className: "mt-0.5 h-4 w-4 shrink-0", checked: allowPrerelease, onChange: (e) => changePrerelease(e.target.checked) }), _jsxs("span", { className: "flex flex-col gap-0.5", children: [_jsx("span", { className: "font-semibold", children: "Allow pre-release versions" }), _jsx("span", { className: "text-xs text-text-muted", children: "Also offer beta and other pre-release builds, such as 1.0.0-beta.2, as updates and as versions to install. They can be unstable. This is remembered in this browser." })] })] }), bulkFailure && (_jsx(Alert, { children: _jsxs("div", { children: [bulkFailure.title, _jsx("ul", { className: "list-disc pl-5 mt-1", children: bulkFailure.reasons.map((reason) => (_jsx("li", { className: "break-words", children: reason }, reason))) })] }) })), error &&
+                (retryEnable ? (_jsxs(Alert, { children: [error, " ", _jsx(Button, { type: "button", variant: "text", className: "!w-auto !p-0", onClick: () => void toggle(retryEnable), children: "Try again" })] })) : (_jsx(Alert, { children: error }))), _jsx(RolloutBanner, { status: status }), statusStale && status && (_jsx("p", { className: "mb-4 text-xs text-text-muted", children: "Couldn't refresh server status. Showing the last status reported." })), listStale && (_jsxs("p", { className: "mb-4 text-xs text-text-muted", children: ["Couldn't re-read the plugin list, so it may be out of date.", " ", _jsx(Button, { type: "button", variant: "text", className: "!w-auto !p-0 !text-xs", onClick: () => void reload(), children: "Retry" })] })), _jsxs("div", { className: "flex items-center justify-between gap-4 mb-2", children: [_jsx(SectionHeading, { className: "text-sm font-bold uppercase tracking-wide", children: "Installed plugins" }), embedded && addButton] }), loading ? (_jsx("p", { className: "text-sm text-text-muted", children: "Loading\u2026" })) : plugins.length === 0 && purges.length === 0 ? (_jsx("p", { className: "text-sm text-text-muted", children: "No plugins installed." })) : (_jsxs("div", { className: "overflow-x-auto", children: [plugins.length > 0 && (_jsxs("div", { role: "toolbar", "aria-label": "Actions for several plugins", className: "flex flex-wrap items-center gap-2 py-2", children: [_jsxs("label", { className: "flex items-center gap-2 text-sm mr-2 cursor-pointer", children: [_jsx("input", { type: "checkbox", className: "h-4 w-4 shrink-0", "aria-label": "Select all plugins", checked: allSelected, disabled: bulkBusy, ref: (input) => {
                                             if (input) {
                                                 input.indeterminate = selectedPlugins.length > 0 && !allSelected;
                                             }
@@ -533,13 +593,15 @@ export default function PluginsManager({ embedded = false } = {}) {
                                     versions: new Map(selectedUpgrades.map((plugin) => [plugin.uid, updates.get(plugin.uid).latestVersion])),
                                 }), children: ["Upgrade", selectedUpgrades.length > 0 ? ` (${selectedUpgrades.length})` : ""] }), _jsxs(Button, { type: "button", variant: "secondary", className: "!w-auto", "aria-label": "Disable selected plugins", disabled: bulkBusy || selectedEnabled.length === 0, onClick: () => void runBulk("disable", selectedEnabled), children: ["Disable", selectedEnabled.length > 0 ? ` (${selectedEnabled.length})` : ""] }), _jsxs(Button, { type: "button", variant: "secondary", className: "!w-auto", "aria-label": "Uninstall selected plugins", disabled: bulkBusy || selectedPlugins.length === 0, onClick: () => setConfirmingBulkUninstall(selectedPlugins), children: ["Uninstall", selectedPlugins.length > 0 ? ` (${selectedPlugins.length})` : ""] }), _jsx(Button, { type: "button", className: "!w-auto ml-auto", "aria-label": "Upgrade all plugins", loading: bulk?.kind === "upgrade", disabled: bulkBusy, onClick: () => void upgradeAll(), children: "Upgrade all" }), bulk && (_jsxs("span", { "aria-live": "polite", className: "basis-full text-xs text-text-muted", children: [BULK_WORDS[bulk.kind].doing, " ", bulk.current, " (", bulk.done + 1, " of ", bulk.total, ")\u2026"] }))] })), _jsxs("table", { role: "table", className: "w-full text-sm border-collapse block lg:table", children: [_jsx("thead", { role: "rowgroup", className: "hidden lg:table-header-group", children: _jsxs("tr", { role: "row", children: [_jsx("th", { role: "columnheader", className: TH_CLASS, children: "Plugin" }), _jsx("th", { role: "columnheader", className: TH_CLASS, children: "Version" }), _jsx("th", { role: "columnheader", className: TH_CLASS, children: "Status" }), _jsx("th", { role: "columnheader", className: TH_CLASS, children: _jsx("span", { className: "sr-only", children: "Actions" }) })] }) }), _jsxs("tbody", { role: "rowgroup", className: "block lg:table-row-group", children: [plugins.map((plugin) => {
                                         const update = updates.get(plugin.uid);
-                                        const latest = update?.updateAvailable ? update.latestVersion : undefined;
+                                        const uploaded = plugin.source === "upload";
+                                        // An uploaded pack has no registry version to be newer than.
+                                        const latest = !uploaded && update?.updateAvailable ? update.latestVersion : undefined;
                                         const busy = busyUids.has(plugin.uid) || confirming?.uid === plugin.uid || bulkBusy;
                                         const requires = Object.keys(plugin.manifest.requires ?? {}).map(displayNameOf);
                                         const requiredBy = plugins
                                             .filter((other) => other.uid !== plugin.uid && other.manifest.requires?.[plugin.name] !== undefined)
                                             .map((other) => other.manifest.displayName);
-                                        return (_jsxs("tr", { role: "row", className: INSTALLED_ROW_CLASS, children: [_jsx("td", { role: "cell", className: `${INSTALLED_TD_CLASS} basis-full pt-3 pb-2`, children: _jsxs("div", { className: "flex items-start gap-3", children: [_jsx("input", { type: "checkbox", className: "mt-1 h-4 w-4 shrink-0", "aria-label": `Select ${plugin.manifest.displayName}`, checked: selected.has(plugin.uid), disabled: bulkBusy, onChange: () => toggleSelected(plugin.uid) }), _jsxs("div", { className: "min-w-0", children: [_jsx("div", { className: "font-semibold", children: plugin.manifest.displayName }), _jsx("div", { className: "text-xs text-text-muted", children: plugin.name }), plugin.manifest.description && (_jsx("div", { className: "text-xs text-text-muted mt-1 max-w-md", children: plugin.manifest.description })), requires.length > 0 && _jsxs("div", { className: "text-xs text-text-muted mt-1", children: ["Requires: ", requires.join(", ")] }), requiredBy.length > 0 && (_jsxs("div", { className: "text-xs text-text-muted mt-1", children: ["Required by: ", requiredBy.join(", ")] }))] })] }) }), _jsxs("td", { role: "cell", className: `${INSTALLED_TD_CLASS} pt-1 pb-1 whitespace-nowrap`, children: [_jsx("div", { children: plugin.packageVersion }), latest && _jsxs("div", { className: "mt-1 text-xs font-semibold text-primary-dark", children: ["Update available: ", latest] })] }), _jsx("td", { role: "cell", className: `${INSTALLED_TD_CLASS} pt-1 pb-1`, children: _jsx(PluginStatusCell, { plugin: plugin, status: status }) }), _jsx("td", { role: "cell", className: `${INSTALLED_TD_CLASS} basis-full pt-2 pb-3`, children: _jsxs("div", { className: "flex flex-col items-start gap-1.5 lg:items-end lg:min-w-[11rem]", children: [_jsxs("div", { className: "flex flex-wrap gap-2 lg:justify-end", children: [latest && (_jsx(Button, { type: "button", variant: "secondary", className: "!w-auto", "aria-label": `Upgrade ${plugin.manifest.displayName} to ${latest}`, disabled: busy, onClick: () => void upgrade(plugin, latest), children: "Upgrade" })), (plugin.manifest.settings ?? []).length > 0 && (_jsx(Button, { variant: "secondary", type: "button", className: "!w-auto", onClick: () => setConfiguring(plugin), children: "Settings" })), _jsx(Button, { variant: plugin.enabled ? "secondary" : "primary", type: "button", className: "!w-auto min-w-[5.5rem]", "aria-label": `${plugin.enabled ? "Disable" : "Enable"} ${plugin.manifest.displayName}`, disabled: busy, onClick: () => void toggle(plugin), children: plugin.enabled ? "Disable" : "Enable" })] }), _jsxs("div", { className: "flex flex-wrap gap-x-4 lg:justify-end", children: [_jsx(Button, { variant: "text", type: "button", onClick: () => setUpgrading(plugin), children: "Change version" }), _jsx(Button, { variant: "text", type: "button", onClick: () => setRemoving(plugin), children: "Uninstall" })] })] }) })] }, plugin.uid));
+                                        return (_jsxs("tr", { role: "row", className: INSTALLED_ROW_CLASS, children: [_jsx("td", { role: "cell", className: `${INSTALLED_TD_CLASS} basis-full pt-3 pb-2`, children: _jsxs("div", { className: "flex items-start gap-3", children: [_jsx("input", { type: "checkbox", className: "mt-1 h-4 w-4 shrink-0", "aria-label": `Select ${plugin.manifest.displayName}`, checked: selected.has(plugin.uid), disabled: bulkBusy, onChange: () => toggleSelected(plugin.uid) }), _jsxs("div", { className: "min-w-0", children: [_jsx("div", { className: "font-semibold", children: plugin.manifest.displayName }), _jsx("div", { className: "text-xs text-text-muted", children: plugin.name }), plugin.manifest.description && (_jsx("div", { className: "text-xs text-text-muted mt-1 max-w-md", children: plugin.manifest.description })), uploaded && (_jsxs("div", { className: "text-xs text-text-muted mt-1 break-words", children: [_jsx("span", { className: `${BADGE_CLASS} bg-surface-alt text-text-muted`, children: "Uploaded" }), " ", plugin.uploadFilename, plugin.uploadedAt ? `, ${formatDate(plugin.uploadedAt)}` : ""] })), requires.length > 0 && _jsxs("div", { className: "text-xs text-text-muted mt-1", children: ["Requires: ", requires.join(", ")] }), requiredBy.length > 0 && (_jsxs("div", { className: "text-xs text-text-muted mt-1", children: ["Required by: ", requiredBy.join(", ")] }))] })] }) }), _jsxs("td", { role: "cell", className: `${INSTALLED_TD_CLASS} pt-1 pb-1 whitespace-nowrap`, children: [_jsx("div", { children: plugin.packageVersion }), latest && _jsxs("div", { className: "mt-1 text-xs font-semibold text-primary-dark", children: ["Update available: ", latest] })] }), _jsx("td", { role: "cell", className: `${INSTALLED_TD_CLASS} pt-1 pb-1`, children: _jsx(PluginStatusCell, { plugin: plugin, status: status }) }), _jsx("td", { role: "cell", className: `${INSTALLED_TD_CLASS} basis-full pt-2 pb-3`, children: _jsxs("div", { className: "flex flex-col items-start gap-1.5 lg:items-end lg:min-w-[11rem]", children: [_jsxs("div", { className: "flex flex-wrap gap-2 lg:justify-end", children: [latest && (_jsx(Button, { type: "button", variant: "secondary", className: "!w-auto", "aria-label": `Upgrade ${plugin.manifest.displayName} to ${latest}`, disabled: busy, onClick: () => void upgrade(plugin, latest), children: "Upgrade" })), (plugin.manifest.settings ?? []).length > 0 && (_jsx(Button, { variant: "secondary", type: "button", className: "!w-auto", onClick: () => setConfiguring(plugin), children: "Settings" })), _jsx(Button, { variant: plugin.enabled ? "secondary" : "primary", type: "button", className: "!w-auto min-w-[5.5rem]", "aria-label": `${plugin.enabled ? "Disable" : "Enable"} ${plugin.manifest.displayName}`, disabled: busy, onClick: () => void toggle(plugin), children: plugin.enabled ? "Disable" : "Enable" })] }), _jsxs("div", { className: "flex flex-wrap gap-x-4 lg:justify-end", children: [_jsx(Button, { variant: "text", type: "button", onClick: () => setUpgrading(plugin), children: uploaded ? "Install the registry version" : "Change version" }), _jsx(Button, { variant: "text", type: "button", onClick: () => setRemoving(plugin), children: "Uninstall" })] })] }) })] }, plugin.uid));
                                     }), purges.map((purge) => (_jsx(UninstalledPluginRow, { purge: purge, busy: busyUids.has(purge.uid), onRetry: () => void retryPurge(purge), onInstall: () => void reinstall(purge) }, purge.uid)))] })] })] })), _jsx(PluginBrowser, { headingLevel: SectionHeading, plugins: plugins, prerelease: allowPrerelease, onInstall: (result) => install(result.name, result.version, result.name), 
                 // The browser only offers an upgrade for a result it matched to one of these same `plugins`.
                 onUpgrade: (uid, packageVersion) => upgrade(plugins.find((p) => p.uid === uid), packageVersion) }), _jsx(AddPluginModal, { open: adding, prerelease: allowPrerelease, onClose: () => setAdding(false), onAdd: async (name, packageVersion, displayName) => {
@@ -554,7 +616,11 @@ export default function PluginsManager({ embedded = false } = {}) {
                         setUpgrading(null);
                     }
                     return problem;
-                } })), confirming && (_jsx(ConfirmDependenciesModal, { change: confirming, displayNameOf: displayNameOf, onClose: () => setConfirming(null), onDone: () => setConfirming(null) })), confirmingBulkUninstall && (_jsx(BulkUninstallModal, { plugins: confirmingBulkUninstall, onClose: () => setConfirmingBulkUninstall(null), onConfirm: (purgeData) => {
+                } })), replacing && (_jsxs(Modal, { open: true, onClose: () => setReplacing(null), title: "Replace plugin?", children: [_jsx("p", { className: "text-sm mb-2", children: replacing.question }), _jsx("p", { className: "text-sm text-text-muted mb-4 break-words", children: replacing.reason }), _jsxs("div", { className: "flex gap-2 justify-end", children: [_jsx(Button, { type: "button", variant: "secondary", className: "!w-auto", onClick: () => setReplacing(null), children: "Cancel" }), _jsx(Button, { type: "button", className: "!w-auto", onClick: () => {
+                                    const { file } = replacing;
+                                    setReplacing(null);
+                                    void runUpload(file, true);
+                                }, children: "Replace" })] })] })), confirming && (_jsx(ConfirmDependenciesModal, { change: confirming, displayNameOf: displayNameOf, onClose: () => setConfirming(null), onDone: () => setConfirming(null) })), confirmingBulkUninstall && (_jsx(BulkUninstallModal, { plugins: confirmingBulkUninstall, onClose: () => setConfirmingBulkUninstall(null), onConfirm: (purgeData) => {
                     const targets = confirmingBulkUninstall;
                     setConfirmingBulkUninstall(null);
                     void runBulk("uninstall", targets, { purgeData });
@@ -777,14 +843,19 @@ function ChangeVersionModal({ plugin, prerelease, onClose, onSave, }) {
     const [selected, setSelected] = useState(plugin.packageVersion);
     const [error, setError] = useState(null);
     const [busy, setBusy] = useState(false);
+    // An uploaded pack isn't a registry version, so any registry version is a change from it - the newest is offered first.
+    const uploaded = plugin.source === "upload";
     useEffect(() => {
         lookupPluginPackage(plugin.name, undefined, { prerelease })
             .then((found) => {
             setVersions(found.package.versions);
             setLatest(found.package.latest);
+            if (uploaded && found.package.latest) {
+                setSelected(found.package.latest);
+            }
         })
             .catch((err) => setError(errorMessage(err, "Could not load the available versions.")));
-    }, [plugin.name, prerelease]);
+    }, [plugin.name, prerelease, uploaded]);
     async function save() {
         setBusy(true);
         setError(null);
@@ -794,7 +865,7 @@ function ChangeVersionModal({ plugin, prerelease, onClose, onSave, }) {
             setBusy(false);
         }
     }
-    return (_jsxs(Modal, { open: true, onClose: onClose, title: `${plugin.manifest.displayName} version`, children: [error && _jsx(Alert, { children: error }), versions === null ? (!error && _jsx("p", { className: "text-sm text-text-muted", children: "Loading\u2026" })) : (_jsxs("div", { className: "flex flex-col gap-3", children: [_jsxs("label", { className: "flex flex-col gap-1.5 text-sm", children: [_jsx("span", { className: "font-semibold", children: "Version" }), _jsx("select", { "aria-label": "Version", className: INPUT_CLASS, value: selected, onChange: (e) => setSelected(e.target.value), children: versions.map((version) => (_jsxs("option", { value: version, children: [version, version === latest ? " (latest)" : "", version === plugin.packageVersion ? " (installed)" : ""] }, version))) })] }), _jsxs("div", { className: "flex gap-2 justify-end", children: [_jsx(Button, { type: "button", variant: "secondary", className: "!w-auto", onClick: onClose, children: "Cancel" }), _jsx(Button, { type: "button", className: "!w-auto", loading: busy, disabled: busy || selected === plugin.packageVersion, onClick: () => void save(), children: "Save" })] })] }))] }));
+    return (_jsxs(Modal, { open: true, onClose: onClose, title: uploaded ? `Install the registry version of ${plugin.manifest.displayName}` : `${plugin.manifest.displayName} version`, children: [error && _jsx(Alert, { children: error }), versions === null ? (!error && _jsx("p", { className: "text-sm text-text-muted", children: "Loading\u2026" })) : (_jsxs("div", { className: "flex flex-col gap-3", children: [uploaded && (_jsxs("p", { className: "text-sm text-text-muted", children: [plugin.manifest.displayName, " ", plugin.packageVersion, " was uploaded as ", plugin.uploadFilename, ". This replaces it with the version from the registry."] })), _jsxs("label", { className: "flex flex-col gap-1.5 text-sm", children: [_jsx("span", { className: "font-semibold", children: "Version" }), _jsx("select", { "aria-label": "Version", className: INPUT_CLASS, value: selected, onChange: (e) => setSelected(e.target.value), children: versions.map((version) => (_jsxs("option", { value: version, children: [version, version === latest ? " (latest)" : "", !uploaded && version === plugin.packageVersion ? " (installed)" : ""] }, version))) })] }), _jsxs("div", { className: "flex gap-2 justify-end", children: [_jsx(Button, { type: "button", variant: "secondary", className: "!w-auto", onClick: onClose, children: "Cancel" }), _jsx(Button, { type: "button", className: "!w-auto", loading: busy, disabled: busy || (!uploaded && selected === plugin.packageVersion), onClick: () => void save(), children: uploaded ? "Install" : "Save" })] })] }))] }));
 }
 /** Lists the plugins a change also installs or enables, and makes the change once confirmed. */
 function ConfirmDependenciesModal({ change, displayNameOf, onClose, onDone, }) {

package/dist/lib/admin/pluginsApi.d.ts

@@ -64,6 +64,14 @@ export interface Plugin {
      * predates it, which reads as nothing being configured. */
     configured?: Record<string, PluginConfiguredSetting>;
     manifest: PluginManifest;
+    /** Where the installed package came from: the npm registry (also what a server that predates uploads means), or a `.tgz` an administrator uploaded. */
+    source?: "registry" | "upload";
+    /** The name of the uploaded file, for a plugin with `source` `upload`. */
+    uploadFilename?: string;
+    /** ISO time the file was uploaded. */
+    uploadedAt?: string;
+    /** The uid of the administrator who uploaded it. */
+    uploadedByUserUid?: string;
 }
 /** Mirrors `@rapidmx/restapi`'s `RegistryPackageVersion`. `manifest` is a message when the version isn't a
  * loadable plugin. */
@@ -260,6 +268,16 @@ export declare function planPluginChange(name: string, packageVersion?: string,
  * requires first. Refused (409) when a requirement conflicts with an installed plugin's version, or when
  * `expectedPlan` is given and no longer matches what adding it would install and enable. */
 export declare function addPlugin(name: string, packageVersion?: string, expectedPlan?: PluginExpectedPlan, client?: ApiClient): Promise<AddPluginResult>;
+/**
+ * Installs a plugin from `file`, the `.tgz` that `npm pack` produces, instead of from the registry - to try a new version before it is released, or an
+ * alternative distribution. The file's raw bytes are the request body (not multipart); its name travels in the query string. Needs an elevated
+ * administrator (403 `api-104` otherwise) and uploads switched on by the operator (403). Refused with 409 when a plugin of that name is already
+ * installed - unless `replace` is set, which swaps it for the uploaded one - or when a plugin it requires isn't installed; 400 when it isn't a
+ * loadable plugin and 413 when it is too large. Like adding one, it starts a rollout.
+ */
+export declare function uploadPlugin(file: File, options?: {
+    replace?: boolean;
+}, client?: ApiClient): Promise<Plugin>;
 export declare function updatePlugin(uid: string, input: UpdatePluginInput, client?: ApiClient): Promise<Plugin>;
 /**
  * Removes a plugin. Refused (409) while an enabled plugin requires it, as is disabling it with `updatePlugin()`.

package/dist/lib/admin/pluginsApi.js

@@ -8,7 +8,7 @@
  * each server copy installs the new plugin set and restarts itself, one copy at a time, and reports back through
  * `getPluginStatus()`.
  */
-import { withClient } from "../util/api.js";
+import { withClient, withClientRaw } from "../util/api.js";
 /** Whether `value` is the placeholder a saved secret setting is shown as. */
 export function isSecretSetting(value) {
     return typeof value === "object" && value !== null && value.secret === true;
@@ -85,6 +85,20 @@ export function planPluginChange(name, packageVersion, options = {}, client) {
 export function addPlugin(name, packageVersion, expectedPlan, client) {
     return withClient(client, BASE, { method: "POST", body: JSON.stringify({ name, packageVersion, expectedPlan }) });
 }
+/**
+ * Installs a plugin from `file`, the `.tgz` that `npm pack` produces, instead of from the registry - to try a new version before it is released, or an
+ * alternative distribution. The file's raw bytes are the request body (not multipart); its name travels in the query string. Needs an elevated
+ * administrator (403 `api-104` otherwise) and uploads switched on by the operator (403). Refused with 409 when a plugin of that name is already
+ * installed - unless `replace` is set, which swaps it for the uploaded one - or when a plugin it requires isn't installed; 400 when it isn't a
+ * loadable plugin and 413 when it is too large. Like adding one, it starts a rollout.
+ */
+export function uploadPlugin(file, options = {}, client) {
+    const params = new URLSearchParams({ filename: file.name });
+    if (options.replace) {
+        params.set("replace", "true");
+    }
+    return withClientRaw(client, `${BASE}/upload?${params.toString()}`, "POST", file, "application/gzip", "Could not upload the plugin.");
+}
 export function updatePlugin(uid, input, client) {
     return withClient(client, `${BASE}/${encodeURIComponent(uid)}`, { method: "PUT", body: JSON.stringify(input) });
 }

package/lib/admin/pluginsApi.ts

@@ -8,7 +8,7 @@
  * each server copy installs the new plugin set and restarts itself, one copy at a time, and reports back through
  * `getPluginStatus()`.
  */
-import { ApiClient, withClient } from "../util/api.js";
+import { ApiClient, withClient, withClientRaw } from "../util/api.js";
 
 /** Mirrors `@rapidmx/restapi`'s `PluginSettingDefinition`. */
 export interface PluginSettingDefinition {
@@ -78,6 +78,14 @@ export interface Plugin {
      * predates it, which reads as nothing being configured. */
     configured?: Record<string, PluginConfiguredSetting>;
     manifest: PluginManifest;
+    /** Where the installed package came from: the npm registry (also what a server that predates uploads means), or a `.tgz` an administrator uploaded. */
+    source?: "registry" | "upload";
+    /** The name of the uploaded file, for a plugin with `source` `upload`. */
+    uploadFilename?: string;
+    /** ISO time the file was uploaded. */
+    uploadedAt?: string;
+    /** The uid of the administrator who uploaded it. */
+    uploadedByUserUid?: string;
 }
 
 /** Mirrors `@rapidmx/restapi`'s `RegistryPackageVersion`. `manifest` is a message when the version isn't a
@@ -331,6 +339,21 @@ export function addPlugin(
     return withClient(client, BASE, { method: "POST", body: JSON.stringify({ name, packageVersion, expectedPlan }) });
 }
 
+/**
+ * Installs a plugin from `file`, the `.tgz` that `npm pack` produces, instead of from the registry - to try a new version before it is released, or an
+ * alternative distribution. The file's raw bytes are the request body (not multipart); its name travels in the query string. Needs an elevated
+ * administrator (403 `api-104` otherwise) and uploads switched on by the operator (403). Refused with 409 when a plugin of that name is already
+ * installed - unless `replace` is set, which swaps it for the uploaded one - or when a plugin it requires isn't installed; 400 when it isn't a
+ * loadable plugin and 413 when it is too large. Like adding one, it starts a rollout.
+ */
+export function uploadPlugin(file: File, options: { replace?: boolean } = {}, client?: ApiClient): Promise<Plugin> {
+    const params = new URLSearchParams({ filename: file.name });
+    if (options.replace) {
+        params.set("replace", "true");
+    }
+    return withClientRaw(client, `${BASE}/upload?${params.toString()}`, "POST", file, "application/gzip", "Could not upload the plugin.");
+}
+
 export function updatePlugin(uid: string, input: UpdatePluginInput, client?: ApiClient): Promise<Plugin> {
     return withClient(client, `${BASE}/${encodeURIComponent(uid)}`, { method: "PUT", body: JSON.stringify(input) });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rapidmx/web-client",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "RapidMX's webmail and admin console React UI for web-based clients.",
   "type": "module",
   "repository": "https://github.com/rapidmx/web-client",