tempmail_sdk 1.3.3 → 1.3.5

data/lib/tempmail_sdk/providers/temporarymail_com.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module TempmailSdk
+  module Providers
+    # Temporarymail 渠道实现（temporarymail.com）
+    #
+    # 无认证 REST（key 为空即随机建箱）：
+    #   GET /api/?action=requestEmailAccess&key=&value=random 建箱，
+    #   响应 {"address":"...","secretKey":"..."}，secretKey 用于后续 checkInbox。
+    # 读信 GET /api/?action=checkInbox&value=<secretKey>，响应有两种形态：
+    #   空收件箱为 []，有信时为 map[id]→邮件元数据对象。
+    # 详情 POST /api/?action=getEmail&value=<id> 覆盖真实主题（列表常为 "[No Subject]"）；
+    # 全文 GET /view/?i=<id> 返回 HTML 化网页，本地剥标签还原纯文本。
+    # 地址最长周期固定为 4 小时。
+    module TemporarymailCom
+      CHANNEL = "temporarymail-com"
+      BASE_URL = "https://temporarymail.com"
+
+      # 备用浏览器 UA（403 重试用，规避共享池随机 UA 耗尽）
+      ALT_UA = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) " \
+               "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Safari/537.36"
+
+      HEADERS = {
+        "Accept" => "application/json, text/plain, */*",
+        "Accept-Language" => "en-US,en;q=0.9",
+        "Sec-Fetch-Site" => "same-origin",
+        "Sec-Fetch-Mode" => "cors",
+        "Sec-Fetch-Dest" => "empty",
+        "Referer" => "#{BASE_URL}/",
+        "Origin" => BASE_URL,
+        "User-Agent" => "Mozilla/5.0 (Windows NT 10.0; Win64; x64) " \
+                        "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Safari/537.36"
+      }.freeze
+
+      module_function
+
+      # 构造 /api/ 请求头（403 时换备用 UA 重试）
+      # @param ua [String] User-Agent
+      # @return [Hash]
+      def api_headers(ua)
+        HEADERS.merge("User-Agent" => ua)
+      end
+
+      # 创建 temporarymail.com 临时邮箱
+      # GET /api/?action=requestEmailAccess&key=&value=random；token 复用 secretKey。
+      # @return [EmailInfo]
+      def generate_email
+        resp = Http.get("#{BASE_URL}/api/?action=requestEmailAccess&key=&value=random",
+                        headers: api_headers(HEADERS["User-Agent"]), timeout: 15)
+        if resp.status_code == 429
+          raise "temporarymail: 创建邮箱平台限流(429)，请稍后重试"
+        end
+        resp.raise_for_status
+        data = resp.json
+        raise "temporarymail: 创建响应非对象" unless data.is_a?(Hash)
+
+        addr = data["address"].to_s.strip
+        key = data["secretKey"].to_s.strip
+        raise "temporarymail: 创建响应缺少 address 或 secretKey" if addr.empty? || key.empty?
+
+        EmailInfo.new(channel: CHANNEL, email: addr, token: key)
+      end
+
+      # 解析平台双形态响应（[] 或 map[id]→对象）为数组
+      # @param data [Object] JSON 解析结果
+      # @return [Array<Hash>, nil]
+      def list_of(data)
+        return data if data.is_a?(Array)
+
+        data.values if data.is_a?(Hash)
+      end
+
+      # 读取 temporarymail 收件箱
+      # 列表主题常为 "[No Subject]"：逐封拉详情覆盖真实主题，并逐封抓 /view/ 全文。
+      # @param email [String] 邮箱地址
+      # @param token [String] 建箱返回的 secretKey
+      # @return [Array<Email>]
+      def get_emails(email, token)
+        tk = token.to_s.strip
+        raise "temporarymail: token 为空" if tk.empty?
+
+        body = check_inbox(tk)
+        list = list_of(body)
+        return [] unless list.is_a?(Array)
+
+        addr = email.to_s.strip
+        list.filter_map do |m|
+          next unless m.is_a?(Hash)
+
+          row = m.dup
+          row["to"] = addr unless row.key?("to")
+          id = row["id"].to_s.strip
+          unless id.empty?
+            # 详情覆盖真实主题/发件人（失败不致命：列表元数据兜底）
+            det = fetch_detail(id)
+            if det.is_a?(Hash)
+              row["subject"] = det["subject"] if det["subject"].to_s.strip != ""
+              row["from"] = det["from"] if det["from"].to_s.strip != ""
+            end
+            # /view/ 渲染端点全文（失败不致命：列表元数据兜底）
+            text = fetch_view(id)
+            row["text"] = text if !text.empty?
+          end
+          Normalize.normalize_email(row, addr)
+        end
+      end
+
+      # 拉取 checkInbox 响应体；403 换备用 UA 重试一次，429 报平台限流。
+      # @param token [String] secretKey
+      # @return [Object] JSON 解析结果
+      def check_inbox(token)
+        uas = [HEADERS["User-Agent"], ALT_UA]
+        last_status = 0
+        last_raw = ""
+        uas.each do |ua|
+          uri = "#{BASE_URL}/api/?action=checkInbox&value=#{URI.encode_www_form_component(token)}"
+          resp = Http.get(uri, headers: api_headers(ua), timeout: 15)
+          if resp.status_code == 429
+            raise "temporarymail: 读取收件箱平台限流(429)，请拉大轮询间隔"
+          end
+          if resp.ok?
+            return resp.json
+          end
+          last_status = resp.status_code
+          last_raw = resp.body.to_s
+          # 403/404 疑似 UA 键控风控，换备用 UA 重试一次
+          next if [403, 404].include?(resp.status_code)
+
+          raise "temporarymail: 读取收件箱失败 http #{resp.status_code}: #{last_raw}"
+        end
+        raise "temporarymail: 读取收件箱失败 http #{last_status}（两次尝试均被拒）"
+      end
+
+      # 拉取单封详情（POST /api/?action=getEmail&value=<id>），风控失败返回 nil 降级
+      # @param id [String] 邮件 ID
+      # @return [Hash, nil]
+      def fetch_detail(id)
+        uri = "#{BASE_URL}/api/?action=getEmail&value=#{URI.encode_www_form_component(id)}"
+        resp = Http.post(uri, headers: api_headers(HEADERS["User-Agent"]), timeout: 15)
+        return nil if resp.status_code == 429 || !resp.ok?
+
+        data = resp.json
+        return nil unless data.is_a?(Hash)
+
+        data.values.first
+      rescue StandardError
+        nil
+      end
+
+      # 抓取 /view/ 渲染端点全文并还原纯文本
+      # @param id [String] 邮件 ID
+      # @return [String]
+      def fetch_view(id)
+        uri = "#{BASE_URL}/view/?i=#{URI.encode_www_form_component(id)}&width=800"
+        resp = Http.get(uri,
+                        headers: {
+                          "Accept" => "text/html, */*",
+                          "User-Agent" => HEADERS["User-Agent"],
+                          "Referer" => "#{BASE_URL}/"
+                        },
+                        timeout: 15)
+        return "" unless resp.ok?
+
+        view_to_text(resp.body.to_s)
+      end
+
+      # 将 /view/ 响应剥标签还原为纯文本（<br>/<p> 换行保留）
+      # @param src [String] HTML 化网页原文
+      # @return [String]
+      def view_to_text(src)
+        s = src.to_s
+        %w[<br\ /> <br/> <br> <p> </p>].each { |tag| s = s.gsub(tag, "\n") }
+        s = s.gsub(/<script\b[^>]*>.*?<\/script>/mi, " ")
+        s = s.gsub(/<style\b[^>]*>.*?<\/style>/mi, " ")
+        s = s.gsub(/<[^>]+>/, " ")
+        s = s.gsub("&nbsp;", "&").gsub("&nbsp;", " ").gsub("&gt;", ">").gsub("&lt;", "<")
+        s = s.gsub("&quot;", '"').gsub("&#39;", "'").gsub("&amp;", "&")
+        s.split("\n").map { |ln| ln.strip }.join("\n").strip
+      end
+    end
+  end
+end

