@marinoscar/platform-web 0.1.0-next.3 → 0.1.0-next.5

package/dist/email/headless/normalize-email-settings.js

@@ -0,0 +1,71 @@
+// =============================================================================
+// Reading a response from an API older than the transports (PP-14.8)
+// =============================================================================
+//
+// `GET /api/email-settings` describes every registered transport (`descriptors`),
+// carries each one's settings (`transports`) and the masked status of each of
+// its secrets (`secretStatuses`). A response from a deployment whose API is
+// older than that carries only the flat `ses*`/`smtp*` fields and the two
+// legacy secret statuses. The page must still draw the two built-in forms for
+// it (the web assets and the API are deployed together, but a rolling update or
+// a cached bundle meets the other version for a while), so this fills in what
+// the old response lacked from what it had. A response that carries the new
+// fields is returned untouched.
+// =============================================================================
+const NO_SECRET = { configured: false, hint: null, updatedAt: null, updatedByUserId: null };
+/** The built-in transports' descriptors, for a response that carried none. */
+const BUILTIN_DESCRIPTORS = [
+    {
+        kind: 'email-transport',
+        id: 'ses',
+        label: 'Amazon SES',
+        fields: [
+            { kind: 'string', name: 'region', label: 'Region' },
+            { kind: 'string', name: 'accessKeyId', label: 'Access Key ID' },
+            { kind: 'secret', name: 'secretAccessKey', label: 'Secret Access Key', hasValue: false, required: true },
+        ],
+    },
+    {
+        kind: 'email-transport',
+        id: 'smtp',
+        label: 'SMTP',
+        fields: [
+            { kind: 'string', name: 'host', label: 'Host' },
+            { kind: 'number', name: 'port', label: 'Port', min: 1, max: 65535, integer: true },
+            { kind: 'boolean', name: 'useTls', label: 'Require TLS' },
+            { kind: 'string', name: 'username', label: 'Username' },
+            { kind: 'secret', name: 'password', label: 'Password', hasValue: false, required: false },
+        ],
+    },
+];
+/**
+ * The response with `transports`, `descriptors` and `secretStatuses` filled in
+ * from the flat fields and the two legacy statuses when the API sent none.
+ *
+ * @param settings - the response.
+ * @returns the same object when it already carries the three fields; otherwise a copy that does.
+ *
+ * @stability experimental
+ */
+export function withTransportDefaults(settings) {
+    if (settings.transports && settings.descriptors && settings.secretStatuses)
+        return settings;
+    return {
+        ...settings,
+        transports: settings.transports ?? {
+            ses: { region: settings.sesRegion ?? '', accessKeyId: settings.sesAccessKeyId ?? '' },
+            smtp: {
+                host: settings.smtpHost ?? '',
+                port: settings.smtpPort ?? 587,
+                useTls: settings.smtpUseTls ?? true,
+                username: settings.smtpUsername ?? '',
+            },
+        },
+        descriptors: settings.descriptors && settings.descriptors.length > 0 ? settings.descriptors : [...BUILTIN_DESCRIPTORS],
+        secretStatuses: settings.secretStatuses ?? {
+            ses: { secretAccessKey: settings.sesSecretAccessKeyStatus ?? NO_SECRET },
+            smtp: { password: settings.smtpPasswordStatus ?? NO_SECRET },
+        },
+    };
+}
+//# sourceMappingURL=normalize-email-settings.js.map

package/dist/email/headless/normalize-email-settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-email-settings.js","sourceRoot":"","sources":["../../../src/email/headless/normalize-email-settings.ts"],"names":[],"mappings":"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"}

package/dist/email/headless/use-email-settings.d.ts

