@wirecat/cli-core 0.514.0 → 0.515.0

package/CHANGELOG.md

@@ -7,6 +7,18 @@ shape of this file.
 
 ## Unreleased
 
+## 0.515.0 — 01.11.2026
+
+### Added
+
+- **`storedMailRules(store, account, query?)`** reads one account's mail rules from the store in the shape
+  `syncMail` takes as `account.rules`, and `storedMailRule(stored)` reads one; a rule with a condition this build does
+  not know is left out. An account the store has not seen has no rules.
+- **`labelName(raw)`, `systemLabel(name)` and `decodeMailboxName(name)`** name Gmail labels as people read them
+  (`\Inbox` and `Inbox` are one label, modified UTF-7 is decoded), moved from memo.
+- **`mailProgress(store, key)`** gives each synced folder's window, done and total from the saved resume points,
+  without asking the mailbox. It treats only `not_found` as "no account yet" and passes other store errors on.
+
 ## 0.514.0 — 01.11.2026
 
 ### Fixed

package/dist/mail/index.d.ts

@@ -3,11 +3,14 @@ export { factsOf } from "./facts.js";
 export { GMAIL_ALL_MAIL, mailFolders } from "./folders.js";
 export { dropMissing, type Gone, tooManyGone } from "./gone.js";
 export { type AuthVerdicts, HEADER_FIELDS, headersOf, type MailHeaders, mailHeadersOf } from "./headers.js";
+export { decodeMailboxName, labelName, systemLabel } from "./labels.js";
 export { type Address, htmlToText, looksLikeHtml, MAX_BODY_CHARS, type ParsedMail, parseMail, } from "./parse.js";
 export { PRESET_NAMES, PRESETS, type PresetName, presetMatches } from "./presets.js";
 export { domainsToAge, groupKey, type Probe, type ProbeGroup, probeMail, SUGGEST_RULE } from "./probe.js";
+export { type MailFolderProgress, mailProgress } from "./progress.js";
 export { type FileStamp, FULL_PASS_MS, MBOX_RESUME, type MboxPoint, mergeRanges, parsePoint, type Ranges, type ResumePoint, rangesOf, resumeKey, rulesKey, within, } from "./resume.js";
 export { ruleInput, STORE_ACTION } from "./rule-input.js";
+export { storedMailRule, storedMailRules } from "./rule-stored.js";
 export { mapProposedTags, ruleTagger, settleRuleTags, type TagOutcome } from "./rule-tags.js";
 export { conditionKeys, decide, describeMatch, ENVELOPE, envelopeBox, envelopeBoxOf, type MailAction, type MailFacts, type MailRule, type MailRuleMatch, matches, sameMatch, tagsOf, } from "./rules.js";
 export { type DomainAge, FRAUD_SIGNALS, FREE_MAIL, registrableOf, SCORE_RULE, type Scored, type Signal, scoreGroup, WEIGHTS, } from "./score.js";

package/dist/mail/index.js

@@ -3,11 +3,14 @@ export { factsOf } from "./facts.js";
 export { GMAIL_ALL_MAIL, mailFolders } from "./folders.js";
 export { dropMissing, tooManyGone } from "./gone.js";
 export { HEADER_FIELDS, headersOf, mailHeadersOf } from "./headers.js";
+export { decodeMailboxName, labelName, systemLabel } from "./labels.js";
 export { htmlToText, looksLikeHtml, MAX_BODY_CHARS, parseMail, } from "./parse.js";
 export { PRESET_NAMES, PRESETS, presetMatches } from "./presets.js";
 export { domainsToAge, groupKey, probeMail, SUGGEST_RULE } from "./probe.js";
+export { mailProgress } from "./progress.js";
 export { FULL_PASS_MS, MBOX_RESUME, mergeRanges, parsePoint, rangesOf, resumeKey, rulesKey, within, } from "./resume.js";
 export { ruleInput, STORE_ACTION } from "./rule-input.js";
+export { storedMailRule, storedMailRules } from "./rule-stored.js";
 export { mapProposedTags, ruleTagger, settleRuleTags } from "./rule-tags.js";
 export { conditionKeys, decide, describeMatch, ENVELOPE, envelopeBox, envelopeBoxOf, matches, sameMatch, tagsOf, } from "./rules.js";
 export { FRAUD_SIGNALS, FREE_MAIL, registrableOf, SCORE_RULE, scoreGroup, WEIGHTS, } from "./score.js";

package/dist/mail/labels.d.ts

@@ -0,0 +1,5 @@
+/** IMAP's modified UTF-7 (RFC 3501 §5.1.3): `&` opens base64 of UTF-16BE, `,` stands for `/`, `-` closes. */
+export declare const decodeMailboxName: (name: string) => string;
+export declare const systemLabel: (name: string) => string;
+/** A label as people read it: `\\Important` and `Important` are one label, and names are decoded. */
+export declare const labelName: (raw: string) => string;

package/dist/mail/labels.js

@@ -0,0 +1,27 @@
+const SYSTEM_LABELS = {
+    inbox: "Inbox",
+    sent: "Sent",
+    important: "Important",
+    starred: "Starred",
+    draft: "Drafts",
+    drafts: "Drafts",
+    spam: "Spam",
+    trash: "Trash",
+    junk: "Spam",
+};
+/** IMAP's modified UTF-7 (RFC 3501 §5.1.3): `&` opens base64 of UTF-16BE, `,` stands for `/`, `-` closes. */
+export const decodeMailboxName = (name) => name.replace(/&([^-]*)-/g, (_, run) => {
+    if (run === "")
+        return "&";
+    const bytes = Buffer.from(run.replace(/,/g, "/"), "base64");
+    let text = "";
+    for (let at = 0; at + 1 < bytes.length; at += 2)
+        text += String.fromCharCode(bytes.readUInt16BE(at));
+    return text;
+});
+export const systemLabel = (name) => SYSTEM_LABELS[name.toLowerCase()] ?? name;
+/** A label as people read it: `\\Important` and `Important` are one label, and names are decoded. */
+export const labelName = (raw) => {
+    const system = raw.startsWith("\\") ? raw.slice(1) : raw;
+    return SYSTEM_LABELS[system.toLowerCase()] ?? decodeMailboxName(system);
+};

