@rapidmx/web-client 0.37.0 → 0.38.1

package/apps/shared/components/admin/integrations/DnsResolverForm.tsx

@@ -0,0 +1,61 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React from "react";
+import { DnsResolverMode, IntegrationSettings } from "../../../../../lib/admin/integrationsApi.js";
+import IntegrationSectionForm, { SectionField } from "./IntegrationSectionForm.js";
+import { INPUT_CLASS } from "./SecretField.js";
+
+const MODES: Record<DnsResolverMode, string> = {
+    node: "The system resolver",
+    "doh-dnssec": "DNS over HTTPS, with DNSSEC validation",
+};
+
+const FIELDS: Record<string, SectionField> = {
+    mode: { name: "resolver", describe: (mode: DnsResolverMode) => MODES[mode] },
+    dohEndpoint: { name: "DoH endpoint", describe: (url: string) => url },
+};
+
+/** The DNS resolver section: how this server looks up DNS records. */
+export default function DnsResolverForm({ settings, onChange }: { settings: IntegrationSettings; onChange: (settings: IntegrationSettings) => void }) {
+    return (
+        <IntegrationSectionForm
+            section="dnsResolver"
+            title="DNS resolver"
+            description="How this server looks up DNS records: for domain checks and verification, key discovery and mail delivery decisions."
+            consequence="Every DNS check, domain verification and key discovery uses the new resolver as soon as it is saved, and answers already looked up are dropped."
+            fields={FIELDS}
+            settings={settings}
+            onChange={onChange}
+        >
+            {(form) => (
+                <>
+                    <label className="flex flex-col gap-1.5 text-sm">
+                        <span className="font-semibold">Resolver</span>
+                        <select aria-label="Resolver" className={INPUT_CLASS} value={form.value("mode")} onChange={(e) => form.set("mode", e.target.value)}>
+                            {Object.entries(MODES).map(([mode, label]) => (
+                                <option key={mode} value={mode}>
+                                    {label}
+                                </option>
+                            ))}
+                        </select>
+                    </label>
+                    {form.footer("mode")}
+                    <label className="flex flex-col gap-1.5 text-sm">
+                        <span className="font-semibold">DoH endpoint</span>
+                        <input
+                            aria-label="DoH endpoint"
+                            type="url"
+                            className={INPUT_CLASS}
+                            value={form.value("dohEndpoint")}
+                            onChange={(e) => form.set("dohEndpoint", e.target.value)}
+                        />
+                        <span className="text-xs text-text-muted">The DNS over HTTPS service queried, https:// only. Used with DNS over HTTPS.</span>
+                    </label>
+                    {form.footer("dohEndpoint")}
+                </>
+            )}
+        </IntegrationSectionForm>
+    );
+}

package/apps/shared/components/admin/integrations/GiphyForm.tsx

@@ -0,0 +1,59 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React from "react";
+import { IntegrationSettings } from "../../../../../lib/admin/integrationsApi.js";
+import IntegrationSectionForm, { secretSectionField, SectionField } from "./IntegrationSectionForm.js";
+import SecretField from "./SecretField.js";
+
+const FIELDS: Record<string, SectionField> = {
+    enabled: { name: "GIF search", describe: (value) => (value ? "on" : "off") },
+    apiKey: secretSectionField("API key"),
+};
+
+/** The Giphy section: whether GIF search is offered, and the API key it uses. */
+export default function GiphyForm({ settings, onChange }: { settings: IntegrationSettings; onChange: (settings: IntegrationSettings) => void }) {
+    return (
+        <IntegrationSectionForm
+            section="giphy"
+            title="Giphy"
+            description="GIF search in the message editor, through Giphy's API."
+            fields={FIELDS}
+            settings={settings}
+            onChange={onChange}
+        >
+            {(form) => (
+                <>
+                    <label className="flex items-start gap-2 text-sm">
+                        <input
+                            type="checkbox"
+                            className="mt-1"
+                            aria-label="Use Giphy for GIF search"
+                            checked={form.value("enabled")}
+                            onChange={(e) => form.set("enabled", e.target.checked)}
+                        />
+                        <span>
+                            <span className="font-semibold block">Use Giphy for GIF search</span>
+                            <span className="text-xs text-text-muted">Off, the editor offers no GIF search and the key is not used.</span>
+                        </span>
+                    </label>
+                    {form.footer("enabled")}
+                    <div className="flex flex-col gap-1.5 text-sm">
+                        <span className="font-semibold">API key</span>
+                        <SecretField
+                            id="giphy-api-key"
+                            label="API key"
+                            name="API key"
+                            saved={form.secret("apiKey")}
+                            unreadable={form.unreadable("apiKey")}
+                            value={form.value("apiKey")}
+                            onChange={(value) => form.set("apiKey", value)}
+                        />
+                    </div>
+                    {form.footer("apiKey")}
+                </>
+            )}
+        </IntegrationSectionForm>
+    );
+}

