@remit/data-ports 0.0.83 → 0.0.85

package/dist/errors.js

@@ -0,0 +1,181 @@
+export const isPublicApiError = (value) => {
+    if (typeof value !== "object" || value === null)
+        return false;
+    if (!("code" in value) || typeof value.code !== "string")
+        return false;
+    if (!("details" in value) || value.details === undefined)
+        return true;
+    if (typeof value.details !== "object" || value.details === null)
+        return false;
+    return Object.values(value.details).every((detail) => typeof detail === "string");
+};
+export class HTTPError extends Error {
+    statusCode = 500;
+    publicApiError;
+}
+export class BadRequestError extends HTTPError {
+    name = "BadRequestError";
+    statusCode = 400;
+}
+export class ClientError extends HTTPError {
+    name = "ClientError";
+    statusCode = 401;
+}
+export class ForbiddenError extends HTTPError {
+    name = "ForbiddenError";
+    statusCode = 403;
+}
+export class NotFoundError extends HTTPError {
+    name = "NotFoundError";
+    statusCode = 404;
+}
+export class ConflictError extends HTTPError {
+    name = "ConflictError";
+    statusCode = 409;
+}
+/**
+ * A destructive action refused because the role it needs is unresolved. The
+ * client reads `code` and words its prompt from `details` — never from the
+ * message — so the copy can change without breaking the branch, and the
+ * account the prompt has to appoint a folder on travels with the refusal
+ * (the delete endpoint's body carries no accountId).
+ */
+export class FolderRoleUnresolvedError extends ConflictError {
+    name = "FolderRoleUnresolvedError";
+    constructor(message, role, reason, accountId) {
+        super(message);
+        this.publicApiError = {
+            code: "folder_role_unresolved",
+            details: { role, reason, accountId },
+        };
+    }
+}
+/**
+ * A durable reference cannot be bound to a mailbox whose own mutation has not
+ * settled (folder-rename-and-delete.md D12, imap-mutations R2: wait). Its own
+ * code, because the role is not unresolved — the target is: the client words a
+ * wait, not a retry. Clearing a role is never refused this way.
+ *
+ * **422, not 409** (D4). 409 already means "this folder is being changed right
+ * now, refresh"; this means "the folder you are pointing at has not settled
+ * yet", which is a different sentence and a different remedy. The status is
+ * what separates them for a client that reads no further.
+ */
+export class MailboxNotSettledError extends HTTPError {
+    name = "MailboxNotSettledError";
+    statusCode = 422;
+    constructor(message, mailboxId, syncStatus) {
+        super(message);
+        this.publicApiError = {
+            code: "mailbox_not_settled",
+            details: { mailboxId, syncStatus },
+        };
+    }
+}
+export class MessagePlacementUnsettledError extends ConflictError {
+    name = "MessagePlacementUnsettledError";
+    constructor(message, accountId, messageId, reason) {
+        super(message);
+        this.publicApiError = {
+            code: "message_placement_unsettled",
+            details: { accountId, messageId, reason },
+        };
+    }
+}
+/**
+ * The row named a message the mail server no longer holds at that UID —
+ * another client expunged it or moved it away. Distinct from a plain
+ * not-found so the client can say where the message went rather than
+ * claiming the user deleted it.
+ */
+export class MessageGoneFromServerError extends NotFoundError {
+    name = "MessageGoneFromServerError";
+    constructor(messageId) {
+        super("This message is no longer on the mail server.");
+        this.publicApiError = {
+            code: "message_gone_from_server",
+            details: { messageId },
+        };
+    }
+}
+/**
+ * A configuration import refused because this configuration is not empty
+ * (#1021). The default is to refuse rather than to fold the file in: a person
+ * importing over a configuration they forgot they had should hear about it
+ * before anything moves. `details` counts what is already here, so the client
+ * can say what would be merged, and the same request with `onExisting: merge`
+ * goes through.
+ */
+export class ConfigNotEmptyError extends ConflictError {
+    name = "ConfigNotEmptyError";
+    constructor(message, details) {
+        super(message);
+        this.publicApiError = { code: "config_not_empty", details };
+    }
+}
+/**
+ * A message exists but its body could not be fetched/parsed after every
+ * body-sync retry was spent (issue #1270 / epic #1281 invariant 3). This is
+ * distinct from `NotFoundError`: the message is real, but its content is
+ * permanently unavailable — the client must show an explicit, actionable
+ * error instead of retrying (no 202, no silent skip).
+ */
+export class UnrecoverableBodyError extends HTTPError {
+    name = "UnrecoverableBodyError";
+    statusCode = 422;
+}
+export class CreateFailedConflictError extends ConflictError {
+    statusCode = 409;
+    name = "CreateFailedConflictError";
+    constructor(resourceType, params) {
+        super(`${resourceType} with properties "${JSON.stringify(params)}" already exists.`);
+    }
+}
+export class UnhandledError extends HTTPError {
+    name = "UnhandledError";
+    statusCode = 500;
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.message = message;
+        if (cause)
+            this.cause = cause;
+    }
+    toJSON() {
+        return {
+            message: this.message,
+            cause: this.cause?.message,
+            stack: this.cause?.stack || this.stack,
+        };
+    }
+}
+export class InternalServerError extends UnhandledError {
+    name = "InternalServerError";
+    statusCode = 500;
+}
+/**
+ * A repository lookup or write for a row that no longer exists rejects with a
+ * `NotFoundError`, name-matched rather than by `instanceof`: the class crosses
+ * the adapter boundary and an adapter may throw its own.
+ *
+ * A worker event that references a deliberately-deleted mailbox is completed or
+ * moot work, never a transient fault: every redelivery re-throws the same
+ * `NotFoundError`, and because the sync queues carry `MessageGroupId=accountId`
+ * that permanently-failing head message stalls the whole account's per-group
+ * FIFO. Handlers use this predicate to resolve such an event terminally (ack
+ * with a WARN) instead of retrying forever (issues #287, #289, #290).
+ *
+ * The guard is narrow on purpose: only a genuine not-found terminates. Real
+ * IMAP/infra failures carry other errors and must still propagate to be retried.
+ */
+export const isNotFoundError = (error) => error?.name === "NotFoundError";
+export class MailSyncOffError extends BadRequestError {
+    name = "MailSyncOffError";
+    constructor(message, accountId) {
+        super(message);
+        this.publicApiError = {
+            code: "mail_sync_off",
+            details: { accountId },
+        };
+    }
+}

