tempmail-sdk 1.1.8 → 1.2.0

package/src/providers/tempmail-cn.ts

@@ -0,0 +1,376 @@
+import WebSocket from 'ws';
+import { InternalEmailInfo, Email, Channel } from '../types';
+import { normalizeEmail } from '../normalize';
+
+const CHANNEL: Channel = 'tempmail-cn';
+const DEFAULT_HOST = 'tempmail.cn';
+const CONNECT_TIMEOUT_MS = 15000;
+const HANDSHAKE_WAIT_MS = 1000;
+const INITIAL_SYNC_WAIT_MS = 80;
+const SOCKET_IO_VERSIONS = [4, 3];
+
+const DEFAULT_HEADERS: Record<string, string> = {
+  'User-Agent':
+    'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36 Edg/146.0.0.0',
+  'Accept-Language': 'zh-CN,zh;q=0.9,en;q=0.8,en-GB;q=0.7,en-US;q=0.6',
+  'Cache-Control': 'no-cache',
+  DNT: '1',
+  Pragma: 'no-cache',
+};
+
+type BoxState = {
+  emails: Email[];
+  seenIds: Set<string>;
+  ws: WebSocket | null;
+  connectPromise?: Promise<void>;
+};
+
+const mailboxes = new Map<string, BoxState>();
+
+function getState(email: string): BoxState {
+  const key = email.trim().toLowerCase();
+  let st = mailboxes.get(key);
+  if (!st) {
+    st = { emails: [], seenIds: new Set(), ws: null };
+    mailboxes.set(key, st);
+  }
+  return st;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function normalizeHost(domain?: string | null): string {
+  const raw = String(domain || '').trim();
+  if (!raw) {
+    return DEFAULT_HOST;
+  }
+
+  let host = raw;
+  if (/^https?:\/\//i.test(host)) {
+    try {
+      host = new URL(host).host;
+    } catch {
+      host = raw;
+    }
+  } else if (host.includes('/')) {
+    try {
+      host = new URL(`https://${host}`).host;
+    } catch {
+      host = host.split('/')[0];
+    }
+  }
+
+  host = host.replace(/^\.+|\.+$/g, '');
+  const at = host.lastIndexOf('@');
+  if (at >= 0) {
+    host = host.slice(at + 1);
+  }
+  return host || DEFAULT_HOST;
+}
+
+function splitAddress(email: string): { local: string; host: string } {
+  const trimmed = email.trim();
+  const at = trimmed.indexOf('@');
+  if (at <= 0 || at === trimmed.length - 1) {
+    throw new Error('tempmail-cn: invalid email address');
+  }
+  return {
+    local: trimmed.slice(0, at),
+    host: normalizeHost(trimmed.slice(at + 1)),
+  };
+}
+
+function socketUrl(host: string, eio: number): string {
+  return `wss://${host}/socket.io/?EIO=${eio}&transport=websocket`;
+}
+
+function socketHeaders(host: string): Record<string, string> {
+  return {
+    ...DEFAULT_HEADERS,
+    Origin: `https://${host}`,
+    Referer: `https://${host}/`,
+  };
+}
+
+function sendEvent(ws: WebSocket, event: string, payload: unknown): void {
+  ws.send(`42${JSON.stringify([event, payload])}`);
+}
+
+function parseEventPacket(packet: string): { event: string; payload: any } | null {
+  if (!packet.startsWith('42')) {
+    return null;
+  }
+  try {
+    const decoded = JSON.parse(packet.slice(2));
+    if (!Array.isArray(decoded) || typeof decoded[0] !== 'string') {
+      return null;
+    }
+    return { event: decoded[0], payload: decoded[1] };
+  } catch {
+    return null;
+  }
+}
+
+function stableMessageId(raw: any, recipientEmail: string): string {
+  const headers = raw?.headers || {};
+  return String(
+    raw?.id ??
+      raw?.messageId ??
+      headers['message-id'] ??
+      headers.messageId ??
+      `${headers.from || raw?.from || ''}\n${headers.subject || raw?.subject || ''}\n${headers.date || raw?.date || ''}\n${recipientEmail}`,
+  );
+}
+
+function flattenMail(raw: any, recipientEmail: string): any {
+  const headers = raw?.headers || {};
+  return {
+    id: stableMessageId(raw, recipientEmail),
+    from: headers.from || raw?.from || '',
+    to: recipientEmail,
+    subject: headers.subject || raw?.subject || '',
+    text: raw?.text || raw?.body || '',
+    html: raw?.html || '',
+    date: headers.date || raw?.date || '',
+    isRead: false,
+    attachments: Array.isArray(raw?.attachments) ? raw.attachments : [],
+  };
+}
+
+async function connectSocket(host: string): Promise<WebSocket> {
+  let lastError: Error | null = null;
+
+  for (const version of SOCKET_IO_VERSIONS) {
+    try {
+      return await new Promise<WebSocket>((resolve, reject) => {
+        const ws = new WebSocket(socketUrl(host, version), {
+          handshakeTimeout: CONNECT_TIMEOUT_MS,
+          headers: socketHeaders(host),
+        });
+
+        let timer: NodeJS.Timeout | undefined;
+        let sentConnect = false;
+        let settled = false;
+
+        const cleanup = () => {
+          if (timer) {
+            clearTimeout(timer);
+            timer = undefined;
+          }
+          ws.off('message', onMessage);
+          ws.off('error', onError);
+          ws.off('close', onClose);
+        };
+
+        const resolveOnce = () => {
+          if (settled) return;
+          settled = true;
+          cleanup();
+          resolve(ws);
+        };
+
+        const rejectOnce = (err: Error) => {
+          if (settled) return;
+          settled = true;
+          cleanup();
+          try {
+            ws.close();
+          } catch {
+            /* ignore close errors */
+          }
+          reject(err);
+        };
+
+        const armHandshakeFallback = () => {
+          if (timer) return;
+          timer = setTimeout(resolveOnce, HANDSHAKE_WAIT_MS);
+        };
+
+        const onMessage = (data: WebSocket.RawData) => {
+          const packet = data.toString();
+          if (packet === '2') {
+            try {
+              ws.send('3');
+            } catch {
+              /* ignore send errors during probing */
+            }
+            return;
+          }
+          if (!sentConnect) {
+            if (!packet.startsWith('0')) {
+              rejectOnce(new Error(`tempmail-cn: unexpected open packet for EIO=${version}`));
+              return;
+            }
+            sentConnect = true;
+            try {
+              ws.send('40');
+            } catch (error) {
+              rejectOnce(error instanceof Error ? error : new Error(String(error)));
+              return;
+            }
+            armHandshakeFallback();
+            return;
+          }
+          if (packet.startsWith('40')) {
+            resolveOnce();
+          }
+        };
+
+        const onError = (error: Error) => rejectOnce(error);
+        const onClose = () => rejectOnce(new Error(`tempmail-cn: websocket closed during EIO=${version} handshake`));
+
+        ws.on('message', onMessage);
+        ws.once('error', onError);
+        ws.once('close', onClose);
+      });
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+    }
+  }
+
+  throw lastError || new Error('tempmail-cn: websocket handshake failed');
+}
+
+async function requestShortId(host: string): Promise<string> {
+  const ws = await connectSocket(host);
+
+  return await new Promise<string>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      cleanup();
+      try {
+        ws.close();
+      } catch {
+        /* ignore close errors */
+      }
+      reject(new Error('tempmail-cn: timed out waiting for shortid'));
+    }, CONNECT_TIMEOUT_MS);
+
+    const cleanup = () => {
+      clearTimeout(timer);
+      ws.off('message', onMessage);
+      ws.off('error', onError);
+      ws.off('close', onClose);
+    };
+
+    const finish = (value: string) => {
+      cleanup();
+      try {
+        ws.close();
+      } catch {
+        /* ignore close errors */
+      }
+      resolve(value);
+    };
+
+    const fail = (error: Error) => {
+      cleanup();
+      try {
+        ws.close();
+      } catch {
+        /* ignore close errors */
+      }
+      reject(error);
+    };
+
+    const onMessage = (data: WebSocket.RawData) => {
+      const packet = data.toString();
+      if (packet === '2') {
+        ws.send('3');
+        return;
+      }
+      const decoded = parseEventPacket(packet);
+      if (!decoded || decoded.event !== 'shortid' || typeof decoded.payload !== 'string') {
+        return;
+      }
+      finish(decoded.payload);
+    };
+
+    const onError = (error: Error) => fail(error);
+    const onClose = () => fail(new Error('tempmail-cn: websocket closed before shortid arrived'));
+
+    ws.on('message', onMessage);
+    ws.once('error', onError);
+    ws.once('close', onClose);
+
+    sendEvent(ws, 'request shortid', true);
+  });
+}
+
+async function ensureMailbox(email: string): Promise<void> {
+  const st = getState(email);
+  if (st.ws?.readyState === WebSocket.OPEN) {
+    return;
+  }
+  if (st.connectPromise) {
+    return st.connectPromise;
+  }
+
+  const { local, host } = splitAddress(email);
+
+  st.connectPromise = (async () => {
+    try {
+      const ws = await connectSocket(host);
+      st.ws = ws;
+
+      const detach = () => {
+        if (st.ws === ws) {
+          st.ws = null;
+        }
+        st.connectPromise = undefined;
+      };
+
+      ws.on('message', (data: WebSocket.RawData) => {
+        const packet = data.toString();
+        if (packet === '2') {
+          try {
+            ws.send('3');
+          } catch {
+            /* ignore late pong failures */
+          }
+          return;
+        }
+
+        const decoded = parseEventPacket(packet);
+        if (!decoded || decoded.event !== 'mail' || !decoded.payload) {
+          return;
+        }
+
+        const normalized = normalizeEmail(flattenMail(decoded.payload, email), email);
+        if (!normalized.id || st.seenIds.has(normalized.id)) {
+          return;
+        }
+
+        st.seenIds.add(normalized.id);
+        st.emails.push(normalized);
+      });
+
+      ws.on('close', detach);
+      ws.on('error', detach);
+
+      sendEvent(ws, 'set shortid', local);
+      await sleep(INITIAL_SYNC_WAIT_MS);
+    } catch (error) {
+      st.connectPromise = undefined;
+      throw error;
+    }
+  })();
+
+  return st.connectPromise;
+}
+
+export async function generateEmail(domain?: string | null): Promise<InternalEmailInfo> {
+  const host = normalizeHost(domain);
+  const shortid = await requestShortId(host);
+  return {
+    channel: CHANNEL,
+    email: `${shortid}@${host}`,
+  };
+}
+
+export async function getEmails(email: string): Promise<Email[]> {
+  await ensureMailbox(email);
+  const st = getState(email);
+  return [...st.emails];
+}