package/apps/shared/components/admin/integrations/IntegrationSectionForm.tsx

@@ -0,0 +1,234 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { FormEvent, ReactNode, useState } from "react";
+import {
+    IntegrationSectionName,
+    IntegrationSectionView,
+    IntegrationSettings,
+    IntegrationSource,
+    getIntegrations,
+    isSecretMask,
+    isUnreadableSecret,
+    updateIntegrationSection,
+} from "../../../../../lib/admin/integrationsApi.js";
+import Button from "../../../../../lib/components/buttons/Button.js";
+import { ApiRequestError } from "../../../../../lib/util/api.js";
+import Alert from "../ActionAlert.js";
+import { actionErrorMessage } from "../elevation.js";
+
+/** A field put back to the deployment's value, pending the form's Save. */
+const RESET: unique symbol = Symbol("reset");
+
+/** How a section's form treats one of its fields. */
+export interface SectionField {
+    /** How the field's reset button names it ("Reset API key to the deployment default"). */
+    name: string;
+    /** The deployment's value, in words, for the line beneath the field. */
+    describe: (value: any) => string;
+    /** The form's value for a value of the view, saved here (`admin`) or the deployment's (the value itself when left out). */
+    toForm?: (value: any, source: IntegrationSource) => unknown;
+    /** The form's value as the server shows it, to compare with the saved and the deployment's values (the value itself when left out). */
+    toWire?: (formValue: any) => unknown;
+    /** What saving sends for the form's value, when it differs from `toWire()`'s. */
+    toSend?: (formValue: any) => unknown;
+    /** False when the form's value isn't the deployment's though `toWire()` shows it the same: a secret saved here masked like the deployment's.
+     * Such a value is never taken as edited back to the deployment's (reset), which would drop the secret saved here. */
+    canBeDeployment?: (formValue: any) => boolean;
+}
+
+/** A secret field: no value in the form (it is write-only, `SecretField`), "set" or "none" for the deployment's. */
+export function secretSectionField(name: string): SectionField {
+    return { name, describe: (value) => (isSecretMask(value) ? "set" : "none"), toForm: () => undefined };
+}
+
+/** What a section form's fields are drawn with. */
+export interface SectionForm {
+    /** The field's value in the form. */
+    value(field: string): any;
+    /** Changes the field; `undefined` takes back any change. */
+    set(field: string, value: unknown): void;
+    /** What is saved for a secret field now: nothing, a value saved here, or the deployment's. A pending reset shows the deployment's. */
+    secret(field: string): "none" | "here" | "deployment";
+    /** Whether the secret saved here for the field is one the server can't decrypt, so that it must be entered again. */
+    unreadable(field: string): boolean;
+    /** Whether the form holds a value of the administrator's for the field, rather than the deployment's. */
+    setHere(field: string): boolean;
+    /** The line beneath a field: the deployment's value and, for a field set here, the button that puts it back. */
+    footer(field: string): ReactNode;
+}
+
+/** Whether two values are the same once sent (`undefined` counting as `null`, and a secret's `unreadable` flag, which is only the server's remark, not
+ * counting at all). */
+function same(a: unknown, b: unknown): boolean {
+    const plain = (value: unknown): string => JSON.stringify(value ?? null, (key, inner) => (key === "unreadable" ? undefined : inner));
+    return plain(a) === plain(b);
+}
+
+export interface IntegrationSectionFormProps {
+    section: IntegrationSectionName;
+    title: string;
+    description: ReactNode;
+    /** What a change affects, stated above the Save button. */
+    consequence?: ReactNode;
+    fields: Record<string, SectionField>;
+    settings: IntegrationSettings;
+    onChange: (settings: IntegrationSettings) => void;
+    children: (form: SectionForm) => ReactNode;
+}
+
+/**
+ * One Integrations section's form, following the policy pages: each field shows the deployment's value beneath it and, while the form holds a value
+ * saved here, a "Reset to deployment default" that puts the field back in the form only - Save sends it, with the rest, as `null`. A field is never
+ * saved as a copy of the deployment's value (it would stop following the deployment's configuration): edited back to it, it is reset too. Only what
+ * changes is sent, with the version the settings were read at, so a change made over someone else's is refused rather than overwriting it. A save
+ * the server refuses for want of a recently confirmed identity offers to confirm it again (`ActionAlert`).
+ */
+export default function IntegrationSectionForm({
+    section,
+    title,
+    description,
+    consequence,
+    fields,
+    settings,
+    onChange,
+    children,
+}: IntegrationSectionFormProps) {
+    const view = settings[section] as IntegrationSectionView<any>;
+    const [edits, setEdits] = useState<Record<string, unknown>>({});
+    // Bumped by a save, so the fields start over (a credential being replaced is shown as saved again).
+    const [formKey, setFormKey] = useState(0);
+    const [error, setError] = useState<string | null>(null);
+    const [saving, setSaving] = useState(false);
+    const [saved, setSaved] = useState(false);
+
+    const toForm = (field: string, value: unknown, source: IntegrationSource): unknown => (fields[field].toForm ? fields[field].toForm(value, source) : value);
+    /** The field's change as the server would show it, the deployment's value for a reset. */
+    const wire = (field: string, edit: unknown): unknown => (edit === RESET ? view.defaults[field] : fields[field].toWire ? fields[field].toWire(edit) : edit);
+    /** Whether the field's change puts it back to the deployment's value: a reset, a value left empty (`null`, which the server takes as unset), or the
+     * deployment's own. */
+    const isDeployment = (field: string, edit: unknown): boolean =>
+        edit === RESET ||
+        wire(field, edit) === null ||
+        (same(wire(field, edit), view.defaults[field]) && (fields[field].canBeDeployment?.(edit) ?? true));
+
+    const form: SectionForm = {
+        value: (field) =>
+            field in edits
+                ? edits[field] === RESET
+                    ? toForm(field, view.defaults[field], "deployment")
+                    : edits[field]
+                : toForm(field, view.values[field], view.source[field]),
+        set: (field, value) =>
+            setEdits((current) => {
+                const next = { ...current };
+                if (value === undefined) {
+                    delete next[field];
+                } else {
+                    next[field] = value;
+                }
+                return next;
+            }),
+        secret: (field) => {
+            const reset = edits[field] === RESET;
+            const shown = reset ? view.defaults[field] : view.values[field];
+            const source: IntegrationSource = reset ? "deployment" : view.source[field];
+            return !isSecretMask(shown) ? "none" : source === "admin" ? "here" : "deployment";
+        },
+        unreadable: (field) => edits[field] !== RESET && view.source[field] === "admin" && isUnreadableSecret(view.values[field]),
+        setHere: (field) =>
+            field in edits
+                ? !isDeployment(field, edits[field])
+                : // A registry elsewhere than the deployment's shows its token as none set here (restapi's view): nothing to reset.
+                  view.source[field] === "admin" && view.values[field] !== null,
+        footer: (field) => (
+            <div className="flex flex-wrap items-center gap-x-3 text-xs text-text-muted -mt-1">
+                <span>Deployment default: {fields[field].describe(view.defaults[field])}</span>
+                {form.setHere(field) && (
+                    <Button
+                        type="button"
+                        variant="text"
+                        className="text-xs"
+                        aria-label={`Reset ${fields[field].name} to the deployment default`}
+                        onClick={() => form.set(field, RESET)}
+                    >
+                        Reset to deployment default
+                    </Button>
+                )}
+            </div>
+        ),
+    };
+
+    async function handleSubmit(e: FormEvent) {
+        e.preventDefault();
+        setError(null);
+        setSaved(false);
+        const patch: Record<string, unknown> = {};
+        for (const [field, edit] of Object.entries(edits)) {
+            const value: unknown = wire(field, edit);
+            const admin: boolean = view.source[field] === "admin";
+            if (isDeployment(field, edit)) {
+                // Back to the deployment's value: nothing to send unless one is saved here.
+                if (admin) {
+                    patch[field] = null;
+                }
+            } else if (!admin || !same(value, view.values[field])) {
+                patch[field] = fields[field].toSend ? fields[field].toSend(edit) : value;
+            }
+        }
+        if (Object.keys(patch).length === 0) {
+            setEdits({});
+            setSaved(true);
+            return;
+        }
+        setSaving(true);
+        try {
+            onChange(await updateIntegrationSection(section, { ...patch, version: settings.version }));
+            setEdits({});
+            setFormKey((key) => key + 1);
+            setSaved(true);
+        } catch (err) {
+            setError(await refusalMessage(err));
+        } finally {
+            setSaving(false);
+        }
+    }
+
+    /** What a failed save says. A change refused for a newer version loads the settings again (keeping the entries, which are compared with them when
+     * saving), so that the next Save is made against the version now saved rather than failing the same way until the page is reloaded. */
+    async function refusalMessage(err: unknown): Promise<string> {
+        if (err instanceof ApiRequestError && err.status === 409) {
+            try {
+                const latest: IntegrationSettings = await getIntegrations();
+                if (latest.version !== settings.version) {
+                    onChange(latest);
+                    return "The integration settings were changed by someone else. They are shown as saved now, with your entries kept: check them and save again.";
+                }
+            } catch {
+                // Not loaded: the server's own message stands.
+            }
+        }
+        return actionErrorMessage(err, `Could not save the ${title} settings.`);
+    }
+
+    return (
+        <div className="max-w-xl">
+            <h2 className="text-lg font-bold uppercase tracking-wide mb-1">{title}</h2>
+            <div className="text-sm text-text-muted mb-5">{description}</div>
+
+            {error && <Alert>{error}</Alert>}
+            {saved && !error && <div className="mb-4 text-sm text-success font-medium">Saved.</div>}
+
+            <form onSubmit={handleSubmit} className="flex flex-col gap-4">
+                <React.Fragment key={formKey}>{children(form)}</React.Fragment>
+                {consequence && <p className="text-xs text-text-muted">{consequence}</p>}
+                <div>
+                    <Button type="submit" loading={saving} disabled={saving} className="!w-auto">
+                        Save
+                    </Button>
+                </div>
+            </form>
+        </div>
+    );
+}

