tempmail_sdk 1.3.4 → 1.3.5

data/lib/tempmail_sdk/providers/generator_email.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "json"
+
+module TempmailSdk
+  module Providers
+    # GeneratorEmail 渠道实现（generator.email，PHP SSR 网页型）
+    #
+    # 流程：
+    #   GET /inbox4/ 首页 SSR：解析 window.SITE_DATA 的 cur_user/cur_domain
+    #     快照生成邮箱（邮箱=user@domain），同页 Set-Cookie inbox_ctx
+    #     选中该邮箱会话
+    #   GET /inbox4/（带 inbox_ctx Cookie）收信页：列为 class 含
+    #     list-group-item2 的行（平台实测真实类为 list-group-item2，
+    #     非 list-group-item），内含 from_div_45g45gg / subj_div_45g45gg /
+    #     time_div_45g45gg 三要素块
+    # 限制：本站不提供原文正文，按列表三要素归一。
+    # token 语义：{email, domain, user} JSON 快照。
+    module GeneratorEmail
+      CHANNEL = "generator-email"
+      BASE_URL = "https://generator.email"
+      INBOX_URL = "#{BASE_URL}/inbox4/"
+
+      USER_AGENT = "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 " \
+                   "(KHTML, like Gecko) Chrome/154.0.0.0 Safari/537.36"
+
+      USER_RE = /cur_user:"([^"]*)"/
+      DOMAIN_RE = /cur_domain:"([^"]*)"/
+      # 列表条目与三要素块（平台实测真实类为 list-group-item2，按类名后缀锚定）
+      ITEM_RE = /<div[^>]*class="[^"]*list-group-item2[^"]*"[^>]*>(.*?)(?:<\/div>\s*){3}/m
+      FROM_RE = /class="[^"]*from_div_45g45gg[^"]*"[^>]*>(.*?)<\/div>/m
+      SUBJ_RE = /class="[^"]*subj_div_45g45gg[^"]*"[^>]*>(.*?)<\/div>/m
+      TIME_RE = /class="[^"]*time_div_45g45gg[^"]*"[^>]*>(.*?)<\/div>/m
+      SCRIPT_RE = /<(script|style)[\s\S]*?<\/\1>/i
+      TAG_RE = /<[^>]+>/
+
+      module_function
+
+      # 请求收件箱渲染页并返回 HTML（邮箱由服务端依据 inbox_ctx Cookie 选择）
+      # @return [String]
+      def fetch_page
+        headers = {
+          "User-Agent" => USER_AGENT,
+          "Accept" => "text/html,application/xhtml+xml,application/xml;q=0.9," \
+                      "image/avif,image/webp,*/*;q=0.8",
+          "Accept-Language" => "en-US,en;q=0.9",
+          "Referer" => "#{BASE_URL}/"
+        }
+        ctx = @inbox_ctx
+        headers["Cookie"] = "inbox_ctx=#{ctx}" if ctx && !ctx.empty?
+        resp = Http.get(INBOX_URL, headers: headers, timeout: 20)
+        # 收下响应 Set-Cookie 的 inbox_ctx 最新值（同页刷新）
+        resp.set_cookies.each do |line|
+          kv = line.split(";").first.to_s.strip
+          @inbox_ctx = kv.delete_prefix("inbox_ctx=") if kv.start_with?("inbox_ctx=")
+        end
+        resp.raise_for_status
+        resp.body.to_s
+      end
+
+      # 取正则第一个捕获组，无匹配返回空串
+      # @param re [Regexp]
+      # @param src [String]
+      # @return [String]
+      def match_first(re, src)
+        m = re.match(src)
+        m ? m[1].to_s : ""
+      end
+
+      # 去标签与脚本/样式块，压缩空白
+      # @param s [String]
+      # @return [String]
+      def strip_tags(s)
+        out = s.gsub(SCRIPT_RE, " ")
+        out = out.gsub(TAG_RE, " ")
+        out.gsub(/\s+/, " ").strip
+      end
+
+      # 创建 generator.email 临时邮箱
+      # 解析首页 SITE_DATA 快照（cur_user/cur_domain）得到邮箱地址。
+      # @return [EmailInfo]
+      def generate_email
+        src = fetch_page
+        user = match_first(USER_RE, src)
+        domain = match_first(DOMAIN_RE, src)
+        if user.empty? || domain.empty?
+          raise "generator-email: 首页未携带邮箱快照（cur_user/cur_domain）"
+        end
+
+        email = "#{user}@#{domain}"
+        token = JSON.generate({ email: email, domain: domain, user: user })
+        EmailInfo.new(channel: CHANNEL, email: email, token: token)
+      end
+
+      # 获取 generator.email 收件箱
+      # 解析收件箱渲染页的列表条目（from/subj/time 三要素）；本站不提供
+      # 原文正文，SDK 按摘要归一。
+      # @param email [String] 邮箱地址
+      # @param token [String] 会话凭据 JSON（{email, domain, user}）
+      # @return [Array<Email>]
+      def get_emails(email, token)
+        sess = JSON.parse(token.to_s)
+        raise "generator-email: 会话凭据解析失败（非对象）" unless sess.is_a?(Hash)
+
+        raise "generator-email: 会话邮箱与查询邮箱不匹配" if sess["email"] != email
+
+        sess_domain = sess["domain"].to_s
+        src = fetch_page
+        # 服务端当前渲染邮箱与 token 不一致说明 Cookie 上下文已被切换
+        got_domain = match_first(DOMAIN_RE, src)
+        if got_domain != sess_domain
+          raise "generator-email: 会话域名已切换（token #{sess_domain}，服务端 #{got_domain}）"
+        end
+
+        # 列表区域锚定（#email-table ... #markodile 之间）
+        list_start = src.index('id="email-table"')
+        list_end = src.index('id="markodile"')
+        region = if list_start && list_end && list_end > list_start
+                   src[list_start...list_end]
+                 else
+                   ""
+                 end
+
+        out = []
+        src.scan(ITEM_RE) do |raw|
+          raw = raw.to_s
+          # 跳过列表容器外的候选：要求条目文本来自列表区域
+          next if !region.empty? && !region.include?(raw)
+
+          from = strip_tags(match_first(FROM_RE, raw))
+          subject = strip_tags(match_first(SUBJ_RE, raw))
+          when_str = strip_tags(match_first(TIME_RE, raw))
+          next if from.empty? && subject.empty? && when_str.empty?
+
+          out << Normalize.normalize_email(
+            { "from" => from, "to" => email, "subject" => subject, "date" => when_str },
+            email
+          )
+        end
+        out
+      rescue JSON::ParserError => e
+        raise "generator-email: 会话凭据解析失败: #{e.message}"
+      end
+    end
+  end
+end

data/lib/tempmail_sdk/providers/huskmail.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module TempmailSdk
+  module Providers
+    # Huskmail 渠道实现（huskmail.xyz，API 域 api.huskmail.space）
+    #
+    # 流程：
+    #   POST /v1/accounts 建箱（空 JSON body，响应 id/address/password/token/expiresAt/tier，
+    #                          token 为 JWT）
+    #   GET /v1/messages 读信（Header Authorization: Bearer <token>，响应 {"messages":[...]}）
+    #   GET /v1/messages/{id} 取单封详情（Bearer）
+    # 收信域固定为 @huskmail.xyz。
+    module Huskmail
+      CHANNEL = "huskmail"
+      BASE_URL = "https://api.huskmail.space"
+
+      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
+
+      # 可行 ID 候选键，按序提取
+      ID_KEYS = %w[id Id slug messageId message_id].freeze
+
+      module_function
+
+      # 设置 huskmail 请求的通用请求头
+      # @param token [String] 认证令牌，非空时携带 Authorization: Bearer
+      # @return [Hash]
+      def auth_headers(token = "")
+        hdrs = HEADERS.dup
+        hdrs["Authorization"] = "Bearer #{token}" unless token.to_s.empty?
+        hdrs
+      end
+
+      # 创建 huskmail（@huskmail.xyz）临时邮箱
+      # POST /v1/accounts（空 JSON body）返回 address 与 JWT token
+      # @return [EmailInfo]
+      def generate_email
+        resp = Http.post("#{BASE_URL}/v1/accounts",
+                         headers: HEADERS.merge("Content-Type" => "application/json"),
+                         json: {}, timeout: 15)
+        resp.raise_for_status
+        data = resp.json
+        address = data.is_a?(Hash) ? data["address"].to_s.strip : ""
+        token = data.is_a?(Hash) ? data["token"].to_s.strip : ""
+        raise "huskmail: 创建邮箱响应缺少必要字段" if address.empty? || token.empty?
+
+        EmailInfo.new(channel: CHANNEL, email: address, token: token,
+                      expires_at: data["expiresAt"])
+      end
+
+      # 获取 huskmail 邮件列表
+      # GET /v1/messages（{"messages":[...]}）；对每个元素按 id 逐封请求详情合并，
+      # 详情失败时以列表摘要归一。
+      # @param token [String] JWT 认证令牌
+      # @param email [String] 邮箱地址（@huskmail.xyz）
+      # @return [Array<Email>]
+      def get_emails(token, email)
+        tk = token.to_s.strip
+        raise "huskmail: token 为空" if tk.empty?
+
+        resp = Http.get("#{BASE_URL}/v1/messages", headers: auth_headers(tk), timeout: 15)
+        resp.raise_for_status
+        data = resp.json
+        list = data.is_a?(Hash) ? data["messages"] : nil
+        return [] unless list.is_a?(Array)
+
+        addr = email.to_s.strip
+        list.filter_map do |m|
+          next unless m.is_a?(Hash)
+
+          Normalize.normalize_email(detail_row(tk, m, addr), addr)
+        end
+      end
+
+      # 从列表元素中提取消息 ID（候选键 id/Id/slug/messageId/message_id）
+      # @param row [Hash]
+      # @return [String]
+      def message_id_of(row)
+        ID_KEYS.each do |key|
+          val = row[key]
+          return val.to_s.strip unless val.nil? || val.to_s.strip.empty?
+        end
+        ""
+      end
+
+      # 逐封拉取详情并合并到列表摘要；无 ID 或详情失败时以摘要归一
+      # @param token [String] JWT 认证令牌
+      # @param summary [Hash] 列表元素摘要
+      # @param email [String] 收件人邮箱
+      # @return [Hash] 归一化输入行
+      def detail_row(token, summary, email)
+        id = message_id_of(summary)
+        uri = "#{BASE_URL}/v1/messages/#{URI.encode_www_form_component(id)}"
+        resp = Http.get(uri, headers: auth_headers(token), timeout: 15)
+        merged = summary
+        if resp.ok?
+          detail = begin
+            resp.json
+          rescue StandardError
+            nil
+          end
+          # 详情缺失字段不覆盖列表摘要（包含 null 的键跳过）
+          merged = summary.merge(detail.reject { |_k, v| v.nil? }) if detail.is_a?(Hash)
+        end
+        to_normalized_row(merged, email)
+      rescue StandardError
+        to_normalized_row(summary, email)
+      end
+
+      # 将原始消息 Hash 转换为归一化输入行
+      # @param raw [Hash]
+      # @param email [String]
+      # @return [Hash]
+      def to_normalized_row(raw, email)
+        {
+          "id" => raw["id"] || raw["messageId"] || raw["message_id"],
+          "from" => raw["from"],
+          "to" => email,
+          "subject" => raw["subject"],
+          "text" => raw["text"],
+          "html" => raw["html"],
+          "date" => raw["date"]
+        }
+      end
+    end
+  end
+end

data/lib/tempmail_sdk/providers/internxt.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require "json"
+
+module TempmailSdk
+  module Providers
+    # Internxt 渠道实现（internxt.com/temporary-email，Next.js + OpenNext）
+    #
+    # 流程：
+    #   GET /temporary-email 夺取 XSRF-TOKEN Cookie（同气 csrfSecret）
+    #   GET /api/temp-mail/create-email（头 csrf-token=<XSRF-TOKEN 值>）建箱
+    #   GET /api/temp-mail/get-inbox?email=&token=（顶层数组）列信
+    #   GET /api/temp-mail/get-message?email=&token=&messageId= 取单封全文
+    # CSRF 要点：csrf-token 头的值必须是罐中 XSRF-TOKEN（每次 API 响应都会
+    #   刷新该 Cookie，故每次请求前重取），不是 csrfSecret。
+    # token 语义：{address, token} JSON。
+    module Internxt
+      CHANNEL = "internxt"
+      SITE = "https://internxt.com"
+      REF = "#{SITE}/temporary-email"
+      API_BASE = "#{SITE}/api/temp-mail"
+
+      USER_AGENT = "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 " \
+                   "(KHTML, like Gecko) Chrome/154.0.0.0 Safari/537.36"
+
+      # 简单查询编码（取值均为 URL 安全字符）
+      REQUIRE_URI = true
+
+      module_function
+
+      # 收下响应 Set-Cookie：XSRF-TOKEN/csrfSecret 同名覆写模块级状态
+      # @param resp [Http::Response]
+      def merge_cookies(resp)
+        resp.set_cookies.each do |line|
+          kv = line.split(";").first.to_s.strip
+          name, value = kv.split("=", 2)
+          @xsrf = value if name == "XSRF-TOKEN" && value
+          @secret = value if name == "csrfSecret" && value
+        end
+      end
+
+      # 组装 Cookie 请求头（有则携带）
+      # @return [String]
+      def cookie_header
+        parts = []
+        parts << "csrfSecret=#{@secret}" if @secret && !@secret.empty?
+        parts << "XSRF-TOKEN=#{@xsrf}" if @xsrf && !@xsrf.empty?
+        parts.join("; ")
+      end
+
+      # 确保已取得 XSRF-TOKEN：无则 GET /temporary-email 夺取
+      # @return [String] 罐中 XSRF-TOKEN 最新值
+      def prepare_xsrf
+        return @xsrf if @xsrf && !@xsrf.empty?
+
+        resp = Http.get(REF, headers: {
+          "User-Agent" => USER_AGENT,
+          "Accept" => "text/html,application/xhtml+xml,application/xml;q=0.9," \
+                      "image/avif,image/webp,*/*;q=0.8",
+          "Accept-Language" => "en-US,en;q=0.9"
+        }, timeout: 20)
+        resp.raise_for_status
+        merge_cookies(resp)
+        raise "internxt: 未取得 XSRF-TOKEN Cookie" if @xsrf.to_s.empty?
+
+        @xsrf
+      end
+
+      # 带 CSRF 头请求 internxt 数据接口（GET），返回解析后的 JSON。
+      # csrf-token 头取罐中 XSRF-TOKEN 最新值（每次请求前重取，因每个 API
+      # 响应都会刷新该 Cookie）。
+      # @param path [String] 接口路径
+      # @param params [Hash, nil] 查询参数
+      # @return [Object]
+      def api_get(path, params = nil)
+        csrf = prepare_xsrf
+        url = "#{API_BASE}#{path}"
+        unless params.nil? || params.empty?
+          qs = params.map { |k, v| "#{k}=#{v}" }.join("&")
+          url = "#{url}?#{qs}"
+        end
+        headers = {
+          "User-Agent" => USER_AGENT,
+          "Accept" => "application/json, text/plain, */*",
+          "Origin" => SITE,
+          "Referer" => REF,
+          "csrf-token" => csrf
+        }
+        cookie = cookie_header
+        headers["Cookie"] = cookie unless cookie.empty?
+        resp = Http.get(url, headers: headers, timeout: 20)
+        merge_cookies(resp)
+        resp.raise_for_status
+        body = resp.body.to_s.strip
+        body.empty? ? nil : JSON.parse(body)
+      end
+
+      # 创建 internxt.com 临时邮箱
+      # 先确保已取得 XSRF-TOKEN，再 GET /api/temp-mail/create-email
+      # （带 csrf-token 头），响应 {"address","token"}。
+      # @return [EmailInfo]
+      def generate_email
+        prepare_xsrf
+        data = api_get("/create-email")
+        unless data.is_a?(Hash)
+          raise "internxt: 解析建箱响应失败"
+        end
+
+        address = data["address"].to_s.strip
+        api_token = data["token"].to_s.strip
+        if address.empty? || api_token.empty? || !address.include?("@")
+          raise "internxt: 创建邮箱响应缺少必要字段（address/token）"
+        end
+
+        token = JSON.generate({ address: address, token: api_token })
+        EmailInfo.new(channel: CHANNEL, email: address, token: token)
+      end
+
+      # 从列表元素中提取邮件 ID（字符串形态，与 Go 端 messageIDOf 一致）
+      # @param row [Hash]
+      # @return [String]
+      def message_id_of(row)
+        %w[id messageId message_id].each do |key|
+          val = row[key]
+          return val.to_s.strip unless val.nil? || val.to_s.strip.empty?
+        end
+        ""
+      end
+
+      # 获取 internxt.com 收件箱
+      # get-inbox 返回顶层数组（列表元素含 id/from/subject/date/seen 等）；
+      # 逐条 get-message 拉单封全文（响应为单封对象，含 html 渲染全文），
+      # 详情失败回退列表摘要。
+      # @param email [String] 邮箱地址
+      # @param token [String] 会话凭据 JSON（address/token）
+      # @return [Array<Email>]
+      def get_emails(email, token)
+        begin
+          sess = JSON.parse(token.to_s)
+        rescue JSON::ParserError => e
+          raise "internxt: 会话凭据解析失败: #{e.message}"
+        end
+        raise "internxt: 会话凭据解析失败（非对象）" unless sess.is_a?(Hash)
+
+        address = sess["address"].to_s.strip
+        api_token = sess["token"].to_s.strip
+        raise "internxt: 会话凭据缺少必要字段" if address.empty? || api_token.empty?
+
+        raise "internxt: 会话邮箱与查询邮箱不匹配" if address != email
+
+        inbox = api_get("/get-inbox", email: address, token: api_token)
+        raise "internxt: 解析收件箱响应失败" unless inbox.is_a?(Array)
+
+        inbox.filter_map do |item|
+          next unless item.is_a?(Hash)
+
+          m = item.dup
+          mid = message_id_of(m)
+          unless mid.empty?
+            begin
+              detail = api_get("/get-message",
+                               email: address, token: api_token, messageId: mid)
+              if detail.is_a?(Hash)
+                # 列表字段优先，详情仅补齐缺失字段
+                detail.each { |k, v| m[k] = v unless m.key?(k) }
+              end
+            rescue StandardError
+              # 详情失败回退列表摘要
+            end
+          end
+          Normalize.normalize_email(m, email)
+        end
+      end
+    end
+  end
+end

data/lib/tempmail_sdk/providers/linshi_xyz.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module TempmailSdk
+  module Providers
+    # LinshiXYZ 渠道实现（linshi.xyz）
+    #
+    # 无建箱请求：本地随机 6 位 hex 前缀（官网 client 即用短 id）+ @linshi.xyz。
+    # 读信 GET https://linshi.xyz/api/mails/{前缀}，无邮件时返回空数组 []，
+    #   有邮件时为邮件对象数组（元素含 headers{from,to,subject,date} 与 html 正文）。
+    # 归一化时将 headers 平铺并注入收件人地址；非数组骨架（如 {ok:false}）整体失败，
+    # 交由上层 fallback 渠道处理。
+    module LinshiXyz
+      CHANNEL = "linshi-xyz"
+      BASE_URL = "https://linshi.xyz"
+      DOMAIN = "linshi.xyz"
+      HEX_DIGITS = "0123456789abcdef"
+
+      HEADERS = {
+        "Accept" => "application/json",
+        "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
+
+      # 生成本地随机 6 位 hex 前缀（与官网 client 相同格式）
+      # @return [String]
+      def local_name
+        Array.new(6) { HEX_DIGITS[rand(HEX_DIGITS.length)] }.join
+      end
+
+      # 创建 linshi.xyz 临时邮箱
+      # 无需建箱请求，本地随机 6 位 hex 前缀；token 复用完整地址。
+      # @return [EmailInfo]
+      def generate_email
+        addr = "#{local_name}@#{DOMAIN}"
+        EmailInfo.new(channel: CHANNEL, email: addr, token: addr)
+      end
+
+      # 读取 linshi.xyz 收件箱
+      # GET /api/mails/{前缀}（URL 编码），响应为邮件对象数组。
+      # @param email [String] 完整邮箱地址（前缀@linshi.xyz）
+      # @param token [String] 复用完整地址
+      # @return [Array<Email>]
+      def get_emails(email, token)
+        addr = email.to_s.strip
+        raise "linshi-xyz: 邮箱地址无效: #{addr.inspect}" if addr.empty? || !addr.include?("@")
+
+        local = addr.split("@", 2).first.to_s
+        resp = Http.get("#{BASE_URL}/api/mails/#{URI.encode_www_form_component(local)}",
+                        headers: HEADERS, timeout: 15)
+        raise "linshi-xyz: 读取收件箱失败 http #{resp.status_code}" unless resp.ok?
+
+        list = resp.json
+        raise "linshi-xyz: 收件箱响应非数组" unless list.is_a?(Array)
+
+        list.filter_map do |m|
+          next unless m.is_a?(Hash)
+
+          Normalize.normalize_email(normalize_row(m, addr), addr)
+        end
+      end
+
+      # 将 linshi.xyz 邮件对象归一化：headers 平铺为顶层字段并注入收件人。
+      # @param m [Hash] 原始邮件对象
+      # @param email [String] 收件人地址
+      # @return [Hash]
+      def normalize_row(m, email)
+        flat = m.dup
+        headers = m["headers"]
+        flat.merge!(headers) if headers.is_a?(Hash)
+        flat["to"] = email unless flat.key?("to")
+        flat
+      end
+    end
+  end
+end

data/lib/tempmail_sdk/providers/mailmomy.rb

@@ -12,7 +12,7 @@ module TempmailSdk
     #   2. 本地随机 10 位 [a-z0-9] local part，拼接为 <local>@<域名>
     #   3. GET /api/mail/messages?to=<email>&page=1&limit=20 -> {"emails": [...], ...}
     #
-    # 16 个域名变体渠道（如 16888888.cyou、sbook.pics 等）复用同一后端，
+    # 域名变体渠道（如 17666688.shop、sbook.pics 等）复用同一后端，
     # 仅在 generate_email(domain) 传入固定域名即可，收信逻辑完全一致。
     module Mailmomy
       CHANNEL = "mailmomy"

data/lib/tempmail_sdk/providers/mailticking.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module TempmailSdk
+  module Providers
+    # Mailticking 渠道实现（www.mailticking.com，旧域名 temporary-mail.net 的更名站）
+    #
+    # 实测协议（三类请求均以 application/json 交流，站点在 Cloudflare 后）：
+    #   1. 建箱 POST /get-mailbox body {"types":["4"]}（4=独立域名，排除 Gmail 别名）
+    #      响应 {"success":true,"email":"xxx@domain","activate_token":"..."}
+    #   2. 激活 POST /activate-email body {"email":..,"source":"api","activate_token":..}
+    #      响应 {"success":true}
+    #   3. 列信 POST /get-emails?lang=en body {"email":..,"code":..}
+    #      空箱实测响应 {"emails":[],"success":true}；空闲超时/被改绑后返回
+    #      {"success":false,"needNewEmail":true,...}，此时返回错误提示换箱。
+    #
+    # 读信正文无公开端点：GetEmails 只具备列表能力，列表字段名采用多候选提取
+    # 策略，命中多少映射多少（Normalize 既有候选字段负责兜底）。
+    module Mailticking
+      CHANNEL = "mailticking"
+      BASE_URL = "https://www.mailticking.com"
+
+      HEADERS = {
+        "Accept" => "application/json",
+        "Accept-Language" => "en-US,en;q=0.9",
+        "Content-Type" => "application/json",
+        "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
+
+      # 执行 JSON POST 请求并解析响应；响应非 2xx 或 success=false 时抛错
+      # @param path [String] 请求路径
+      # @param payload [Hash] JSON 请求体
+      # @return [Hash]
+      def do_post(path, payload)
+        resp = Http.post("#{BASE_URL}#{path}", headers: HEADERS, json: payload, timeout: 15)
+        data = resp.json
+        unless resp.ok?
+          msg = data.is_a?(Hash) ? (data["error"] || data["message"]).to_s : ""
+          msg = resp.body.to_s if msg.empty?
+          raise "mailticking: http #{resp.status_code}: #{msg}"
+        end
+        unless data.is_a?(Hash) && data["success"] == true
+          msg = data.is_a?(Hash) ? (data["error"] || data["message"]).to_s : ""
+          msg = "unknown error" if msg.empty?
+          raise "mailticking: 请求失败: #{msg}"
+        end
+        data
+      end
+
+      # 创建 mailticking 邮箱账号
+      # 请求 type=4（独立域名）固定取独立域名邮箱，建箱后立即激活会话；
+      # token 必须携带 activate_token（列信协议依赖激活会话），不能为空。
+      # @return [EmailInfo]
+      def generate_email
+        box = do_post("/get-mailbox", { "types" => ["4"] })
+        token = box["code"].to_s.strip
+        token = box["email"].to_s.strip if token.empty?
+        email = box["email"].to_s.strip
+        if token.empty? || email.empty?
+          raise "mailticking: get-mailbox 返回空 email/activate_token"
+        end
+
+        # 激活邮箱，使后续列信请求与服务器记录的最新会话一致
+        do_post("/activate-email", {
+                  "email" => email,
+                  "source" => "api",
+                  "activate_token" => token
+                })
+
+        EmailInfo.new(channel: CHANNEL, email: email, token: token)
+      end
+
+      # 获取 mailticking 邮箱的邮件列表
+      # 空箱返回空列表不报错；需要换箱的响应（needNewEmail）返回语义错误。
+      # @param email [String] 邮箱地址
+      # @param token [String] 建箱返回的激活令牌
+      # @return [Array<Email>]
+      def get_emails(email, token)
+        addr = email.to_s.strip
+        tk = token.to_s.strip
+        raise "mailticking: 邮箱地址为空" if addr.empty?
+        raise "mailticking: activate code 为空" if tk.empty?
+
+        resp = Http.post("#{BASE_URL}/get-emails?lang=en",
+                         headers: HEADERS,
+                         json: { "email" => addr, "code" => tk },
+                         timeout: 15)
+        data = resp.json
+        unless resp.ok?
+          msg = data.is_a?(Hash) ? (data["error"] || data["message"]).to_s : ""
+          msg = resp.body.to_s if msg.empty?
+          raise "mailticking: http #{resp.status_code}: #{msg}"
+        end
+        unless data.is_a?(Hash) && data["success"] == true
+          raise "mailticking: 邮箱已过期，请重新建箱" if data.is_a?(Hash) && data["needNewEmail"] == true
+
+          raise "mailticking: get-emails 失败"
+        end
+        emails = data["emails"]
+        return [] unless emails.is_a?(Array)
+
+        emails.filter_map do |raw|
+          next unless raw.is_a?(Hash)
+
+          Normalize.normalize_email(migrated_fields(raw), addr)
+        end
+      end
+
+      # 尽量映射列表字段到统一字段名
+      # 官网首页表格只有 SENDER/SUBJECT/TIME 三列，字段全名缺少可观测证据，
+      # 因此对常见字段做多候选提取；未命中的字段留给 Normalize 自己处理。
+      # @param raw [Hash]
+      # @return [Hash]
+      def migrated_fields(raw)
+        m = raw.dup
+        unless m.key?("from")
+          %w[mail_from from_mail from_email sender_address from_address
+             send_addr mail_addr address_from ho_from fromname fromS].each do |key|
+            v = m[key]
+            if v.is_a?(String) && v.strip != ""
+              m["from"] = v
+              break
+            end
+          end
+        end
+        if !m.key?("sender") && m["from"].is_a?(String) && m["from"].strip != ""
+          m["sender"] = m["from"]
+        end
+        m["id"] = m["mail_id"] if !m.key?("id") && m.key?("mail_id")
+        m["date"] = m["received_at"] if !m.key?("date") && m.key?("received_at")
+        m
+      end
+    end
+  end
+end