@rapidmx/web-client 0.20.0 → 0.22.0

package/lib/admin/pluginsApi.ts

@@ -0,0 +1,339 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s `BasePluginRoute` (mounted at `system/plugins`) - the plugins this
+ * deployment runs. Every endpoint is trusted-admin-only server-side. Saving a change doesn't apply it directly:
+ * 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";
+
+/** Mirrors `@rapidmx/restapi`'s `PluginSettingDefinition`. */
+export interface PluginSettingDefinition {
+    key: string;
+    label: string;
+    type: "string" | "number" | "boolean" | "select";
+    help?: string;
+    default?: string | number | boolean;
+    required?: boolean;
+    min?: number;
+    max?: number;
+    options?: { value: string; label: string }[];
+}
+
+/** Mirrors `@rapidmx/restapi`'s `PluginManifest`. */
+export interface PluginManifest {
+    apiVersion: number;
+    displayName: string;
+    description?: string;
+    settings?: PluginSettingDefinition[];
+    /** Other plugins this one needs, as package name to npm version range. */
+    requires?: Record<string, string>;
+    /** Whether the plugin stores per-mailbox data that data-subject erasure must reach. */
+    mailboxScopedData?: boolean;
+}
+
+export type PluginSettingValue = string | number | boolean;
+
+/** Mirrors `@rapidmx/restapi`'s `PluginConfiguredSetting`: what the deployment's own configuration (the command line, the
+ * environment, the server's defaults) says about one setting. It applies until a value is saved, which wins over it. */
+export interface PluginConfiguredSetting {
+    /** Left out for a secret, which the server never sends. */
+    value?: PluginSettingValue;
+    secret: boolean;
+}
+
+/** Mirrors `@rapidmx/restapi`'s `Plugin`. `version` is the row's optimistic-lock counter; the npm version is
+ * `packageVersion`. */
+export interface Plugin {
+    uid: string;
+    version: number;
+    name: string;
+    packageVersion: string;
+    integrity?: string;
+    enabled: boolean;
+    settings: Record<string, PluginSettingValue>;
+    /** For each setting the deployment's configuration provides a value for, what it says. Absent from a server that
+     * predates it, which reads as nothing being configured. */
+    configured?: Record<string, PluginConfiguredSetting>;
+    manifest: PluginManifest;
+}
+
+/** Mirrors `@rapidmx/restapi`'s `RegistryPackageVersion`. `manifest` is a message when the version isn't a
+ * loadable plugin. */
+export interface RegistryPackageVersion {
+    name: string;
+    version: string;
+    description?: string;
+    integrity?: string;
+    peerDependencies: Record<string, string>;
+    manifest: PluginManifest | string;
+}
+
+export interface PluginRegistryLookup {
+    package: { name: string; latest?: string; versions: string[] };
+    selected: RegistryPackageVersion;
+}
+
+/** What one server copy last reported. */
+export interface PluginInstanceStatus {
+    instance: string;
+    /** Equals `PluginStatus.hash` once the copy has applied the current plugin set. */
+    hash: string;
+    loaded: { name: string; version: string }[];
+    errors: { name: string; message: string }[];
+    safeMode: boolean;
+    updatedAt: string;
+}
+
+/** Where an uninstalled plugin's data deletion stands: `pending` until no server runs the plugin, `running` while one
+ * server deletes, then `done` or `failed` (retryable). */
+export type PluginPurgeState = "pending" | "running" | "done" | "failed";
+
+/** One step of a data deletion. A retry runs only the steps that failed. */
+export interface PluginPurgeStep {
+    /** `hook`, `data:<datastore>:<collection or table>`, `blobs`, `settings` or `files`. */
+    step: string;
+    ok: boolean;
+    /** How many documents or rows the step deleted. */
+    count?: number;
+    error?: string;
+    note?: string;
+}
+
+/** The deletion of an uninstalled plugin's data (`GET /status`'s `purges`). */
+export interface PluginPurgeInfo {
+    uid: string;
+    name: string;
+    displayName?: string;
+    state: PluginPurgeState;
+    /** The uid of the administrator who asked for it. */
+    requestedBy?: string;
+    /** ISO time. */
+    requestedAt?: string;
+    /** ISO time; set once it is `done` or `failed`. */
+    completedAt?: string;
+    steps: PluginPurgeStep[];
+    /** Why it failed. */
+    error?: string;
+    /** While `pending`: how many servers still run the plugin (or haven't applied its removal), of how many report. */
+    serversRunning?: number;
+    serversTotal?: number;
+}
+
+export interface PluginStatus {
+    /** The fingerprint of the saved plugin set every copy should reach. */
+    hash: string;
+    instances: PluginInstanceStatus[];
+    /** Each uninstalled plugin whose data was asked to be deleted. Absent from an older server. */
+    purges?: PluginPurgeInfo[];
+}
+
+/** A plugin package found by `searchPlugins()`. `version` is its latest published version. */
+export interface PluginSearchResult {
+    name: string;
+    version: string;
+    description?: string;
+    date?: string;
+    /** Whether this server's configuration lets an administrator add it. */
+    allowed: boolean;
+    /** Set when the package is already installed. */
+    installedUid?: string;
+    installedVersion?: string;
+    /** Whether `version` is newer than the installed version. */
+    updateAvailable: boolean;
+}
+
+/** An installed plugin's latest published version, from `getPluginUpdates()`. */
+export interface PluginUpdateInfo {
+    uid: string;
+    name: string;
+    installedVersion: string;
+    latestVersion?: string;
+    updateAvailable: boolean;
+    /** Whether this server's configuration still allows the package; an update is never offered when it doesn't. */
+    allowed?: boolean;
+    /** Why the registry couldn't be checked for this plugin. */
+    error?: string;
+}
+
+/** A namespace (npm scope) this server searches for plugins. */
+export interface PluginNamespace {
+    name: string;
+    registry?: string;
+}
+
+/** What `planPluginChange()` found: dependencies that would be installed (dependencies first) and installed plugins
+ * that would be enabled. The change is refused while `conflicts` isn't empty. */
+export interface PluginChangePlan {
+    plugin: { name: string; version: string; manifest: PluginManifest };
+    install: { name: string; version: string; integrity?: string; manifest: PluginManifest }[];
+    enable: string[];
+    conflicts: string[];
+}
+
+/** `addPlugin()`'s result: the added plugin and the dependencies installed or enabled with it. */
+export interface AddPluginResult {
+    plugin: Plugin;
+    dependencies: Plugin[];
+    /** The plugins whose pending data deletion adding this cancelled (the plugin itself, and any it requires). */
+    purgeCancelled?: string[];
+    /** Things worth telling the administrator, such as a cancelled data deletion. */
+    warnings?: string[];
+}
+
+/** What uninstalling a plugin did. */
+export interface RemovePluginResult {
+    /** Whether the plugin's data will be deleted once no server runs the plugin any more. */
+    purgeScheduled: boolean;
+    purge?: PluginPurgeInfo;
+}
+
+/** The other plugins a previewed change was confirmed to install and enable (from its `PluginChangePlan`). The server
+ * refuses the change (409) when what it would do now differs, e.g. because a new dependency appeared since. Send empty
+ * lists to require that nothing else is installed or enabled. */
+export interface PluginExpectedPlan {
+    /** The version of the plugin itself that was previewed. */
+    version?: string;
+    install: { name: string; version: string }[];
+    enable: string[];
+}
+
+/** The `expectedPlan` to send for a change previewed as `plan`. */
+export function expectedPlanOf(plan: Pick<PluginChangePlan, "install" | "enable"> & { plugin?: { version: string } }): PluginExpectedPlan {
+    return {
+        ...(plan.plugin ? { version: plan.plugin.version } : {}),
+        install: plan.install.map(({ name, version }) => ({ name, version })),
+        enable: [...plan.enable],
+    };
+}
+
+export interface UpdatePluginInput {
+    /** The row's optimistic-lock counter. */
+    version?: number;
+    packageVersion?: string;
+    enabled?: boolean;
+    /** A `null` value clears a setting back to the plugin's own default. */
+    settings?: Record<string, PluginSettingValue | null>;
+    /** What a previewed version change or enable was confirmed to also install and enable. */
+    expectedPlan?: PluginExpectedPlan;
+}
+
+const BASE = "/system/plugins";
+
+/** Whether prerelease versions (`1.0.0-beta.2`) count when the server picks a package's newest version. */
+export interface PrereleaseOptions {
+    /** Off by default. Sent to the server only when `true`, so a server that predates it is called exactly as before. */
+    prerelease?: boolean;
+}
+
+/** `?name=…` style query parameters for `params`, plus `prerelease=true` when asked for. */
+function withPrerelease(params: URLSearchParams, options: PrereleaseOptions): string {
+    if (options.prerelease) {
+        params.set("prerelease", "true");
+    }
+    return params.toString();
+}
+
+/** `client`, given by every function below, is an explicit `ApiClient` from `createApiClient()` (e.g. one
+ * account of a multi-account app) to call instead of the default global `apiFetch()` - see `withClient()`'s
+ * own doc comment in `util/api.ts`. Omitted (the default), every function here behaves exactly as before. */
+export function listPlugins(client?: ApiClient): Promise<Plugin[]> {
+    return withClient(client, BASE);
+}
+
+export function getPluginStatus(client?: ApiClient): Promise<PluginStatus> {
+    return withClient(client, `${BASE}/status`);
+}
+
+/** The namespaces this server searches for plugins. */
+export function listPluginNamespaces(client?: ApiClient): Promise<PluginNamespace[]> {
+    return withClient(client, `${BASE}/namespaces`);
+}
+
+/** Plugin packages (named `*-plugin`) in `namespace`, or in every configured namespace when it's omitted. Each one's
+ * `version` is its newest release, or its newest version of any kind with `prerelease`. */
+export function searchPlugins(namespace?: string, options: PrereleaseOptions = {}, client?: ApiClient): Promise<PluginSearchResult[]> {
+    const query = withPrerelease(new URLSearchParams(namespace ? { namespace } : {}), options);
+    return withClient(client, `${BASE}/search${query ? `?${query}` : ""}`);
+}
+
+/** Each installed plugin's newest published version - a release, unless `prerelease` also counts prereleases. */
+export function getPluginUpdates(options: PrereleaseOptions = {}, client?: ApiClient): Promise<PluginUpdateInfo[]> {
+    const query = withPrerelease(new URLSearchParams(), options);
+    return withClient(client, `${BASE}/updates${query ? `?${query}` : ""}`);
+}
+
+/**
+ * A package's published versions and one version's manifest (the newest, unless `packageVersion` is given). Prereleases
+ * are left out of the versions and never the newest unless `prerelease` is set. The name goes in the query string: a
+ * scoped name in the path needs its `/` escaped as `%2F`, which a proxy in front of the server (Envoy Gateway's
+ * default) unescapes and redirects to a path that matches no route.
+ */
+export function lookupPluginPackage(
+    name: string,
+    packageVersion?: string,
+    options: PrereleaseOptions = {},
+    client?: ApiClient,
+): Promise<PluginRegistryLookup> {
+    const query = new URLSearchParams({ name });
+    if (packageVersion) {
+        query.set("packageVersion", packageVersion);
+    }
+    return withClient(client, `${BASE}/registry?${withPrerelease(query, options)}`);
+}
+
+/** What adding `name` - or changing it, when installed - at `packageVersion` (default: the newest, see
+ * `lookupPluginPackage()`) would also install and enable, and what would refuse it. Nothing is changed. */
+export function planPluginChange(
+    name: string,
+    packageVersion?: string,
+    options: PrereleaseOptions = {},
+    client?: ApiClient,
+): Promise<PluginChangePlan> {
+    const query = new URLSearchParams({ name });
+    if (packageVersion) {
+        query.set("packageVersion", packageVersion);
+    }
+    return withClient(client, `${BASE}/plan?${withPrerelease(query, options)}`);
+}
+
+/** Adds a plugin, at its latest version unless `packageVersion` is given, installing and enabling the plugins it
+ * 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 function addPlugin(
+    name: string,
+    packageVersion?: string,
+    expectedPlan?: PluginExpectedPlan,
+    client?: ApiClient,
+): Promise<AddPluginResult> {
+    return withClient(client, BASE, { method: "POST", body: JSON.stringify({ name, packageVersion, expectedPlan }) });
+}
+
+export function updatePlugin(uid: string, input: UpdatePluginInput, client?: ApiClient): Promise<Plugin> {
+    return withClient(client, `${BASE}/${encodeURIComponent(uid)}`, { method: "PUT", body: JSON.stringify(input) });
+}
+
+/**
+ * Removes a plugin. Refused (409) while an enabled plugin requires it, as is disabling it with `updatePlugin()`.
+ *
+ * By default the data it stored stays in the database. With `purgeData` it is also deleted - its collections and tables,
+ * saved settings and files - once no server runs the plugin any more (see `PluginStatus.purges`); that can't be undone,
+ * and the server only accepts it from an elevated administrator (403 `api-104` otherwise). Adding the plugin again before
+ * the deletion starts cancels it.
+ */
+export async function removePlugin(uid: string, options: { purgeData?: boolean } = {}, client?: ApiClient): Promise<RemovePluginResult> {
+    const result = await withClient<RemovePluginResult | undefined>(client, `${BASE}/${encodeURIComponent(uid)}`, {
+        method: "DELETE",
+        // Nothing is sent unless asked for, so a server that doesn't know the flag is called exactly as before.
+        ...(options.purgeData ? { body: JSON.stringify({ purgeData: true }) } : {}),
+    });
+    return result ?? { purgeScheduled: false };
+}
+
+/** Runs the steps of a failed data deletion that failed again. Needs an elevated administrator. */
+export function retryPluginPurge(purgeUid: string, client?: ApiClient): Promise<PluginPurgeInfo> {
+    return withClient(client, `${BASE}/purges/${encodeURIComponent(purgeUid)}/retry`, { method: "POST" });
+}

