@rapidmx/web-client 0.21.0 → 0.23.0

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

@@ -0,0 +1,20 @@
+/**
+ * Typed wrapper over `@rapidmx/restapi`'s eDiscovery Matter-scoped search (`BaseMatterSearchRoute`,
+ * mounted at `escrow/matter-search`) — holder-gated (`requireEscrowHolder()` against the matter's own
+ * `escrowScopeId`). Lives under `admin/` only because that's where every other Matter/Escrow-family
+ * wrapper in this package lives — consumed exclusively by `apps/escrow`.
+ *
+ * Reuses the exact same query-param grammar/shape `search/searchApi.ts`'s own `search()` already speaks
+ * (`SearchParams`/`buildSearchParams()`) — this route is a fan-out of the same underlying
+ * `SearchProvider`, once per the matter's own custodian mailboxes, not a new search capability. `before`/
+ * `after` are always clamped server-side to the matter's own date range, regardless of what's supplied.
+ * There is no merged cross-mailbox ranking or cursor-based pagination — the response is keyed by
+ * `mailboxUid`, one page per custodian, matching how a holder-facing review UI groups results anyway.
+ */
+import { ApiClient } from "../util/api.js";
+import { SearchParams, SearchResultPage } from "../search/searchApi.js";
+export type { SearchParams, SearchResultPage };
+/** `client`, given 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), this behaves exactly as before. */
+export declare function searchMatter(matterId: string, text: string, params?: SearchParams, client?: ApiClient): Promise<Record<string, SearchResultPage>>;

package/dist/lib/admin/matterSearchApi.js

@@ -0,0 +1,27 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrapper over `@rapidmx/restapi`'s eDiscovery Matter-scoped search (`BaseMatterSearchRoute`,
+ * mounted at `escrow/matter-search`) — holder-gated (`requireEscrowHolder()` against the matter's own
+ * `escrowScopeId`). Lives under `admin/` only because that's where every other Matter/Escrow-family
+ * wrapper in this package lives — consumed exclusively by `apps/escrow`.
+ *
+ * Reuses the exact same query-param grammar/shape `search/searchApi.ts`'s own `search()` already speaks
+ * (`SearchParams`/`buildSearchParams()`) — this route is a fan-out of the same underlying
+ * `SearchProvider`, once per the matter's own custodian mailboxes, not a new search capability. `before`/
+ * `after` are always clamped server-side to the matter's own date range, regardless of what's supplied.
+ * There is no merged cross-mailbox ranking or cursor-based pagination — the response is keyed by
+ * `mailboxUid`, one page per custodian, matching how a holder-facing review UI groups results anyway.
+ */
+import { withClient } from "../util/api.js";
+import { buildSearchParams } from "../search/searchApi.js";
+/** `client`, given 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), this behaves exactly as before. */
+export function searchMatter(matterId, text, params = {}, client) {
+    const query = buildSearchParams(text, params);
+    query.set("matterId", matterId);
+    return withClient(client, `/escrow/matter-search?${query.toString()}`);
+}

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

