@wirecat/cli-core 0.487.0 → 0.489.0

package/dist/mail/retry.js

@@ -0,0 +1,110 @@
+import { CliError } from "@wirecat/cli-base";
+import { addressOf, FETCH_CHUNK, readAttachments } from "./attachments.js";
+import { mailFolders } from "./folders.js";
+import { mailHeadersOf } from "./headers.js";
+import { parseMail } from "./parse.js";
+/** Failures a newer install mends: the reader was missing, not the file at fault, so reading again can succeed. */
+export const RETRYABLE_ATTACHMENTS = ["engine-missing"];
+/**
+ * Reads again, by Gmail id, only the stored emails with an attachment a missing reader left unread: memo keeps no
+ * attachment file, so the email comes from the source again. Nothing is listed, so no deletion is proved and no
+ * resume point moves; the email keeps its stored mailboxes, flags and rule.
+ */
+export const retryUnread = async ({ store, source, account, since, max, maxBodyChars, maxAttachmentChars, now, loadEngine, index, }) => {
+    const startedAt = now();
+    const key = { provider: "email", account: account.address.toLowerCase() };
+    const find = source.find;
+    if (find === undefined)
+        throw new CliError("validation_error", "--retry-attachments reads mail again by its Gmail id; an mbox file or a plain IMAP account has none");
+    const accountId = await store.accounts.saveAccount(key, { name: account.address });
+    const wanted = (await store.mail.emailRefs({ accountId, attachmentErrors: RETRYABLE_ATTACHMENTS })).map(({ externalId }) => externalId);
+    const chosen = wanted.slice(0, max);
+    const found = new Map();
+    for (const folder of await mailFolders(account, source)) {
+        const left = chosen.filter((id) => !found.has(id));
+        if (left.length === 0)
+            break;
+        for (const item of await find(left, folder))
+            if (!found.has(item.messageId))
+                found.set(item.messageId, item);
+    }
+    const items = [...found.values()];
+    const attachments = [];
+    const unreadable = [];
+    let emails = 0;
+    let extracted = 0;
+    let stillFailed = 0;
+    for (let start = 0; start < items.length; start += FETCH_CHUNK) {
+        const chunk = items.slice(start, start + FETCH_CHUNK);
+        const raws = await source.fetchRaw(chunk);
+        for (const [index, item] of chunk.entries()) {
+            const raw = raws[index];
+            const stored = await store.mail.email(accountId, item.messageId);
+            if (stored === null)
+                continue;
+            let mail;
+            try {
+                if (raw === undefined || raw instanceof Error)
+                    throw raw ?? new Error("not read");
+                mail = await parseMail(raw, maxBodyChars);
+            }
+            catch (error) {
+                unreadable.push({ message: item.messageId, reason: error instanceof Error ? error.message : String(error) });
+                continue;
+            }
+            const before = new Map(stored.attachments.map(({ position, extractionError }) => [position, extractionError]));
+            const files = await readAttachments(mail, item.messageId, { loadEngine, maxAttachmentChars, at: startedAt }, attachments);
+            for (const file of files)
+                if (RETRYABLE_ATTACHMENTS.includes(before.get(file.position) ?? ""))
+                    if (file.extraction === "text")
+                        extracted++;
+                    else
+                        stillFailed++;
+            const header = mailHeadersOf(raw);
+            await store.mail.saveThread({
+                accountId,
+                externalId: item.threadId,
+                now: startedAt,
+                emails: [
+                    {
+                        externalId: item.messageId,
+                        subject: mail.subject,
+                        from: mail.from === null ? null : addressOf(mail.from),
+                        to: mail.to.map(addressOf),
+                        cc: mail.cc.map(addressOf),
+                        bcc: mail.bcc.map(addressOf),
+                        sentAt: null,
+                        receivedAt: Date.parse(item.receivedAt),
+                        bodyText: mail.text || null,
+                        size: item.size ?? stored.size,
+                        ...(Object.keys(header).length ? { headers: header } : {}),
+                        outgoing: mail.from === null ? null : mail.from.email === key.account,
+                        mailboxes: stored.mailboxes.map(({ externalId, name, kind }) => ({ externalId, name, kind })),
+                        ...(stored.read === null ? {} : { read: stored.read }),
+                        ...(stored.flagged === null ? {} : { flagged: stored.flagged }),
+                        metadata: stored.metadata,
+                        mailRuleId: stored.mailRuleId,
+                        attachments: files,
+                    },
+                ],
+            });
+            emails++;
+        }
+    }
+    const indexed = await index?.(store, key);
+    return {
+        account: key.account,
+        since: since.toISOString(),
+        listed: items.length,
+        saved: 0,
+        alreadyStored: 0,
+        skipped: 0,
+        envelopes: 0,
+        deleted: 0,
+        complete: wanted.length <= max && unreadable.length === 0,
+        ...(indexed === undefined ? {} : { indexed }),
+        retried: { emails, extracted, stillFailed, missing: chosen.length - items.length },
+        ...(attachments.length ? { attachments } : {}),
+        ...(unreadable.length ? { unreadable } : {}),
+    };
+};