data/lib/tempmail_sdk/providers/tenmin_app.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module TempmailSdk
+  module Providers
+    # Tenmin.app 渠道实现（真实 API 域 api.tenmin.app）
+    #
+    # 建箱+读信共用 GET /api/inbox/{localpart}（Accept: application/json）。
+    # localpart 为随机 6 位小写十六进制串（首访即建箱，平台无显式创建接口）；
+    # 响应：{"inboxId":..,"address":"..@tenmin.app","ttl":600,"count":0,"messages":[]}，
+    # messages[] 元素字段：id/from/subject/text/html/receivedAt（from 为 {name,address} 对象）。
+    module TenminApp
+      CHANNEL = "tenmin-app"
+      BASE_URL = "https://api.tenmin.app"
+      DEFAULT_DOMAIN = "tenmin.app"
+
+      HEADERS = {
+        "Accept" => "application/json",
+        "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"
+      }.freeze
+
+      module_function
+
+      HEX_CHARS = ("0".."9").to_a + ("a".."f").to_a
+
+      # 生成 6 位小写十六进制随机 localpart
+      def random_local
+        Array.new(6) { HEX_CHARS.sample }.join
+      end
+
+      # 请求 /api/inbox/{localpart}
+      # @param localpart [String] 邮箱 localpart
+      # @return [Hash] 解析后的收件箱响应（解析失败返回空 Hash）
+      def fetch_inbox(localpart)
+        resp = Http.get("#{BASE_URL}/api/inbox/#{localpart}", headers: HEADERS, timeout: 15)
+        resp.raise_for_status
+        data = resp.json
+        data.is_a?(Hash) ? data : {}
+      end
+
+      # 创建 tenmin.app 临时邮箱
+      # 首次 GET 随机 localpart 即自动建箱（10 分钟 TTL），token 存储 localpart
+      # @return [EmailInfo]
+      def generate_email
+        local = random_local
+        data = fetch_inbox(local)
+        address = data["address"].to_s.strip
+        address = "#{local}@#{DEFAULT_DOMAIN}" if address.empty?
+        ttl = data["ttl"].to_i
+        expires_at = nil
+        expires_at = ((Time.now.to_f + ttl) * 1000).to_i if ttl.positive?
+        EmailInfo.new(channel: CHANNEL, email: address, token: local, expires_at: expires_at)
+      end
+
+      # 读取 tenmin.app 收件箱
+      # 复用建箱同一 localpart 轮询；from 为 {name,address} 对象，拆开格式化后归一。
+      # @param email [String] 邮箱地址
+      # @param token [String] localpart
+      # @return [Array<Email>]
+      def get_emails(email, token)
+        local = token.to_s.strip
+        raise "tenmin-app: token 为空" if local.empty?
+
+        data = fetch_inbox(local)
+        messages = data["messages"]
+        return [] unless messages.is_a?(Array)
+
+        addr = email.to_s.strip
+        messages.filter_map do |m|
+          next unless m.is_a?(Hash)
+
+          from = m["from"]
+          # from 为对象（{name,address}）时拆出地址字段
+          from_str = if from.is_a?(Hash)
+                       fname = from["name"].to_s.strip
+                       faddr = from["address"].to_s.strip
+                       if !faddr.empty? && !fname.empty?
+                         "#{fname} <#{faddr}>"
+                       else
+                         faddr.empty? ? fname : faddr
+                       end
+                     else
+                       from.to_s
+                     end
+
+          row = {
+            "id" => m["id"],
+            "from" => from_str,
+            "to" => addr,
+            "subject" => m["subject"],
+            "text" => m["text"],
+            "html" => m["html"],
+            "date" => m["receivedAt"] || m["created_at"] || m["date"]
+          }
+          Normalize.normalize_email(row, addr)
+        end
+      end
+    end
+  end
+end

