@remit/data-ports 0.0.36 → 0.0.38

package/package.json

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

package/src/errors.ts

@@ -1,5 +1,29 @@
+import type { CanonicalMailboxRoleValue } from "./folder-role.js";
+
+/**
+ * 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 const isPublicApiError = (value: unknown): value is PublicApiError => {
+	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 {
 	public statusCode = 500;
+	publicApiError?: PublicApiError;
 }
 
 export class BadRequestError extends HTTPError {
@@ -27,6 +51,40 @@ export class ConflictError extends HTTPError {
 	public statusCode = 409;
 }
 
+/**
+ * Why a canonical role names no folder this 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";
+
+/**
+ * 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: string,
+		role: CanonicalMailboxRoleValue,
+		reason: FolderRoleUnresolvedReason,
+		accountId: string,
+	) {
+		super(message);
+		this.publicApiError = {
+			code: "folder_role_unresolved",
+			details: { role, reason, accountId },
+		};
+	}
+}
+
 /**
  * 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

package/src/id.ts

@@ -7,13 +7,6 @@ const translator = shortUuid.createTranslator(shortUuid.constants.uuid25Base36);
 
 export const base36uuid = (): string => translator.generate();
 
-export const fromUUID = (uuid: string): string => translator.fromUUID(uuid);
-
-export const toUUID = (shortId: string): string => translator.toUUID(shortId);
-
-export const generateUuidv5 = (name: string, namespace: string): string =>
-	uuidv5(name, namespace);
-
 export const base36uuidv5 = (name: string, namespace: string): string =>
 	translator.fromUUID(uuidv5(name, namespace));
 
@@ -118,16 +111,6 @@ export const ROOT_PART_PATH = "0";
 export const deriveBodyPartId = (messageId: string, partPath: string): string =>
 	base36uuidv5(`bodypart:${messageId}:${partPath}`, REMIT_NAMESPACE);
 
-export const deriveBodyPartParameterId = (
-	messageId: string,
-	partPath: string,
-	parameterName: string,
-): string =>
-	base36uuidv5(
-		`bodypartparam:${messageId}:${partPath}:${parameterName.toLowerCase()}`,
-		REMIT_NAMESPACE,
-	);
-
 /**
  * Identity of a quarantined message (issue #72). Derived rather than generated
  * so re-quarantining the same message rewrites its own row: the sync path can

package/src/mailbox-role.ts

@@ -1,5 +1,5 @@
 import { CanonicalMailboxRole } from "@remit/domain-enums";
-import { ROLE_NAME_HINTS, resolveMailboxForRole } from "./folder-role.js";
+import { ROLE_NAME_HINTS } from "./folder-role.js";
 
 /**
  * The conventional names for a role, taken from the one table every
@@ -12,34 +12,3 @@ export const JUNK_FOLDER_NAMES: readonly string[] =
 
 export const TRASH_FOLDER_NAMES: readonly string[] =
 	ROLE_NAME_HINTS[CanonicalMailboxRole.Trash] ?? [];
-
-export interface MailboxRole {
-	readonly fullPath: string;
-	readonly hierarchyDelimiter?: string;
-	readonly specialUse?: readonly string[];
-}
-
-/**
- * Whether one mailbox, considered alone, carries a role: its SPECIAL-USE flag
- * or its conventional name. A single mailbox carries no account context, so
- * this cannot see the user's appointment — a caller holding an accountId asks
- * `IMailboxSpecialUseRepository` instead, which does.
- */
-const carriesRole = (
-	mailbox: MailboxRole,
-	role: (typeof CanonicalMailboxRole)[keyof typeof CanonicalMailboxRole],
-): boolean =>
-	resolveMailboxForRole(role, [
-		{
-			mailboxId: "",
-			fullPath: mailbox.fullPath,
-			hierarchyDelimiter: mailbox.hierarchyDelimiter ?? "",
-			specialUse: mailbox.specialUse,
-		},
-	]) !== null;
-
-export const isJunkMailbox = (mailbox: MailboxRole): boolean =>
-	carriesRole(mailbox, CanonicalMailboxRole.Junk);
-
-export const isTrashMailbox = (mailbox: MailboxRole): boolean =>
-	carriesRole(mailbox, CanonicalMailboxRole.Trash);