package/lib/admin/retentionPolicyApi.ts

@@ -0,0 +1,46 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s deployment-wide `RetentionPolicy` singleton
+ * (`BaseRetentionPolicyRoute`, mounted at `system/retention-policy`). `GET` is readable by any
+ * authenticated user; `PUT` is trusted-admin-only server-side. Enforcement itself (actually purging
+ * expired messages/audit-log entries) lives entirely in restapi's own `RetentionEnforcementJob` — this
+ * file only reads/writes the configuration.
+ */
+import { ApiClient, withClient } from "../util/api.js";
+
+/** Mirrors `@rapidmx/restapi`'s `PublicRetentionPolicy` exactly. Both fields `undefined` means "no
+ * automatic purge configured" — `GET` returns `{}` rather than 404 when nothing has been set yet. */
+export interface RetentionPolicy {
+    /** Max age (days) for any `Message`, any folder. `undefined` = no automatic purge. */
+    messageRetentionDays?: number;
+    /** Max age (days) for `AuditLogEntry` rows. `undefined` = keep forever. Never applies to the
+     * separate, hash-chained `EscrowAuditLogEntry` ledger — deleting from that would break its own
+     * tamper-evident chain, by design. */
+    auditLogRetentionDays?: number;
+}
+
+/** The server-enforced floor for `auditLogRetentionDays` (2190 days, ~6 years — a HIPAA-approximation
+ * minimum) — mirrored here only so client-side validation can give the same message before a round trip;
+ * the server enforces this regardless. */
+export const MIN_AUDIT_LOG_RETENTION_DAYS = 2190;
+
+/** `client`, given by every function below, is an explicit `ApiClient` from `createApiClient()` (e.g. one
+ * account of a multi-account app) to call instead of the default global `apiFetch()` - see `withClient()`'s
+ * own doc comment in `util/api.ts`. Omitted (the default), every function here behaves exactly as before. */
+export function getRetentionPolicy(client?: ApiClient): Promise<RetentionPolicy> {
+    return withClient(client, `/system/retention-policy`);
+}
+
+/** A retention policy change: a field left out is left alone, and `null` clears it back to "no automatic purge". */
+export type RetentionPolicyUpdate = { [K in keyof RetentionPolicy]?: RetentionPolicy[K] | null };
+
+/** Partial patch — only supplied fields are changed, and a `null` field is cleared. */
+export function updateRetentionPolicy(patch: RetentionPolicyUpdate, client?: ApiClient): Promise<RetentionPolicy> {
+    return withClient(client, `/system/retention-policy`, {
+        method: "PUT",
+        body: JSON.stringify(patch),
+    });
+}

