@remit/data-ports 0.0.82 → 0.0.84

package/dist/conformance/calendar-suggestion.js

@@ -0,0 +1,255 @@
+import assert from "node:assert/strict";
+import { after, before, describe, test } from "node:test";
+import { CalendarInviteMethod, CalendarSuggestionSource, CalendarSuggestionState, ZoneCertainty, } from "@remit/domain-enums";
+import { deriveCalendarSuggestionId } from "../id.js";
+const suggestion = (accountConfigId, messageId, bodyPartId, icalUid, overrides = {}) => ({
+    accountConfigId,
+    messageId,
+    bodyPartId,
+    icalUid,
+    sequence: 0,
+    method: CalendarInviteMethod.Request,
+    source: CalendarSuggestionSource.IcalendarPart,
+    summary: "Design review",
+    dtStart: "2026-09-01T10:00:00+02:00",
+    dtEnd: "2026-09-01T11:00:00+02:00",
+    endsAtUtc: "2026-09-01T09:00:00Z",
+    allDay: false,
+    location: "",
+    organizer: "organizer@example.test",
+    zoneCertainty: ZoneCertainty.Explicit,
+    icalData: "BEGIN:VCALENDAR\r\nEND:VCALENDAR\r\n",
+    ...overrides,
+});
+const EARLIEST_INSTANT = "1970-01-01T00:00:00.000Z";
+export function calendarSuggestionRepositoryConformance(harness) {
+    describe("ICalendarSuggestionRepository conformance", () => {
+        let repo;
+        before(async () => {
+            repo = await harness.createRepository();
+        });
+        after(() => harness.teardown());
+        test("put writes a Pending suggestion under its derived id", async () => {
+            const accountConfigId = harness.makeId();
+            const messageId = harness.makeId();
+            const bodyPartId = harness.makeId();
+            const written = await repo.put(suggestion(accountConfigId, messageId, bodyPartId, "uid-1"));
+            assert.equal(written.suggestionId, deriveCalendarSuggestionId(messageId, bodyPartId, "uid-1"));
+            assert.equal(written.state, CalendarSuggestionState.Pending);
+            assert.equal(written.acceptedCalendarObjectId, "");
+        });
+        test("put re-reading the same message converges on one row", async () => {
+            const accountConfigId = harness.makeId();
+            const messageId = harness.makeId();
+            const bodyPartId = harness.makeId();
+            await repo.put(suggestion(accountConfigId, messageId, bodyPartId, "uid-1"));
+            await repo.put(suggestion(accountConfigId, messageId, bodyPartId, "uid-1", {
+                summary: "Design review, moved",
+            }));
+            const rows = await repo.listByMessage(accountConfigId, messageId);
+            assert.equal(rows.length, 1);
+            assert.equal(rows[0]?.summary, "Design review, moved");
+        });
+        test("put leaves an answered suggestion answered", async () => {
+            // A re-sync must never walk a decision back to Pending: the user
+            // already added this event to a calendar, and a producer write is not
+            // allowed to un-decide that.
+            const accountConfigId = harness.makeId();
+            const messageId = harness.makeId();
+            const bodyPartId = harness.makeId();
+            const written = await repo.put(suggestion(accountConfigId, messageId, bodyPartId, "uid-1"));
+            await repo.settle(accountConfigId, written.suggestionId, {
+                state: CalendarSuggestionState.Accepted,
+                acceptedCalendarObjectId: "cal-object-1",
+            });
+            await repo.put(suggestion(accountConfigId, messageId, bodyPartId, "uid-1"));
+            const reread = await repo.get(accountConfigId, written.suggestionId);
+            assert.equal(reread.state, CalendarSuggestionState.Accepted);
+            assert.equal(reread.acceptedCalendarObjectId, "cal-object-1");
+        });
+        test("get rejects a suggestion that is not there", async () => {
+            const accountConfigId = harness.makeId();
+            await assert.rejects(() => repo.get(accountConfigId, harness.makeId()), (error) => harness.isNotFoundError(error));
+        });
+        test("get scopes to the account config", async () => {
+            const accountConfigId = harness.makeId();
+            const written = await repo.put(suggestion(accountConfigId, harness.makeId(), harness.makeId(), "uid"));
+            await assert.rejects(() => repo.get(harness.makeId(), written.suggestionId), (error) => harness.isNotFoundError(error));
+        });
+        test("listByMessage returns every suggestion one message produced", async () => {
+            const accountConfigId = harness.makeId();
+            const messageId = harness.makeId();
+            const other = harness.makeId();
+            await repo.put(suggestion(accountConfigId, messageId, harness.makeId(), "uid-a"));
+            await repo.put(suggestion(accountConfigId, messageId, harness.makeId(), "uid-b"));
+            await repo.put(suggestion(accountConfigId, other, harness.makeId(), "uid-c"));
+            const rows = await repo.listByMessage(accountConfigId, messageId);
+            assert.deepEqual(rows.map((row) => row.icalUid).sort(), [
+                "uid-a",
+                "uid-b",
+            ]);
+        });
+        test("listByState returns only the state asked for", async () => {
+            const accountConfigId = harness.makeId();
+            const pending = await repo.put(suggestion(accountConfigId, harness.makeId(), harness.makeId(), "p"));
+            const declined = await repo.put(suggestion(accountConfigId, harness.makeId(), harness.makeId(), "d"));
+            await repo.settle(accountConfigId, declined.suggestionId, {
+                state: CalendarSuggestionState.Declined,
+                acceptedCalendarObjectId: "",
+            });
+            const page = await repo.listByState(accountConfigId, CalendarSuggestionState.Pending, { endsAfter: EARLIEST_INSTANT });
+            assert.deepEqual(page.items.map((row) => row.suggestionId), [pending.suggestionId]);
+        });
+        test("listByState drops a suggestion that ended before endsAfter, comparing instants across offsets", async () => {
+            const accountConfigId = harness.makeId();
+            await repo.put(suggestion(accountConfigId, harness.makeId(), harness.makeId(), "ended", {
+                dtEnd: "2026-10-06T23:00:00+14:00",
+                endsAtUtc: "2026-10-06T09:00:00Z",
+            }));
+            const running = await repo.put(suggestion(accountConfigId, harness.makeId(), harness.makeId(), "running", {
+                dtEnd: "2026-10-06T01:00:00-12:00",
+                endsAtUtc: "2026-10-06T13:00:00Z",
+            }));
+            const page = await repo.listByState(accountConfigId, CalendarSuggestionState.Pending, { endsAfter: "2026-10-06T10:00:00Z" });
+            assert.deepEqual(page.items.map((row) => row.suggestionId), [running.suggestionId]);
+        });
+        test("listByState keeps a suggestion ending exactly at endsAfter", async () => {
+            const accountConfigId = harness.makeId();
+            const boundary = await repo.put(suggestion(accountConfigId, harness.makeId(), harness.makeId(), "edge", {
+                endsAtUtc: "2026-10-06T10:00:00Z",
+            }));
+            const page = await repo.listByState(accountConfigId, CalendarSuggestionState.Pending, { endsAfter: "2026-10-06T10:00:00Z" });
+            assert.deepEqual(page.items.map((row) => row.suggestionId), [boundary.suggestionId]);
+        });
+        test("listByState scopes to the account config", async () => {
+            const accountConfigId = harness.makeId();
+            await repo.put(suggestion(harness.makeId(), harness.makeId(), harness.makeId(), "x"));
+            const page = await repo.listByState(accountConfigId, CalendarSuggestionState.Pending, { endsAfter: EARLIEST_INSTANT });
+            assert.equal(page.items.length, 0);
+        });
+        test("listByState pages, and the token resumes where the page stopped", async () => {
+            const accountConfigId = harness.makeId();
+            for (const uid of ["a", "b", "c"]) {
+                await repo.put(suggestion(accountConfigId, harness.makeId(), harness.makeId(), uid));
+            }
+            const first = await repo.listByState(accountConfigId, CalendarSuggestionState.Pending, { endsAfter: EARLIEST_INSTANT, limit: 2 });
+            assert.equal(first.items.length, 2);
+            assert.ok(first.continuationToken);
+            const second = await repo.listByState(accountConfigId, CalendarSuggestionState.Pending, {
+                endsAfter: EARLIEST_INSTANT,
+                limit: 2,
+                continuationToken: first.continuationToken,
+            });
+            const seen = [...first.items, ...second.items].map((row) => row.suggestionId);
+            assert.equal(new Set(seen).size, 3);
+        });
+        test("listByAcceptedCalendarObjects returns, in one read, the account's suggestions answered into any of the resources", async () => {
+            const accountConfigId = harness.makeId();
+            const first = await repo.put(suggestion(accountConfigId, harness.makeId(), harness.makeId(), "uid"));
+            const second = await repo.put(suggestion(accountConfigId, harness.makeId(), harness.makeId(), "uid"));
+            const elsewhere = await repo.put(suggestion(accountConfigId, harness.makeId(), harness.makeId(), "uid"));
+            const unasked = await repo.put(suggestion(accountConfigId, harness.makeId(), harness.makeId(), "uid"));
+            const stranger = harness.makeId();
+            const strangers = await repo.put(suggestion(stranger, harness.makeId(), harness.makeId(), "uid"));
+            for (const [owner, row, objectId] of [
+                [accountConfigId, first, "cal-object-1"],
+                [accountConfigId, second, "cal-object-1"],
+                [accountConfigId, elsewhere, "cal-object-2"],
+                [accountConfigId, unasked, "cal-object-3"],
+                [stranger, strangers, "cal-object-1"],
+            ]) {
+                await repo.settle(owner, row.suggestionId, {
+                    state: CalendarSuggestionState.Accepted,
+                    acceptedCalendarObjectId: objectId,
+                });
+            }
+            const rows = await repo.listByAcceptedCalendarObjects(accountConfigId, [
+                "cal-object-1",
+                "cal-object-2",
+            ]);
+            assert.deepEqual(rows.map((row) => row.suggestionId).sort(), [
+                first.suggestionId,
+                second.suggestionId,
+                elsewhere.suggestionId,
+            ].sort());
+            assert.deepEqual(await repo.listByAcceptedCalendarObjects(accountConfigId, []), []);
+        });
+        test("settle records the accepted resource", async () => {
+            const accountConfigId = harness.makeId();
+            const written = await repo.put(suggestion(accountConfigId, harness.makeId(), harness.makeId(), "uid"));
+            const settled = await repo.settle(accountConfigId, written.suggestionId, {
+                state: CalendarSuggestionState.Accepted,
+                acceptedCalendarObjectId: "cal-object-9",
+            });
+            assert.equal(settled.state, CalendarSuggestionState.Accepted);
+            assert.equal(settled.acceptedCalendarObjectId, "cal-object-9");
+        });
+        test("supersedeIfPending retires a card still waiting on the user", async () => {
+            const accountConfigId = harness.makeId();
+            const written = await repo.put(suggestion(accountConfigId, harness.makeId(), harness.makeId(), "uid"));
+            const newerMessageId = harness.makeId();
+            const retired = await repo.supersedeIfPending(accountConfigId, written.suggestionId, newerMessageId);
+            assert.equal(retired?.state, CalendarSuggestionState.Superseded);
+            const reread = await repo.get(accountConfigId, written.suggestionId);
+            assert.equal(reread.supersededByMessageId, newerMessageId);
+        });
+        test("a re-read of the retired message keeps the revision that retired it", async () => {
+            const accountConfigId = harness.makeId();
+            const input = suggestion(accountConfigId, harness.makeId(), harness.makeId(), "uid");
+            const written = await repo.put(input);
+            const newerMessageId = harness.makeId();
+            await repo.supersedeIfPending(accountConfigId, written.suggestionId, newerMessageId);
+            const rewritten = await repo.put(input);
+            assert.equal(rewritten.state, CalendarSuggestionState.Superseded);
+            assert.equal(rewritten.supersededByMessageId, newerMessageId);
+        });
+        test("supersedeIfPending leaves an answered card alone and says so", async () => {
+            // The producer reads the pending set and writes to it in two steps. A
+            // person accepting in between must keep their acceptance — and the
+            // link to the event it put in their calendar.
+            const accountConfigId = harness.makeId();
+            const written = await repo.put(suggestion(accountConfigId, harness.makeId(), harness.makeId(), "uid"));
+            await repo.settle(accountConfigId, written.suggestionId, {
+                state: CalendarSuggestionState.Accepted,
+                acceptedCalendarObjectId: "cal-object-7",
+            });
+            const retired = await repo.supersedeIfPending(accountConfigId, written.suggestionId, harness.makeId());
+            assert.equal(retired, null);
+            const reread = await repo.get(accountConfigId, written.suggestionId);
+            assert.equal(reread.state, CalendarSuggestionState.Accepted);
+            assert.equal(reread.supersededByMessageId, "");
+            assert.equal(reread.acceptedCalendarObjectId, "cal-object-7");
+        });
+        test("supersedeIfPending scopes to the account config", async () => {
+            const accountConfigId = harness.makeId();
+            const written = await repo.put(suggestion(accountConfigId, harness.makeId(), harness.makeId(), "uid"));
+            assert.equal(await repo.supersedeIfPending(harness.makeId(), written.suggestionId, harness.makeId()), null);
+        });
+        test("repointSuperseded moves a retired card to a later revision", async () => {
+            const accountConfigId = harness.makeId();
+            const written = await repo.put(suggestion(accountConfigId, harness.makeId(), harness.makeId(), "uid"));
+            await repo.supersedeIfPending(accountConfigId, written.suggestionId, harness.makeId());
+            const newest = harness.makeId();
+            const repointed = await repo.repointSuperseded(accountConfigId, written.suggestionId, newest);
+            assert.equal(repointed?.supersededByMessageId, newest);
+            const reread = await repo.get(accountConfigId, written.suggestionId);
+            assert.equal(reread.state, CalendarSuggestionState.Superseded);
+            assert.equal(reread.supersededByMessageId, newest);
+        });
+        test("repointSuperseded leaves a card that is not superseded alone", async () => {
+            const accountConfigId = harness.makeId();
+            const written = await repo.put(suggestion(accountConfigId, harness.makeId(), harness.makeId(), "uid"));
+            assert.equal(await repo.repointSuperseded(accountConfigId, written.suggestionId, harness.makeId()), null);
+            const reread = await repo.get(accountConfigId, written.suggestionId);
+            assert.equal(reread.state, CalendarSuggestionState.Pending);
+            assert.equal(reread.supersededByMessageId, "");
+        });
+        test("settle rejects a suggestion that is not there", async () => {
+            const accountConfigId = harness.makeId();
+            await assert.rejects(() => repo.settle(accountConfigId, harness.makeId(), {
+                state: CalendarSuggestionState.Declined,
+                acceptedCalendarObjectId: "",
+            }), (error) => harness.isNotFoundError(error));
+        });
+    });
+}

