react-native-email-imap-smtp 0.3.28 → 0.3.29

package/src/index.tsx

@@ -8,6 +8,14 @@
 // ============================================================
 
 const { Platform } = require('react-native');
+const {
+  logAttachmentWarnings,
+  logWarning,
+  logInfo,
+  logError,
+  setLogHandler,
+  getLogHandler,
+} = require('./log');
 
 // ─── Platform-aware module resolution ──────────────────────
 
@@ -94,13 +102,26 @@ module.exports = {
     uids: number[]
   ) => Promise<import('./types').BatchResult>,
   imapExpunge: impl.imapExpunge as () => Promise<void>,
-  imapFetchAttachments: impl.imapFetchAttachments as (
+  imapFetchAttachments: (async (
+    uid: number,
+    partId: string
+  ): Promise<import('./types').Attachment | null> => {
+    const att = await impl.imapFetchAttachments(uid, partId);
+    if (att?.integrityWarning) {
+      logWarning(`附件完整性告警: ${att.filename} — ${att.integrityWarning}`);
+    }
+    return att;
+  }) as (
     uid: number,
     partId: string
   ) => Promise<import('./types').Attachment | null>,
-  imapFetchAllAttachments: impl.imapFetchAllAttachments as (
+  imapFetchAllAttachments: (async (
     uid: number
-  ) => Promise<import('./types').Attachment[]>,
+  ): Promise<import('./types').Attachment[]> => {
+    const atts = await impl.imapFetchAllAttachments(uid);
+    logAttachmentWarnings(atts);
+    return atts;
+  }) as (uid: number) => Promise<import('./types').Attachment[]>,
   imapIdle: impl.imapIdle as (
     callback: (notification: import('./types').IMAPNotification) => void
   ) => Promise<void>,
@@ -143,4 +164,19 @@ module.exports = {
    */
   SmtpNotConnectedError: impl.SmtpNotConnectedError as
     (new () => Error) | undefined,
+
+  // ─── 公共日志工具（所有平台可用） ─────────────────────────
+
+  /** 打印普通提示 */
+  logInfo,
+  /** 打印告警（Web 端=控制台 warn，原生端=调试输出） */
+  logWarning,
+  /** 打印错误 */
+  logError,
+  /** 批量打印一批附件的完整性告警 */
+  logAttachmentWarnings,
+  /** 自定义日志处理器（传 null 恢复默认 console 输出） */
+  setLogHandler,
+  /** 获取当前日志处理器 */
+  getLogHandler,
 };

package/src/log.ts

@@ -0,0 +1,83 @@
+// ============================================================
+// 公共日志工具
+// ============================================================
+//
+// 统一所有需要向「使用方应用」输出提示/告警/错误的打印入口。
+// 默认使用 console.*（RN 的 console 会自动桥接到原生调试输出：
+// Android Logcat / iOS Xcode console / Windows Debug 输出）。
+//
+// 使用方可通过 setLogHandler() 自定义打印目标（例如接入自己的
+// 日志系统、把 warn 转发到业务 UI 等）。
+//
+// 用法：
+//   import { logWarning } from 'react-native-email-imap-smtp';
+//   logWarning('附件大小异常', detail);
+// ============================================================
+
+export type LogLevel = 'info' | 'warn' | 'error';
+
+/** 自定义日志处理函数签名 */
+export type LogHandler = (
+  level: LogLevel,
+  message: string,
+  data?: unknown
+) => void;
+
+/** 默认处理器：走 console，RN 会自动桥接到原生调试输出 */
+const defaultHandler: LogHandler = (level, message, data) => {
+  const prefix = '[email-imap-smtp]';
+  switch (level) {
+    case 'warn':
+      console.warn(prefix, message, data !== undefined ? data : '');
+      break;
+    case 'error':
+      console.error(prefix, message, data !== undefined ? data : '');
+      break;
+    default:
+      console.log(prefix, message, data !== undefined ? data : '');
+  }
+};
+
+let handler: LogHandler = defaultHandler;
+
+/**
+ * 自定义日志处理器。
+ * 传 `null` 或省略可恢复默认的 console 输出。
+ */
+export function setLogHandler(next?: LogHandler | null): void {
+  handler = next || defaultHandler;
+}
+
+/** 获取当前日志处理器（默认是 console 版） */
+export function getLogHandler(): LogHandler {
+  return handler;
+}
+
+/** 打印普通提示 */
+export function logInfo(message: string, data?: unknown): void {
+  handler('info', message, data);
+}
+
+/** 打印告警（Web 端=控制台 warn，原生端=调试输出） */
+export function logWarning(message: string, data?: unknown): void {
+  handler('warn', message, data);
+}
+
+/** 打印错误 */
+export function logError(message: string, data?: unknown): void {
+  handler('error', message, data);
+}
+
+/** 便捷方法：批量打印一批附件的完整性告警 */
+export function logAttachmentWarnings(
+  attachments: Array<{ filename?: string; integrityWarning?: string }>
+): void {
+  if (!attachments || !attachments.length) return;
+  for (const att of attachments) {
+    if (att.integrityWarning) {
+      logWarning(
+        `附件完整性告警: ${att.filename ?? ''} — ${att.integrityWarning}`
+      );
+    }
+  }
+}

package/src/types.ts

@@ -264,6 +264,13 @@ export interface Attachment {
   contentDisposition: string;
   /** 附件在本地缓存的文件路径（大附件避免全部加载到内存） */
   localPath?: string;
+  /**
+   * 完整性校验告警（可选）。
+   * 仅当服务器声明的附件大小与实际下载字节数不一致时存在，
+   * 例如 `'附件大小与服务器声明不符: xxx'` 或 `'附件疑似截断: xxx'`。
+   * 正常下载的附件不包含此字段。
+   */
+  integrityWarning?: string;
 }
 
 /**