package/apps/shared/components/admin/integrations/IntegrationSectionPage.tsx

@@ -0,0 +1,40 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { ReactNode } from "react";
+import { getIntegrations, IntegrationSettings } from "../../../../../lib/admin/integrationsApi.js";
+import { ApiRequestError } from "../../../../../lib/util/api.js";
+import AdminShell, { AdminShellProps } from "../layout/AdminShell.js";
+import LoadedSettingsForm from "../settings/LoadedSettingsForm.js";
+import IntegrationsLayout, { IntegrationArea } from "./IntegrationsLayout.js";
+
+/** What a server from before Integrations (no `system/integrations` route) is shown instead of a bare "Not Found". */
+export const NO_INTEGRATIONS_MESSAGE = "This server doesn't offer Integrations yet. Upgrade it to manage them here.";
+
+/** The integration settings, with a server that has none answering `NO_INTEGRATIONS_MESSAGE`. */
+async function loadIntegrations(): Promise<IntegrationSettings> {
+    try {
+        return await getIntegrations();
+    } catch (err) {
+        throw err instanceof ApiRequestError && err.status === 404 ? new ApiRequestError(NO_INTEGRATIONS_MESSAGE, 404) : err;
+    }
+}
+
+export interface IntegrationSectionPageProps extends Omit<AdminShellProps, "active"> {
+    area: Exclude<IntegrationArea, "dnsProviders">;
+    children: (settings: IntegrationSettings, onChange: (settings: IntegrationSettings) => void) => ReactNode;
+}
+
+/** One Integrations section's page: the console's frame, the Integrations navigation, and the section's form once the settings have loaded. */
+export default function IntegrationSectionPage({ area, children, ...props }: IntegrationSectionPageProps) {
+    return (
+        <AdminShell {...props} active="integrations">
+            <IntegrationsLayout active={area}>
+                <LoadedSettingsForm load={loadIntegrations} loadErrorMessage="Could not load the integrations.">
+                    {children}
+                </LoadedSettingsForm>
+            </IntegrationsLayout>
+        </AdminShell>
+    );
+}

