@rapidmx/web-client 0.21.0 → 0.22.0

package/dist/lib/mail/labelsApi.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s `Label` CRUD route (`BaseScopedChildRoute`,
+ * `scopeProperty: "mailboxUid"`) — mailbox-scoped, same pattern as `mailSignaturesApi.ts`. A label is
+ * applied to a message by setting `Message.labelUids` directly (an ordinary field, not read-only - see
+ * `mailApi.ts#setMessageLabels()`), the same way `MailFilterActionType.APPLY_LABEL` does it
+ * automatically for inbound mail; there is no separate "assign" endpoint.
+ */
+import { ApiClient } from "../util/api.js";
+import { ListParams } from "../util/apiQuery.js";
+export type { ListParams };
+export interface Label {
+    uid: string;
+    version: number;
+    dateCreated: string;
+    dateModified: string;
+    mailboxUid: string;
+    name: string;
+    /** An optional hex-ish color hint (same loose convention as `Note.color`) - restapi doesn't
+     * validate its shape. */
+    color?: 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 listLabels(mailboxUid: string, params?: ListParams, client?: ApiClient): Promise<Label[]>;
+export declare function getLabel(uid: string, client?: ApiClient): Promise<Label>;
+export interface CreateLabelInput {
+    mailboxUid: string;
+    name: string;
+    color?: string;
+}
+export declare function createLabel(input: CreateLabelInput, client?: ApiClient): Promise<Label>;
+export interface UpdateLabelInput {
+    uid: string;
+    version: number;
+    name?: string;
+    color?: string;
+}
+export declare function updateLabel(input: UpdateLabelInput, client?: ApiClient): Promise<Label>;
+/**
+ * Deleting a label also strips its uid from every message's `labelUids` in this mailbox
+ * (`BaseLabelRoute.cleanUpDeletedLabel()`, a synchronous full-mailbox scan server-side) - the client
+ * has no separate cleanup step to perform, but a caller with an already-loaded message list should
+ * still drop the deleted uid from any locally-cached `labelUids` itself, since this call doesn't return
+ * the affected messages.
+ */
+export declare function deleteLabel(uid: string, version: number, client?: ApiClient): Promise<void>;

package/dist/lib/mail/labelsApi.js

@@ -0,0 +1,38 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s `Label` CRUD route (`BaseScopedChildRoute`,
+ * `scopeProperty: "mailboxUid"`) — mailbox-scoped, same pattern as `mailSignaturesApi.ts`. A label is
+ * applied to a message by setting `Message.labelUids` directly (an ordinary field, not read-only - see
+ * `mailApi.ts#setMessageLabels()`), the same way `MailFilterActionType.APPLY_LABEL` does it
+ * automatically for inbound mail; there is no separate "assign" endpoint.
+ */
+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 listLabels(mailboxUid, params = {}, client) {
+    return withClient(client, `/mail/labels?${buildQuery(params, { mailboxUid })}`);
+}
+export function getLabel(uid, client) {
+    return withClient(client, `/mail/labels/${encodeURIComponent(uid)}`);
+}
+export function createLabel(input, client) {
+    return withClient(client, "/mail/labels", { method: "POST", body: JSON.stringify(input) });
+}
+export function updateLabel(input, client) {
+    return withClient(client, `/mail/labels/${encodeURIComponent(input.uid)}`, { method: "PUT", body: JSON.stringify(input) });
+}
+/**
+ * Deleting a label also strips its uid from every message's `labelUids` in this mailbox
+ * (`BaseLabelRoute.cleanUpDeletedLabel()`, a synchronous full-mailbox scan server-side) - the client
+ * has no separate cleanup step to perform, but a caller with an already-loaded message list should
+ * still drop the deleted uid from any locally-cached `labelUids` itself, since this call doesn't return
+ * the affected messages.
+ */
+export function deleteLabel(uid, version, client) {
+    return withClient(client, `/mail/labels/${encodeURIComponent(uid)}?version=${version}`, { method: "DELETE" });
+}

package/dist/lib/mail/mailAddress.d.ts

@@ -0,0 +1,27 @@
+/** Anything with a mail address and, optionally, the name it is shown as - a `Recipient`, a message's `from`. `name` is
+ * accepted as a synonym for `displayName` so callers holding either shape can pass it straight in. */
+export interface MailAddressLike {
+    address: string;
+    displayName?: string;
+    name?: string;
+}
+/** A sender/recipient split into what a compact row needs: the name (when there is a distinct one) and the address. */
+export interface MailAddressParts {
+    /** The display name, cleaned up - `undefined` when there is none, or it is only the address again. */
+    name?: string;
+    /** The real address, cleaned up. Always present: every format below shows it, whatever the name says. */
+    address: string;
+}
+/**
+ * Splits a sender or recipient into its name and its address. The name is dropped when it is missing or is just the
+ * address again (compared case-insensitively) - those show as the bare address.
+ */
+export declare function splitMailAddress(recipient: MailAddressLike): MailAddressParts;
+/**
+ * `Name <address@domain>`, or just `address@domain` when there is no distinct name - the form a mail client shows so the
+ * real address is never hidden behind a name. A name with a special character (a comma, a quote, an angle bracket, an
+ * `@` ...) is quoted, `"Doe, Jane" <jane@example.com>`, so it reads as one name and can be pasted into a To field.
+ * The real address always comes last and always appears, whatever the name says - including a name that is itself a
+ * different address (`"ceo@bank.com" <evil@example.net>`).
+ */
+export declare function formatMailAddress(recipient: MailAddressLike): string;

package/dist/lib/mail/mailAddress.js

@@ -0,0 +1,54 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/** Control characters, and the invisible/bidirectional-override characters that can make one string read as another
+ * (U+200B-200F, U+202A-202E, U+2060-2064, U+2066-2069, U+FEFF). */
+// eslint-disable-next-line no-control-regex
+const INVISIBLE_CHARACTERS = /[\u0000-\u001F\u007F-\u009F​-‏‪-‮⁠-⁤⁦-⁩]/g;
+/** Characters that need a display name quoted (RFC 5322's specials, which is what keeps `Doe, Jane` one name), including
+ * the fullwidth and small `@` a reader would take for a real one. */
+const NEEDS_QUOTING = /[()<>[\]:;@＠﹫\\,"]/;
+function clean(value) {
+    return (value ?? "").replace(INVISIBLE_CHARACTERS, " ").replace(/\s+/g, " ").trim();
+}
+/**
+ * An ingested message's `from` sometimes carries the whole `"Bob Allen" <bob@example.com>` From header as its display
+ * name, which would be shown as `"Bob Allen" <bob@example.com> <bob@example.com>`. A name that ends in the sender's own
+ * address in angle brackets is reduced to what precedes it, unquoted. Any other name is left exactly as it is - a name
+ * showing a *different* address is never tidied away, so it can still be seen for what it is.
+ */
+function withoutOwnAddress(name, address) {
+    const wrapped = /^(.*)<([^<>]*)>$/.exec(name);
+    if (!wrapped || wrapped[2].trim().toLowerCase() !== address.toLowerCase()) {
+        return name;
+    }
+    return wrapped[1].trim().replace(/^"(.*)"$/s, "$1").trim();
+}
+/**
+ * Splits a sender or recipient into its name and its address. The name is dropped when it is missing or is just the
+ * address again (compared case-insensitively) - those show as the bare address.
+ */
+export function splitMailAddress(recipient) {
+    const address = clean(recipient.address);
+    const name = withoutOwnAddress(clean(recipient.displayName ?? recipient.name), address);
+    if (!name || name.toLowerCase() === address.toLowerCase()) {
+        return { address };
+    }
+    return { name, address };
+}
+/**
+ * `Name <address@domain>`, or just `address@domain` when there is no distinct name - the form a mail client shows so the
+ * real address is never hidden behind a name. A name with a special character (a comma, a quote, an angle bracket, an
+ * `@` ...) is quoted, `"Doe, Jane" <jane@example.com>`, so it reads as one name and can be pasted into a To field.
+ * The real address always comes last and always appears, whatever the name says - including a name that is itself a
+ * different address (`"ceo@bank.com" <evil@example.net>`).
+ */
+export function formatMailAddress(recipient) {
+    const { name, address } = splitMailAddress(recipient);
+    if (!name) {
+        return address;
+    }
+    const shown = NEEDS_QUOTING.test(name) ? `"${name.replace(/[\\"]/g, "\\$&")}"` : name;
+    return `${shown} <${address}>`;
+}