@remit/data-ports 0.0.56 → 0.0.58

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/data-ports",
-  "version": "0.0.56",
+  "version": "0.0.58",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -37,6 +37,10 @@
       "types": "./src/mutation-events.ts",
       "default": "./src/mutation-events.ts"
     },
+    "./virtual-copy": {
+      "types": "./src/virtual-copy.ts",
+      "default": "./src/virtual-copy.ts"
+    },
     "./mailbox-name": {
       "types": "./src/mailbox-name.ts",
       "default": "./src/mailbox-name.ts"

package/src/interfaces/address.ts

@@ -95,6 +95,18 @@ export interface IAddressRepository {
 		cursor?: string;
 		limit?: number;
 	}): Promise<ResultList<AddressItem>>;
+	/**
+	 * Every address stored under the configuration, for a reader that must see
+	 * the whole set: nothing is hidden, so a row the machine marked `junkOnly`
+	 * still comes back with whatever the user decided about it. Ordered by
+	 * `addressId`, which no write moves, so a page boundary cannot skip a row
+	 * while message sync updates counts and timestamps underneath the read.
+	 */
+	listAllByAccountConfigPage(input: {
+		accountConfigId: string;
+		cursor?: string;
+		limit?: number;
+	}): Promise<ResultList<AddressItem>>;
 	createEnvelopeAddress(
 		input: CreateEnvelopeAddressInput,
 	): Promise<EnvelopeAddressItem>;

package/src/interfaces/outbox-message.ts

@@ -92,5 +92,15 @@ export interface IOutboxMessageRepository {
 		accountId: string,
 		options?: { limit?: number; continuationToken?: string },
 	): Promise<ResultList<OutboxMessageItem>>;
+	/**
+	 * One keyset scan over several accounts, ordered globally by createdAt then
+	 * outboxMessageId. The continuation token names a position in that single
+	 * ordering rather than one position per account, so a second page stays
+	 * coherent however the accounts' rows interleave.
+	 */
+	listByAccounts(
+		accountIds: string[],
+		options?: { limit?: number; continuationToken?: string },
+	): Promise<ResultList<OutboxMessageItem>>;
 	listQueued(accountId: string): Promise<OutboxMessageItem[]>;
 }

package/src/interfaces/thread-message.ts

@@ -47,6 +47,13 @@ export interface IThreadMessageRepository {
 			continuationToken?: string;
 			inboxMailboxIds?: Set<string>;
 			excludeDeleted?: boolean;
+			/**
+			 * Row criteria applied inside the query, so a page is a page of
+			 * matches however rare the criterion is. Filtering the rows a page
+			 * returned instead is what makes a listing look empty whenever the
+			 * matching mail sits below the newest page (#308).
+			 */
+			search?: SearchOptions;
 		},
 	): Promise<ResultList<ThreadMessageItem>>;
 	/**
@@ -100,8 +107,31 @@ export interface IThreadMessageRepository {
 			continuationToken?: string;
 			mailboxIds?: Set<string>;
 			excludeDeleted?: boolean;
+			/** Row criteria applied inside the query; see `listByDate`. */
+			search?: SearchOptions;
 		},
 	): Promise<ResultList<ThreadMessageItem>>;
+	/**
+	 * COUNT of matching CONVERSATIONS over the same predicate and the same
+	 * mailbox scope the three cross-account listing modes read with — the scoped
+	 * counterpart of `countByMailbox`.
+	 *
+	 * A page size bounds the rows a response carries and has no bearing on how
+	 * much matches, so a count returns no rows and is answered in full.
+	 *
+	 * Distinct on `threadId`, unlike `countByMailbox`, because the cross-account
+	 * listing is collapsed by thread before it is rendered: a row is per mailbox,
+	 * so one message reachable through a real folder and a virtual copy of it is
+	 * several rows, and two matching messages of one conversation are two more.
+	 */
+	countThreadsInScope(
+		accountConfigId: string,
+		search: SearchOptions,
+		options?: {
+			mailboxIds?: Set<string>;
+			excludeDeleted?: boolean;
+		},
+	): Promise<number>;
 	/**
 	 * Every message of a thread, across all mailboxes of the account. A
 	 * conversation spans INBOX, Sent and any folder its messages were filed

package/src/virtual-copy.test.ts

@@ -0,0 +1,34 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { MailboxItem } from "./types.js";
+import { isVirtualCopyMailbox } from "./virtual-copy.js";
+
+const mailbox = (fullPath: string, specialUse?: string[]): MailboxItem =>
+	({
+		mailboxId: `mbx-${fullPath}`,
+		fullPath,
+		...(specialUse ? { specialUse } : {}),
+	}) as MailboxItem;
+
+describe("which folders hold a second copy of mail that lives elsewhere", () => {
+	it("reads the special-use the server advertises", () => {
+		assert.equal(isVirtualCopyMailbox(mailbox("Everything", ["All"])), true);
+		assert.equal(isVirtualCopyMailbox(mailbox("Pinned", ["Flagged"])), true);
+		assert.equal(isVirtualCopyMailbox(mailbox("Urgent", ["Important"])), true);
+	});
+
+	it("falls back to the well-known path when the server advertises nothing", () => {
+		assert.equal(isVirtualCopyMailbox(mailbox("[Gmail]/All Mail")), true);
+		assert.equal(isVirtualCopyMailbox(mailbox("[gmail]/starred")), true);
+	});
+
+	it("matches the whole path, so a folder of the user's own is real mail", () => {
+		assert.equal(isVirtualCopyMailbox(mailbox("Starred ideas")), false);
+		assert.equal(isVirtualCopyMailbox(mailbox("[Gmail]/All Mail/2024")), false);
+	});
+
+	it("reads an ordinary folder as the place mail lives", () => {
+		assert.equal(isVirtualCopyMailbox(mailbox("INBOX")), false);
+		assert.equal(isVirtualCopyMailbox(mailbox("Rubbish", ["Junk"])), false);
+	});
+});

package/src/virtual-copy.ts

@@ -0,0 +1,33 @@
+import { MailboxSpecialUse } from "@remit/domain-enums";
+import type { MailboxItem } from "./types.js";
+
+/**
+ * Special-use folders that hold a second copy of mail already reachable through
+ * the folder it actually lives in — Gmail's All Mail, Starred and Important.
+ */
+const VIRTUAL_COPY_SPECIAL_USE: readonly string[] = [
+	MailboxSpecialUse.All,
+	MailboxSpecialUse.Flagged,
+	MailboxSpecialUse.Important,
+];
+
+/**
+ * Well-known Gmail virtual paths, for servers that do not advertise the
+ * special-use attribute. Whole path, never a prefix — a user's own
+ * `Starred ideas` folder is real mail.
+ */
+const VIRTUAL_COPY_FULL_PATHS: readonly string[] = [
+	"[gmail]/all mail",
+	"[gmail]/starred",
+	"[gmail]/important",
+];
+
+/**
+ * Whether this folder holds mail that also lives in a real folder. Such a
+ * folder is a view, not a filing location: seeing a message in it says nothing
+ * about where the message was filed, so it neither picks which duplicate a
+ * listing drops nor decides where a message lives.
+ */
+export const isVirtualCopyMailbox = (mailbox: MailboxItem): boolean =>
+	mailbox.specialUse?.some((use) => VIRTUAL_COPY_SPECIAL_USE.includes(use)) ===
+		true || VIRTUAL_COPY_FULL_PATHS.includes(mailbox.fullPath.toLowerCase());