package/src/retry.ts

@@ -89,17 +89,28 @@ function sleep(ms: number): Promise<void> {
  * @param fn 要执行的异步操作
  * @param options 重试配置
  */
-export async function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T> {
+export type RetryWithAttemptsResult<T> =
+  | { ok: true; value: T; attempts: number }
+  | { ok: false; error: unknown; attempts: number };
+
+/**
+ * 与 withRetry 相同，额外返回尝试次数（成功或最终失败时均有效）
+ */
+export async function withRetryWithAttempts<T>(
+  fn: () => Promise<T>,
+  options?: RetryOptions,
+): Promise<RetryWithAttemptsResult<T>> {
   const opts = { ...DEFAULT_RETRY_OPTIONS, ...options };
   let lastError: any;
 
   for (let attempt = 0; attempt <= opts.maxRetries; attempt++) {
+    const attempts = attempt + 1;
     try {
       const result = await fn();
       if (attempt > 0) {
         logger.info(`第 ${attempt + 1} 次尝试成功`);
       }
-      return result;
+      return { ok: true, value: result, attempts };
     } catch (error: any) {
       lastError = error;
       const errorMsg = error.message || String(error);
@@ -111,7 +122,7 @@ export async function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions)
         } else if (!opts.shouldRetry(error)) {
           logger.debug(`不可重试的错误: ${errorMsg}`);
         }
-        throw error;
+        return { ok: false, error, attempts };
       }
 
       /* 指数退避等待 */
@@ -121,7 +132,13 @@ export async function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions)
     }
   }
 
