@bobfrankston/mailx-types 0.1.11 → 0.1.13

package/index.d.ts

@@ -4,6 +4,7 @@
  * This is the contract between client and server.
  */
 export { CONTACT_RULES } from "./contact-rules.js";
+export type { MailxApi } from "./mailx-api.js";
 export { expandRecipients, splitRecipients, isAddressToken, extractAddress, } from "./groups.js";
 export type { GroupMap, RecipientToken, ExpansionResult } from "./groups.js";
 /** Supported authentication methods */
@@ -64,6 +65,30 @@ export interface Folder {
     unreadCount: number;
     children: Folder[]; /** Nested subfolders */
 }
+interface FlagBearing {
+    flags: string[];
+}
+export declare const seenOf: (m: {
+    flags?: readonly string[];
+}) => boolean;
+export declare const flaggedOf: (m: {
+    flags?: readonly string[];
+}) => boolean;
+export declare const answeredOf: (m: {
+    flags?: readonly string[];
+}) => boolean;
+export declare const draftOf: (m: {
+    flags?: readonly string[];
+}) => boolean;
+export declare const deletedOf: (m: {
+    flags?: readonly string[];
+}) => boolean;
+export declare const setSeen: (m: FlagBearing, state: boolean) => void;
+export declare const setFlagged: (m: FlagBearing, state: boolean) => void;
+export declare const setAnswered: (m: FlagBearing, state: boolean) => void;
+export declare const setDraft: (m: FlagBearing, state: boolean) => void;
+export declare const toggleSeen: (m: FlagBearing) => void;
+export declare const toggleFlagged: (m: FlagBearing) => void;
 /** Email address with optional display name */
 export interface EmailAddress {
     name: string; /** Display name, may be empty */

package/index.js

@@ -12,6 +12,50 @@ export { CONTACT_RULES } from "./contact-rules.js";
 // send time. Both desktop and Android send paths consume this expander
 // against contacts.jsonc → groups.
 export { expandRecipients, splitRecipients, isAddressToken, extractAddress, } from "./groups.js";
+// ── Message flag state ──
+//
+// External API surface for the IMAP system flags. The literal strings
+// (`"\\Seen"`, `"\\Flagged"`, etc.) live ONLY inside this module — every
+// caller speaks in terms of named predicates (`seenOf(msg)`) and verbs
+// (`setSeen(msg, true)`, `toggleSeen(msg)`). That keeps a typo like
+// `"\Seen"` (single backslash) from silently bypassing flag checks
+// elsewhere, and removes the "two-API leak" of having both `FLAG.SEEN`
+// constants AND verb helpers exposed simultaneously.
+//
+// These work against any object with a mutable `flags: string[]`
+// property — `MessageEnvelope`, `Message`, and the row's `msg` reference
+// all qualify. The verbs return `void` and mutate `msg.flags` in place
+// (replacing the array with a fresh one so listeners observing
+// reference identity, e.g. message-state, still re-render). Pure
+// predicate calls (`seenOf`, `flaggedOf`) don't mutate.
+const _SEEN = "\\Seen";
+const _FLAGGED = "\\Flagged";
+const _ANSWERED = "\\Answered";
+const _DRAFT = "\\Draft";
+const _DELETED = "\\Deleted";
+function _has(msg, flag) {
+    return !!msg.flags && msg.flags.includes(flag);
+}
+function _set(msg, flag, state) {
+    const present = (msg.flags || []).includes(flag);
+    if (state === present)
+        return;
+    const next = state
+        ? [...(msg.flags || []), flag]
+        : (msg.flags || []).filter(f => f !== flag);
+    msg.flags = next;
+}
+export const seenOf = (m) => _has(m, _SEEN);
+export const flaggedOf = (m) => _has(m, _FLAGGED);
+export const answeredOf = (m) => _has(m, _ANSWERED);
+export const draftOf = (m) => _has(m, _DRAFT);
+export const deletedOf = (m) => _has(m, _DELETED);
+export const setSeen = (m, state) => _set(m, _SEEN, state);
+export const setFlagged = (m, state) => _set(m, _FLAGGED, state);
+export const setAnswered = (m, state) => _set(m, _ANSWERED, state);
+export const setDraft = (m, state) => _set(m, _DRAFT, state);
+export const toggleSeen = (m) => _set(m, _SEEN, !_has(m, _SEEN));
+export const toggleFlagged = (m) => _set(m, _FLAGGED, !_has(m, _FLAGGED));
 // ── Shared Utilities ──
 // Pure functions used by both desktop (mailx-service) and Android (web-service).
 // Kept here to avoid duplication — both platforms import from mailx-types.

package/mailx-api.d.ts

@@ -0,0 +1,212 @@
+/**
+ * MailxApi — the single typed contract that every mailx service implementation
+ * must satisfy. Both the Node-side desktop service (`MailxService`) and the
+ * browser-side Android service (`WebMailxService`) declare
+ * `implements MailxApi`. Missing methods become build errors instead of
+ * silent runtime "parent bridge has no method X" failures.
+ *
+ * **Why this exists**: until now the two implementations drifted independently.
+ * A method added to MailxService for one platform release would be silently
+ * absent on the other for months. spellcheck-on-GDrive (2026-05-13) added
+ * `getUserDict` / `addUserDictWord` / `removeUserDictWord` to the desktop
+ * service; the Android service got none of them; the relay returned
+ * `parent bridge has no method`, the client `.catch(() => {})` swallowed the
+ * rejection, and the feature silently regressed on phone. With this contract
+ * any such addition is a compile-time failure on whichever side it's missing.
+ *
+ * **Surface**: the 83 method names dispatched by
+ * `mailx-service/jsonrpc.ts` plus a handful of internal helpers both
+ * implementations need. IPC-only names (`sendMessage`, `createCalendarEvent`,
+ * etc.) are listed under their dispatch names — desktop classes that today
+ * use a different internal name (e.g., `send`, `createCalendarEventLocal`)
+ * add a thin alias method so the contract holds without renaming call sites.
+ *
+ * **Optional methods**: a handful of methods require an OS popup or native
+ * filesystem hook and have no meaningful browser equivalent
+ * (`openInWord`, `closeWordEdit`, `showReminderPopup`, `openInTextEditor`,
+ * `openLocalPath`). They are declared `?:` so the browser service can
+ * legitimately omit them. The desktop service must implement them.
+ *
+ * **Types**: signatures use `any` where the shape genuinely varies across
+ * implementations (envelope rows, settings, AI payloads). The contract's
+ * job is name + arity enforcement, not deep schema typing — that lives in
+ * the relevant domain types (`Folder`, `AccountConfig`, etc.).
+ *
+ * **Where to add a new method**: add the method here first. Both
+ * implementations will fail to compile until they implement it. Don't add
+ * methods to a service class without the interface entry — that's how we
+ * got into the silent-drift hole.
+ */
+import type { AutocompleteSettings, AutocompleteRequest, AutocompleteResponse, AiTransformRequest, AiTransformResponse } from "./index.js";
+import type { Folder } from "./index.js";
+export interface MailxApi {
+    getAccounts(): any[] | Promise<any[]>;
+    getFolders(accountId: string): Folder[] | Promise<Folder[]>;
+    getMessages(accountId: string, folderId: number, page?: number, pageSize?: number, sort?: string, sortDir?: string, search?: string, flaggedOnly?: boolean): any | Promise<any>;
+    getUnifiedInbox(page?: number, pageSize?: number): any | Promise<any>;
+    getMessage(accountId: string, uid: number, allowRemote?: boolean, folderId?: number): Promise<any>;
+    getThreadMessages(accountId: string, threadId: string): any | Promise<any>;
+    getAttachment(accountId: string, uid: number, attachmentId: number, folderId?: number): Promise<{
+        content: any;
+        contentType: string;
+        filename: string;
+    }>;
+    updateFlags(accountId: string, uid: number, flags: string[]): Promise<void>;
+    deleteMessage(accountId: string, uid: number): Promise<void>;
+    deleteMessages(accountId: string, uids: number[]): Promise<void>;
+    undeleteMessage(accountId: string, uid: number, folderId: number): Promise<void>;
+    moveMessage(accountId: string, uid: number, targetFolderId: number, targetAccountId?: string): Promise<void>;
+    moveMessages(accountId: string, uids: number[], targetFolderId: number): Promise<void>;
+    markAsSpamMessages(accountId: string, uids: number[]): Promise<{
+        targetFolderId: number;
+        moved: number;
+    }>;
+    recordSpamReport(accountId: string, uid: number, folderId: number): Promise<any>;
+    markFolderRead(folderId: number): void | Promise<void>;
+    createFolder(accountId: string, parentPath: string, name: string): Promise<void>;
+    renameFolder(accountId: string, folderId: number, newName: string): Promise<void>;
+    deleteFolder(accountId: string, folderId: number): Promise<void>;
+    moveFolderToTrash(accountId: string, folderId: number): Promise<void>;
+    emptyFolder(accountId: string, folderId: number): Promise<void>;
+    sendMessage(msg: any): Promise<void>;
+    saveDraft(accountId: string, subject: string, bodyHtml: string, bodyText: string, to?: string, cc?: string, previousDraftUid?: number, draftId?: string): Promise<{
+        draftUid: number | null;
+        draftId: string;
+    }>;
+    deleteDraft(accountId: string, draftUid: number, draftId?: string): Promise<void>;
+    getOutboxStatus(): any | Promise<any>;
+    listQueuedOutgoing(): any[] | Promise<any[]>;
+    cancelQueuedOutgoing(filePath: string): {
+        ok: true;
+    } | Promise<{
+        ok: true;
+    }>;
+    syncAll(): Promise<void>;
+    syncAccount(accountId: string): Promise<void>;
+    getSyncPending(): {
+        pending: number;
+    } | Promise<{
+        pending: number;
+    }>;
+    drainStoreSync(): Promise<void>;
+    reauthenticate(accountId: string): Promise<boolean>;
+    reauthGoogleScopes(): {
+        cleared: number;
+    } | Promise<{
+        cleared: number;
+    }>;
+    searchMessages(query: string, page?: number, pageSize?: number, scope?: string, accountId?: string, folderId?: number, includeTrashSpam?: boolean): Promise<any>;
+    searchContacts(query: string): any[] | Promise<any[]>;
+    hasCcHistoryTo(email: string): boolean | Promise<boolean>;
+    hasBccHistoryTo(email: string): boolean | Promise<boolean>;
+    addContact(name: string, email: string): boolean | Promise<boolean>;
+    listContacts(query: string, page?: number, pageSize?: number): any | Promise<any>;
+    upsertContact(name: string, email: string): {
+        ok: true;
+    } | Promise<{
+        ok: true;
+    }>;
+    deleteContact(email: string): {
+        ok: true;
+    } | Promise<{
+        ok: true;
+    }>;
+    addPreferredContact(entry: {
+        name: string;
+        email: string;
+        source?: string;
+        organization?: string;
+    }): Promise<void>;
+    addToDenylist(email: string): Promise<void>;
+    loadContactsConfig(): Promise<any>;
+    getPriorityLists(): {
+        senders: string[];
+        domains: string[];
+    } | Promise<{
+        senders: string[];
+        domains: string[];
+    }>;
+    setPrioritySender(email: string, value: boolean, name?: string): Promise<void>;
+    setPriorityDomain(domain: string, value: boolean): Promise<void>;
+    flagSenderOrDomain(type: "sender" | "domain", value: string): Promise<{
+        flagged: boolean;
+    }>;
+    allowRemoteContent(type: "sender" | "domain" | "recipient", value: string): Promise<void>;
+    getCalendarEvents(fromMs: number, toMs: number): Promise<any[]>;
+    createCalendarEvent(ev: any): Promise<{
+        uuid: string;
+    }>;
+    updateCalendarEvent(uuid: string, patch: any): Promise<{
+        ok: true;
+    }>;
+    deleteCalendarEvent(uuid: string): Promise<{
+        ok: true;
+    }>;
+    getTasks(includeCompleted?: boolean): Promise<any[]>;
+    createTask(t: {
+        title: string;
+        notes?: string;
+        dueMs?: number;
+    }): Promise<{
+        uuid: string;
+    }>;
+    updateTask(uuid: string, patch: any): Promise<{
+        ok: true;
+    }>;
+    deleteTask(uuid: string): Promise<{
+        ok: true;
+    }>;
+    getUserDict(): Promise<string[]>;
+    addUserDictWord(word: string): Promise<string[]>;
+    removeUserDictWord(word: string): Promise<string[]>;
+    getSettings(): any | Promise<any>;
+    saveSettingsData(settings: any): Promise<void>;
+    getDiagnostics(): any | Promise<any>;
+    getPrimaryAccount(feature?: string): any | Promise<any>;
+    setupAccount(name: string, email: string, password?: string): Promise<{
+        ok: boolean;
+        error?: string;
+        message?: string;
+    }>;
+    repairAccounts(): Promise<{
+        ok: boolean;
+        error?: string;
+        message?: string;
+    }>;
+    getAutocompleteSettings(): AutocompleteSettings | Promise<AutocompleteSettings>;
+    saveAutocompleteSettings(settings: AutocompleteSettings): void | Promise<void>;
+    autocomplete(req: AutocompleteRequest): Promise<AutocompleteResponse>;
+    aiTransform(req: AiTransformRequest): Promise<AiTransformResponse>;
+    readJsoncFile(name: string): Promise<string | null>;
+    writeJsoncFile(name: string, content: string): Promise<void>;
+    formatJsonc(content: string): Promise<string>;
+    readConfigHelp(name: string): Promise<string>;
+    unsubscribeOneClick(url: string): Promise<{
+        ok: boolean;
+        status: number;
+        statusText: string;
+    }>;
+    consumePendingMailto(): any | Promise<any>;
+    logClientEvent?(...args: any[]): void | Promise<void>;
+    getVersion?(): any | Promise<any>;
+    openInWord?(editId: string, html: string): Promise<{
+        ok: boolean;
+        path: string;
+        opener: string;
+    }>;
+    closeWordEdit?(editId: string): Promise<void>;
+    showReminderPopup?(opts: any): Promise<{
+        button: string;
+        form?: any;
+    }>;
+    openInTextEditor?(filePath: string): Promise<{
+        ok: boolean;
+        opener: string;
+        reason?: string;
+    }>;
+    openLocalPath?(which: "config" | "log"): Promise<{
+        ok: true;
+        path: string;
+    }>;
+}
+//# sourceMappingURL=mailx-api.d.ts.map

package/mailx-api.js

@@ -0,0 +1,41 @@
+/**
+ * MailxApi — the single typed contract that every mailx service implementation
+ * must satisfy. Both the Node-side desktop service (`MailxService`) and the
+ * browser-side Android service (`WebMailxService`) declare
+ * `implements MailxApi`. Missing methods become build errors instead of
+ * silent runtime "parent bridge has no method X" failures.
+ *
+ * **Why this exists**: until now the two implementations drifted independently.
+ * A method added to MailxService for one platform release would be silently
+ * absent on the other for months. spellcheck-on-GDrive (2026-05-13) added
+ * `getUserDict` / `addUserDictWord` / `removeUserDictWord` to the desktop
+ * service; the Android service got none of them; the relay returned
+ * `parent bridge has no method`, the client `.catch(() => {})` swallowed the
+ * rejection, and the feature silently regressed on phone. With this contract
+ * any such addition is a compile-time failure on whichever side it's missing.
+ *
+ * **Surface**: the 83 method names dispatched by
+ * `mailx-service/jsonrpc.ts` plus a handful of internal helpers both
+ * implementations need. IPC-only names (`sendMessage`, `createCalendarEvent`,
+ * etc.) are listed under their dispatch names — desktop classes that today
+ * use a different internal name (e.g., `send`, `createCalendarEventLocal`)
+ * add a thin alias method so the contract holds without renaming call sites.
+ *
+ * **Optional methods**: a handful of methods require an OS popup or native
+ * filesystem hook and have no meaningful browser equivalent
+ * (`openInWord`, `closeWordEdit`, `showReminderPopup`, `openInTextEditor`,
+ * `openLocalPath`). They are declared `?:` so the browser service can
+ * legitimately omit them. The desktop service must implement them.
+ *
+ * **Types**: signatures use `any` where the shape genuinely varies across
+ * implementations (envelope rows, settings, AI payloads). The contract's
+ * job is name + arity enforcement, not deep schema typing — that lives in
+ * the relevant domain types (`Folder`, `AccountConfig`, etc.).
+ *
+ * **Where to add a new method**: add the method here first. Both
+ * implementations will fail to compile until they implement it. Don't add
+ * methods to a service class without the interface entry — that's how we
+ * got into the silent-drift hole.
+ */
+export {};
+//# sourceMappingURL=mailx-api.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/mailx-types",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "type": "module",
   "main": "index.js",
   "types": "index.d.ts",