@@ -0,0 +1,95 @@
+import type { EmailProviderKind, EmailSettingsResponse, TestEmailResult, UpdateEmailSettingsInput } from '@marinoscar/platform-contract/email';
+import type { PlatformApiClient } from '../../core/index.js';
+/**
+ * The stored email configuration as `GET /api/email-settings` returns it: the
+ * settings, the masked status of both secrets, the repair message and the row
+ * version.
+ *
+ * @stability experimental
+ */
+export type EmailSettings = EmailSettingsResponse;
+/**
+ * The `PUT /api/email-settings` body. A blank or absent `smtpPassword` /
+ * `sesSecretAccessKey` keeps the stored secret.
+ *
+ * @stability experimental
+ */
+export type EmailSettingsInput = UpdateEmailSettingsInput;
+/**
+ * The last test attempt. A real response carries every field; the hook builds
+ * a partial one (`success: false` and the API's message) when the CALL itself
+ * failed (403, 500, a dropped connection), so both land in the same place.
+ *
+ * @stability experimental
+ */
+export type EmailTestResult = Partial<Omit<TestEmailResult, 'success'>> & {
+    /** Whether the provider accepted the message. */
+    success: boolean;
+};
+/**
+ * The masked status of a stored secret.
+ *
+ * @stability experimental
+ */
+export type SmtpPasswordStatus = EmailSettingsResponse['smtpPasswordStatus'];
+export type { EmailProviderKind };
+/**
+ * Options of {@link useEmailSettings}.
+ *
+ * @stability experimental
+ */
+export interface UseEmailSettingsOptions {
+    /** The transport. Default: the `PlatformHostProvider`'s (keep its identity stable). */
+    api?: PlatformApiClient;
+}
+/**
+ * What {@link useEmailSettings} returns.
+ *
+ * @stability experimental
+ */
+export interface UseEmailSettingsReturn {
+    /** The stored configuration, or `null` until loaded. */
+    settings: EmailSettings | null;
+    /** Whether a load is in flight. */
+    isLoading: boolean;
+    /** Failure to LOAD. Distinct from `saveError`: one means "nothing to edit", the other "your edit did not stick". */
+    loadError: string | null;
+    /** Whether a save is in flight. */
+    isSaving: boolean;
+    /** Why the last save did not land, or `null`. */
+    saveError: string | null;
+    /** Whether a test send is in flight. */
+    isTesting: boolean;
+    /** The last test attempt, success or failure, until the page clears it. */
+    testResult: EmailTestResult | null;
+    /** Resolves `true` when the save landed, `false` when it did not — never throws. */
+    save: (input: EmailSettingsInput) => Promise<boolean>;
+    /** Sends the test message to the viewer; the outcome lands in `testResult`, never throws. */
+    sendTest: () => Promise<void>;
+    /** Clears `testResult`. */
+    clearTestResult: () => void;
+    /** Clears `saveError`. */
+    clearSaveError: () => void;
+    /** Reloads the configuration. */
+    refresh: () => Promise<void>;
+}
+/**
+ * Load, save and test-send the deployment's email configuration
+ * (`system_settings:read` to load, `system_settings:write` to save and send).
+ * Save is a PUT with the loaded version as `If-Match`; a 409 reloads the form
+ * and says so. A failed test send is a result, never a rejected promise.
+ *
+ * @param options - the transport, when the hook runs outside the host provider.
+ * @returns the settings, the flags and the three actions.
+ * @throws Error when there is neither a host nor an `api` option.
+ *
+ * @example
+ * ```tsx
+ * const { settings, save, sendTest, testResult } = useEmailSettings();
+ * ```
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export declare function useEmailSettings(options?: UseEmailSettingsOptions): UseEmailSettingsReturn;
+//# sourceMappingURL=use-email-settings.d.ts.map

package/dist/email/headless/use-email-settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-email-settings.d.ts","sourceRoot":"","sources":["../../../src/email/headless/use-email-settings.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EACV,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,wBAAwB,EACzB,MAAM,qCAAqC,CAAC;AAI7C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAE7D;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,qBAAqB,CAAC;AAElD;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,wBAAwB,CAAC;AAE1D;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,eAAe,EAAE,SAAS,CAAC,CAAC,GAAG;IACxE,iDAAiD;IACjD,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,qBAAqB,CAAC,oBAAoB,CAAC,CAAC;AAE7E,YAAY,EAAE,iBAAiB,EAAE,CAAC;AAElC;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,uFAAuF;IACvF,GAAG,CAAC,EAAE,iBAAiB,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,wDAAwD;IACxD,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;IAC/B,mCAAmC;IACnC,SAAS,EAAE,OAAO,CAAC;IACnB,oHAAoH;IACpH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,mCAAmC;IACnC,QAAQ,EAAE,OAAO,CAAC;IAClB,iDAAiD;IACjD,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,wCAAwC;IACxC,SAAS,EAAE,OAAO,CAAC;IACnB,2EAA2E;IAC3E,UAAU,EAAE,eAAe,GAAG,IAAI,CAAC;IACnC,oFAAoF;IACpF,IAAI,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACtD,6FAA6F;IAC7F,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,2BAA2B;IAC3B,eAAe,EAAE,MAAM,IAAI,CAAC;IAC5B,0BAA0B;IAC1B,cAAc,EAAE,MAAM,IAAI,CAAC;IAC3B,iCAAiC;IACjC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAcD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,uBAA4B,GAAG,sBAAsB,CA6J9F"}

package/dist/email/headless/use-email-settings.js

@@ -0,0 +1,212 @@
+// The email settings hook (issue #124, epic #109; in @marinoscar/platform-web
+// since #737, behaviour unchanged).
+/*
+ * Issue #124, epic #109. Shaped after `useSystemSettings` — same `isMounted`
+ * discipline, same "error is a string the page renders" contract — with three
+ * departures that are specific to this endpoint and are the reason it is a
+ * separate hook rather than another branch of the system settings document:
+ *
+ *   1. SAVE IS A PUT of the whole document, not a PATCH of one branch. Email
+ *      settings are a dozen coupled fields edited on one screen; a per-field
+ *      merge would let a half-saved provider switch (SMTP host written, SES
+ *      region not) exist as a state nothing in the UI can show.
+ *
+ *   2. THE TEST IS NOT A SAVE. `sendTest` mutates nothing and is deliberately
+ *      tracked by its own `isTesting` flag and its own result, because the page
+ *      must be able to say "the save worked and the send did not" — which is
+ *      the single most common real outcome and the whole reason the page exists.
+ *
+ *   3. A FAILED SEND IS NOT A REJECTED PROMISE. See `sendTest` below; getting
+ *      this wrong is how a page ends up announcing success over a provider that
+ *      refused the message.
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { isPlatformApiError, useOptionalPlatformHost } from '../../core/index.js';
+/** A mounted guard for every `setState` past an `await`. */
+function useIsMounted() {
+    const mounted = useRef(true);
+    useEffect(() => {
+        mounted.current = true;
+        return () => {
+            mounted.current = false;
+        };
+    }, []);
+    return useCallback(() => mounted.current, []);
+}
+/**
+ * Load, save and test-send the deployment's email configuration
+ * (`system_settings:read` to load, `system_settings:write` to save and send).
+ * Save is a PUT with the loaded version as `If-Match`; a 409 reloads the form
+ * and says so. A failed test send is a result, never a rejected promise.
+ *
+ * @param options - the transport, when the hook runs outside the host provider.
+ * @returns the settings, the flags and the three actions.
+ * @throws Error when there is neither a host nor an `api` option.
+ *
+ * @example
+ * ```tsx
+ * const { settings, save, sendTest, testResult } = useEmailSettings();
+ * ```
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export function useEmailSettings(options = {}) {
+    const host = useOptionalPlatformHost();
+    const api = options.api ?? host?.api;
+    if (!api) {
+        throw new Error('useEmailSettings needs a transport: mount PlatformHostProvider (@marinoscar/platform-web/core) or pass { api }.');
+    }
+    const [settings, setSettings] = useState(null);
+    const [isLoading, setIsLoading] = useState(true);
+    const [loadError, setLoadError] = useState(null);
+    const [isSaving, setIsSaving] = useState(false);
+    const [saveError, setSaveError] = useState(null);
+    const [isTesting, setIsTesting] = useState(false);
+    const [testResult, setTestResult] = useState(null);
+    // Every `setState` past an `await` is guarded: a request that settles after
+    // the component is gone must not schedule an update on it. Only the state
+    // write is skipped — what these functions return is unchanged. Same rule as
+    // `useSystemSettings` and `useAllowlist`.
+    const isMounted = useIsMounted();
+    const fetchSettings = useCallback(async () => {
+        try {
+            setIsLoading(true);
+            setLoadError(null);
+            const data = await api.get('/email-settings');
+            if (isMounted())
+                setSettings(data);
+        }
+        catch (err) {
+            if (isMounted()) {
+                // 403 is named explicitly because it is the one failure the admin can
+                // act on themselves; everything else surfaces the API's own message.
+                if (isPlatformApiError(err) && err.status === 403) {
+                    setLoadError('You do not have permission to view email settings');
+                }
+                else {
+                    setLoadError(isPlatformApiError(err) ? err.message : 'Failed to load email settings');
+                }
+            }
+        }
+        finally {
+            if (isMounted())
+                setIsLoading(false);
+        }
+    }, [api, isMounted]);
+    useEffect(() => {
+        fetchSettings();
+    }, [fetchSettings]);
+    /**
+     * PUT the form, adopt whatever the server says the settings now are.
+     *
+     * Returns a boolean instead of throwing because every caller of this is a
+     * click handler that needs to branch (raise the "saved" snackbar or not), and
+     * a rethrow would make each one write the same try/catch around a call whose
+     * error has ALREADY been captured in `saveError` for rendering.
+     *
+     * THE RESPONSE IS THE NEW BASELINE, not the input. The server owns
+     * `smtpPasswordStatus`, `settingsError`, `version`, `updatedAt` and
+     * `updatedBy`, and the password status in particular must come back from the
+     * server: after a save that set a password for the first time, a page still
+     * holding the old `configured: false` would keep telling the admin no
+     * password is stored while one is. `version` matters for the same reason —
+     * the response carries the number the NEXT save must send as `If-Match`, so
+     * two saves in a row work without a reload in between.
+     */
+    const save = useCallback(async (input) => {
+        try {
+            setIsSaving(true);
+            setSaveError(null);
+            // The version this form was built from, as `If-Match`. `?? 0` rather
+            // than "omit when we have none": 0 is the API's way of asserting "I
+            // believe nothing is stored yet", so even a first save on a fresh
+            // deployment is guarded rather than being the one unprotected write.
+            const data = await api.put('/email-settings', input, { ifMatch: String(settings?.version ?? 0) });
+            if (isMounted())
+                setSettings(data);
+            return true;
+        }
+        catch (err) {
+            // 409 IS NOT A GENERIC FAILURE. Somebody else saved between this
+            // page's load and this click, so the version we asserted is stale and
+            // every retry would 409 identically until the form is rebuilt from the
+            // current row. Reload it, and say plainly that the fields on screen
+            // have been replaced — a message alone, over a form still holding the
+            // stale values, would invite the admin to press Save again and
+            // (version now current) overwrite the colleague's change for real.
+            if (isPlatformApiError(err) && err.status === 409) {
+                await fetchSettings();
+                if (isMounted()) {
+                    setSaveError('Someone else changed the email settings while you were editing. ' +
+                        'The form has been reloaded with the current configuration — review it and save again.');
+                }
+                return false;
+            }
+            if (isMounted()) {
+                setSaveError(isPlatformApiError(err) ? err.message : 'Failed to save email settings');
+            }
+            return false;
+        }
+        finally {
+            if (isMounted())
+                setIsSaving(false);
+        }
+    }, [api, settings, fetchSettings, isMounted]);
+    /**
+     * Ask the API to send a real message to the signed-in user, and record what
+     * the provider said.
+     *
+     * TWO KINDS OF FAILURE, ONE SURFACE. The endpoint answers 200 with
+     * `{ success: false, error }` when the provider refuses the message — that is
+     * the interesting case, and it is NOT an exception. It rejects only when the
+     * call itself fails (403, 500, connection dropped). Both are failed tests, so
+     * both end up in the same `testResult` with `success: false`; the page has one
+     * red region to render and no way to accidentally treat a resolved promise as
+     * a successful send.
+     *
+     * This function deliberately never throws, for the same reason `save` does
+     * not: the outcome is state to render, not an exception to handle.
+     */
+    const sendTest = useCallback(async () => {
+        try {
+            setIsTesting(true);
+            setTestResult(null);
+            const result = await api.post('/email-settings/test');
+            if (isMounted())
+                setTestResult(result);
+        }
+        catch (err) {
+            if (isMounted()) {
+                setTestResult({
+                    success: false,
+                    // The API's message verbatim — a 403 from a read-only admin and a
+                    // 500 from a broken provider module read very differently, and
+                    // flattening both to "test failed" would throw away the only clue.
+                    error: isPlatformApiError(err) ? err.message : 'The test request could not be sent',
+                });
+            }
+        }
+        finally {
+            if (isMounted())
+                setIsTesting(false);
+        }
+    }, [api, isMounted]);
+    const clearTestResult = useCallback(() => setTestResult(null), []);
+    const clearSaveError = useCallback(() => setSaveError(null), []);
+    return {
+        settings,
+        isLoading,
+        loadError,
+        isSaving,
+        saveError,
+        isTesting,
+        testResult,
+        save,
+        sendTest,
+        clearTestResult,
+        clearSaveError,
+        refresh: fetchSettings,
+    };
+}
+//# sourceMappingURL=use-email-settings.js.map