-  throw lastError;
+  return { ok: false, error: lastError, attempts: opts.maxRetries + 1 };
+}
+
+export async function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T> {
+  const r = await withRetryWithAttempts(fn, options);
+  if (r.ok) return r.value;
+  throw r.error;
 }
 
 /**

package/src/telemetry.ts

@@ -0,0 +1,138 @@
+import { getConfig } from './config';
+import { getSdkVersion } from './version';
+
+const DEFAULT_URL = 'https://sdk-1.openel.top/v1/event';
+const MAX_BATCH = 32;
+const FLUSH_MS = 2000;
+
+const EMAIL_LIKE = /[^\s@]{1,64}@[^\s@]{1,255}/g;
+
+interface TelemetryEvent {
+  operation: string;
+  channel: string;
+  success: boolean;
+  attempt_count: number;
+  channels_tried?: number;
+  error?: string;
+  ts_ms: number;
+}
+
+interface TelemetryBatch {
+  schema_version: number;
+  sdk_language: string;
+  sdk_version: string;
+  os: string;
+  arch: string;
+  events: TelemetryEvent[];
+}
+
+const queue: TelemetryEvent[] = [];
+let flushTimer: ReturnType<typeof setTimeout> | null = null;
+let periodicStarted = false;
+
+function sanitizeError(msg: string): string {
+  if (!msg) return '';
+  return msg.replace(EMAIL_LIKE, '[redacted]').slice(0, 400);
+}
+
+function resolveUrl(): string {
+  const c = getConfig();
+  const u = (c.telemetryUrl || '').trim();
+  if (u) return u;
+  return DEFAULT_URL;
+}
+
+function telemetryOn(): boolean {
+  const v = getConfig().telemetryEnabled;
+  if (v === false) return false;
+  return true;
+}
+
+function getFetchForTelemetry(): { fetchFn: typeof fetch } {
+  const c = getConfig();
+  return { fetchFn: c.customFetch || fetch };
+}
+
+function startPeriodicFlush(): void {
+  if (periodicStarted) return;
+  periodicStarted = true;
+  setInterval(() => {
+    void flushQueue();
+  }, FLUSH_MS);
+}
+
+function scheduleDebouncedFlush(): void {
+  if (flushTimer) clearTimeout(flushTimer);
+  flushTimer = setTimeout(() => {
+    flushTimer = null;
+    void flushQueue();
+  }, FLUSH_MS);
+}
+
+async function flushQueue(): Promise<void> {
+  if (!telemetryOn()) {
+    queue.length = 0;
+    return;
+  }
+  if (queue.length === 0) return;
+
+  const events = queue.splice(0, queue.length);
+  const url = resolveUrl();
+  if (!url) return;
+
+  const sdkVersion = getSdkVersion();
+  const batch: TelemetryBatch = {
+    schema_version: 2,
+    sdk_language: 'node',
+    sdk_version: sdkVersion,
+    os: typeof process !== 'undefined' ? process.platform : 'unknown',
+    arch: typeof process !== 'undefined' ? process.arch : 'unknown',
+    events,
+  };
+
+  const { fetchFn } = getFetchForTelemetry();
+  try {
+    await fetchFn(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'User-Agent': `tempmail-sdk-node/${sdkVersion}`,
+      },
+      body: JSON.stringify(batch),
+    });
+  } catch {
+    /* ignore */
+  }
+}
+
+export function reportTelemetry(
+  operation: string,
+  channel: string,
+  success: boolean,
+  attemptCount: number,
+  channelsTried: number,
+  error: string,
+): void {
+  if (!telemetryOn()) return;
+
+  startPeriodicFlush();
+
+  const ev: TelemetryEvent = {
+    operation,
+    channel,
+    success,
+    attempt_count: attemptCount,
+    ts_ms: Date.now(),
+  };
+  if (channelsTried > 0) ev.channels_tried = channelsTried;
+  const err = sanitizeError(error);
+  if (err) ev.error = err;
+
+  queue.push(ev);
+
+  if (queue.length >= MAX_BATCH) {
+    void flushQueue();
+  } else {
+    scheduleDebouncedFlush();
+  }
+}