package/{src/conformance/harness.ts → dist/conformance/harness.d.ts}

@@ -5,8 +5,8 @@
  * which differ per implementation.
  */
 export interface RepositoryConformanceHarness<TRepo> {
-	createRepository(): Promise<TRepo>;
-	teardown(): Promise<void>;
-	makeId(): string;
-	isNotFoundError(error: unknown): boolean;
+    createRepository(): Promise<TRepo>;
+    teardown(): Promise<void>;
+    makeId(): string;
+    isNotFoundError(error: unknown): boolean;
 }

package/dist/conformance/harness.js

@@ -0,0 +1 @@
+export {};

package/dist/conformance/index.js

@@ -0,0 +1,8 @@
+export { accountRepositoryConformance } from "./account.js";
+export { calendarCollectionRepositoryConformance } from "./calendar-collection.js";
+export { calendarEventIndexRepositoryConformance } from "./calendar-event-index.js";
+export { calendarFeedTokenRepositoryConformance } from "./calendar-feed-token.js";
+export { calendarObjectRepositoryConformance } from "./calendar-object.js";
+export { calendarSuggestionRepositoryConformance } from "./calendar-suggestion.js";
+export { labelRepositoryConformance } from "./label.js";
+export { senderSignerStandingRepositoryConformance } from "./sender-signer-standing.js";