data/lib/tempmail_sdk/providers/tenminutemail_net.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "time"
+
+module TempmailSdk
+  module Providers
+    # 10minutemail.net 渠道实现
+    #
+    # 流程：GET / 获取 PHPSESSID session cookie + 从 HTML 输入框提取邮箱地址
+    #       GET /mailbox.ajax.php?_={毫秒时间戳} 获取邮件列表（HTML 表格）
+    #       GET /readmail.html?mid={id} 获取单封邮件正文
+    # token 为空字符串（session 由 cookie jar 自动维护）
+    module TenminutemailNet
+      CHANNEL = "10minutemail-net"
+      BASE_URL = "https://10minutemail.net"
+
+      EMAIL_RE    = /value="([^"]+@[^"]+)"/
+      ROW_RE      = /<tr[^>]*>(.*?)<\/tr>/im
+      MID_RE      = /readmail\.html\?mid=([^'"&]+)/i
+      CELL_RE     = /<td[^>]*>(.*?)<\/td>/im
+      TITLE_RE    = /title="([^"]+)"/i
+      CF_RE       = /data-cfemail="([0-9a-fA-F]+)"/i
+      TAG_RE      = /<[^>]+>/
+      BODY_MARK   = 'class="mailinhtml"'
+
+      BROWSER_HEADERS = {
+        "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" => "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif," \
+                    "image/webp,image/apng,*/*;q=0.8",
+        "Accept-Language" => "en-US,en;q=0.9,zh-CN;q=0.8,zh;q=0.7"
+      }.freeze
+
+      AJAX_HEADERS = BROWSER_HEADERS.merge(
+        "Accept" => "*/*",
+        "X-Requested-With" => "XMLHttpRequest",
+        "Referer" => BASE_URL + "/"
+      ).freeze
+
+      module_function
+
+      # 解码 Cloudflare 邮箱保护混淆字符串
+      # @param encoded [String] 十六进制字符串
+      # @return [String]
+      def cf_decode(encoded)
+        data = [encoded].pack("H*")
+        return "" if data.length < 2
+
+        key = data.getbyte(0)
+        out = data.bytes[1..].map { |b| b ^ key }.pack("C*")
+        out.include?("@") ? out : ""
+      rescue StandardError
+        ""
+      end
+
+      # 从单元格 HTML 提取纯文本（优先解码 CF 混淆）
+      # @param cell [String]
+      # @return [String]
+      def extract_text(cell)
+        if (m = cell.match(CF_RE))
+          decoded = cf_decode(m[1])
+          return decoded unless decoded.empty?
+        end
+
+        text = cell.gsub(TAG_RE, "")
+        text = text.gsub("&nbsp;", " ").gsub("&#160;", " ")
+                   .gsub("&amp;", "&").gsub("&lt;", "<")
+                   .gsub("&gt;", ">").gsub("&quot;", '"')
+        text.strip
+      end
+
+      # 从整页 HTML 提取 mailinhtml div 正文
+      # @param page [String]
+      # @return [String]
+      def extract_body(page)
+        si = page.index(BODY_MARK)
+        return "" unless si
+
+        gt = page.index(">", si)
+        return "" unless gt
+
+        content_start = gt + 1
+        rest = page[content_start..]
+
+        ei = rest.index("email-decode.min.js")
+        segment = if ei
+                    s = rest[0...ei]
+                    s = s[0...s.rindex("<script")] if s.rindex("<script")
+                    s.strip.sub(/<\/div>\s*\z/, "").strip.sub(/<\/div>\s*\z/, "").strip
+                  else
+                    di = rest.index("</div>")
+                    di ? rest[0...di].strip : rest.strip
+                  end
+        segment
+      end
+
+      # 创建 10minutemail.net 临时邮箱
+      # @return [EmailInfo]
+      def generate_email
+        resp = Http.get(BASE_URL + "/", headers: BROWSER_HEADERS, timeout: 15)
+        resp.raise_for_status
+        m = resp.body.match(EMAIL_RE)
+        raise "10minutemail-net: 未能从首页提取邮箱地址" unless m
+
+        email = m[1].strip
+        raise "10minutemail-net: 获取到的邮箱地址无效" if email.empty? || !email.include?("@")
+
+        EmailInfo.new(channel: CHANNEL, email: email, token: "")
+      end
+
+      # 获取 10minutemail.net 邮件列表
+      # @param email [String]
+      # @param token [String] 未使用（session 由 cookie jar 维护）
+      # @return [Array<Email>]
+      def get_emails(email, token)
+        _ = token
+        ts = (Time.now.to_f * 1000).to_i
+        list_url = "#{BASE_URL}/mailbox.ajax.php?_=#{ts}"
+        resp = Http.get(list_url, headers: AJAX_HEADERS, timeout: 15)
+        resp.raise_for_status
+
+        rows = resp.body.scan(ROW_RE)
+        emails = []
+        rows.each do |row_inner_arr|
+          row_inner = row_inner_arr[0]
+          next if row_inner.downcase.include?("<th")
+
+          mid_m = row_inner.match(MID_RE)
+          next unless mid_m
+
+          mail_id = mid_m[1].strip
+          next if mail_id.empty?
+
+          cells = row_inner.scan(CELL_RE).map { |c| c[0] }
+          from_cell    = cells[0] || ""
+          subject_cell = cells[1] || ""
+          date_cell    = cells[2] || ""
+
+          from    = extract_text(from_cell)
+          subject = extract_text(subject_cell)
+          date    = if (tm = date_cell.match(TITLE_RE))
+                      tm[1].strip
+                    else
+                      extract_text(date_cell)
+                    end
+
+          # 未读行的 <tr> 样式含 font-weight: bold
+          full_row = "<tr#{row_inner}</tr>"
+          is_read = !full_row.downcase.include?("font-weight: bold")
+
+          html_body = fetch_body(mail_id)
+
+          flat = {
+            "id" => mail_id, "from" => from, "to" => email,
+            "subject" => subject, "html" => html_body,
+            "date" => date, "isRead" => is_read
+          }
+          emails << Normalize.normalize_email(flat, email)
+        end
+        emails
+      end
+
+      # 获取单封邮件正文
+      # @param mail_id [String]
+      # @return [String]
+      def fetch_body(mail_id)
+        return "" if mail_id.empty?
+
+        url = "#{BASE_URL}/readmail.html?mid=#{mail_id}"
+        resp = Http.get(
+          url,
+          headers: BROWSER_HEADERS.merge("Referer" => BASE_URL + "/"),
+          timeout: 15
+        )
+        return "" unless resp.status_code == 200
+
+        extract_body(resp.body)
+      rescue StandardError
+        ""
+      end
+    end
+  end
+end

data/lib/tempmail_sdk/providers/thirty_min_email.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module TempmailSdk
+  module Providers
+    # 30minemail 渠道实现（30minemail.com）
+    #
+    # 官网邮箱由服务端 16 位 hex 本地名识别：
+    #   GET /?generate 返回完整 HTML 页面，从中解析 <地址>@30minemail.com；
+    #   本地名无效邮箱访问 messages.php 时返回 ok:false/expired:true，故必须经服务端建箱。
+    # 读信 GET /messages.php?email=<完整地址>&_=<unix毫秒>，响应
+    #   {"ok":true,"expired":false,"count":0,"emails":[],"expires_in":...}。
+    # emails 元素字段实测：{id,from,to,subject,date,html}（html 为完整正文）。
+    # 无认证、无 Cookie、无 CSRF。
+    module ThirtyMinEmail
+      CHANNEL = "30minemail"
+      BASE_URL = "https://30minemail.com"
+      DOMAIN = "30minemail.com"
+
+      HEADERS = {
+        "Accept" => "text/html,application/xhtml+xml,application/json;q=0.9,*/*;q=0.8",
+        "User-Agent" => "Mozilla/5.0 (Windows NT 10.0; Win64; x64) " \
+                        "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Safari/537.36"
+      }.freeze
+
+      module_function
+
+      # 创建 30minemail.com 临时邮箱
+      # GET /?generate 返回 HTML 页面，从其中解析 16 位 hex 本地名地址；
+      # token 复用完整地址（服务端以地址定位收件箱）。
+      # @return [EmailInfo]
+      def generate_email
+        resp = Http.get("#{BASE_URL}/?generate", headers: HEADERS, timeout: 15)
+        resp.raise_for_status
+        page = resp.body.to_s
+        idx = page.index("@#{DOMAIN}")
+        raise "30minemail: 创建页面未找到邮箱地址" if idx.nil?
+
+        # 向前查找本地名起点：空白或 > 之后
+        start = idx
+        while start.positive? && ![" ", "\n", "\t", ">", '"'].include?(page[start - 1])
+          start -= 1
+        end
+        local = page[start...idx].to_s.strip
+        raise "30minemail: 创建页面解析地址异常" if local.length < 8
+
+        addr = "#{local}@#{DOMAIN}"
+        EmailInfo.new(channel: CHANNEL, email: addr, token: addr)
+      end
+
+      # 读取 30minemail.com 收件箱
+      # GET /messages.php?email=<完整地址>&_=<unix毫秒>，模拟官方轮询参数。
+      # @param email [String] 完整邮箱地址
+      # @param token [String] 复用完整地址（服务端以地址定位收件箱）
+      # @return [Array<Email>]
+      def get_emails(email, token)
+        addr = email.to_s.strip
+        raise "30minemail: 邮箱地址为空" if addr.empty?
+
+        uri = "#{BASE_URL}/messages.php?email=#{URI.encode_www_form_component(addr)}&_=#{(Time.now.to_f * 1000).to_i}"
+        resp = Http.get(uri,
+                        headers: {
+                          "Accept" => "application/json",
+                          "User-Agent" => HEADERS["User-Agent"]
+                        },
+                        timeout: 15)
+        raise "30minemail: 读取收件箱失败 http #{resp.status_code}" unless resp.ok?
+
+        data = resp.json
+        raise "30minemail: 收件箱响应非对象" unless data.is_a?(Hash)
+
+        unless data["ok"] == true && data["expired"] != true
+          raise "30minemail: 收件箱不可用或已过期"
+        end
+        emails = data["emails"]
+        return [] unless emails.is_a?(Array)
+
+        emails.filter_map do |m|
+          next unless m.is_a?(Hash)
+
+          row = m.dup
+          # 列表元素无 to 字段时注入收件人地址
+          row["to"] = addr unless row.key?("to")
+          Normalize.normalize_email(row, addr)
+        end
+      end
+    end
+  end
+end

data/lib/tempmail_sdk/providers/tmpkit.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "json"
+
+module TempmailSdk
+  module Providers
+    # Tmpkit 渠道实现（tmpkit.com，Next.js tRPC 前端 + Go-Guerrilla SMTP 后端）
+    #
+    # 流程：
+    #   POST /api/rpc/tempmail/initSession（body 为 tRPC 包裹 {"json":{}}）建箱，
+    #     响应 session.sessionId 与 session.email（sessionId 同值 Set-Cookie）
+    #   POST /api/rpc/tempmail/getEmails（{"json":{"offset":0,"limit":20}} +
+    #     Cookie tempmail_session=<sessionId>）列信（列表键 mailId，无 id）
+    #   POST /api/rpc/tempmail/getEmailDetail（{"json":{"mailId":<数字>}}）取正文
+    # 会话粘性：token 保存 sessionId（tempMailSession=<sid>），读信显式携带
+    #   Cookie 请求头，防并行会话串箱。
+    module Tmpkit
+      CHANNEL = "tmpkit"
+      BASE_URL = "https://tmpkit.com"
+      RPC_PREFIX = "#{BASE_URL}/api/rpc/tempmail"
+
+      USER_AGENT = "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 " \
+                   "(KHTML, like Gecko) Chrome/154.0.0.0 Safari/537.36"
+
+      module_function
+
+      # tRPC 调用请求头（Content-Type JSON、Accept 通配、同站 Origin/Referer）
+      # @param cookie [String] sessionId，非空时携带 tempmail_session Cookie
+      # @return [Hash]
+      def rpc_headers(cookie = "")
+        hdrs = {
+          "User-Agent" => USER_AGENT,
+          "Accept" => "*/*",
+          "Content-Type" => "application/json",
+          "Origin" => BASE_URL,
+          "Referer" => "#{BASE_URL}/en"
+        }
+        hdrs["Cookie"] = "tempmail_session=#{cookie}" unless cookie.empty?
+        hdrs
+      end
+
+      # 对 tmpkit 发起 rpc 调用（tRPC 包裹 {"json":<reqBody>}）
+      # 响应外层 {"json":{...}} 解析为 Hash 返回。
+      # @param procedure [String] rpc 过程名
+      # @param req_body [Hash] 过程参数
+      # @param cookie [String] sessionId
+      # @return [Hash]
+      def rpc(procedure, req_body, cookie = "")
+        resp = Http.post("#{RPC_PREFIX}/#{procedure}",
+                         headers: rpc_headers(cookie),
+                         body: JSON.generate({ json: req_body }),
+                         timeout: 15)
+        resp.raise_for_status
+        outer = resp.json
+        payload = outer.is_a?(Hash) ? outer["json"] : nil
+        raise "tmpkit: #{procedure} 响应缺 json 载荷" unless payload.is_a?(Hash)
+
+        payload
+      end
+
+      # 创建 tmpkit.com 临时邮箱
+      # 调 initSession（tRPC 包裹 {"json":{}}），sessionId 与邮箱地址同返。
+      # @return [EmailInfo]
+      def generate_email
+        data = rpc("initSession", {})
+        sess = data["session"]
+        raise "tmpkit: 创建会话响应缺 session 字段" unless sess.is_a?(Hash)
+
+        email = sess["email"].to_s.strip
+        session_id = sess["sessionId"].to_s.strip
+        raise "tmpkit: 创建会话响应缺少必要字段（email/sessionId）" if email.empty? || session_id.empty? || !email.include?("@")
+
+        EmailInfo.new(channel: CHANNEL, email: email,
+                      token: "tempMailSession=#{session_id}")
+      end
+
+      # 获取 tmpkit.com 邮件列表
+      # getEmails（offset 0 / limit 20）取摘要，逐封 getEmailDetail 拉详情并
+      # 将详情键并入摘要；详情失败回退列表摘要。getEmails 返回的 session.email
+      # 与收信邮箱不符时报错，防止会话被覆盖。
+      # @param email [String] 邮箱地址
+      # @param token [String] 会话凭据串（tempMailSession=<sessionId>）
+      # @return [Array<Email>]
+      def get_emails(email, token)
+        raw = token.to_s.strip
+        mailbox = raw.start_with?("tempMailSession=") ? raw.delete_prefix("tempMailSession=") : raw
+        raise "tmpkit: 会话 token 为空" if mailbox.empty?
+
+        data = rpc("getEmails", { offset: 0, limit: 20 }, mailbox)
+
+        # 会话指向校验：getEmails 响应自带 session.email（无 Cookie 时
+        # session 为 null，同样视为会话失效）
+        sess = data["session"]
+        if sess.is_a?(Hash)
+          got = sess["email"].to_s.strip
+          raise "tmpkit: 会话邮箱不匹配（响应 #{got}，请求 #{email}）" if !got.empty? && got != email
+        else
+          raise "tmpkit: 会话已失效（getEmails 返回空会话）"
+        end
+
+        list = data["emails"]
+        raise "tmpkit: 邮件列表响应缺 emails 字段" unless list.is_a?(Array)
+
+        list.map do |item|
+          next unless item.is_a?(Hash)
+
+          m = item.dup
+          # mailId 为数字：合法时逐封拉详情（详情键并入摘要，跳过会话类键）
+          mail_id = m["mailId"]
+          if mail_id.is_a?(Numeric) && mail_id.positive?
+            begin
+              detail = rpc("getEmailDetail", { mailId: mail_id.to_i }, mailbox)
+              if detail.is_a?(Hash)
+                detail.each do |k, v|
+                  next if %w[session emails total error].include?(k)
+
+                  m[k] = v
+                end
+              end
+            rescue StandardError
+              # 详情失败回退列表摘要
+            end
+          end
+          Normalize.normalize_email(m, email)
+        end.compact
+      end
+    end
+  end
+end