package/src/types.ts

@@ -2,7 +2,7 @@
  * 支持的临时邮箱渠道标识
  * 每个渠道对应一个第三方临时邮箱服务商
  */
-export type Channel = 'tempmail' | 'linshi-email' | 'linshiyou' | 'mffac' | 'tempmail-lol' | 'chatgpt-org-uk' | 'temp-mail-io' | 'awamail' | 'temporary-email-org' | 'mail-tm' | 'mail-cx' | 'dropmail' | 'guerrillamail' | 'maildrop' | 'smail-pw' | 'boomlify' | 'minmail' | 'vip-215' | 'anonbox' | 'fake-legal';
+export type Channel = 'tempmail' | 'tempmail-cn' | 'linshi-email' | 'linshiyou' | 'mffac' | 'tempmail-lol' | 'chatgpt-org-uk' | 'temp-mail-io' | 'awamail' | 'temporary-email-org' | 'mail-tm' | 'mail-cx' | 'dropmail' | 'guerrillamail' | 'maildrop' | 'smail-pw' | 'boomlify' | 'minmail' | 'vip-215' | 'anonbox' | 'fake-legal';
 
 /**
  * 创建临时邮箱后返回的邮箱信息
@@ -130,7 +130,7 @@ export interface GenerateEmailOptions {
   channelFallback?: boolean;
   /** 邮箱有效时长 */
   duration?: number;
-  /** 指定邮箱域名 */
+  /** 指定邮箱域名或接入域名（如 `tempmail-cn` 自定义域名） */
   domain?: string | null;
   /** 重试配置，不传则使用默认值（最多重试 2 次） */
   retry?: RetryConfig;

package/src/version.ts

@@ -0,0 +1,19 @@
+import { readFileSync } from 'fs';
+import { join } from 'path';
+
+let cached: string | null = null;
+
+export function getSdkVersion(): string {
+  if (cached !== null) {
+    return cached;
+  }
+  try {
+    const pkgPath = join(__dirname, '..', 'package.json');
+    const raw = readFileSync(pkgPath, 'utf8');
+    const j = JSON.parse(raw) as { version?: string };
+    cached = j.version && String(j.version).trim() ? String(j.version).trim() : '0.0.0';
+  } catch {
+    cached = '0.0.0';
+  }
+  return cached;
+}