package/dist/conformance/label.d.ts

@@ -0,0 +1,3 @@
+import type { ILabelRepository } from "../interfaces/label.js";
+import type { RepositoryConformanceHarness } from "./harness.js";
+export declare function labelRepositoryConformance(harness: RepositoryConformanceHarness<ILabelRepository>): void;

package/dist/conformance/label.js

@@ -0,0 +1,92 @@
+import assert from "node:assert/strict";
+import { after, before, describe, test } from "node:test";
+import { LabelColor } from "@remit/domain-enums";
+export function labelRepositoryConformance(harness) {
+    describe("ILabelRepository conformance", () => {
+        let repo;
+        before(async () => {
+            repo = await harness.createRepository();
+        });
+        after(() => harness.teardown());
+        test("create derives normalizedName and defaults color", async () => {
+            const accountConfigId = harness.makeId();
+            const label = await repo.create({
+                accountConfigId,
+                name: "  Receipts  ",
+            });
+            assert.equal(label.name, "  Receipts  ");
+            assert.equal(label.normalizedName, "receipts");
+            assert.equal(label.color, LabelColor.Default);
+        });
+        test("get throws a not-found error for a missing label", async () => {
+            await assert.rejects(repo.get(harness.makeId(), harness.makeId()), (error) => harness.isNotFoundError(error));
+        });
+        test("update re-derives normalizedName when the name changes", async () => {
+            const accountConfigId = harness.makeId();
+            const label = await repo.create({ accountConfigId, name: "Old Name" });
+            const updated = await repo.update(accountConfigId, label.labelId, {
+                name: "New Name",
+            });
+            assert.equal(updated.name, "New Name");
+            assert.equal(updated.normalizedName, "new name");
+        });
+        test("update throws a not-found error for a missing label", async () => {
+            await assert.rejects(repo.update(harness.makeId(), harness.makeId(), { name: "x" }), (error) => harness.isNotFoundError(error));
+        });
+        test("listByAccountConfig scopes to the account", async () => {
+            const accountConfigId = harness.makeId();
+            const other = harness.makeId();
+            const mine = await repo.create({ accountConfigId, name: "Mine" });
+            await repo.create({ accountConfigId: other, name: "Foreign" });
+            const labels = await repo.listByAccountConfig(accountConfigId);
+            assert.equal(labels.length, 1);
+            assert.equal(labels[0]?.labelId, mine.labelId);
+        });
+        test("findByNormalizedName dedupes case- and whitespace-insensitively", async () => {
+            const accountConfigId = harness.makeId();
+            const label = await repo.create({ accountConfigId, name: "Work" });
+            const found = await repo.findByNormalizedName(accountConfigId, "WORK");
+            assert.equal(found?.labelId, label.labelId);
+            const missing = await repo.findByNormalizedName(accountConfigId, "nonexistent");
+            assert.equal(missing, null);
+        });
+        test("listPageByAccountConfig pages through an account's labels, scoped to the account", async () => {
+            const accountConfigId = harness.makeId();
+            const other = harness.makeId();
+            // Created concurrently so their `createdAt` millisecond can tie (as it
+            // reliably does against the synchronous sqlite driver): the keyset's
+            // `labelId` tiebreak then decides order, so this asserts pagination is
+            // exhaustive and duplicate-free rather than a specific creation order.
+            const created = await Promise.all([
+                repo.create({ accountConfigId, name: "First" }),
+                repo.create({ accountConfigId, name: "Second" }),
+            ]);
+            await repo.create({ accountConfigId: other, name: "Foreign" });
+            const page1 = await repo.listPageByAccountConfig(accountConfigId, {
+                limit: 1,
+            });
+            assert.equal(page1.items.length, 1);
+            assert.ok(page1.continuationToken);
+            const page2 = await repo.listPageByAccountConfig(accountConfigId, {
+                limit: 1,
+                continuationToken: page1.continuationToken,
+            });
+            assert.equal(page2.items.length, 1);
+            assert.equal(page2.continuationToken, undefined);
+            const seen = new Set([
+                ...page1.items.map((label) => label.labelId),
+                ...page2.items.map((label) => label.labelId),
+            ]);
+            assert.equal(seen.size, created.length, "every label is paged exactly once");
+            for (const label of created) {
+                assert.ok(seen.has(label.labelId));
+            }
+        });
+        test("delete removes the row", async () => {
+            const accountConfigId = harness.makeId();
+            const label = await repo.create({ accountConfigId, name: "Gone" });
+            await repo.delete(accountConfigId, label.labelId);
+            await assert.rejects(repo.get(accountConfigId, label.labelId), (error) => harness.isNotFoundError(error));
+        });
+    });
+}