package/dist/mail/sync.d.ts

@@ -74,7 +74,8 @@ export interface MailSyncResult {
         missing: number;
     };
 }
-export declare const MAX_ATTACHMENT_CHARS = 200000;
+export { MAX_ATTACHMENT_CHARS } from "./attachments.js";
+export { RETRYABLE_ATTACHMENTS } from "./retry.js";
 export interface MailSyncOptions {
     account: MailAccount;
     since: Date;
@@ -102,5 +103,3 @@ export interface MailSyncOptions {
     budget?: RunBudget;
 }
 export declare const syncMail: (source: MailSource, store: MessageStore, options: MailSyncOptions) => Promise<MailSyncResult>;
-/** Failures a newer install mends: the reader was missing, not the file at fault, so reading again can succeed. */
-export declare const RETRYABLE_ATTACHMENTS: string[];

package/dist/mail/sync.js

@@ -1,59 +1,27 @@
 import { CliError } from "@wirecat/cli-base";
-import { extractText, importEngine } from "../attachments/extract.js";
+import { importEngine } from "../attachments/extract.js";
+import { addressOf, FETCH_CHUNK, MAX_ATTACHMENT_CHARS, readAttachments } from "./attachments.js";
 import { BULK, bulkBox } from "./bulk.js";
 import { factsOf } from "./facts.js";
 import { GMAIL_ALL_MAIL, mailFolders } from "./folders.js";
 import { dropMissing, tooManyGone } from "./gone.js";
 import { mailHeadersOf } from "./headers.js";
+import { flagsToRefresh, proveByLocation } from "./locations.js";
 import { MAX_BODY_CHARS, parseMail } from "./parse.js";
 import { FETCH_SLICE, keyOf, readQuick } from "./quick.js";
 import { FULL_PASS_MS, MBOX_RESUME, mergeRanges, parsePoint, rangesOf, resumeKey, rulesKey, within, } from "./resume.js";
+import { retryUnread } from "./retry.js";
 import { ruleTagger, settleRuleTags } from "./rule-tags.js";
 import { decide, ENVELOPE, envelopeBox, envelopeBoxOf, tagsOf } from "./rules.js";
 const DAY = 86_400_000;
 /** IMAP's SINCE counts whole days in the server's zone, so the window's first days are not trusted. */
 const EDGE = 2 * DAY;
-export const MAX_ATTACHMENT_CHARS = 200_000;
-/** One chunk of raw mail is held in memory at a time. */
-const FETCH_CHUNK = 50;
 /** How often a long run saves where it is, so a kill costs at most this much listing again. */
 const SAVE_EVERY_MS = 30_000;
 /** About a minute of listing; the 30-day window of the timer stays below it. */
 const RESUME_FROM = 5_000;
-const addressOf = ({ email, name }) => ({ address: email, name });
-/** A parsed email's attachments as the store keeps them, each with its text or why it has none. */
-const readAttachments = async (mail, messageId, { loadEngine, maxAttachmentChars, at }, log) => {
-    const files = [];
-    for (const [position, part] of mail.attachments.entries()) {
-        const extraction = part.bytes === null
-            ? { status: "unavailable" }
-            : await extractText(part.bytes, { kind: "file", name: part.name, mime: part.mime, path: part.name }, loadEngine);
-        log.push({ message: messageId, part: part.id, status: extraction.status });
-        const extracted = extraction.status === "extracted" ? extraction : undefined;
-        files.push({
-            position,
-            kind: "file",
-            mime: part.mime,
-            name: part.name,
-            title: null,
-            url: null,
-            size: part.bytes === null ? null : part.bytes.byteLength,
-            width: null,
-            height: null,
-            duration: null,
-            providerRef: { message: messageId, part: part.id },
-            localPath: null,
-            text: extracted ? extracted.text.slice(0, maxAttachmentChars) : null,
-            normalizedText: null,
-            extraction: extracted ? "text" : "failed",
-            extractor: extracted ? extracted.extractor : null,
-            extractionError: extracted ? null : extraction.status,
-            contentSha256: null,
-            extractedAt: at,
-        });
-    }
-    return files;
-};
+export { MAX_ATTACHMENT_CHARS } from "./attachments.js";
+export { RETRYABLE_ATTACHMENTS } from "./retry.js";
 const LIST_SLICE = 200;
 export const syncMail = async (source, store, options) => {
     const { budget, index } = options;
@@ -194,6 +162,11 @@ const syncRound = async (source, store, { account, since, max = 200, maxBodyChar
     /** Raw mail read to learn its id, kept for the save so it is not read twice. */
     const rawOf = new Map();
     const quickRan = new Set();
+    /** Folders whose server gives no cheap id: their mail's UIDs are kept, so a UID listing can stand in for headers. */
+    const locatable = new Set();
+    /** A quick folder's stored mail as it was before this run changed anything, with the UID of each. */
+    const folderMail = new Map();
+    const refreshed = new Map();
     let holding;
     const holdsMail = async (folder) => {
         holding ??= new Set((await store.mail.emailRefs({ accountId })).flatMap(({ mailboxes }) => mailboxes
@@ -234,10 +207,16 @@ const syncRound = async (source, store, { account, since, max = 200, maxBodyChar
                 searched.validity !== undefined &&
                 source.quick !== undefined &&
                 source.identify !== undefined;
+            if (quickable)
+                locatable.add(folder);
+            // The UID listing proves deletions only for mail whose UID is stored; a folder stored before locations existed
+            // gets them from one header listing.
+            const located = point?.located !== undefined && Date.parse(point.located) <= since.getTime();
+            const quickReady = async () => (sameRules && located) || !(await holdsMail(folder));
             const inQuick = quickable &&
                 (plan === undefined
-                    ? sameRules || !(await holdsMail(folder))
-                    : plan.quickFolders.has(folder) || (!plan.modes.has(folder) && (sameRules || !(await holdsMail(folder)))));
+                    ? await quickReady()
+                    : plan.quickFolders.has(folder) || (!plan.modes.has(folder) && (await quickReady())));
             if (inQuick) {
                 plan?.quickFolders.add(folder);
                 plan?.modes.set(folder, "resumed");
@@ -246,7 +225,12 @@ const syncRound = async (source, store, { account, since, max = 200, maxBodyChar
                 const done = point !== undefined && sameRules ? point.done : [];
                 if (point !== undefined && sameRules)
                     earlier.set(folder, point);
-                const round = await readQuick(source, since, folder, searched, done, max, plan);
+                const rows = await store.mail.folderEmails(accountId, folder, searched.validity);
+                folderMail.set(folder, rows);
+                const byUid = new Map(rows.map((row) => [String(row.uid), row]));
+                const round = await readQuick(source, since, folder, searched, done, max, plan, new Set(byUid.keys()));
+                for (const [id, flags] of flagsToRefresh(byUid, round.listing))
+                    refreshed.set(id, { ...refreshed.get(id), ...flags });
                 if (round.capped)
                     capped = true;
                 for (const { item, raw } of round.read) {
@@ -260,12 +244,13 @@ const syncRound = async (source, store, { account, since, max = 200, maxBodyChar
             if (point !== undefined && point.validity === searched.validity && point.rules === ruleSet) {
                 earlier.set(folder, point);
                 const mode = plan?.modes.get(folder);
+                const backfill = quickable && !located;
                 const usable = Date.parse(point.full.since) <= since.getTime() && startedAt - Date.parse(point.full.at) < FULL_PASS_MS;
                 // A budgeted run goes on with an unfinished pass however small its window is: listing it whole again would
                 // ask for the same newest messages every run.
                 const unfinished = plan !== undefined && searched.uids.some((uid) => !within(point.done, Number(uid)));
                 if (mode === "resumed" ||
-                    (mode === undefined && usable && (searched.uids.length >= resumeFrom || unfinished))) {
+                    (mode === undefined && usable && !backfill && (searched.uids.length >= resumeFrom || unfinished))) {
                     resumed.add(folder);
                     wanted = { ...searched, uids: searched.uids.filter((uid) => !within(point.done, Number(uid))) };
                 }
@@ -332,6 +317,22 @@ const syncRound = async (source, store, { account, since, max = 200, maxBodyChar
         current.add(item.folder ?? folders[0]);
         foundFolders.set(item.messageId, current);
     }
+    const listingWhole = !capped && (plan === undefined || (plan.stopped === null && plan.failed.size === 0 && plan.only === undefined));
+    /** Where each message was seen this run, saved with it so a message saved is a message located. */
+    const locationsOf = new Map();
+    for (const item of collected) {
+        const folder = item.folder ?? folders[0];
+        const validity = searches.get(folder)?.validity;
+        if (!locatable.has(folder) || validity === undefined)
+            continue;
+        const where = locationsOf.get(item.messageId) ?? [];
+        where.push({ folder, uidvalidity: validity, uid: Number(item.uid) });
+        locationsOf.set(item.messageId, where);
+    }
+    const locationOf = (item) => {
+        const locations = locationsOf.get(item.messageId);
+        return locations === undefined ? {} : { locations };
+    };
     const mailbox = (folder) => ({ externalId: folder, name: folder, kind: null });
     const label = (name) => ({ externalId: `label:${name}`, name, kind: "label" });
     const labelsOf = new Map(collected.flatMap((item) => (item.labels === undefined ? [] : [[item.messageId, item]])));
@@ -346,8 +347,23 @@ const syncRound = async (source, store, { account, since, max = 200, maxBodyChar
         skipped = "an mbox file is a snapshot; mail missing from it is not proven deleted";
     else if (plan !== undefined && (capped || plan.tried.size > plan.asked || plan.only !== undefined))
         skipped = "this run read the window in parts; a run that lists all of it at once checks deletions";
-    else if (quickRan.size > 0)
-        skipped = "this run listed only mail not read before, by UID; --rescan lists every message and checks deletions";
+    else if (quickRan.size > 0) {
+        const proof = await proveByLocation(store, accountId, {
+            folders: new Map([...quickRan].map((folder) => [
+                folder,
+                { searched: searches.get(folder), rows: folderMail.get(folder) ?? [] },
+            ])),
+            windowFrom: windowStart.getTime(),
+            present,
+            now: startedAt,
+        }, tooManyGone);
+        deleted = proof.deleted;
+        skipped =
+            proof.skipped ??
+                (quickRan.size < folders.length
+                    ? "folders this run did not list by UID are not checked for deletions; --rescan lists every message and checks them"
+                    : undefined);
+    }
     else if (resumed.size > 0)
         skipped =
             "this run listed only mail not read before; a full listing, at least daily or with --rescan, checks deletions";
@@ -481,6 +497,8 @@ const syncRound = async (source, store, { account, since, max = 200, maxBodyChar
                     ? undefined
                     : { since: prior.window.since, total: prior.window.total, at: prior.updatedAt });
             const widestEver = priorWidest === undefined || since.getTime() <= Date.parse(priorWidest.since) ? thisRun : priorWidest;
+            const located = locatable.has(folder) && (quickRan.has(folder) || (!resumed.has(folder) && listingWhole));
+            const locatedFrom = before?.located === undefined ? since.toISOString() : before.located;
             const point = {
                 validity: searched.validity,
                 done: merged,
@@ -494,12 +512,22 @@ const syncRound = async (source, store, { account, since, max = 200, maxBodyChar
                     }
                     : before.window,
                 widest: widestEver,
+                ...(located
+                    ? { located: Date.parse(locatedFrom) < since.getTime() ? locatedFrom : since.toISOString() }
+                    : before?.located === undefined
+                        ? {}
+                        : { located: before.located }),
                 last: { ...thisRun, done: searched.uids.filter((uid) => within(merged, Number(uid))).length },
                 updatedAt: new Date(now()).toISOString(),
             };
             await store.sync.setSyncState(key, resumeKey(folder), JSON.stringify(point));
         }
     };
+    // Mail already stored is located before its UID is marked done, so a done UID always has its place.
+    for (const folder of locatable) {
+        const searched = searches.get(folder);
+        await store.mail.setLocations(accountId, folder, searched.validity, uidsOf.get(folder) ?? new Map());
+    }
     let savedAt = now();
     const saveNow = async (force = false) => {
         if (!force && now() - savedAt < SAVE_EVERY_MS)
@@ -534,6 +562,7 @@ const syncRound = async (source, store, { account, since, max = 200, maxBodyChar
                     size: item.size ?? null,
                     outgoing: headers?.from === key.account,
                     mailboxes: [...inMailboxes(item), envelopeBox(rule.match)],
+                    ...locationOf(item),
                     ...flagsOf(item),
                     mailRuleId: rule.id ?? null,
                     metadata: {
@@ -620,6 +649,7 @@ const syncRound = async (source, store, { account, since, max = 200, maxBodyChar
                         ...(Object.keys(header).length ? { headers: header } : {}),
                         outgoing: mail.from === null ? null : mail.from.email === key.account,
                         mailboxes: inMailboxes(item),
+                        ...locationOf(item),
                         ...flagsOf(item),
                         ...(upgraded.has(item.messageId) ? { metadata: {} } : {}),
                         mailRuleId: decide(rules, factsFor(item))?.id ?? null,
@@ -647,9 +677,17 @@ const syncRound = async (source, store, { account, since, max = 200, maxBodyChar
     }
     // Read and starred change at the source after import; mail saved in this run already holds them.
     if (!snapshot)
-        await store.mail.setFlags(accountId, new Map([...labelsOf].flatMap(([id, { seen, flagged }]) => seen === undefined && flagged === undefined
-            ? []
-            : [[id, { ...(seen === undefined ? {} : { read: seen }), ...(flagged === undefined ? {} : { flagged }) }]])), startedAt);
+        await store.mail.setFlags(accountId, new Map([
+            ...refreshed,
+            ...[...labelsOf].flatMap(([id, { seen, flagged }]) => seen === undefined && flagged === undefined
+                ? []
+                : [
+                    [
+                        id,
+                        { ...(seen === undefined ? {} : { read: seen }), ...(flagged === undefined ? {} : { flagged }) },
+                    ],
+                ]),
+        ]), startedAt);
     const incomplete = capped || (plan !== undefined && (plan.stopped !== null || plan.failed.size > 0));
     const complete = !full && !incomplete && unreadable.length === 0 && (plan?.unreadable.size ?? 0) === 0;
     const bulk = new Map(listed.filter((item) => item.headers?.bulk).map((item) => [item.messageId, [bulkBox.externalId]]));
@@ -690,108 +728,3 @@ const syncRound = async (source, store, { account, since, max = 200, maxBodyChar
         ...(tagging.skipped.length ? { tagsSkipped: tagging.skipped } : {}),
     };
 };
-/** Failures a newer install mends: the reader was missing, not the file at fault, so reading again can succeed. */
-export const RETRYABLE_ATTACHMENTS = ["engine-missing"];
-/**
- * Reads again, by Gmail id, only the stored emails with an attachment a missing reader left unread: memo keeps no
- * attachment file, so the email comes from the source again. Nothing is listed, so no deletion is proved and no
- * resume point moves; the email keeps its stored mailboxes, flags and rule.
- */
-const retryUnread = async ({ store, source, account, since, max, maxBodyChars, maxAttachmentChars, now, loadEngine, index, }) => {
-    const startedAt = now();
-    const key = { provider: "email", account: account.address.toLowerCase() };
-    const find = source.find;
-    if (find === undefined)
-        throw new CliError("validation_error", "--retry-attachments reads mail again by its Gmail id; an mbox file or a plain IMAP account has none");
-    const accountId = await store.accounts.saveAccount(key, { name: account.address });
-    const wanted = (await store.mail.emailRefs({ accountId, attachmentErrors: RETRYABLE_ATTACHMENTS })).map(({ externalId }) => externalId);
-    const chosen = wanted.slice(0, max);
-    const found = new Map();
-    for (const folder of await mailFolders(account, source)) {
-        const left = chosen.filter((id) => !found.has(id));
-        if (left.length === 0)
-            break;
-        for (const item of await find(left, folder))
-            if (!found.has(item.messageId))
-                found.set(item.messageId, item);
-    }
-    const items = [...found.values()];
-    const attachments = [];
-    const unreadable = [];
-    let emails = 0;
-    let extracted = 0;
-    let stillFailed = 0;
-    for (let start = 0; start < items.length; start += FETCH_CHUNK) {
-        const chunk = items.slice(start, start + FETCH_CHUNK);
-        const raws = await source.fetchRaw(chunk);
-        for (const [index, item] of chunk.entries()) {
-            const raw = raws[index];
-            const stored = await store.mail.email(accountId, item.messageId);
-            if (stored === null)
-                continue;
-            let mail;
-            try {
-                if (raw === undefined || raw instanceof Error)
-                    throw raw ?? new Error("not read");
-                mail = await parseMail(raw, maxBodyChars);
-            }
-            catch (error) {
-                unreadable.push({ message: item.messageId, reason: error instanceof Error ? error.message : String(error) });
-                continue;
-            }
-            const before = new Map(stored.attachments.map(({ position, extractionError }) => [position, extractionError]));
-            const files = await readAttachments(mail, item.messageId, { loadEngine, maxAttachmentChars, at: startedAt }, attachments);
-            for (const file of files)
-                if (RETRYABLE_ATTACHMENTS.includes(before.get(file.position) ?? ""))
-                    if (file.extraction === "text")
-                        extracted++;
-                    else
-                        stillFailed++;
-            const header = mailHeadersOf(raw);
-            await store.mail.saveThread({
-                accountId,
-                externalId: item.threadId,
-                now: startedAt,
-                emails: [
-                    {
-                        externalId: item.messageId,
-                        subject: mail.subject,
-                        from: mail.from === null ? null : addressOf(mail.from),
-                        to: mail.to.map(addressOf),
-                        cc: mail.cc.map(addressOf),
-                        bcc: mail.bcc.map(addressOf),
-                        sentAt: null,
-                        receivedAt: Date.parse(item.receivedAt),
-                        bodyText: mail.text || null,
-                        size: item.size ?? stored.size,
-                        ...(Object.keys(header).length ? { headers: header } : {}),
-                        outgoing: mail.from === null ? null : mail.from.email === key.account,
-                        mailboxes: stored.mailboxes.map(({ externalId, name, kind }) => ({ externalId, name, kind })),
-                        ...(stored.read === null ? {} : { read: stored.read }),
-                        ...(stored.flagged === null ? {} : { flagged: stored.flagged }),
-                        metadata: stored.metadata,
-                        mailRuleId: stored.mailRuleId,
-                        attachments: files,
-                    },
-                ],
-            });
-            emails++;
-        }
-    }
-    const indexed = await index?.(store, key);
-    return {
-        account: key.account,
-        since: since.toISOString(),
-        listed: items.length,
-        saved: 0,
-        alreadyStored: 0,
-        skipped: 0,
-        envelopes: 0,
-        deleted: 0,
-        complete: wanted.length <= max && unreadable.length === 0,
-        ...(indexed === undefined ? {} : { indexed }),
-        retried: { emails, extracted, stillFailed, missing: chosen.length - items.length },
-        ...(attachments.length ? { attachments } : {}),
-        ...(unreadable.length ? { unreadable } : {}),
-    };
-};

package/dist/mail/testing/fake.d.ts

@@ -26,6 +26,8 @@ export interface FakeMail {
     flagged?: boolean;
     /** `trash` puts it in the trash folder; otherwise it is in All Mail, which INBOX also shows. */
     folder?: "trash";
+    /** Folders that do not hold it although its `folder` says they do, as a server's delete from one folder leaves it. */
+    absentFrom?: string[];
 }
 /** The mailbox a fake source reads live, so a test changes it between syncs; the switches make the source fail. */
 export interface FakeMailbox {

package/dist/mail/testing/fake.js

@@ -54,7 +54,7 @@ export const fakeMailSource = (mailbox) => {
     const inFolder = (folder) => {
         if (![all(), trash(), "INBOX"].includes(folder))
             throw failure(`Gmail has no such mailbox: ${folder}`);
-        return mailbox.messages.filter((m) => (folder === trash() ? m.folder === "trash" : m.folder !== "trash"));
+        return mailbox.messages.filter((m) => (folder === trash() ? m.folder === "trash" : m.folder !== "trash") && !m.absentFrom?.includes(folder));
     };
     const search = async (since, folder) => {
         if (mailbox.searchFails)

package/dist/meetings/event-store.d.ts

@@ -144,6 +144,10 @@ export interface StoredEntry {
     etag: string | null;
     seenAt: number | null;
     deletedAt: number | null;
+    /** When this copy was first stored. */
+    createdAt: number;
+    /** `transparent`: the copy does not take the owner's time. */
+    transparency: EntryTransparency | null;
 }
 export interface StoredParticipant {
     entryId: number;
@@ -183,6 +187,13 @@ export interface EventFilter {
     to?: number;
     /** All-day events, which have dates and no instant, ending after this local day (`YYYY-MM-DD`); `from` without it. */
     fromDate?: string;
+    /** Events `eventChange` finds new, moved or cancelled at or after this instant. */
+    changedSince?: number;
+    /**
+     * Events whose time overlaps another's. Only timed events that take the owner's time count: not cancelled, and with
+     * a live copy the owner did not decline or mark free.
+     */
+    overlapping?: boolean;
     /** All-day events starting before this local day (exclusive); `to` without it. */
     toDate?: string;
     accountId?: number;
@@ -195,10 +206,17 @@ export interface EventFilter {
     offset?: number;
 }
 /** Pairs the rules left unlinked because two or more entities fit equally well (requirements 3.6). */
+/** One series' slots for `EventStore.saveSlots`: what the provider gave, or `null` to keep what is stored. */
+export interface SeriesSlots {
+    series: string;
+    slots: EntryInput[] | null;
+}
 export interface LinkReview {
     id: number;
     linkableType: string;
     linkableId: number;
+    /** The calendar of a `calendar_entry` review's copy, so a choice is made only from that calendar's account. */
+    calendarId: number | null;
     entityType: string;
     candidates: number[];
     reason: string;
@@ -231,13 +249,22 @@ export interface EventStore {
      */
     removeEntries(calendarId: number, externalIds: string[], now: number): Promise<number>;
     /**
-     * After a full list: entries not seen since `seenBefore` get `deleted_at`. Plain occurrences come only from the
-     * window fetched, so only those inside it count. Events, series and links stay.
+     * After a full list: entries not seen since `seenBefore` get `deleted_at`. A full list holds only what falls in the
+     * window, so only entries `entryInWindow` puts there count. Events, series and links stay.
      */
     markUnseen(calendarId: number, seenBefore: number, window: {
         from: number;
         to: number;
     }, now: number): Promise<number>;
+    /**
+     * Takes `deleted_at` off the entries a full list marked although they were outside the window it listed:
+     * `windowAt(deletedAt)` is the window of the list that marked one. Their events take their fields again. Returns how
+     * many came back.
+     */
+    restoreUnseen(calendarId: number, windowAt: (deletedAt: number) => {
+        from: number;
+        to: number;
+    }, now: number): Promise<number>;
     /**
      * Where the calendar's last sync stopped, as the sync engine wrote it (`{"v":1,"token":…,"window":…,"fullAt":…}`),
      * or `null` before the first one.
@@ -247,8 +274,34 @@ export interface EventStore {
     setCursor(calendarId: number, value: string | null, now: number): Promise<void>;
     /** One entry by the provider's id; a series, which no event holds, is found only this way. */
     entry(calendarId: number, externalId: string): Promise<StoredEntry | null>;
+    /**
+     * Several series' slots in the window and the sync cursor, in one transaction: a sync commits once for many series
+     * instead of twice for each. A series' slots replace its stored plain slots in the window (one it no longer has is
+     * cancelled, as `removeEntries` does); `slots: null` keeps them and counts them as seen now.
+     */
+    saveSlots(calendarId: number, groups: SeriesSlots[], window: {
+        from: number;
+        to: number;
+    }, cursor: string, now: number): Promise<{
+        saved: number;
+        removed: number;
+    }>;
+    /** The series' stored slots, moved ones too, whose original start falls in the window; deleted ones left out. */
+    slotsOf(calendarId: number, seriesExternalId: string, window: {
+        from: number;
+        to: number;
+    }): Promise<StoredEntry[]>;
     events(filter?: EventFilter): Promise<Event[]>;
     event(id: number): Promise<EventDetails | null>;
+    /** These events' copies on these calendars, deleted ones too, and their revisions since the instant, for `eventChange`. */
+    historyOf(eventIds: number[], calendarIds: number[], since: number): Promise<{
+        entries: StoredEntry[];
+        revisions: EntryRevision[];
+    }>;
+    /** The participants of these events' copies on these calendars, deleted copies too, as `event` gives them. */
+    participantsOf(eventIds: number[], calendarIds: number[]): Promise<(StoredParticipant & {
+        eventId: number;
+    })[]>;
     /** The owner's link of an entry to an event; no rule replaces it. */
     linkEntry(entryId: number, eventId: number, now: number): Promise<void>;
     /** The owner's unlink: the rules leave the entry alone after it. */
@@ -258,3 +311,28 @@ export interface EventStore {
     }): Promise<LinkReview[]>;
     resolveReview(id: number, decision: ReviewDecision, now: number): Promise<LinkReview>;
 }
+/**
+ * Whether a full list of the window would return the entry: a single or a moved slot by its own time, a plain slot by
+ * the time its series gave it, a series while it repeats into the window. An entry with no time is never counted.
+ */
+export declare const entryInWindow: (entry: Pick<StoredEntry, "kind" | "exception" | "startsAt" | "endsAt" | "originalStartsAt" | "recurrence" | "recurrenceEndsAt">, window: {
+    from: number;
+    to: number;
+}) => boolean;
+/** What happened to an event at or after an instant, from its copies: first stored, a new time, or cancelled. */
+export interface EventChange {
+    change: "new" | "moved" | "cancelled";
+    /** When the store saw it. */
+    at: number;
+    /** The time a moved event had at the instant. */
+    was?: {
+        startsAt: number | null;
+        endsAt: number | null;
+    };
+}
+/**
+ * The event's change since `since`, from its copies and their revisions (each revision holds the fields before one
+ * change): cancelled when the event is gone and a copy was cancelled or removed since; new when its first copy was
+ * stored since; moved when a live copy's time now differs from its time at `since`. `null` when none of these.
+ */
+export declare const eventChange: (event: Pick<Event, "status" | "sourceDeletedAt">, entries: readonly StoredEntry[], revisions: readonly EntryRevision[], since: number) => EventChange | null;