@remit/data-ports 0.0.27 → 0.0.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/data-ports",
-  "version": "0.0.27",
+  "version": "0.0.29",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/conformance/index.ts

@@ -1,2 +1,3 @@
 export type { RepositoryConformanceHarness } from "./harness.js";
 export { labelRepositoryConformance } from "./label.js";
+export { senderSignerStandingRepositoryConformance } from "./sender-signer-standing.js";

package/src/conformance/sender-signer-standing.ts

@@ -0,0 +1,117 @@
+import assert from "node:assert/strict";
+import { after, before, describe, test } from "node:test";
+import type { ISenderSignerStandingRepository } from "../interfaces/sender-signer-standing.js";
+import type { RepositoryConformanceHarness } from "./harness.js";
+
+export function senderSignerStandingRepositoryConformance(
+	harness: RepositoryConformanceHarness<ISenderSignerStandingRepository>,
+): void {
+	describe("ISenderSignerStandingRepository conformance", () => {
+		let repo: ISenderSignerStandingRepository;
+
+		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/src/index.ts

@@ -26,6 +26,7 @@ export type {
 export { holdsRoom } from "./interfaces/outbox-attachment.js";
 export type { IOutboxMessageRepository } from "./interfaces/outbox-message.js";
 export type { IQuarantineRepository } from "./interfaces/quarantine.js";
+export type { ISenderSignerStandingRepository } from "./interfaces/sender-signer-standing.js";
 export type { IThreadMessageRepository } from "./interfaces/thread-message.js";
 export type {
 	IUnitOfWork,
@@ -85,6 +86,7 @@ export type {
 	MessageLabelItem,
 	MessagePlacementMoveItem,
 	MessageReferenceItem,
+	ObserveSenderSignerStandingInput,
 	OrganizeJobRequestItem,
 	OutboxAttachmentItem,
 	OutboxMessageItem,
@@ -96,6 +98,7 @@ export type {
 	RawMessageStorageItem,
 	ResultList,
 	SearchOptions,
+	SenderSignerStandingItem,
 	ThreadMessageItem,
 	UpdateAccountConfigInput,
 	UpdateAccountExportRequestInput,

package/src/interfaces/address.ts

@@ -61,14 +61,23 @@ export interface IAddressRepository {
 		accountConfigId: string;
 		limit?: number;
 	}): Promise<AddressItem[]>;
+	/**
+	 * The account's addresses, most worth suggesting first: where the search term
+	 * hit — the start of a value before the middle of one, and the display name
+	 * before the local part, the domain and the whole address — then the account's
+	 * standing for the sender, how much it corresponds with it, how recently, and
+	 * the stored compound and id last so the order is total. Without a term every
+	 * row scores the same match, so the remaining keys decide and the listing comes
+	 * back by standing, correspondence and recency rather than alphabetically.
+	 */
 	listByAccountConfig(input: {
 		accountConfigId: string;
 		/**
-		 * Prefix term matched against both the display-name compound
-		 * (`"<display name> <email>"`) and the normalized email. Matching the
-		 * email separately is what makes an exact-address lookup resolve: the
-		 * compound leads with the display name, so an email prefix never
-		 * matches it.
+		 * Matched as a substring of the display name, the local part, the domain
+		 * and the whole address, so `po`, `locatie`, `amsterdam`, `pocahondas.nl`
+		 * and `amsterdam@pocahondas.nl` all resolve
+		 * `Pocahondas locatie amsterdam <amsterdam@pocahondas.nl>`. A name outside
+		 * ASCII (`Öz` for `Özcan Bakker`) resolves through the folded compound.
 		 */
 		search?: string;
 		cursor?: string;

package/src/interfaces/sender-signer-standing.ts

@@ -0,0 +1,37 @@
+import type {
+	ObserveSenderSignerStandingInput,
+	SenderSignerStandingItem,
+} from "../types.js";
+
+/**
+ * Per-account record of how often one sender has been seen arriving under one
+ * DKIM signing identity.
+ *
+ * The authenticity derivation asks this port two things: whether a key already
+ * had standing when a message arrived, and — afterwards — that this message be
+ * counted. `get` answers the first and must not create anything; `observe`
+ * answers the second and is the only writer.
+ */
+export interface ISenderSignerStandingRepository {
+	/**
+	 * Record one observation of a key, creating the row at `messageCount = 1`
+	 * or incrementing an existing one.
+	 *
+	 * `firstSeenAt` is set once, on creation, and never moves — an
+	 * implementation that rewrites it on the increment path erases the age the
+	 * derivation reads standing from. `lastSeenAt` advances on every call.
+	 */
+	observe(
+		input: ObserveSenderSignerStandingInput,
+	): Promise<SenderSignerStandingItem>;
+
+	/**
+	 * The standing of one key. Throws the adapter's not-found error when the
+	 * key has never been observed, and creates nothing.
+	 */
+	get(
+		accountConfigId: string,
+		senderKey: string,
+		signerDomain: string,
+	): Promise<SenderSignerStandingItem>;
+}

package/src/types.ts

@@ -25,6 +25,7 @@ import type {
 	OutboxMessageSchema,
 	QuarantineSchema,
 	RawMessageStorageSchema,
+	SenderSignerStandingSchema,
 	ThreadMessageSchema,
 } from "@remit/api-zod-schemas";
 import type { z } from "zod";
@@ -360,6 +361,7 @@ export type CreateMessageInput = Omit<
 	| "status"
 	| "syncStatus"
 	| "category"
+	| "authenticityVerdict"
 	| "hasListUnsubscribe"
 	| "movedByRemit"
 > & {
@@ -367,6 +369,7 @@ export type CreateMessageInput = Omit<
 	status?: MessageItem["status"];
 	syncStatus?: MessageItem["syncStatus"];
 	category?: MessageItem["category"];
+	authenticityVerdict?: MessageItem["authenticityVerdict"];
 	hasListUnsubscribe?: MessageItem["hasListUnsubscribe"];
 	movedByRemit?: MessageItem["movedByRemit"];
 };
@@ -527,3 +530,21 @@ export type CreateFilterAnchorInput = Omit<
 	FilterAnchorItem,
 	"createdAt" | "updatedAt"
 >;
+
+export type SenderSignerStandingItem = z.infer<
+	typeof SenderSignerStandingSchema
+>;
+
+/**
+ * One message observed arriving for a `(senderKey, signerDomain)` pair.
+ *
+ * `observedAt` is supplied rather than taken from the clock so a caller
+ * replaying a body-sync batch records the arrival's own time, and so the
+ * `firstSeenAt`-immutability contract is assertable without sleeping.
+ */
+export type ObserveSenderSignerStandingInput = {
+	accountConfigId: string;
+	senderKey: string;
+	signerDomain: string;
+	observedAt: number;
+};