@rapidmx/web-client 0.30.0 → 0.32.0

package/dist/lib/admin/escrowScopesApi.js

@@ -11,12 +11,12 @@
  * `apps/admin/escrow-scopes/*`, never by the holder-facing `apps/escrow` area.
  */
 import { withClient } from "../util/api.js";
-import { buildQuery } from "../util/apiQuery.js";
+import { buildQuery, sortQuery } 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 listEscrowScopes(params = {}, client) {
-    return withClient(client, `/escrow/scopes?${buildQuery(params)}`);
+    return withClient(client, `/escrow/scopes?${buildQuery(params, sortQuery({ uid: "ASC" }))}`);
 }
 /**
  * Who a typed principal - a mailbox address, an auth-server username or e-mail alias, or a user uid - is, for the

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

@@ -32,6 +32,17 @@ export interface PluginManifest {
     mailboxScopedData?: boolean;
 }
 export type PluginSettingValue = string | number | boolean;
+/** What `@rapidmx/restapi` answers in place of the saved value of a setting whose key names a secret (secret, password, credential, token, api key), so a
+ * stored API key or shared secret never reaches the console. Sent back as it was given, it means "left alone": the saved value stays. */
+export interface PluginSecretSetting {
+    secret: true;
+}
+/** A saved setting as a response shows it. */
+export type PluginSavedSetting = PluginSettingValue | PluginSecretSetting;
+/** Whether `value` is the placeholder a saved secret setting is shown as. */
+export declare function isSecretSetting(value: unknown): value is PluginSecretSetting;
+/** Whether a setting's key names a secret - mirrors `@rapidmx/restapi`'s `SECRET_SETTING_KEY`, which decides what it withholds. */
+export declare function isSecretSettingKey(key: string): 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 {
@@ -48,11 +59,19 @@ export interface Plugin {
     packageVersion: string;
     integrity?: string;
     enabled: boolean;
-    settings: Record<string, PluginSettingValue>;
+    settings: Record<string, PluginSavedSetting>;
     /** 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;
+    /** Where the installed package came from: the npm registry (also what a server that predates uploads means), or a `.tgz` an administrator uploaded. */
+    source?: "registry" | "upload";
+    /** The name of the uploaded file, for a plugin with `source` `upload`. */
+    uploadFilename?: string;
+    /** ISO time the file was uploaded. */
+    uploadedAt?: string;
+    /** The uid of the administrator who uploaded it. */
+    uploadedByUserUid?: string;
 }
 /** Mirrors `@rapidmx/restapi`'s `RegistryPackageVersion`. `manifest` is a message when the version isn't a
  * loadable plugin. */
@@ -214,7 +233,7 @@ export interface UpdatePluginInput {
     packageVersion?: string;
     enabled?: boolean;
     /** A `null` value clears a setting back to the plugin's own default. */
-    settings?: Record<string, PluginSettingValue | null>;
+    settings?: Record<string, PluginSavedSetting | null>;
     /** What a previewed version change or enable was confirmed to also install and enable. */
     expectedPlan?: PluginExpectedPlan;
 }
@@ -249,6 +268,16 @@ export declare function planPluginChange(name: string, packageVersion?: string,
  * requires first. Refused (409) when a requirement conflicts with an installed plugin's version, or when
  * `expectedPlan` is given and no longer matches what adding it would install and enable. */
 export declare function addPlugin(name: string, packageVersion?: string, expectedPlan?: PluginExpectedPlan, client?: ApiClient): Promise<AddPluginResult>;
+/**
+ * Installs a plugin from `file`, the `.tgz` that `npm pack` produces, instead of from the registry - to try a new version before it is released, or an
+ * alternative distribution. The file's raw bytes are the request body (not multipart); its name travels in the query string. Needs an elevated
+ * administrator (403 `api-104` otherwise) and uploads switched on by the operator (403). Refused with 409 when a plugin of that name is already
+ * installed - unless `replace` is set, which swaps it for the uploaded one - or when a plugin it requires isn't installed; 400 when it isn't a
+ * loadable plugin and 413 when it is too large. Like adding one, it starts a rollout.
+ */
+export declare function uploadPlugin(file: File, options?: {
+    replace?: boolean;
+}, client?: ApiClient): Promise<Plugin>;
 export declare function updatePlugin(uid: string, input: UpdatePluginInput, client?: ApiClient): Promise<Plugin>;
 /**
  * Removes a plugin. Refused (409) while an enabled plugin requires it, as is disabling it with `updatePlugin()`.

package/dist/lib/admin/pluginsApi.js

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

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

@@ -20,6 +20,9 @@ export interface RetentionPolicy {
  * 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;
+/** The server-enforced floor for `messageRetentionDays` (30 days) - `MIN_MESSAGE_RETENTION_DAYS` in `@rapidmx/restapi`, mirrored here for the same reason as
+ * `MIN_AUDIT_LOG_RETENTION_DAYS`. A shorter period is refused with a 400. */
+export declare const MIN_MESSAGE_RETENTION_DAYS = 30;
 /** `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. */

package/dist/lib/admin/retentionPolicyApi.js

@@ -14,6 +14,9 @@ import { withClient } from "../util/api.js";
  * 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;
+/** The server-enforced floor for `messageRetentionDays` (30 days) - `MIN_MESSAGE_RETENTION_DAYS` in `@rapidmx/restapi`, mirrored here for the same reason as
+ * `MIN_AUDIT_LOG_RETENTION_DAYS`. A shorter period is refused with a 400. */
+export const MIN_MESSAGE_RETENTION_DAYS = 30;
 /** `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. */

package/dist/lib/admin/transportRulesApi.js

@@ -9,12 +9,12 @@
  * natural address of its own.
  */
 import { withClient } from "../util/api.js";
-import { buildQuery } from "../util/apiQuery.js";
+import { buildQuery, sortQuery } 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 listTransportRules(params = {}, client) {
-    return withClient(client, `/mail/transport-rules?${buildQuery(params)}`);
+    return withClient(client, `/mail/transport-rules?${buildQuery(params, sortQuery({ sequence: "ASC", uid: "ASC" }))}`);
 }
 export function getTransportRule(uid, client) {
     return withClient(client, `/mail/transport-rules/${encodeURIComponent(uid)}`);

package/dist/lib/appearance/preferencesApi.d.ts

@@ -112,7 +112,7 @@ export declare function getAppearance(client?: ApiClient): Promise<AppearancePre
 export declare function saveAppearance(update: AppearanceUpdate, client?: ApiClient): Promise<AppearancePreferences>;
 /** Stores `file` (already checked with `validateBackgroundFile()`) as the background: its raw bytes, with its own content type - which
  * bypasses `apiFetch()`, as it always sends JSON. Answers with the updated preferences. */
-export declare function uploadAppearanceBackground(file: Blob): Promise<AppearancePreferences>;
+export declare function uploadAppearanceBackground(file: Blob, client?: ApiClient): Promise<AppearancePreferences>;
 /** Removes the stored background image. Answers with the updated preferences when the server sends them, else `undefined`. */
 export declare function deleteAppearanceBackground(client?: ApiClient): Promise<AppearancePreferences | undefined>;
 /** The URL of the stored background image `version` - what CSS `url()` and `<img src>` use. Immutable per version. */

package/dist/lib/appearance/preferencesApi.js

@@ -19,7 +19,7 @@
  * Everything that comes from outside - the response, a push event, the page's server-rendered props, `localStorage` - goes through
  * `normalizeAppearance()`, which keeps only well-formed values (so a stale or hostile value can never reach a CSS declaration).
  */
-import { ApiRequestError, apiUrl, withClient, withCsrfHeader } from "../util/api.js";
+import { ApiRequestError, apiUrl, withClient, withClientRaw } from "../util/api.js";
 export const APPEARANCE_MODES = ["system", "light", "dark"];
 export const BACKGROUND_KINDS = ["none", "color", "image"];
 export const BACKGROUND_FITS = ["cover", "contain", "tile"];
@@ -212,19 +212,8 @@ export async function saveAppearance(update, client) {
 }
 /** Stores `file` (already checked with `validateBackgroundFile()`) as the background: its raw bytes, with its own content type - which
  * bypasses `apiFetch()`, as it always sends JSON. Answers with the updated preferences. */
-export async function uploadAppearanceBackground(file) {
-    const res = await fetch(apiUrl(`${PATH}/background`), {
-        method: "POST",
-        credentials: "include",
-        headers: withCsrfHeader({ "Content-Type": file.type || "application/octet-stream" }),
-        body: file,
-    });
-    const contentType = res.headers.get("content-type") ?? "";
-    const body = contentType.includes("application/json") ? await res.json().catch(() => undefined) : undefined;
-    if (!res.ok) {
-        const message = (body && (body.message || body.error)) || res.statusText || "Upload failed.";
-        throw new ApiRequestError(message, res.status, body?.code);
-    }
+export async function uploadAppearanceBackground(file, client) {
+    const body = await withClientRaw(client, `${PATH}/background`, "POST", file, file.type || "application/octet-stream");
     const stored = normalizeAppearance(body);
     if (!stored) {
         throw new ApiRequestError("The server did not return the saved appearance.", 502);

package/dist/lib/auth/session.d.ts

@@ -4,30 +4,67 @@ export declare const SESSION_REFRESH_AFTER_MS: number;
 export declare const SESSION_REFRESH_CHECK_MS: number;
 /** A reload that follows a successful recovery refresh but still finds no session is not repeated within this window. */
 export declare const SESSION_RELOAD_GUARD_MS: number;
+/** A refresh answered with a refusal is asked once more after this long, in case the cookies were rotated by another tab or the server's session save lagged. */
+export declare const SESSION_REFRESH_RETRY_MS = 1500;
+/** A forced refresh (a request was refused, or the page has no session) does nothing when a refresh succeeded within this long: the refusal came from the old cookies. */
+export declare const SESSION_REFRESH_MIN_GAP_MS: number;
+/** How many entries `rapidmx.session.log` keeps. */
+export declare const SESSION_LOG_MAX = 40;
+/**
+ * How long a refresh request may go unanswered before it is given up on (not aborted - see `postRefresh()`). A refresh runs inside a cross-tab Web Lock, so one that hangs would hold the lock - and
+ * with it every tab's refresh, and every request waiting on a recovery - for good.
+ */
+export declare const SESSION_REFRESH_TIMEOUT_MS: number;
+/** Sets how long a refresh request may go unanswered (for tests); `resetSessionRecovery()` restores the default. */
+export declare function setSessionRefreshTimeout(ms: number): void;
+/** Sets how long a refused refresh waits before its one retry (for tests); `resetSessionRecovery()` restores the default. */
+export declare function setSessionRefreshRetryDelay(ms: number): void;
+/** Whether a refresh succeeded within the last `ms`, in this tab or another (they share `localStorage`). A cleared or future-dated record counts as no. */
+export declare function refreshedRecently(ms: number): boolean;
+/** One entry of the session log (`rapidmx.session.log`). */
+export interface SessionLogEntry {
+    /** When it happened, ISO 8601. */
+    t: string;
+    /** What happened, e.g. `refresh:start`, `refresh:rejected`, `leave`. */
+    e: string;
+    /** A short detail (a reason, a status, an age). Never a token or cookie value. */
+    d?: string;
+}
+/** The session log: the last `SESSION_LOG_MAX` things the silent refresh did, oldest first, kept in `localStorage['rapidmx.session.log']` so the cause of an unexpected sign-in can be read afterward. */
+export declare function getSessionLog(): SessionLogEntry[];
+/** Appends to the session log, dropping the oldest entries past `SESSION_LOG_MAX`. Best effort: blocked storage loses the entry. */
+export declare function logSessionEvent(e: string, d?: string): void;
+/** Why a refresh was made, for the session log. */
+export type SessionRefreshReason = "check" | "recovery" | "nouser";
 /**
  * Refreshes the signed-in session through auth-server: exchanges the `refresh` cookie for a new access token and
  * refresh token, both set as cookies on the response. Rejects with the `ApiRequestError` auth-server answered
  * (`401`/`403` when the refresh token has expired or was revoked).
  *
- * A refresh token is single-use and bound to the session, so two tabs refreshing at once would make the second one look
- * like a dead session. Refreshes are therefore serialised across tabs (Web Locks, where the browser has them) and each
- * tab records when the last one happened, so a tab that gets its turn right after another tab refreshed does nothing.
+ * A refresh token is single-use and bound to the session, and auth-server saves the rotated token a moment after it
+ * answers, so refreshing twice in quick succession makes the second look like a dead session. Refreshes are therefore
+ * shared by every caller in the tab (one in flight at a time), serialised across tabs (Web Locks, where the browser has
+ * them), and each tab records when the last one succeeded, so a caller that gets its turn right after a refresh does
+ * nothing. A refresh that is refused is asked once more after `SESSION_REFRESH_RETRY_MS` (the cookies may have been
+ * rotated meanwhile) before it counts as a rejection.
  *
- * @param force Refresh even when the last refresh, by this tab or another, was recent.
+ * @param force Refresh even when the last refresh, by this tab or another, was `SESSION_REFRESH_AFTER_MS` ago or less. Even forced, a refresh made within `SESSION_REFRESH_MIN_GAP_MS` is not repeated.
+ * @param reason Why, for the session log.
  * @returns `true` when a refresh was made, `false` when one was not needed.
  */
-export declare function refreshSession(authServerUrl: string, force?: boolean): Promise<boolean>;
+export declare function refreshSession(authServerUrl: string, force?: boolean, reason?: SessionRefreshReason): Promise<boolean>;
 /** How long the outcome of a recovery is reused for: requests that fail together share one refresh, and a session that will not come back is not asked again at once. */
 export declare const SESSION_RECOVERY_COOLDOWN_MS: number;
 /**
- * Renews the session because a request was refused for lack of one, whatever this browser's record of the last refresh says. Every request
- * refused at about the same time shares one refresh, and its outcome is reused for `SESSION_RECOVERY_COOLDOWN_MS`. A refusal also clears the record of
- * the last refresh, so the next regular check asks again (and sends the browser to sign-in if the refresh token is truly gone).
+ * Renews the session because a request was refused for lack of one, whatever this browser's record of the last refresh says - except that a refresh that
+ * succeeded within `SESSION_REFRESH_MIN_GAP_MS` (by this tab or another) is not repeated: the request was refused with the cookies from before it, so it is
+ * simply sent again with the new ones. Every request refused at about the same time shares one refresh, and its outcome is reused for `SESSION_RECOVERY_COOLDOWN_MS`.
+ * A refusal also clears the record of the last refresh, so the next regular check asks again (and sends the browser to sign-in if the refresh token is truly gone).
  *
  * @returns Whether the session was renewed.
  */
 export declare function recoverSession(authServerUrl: string): Promise<boolean>;
-/** Forgets what recoveries have done (for tests). */
+/** Forgets what recoveries and refreshes have done, and restores the retry delay and timeout (for tests). */
 export declare function resetSessionRecovery(): void;
 /**
  * Redirects the browser to auth-server's sign-in page when `userUid` is absent, carrying the current URL as
@@ -66,9 +103,11 @@ export interface SessionRefreshOptions {
  * - `userUid` set: also renews the session when a request is refused for lack of one (`apiFetch()` asks `recoverSession()` and sends the request
  * again), so a token that ran out while timers were stopped costs nothing. Refreshes once the token is `SESSION_REFRESH_AFTER_MS` old (and right away when this browser has no
  * record of a recent refresh, since the page's token age is unknown), checked every `SESSION_REFRESH_CHECK_MS` and
- * whenever the tab becomes visible or the network returns, because a sleeping laptop stops timers. A failure that is
- * not a rejection is simply retried at the next check. A rejection (`401`/`403`: the refresh token expired or was
- * revoked, so the session cannot be kept) redirects to sign-in with `return_to` after `options.beforeRedirect` has run.
+ * whenever the tab becomes visible or focused or the network returns, because a sleeping laptop stops timers (a tab that wakes after the
+ * token's hour checks first, and a request refused meanwhile waits for that same refresh rather than starting its own). A failure that is
+ * not a rejection is simply retried at the next check. A rejection (`401`/`403` twice running, `SESSION_REFRESH_RETRY_MS` apart: the refresh
+ * token expired or was revoked, so the session cannot be kept) redirects to sign-in with `return_to` after `options.beforeRedirect` has run.
+ * Everything it does is recorded in the session log (`getSessionLog()`), which is also printed to the console when the browser goes to sign-in.
  *
  * **A no-op under an `ApiClientContext.Provider`** (see `util/apiClientContext.ts`): everything above assumes a
  * `jwt`/`refresh` cookie pair this app can renew through auth-server's own `/auth/refresh` - meaningless for a