package/dist/conformance/sender-signer-standing.d.ts

@@ -0,0 +1,3 @@
+import type { ISenderSignerStandingRepository } from "../interfaces/sender-signer-standing.js";
+import type { RepositoryConformanceHarness } from "./harness.js";
+export declare function senderSignerStandingRepositoryConformance(harness: RepositoryConformanceHarness<ISenderSignerStandingRepository>): void;

package/dist/conformance/sender-signer-standing.js

@@ -0,0 +1,81 @@
+import assert from "node:assert/strict";
+import { after, before, describe, test } from "node:test";
+export function senderSignerStandingRepositoryConformance(harness) {
+    describe("ISenderSignerStandingRepository conformance", () => {
+        let repo;
+        before(async () => {
+            repo = await harness.createRepository();
+        });
+        after(() => harness.teardown());
+        test("the first observation creates the row at a count of one", async () => {
+            const accountConfigId = harness.makeId();
+            const observedAt = 1_700_000_000_000;
+            const standing = await repo.observe({
+                accountConfigId,
+                senderKey: "example.com",
+                signerDomain: "esp.example",
+                observedAt,
+            });
+            assert.equal(standing.messageCount, 1);
+            assert.equal(standing.firstSeenAt, observedAt);
+            assert.equal(standing.lastSeenAt, observedAt);
+            assert.equal(standing.userAffirmedAt, 0);
+        });
+        test("a repeat observation increments the count", async () => {
+            const accountConfigId = harness.makeId();
+            const key = {
+                accountConfigId,
+                senderKey: "example.com",
+                signerDomain: "esp.example",
+            };
+            await repo.observe({ ...key, observedAt: 1_700_000_000_000 });
+            const second = await repo.observe({
+                ...key,
+                observedAt: 1_700_000_060_000,
+            });
+            assert.equal(second.messageCount, 2);
+            assert.equal((await repo.get(accountConfigId, key.senderKey, key.signerDomain))
+                .messageCount, 2);
+        });
+        test("firstSeenAt survives every later observation while lastSeenAt advances", async () => {
+            const accountConfigId = harness.makeId();
+            const key = {
+                accountConfigId,
+                senderKey: "news.example.com",
+                signerDomain: "unverified",
+            };
+            const first = 1_700_000_000_000;
+            await repo.observe({ ...key, observedAt: first });
+            await repo.observe({ ...key, observedAt: first + 60_000 });
+            const third = await repo.observe({ ...key, observedAt: first + 120_000 });
+            assert.equal(third.messageCount, 3);
+            assert.equal(third.firstSeenAt, first);
+            assert.equal(third.lastSeenAt, first + 120_000);
+            const reread = await repo.get(accountConfigId, key.senderKey, key.signerDomain);
+            assert.equal(reread.firstSeenAt, first);
+            assert.equal(reread.lastSeenAt, first + 120_000);
+        });
+        test("a key differing only in signer domain is a separate row", async () => {
+            const accountConfigId = harness.makeId();
+            const observedAt = 1_700_000_000_000;
+            await repo.observe({
+                accountConfigId,
+                senderKey: "example.com",
+                signerDomain: "esp-one.example",
+                observedAt,
+            });
+            const other = await repo.observe({
+                accountConfigId,
+                senderKey: "example.com",
+                signerDomain: "esp-two.example",
+                observedAt,
+            });
+            assert.equal(other.messageCount, 1);
+        });
+        test("get reports not-found for a key never observed, and does not create it", async () => {
+            const accountConfigId = harness.makeId();
+            await assert.rejects(repo.get(accountConfigId, "stranger.example", "esp.example"), (error) => harness.isNotFoundError(error));
+            await assert.rejects(repo.get(accountConfigId, "stranger.example", "esp.example"), (error) => harness.isNotFoundError(error));
+        });
+    });
+}