package/lib/admin/setupApi.ts

@@ -0,0 +1,40 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s first-run setup state (`BaseSetupRoute`, mounted at `system/setup`).
+ * Trusted-admin-only: a non-admin gets a `403`, which is how the web apps know not to send them to the wizard.
+ */
+import { ApiClient, withClient } from "../util/api.js";
+
+/** Mirrors `@rapidmx/restapi`'s `SetupStatus`. Dates arrive as ISO strings. */
+export interface SetupStatus {
+    /** Whether an administrator should be taken to the setup wizard. */
+    required: boolean;
+    startedAt?: string;
+    completedAt?: string;
+    /** The wizard step last saved with `saveSetupStep()`. */
+    currentStep?: string;
+}
+
+/** `client`, given by every function below, is an explicit `ApiClient` from `createApiClient()` (e.g. one
+ * account of a multi-account app) to call instead of the default global `apiFetch()` - see `withClient()`'s
+ * own doc comment in `util/api.ts`. Omitted (the default), every function here behaves exactly as before. */
+export function getSetupStatus(client?: ApiClient): Promise<SetupStatus> {
+    return withClient(client, "/system/setup");
+}
+
+/** Records the step the administrator is on, so leaving and coming back resumes there. */
+export function saveSetupStep(currentStep: string, client?: ApiClient): Promise<SetupStatus> {
+    return withClient(client, "/system/setup", { method: "PUT", body: JSON.stringify({ currentStep }) });
+}
+
+export function completeSetup(client?: ApiClient): Promise<SetupStatus> {
+    return withClient(client, "/system/setup/complete", { method: "POST" });
+}
+
+/** Sends administrators back through the wizard from its first step. */
+export function reopenSetup(client?: ApiClient): Promise<SetupStatus> {
+    return withClient(client, "/system/setup/reopen", { method: "POST" });
+}