@@ -0,0 +1,56 @@
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s `Matter` CRUD route (`BaseMatterRoute`) — deliberately
+ * **holder-gated, not admin-gated**, unlike every other file in `admin/`: a trusted administrator who
+ * isn't a holder of the matter's own `escrowScopeId` gets the same 403 as anyone else (see
+ * `escrowScopesApi.ts`, `specs/end-to-end_encryption.md`'s "Separation of duties"). Lives under `admin/`
+ * only because that's where every other CRUD-wrapper module in this package lives, not because it's an
+ * admin-only feature — it's consumed exclusively by `apps/escrow`, never `apps/admin`.
+ */
+import { ApiClient } from "../util/api.js";
+import { ListParams } from "../util/apiQuery.js";
+export type { ListParams };
+export interface Matter {
+    uid: string;
+    version: number;
+    dateCreated: string;
+    dateModified: string;
+    name: string;
+    description?: string;
+    /** Immutable after creation — see `BaseMatterRoute.update()`. */
+    escrowScopeId: string;
+    custodianMailboxUids: string[];
+    /** ISO 8601 timestamp. */
+    dateRangeStart: string;
+    /** ISO 8601 timestamp. */
+    dateRangeEnd: string;
+    /** Once set, this matter is permanently closed — one-way, see `closeMatter()`. */
+    closedAt?: 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 declare function listMatters(params?: ListParams, client?: ApiClient): Promise<Matter[]>;
+export declare function getMatter(uid: string, client?: ApiClient): Promise<Matter>;
+export interface CreateMatterInput {
+    name: string;
+    description?: string;
+    escrowScopeId: string;
+    custodianMailboxUids: string[];
+    dateRangeStart: string;
+    dateRangeEnd: string;
+}
+export declare function createMatter(input: CreateMatterInput, client?: ApiClient): Promise<Matter>;
+export interface UpdateMatterInput {
+    uid: string;
+    version: number;
+    name?: string;
+    description?: string;
+    custodianMailboxUids?: string[];
+    dateRangeStart?: string;
+    dateRangeEnd?: string;
+}
+export declare function updateMatter(input: UpdateMatterInput, client?: ApiClient): Promise<Matter>;
+export declare function deleteMatter(uid: string, version: number, client?: ApiClient): Promise<void>;
+/** One-way — `BaseMatterRoute.close()` 400s if the matter is already closed, and once closed no further
+ * `updateMatter()`/`createAccessRequest()` against it will succeed. */
+export declare function closeMatter(uid: string, client?: ApiClient): Promise<Matter>;

package/dist/lib/admin/mattersApi.js

@@ -0,0 +1,40 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s `Matter` CRUD route (`BaseMatterRoute`) — deliberately
+ * **holder-gated, not admin-gated**, unlike every other file in `admin/`: a trusted administrator who
+ * isn't a holder of the matter's own `escrowScopeId` gets the same 403 as anyone else (see
+ * `escrowScopesApi.ts`, `specs/end-to-end_encryption.md`'s "Separation of duties"). Lives under `admin/`
+ * only because that's where every other CRUD-wrapper module in this package lives, not because it's an
+ * admin-only feature — it's consumed exclusively by `apps/escrow`, never `apps/admin`.
+ */
+import { withClient } from "../util/api.js";
+import { buildQuery } from "../util/apiQuery.js";
+/** `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 listMatters(params = {}, client) {
+    return withClient(client, `/escrow/matters?${buildQuery(params)}`);
+}
+export function getMatter(uid, client) {
+    return withClient(client, `/escrow/matters/${encodeURIComponent(uid)}`);
+}
+export function createMatter(input, client) {
+    return withClient(client, "/escrow/matters", { method: "POST", body: JSON.stringify(input) });
+}
+export function updateMatter(input, client) {
+    return withClient(client, `/escrow/matters/${encodeURIComponent(input.uid)}`, {
+        method: "PUT",
+        body: JSON.stringify(input),
+    });
+}
+export function deleteMatter(uid, version, client) {
+    return withClient(client, `/escrow/matters/${encodeURIComponent(uid)}?version=${version}`, { method: "DELETE" });
+}
+/** One-way — `BaseMatterRoute.close()` 400s if the matter is already closed, and once closed no further
+ * `updateMatter()`/`createAccessRequest()` against it will succeed. */
+export function closeMatter(uid, client) {
+    return withClient(client, `/escrow/matters/${encodeURIComponent(uid)}/close`, { method: "POST" });
+}

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

@@ -0,0 +1,265 @@
+/**
+ * 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 } 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 declare function expectedPlanOf(plan: Pick<PluginChangePlan, "install" | "enable"> & {
+    plugin?: {
+        version: string;
+    };
+}): PluginExpectedPlan;
+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;
+}
+/** 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;
+}
+/** `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 declare function listPlugins(client?: ApiClient): Promise<Plugin[]>;
+export declare function getPluginStatus(client?: ApiClient): Promise<PluginStatus>;
+/** The namespaces this server searches for plugins. */
+export declare function listPluginNamespaces(client?: ApiClient): Promise<PluginNamespace[]>;
+/** 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 declare function searchPlugins(namespace?: string, options?: PrereleaseOptions, client?: ApiClient): Promise<PluginSearchResult[]>;
+/** Each installed plugin's newest published version - a release, unless `prerelease` also counts prereleases. */
+export declare function getPluginUpdates(options?: PrereleaseOptions, client?: ApiClient): Promise<PluginUpdateInfo[]>;
+/**
+ * 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 declare function lookupPluginPackage(name: string, packageVersion?: string, options?: PrereleaseOptions, client?: ApiClient): Promise<PluginRegistryLookup>;
+/** 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 declare function planPluginChange(name: string, packageVersion?: string, options?: PrereleaseOptions, client?: ApiClient): Promise<PluginChangePlan>;
+/** 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 declare function addPlugin(name: string, packageVersion?: string, expectedPlan?: PluginExpectedPlan, client?: ApiClient): Promise<AddPluginResult>;
+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()`.
+ *
+ * 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 declare function removePlugin(uid: string, options?: {
+    purgeData?: boolean;
+}, client?: ApiClient): Promise<RemovePluginResult>;
+/** Runs the steps of a failed data deletion that failed again. Needs an elevated administrator. */
+export declare function retryPluginPurge(purgeUid: string, client?: ApiClient): Promise<PluginPurgeInfo>;

package/dist/lib/admin/pluginsApi.js

@@ -0,0 +1,102 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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 { withClient } from "../util/api.js";
+/** The `expectedPlan` to send for a change previewed as `plan`. */
+export function expectedPlanOf(plan) {
+    return {
+        ...(plan.plugin ? { version: plan.plugin.version } : {}),
+        install: plan.install.map(({ name, version }) => ({ name, version })),
+        enable: [...plan.enable],
+    };
+}
+const BASE = "/system/plugins";
+/** `?name=…` style query parameters for `params`, plus `prerelease=true` when asked for. */
+function withPrerelease(params, options) {
+    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) {
+    return withClient(client, BASE);
+}
+export function getPluginStatus(client) {
+    return withClient(client, `${BASE}/status`);
+}
+/** The namespaces this server searches for plugins. */
+export function listPluginNamespaces(client) {
+    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, options = {}, client) {
+    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 = {}, client) {
+    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, packageVersion, options = {}, client) {
+    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, packageVersion, options = {}, client) {
+    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, packageVersion, expectedPlan, client) {
+    return withClient(client, BASE, { method: "POST", body: JSON.stringify({ name, packageVersion, expectedPlan }) });
+}
+export function updatePlugin(uid, input, client) {
+    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, options = {}, client) {
+    const result = await withClient(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, client) {
+    return withClient(client, `${BASE}/purges/${encodeURIComponent(purgeUid)}/retry`, { method: "POST" });
+}

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

@@ -0,0 +1,32 @@
+/**
+ * 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 } 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 declare 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 declare function getRetentionPolicy(client?: ApiClient): Promise<RetentionPolicy>;
+/** 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 declare function updateRetentionPolicy(patch: RetentionPolicyUpdate, client?: ApiClient): Promise<RetentionPolicy>;

package/dist/lib/admin/retentionPolicyApi.js

@@ -0,0 +1,29 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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 { withClient } from "../util/api.js";
+/** 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) {
+    return withClient(client, `/system/retention-policy`);
+}
+/** Partial patch — only supplied fields are changed, and a `null` field is cleared. */
+export function updateRetentionPolicy(patch, client) {
+    return withClient(client, `/system/retention-policy`, {
+        method: "PUT",
+        body: JSON.stringify(patch),
+    });
+}

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

@@ -0,0 +1,23 @@
+/**
+ * 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 } 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 declare function getSetupStatus(client?: ApiClient): Promise<SetupStatus>;
+/** Records the step the administrator is on, so leaving and coming back resumes there. */
+export declare function saveSetupStep(currentStep: string, client?: ApiClient): Promise<SetupStatus>;
+export declare function completeSetup(client?: ApiClient): Promise<SetupStatus>;
+/** Sends administrators back through the wizard from its first step. */
+export declare function reopenSetup(client?: ApiClient): Promise<SetupStatus>;

package/dist/lib/admin/setupApi.js

@@ -0,0 +1,26 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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 { withClient } from "../util/api.js";
+/** `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) {
+    return withClient(client, "/system/setup");
+}
+/** Records the step the administrator is on, so leaving and coming back resumes there. */
+export function saveSetupStep(currentStep, client) {
+    return withClient(client, "/system/setup", { method: "PUT", body: JSON.stringify({ currentStep }) });
+}
+export function completeSetup(client) {
+    return withClient(client, "/system/setup/complete", { method: "POST" });
+}
+/** Sends administrators back through the wizard from its first step. */
+export function reopenSetup(client) {
+    return withClient(client, "/system/setup/reopen", { method: "POST" });
+}