package/dist/display-name.d.ts

@@ -0,0 +1 @@
+export declare const storedDisplayName: (displayName: string | undefined, normalizedEmail: string | undefined) => string;

package/dist/display-name.js

@@ -0,0 +1,26 @@
+const EMBEDDED_ADDRESS = /[^\s@<>()[\],;:"'\\]+@[^\s@<>()[\],;:"'\\]+\.[^\s@<>()[\],;:"'\\.]{2,}/gu;
+const DELIMITER_PAIR_LEFT_EMPTY = /[<([{"']\s*[>)\]}"']/gu;
+const LEADING_OR_TRAILING_SEPARATORS = /^[\s,;:|/\\-]+|[\s,;:|/\\-]+$/gu;
+const tidyAfterAddressRemoval = (text) => text
+    .replace(DELIMITER_PAIR_LEFT_EMPTY, " ")
+    .replace(/\s+/gu, " ")
+    .replace(LEADING_OR_TRAILING_SEPARATORS, "")
+    .trim();
+const carriesAddressOtherThan = (text, ownAddress) => {
+    for (const [address] of text.matchAll(EMBEDDED_ADDRESS)) {
+        if (address.toLowerCase() !== ownAddress)
+            return true;
+    }
+    return false;
+};
+export const storedDisplayName = (displayName, normalizedEmail) => {
+    if (!displayName)
+        return "";
+    const ownAddress = normalizedEmail?.toLowerCase();
+    if (!carriesAddressOtherThan(displayName, ownAddress))
+        return displayName;
+    const remainder = tidyAfterAddressRemoval(displayName.replace(EMBEDDED_ADDRESS, (address) => address.toLowerCase() === ownAddress ? address : " "));
+    if (!remainder || carriesAddressOtherThan(remainder, ownAddress))
+        return "";
+    return remainder;
+};

package/dist/errors.d.ts

@@ -0,0 +1,150 @@
+import type { CanonicalMailboxRoleValue, FolderRoleUnresolvedReason } from "./folder-role.js";
+export type { FolderRoleUnresolvedReason };
+/**
+ * The half of an error a client may read: a stable `code` it branches on and
+ * string `details` it words its own prompt from. Opt-in — an error that
+ * declares none keeps today's `{ message }` body, so no response gains a
+ * shape the API never promised and no internal failure leaks its innards.
+ */
+export interface PublicApiError {
+    code: string;
+    details?: Record<string, string>;
+}
+export declare const isPublicApiError: (value: unknown) => value is PublicApiError;
+export declare class HTTPError extends Error {
+    statusCode: number;
+    publicApiError?: PublicApiError;
+}
+export declare class BadRequestError extends HTTPError {
+    name: string;
+    statusCode: number;
+}
+export declare class ClientError extends HTTPError {
+    name: string;
+    statusCode: number;
+}
+export declare class ForbiddenError extends HTTPError {
+    name: string;
+    statusCode: number;
+}
+export declare class NotFoundError extends HTTPError {
+    name: string;
+    statusCode: number;
+}
+export declare class ConflictError extends HTTPError {
+    name: string;
+    statusCode: number;
+}
+/**
+ * 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 declare class FolderRoleUnresolvedError extends ConflictError {
+    name: string;
+    constructor(message: string, role: CanonicalMailboxRoleValue, reason: FolderRoleUnresolvedReason, accountId: string);
+}
+/**
+ * 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 declare class MailboxNotSettledError extends HTTPError {
+    name: string;
+    statusCode: number;
+    constructor(message: string, mailboxId: string, syncStatus: string);
+}
+/**
+ * Why the row's folder and uid do not name the same message. One value, because
+ * one state produces it: a mutation is still in flight and the pair clears on
+ * its own, so the client words a wait rather than a repair. A mutation that
+ * gave up does not reach here — it hands the row back to a placement the server
+ * confirmed first (docs/architecture/imap-mutations.md R3), which is a pair
+ * every dependent mutation can act on.
+ */
+export type MessagePlacementUnsettledReason = "in_flight";
+export declare class MessagePlacementUnsettledError extends ConflictError {
+    name: string;
+    constructor(message: string, accountId: string, messageId: string, reason: MessagePlacementUnsettledReason);
+}
+/**
+ * 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 declare class MessageGoneFromServerError extends NotFoundError {
+    name: string;
+    constructor(messageId: string);
+}
+/**
+ * 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 declare class ConfigNotEmptyError extends ConflictError {
+    name: string;
+    constructor(message: string, details: Record<string, string>);
+}
+/**
+ * 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 declare class UnrecoverableBodyError extends HTTPError {
+    name: string;
+    statusCode: number;
+}
+export declare class CreateFailedConflictError extends ConflictError {
+    statusCode: number;
+    name: string;
+    constructor(resourceType: string, params: unknown);
+}
+export declare class UnhandledError extends HTTPError {
+    name: string;
+    statusCode: number;
+    readonly cause: Error | undefined;
+    constructor(message: string, cause?: Error);
+    toJSON(): {
+        message: string;
+        cause: string | undefined;
+        stack: string | undefined;
+    };
+}
+export declare class InternalServerError extends UnhandledError {
+    name: string;
+    statusCode: number;
+}
+/**
+ * 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 declare const isNotFoundError: (error: unknown) => boolean;
+export declare class MailSyncOffError extends BadRequestError {
+    name: string;
+    constructor(message: string, accountId: string);
+}