package/dist/filter-ttl.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Epoch-seconds `ttl` derived from `expiresAt`, set only for a `Temporary`
+ * filter (RFC 034 Decision 1.3). A `Standing` filter never carries `ttl` — the
+ * reserved table-wide TTL attribute must stay absent, or the row would be swept
+ * (Decision 1.4).
+ */
+export declare const deriveFilterTtl: (scope: string, expiresAt: string | undefined) => number | undefined;

package/{src/filter-ttl.ts → dist/filter-ttl.js}

@@ -1,20 +1,17 @@
 import { FilterScope } from "@remit/domain-enums";
 import { BadRequestError } from "./errors.js";
-
 /**
  * Epoch-seconds `ttl` derived from `expiresAt`, set only for a `Temporary`
  * filter (RFC 034 Decision 1.3). A `Standing` filter never carries `ttl` — the
  * reserved table-wide TTL attribute must stay absent, or the row would be swept
  * (Decision 1.4).
  */
-export const deriveFilterTtl = (
-	scope: string,
-	expiresAt: string | undefined,
-): number | undefined => {
-	if (scope !== FilterScope.Temporary || !expiresAt) return undefined;
-	const ms = new Date(expiresAt).getTime();
-	if (Number.isNaN(ms)) {
-		throw new BadRequestError(`Invalid expiresAt: ${expiresAt}`);
-	}
-	return Math.floor(ms / 1000);
+export const deriveFilterTtl = (scope, expiresAt) => {
+    if (scope !== FilterScope.Temporary || !expiresAt)
+        return undefined;
+    const ms = new Date(expiresAt).getTime();
+    if (Number.isNaN(ms)) {
+        throw new BadRequestError(`Invalid expiresAt: ${expiresAt}`);
+    }
+    return Math.floor(ms / 1000);
 };

package/dist/folder-role.d.ts

@@ -0,0 +1,239 @@
+import { CanonicalMailboxRole, FolderAppointmentSource } from "@remit/domain-enums";
+import { type MailboxNameCandidate } from "./mailbox-name.js";
+export type CanonicalMailboxRoleValue = (typeof CanonicalMailboxRole)[keyof typeof CanonicalMailboxRole];
+/** The fixed anchor set, in the RFC's canonical display order. */
+export declare const CANONICAL_ROLES: readonly CanonicalMailboxRoleValue[];
+/**
+ * The stored `AccountSetting` name holding one role's appointment. Composed
+ * here rather than at either reader, so the backend that writes it and the
+ * repository that reads it can never disagree about the key.
+ */
+export declare const composeFolderRoleAppointmentName: (accountId: string, role: CanonicalMailboxRoleValue) => string;
+/**
+ * The stored `AccountSetting` name holding the path one role's appointed
+ * mailbox had at the moment it was appointed. A sibling row rather than a field
+ * on the appointment, so "never read by resolution" is structural: the
+ * repository composes only the appointment name and cannot reach this one.
+ */
+export declare const composeFolderRoleAppointmentLabelName: (accountId: string, role: CanonicalMailboxRoleValue) => string;
+/**
+ * Split a stored appointment name back into its two-part target. Unlike the
+ * single-target composites (`MailboxRole#<id>`), this setting composes two ids
+ * after the base, so it parses the suffix itself rather than reusing
+ * `targetIdOf`.
+ */
+export declare const parseFolderRoleAppointmentName: (name: string) => {
+    accountId: string;
+    role: CanonicalMailboxRoleValue;
+} | undefined;
+/**
+ * The label row's counterpart, so the config-wide settings batch can recover
+ * the recorded path for a role the same way it recovers the appointment.
+ */
+export declare const parseFolderRoleAppointmentLabelName: (name: string) => {
+    accountId: string;
+    role: CanonicalMailboxRoleValue;
+} | undefined;
+/**
+ * RFC 6154 SPECIAL-USE flag per role. Inbox has no SPECIAL-USE flag (RFC 3501
+ * reserves the name itself); a role with no entry here is matched by name hint
+ * only.
+ */
+export declare const ROLE_SPECIAL_USE: Partial<Record<CanonicalMailboxRoleValue, string>>;
+/**
+ * Weak name hints, ordered best-first and lower case: the last resort for a
+ * provider that advertises no SPECIAL-USE and whose user has appointed
+ * nothing. Deliberately small — a guess that seeds a proposal, never a
+ * substitute for server truth or for what the user chose.
+ */
+export declare const ROLE_NAME_HINTS: Partial<Record<CanonicalMailboxRoleValue, readonly string[]>>;
+/**
+ * The role a folder's own leaf name is most conventionally for. A name that
+ * several roles list goes to the role that ranks it highest, so `All Mail` is
+ * an All folder rather than a lookalike of Archive.
+ *
+ * `name` is the leaf segment, lower case.
+ */
+export declare const roleForFolderName: (name: string) => CanonicalMailboxRoleValue | undefined;
+/**
+ * Whether the mailbox sweep would read a folder with this leaf name as a
+ * duplicate of a role's canonical folder — and so delete its row, and under D8
+ * the mail in it, as soon as another folder carries the role's SPECIAL-USE
+ * flag. It is the sweep's own predicate, so a rename refused on it and a folder
+ * reaped by it can never disagree (docs/architecture/folder-rename-and-delete.md
+ * D5).
+ *
+ * A role with no flag to be a duplicate of is not reserved: nothing reaps a
+ * folder for it.
+ */
+export declare const isReservedFolderName: (name: string) => boolean;
+/**
+ * The pane where a user appoints a folder to a role, named as it is labelled.
+ * Every refusal that asks for an appointment points here, in one wording — the
+ * settings screen is titled "Folder roles", and copies of this sentence had
+ * already drifted to "Folders".
+ */
+export declare const FOLDER_ROLES_SETTINGS_PATH = "Settings \u203A Folder roles";
+/**
+ * Why an operation that files or destroys mail was refused. A delete, an
+ * Empty Trash and the count the handler reports before one all act on the
+ * folder the user appointed or the server flagged, and all refuse in these
+ * words — one sentence, so two surfaces cannot tell a user two things about
+ * one account.
+ */
+export declare const NO_TRASH_FOLDER_REASON = "This account has no Trash folder, so nothing was deleted. Appoint one under Settings \u203A Folder roles, then try again.";
+/**
+ * The folder somebody chose as this account's Trash is no longer on the mail
+ * server. Reader will not quietly file mail into whatever it would have picked
+ * had nobody chosen: the user's choice went missing and only they can replace
+ * it.
+ */
+export declare const STALE_TRASH_FOLDER_REASON = "The folder appointed as this account's Trash is no longer on the mail server, so nothing was deleted. Appoint one under Settings \u203A Folder roles, then try again.";
+/**
+ * A folder matches the Trash name hint and nothing else — enough to file a
+ * delete somewhere retrievable, never enough to erase what is already in it.
+ * Emptying that folder and deleting a message already inside it both land here
+ * (#876), so the sentence names neither verb: "nothing was deleted" is true of
+ * both, the way its two siblings above are.
+ */
+export declare const UNCONFIRMED_TRASH_FOLDER_REASON = "Nobody has confirmed which folder is this account's Trash, so nothing was deleted. Appoint one under Settings \u203A Folder roles, then try again.";
+/**
+ * The mailboxes holding Junk and Trash across a set of accounts, as ids. The
+ * shape a SQL predicate needs when it must ask "is this message in Junk"
+ * without spelling the rule a second time: resolution happens once, here, and
+ * SQL compares mailbox ids.
+ *
+ * A role resolves to at most one mailbox per account, so each list holds one id
+ * per account that has that folder — and no entry at all for an account that
+ * has none.
+ */
+export interface JunkRoleMailboxes {
+    readonly junkMailboxIds: readonly string[];
+    readonly trashMailboxIds: readonly string[];
+}
+/** The minimal mailbox shape role resolution reads. */
+export interface RoleMailboxCandidate extends MailboxNameCandidate {
+    specialUse?: readonly string[];
+}
+/**
+ * What an account with no appointment for the role resolves to, and equally
+ * what a stale appointment falls back to — the fallback can never itself be an
+ * appointment, stale or otherwise.
+ */
+export type UnappointedRoleResolution<T> = {
+    kind: "flagged";
+    mailbox: T;
+} | {
+    kind: "reserved";
+    mailbox: T;
+} | {
+    kind: "proposed";
+    mailbox: T;
+} | {
+    kind: "none";
+};
+/**
+ * What resolving a role for an account answered, and on what evidence. Total:
+ * there is a member for every outcome, so a caller that must weigh the evidence
+ * — Empty Trash may only expunge what somebody designated — reads the tag
+ * instead of inferring it from a `null` that means four different things.
+ *
+ * `appointment_stale` is the case a nullable answer cannot express: the user
+ * appointed a mailbox the account no longer holds. It carries the id they chose
+ * so a surface can offer the repair, and the resolution that would have applied
+ * had they appointed nothing.
+ */
+export type RoleResolution<T> = {
+    kind: "appointed";
+    mailbox: T;
+} | UnappointedRoleResolution<T> | {
+    kind: "appointment_stale";
+    appointedMailboxId: string;
+    fallback: UnappointedRoleResolution<T>;
+};
+/**
+ * The single mailbox that holds a canonical role for an account (RFC 032
+ * exclusive-folder-appointment, #976), in one precedence order every caller
+ * shares:
+ *
+ * 1. the mailbox the user appointed;
+ * 2. the server's own SPECIAL-USE flag (RFC 6154) — language-independent truth;
+ * 3. the reserved `INBOX` name, for the Inbox role only (RFC 3501);
+ * 4. a conventional name, matched on the folder's own leaf segment so it
+ *    resolves at any depth under any prefix.
+ *
+ * The last of those is a guess: a folder named `Deleted` is not evidence that
+ * the user means it as Trash. Use it only where being wrong misfiles a message
+ * a user can move back — never where it destroys mail.
+ */
+export declare const resolveRoleForAccount: <T extends RoleMailboxCandidate>(role: CanonicalMailboxRoleValue, mailboxes: readonly T[], appointedMailboxId?: string) => RoleResolution<T>;
+/**
+ * How much evidence a Trash verb demands. `confirmed` is what an expunge
+ * requires: somebody designated this folder, either the user or the server.
+ * `resolved` additionally accepts the name guess, for filing mail somewhere the
+ * user can retrieve it from. Trash only, deliberately — no other role and no
+ * other verb weighs its evidence, and a matrix over eight roles would be five
+ * gates nobody asked for.
+ */
+export type TrashAssuranceLevel = "confirmed" | "resolved";
+/**
+ * Why a canonical role names no folder an action may act on. `none`: the
+ * account has no candidate at all. `stale`: the folder the user appointed is
+ * gone from the server. `unconfirmed`: a folder matches by name, but nobody —
+ * neither the user nor the server's own flag — ever said it holds the role.
+ * These three and no others; a target that is merely unsettled is a different
+ * refusal under its own code.
+ */
+export type FolderRoleUnresolvedReason = "none" | "stale" | "unconfirmed";
+export type TrashGateOutcome<T> = {
+    allowed: true;
+    mailbox: T;
+} | {
+    allowed: false;
+    reason: FolderRoleUnresolvedReason;
+};
+/**
+ * The Trash folder a verb at this assurance level may act on, or which of the
+ * three reasons stops it. One switch: the delete, the expunge and the count
+ * reported before one all decide here, so no two of them can answer a user
+ * differently about the same account.
+ */
+export declare const trashMailboxAt: <T>(resolution: RoleResolution<T>, level: TrashAssuranceLevel) => TrashGateOutcome<T>;
+export declare const meetsTrashAssurance: <T>(resolution: RoleResolution<T>, level: TrashAssuranceLevel) => boolean;
+export type FolderAppointmentSourceValue = (typeof FolderAppointmentSource)[keyof typeof FolderAppointmentSource];
+/**
+ * The same gate as {@link trashMailboxAt}, asked of the source `/config`
+ * reports rather than of the resolution the server computed — so a client can
+ * word a delete from the answer the service will give it.
+ *
+ * It runs that switch rather than restating it. A hand-written mirror gets
+ * `Reserved` wrong: it reads as designated, and the gate accepts only the user's
+ * appointment and the server's flag.
+ */
+export declare const trashSourceMeetsAssurance: (source: FolderAppointmentSourceValue, level: TrashAssuranceLevel) => boolean;
+/**
+ * The mailbox a role is CONFIRMED to hold: the one the user appointed, or the
+ * one the server flagged (RFC 6154). No name guessing — `null` here means
+ * nobody has said which folder this is, only that a folder happens to be named
+ * something plausible. An operation that destroys mail resolves through this
+ * and refuses when it comes back empty; `resolveMailboxForRole` adds the guess
+ * on top for the operations where being wrong only misfiles a message.
+ *
+ * An appointment naming a mailbox this account does not hold — deleted,
+ * renamed, or carried in from elsewhere — is stale, and answers `null` here
+ * too: the fallback is the folder the user did not choose, which is fine to
+ * file mail into and no basis at all for destroying it.
+ */
+export declare const resolveConfirmedMailboxForRole: <T extends RoleMailboxCandidate>(role: CanonicalMailboxRoleValue, mailboxes: readonly T[], appointedMailboxId?: string) => T | null;
+/**
+ * The role's mailbox including the name guess: `null` only when nothing
+ * matches at all, so the caller says the role has no folder rather than picking
+ * one. A stale appointment answers with its fallback — every role but Trash
+ * files mail on this read, and refusing them all would be a behaviour change
+ * with no surface to explain it.
+ *
+ * Built on `resolveRoleForAccount` directly, never on the confirmed adapter: a
+ * stale appointment must still reach the `\Sent` flag here, not fall past it
+ * into a folder that merely reads like one.
+ */
+export declare const resolveMailboxForRole: <T extends RoleMailboxCandidate>(role: CanonicalMailboxRoleValue, mailboxes: readonly T[], appointedMailboxId?: string) => T | null;