@diskd-ai/email-client-mcp 0.1.21 → 0.1.23

package/dist/store/payloadTypes.d.ts

@@ -11,14 +11,18 @@ export type EmailAddress = {
     readonly name: string | null;
     readonly address: string;
 };
+export type BodyState = "not_loaded" | "loading" | "loaded" | "failed_retryable" | "failed_permanent";
+export type AttachmentStorageState = "not_loaded" | "loading" | "loaded" | "failed_retryable" | "failed_permanent";
 export type StoredAttachment = {
     readonly filename: string;
     readonly contentType: string;
     readonly sizeBytes: number;
     readonly partId: string;
     readonly attachmentId?: string;
+    readonly storageState?: AttachmentStorageState;
     readonly storedSizeBytes?: number;
     readonly storedAt?: string;
+    readonly lastLoadError?: string;
 };
 export type StoredEmailPayload = {
     readonly accountId: string;
@@ -41,6 +45,9 @@ export type StoredEmailPayload = {
     readonly bodyText: string | null;
     readonly bodyHtml: string | null;
     readonly truncated: boolean;
+    readonly bodyState?: BodyState;
+    readonly bodyFetchedAt?: string | null;
+    readonly bodyFetchError?: string | null;
     readonly fetchedAt: string;
 };
 /**
@@ -50,14 +57,20 @@ export type StoredEmailPayload = {
  *  - `uidValidity`: snapshot of last seen UIDVALIDITY; mismatch triggers
  *    a full folder drop+resync.
  *  - `uidNext`: snapshot of last seen UIDNEXT; the head of the sync window.
- *  - `lastSyncedUid`: highest UID confirmed written via successful upsert.
- *    `runSyncOnce` advances this only after a batch upsert returns Ok.
+ *  - `forwardSyncedUid`: highest UID confirmed written for the new-mail
+ *    forward cursor.
+ *  - `backfillBeforeUid`: lowest UID covered by historical backfill. A
+ *    non-null value means older messages below this UID are still pending.
+ *  - `lastSyncedUid`: compatibility mirror of `forwardSyncedUid` for old
+ *    metadata readers and old folder states.
  *  - `lastSyncStartedAt` / `lastSyncFinishedAt` / `lastSyncError`:
  *    diagnostic snapshot exposed via `get_watcher_status`.
  */
 export type SyncState = {
     readonly uidValidity: number;
     readonly uidNext: number;
+    readonly forwardSyncedUid: number;
+    readonly backfillBeforeUid: number | null;
     readonly lastSyncedUid: number;
     readonly lastSyncStartedAt: string | null;
     readonly lastSyncFinishedAt: string | null;

package/dist/sync/attachmentHydration.d.ts

@@ -0,0 +1,44 @@
+import { type AppError } from "../domain/errors.js";
+import { type Result } from "../domain/result.js";
+import { type UploadAttachmentResult } from "../store/attachments.js";
+import type { StoredAttachment, StoredEmailPayload } from "../store/payloadTypes.js";
+export type AttachmentHydrationRef = {
+    readonly mailboxId: string;
+    readonly folderId: string;
+    readonly externalId: string;
+    readonly attachmentId: string;
+};
+export type AttachmentHydrationDeps = {
+    readonly drive: {
+        readonly getMessage: (mailboxId: string, folderId: string, externalId: string) => Promise<Result<AppError, StoredEmailPayload | null>>;
+        readonly upsertMessages: (mailboxId: string, folderId: string, payloads: readonly StoredEmailPayload[], externalIds: readonly string[]) => Promise<Result<AppError, {
+            inserted: number;
+            updated: number;
+        }>>;
+        readonly uploadAttachment: (mailboxId: string, folderId: string, externalId: string, attachment: StoredAttachment & {
+            readonly attachmentId: string;
+        }, content: AsyncIterable<Uint8Array>) => Promise<Result<AppError, UploadAttachmentResult>>;
+    };
+    readonly imap: {
+        readonly downloadPart: (accountId: string, mailbox: string, uid: number, partId: string) => Promise<{
+            readonly content: AsyncIterable<Uint8Array>;
+            readonly sizeBytes: number | null;
+            readonly contentType: string | null;
+            readonly dispose: () => void;
+        }>;
+    };
+};
+export type AttachmentHydrationStatus = "loaded" | "skipped" | "failed_retryable" | "failed_permanent";
+export type AttachmentHydrationOutcome = {
+    readonly status: AttachmentHydrationStatus;
+    readonly mailboxId: string;
+    readonly folderId: string;
+    readonly externalId: string;
+    readonly attachmentId: string;
+    readonly attachment: StoredAttachment | null;
+    readonly payload: StoredEmailPayload;
+    readonly error: string | null;
+};
+export declare const hydrateStoredMessageAttachment: (deps: AttachmentHydrationDeps, ref: AttachmentHydrationRef, options?: {
+    readonly refresh?: boolean;
+}) => Promise<Result<AppError, AttachmentHydrationOutcome>>;

package/dist/sync/attachmentHydration.js

@@ -0,0 +1,118 @@
+import { errorMessage, isRetryableImapError, notFound } from "../domain/errors.js";
+import { Err, Ok } from "../domain/result.js";
+import { attachmentIdFor } from "../store/attachments.js";
+const resolvedAttachmentId = (payload, attachment) => attachment.attachmentId ?? attachmentIdFor(payload.uidValidity, payload.uid, attachment.partId);
+const findAttachment = (payload, attachmentId) => payload.attachments.find((attachment) => resolvedAttachmentId(payload, attachment) === attachmentId) ?? null;
+const patchAttachment = (payload, attachmentId, patch) => {
+    let patchedAttachment = null;
+    const attachments = payload.attachments.map((attachment) => {
+        const nextAttachment = {
+            ...attachment,
+            attachmentId: resolvedAttachmentId(payload, attachment),
+        };
+        if (nextAttachment.attachmentId !== attachmentId)
+            return nextAttachment;
+        patchedAttachment = patch(nextAttachment);
+        return patchedAttachment;
+    });
+    return { payload: { ...payload, attachments }, attachment: patchedAttachment };
+};
+const patchLoaded = (payload, attachmentId, uploaded) => patchAttachment(payload, attachmentId, (attachment) => {
+    const { lastLoadError: _lastLoadError, ...rest } = attachment;
+    return {
+        ...rest,
+        storageState: "loaded",
+        storedSizeBytes: uploaded.storedSizeBytes,
+        storedAt: uploaded.storedAt,
+    };
+});
+const patchFailed = (payload, attachmentId, status, message) => patchAttachment(payload, attachmentId, (attachment) => ({
+    ...attachment,
+    storageState: status,
+    lastLoadError: message,
+}));
+const persist = async (deps, ref, payload) => {
+    const upsert = await deps.drive.upsertMessages(ref.mailboxId, ref.folderId, [payload], [ref.externalId]);
+    if (upsert.tag === "Err")
+        return upsert;
+    return Ok(payload);
+};
+const isRetryableAppFailure = (cause) => isRetryableImapError(cause);
+const outcome = (ref, payload, status, attachment, error) => ({
+    status,
+    mailboxId: ref.mailboxId,
+    folderId: ref.folderId,
+    externalId: ref.externalId,
+    attachmentId: ref.attachmentId,
+    attachment,
+    payload,
+    error,
+});
+export const hydrateStoredMessageAttachment = async (deps, ref, options) => {
+    const existing = await deps.drive.getMessage(ref.mailboxId, ref.folderId, ref.externalId);
+    if (existing.tag === "Err")
+        return existing;
+    if (existing.value === null)
+        return Err(notFound(`message ${ref.externalId}`));
+    const payload = existing.value;
+    const attachment = findAttachment(payload, ref.attachmentId);
+    if (attachment === null) {
+        return Ok(outcome(ref, payload, "failed_permanent", null, `attachment not found: ${ref.attachmentId}`));
+    }
+    const attachmentWithId = {
+        ...attachment,
+        attachmentId: resolvedAttachmentId(payload, attachment),
+    };
+    if (attachmentWithId.storageState === "loaded" && options?.refresh !== true) {
+        return Ok(outcome(ref, payload, "skipped", attachmentWithId, null));
+    }
+    if (attachmentWithId.partId.length === 0) {
+        const message = `attachment partId is missing: ${ref.attachmentId}`;
+        const patched = patchFailed(payload, ref.attachmentId, "failed_permanent", message);
+        const persisted = await persist(deps, ref, patched.payload);
+        if (persisted.tag === "Err")
+            return persisted;
+        return Ok(outcome(ref, persisted.value, "failed_permanent", patched.attachment, message));
+    }
+    let downloaded;
+    try {
+        downloaded = await deps.imap.downloadPart(payload.accountId, payload.mailbox, payload.uid, attachmentWithId.partId);
+    }
+    catch (cause) {
+        const message = cause?.message ?? String(cause);
+        const status = isRetryableAppFailure(cause) ? "failed_retryable" : "failed_permanent";
+        const patched = patchFailed(payload, ref.attachmentId, status, message);
+        const persisted = await persist(deps, ref, patched.payload);
+        if (persisted.tag === "Err")
+            return persisted;
+        return Ok(outcome(ref, persisted.value, status, patched.attachment, message));
+    }
+    const uploadAttachment = {
+        ...attachmentWithId,
+        sizeBytes: downloaded.sizeBytes ?? attachmentWithId.sizeBytes,
+        contentType: downloaded.contentType ?? attachmentWithId.contentType,
+    };
+    const uploaded = await (async () => {
+        try {
+            return await deps.drive.uploadAttachment(ref.mailboxId, ref.folderId, ref.externalId, uploadAttachment, downloaded.content);
+        }
+        finally {
+            downloaded.dispose();
+        }
+    })();
+    if (uploaded.tag === "Err") {
+        const message = errorMessage(uploaded.error);
+        const status = isRetryableAppFailure(message) ? "failed_retryable" : "failed_permanent";
+        const patched = patchFailed(payload, ref.attachmentId, status, message);
+        const persisted = await persist(deps, ref, patched.payload);
+        if (persisted.tag === "Err")
+            return persisted;
+        return Ok(outcome(ref, persisted.value, status, patched.attachment, message));
+    }
+    const patched = patchLoaded(payload, ref.attachmentId, uploaded.value);
+    const persisted = await persist(deps, ref, patched.payload);
+    if (persisted.tag === "Err")
+        return persisted;
+    return Ok(outcome(ref, persisted.value, "loaded", patched.attachment, null));
+};
+//# sourceMappingURL=attachmentHydration.js.map

package/dist/sync/attachmentHydration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachmentHydration.js","sourceRoot":"","sources":["../../src/sync/attachmentHydration.ts"],"names":[],"mappings":"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"}

package/dist/sync/bodyHydration.d.ts

@@ -0,0 +1,52 @@
+import { type AppError, type ImapError } from "../domain/errors.js";
+import { type Result } from "../domain/result.js";
+import type { StoredEmailPayload } from "../store/payloadTypes.js";
+export type FetchedBodyContent = {
+    readonly bodyText: string | null;
+    readonly bodyHtml: string | null;
+    readonly truncated: boolean;
+    readonly bytesRead: number;
+};
+export type BodyHydrationRef = {
+    readonly mailboxId: string;
+    readonly folderId: string;
+    readonly externalId: string;
+};
+export type BodyHydrationDeps = {
+    readonly drive: {
+        readonly getMessage: (mailboxId: string, folderId: string, externalId: string) => Promise<Result<AppError, StoredEmailPayload | null>>;
+        readonly upsertMessages: (mailboxId: string, folderId: string, payloads: readonly StoredEmailPayload[], externalIds: readonly string[]) => Promise<Result<AppError, {
+            inserted: number;
+            updated: number;
+        }>>;
+    };
+    readonly imap: {
+        readonly fetchBody: (accountId: string, mailbox: string, uid: number) => Promise<Result<ImapError, FetchedBodyContent | null>>;
+    };
+    readonly now: () => Date;
+};
+export type BodyHydrationStatus = "loaded" | "skipped" | "failed_retryable" | "failed_permanent";
+export type BodyHydrationOutcome = {
+    readonly status: BodyHydrationStatus;
+    readonly payload: StoredEmailPayload;
+    readonly error: string | null;
+};
+export type BodyHydrationBatchItem = BodyHydrationOutcome & {
+    readonly ref: BodyHydrationRef;
+};
+export type BodyHydrationBatchResult = {
+    readonly loaded: readonly BodyHydrationBatchItem[];
+    readonly skipped: readonly BodyHydrationBatchItem[];
+    readonly failedRetryable: readonly BodyHydrationBatchItem[];
+    readonly failedPermanent: readonly BodyHydrationBatchItem[];
+};
+export declare const markBodyLoaded: (payload: StoredEmailPayload, body: FetchedBodyContent, now: Date) => StoredEmailPayload;
+export declare const markBodyFailedRetryable: (payload: StoredEmailPayload, error: string, now: Date) => StoredEmailPayload;
+export declare const markBodyFailedPermanent: (payload: StoredEmailPayload, error: string, now: Date) => StoredEmailPayload;
+export declare const hydrateStoredMessageBody: (deps: BodyHydrationDeps, ref: BodyHydrationRef, options?: {
+    readonly refresh?: boolean;
+}) => Promise<Result<AppError, BodyHydrationOutcome>>;
+export declare const hydrateStoredMessageBodies: (deps: BodyHydrationDeps, refs: readonly BodyHydrationRef[], options?: {
+    readonly refresh?: boolean;
+    readonly maxMessages?: number;
+}) => Promise<Result<AppError, BodyHydrationBatchResult>>;

package/dist/sync/bodyHydration.js

@@ -0,0 +1,103 @@
+import { errorMessage, isRetryableImapError, notFound, } from "../domain/errors.js";
+import { Err, Ok } from "../domain/result.js";
+import { htmlToText } from "../imap/mapper.js";
+const buildSnippet = (bodyText, bodyHtml) => {
+    const text = bodyText ?? (bodyHtml !== null ? htmlToText(bodyHtml) : null);
+    if (text === null)
+        return "";
+    return text.replace(/\s+/g, " ").trim().slice(0, 200);
+};
+const messageHasLoadedBody = (payload) => payload.bodyState === "loaded" ||
+    (payload.bodyState === undefined && (payload.bodyText !== null || payload.bodyHtml !== null));
+export const markBodyLoaded = (payload, body, now) => ({
+    ...payload,
+    snippet: buildSnippet(body.bodyText, body.bodyHtml),
+    bodyText: body.bodyText,
+    bodyHtml: body.bodyHtml,
+    truncated: payload.truncated || body.truncated,
+    bodyState: "loaded",
+    bodyFetchedAt: now.toISOString(),
+    bodyFetchError: null,
+});
+export const markBodyFailedRetryable = (payload, error, now) => ({
+    ...payload,
+    bodyState: "failed_retryable",
+    bodyFetchedAt: now.toISOString(),
+    bodyFetchError: error,
+});
+export const markBodyFailedPermanent = (payload, error, now) => ({
+    ...payload,
+    bodyState: "failed_permanent",
+    bodyFetchedAt: now.toISOString(),
+    bodyFetchError: error,
+});
+const persistBodyState = async (deps, ref, payload) => {
+    const upsert = await deps.drive.upsertMessages(ref.mailboxId, ref.folderId, [payload], [ref.externalId]);
+    if (upsert.tag === "Err")
+        return upsert;
+    return Ok(payload);
+};
+const imapFailureIsRetryable = (error) => isRetryableImapError(error.message) || isRetryableImapError(error.cause);
+export const hydrateStoredMessageBody = async (deps, ref, options) => {
+    const existing = await deps.drive.getMessage(ref.mailboxId, ref.folderId, ref.externalId);
+    if (existing.tag === "Err")
+        return existing;
+    if (existing.value === null)
+        return Err(notFound(`message ${ref.externalId}`));
+    const payload = existing.value;
+    if (options?.refresh !== true && messageHasLoadedBody(payload)) {
+        return Ok({ status: "skipped", payload, error: null });
+    }
+    const fetched = await deps.imap.fetchBody(payload.accountId, payload.mailbox, payload.uid);
+    if (fetched.tag === "Err") {
+        const message = errorMessage(fetched.error);
+        const patched = imapFailureIsRetryable(fetched.error)
+            ? markBodyFailedRetryable(payload, message, deps.now())
+            : markBodyFailedPermanent(payload, message, deps.now());
+        const persisted = await persistBodyState(deps, ref, patched);
+        if (persisted.tag === "Err")
+            return persisted;
+        return Ok({
+            status: imapFailureIsRetryable(fetched.error) ? "failed_retryable" : "failed_permanent",
+            payload: persisted.value,
+            error: message,
+        });
+    }
+    if (fetched.value === null) {
+        const message = `message body not found: ${ref.externalId}`;
+        const patched = markBodyFailedPermanent(payload, message, deps.now());
+        const persisted = await persistBodyState(deps, ref, patched);
+        if (persisted.tag === "Err")
+            return persisted;
+        return Ok({ status: "failed_permanent", payload: persisted.value, error: message });
+    }
+    const patched = markBodyLoaded(payload, fetched.value, deps.now());
+    const persisted = await persistBodyState(deps, ref, patched);
+    if (persisted.tag === "Err")
+        return persisted;
+    return Ok({ status: "loaded", payload: persisted.value, error: null });
+};
+export const hydrateStoredMessageBodies = async (deps, refs, options) => {
+    const maxMessages = options?.maxMessages ?? refs.length;
+    const selectedRefs = refs.slice(0, Math.max(0, maxMessages));
+    const loaded = [];
+    const skipped = [];
+    const failedRetryable = [];
+    const failedPermanent = [];
+    for (const ref of selectedRefs) {
+        const result = await hydrateStoredMessageBody(deps, ref, { refresh: options?.refresh });
+        if (result.tag === "Err")
+            return result;
+        const item = { ...result.value, ref };
+        if (item.status === "loaded")
+            loaded.push(item);
+        else if (item.status === "skipped")
+            skipped.push(item);
+        else if (item.status === "failed_retryable")
+            failedRetryable.push(item);
+        else
+            failedPermanent.push(item);
+    }
+    return Ok({ loaded, skipped, failedRetryable, failedPermanent });
+};
+//# sourceMappingURL=bodyHydration.js.map

package/dist/sync/bodyHydration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bodyHydration.js","sourceRoot":"","sources":["../../src/sync/bodyHydration.ts"],"names":[],"mappings":"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"}

package/dist/sync/sync.d.ts

@@ -21,7 +21,7 @@ import { type Account, type WatcherSettings } from "../config/schema.js";
 import { type AppError, type ImapError } from "../domain/errors.js";
 import { type Result } from "../domain/result.js";
 import { type FetchedMessageLike } from "../imap/mapper.js";
-import { type UploadAttachmentResult } from "../store/attachments.js";
+import type { UploadAttachmentResult } from "../store/attachments.js";
 import type { StoredAttachment, StoredEmailPayload, SyncState } from "../store/payloadTypes.js";
 export type SyncDeps = {
     readonly drive: {
@@ -56,12 +56,14 @@ export type SyncDeps = {
             uidNext: number;
             messages: number;
         }>>;
-        readonly fetchRange: (accountId: string, path: string, fromUid: number, toUid: number) => AsyncIterable<{
-            readonly imapMessage: FetchedMessageLike;
+        readonly fetchMetadataRange: (accountId: string, path: string, fromUid: number, toUid: number) => AsyncIterable<FetchedMessageLike>;
+        readonly fetchEnvelopesRange: (accountId: string, path: string, fromUid: number, toUid: number) => AsyncIterable<FetchedMessageLike>;
+        readonly fetchBody: (accountId: string, mailbox: string, uid: number) => Promise<Result<ImapError, {
             readonly bodyText: string | null;
             readonly bodyHtml: string | null;
-        }>;
-        readonly fetchEnvelopesRange: (accountId: string, path: string, fromUid: number, toUid: number) => AsyncIterable<FetchedMessageLike>;
+            readonly truncated: boolean;
+            readonly bytesRead: number;
+        } | null>>;
         readonly downloadPart: (accountId: string, path: string, uid: number, partId: string) => Promise<{
             readonly content: AsyncIterable<Uint8Array>;
             readonly sizeBytes: number | null;
@@ -74,8 +76,15 @@ export type SyncDeps = {
 export type SyncFolderReport = {
     readonly folderId: string;
     readonly newMessages: number;
+    readonly forwardMessages?: number;
+    readonly backfilledMessages?: number;
     readonly reconciledFlags: number;
+    readonly hydratedBodies: number;
+    readonly bodyHydrationErrors: number;
     readonly uidValidityRolled: boolean;
+    readonly forwardSyncedUid?: number | null;
+    readonly backfillBeforeUid?: number | null;
+    readonly backfillComplete?: boolean;
     readonly error: string | null;
 };
 export type SyncReport = {