@bobfrankston/mailx-types 0.1.2 → 0.1.5

package/index.d.ts

@@ -8,7 +8,8 @@ export type AuthMethod = "password" | "oauth2";
 /** Mail account configuration */
 export interface AccountConfig {
     id: string; /** Unique account identifier (e.g., "iecc", "gmail-bob") */
-    name: string; /** Display name */
+    name: string; /** Sender name for From header (e.g., "Bob Frankston") */
+    label?: string; /** UI label for account list (e.g., "Gmail"). Falls back to name if not set */
     email: string; /** Email address */
     imap: {
         host: string;
@@ -28,6 +29,24 @@ export interface AccountConfig {
         password?: string;
     };
     enabled: boolean;
+    primary?: boolean; /** Catch-all "this is my main account" — default source for Calendar / Tasks / Contacts when no per-feature override set. */
+    primaryCalendar?: boolean; /** Per-feature override: use this account's Google Calendar. Falls back to `primary` if unset. */
+    primaryTasks?: boolean; /** Per-feature override: use this account's Google Tasks. Falls back to `primary` if unset. */
+    primaryContacts?: boolean; /** Per-feature override: use this account's Google Contacts. Falls back to `primary` if unset. */
+    defaultSend?: boolean; /** Use this account's SMTP when From doesn't match any account */
+    syncContacts?: boolean; /** Sync contacts even when account is disabled (contacts-only Gmail) */
+    relayDomains?: string[]; /** Domains to skip in Delivered-To chain (e.g., ["m.connectivity.xyz"]) */
+    deliveredToPrefix?: string[]; /** Prefixes to strip from Delivered-To to get clean alias (e.g., ["bobf-ma-", "bobf-"]) — order matters, longest first */
+    identityDomains?: string[]; /** Domains where Delivered-To address should become the reply From (e.g., ["bob.ma", "bobf.frankston.com"]) */
+    spam?: string; /** IMAP folder path for "Mark as spam" button (e.g., "_spam"). Button hidden when not set. */
+    signature?: string; /** Legacy: HTML signature appended to all outgoing messages (new + reply + forward). Plain text or HTML allowed. Superseded by `sig`. */
+    sig?: AccountSignature; /** Per-account signature object. Initially appended only to NEW messages; later options will cover replies/forwards. */
+}
+/** Signature configuration in accounts.jsonc. Initial shape carries `text`
+ *  only; `html: true` reserved for future support of raw HTML signatures. */
+export interface AccountSignature {
+    text: string; /** Plain-text signature body. Newlines preserved. Appended to NEW messages with the standard "-- " RFC 3676 separator. */
+    html?: boolean; /** Future flag: when true, `text` is treated as raw HTML rather than escaped plain text. Currently ignored. */
 }
 /** Standard IMAP special-use folder types */
 export type SpecialUse = "inbox" | "sent" | "drafts" | "trash" | "junk" | "archive" | "all";
@@ -53,10 +72,13 @@ export interface MessageEnvelope {
     id: number; /** Local store ID */
     accountId: string;
     folderId: number;
-    uid: number; /** IMAP UID */
+    folderName?: string; /** Leaf folder name; populated by cross-folder search so the UI can tag each hit */
+    uid: number; /** IMAP UID (server-side identity; changes on move, UIDVALIDITY bump) */
+    uuid?: string; /** Stable local identity, minted once at first-sight; never changes */
     messageId: string; /** RFC Message-ID header */
     inReplyTo: string; /** For threading */
     references: string[]; /** For threading */
+    threadId?: string; /** Computed thread id (root Message-ID of the conversation) */
     date: number; /** Epoch ms */
     subject: string;
     from: EmailAddress;
@@ -66,6 +88,9 @@ export interface MessageEnvelope {
     size: number;
     hasAttachments: boolean;
     preview: string; /** First ~200 chars of body text */
+    bodyPath?: string; /** Local body location: "idb:..." or "gmail:<id>" */
+    providerId?: string; /** Native server id (Gmail hex id, Outlook Graph id) — bypasses UID→id pagination on body fetch */
+    pending?: boolean; /** True when a queued local action (move/flag/delete) hasn't been ACK'd by the server yet — UI renders pink */
 }
 /** Full message with body content */
 export interface Message extends MessageEnvelope {
@@ -97,6 +122,10 @@ export interface MessageQuery {
     sort?: "date" | "from" | "subject";
     sortDir?: "asc" | "desc";
     search?: string;
+    /** Restrict to messages with the \Flagged flag set (whole-folder, not
+     *  just the currently-rendered page — lets the "show flagged" filter
+     *  find stars on messages that haven't been paged in yet). */
+    flaggedOnly?: boolean;
 }
 /** Compose/send a message */
 export interface ComposeMessage {
@@ -150,6 +179,13 @@ export type WsEvent = {
         total: number;
         unread: number;
     }>;
+} | {
+    type: "folderSynced";
+    accountId: string;
+    entries: {
+        folderId: number;
+        syncedAt: number;
+    }[];
 } | {
     type: "syncProgress";
     accountId: string;
@@ -167,11 +203,18 @@ export type WsEvent = {
 } | {
     type: "error";
     message: string;
+} | {
+    type: "accountError";
+    accountId: string;
+    error: string;
+    hint: string;
+    isOAuth: boolean;
 };
 export interface MailxSettings {
     accounts: AccountConfig[];
     ui: {
-        theme: "dark" | "light";
+        theme: "system" | "dark" | "light";
+        editor: "quill" | "tiptap";
         folderWidth: number;
         listViewerSplit: number; /** Percentage for message list height */
         fontSize: number;
@@ -179,11 +222,53 @@ export interface MailxSettings {
     sync: {
         intervalMinutes: number;
         historyDays: number; /** 0 = all history */
+        prefetch: boolean; /** Download message bodies during sync (default true) */
     };
     store: {
         basePath: string; /** Where message bodies are stored */
         compressionBoundaryDays: number; /** Messages older than this get compressed */
     };
+    autocomplete?: AutocompleteSettings;
+}
+export interface AutocompleteSettings {
+    enabled: boolean;
+    provider: "ollama" | "claude" | "openai" | "off";
+    ollamaUrl: string;
+    ollamaModel: string;
+    cloudApiKey: string;
+    cloudModel: string;
+    debounceMs: number;
+    maxTokens: number;
+    /** Per-feature opt-in for non-autocomplete AI helpers. All default false
+     *  per user preference (2026-04-21): AI features should be controlled by
+     *  a flag, initially OFF in settings. Provider config is shared with
+     *  autocomplete (provider, cloudApiKey, cloudModel, etc.). */
+    translateEnabled?: boolean;
+    proofreadEnabled?: boolean;
+}
+export interface AutocompleteRequest {
+    subject: string;
+    to: string;
+    bodyText: string;
+    cursorOffset: number;
+}
+export interface AutocompleteResponse {
+    suggestion: string;
+}
+export interface AiTransformRequest {
+    /** translate = render in `targetLang`; proofread = corrected version
+     *  with grammar/spelling fixes; summarize = short paragraph summary. */
+    action: "translate" | "proofread" | "summarize";
+    text: string;
+    /** ISO-639-1 (or BCP-47) language code for translate. Defaults to "en". */
+    targetLang?: string;
+}
+export interface AiTransformResponse {
+    /** Transformed text. Empty when AI is disabled / provider error / feature
+     *  not enabled — caller should treat empty as "no result". */
+    text: string;
+    /** Optional reason for empty result, surfaced to UI status bar. */
+    reason?: string;
 }
 /** Body storage backend interface -- implementations are swappable */
 export interface MessageStore {
@@ -192,4 +277,43 @@ export interface MessageStore {
     deleteMessage(accountId: string, folderId: number, uid: number): Promise<void>;
     hasMessage(accountId: string, folderId: number, uid: number): Promise<boolean>;
 }
+/** Sanitize HTML for safe display — strips scripts, inline handlers, remote images, forms, iframes. */
+export declare function sanitizeHtml(html: string): {
+    html: string;
+    hasRemoteContent: boolean;
+};
+/** Encode text as RFC 2045 quoted-printable. */
+export declare function encodeQuotedPrintable(text: string): string;
+/** Render an HTML document as a plain-text approximation suitable for the
+ *  text/plain alternative part of a multipart/alternative outgoing MIME
+ *  message. Not a full HTML-to-text engine — just enough to give non-HTML
+ *  clients (plain-text readers, spam filters scoring on text/plain, people
+ *  who turned HTML off) a readable fallback. Preserves line breaks for
+ *  `<br>` / `</p>` / `</div>` / `<li>`, strips all other tags, decodes the
+ *  common HTML entities, and collapses runs of whitespace.
+ *
+ *  Spam filters (SpamAssassin, Rspamd) penalise HTML-only mail aggressively;
+ *  shipping a real text part typically drops the score by 1–2 points. Also
+ *  matches the behaviour of every other mainstream mail client — sending a
+ *  text/html part alone marks mailx as an outlier in mail logs. */
+export declare function htmlToPlainText(html: string): string;
+/** Parse search query into structured conditions.
+ *  Supports qualifiers: from:, to:, subject:, date:, has:attachment,
+ *  is:flagged, is:unread, is:read. Unqualified terms search across subject /
+ *  from / preview. Returns { conditions, params } for SQL WHERE clause with
+ *  LIKE plus structured predicates (flags_json LIKE, has_attachments=1, date
+ *  range comparisons).
+ *
+ *  Date syntax (matches Gmail-ish conventions):
+ *    - date:2026-04-22         exact day
+ *    - date:2026-04            month
+ *    - date:>2026-04-01        after
+ *    - date:<2026-04-01        before
+ *    - date:2026-04-01..2026-04-30   range
+ *    - date:today / yesterday / last7 / last30
+ */
+export declare function parseSearchQuery(query: string): {
+    conditions: string[];
+    params: (string | number)[];
+};
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -3,5 +3,241 @@
  * Shared type definitions for the mailx email client.
  * This is the contract between client and server.
  */
-export {};
+// ── 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.
+/** Sanitize HTML for safe display — strips scripts, inline handlers, remote images, forms, iframes. */
+export function sanitizeHtml(html) {
+    let hasRemoteContent = false;
+    let clean = html.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, "");
+    clean = clean.replace(/\s+on\w+\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)/gi, "");
+    clean = clean.replace(/<img\b([^>]*)\bsrc\s*=\s*("[^"]*"|'[^']*')/gi, (match, before, src) => {
+        const url = src.slice(1, -1);
+        if (url.startsWith("data:") || url.startsWith("cid:"))
+            return match;
+        hasRemoteContent = true;
+        return `<img${before}src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='20' height='20'%3E%3Crect fill='%23888' width='20' height='20' rx='3'/%3E%3Ctext x='10' y='14' text-anchor='middle' fill='white' font-size='12'%3E⊘%3C/text%3E%3C/svg%3E" data-blocked-src=${src} title="Remote image blocked"`;
+    });
+    clean = clean.replace(/<link\b[^>]*rel\s*=\s*["']stylesheet["'][^>]*>/gi, (match) => {
+        hasRemoteContent = true;
+        return `<!-- blocked: ${match.replace(/--/g, "")} -->`;
+    });
+    clean = clean.replace(/url\s*\(\s*(['"]?)(https?:\/\/[^)]+)\1\s*\)/gi, (_match, _q, url) => {
+        hasRemoteContent = true;
+        return `url("") /* blocked: ${url} */`;
+    });
+    clean = clean.replace(/<\/?form\b[^>]*>/gi, "");
+    clean = clean.replace(/<iframe\b[^>]*>[\s\S]*?<\/iframe>/gi, "");
+    return { html: clean, hasRemoteContent };
+}
+/** Encode text as RFC 2045 quoted-printable. */
+export function encodeQuotedPrintable(text) {
+    const encoder = new TextEncoder();
+    const bytes = encoder.encode(text);
+    let line = "";
+    let result = "";
+    for (let i = 0; i < bytes.length; i++) {
+        const b = bytes[i];
+        let encoded;
+        if (b === 0x0D && bytes[i + 1] === 0x0A) {
+            result += line + "\r\n";
+            line = "";
+            i++;
+            continue;
+        }
+        else if (b === 0x0A) {
+            result += line + "\r\n";
+            line = "";
+            continue;
+        }
+        else if ((b >= 33 && b <= 126 && b !== 61) || b === 9 || b === 32) {
+            encoded = String.fromCharCode(b);
+        }
+        else {
+            encoded = "=" + b.toString(16).toUpperCase().padStart(2, "0");
+        }
+        if (line.length + encoded.length > 75) {
+            result += line + "=\r\n";
+            line = "";
+        }
+        line += encoded;
+    }
+    result += line;
+    return result;
+}
+/** Render an HTML document as a plain-text approximation suitable for the
+ *  text/plain alternative part of a multipart/alternative outgoing MIME
+ *  message. Not a full HTML-to-text engine — just enough to give non-HTML
+ *  clients (plain-text readers, spam filters scoring on text/plain, people
+ *  who turned HTML off) a readable fallback. Preserves line breaks for
+ *  `<br>` / `</p>` / `</div>` / `<li>`, strips all other tags, decodes the
+ *  common HTML entities, and collapses runs of whitespace.
+ *
+ *  Spam filters (SpamAssassin, Rspamd) penalise HTML-only mail aggressively;
+ *  shipping a real text part typically drops the score by 1–2 points. Also
+ *  matches the behaviour of every other mainstream mail client — sending a
+ *  text/html part alone marks mailx as an outlier in mail logs. */
+export function htmlToPlainText(html) {
+    if (!html)
+        return "";
+    let s = html;
+    // Drop <style> / <script> entirely (their contents aren't readable text).
+    s = s.replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, "");
+    s = s.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, "");
+    // Block-level breaks — treat closing tags as line terminators so
+    // paragraphs don't run together.
+    s = s.replace(/<br\s*\/?\s*>/gi, "\n");
+    s = s.replace(/<\/(p|div|li|tr|h[1-6]|blockquote|pre|section|article)\s*>/gi, "\n");
+    // List-item leading bullet (rough but readable).
+    s = s.replace(/<li\b[^>]*>/gi, "  • ");
+    // Anchor: keep href in parens after the text so URLs survive.
+    s = s.replace(/<a\b[^>]*href\s*=\s*(['"])([^'"]*)\1[^>]*>([\s\S]*?)<\/a>/gi, (_m, _q, href, text) => {
+        const t = text.replace(/<[^>]+>/g, "").trim();
+        return t && t !== href ? `${t} (${href})` : href;
+    });
+    // Strip remaining tags.
+    s = s.replace(/<[^>]+>/g, "");
+    // Decode a pragmatic set of HTML entities — the rare ones survive as-is.
+    s = s.replace(/&nbsp;/gi, " ")
+        .replace(/&amp;/gi, "&")
+        .replace(/&lt;/gi, "<")
+        .replace(/&gt;/gi, ">")
+        .replace(/&quot;/gi, "\"")
+        .replace(/&#39;/gi, "'")
+        .replace(/&apos;/gi, "'")
+        .replace(/&mdash;/gi, "—")
+        .replace(/&ndash;/gi, "–")
+        .replace(/&hellip;/gi, "…")
+        .replace(/&#(\d+);/g, (_m, n) => String.fromCodePoint(parseInt(n, 10)))
+        .replace(/&#x([0-9a-f]+);/gi, (_m, h) => String.fromCodePoint(parseInt(h, 16)));
+    // Normalise whitespace: collapse runs of spaces/tabs, trim per-line,
+    // cap consecutive blank lines at 2.
+    s = s.replace(/[ \t]+/g, " ")
+        .split("\n").map(l => l.replace(/^[ \t]+|[ \t]+$/g, "")).join("\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+    return s;
+}
+/** Parse search query into structured conditions.
+ *  Supports qualifiers: from:, to:, subject:, date:, has:attachment,
+ *  is:flagged, is:unread, is:read. Unqualified terms search across subject /
+ *  from / preview. Returns { conditions, params } for SQL WHERE clause with
+ *  LIKE plus structured predicates (flags_json LIKE, has_attachments=1, date
+ *  range comparisons).
+ *
+ *  Date syntax (matches Gmail-ish conventions):
+ *    - date:2026-04-22         exact day
+ *    - date:2026-04            month
+ *    - date:>2026-04-01        after
+ *    - date:<2026-04-01        before
+ *    - date:2026-04-01..2026-04-30   range
+ *    - date:today / yesterday / last7 / last30
+ */
+export function parseSearchQuery(query) {
+    const parts = query.match(/(?:[^\s"]+|"[^"]*")+/g) || [];
+    const conditions = [];
+    const params = [];
+    const dayStart = (y, m, d) => new Date(y, m - 1, d).getTime();
+    const parseDateSpec = (spec) => {
+        const now = new Date();
+        const today0 = new Date(now.getFullYear(), now.getMonth(), now.getDate()).getTime();
+        if (spec === "today")
+            return { from: today0, to: today0 + 86400_000 };
+        if (spec === "yesterday")
+            return { from: today0 - 86400_000, to: today0 };
+        const lastN = spec.match(/^last(\d+)$/i);
+        if (lastN)
+            return { from: today0 - parseInt(lastN[1]) * 86400_000 };
+        const rangeMatch = spec.match(/^(\d{4})-(\d{2})-(\d{2})\.\.(\d{4})-(\d{2})-(\d{2})$/);
+        if (rangeMatch)
+            return {
+                from: dayStart(+rangeMatch[1], +rangeMatch[2], +rangeMatch[3]),
+                to: dayStart(+rangeMatch[4], +rangeMatch[5], +rangeMatch[6]) + 86400_000,
+            };
+        const gtMatch = spec.match(/^>(\d{4})-(\d{2})-(\d{2})$/);
+        if (gtMatch)
+            return { from: dayStart(+gtMatch[1], +gtMatch[2], +gtMatch[3]) + 86400_000 };
+        const ltMatch = spec.match(/^<(\d{4})-(\d{2})-(\d{2})$/);
+        if (ltMatch)
+            return { to: dayStart(+ltMatch[1], +ltMatch[2], +ltMatch[3]) };
+        const monthMatch = spec.match(/^(\d{4})-(\d{2})$/);
+        if (monthMatch) {
+            const y = +monthMatch[1], m = +monthMatch[2];
+            const from = dayStart(y, m, 1);
+            const to = m === 12 ? dayStart(y + 1, 1, 1) : dayStart(y, m + 1, 1);
+            return { from, to };
+        }
+        const dayMatch = spec.match(/^(\d{4})-(\d{2})-(\d{2})$/);
+        if (dayMatch) {
+            const from = dayStart(+dayMatch[1], +dayMatch[2], +dayMatch[3]);
+            return { from, to: from + 86400_000 };
+        }
+        return null;
+    };
+    for (const part of parts) {
+        const fromMatch = part.match(/^from:(.+)$/i);
+        const toMatch = part.match(/^to:(.+)$/i);
+        const subjectMatch = part.match(/^subject:(.+)$/i);
+        const hasMatch = part.match(/^has:(.+)$/i);
+        const isMatch = part.match(/^is:(.+)$/i);
+        const dateMatch = part.match(/^date:(.+)$/i);
+        if (fromMatch) {
+            const term = `%${fromMatch[1].replace(/"/g, "")}%`;
+            conditions.push("(from_name LIKE ? OR from_address LIKE ?)");
+            params.push(term, term);
+        }
+        else if (toMatch) {
+            const term = `%${toMatch[1].replace(/"/g, "")}%`;
+            conditions.push("(to_json LIKE ? OR cc_json LIKE ?)");
+            params.push(term, term);
+        }
+        else if (subjectMatch) {
+            const term = `%${subjectMatch[1].replace(/"/g, "")}%`;
+            conditions.push("subject LIKE ?");
+            params.push(term);
+        }
+        else if (hasMatch) {
+            const v = hasMatch[1].toLowerCase();
+            if (v === "attachment" || v === "attachments") {
+                conditions.push("has_attachments = 1");
+            }
+            // Unknown has: qualifier — silently drop; treating as a literal
+            // search term would be confusing.
+        }
+        else if (isMatch) {
+            const v = isMatch[1].toLowerCase();
+            if (v === "flagged" || v === "starred") {
+                conditions.push("flags_json LIKE ?");
+                params.push("%\\\\Flagged%");
+            }
+            else if (v === "unread") {
+                conditions.push("flags_json NOT LIKE ?");
+                params.push("%\\\\Seen%");
+            }
+            else if (v === "read") {
+                conditions.push("flags_json LIKE ?");
+                params.push("%\\\\Seen%");
+            }
+        }
+        else if (dateMatch) {
+            const spec = parseDateSpec(dateMatch[1]);
+            if (spec) {
+                if (spec.from !== undefined) {
+                    conditions.push("date >= ?");
+                    params.push(spec.from);
+                }
+                if (spec.to !== undefined) {
+                    conditions.push("date < ?");
+                    params.push(spec.to);
+                }
+            }
+        }
+        else {
+            const term = `%${part}%`;
+            conditions.push("(subject LIKE ? OR from_name LIKE ? OR from_address LIKE ? OR preview LIKE ?)");
+            params.push(term, term, term, term);
+        }
+    }
+    return { conditions, params };
+}
 //# sourceMappingURL=index.js.map

package/package.json

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