@bobfrankston/mailx-types 0.1.73 → 0.1.76

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";

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.76",
   "type": "module",
   "main": "index.js",
   "types": "index.d.ts",