package/apps/shared/components/admin/integrations/IntegrationsLayout.tsx

@@ -0,0 +1,72 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { ReactNode } from "react";
+
+/** The Integrations section's areas, in the order the console shows them. */
+export type IntegrationArea = "dnsProviders" | "giphy" | "stun" | "signingCa" | "dnsResolver" | "pluginRegistry";
+
+export const INTEGRATION_AREAS: readonly { id: IntegrationArea; href: string; label: string; description: string }[] = [
+    {
+        id: "dnsProviders",
+        href: "/admin/integrations/dns-providers",
+        label: "DNS providers",
+        description: "The DNS hosting accounts that publish the DNS records of this server and its domains, so they don't have to be added by hand.",
+    },
+    {
+        id: "giphy",
+        href: "/admin/integrations/giphy",
+        label: "Giphy",
+        description: "GIF search in the message editor.",
+    },
+    {
+        id: "stun",
+        href: "/admin/integrations/stun",
+        label: "STUN servers",
+        description: "How video meetings find a way between participants' networks.",
+    },
+    {
+        id: "signingCa",
+        href: "/admin/integrations/signing-ca",
+        label: "S/MIME signing CA",
+        description: "How people get the certificates that sign their mail.",
+    },
+    {
+        id: "dnsResolver",
+        href: "/admin/integrations/dns-resolver",
+        label: "DNS resolver",
+        description: "How this server looks up DNS records.",
+    },
+    {
+        id: "pluginRegistry",
+        href: "/admin/integrations/plugin-registry",
+        label: "Plugin registry",
+        description: "Where plugins are found and installed from.",
+    },
+];
+
+/** The Integrations heading and the navigation between its areas (`active` is the current one; none on the overview), above the area's page. */
+export default function IntegrationsLayout({ active, children }: { active?: IntegrationArea; children: ReactNode }) {
+    return (
+        <>
+            <h1 className="text-xl font-bold uppercase tracking-wide mb-3">Integrations</h1>
+            <nav aria-label="Integrations" className="flex flex-wrap gap-x-4 gap-y-1 border-b border-border mb-6">
+                {INTEGRATION_AREAS.map((area) => (
+                    <a
+                        key={area.id}
+                        href={area.href}
+                        aria-current={area.id === active ? "page" : undefined}
+                        className={[
+                            "py-2 text-sm font-medium border-b-2 -mb-px",
+                            area.id === active ? "border-primary text-primary-dark" : "border-transparent text-text-muted hover:text-text",
+                        ].join(" ")}
+                    >
+                        {area.label}
+                    </a>
+                ))}
+            </nav>
+            {children}
+        </>
+    );
+}