package/dist/mail/progress.d.ts

@@ -0,0 +1,10 @@
+import type { AccountKey, MessageStore } from "../store/index.js";
+export interface MailFolderProgress {
+    folder: string;
+    since: string;
+    done: number;
+    total: number;
+    updatedAt: string;
+}
+/** How far the sync of each stored folder is, from the points the runs saved; the mailbox is not asked. */
+export declare const mailProgress: (store: MessageStore, key: AccountKey) => Promise<MailFolderProgress[]>;

package/dist/mail/progress.js

@@ -0,0 +1,29 @@
+import { CliError } from "@wirecat/cli-base";
+import { parsePoint, resumeKey } from "./resume.js";
+/** How far the sync of each stored folder is, from the points the runs saved; the mailbox is not asked. */
+export const mailProgress = async (store, key) => {
+    let accountId;
+    try {
+        accountId = (await store.accounts.storedAccount(key)).id;
+    }
+    catch (error) {
+        if (error instanceof CliError && error.code === "not_found")
+            return [];
+        throw error;
+    }
+    const folders = [];
+    for (const { kind, externalId: folder } of await store.mail.mailboxes(accountId)) {
+        if (kind !== null)
+            continue;
+        const point = parsePoint((await store.sync.syncState(key, resumeKey(folder)))?.value);
+        if (point !== undefined)
+            folders.push({
+                folder,
+                since: point.window.since,
+                done: point.window.done,
+                total: point.window.total,
+                updatedAt: point.updatedAt,
+            });
+    }
+    return folders;
+};

package/dist/mail/rule-stored.d.ts

@@ -0,0 +1,9 @@
+import type { QueryAst } from "@wirecat/cli-base/query";
+import type { MessageStore, MailRule as StoredRule } from "../store/index.js";
+import type { MailRule } from "./rules.js";
+/** A stored rule as the sync reads it; `undefined` for one this build cannot read, so it is left to the build that can. */
+export declare const storedMailRule: (stored: StoredRule) => MailRule | undefined;
+/** One account's rules from the store, for `account.rules` of the sync; none when the store has not seen the account. */
+export declare const storedMailRules: (store: MessageStore, account: {
+    address: string;
+}, query?: QueryAst) => Promise<MailRule[]>;

package/dist/mail/rule-stored.js

@@ -0,0 +1,57 @@
+import { CliError } from "@wirecat/cli-base";
+import { PRESET_NAMES } from "./presets.js";
+const ACTION_OF = { full: "keep", envelope: "envelope", skip: "skip" };
+const KINDS = {
+    from: "string",
+    from_contains: "string",
+    domain: "string",
+    to: "string",
+    list_id: "string",
+    subject: "string",
+    older_than_days: "number",
+    larger_than_bytes: "number",
+    has_attachments: "boolean",
+    label: "string",
+    unread: "boolean",
+    bulk: "boolean",
+    score_at_least: "number",
+    preset: "string",
+};
+/** A stored rule as the sync reads it; `undefined` for one this build cannot read, so it is left to the build that can. */
+export const storedMailRule = (stored) => {
+    const action = ACTION_OF[String(stored.actions.store)];
+    const entries = Object.entries(stored.conditions);
+    const known = entries.every(([key, value]) => key in KINDS &&
+        typeof value === KINDS[key] &&
+        !(key === "preset" && !PRESET_NAMES.includes(value)));
+    if (action === undefined || !known || entries.length === 0)
+        return undefined;
+    const tags = Array.isArray(stored.actions.tags) ? stored.actions.tags.filter((tag) => typeof tag === "string") : [];
+    const skipped = stored.actions.tags_skipped;
+    const tagsSkipped = skipped !== null && typeof skipped === "object" && !Array.isArray(skipped)
+        ? Object.fromEntries(Object.entries(skipped).filter(([, why]) => typeof why === "string"))
+        : {};
+    return {
+        id: stored.id,
+        match: Object.fromEntries(entries),
+        action,
+        ...(tags.length ? { tags: tags } : {}),
+        ...(Object.keys(tagsSkipped).length ? { tags_skipped: tagsSkipped } : {}),
+        ...(stored.reason === null ? {} : { reason: stored.reason }),
+        ...(stored.protected ? { protected: true } : {}),
+        ...(stored.source === "owner" ? {} : { source: stored.source }),
+        decided_at: new Date(stored.decidedAt).toISOString(),
+    };
+};
+/** One account's rules from the store, for `account.rules` of the sync; none when the store has not seen the account. */
+export const storedMailRules = async (store, account, query) => {
+    try {
+        const { id } = await store.accounts.storedAccount({ provider: "email", account: account.address.toLowerCase() });
+        return (await store.mail.rules.list(id, query)).flatMap((stored) => storedMailRule(stored) ?? []);
+    }
+    catch (error) {
+        if (error instanceof CliError && error.code === "not_found")
+            return [];
+        throw error;
+    }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.514.0",
+  "version": "0.515.0",
   "description": "The messenger-neutral half of a messaging CLI: domain model, message locators, rendering, name resolution, the SQLite seam, the command skeleton and shared read commands, the send guard, run records and the message store",
   "license": "Apache-2.0",
   "author": "Viacheslav Ptsarev",