@bobfrankston/mailx-types 0.1.73 → 0.1.78

package/index.d.ts

@@ -5,6 +5,7 @@
  */
 export { CONTACT_RULES } from "./contact-rules.js";
 export { assessMessageTrust, spamScoreOf } from "./trust.js";
+export { logIfChanged, clearLogState } from "./log-changes.js";
 export type { TrustFinding, TrustInput, SpamScore } from "./trust.js";
 export type { MailxApi } from "./mailx-api.js";
 export { addContactsDenylistEntry, addContactsPreferredEntry, type PreferredContactEntry, type CloudReadFn, type CloudWriteFn, } from "./contacts-config.js";
@@ -54,11 +55,17 @@ export interface AccountConfig {
     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. */
+/** Signature configuration in accounts.jsonc. May be set per-account or once
+ *  at the top level of the file, where it applies to every account that has
+ *  no `sig` of its own. Appended by compose to new mail, replies and
+ *  forwards; drafts already carry it in the saved body.
+ *
+ *  2026-09-02 — Claude Code (Opus 5), at Bob's direction: `html` is honoured
+ *  (client/compose/compose.ts), not "reserved for future use" as this comment
+ *  previously claimed. */
 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. */
+    text: string; /** Signature body. Plain text unless `html` is set. Appended to NEW messages with the standard "-- " RFC 3676 separator. */
+    html?: boolean; /** When true, `text` is inserted as raw HTML — write your own `<br>` for line breaks. When false/absent, `text` is HTML-escaped and newlines become `<br>`. */
 }
 /** Standard IMAP special-use folder types */
 export type SpecialUse = "inbox" | "sent" | "drafts" | "trash" | "junk" | "archive" | "all";

package/index.js

@@ -8,6 +8,7 @@
 // junk-contact filtering on every platform.
 export { CONTACT_RULES } from "./contact-rules.js";
 export { assessMessageTrust, spamScoreOf } from "./trust.js";
+export { logIfChanged, clearLogState } from "./log-changes.js";
 // Shared contacts.jsonc mutations — one implementation for desktop + Android.
 export { addContactsDenylistEntry, addContactsPreferredEntry, } from "./contacts-config.js";
 // Group-name expansion for recipient fields. Lets users type a group name

package/log-changes.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Log a line only when it says something new.
+ *
+ * Sync walks ~90 folders every cycle, and a folder in a bad state produces the
+ * SAME line every time — "reconcile refused — would delete 250/250 (100%)"
+ * once per folder per cycle, forever. On Android each of those is an HTTP
+ * request to the log server, and in the file the real news is buried under
+ * hundreds of identical repeats (Bob 2026-08-29: "are we overlogging").
+ *
+ * Deleting the lines is the wrong fix — a refused reconcile is a genuine
+ * anomaly and the log is where it surfaces. What is worth reading is the
+ * CHANGE: the first time a folder enters that state, and every time the
+ * numbers move. So the same key + same text is dropped, a changed text is
+ * printed, and a state that persists is re-stated once an hour so a standing
+ * problem cannot become invisible.
+ *
+ * Keyed by caller-supplied string (account + folder + which check), because
+ * two folders in the same state are two facts, not one.
+ */
+/**
+ * @param key    identifies the thing being described — "acct/folder:reconcile"
+ * @param line   the message; identical text for the same key is suppressed
+ * @param emit   where to write (defaults to console.log; pass a logger in libraries)
+ * @returns whether the line was emitted, so callers can count what they skipped
+ */
+export declare function logIfChanged(key: string, line: string, emit?: (msg: string) => void): boolean;
+/** Forget a key — call when the condition clears, so its return is news again. */
+export declare function clearLogState(key: string): void;
+//# sourceMappingURL=log-changes.d.ts.map

package/log-changes.js

@@ -0,0 +1,42 @@
+/**
+ * Log a line only when it says something new.
+ *
+ * Sync walks ~90 folders every cycle, and a folder in a bad state produces the
+ * SAME line every time — "reconcile refused — would delete 250/250 (100%)"
+ * once per folder per cycle, forever. On Android each of those is an HTTP
+ * request to the log server, and in the file the real news is buried under
+ * hundreds of identical repeats (Bob 2026-08-29: "are we overlogging").
+ *
+ * Deleting the lines is the wrong fix — a refused reconcile is a genuine
+ * anomaly and the log is where it surfaces. What is worth reading is the
+ * CHANGE: the first time a folder enters that state, and every time the
+ * numbers move. So the same key + same text is dropped, a changed text is
+ * printed, and a state that persists is re-stated once an hour so a standing
+ * problem cannot become invisible.
+ *
+ * Keyed by caller-supplied string (account + folder + which check), because
+ * two folders in the same state are two facts, not one.
+ */
+/** How long an unchanged line stays suppressed before being restated. */
+const RESTATE_AFTER_MS = 60 * 60 * 1000;
+const lastSeen = new Map();
+/**
+ * @param key    identifies the thing being described — "acct/folder:reconcile"
+ * @param line   the message; identical text for the same key is suppressed
+ * @param emit   where to write (defaults to console.log; pass a logger in libraries)
+ * @returns whether the line was emitted, so callers can count what they skipped
+ */
+export function logIfChanged(key, line, emit = console.log) {
+    const now = Date.now();
+    const prev = lastSeen.get(key);
+    if (prev && prev.line === line && now - prev.at < RESTATE_AFTER_MS)
+        return false;
+    lastSeen.set(key, { line, at: now });
+    emit(prev && prev.line === line ? `${line} (unchanged for an hour)` : line);
+    return true;
+}
+/** Forget a key — call when the condition clears, so its return is news again. */
+export function clearLogState(key) {
+    lastSeen.delete(key);
+}
+//# sourceMappingURL=log-changes.js.map

package/package.json

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