package/dist/email/headless/use-email-settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-email-settings.js","sourceRoot":"","sources":["../../../src/email/headless/use-email-settings.ts"],"names":[],"mappings":"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"}

package/dist/email/ui/EmailGenericTransportPanel.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The generic email transport panel (PP-14.8).
+ *
+ * Draws any transport no bespoke panel is registered for, in practice a
+ * transport an app or package added with `registerEmailTransport`
+ * (`@marinoscar/platform-api/email`). Nothing about the transport is known here:
+ * the form is generated from the descriptor the API serves in
+ * `GET /api/email-settings` (`descriptors`) through the settings slice's
+ * `PluggableConfigForm`: a control per setting (a switch, a select, a text or
+ * number input) and a WRITE-ONLY field per declared secret.
+ *
+ * It is controlled and presentational, like the form it wraps. The page owns
+ * the state and the save: the settings go out as `transports.<id>`, the typed
+ * secrets as `secrets.<id>`, and a secret nobody retyped is not sent at all
+ * (blank keeps the stored one). A stored secret is only ever shown as saved,
+ * never as a value.
+ */
+import type { EmailTransportPanelProps } from './emailTransportPanelRegistry.js';
+/**
+ * The form the admin email page draws for a transport that has no registered
+ * panel: its label and description, then its settings and write-only secrets,
+ * all generated from `props.descriptor`. Also usable inside a bespoke panel
+ * that only wants to add to it.
+ *
+ * @param props - see {@link EmailTransportPanelProps}.
+ * @returns the panel.
+ *
+ * @example
+ * ```tsx
+ * registerEmailTransportPanel('sendgrid', (props) => (
+ *   <>
+ *     <Alert severity="info">Verify your sender in the SendGrid console first.</Alert>
+ *     <EmailGenericTransportPanel {...props} />
+ *   </>
+ * ));
+ * ```
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export declare function EmailGenericTransportPanel({ transport, descriptor, value, onChange, secrets, onSecretChange, errors, canWrite, }: EmailTransportPanelProps): import("react").JSX.Element;
+//# sourceMappingURL=EmailGenericTransportPanel.d.ts.map

package/dist/email/ui/EmailGenericTransportPanel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EmailGenericTransportPanel.d.ts","sourceRoot":"","sources":["../../../src/email/ui/EmailGenericTransportPanel.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAEjF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,0BAA0B,CAAC,EACzC,SAAS,EACT,UAAU,EACV,KAAK,EACL,QAAQ,EACR,OAAO,EACP,cAAc,EACd,MAAM,EACN,QAAQ,GACT,EAAE,wBAAwB,+BAmC1B"}

package/dist/email/ui/EmailGenericTransportPanel.js

@@ -0,0 +1,47 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The generic email transport panel (PP-14.8).
+ *
+ * Draws any transport no bespoke panel is registered for, in practice a
+ * transport an app or package added with `registerEmailTransport`
+ * (`@marinoscar/platform-api/email`). Nothing about the transport is known here:
+ * the form is generated from the descriptor the API serves in
+ * `GET /api/email-settings` (`descriptors`) through the settings slice's
+ * `PluggableConfigForm`: a control per setting (a switch, a select, a text or
+ * number input) and a WRITE-ONLY field per declared secret.
+ *
+ * It is controlled and presentational, like the form it wraps. The page owns
+ * the state and the save: the settings go out as `transports.<id>`, the typed
+ * secrets as `secrets.<id>`, and a secret nobody retyped is not sent at all
+ * (blank keeps the stored one). A stored secret is only ever shown as saved,
+ * never as a value.
+ */
+import { Box, Divider, Typography } from '@mui/material';
+import { PluggableConfigForm } from '../../settings/index.js';
+/**
+ * The form the admin email page draws for a transport that has no registered
+ * panel: its label and description, then its settings and write-only secrets,
+ * all generated from `props.descriptor`. Also usable inside a bespoke panel
+ * that only wants to add to it.
+ *
+ * @param props - see {@link EmailTransportPanelProps}.
+ * @returns the panel.
+ *
+ * @example
+ * ```tsx
+ * registerEmailTransportPanel('sendgrid', (props) => (
+ *   <>
+ *     <Alert severity="info">Verify your sender in the SendGrid console first.</Alert>
+ *     <EmailGenericTransportPanel {...props} />
+ *   </>
+ * ));
+ * ```
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export function EmailGenericTransportPanel({ transport, descriptor, value, onChange, secrets, onSecretChange, errors, canWrite, }) {
+    const messages = Object.values(errors);
+    return (_jsxs(Box, { "data-testid": `email-transport-panel-${transport}`, children: [_jsx(Divider, { sx: { my: 3 } }), _jsx(Typography, { variant: "h6", gutterBottom: true, children: descriptor.label }), descriptor.description && (_jsx(Typography, { variant: "body2", color: "text.secondary", sx: { mb: 2 }, children: descriptor.description })), descriptor.fields.length > 0 ? (_jsx(PluggableConfigForm, { descriptor: descriptor, value: value, onChange: onChange, secrets: secrets, onSecretChange: onSecretChange, disabled: !canWrite })) : (_jsx(Typography, { variant: "body2", color: "text.secondary", children: "This transport has nothing to configure." })), messages.length > 0 && (_jsx(Typography, { variant: "body2", color: "error", sx: { mt: 1 }, role: "alert", children: messages.join(' ') }))] }));
+}
+//# sourceMappingURL=EmailGenericTransportPanel.js.map

package/dist/email/ui/EmailGenericTransportPanel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EmailGenericTransportPanel.js","sourceRoot":"","sources":["../../../src/email/ui/EmailGenericTransportPanel.tsx"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAG9D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,0BAA0B,CAAC,EACzC,SAAS,EACT,UAAU,EACV,KAAK,EACL,QAAQ,EACR,OAAO,EACP,cAAc,EACd,MAAM,EACN,QAAQ,GACiB;IACzB,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAEvC,OAAO,CACL,MAAC,GAAG,mBAAc,yBAAyB,SAAS,EAAE,aACpD,KAAC,OAAO,IAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,GAAI,EAC1B,KAAC,UAAU,IAAC,OAAO,EAAC,IAAI,EAAC,YAAY,kBAClC,UAAU,CAAC,KAAK,GACN,EACZ,UAAU,CAAC,WAAW,IAAI,CACzB,KAAC,UAAU,IAAC,OAAO,EAAC,OAAO,EAAC,KAAK,EAAC,gBAAgB,EAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,YAC7D,UAAU,CAAC,WAAW,GACZ,CACd,EACA,UAAU,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAC9B,KAAC,mBAAmB,IAClB,UAAU,EAAE,UAAU,EACtB,KAAK,EAAE,KAAK,EACZ,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,OAAO,EAChB,cAAc,EAAE,cAAc,EAC9B,QAAQ,EAAE,CAAC,QAAQ,GACnB,CACH,CAAC,CAAC,CAAC,CACF,KAAC,UAAU,IAAC,OAAO,EAAC,OAAO,EAAC,KAAK,EAAC,gBAAgB,yDAErC,CACd,EACA,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,CACtB,KAAC,UAAU,IAAC,OAAO,EAAC,OAAO,EAAC,KAAK,EAAC,OAAO,EAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,IAAI,EAAC,OAAO,YAClE,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,GACR,CACd,IACG,CACP,CAAC;AACJ,CAAC"}

package/dist/email/ui/EmailSettingsPage.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Admin → Settings → Email (`/admin/settings/email`).
+ *
+ * Issue #124, epic #109. The first settings page added since `CLAUDE.md`'s
+ * `MANDATORY: Settings UI Pattern` section landed, so it is deliberately a
+ * REGISTRY CARD and nothing else: one entry in `ADMIN_SECTIONS`, one route in
+ * `App.tsx` gated on the same permission string, and no tab anywhere. The hub,
+ * the Console rail and the compact AppBar title all pick it up from that single
+ * declaration — see `docs/specs/settings-ui.md`.
+ *
+ * WHY THIS DOES NOT USE `SystemSettingsSection` (the render-prop wrapper
+ * `NotificationSettingsPage` uses). That component is bound to
+ * `useSystemSettings`: it loads THE system settings document, saves one branch
+ * of it by PATCH, and hands the page a non-null `SystemSettings`. Email is a
+ * different controller with a different document and a save contract this page
+ * exists to make visible (blank password preserves), plus a second, non-saving
+ * action — the test send — that the wrapper has no notion of. Threading all
+ * that through it would generalise a shared component to serve exactly one
+ * caller. What IS shared is the chrome, reproduced here field for field —
+ * container, `h4` title, mirrored card description, "(read-only)" suffix, last
+ * updated line, `Paper` body — so the page reads as a sibling rather than as a
+ * one-off.
+ *
+ * THE TEST BUTTON IS THE POINT OF THE PAGE (#124). A wrong SES region, an
+ * unverified sender identity and a bad SMTP password all fail, and they fail
+ * differently; the provider's own error text is the only thing that tells them
+ * apart. So the failure surface here is a persistent, dismissible alert with
+ * room for a multi-line provider message — never a snackbar that slides away in
+ * five seconds carrying the one string the admin needed to read twice.
+ *
+ * -----------------------------------------------------------------------------
+ * TRANSPORTS ARE PLUGGABLE, AND "OFF" IS TWO FIELDS
+ * -----------------------------------------------------------------------------
+ *
+ * The API describes every registered email transport (`descriptors`) and
+ * carries each one's settings (`transports.<id>`) and the masked status of its
+ * secrets (`secretStatuses`). The page draws one radio per descriptor and the
+ * selected transport's form below it. WHICH component draws that form is the
+ * panel registry's decision (`./emailTransportPanelRegistry.ts`): the two
+ * built-ins register their bespoke panels (`SesTransportPanel`,
+ * `SmtpTransportPanel`, moved verbatim, so their markup did not change), every
+ * other transport gets `EmailGenericTransportPanel`, generated from its
+ * descriptor.
+ *
+ * "Email is turned off" is `enabled: false`, NOT a third `provider` value. See
+ * `providerChoice` below for how the two fields reach one radio group without
+ * either being lost.
+ *
+ * ONLY THE SELECTED TRANSPORT'S SETTINGS AND TYPED SECRETS ARE SENT. The API
+ * merges `transports.<id>` over what is stored and leaves every other
+ * transport's settings alone, so switching between transports and back loses
+ * nothing in the stored row (the edits to a transport that is not selected
+ * stay on this page until it is reloaded).
+ */
+import type { PageSlotsBase } from '../../core/index.js';
+/**
+ * The slots of {@link EmailSettingsPage}: the page-slot contract. `Sections` is
+ * where an app adds a section of its own (a deliverability checklist, a link to
+ * the sending domain's DNS records); the transport panels themselves come from
+ * `registerEmailTransportPanel`.
+ *
+ * @example
+ * ```tsx
+ * <EmailSettingsPage slots={{ Sections: ({ position }) => (position === 'bottom' ? <DnsChecklist /> : null) }} />
+ * ```
+ *
+ * @extensionPoint slot
+ * @stability experimental
+ */
+export type EmailSettingsPageSlots = PageSlotsBase;
+/**
+ * The props of {@link EmailSettingsPage}.
+ *
+ * @stability experimental
+ */
+export interface EmailSettingsPageProps {
+    /** Optional extension slots; omitted, the page renders exactly as it always did. */
+    slots?: EmailSettingsPageSlots;
+}
+/**
+ * `/admin/settings/email`: the email transport, sender and secrets, and the
+ * test send. Routed behind `system_settings:read` (the `Email` card's
+ * permission, the exact string the API enforces on `GET /api/email-settings`);
+ * saving and test-sending need `system_settings:write`, and the page disables
+ * both without it. Reads the viewer from the `PlatformHostProvider`.
+ *
+ * @returns the page.
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export default function EmailSettingsPage(props?: EmailSettingsPageProps): import("react").JSX.Element;
+//# sourceMappingURL=EmailSettingsPage.d.ts.map

package/dist/email/ui/EmailSettingsPage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EmailSettingsPage.d.ts","sourceRoot":"","sources":["../../../src/email/ui/EmailSettingsPage.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AA6BH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AA8JzD;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,sBAAsB,GAAG,aAAa,CAAC;AAEnD;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,oFAAoF;IACpF,KAAK,CAAC,EAAE,sBAAsB,CAAC;CAChC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,OAAO,UAAU,iBAAiB,CAAC,KAAK,GAAE,sBAA2B,+BAggB3E"}