dsh-email 0.17.2 → 0.18.0

package/lib/types.d.ts

@@ -5,7 +5,7 @@ export interface AddressEntry {
 }
 /** One listed message: everything cheap to fetch without the body. */
 export interface ListedMessage {
-    uid: number;
+    uid: number | string;
     /** ISO 8601 string, or '' when unknown. */
     date: string;
     from: AddressEntry[];
@@ -36,6 +36,9 @@ export interface ReadMessageBody {
     truncated: boolean;
 }
 export interface EmailListResult {
+    countExact?: boolean;
+    hasMore?: boolean;
+    order?: 'relevance';
     account: string;
     count: number;
     folder: string;
@@ -45,22 +48,48 @@ export interface EmailListResult {
 }
 export interface EmailReadResult extends ReadMessageBody {
     account: string;
-    uid: number;
+    uid: number | string;
     folder: string;
+    uidValidity?: number;
+}
+export interface EmailSearchOptions {
+    /** Local header window; independent of result offset and bodySearchLimit. */
+    headerScanLimit?: number;
+    headerScanOffset?: number;
+}
+export interface EmailHeaderScan {
+    mailboxTotal: number;
+    scanned: number;
+    matched: number;
+    scanOffset: number;
+    scanLimit: number;
+    complete: boolean;
+    nextScanOffset?: number;
 }
 export interface EmailSearchResult {
+    countExact?: boolean;
+    hasMore?: boolean;
+    order?: 'relevance';
     account: string;
     query: string;
-    /** Server path: the server's match count. Fallback scan: this page's row count (see countKind). */
+    /** Server candidates, local header-window matches, or body-fallback page rows; inspect searchSource and coverage. */
     count: number;
     folder: string;
     /** How many newest matches the caller skipped (0 on the first page). */
     offset: number;
     messages: ListedMessage[];
-    /** Set to 'scanned' when the local body scan produced this page, so count is not a total. */
+    /** Local scans cannot claim a full mailbox/body match total. */
     countKind?: 'scanned';
-    /** How many newest messages the fallback scan looked at (set with countKind='scanned'). */
+    /** Header rows actually scanned, or the configured body window for legacy renderers. */
     scannedLimit?: number;
+    searchSource?: 'server' | 'local-headers' | 'local-body' | 'api';
+    serverMatchCount?: number;
+    serverSearchFailed?: boolean;
+    headerScan?: EmailHeaderScan;
+    bodyScan?: {
+        scanned: number;
+        scanLimit: number;
+    };
 }
 export interface EmailSendResult {
     account: string;
@@ -81,7 +110,7 @@ export interface EmailFoldersResult {
 }
 export interface EmailAttachmentResult {
     account: string;
-    uid: number;
+    uid: number | string;
     filename: string;
     contentType: string;
     size: number;
@@ -101,7 +130,7 @@ export interface EmailListArgs extends AccountArg {
     until?: string;
 }
 export interface EmailReadArgs extends AccountArg {
-    uid: number;
+    uid: number | string;
     folder?: string;
 }
 export interface EmailSearchArgs extends AccountArg {
@@ -111,6 +140,8 @@ export interface EmailSearchArgs extends AccountArg {
     offset?: number;
     since?: string;
     until?: string;
+    headerScanLimit?: number;
+    headerScanOffset?: number;
 }
 export interface EmailSendArgs extends AccountArg {
     to: string;
@@ -124,7 +155,7 @@ export interface EmailFoldersArgs extends AccountArg {
     subscribedOnly?: boolean;
 }
 export interface EmailAttachmentArgs extends AccountArg {
-    uid: number;
+    uid: number | string;
     /** 0-based index into the attachments of email_read. Default 0. */
     index?: number;
     folder?: string;
@@ -136,7 +167,7 @@ export interface EmailWatchArgs extends AccountArg {
 }
 export type EmailMarkAction = 'read' | 'unread' | 'star' | 'unstar' | 'move';
 export interface EmailMarkArgs extends AccountArg {
-    uid: number;
+    uid: number | string;
     action: EmailMarkAction;
     /** Target folder path; only used (and required) when action is 'move'. */
     toFolder?: string;
@@ -144,7 +175,7 @@ export interface EmailMarkArgs extends AccountArg {
 }
 export interface EmailMarkResult {
     account: string;
-    uid: number;
+    uid: number | string;
     folder: string;
     action: EmailMarkAction;
     seen: boolean;
@@ -156,7 +187,7 @@ export interface EmailMarkResult {
 }
 export type EmailReplyMode = 'reply' | 'reply-all' | 'forward';
 export interface EmailReplyArgs extends AccountArg {
-    uid: number;
+    uid: number | string;
     /** The new text to write; the original is quoted below it automatically. */
     text: string;
     mode?: EmailReplyMode;
@@ -169,7 +200,7 @@ export interface EmailReplyResult {
     account: string;
     mode: EmailReplyMode;
     /** uid of the original message that was answered/forwarded. */
-    originalUid: number;
+    originalUid: number | string;
     messageId: string;
     accepted: string[];
     rejected: string[];
@@ -178,6 +209,7 @@ export interface EmailReplyResult {
     subject: string;
 }
 export interface EmailWatchResult {
+    totalUnreadExact?: boolean;
     account: string;
     folder: string;
     /** True on the first call for this account+folder: it sets the baseline. */

package/lib/web.d.ts

@@ -175,7 +175,8 @@ export declare class EmailSettingsBackend {
     private readonly ctx;
     private readonly scope;
     private readonly rowConfig;
-    constructor(ctx: any, scope: any, rowConfig: EmailConfig);
+    private readonly apiFetch?;
+    constructor(ctx: any, scope: any, rowConfig: EmailConfig, apiFetch?: typeof fetch | undefined);
     /** Wired by apply(): the email_watch core; 'web' keeps its own cursor scope. */
     watchImpl?: (account: string, folder: string, limit: number, scope: string) => Promise<EmailWatchResult>;
     private get namespace();
@@ -262,11 +263,18 @@ export declare class EmailSettingsBackend {
      * what was actually tried — including on failure.
      */
     test(value: EmailSettingsValue, accountName?: string): Promise<{
+        ok: boolean;
+        account: string;
+        apiHost: "https://api.agentmail.to" | "https://api.agentmail.eu" | undefined;
+        message: string;
+    } | {
         account: string;
         imapHost: string;
         imapPort: number;
         ok: boolean;
         ms: number;
+        apiHost?: undefined;
+        message?: undefined;
     }>;
     /**
      * Resolve one named account of the *stored* settings — the same accounts the

package/lib/web.js

@@ -6,6 +6,7 @@ import { SETTINGS_NAMESPACE, toEmailConfig, validateSettingsValue } from './sett
 import { isOAuth2Account, OUTLOOK_OAUTH2_CLIENT_ID, parseAccountsYaml, parseServerPresets, presetNamesIn, PROVIDER_PRESETS, resolveEmailSettings, serializeAccountsYaml, } from './config.js';
 import { clearTokenFor, getFreshAccessToken, oauth2StateOf, pollDeviceFlow, startDeviceFlow, } from './oauth2.js';
 import { EmailPool, messageOf, redactCredentials } from './mail-client.js';
+import { AgentMailClient } from './agentmail.js';
 /** Same-origin route the browser settings section talks to. */
 export const SETTINGS_ROUTE = '/_dsh/dsh-email/settings';
 /** Same-origin route serving the whale-girl courier image to the widget. */
@@ -98,7 +99,7 @@ function buildAccountCards(raw, defaultAccount, presets, tokens = () => ({ state
             provider: providerName,
             ...(preset?.label !== undefined && preset.label !== '' ? { providerLabel: preset.label } : {}),
             user,
-            hasPassword: typeof account.password === 'string' && account.password !== '',
+            hasPassword: typeof account.password === 'string' && account.password !== '' || typeof account.apiKey === 'string' && account.apiKey !== '',
             authKind,
             ...(pinned === 'oauth2' || pinned === 'password' ? { authKindDeclared: pinned } : {}),
             ...(clientId !== '' ? { clientId } : {}),
@@ -308,6 +309,8 @@ function washEndpoint(account, key) {
 function persistedProvider(provider, customNames) {
     if (typeof provider !== 'string' || provider === '')
         return undefined;
+    if (provider === 'agentmail' || provider === 'agentmail-eu')
+        return provider;
     if (Object.prototype.hasOwnProperty.call(PROVIDER_PRESETS, provider))
         return provider;
     return customNames.has(provider) ? provider : undefined;
@@ -520,6 +523,15 @@ function serializeAccountsDraft(source, cards, defaultAccount, customNames) {
         // never written — a stored copy is washed out below instead.
         const previousProvider = account.get('provider');
         const nextProvider = persistedProvider(card.provider, customNames);
+        const apiProvider = (value) => value === 'agentmail' || value === 'agentmail-eu';
+        if (apiProvider(previousProvider) !== apiProvider(nextProvider)) {
+            account.delete('password');
+            account.delete('apiKey');
+            account.delete('authPassword');
+            account.delete('authKind');
+        }
+        if (card.password !== undefined && apiProvider(nextProvider))
+            account.delete('apiKey');
         writeField(account, 'provider', nextProvider);
         writeField(account, 'user', card.user);
         // senderName / authUser are plain three-state fields (undefined = 保持原样,
@@ -749,10 +761,12 @@ export class EmailSettingsBackend {
     ctx;
     scope;
     rowConfig;
-    constructor(ctx, scope, rowConfig) {
+    apiFetch;
+    constructor(ctx, scope, rowConfig, apiFetch) {
         this.ctx = ctx;
         this.scope = scope;
         this.rowConfig = rowConfig;
+        this.apiFetch = apiFetch;
     }
     /** Wired by apply(): the email_watch core; 'web' keeps its own cursor scope. */
     watchImpl;
@@ -886,6 +900,10 @@ export class EmailSettingsBackend {
         if (cfg === undefined) {
             throw new Error(`未知账号 "${name}"，可用：${available.join('、')}`);
         }
+        if (cfg.transport === 'agentmail') {
+            await new AgentMailClient(settings, this.apiFetch).test(name);
+            return { ok: true, account: name, apiHost: cfg.apiBase, message: 'AgentMail API 连接成功 / AgentMail API connection successful' };
+        }
         const target = { account: name, imapHost: cfg.imap.host, imapPort: cfg.imap.port };
         const targetDescription = '账号 "' + name + '" · IMAP ' + cfg.imap.host + ':' + cfg.imap.port;
         // An OAuth2 account has no password to check: without a token there is

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-email",
-  "version": "0.17.2",
-  "description": "在 DSH 中收发、搜索和整理邮件，支持多个邮箱账号。",
+  "version": "0.18.0",
+  "description": "在 DSH 中浏览、收发、搜索和整理邮件，支持 IMAP/SMTP 与 AgentMail 多账号。",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -34,7 +34,8 @@
     "dsh",
     "email",
     "imap",
-    "smtp"
+    "smtp",
+    "agentmail"
   ],
   "author": "stardustlc",
   "repository": {