package/lib/admin/transportRulesApi.ts

@@ -0,0 +1,106 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s `TransportRule` CRUD route (`BaseTransportRuleRoute`) —
+ * trusted-role-only, org-wide (evaluated once per SMTP transaction, before per-mailbox fan-out). No
+ * uid-derivation on create (unlike `Domain`/`Mailbox`/`DistributionList`) — a transport rule has no
+ * natural address of its own.
+ */
+
+import { ApiClient, withClient } from "../util/api.js";
+import { ListParams, buildQuery } from "../util/apiQuery.js";
+
+export type { ListParams };
+
+export type TransportRuleActionType = "reject" | "quarantine" | "add_header" | "add_recipient";
+
+export interface TransportRuleAction {
+    type: TransportRuleActionType;
+    /** Required for `add_header`. */
+    headerName?: string;
+    /** Required for `add_header`. */
+    headerValue?: string;
+    /** Required for `add_recipient`. */
+    recipientAddress?: string;
+}
+
+export interface TransportRuleConditions {
+    fromContains?: string[];
+    subjectContains?: string[];
+    bodyContains?: string[];
+    recipientContains?: string[];
+    anyRecipientExternal?: boolean;
+    hasAttachment?: boolean;
+    attachmentNameContains?: string[];
+}
+
+export interface TransportRule {
+    uid: string;
+    version: number;
+    dateCreated: string;
+    dateModified: string;
+    name: string;
+    enabled: boolean;
+    sequence: number;
+    stopProcessingRules: boolean;
+    conditions: TransportRuleConditions;
+    actions: TransportRuleAction[];
+}
+
+/** `client`, given by every function below, is an explicit `ApiClient` from `createApiClient()` (e.g. one
+ * account of a multi-account app) to call instead of the default global `apiFetch()` - see `withClient()`'s
+ * own doc comment in `util/api.ts`. Omitted (the default), every function here behaves exactly as before. */
+export function listTransportRules(params: ListParams = {}, client?: ApiClient): Promise<TransportRule[]> {
+    return withClient(client, `/mail/transport-rules?${buildQuery(params)}`);
+}
+
+export function getTransportRule(uid: string, client?: ApiClient): Promise<TransportRule> {
+    return withClient(client, `/mail/transport-rules/${encodeURIComponent(uid)}`);
+}
+
+export interface CreateTransportRuleInput {
+    name: string;
+    enabled?: boolean;
+    sequence?: number;
+    stopProcessingRules?: boolean;
+    conditions?: TransportRuleConditions;
+    actions?: TransportRuleAction[];
+}
+
+export function createTransportRule(input: CreateTransportRuleInput, client?: ApiClient): Promise<TransportRule> {
+    return withClient(client, "/mail/transport-rules", {
+        method: "POST",
+        body: JSON.stringify({
+            enabled: true,
+            sequence: 0,
+            stopProcessingRules: false,
+            conditions: {},
+            actions: [],
+            ...input,
+        }),
+    });
+}
+
+export interface UpdateTransportRuleInput {
+    uid: string;
+    version: number;
+    name?: string;
+    enabled?: boolean;
+    sequence?: number;
+    stopProcessingRules?: boolean;
+    conditions?: TransportRuleConditions;
+    actions?: TransportRuleAction[];
+}
+
+export function updateTransportRule(input: UpdateTransportRuleInput, client?: ApiClient): Promise<TransportRule> {
+    return withClient(client, `/mail/transport-rules/${encodeURIComponent(input.uid)}`, {
+        method: "PUT",
+        body: JSON.stringify(input),
+    });
+}
+
+export function deleteTransportRule(uid: string, version: number, client?: ApiClient): Promise<void> {
+    return withClient(client, `/mail/transport-rules/${encodeURIComponent(uid)}?version=${version}`, { method: "DELETE" });
+}