ilink 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e4a12ec6f693d67456b1f7cbd06a3bbf7251c15eff1fb963c8b3a6405c756970
+  data.tar.gz: '049ddfe910aa9100ee71bd83b61759830b8c48f12f4d1ae2fda49567395b9722'
+SHA512:
+  metadata.gz: 0b5eba8c115ef1030ad52b7271e37550b6615b1a643743d00571e278d8fd8826b2f585169e6e29f53721d6064db5f7b9d30f128721d42500a398491281a56454
+  data.tar.gz: 549c34e5ec1efcf19ad1baba056f264751ada594bf063be8ff12247aca447ff3dcff10678aee8f6986cf38d6c9c7ee2608153a48b12d41a2a0887d09a1f4dc85

data/README.md

@@ -0,0 +1,248 @@
+# ILink
+
+Ruby SDK for the WeChat iLink Bot API.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "ilink"
+```
+
+Or install directly:
+
+```sh
+gem install ilink
+```
+
+## Quick Start
+
+```ruby
+require "ilink"
+
+ILink.configure do |c|
+  c.token = "your_bot_token"
+end
+
+bot = ILink::Bot.new
+```
+
+## Configuration
+
+| Option              | Default                         | Description                                                     |
+| ------------------- | ------------------------------- | --------------------------------------------------------------- |
+| `base_url`          | `https://ilinkai.weixin.qq.com` | API base URL                                                    |
+| `token`             | `nil`                           | Bot token (Bearer auth)                                         |
+| `app_id`            | `"bot"`                         | iLink-App-Id header                                             |
+| `app_version`       | `"2.1.1"`                       | Client version string                                           |
+| `timeout`           | `15`                            | Default request timeout (seconds)                               |
+| `long_poll_timeout` | `35`                            | Long-poll timeout for `get_updates` / `qrcode_status` (seconds) |
+| `route_tag`         | `nil`                           | Optional SKRouteTag header                                      |
+
+Global configuration applies to all `Bot` instances. You can also override per-instance:
+
+```ruby
+bot = ILink::Bot.new(
+  token: "another_token",
+  base_url: "https://custom-host.example.com"
+)
+```
+
+## API Reference
+
+### QR Code Login
+
+```ruby
+bot = ILink::Bot.new
+
+# Step 1: Get a QR code
+qr = bot.qrcode
+puts qr[:qrcode_img_content]  # QR code image URL — show to user
+
+# Step 2: Poll scan status (long-poll, blocks until scanned or timeout)
+loop do
+  status = bot.qrcode_status(qrcode: qr[:qrcode])
+  case status[:status]
+  when "confirmed"
+    puts "Login success!"
+    puts "bot_token:     #{status[:bot_token]}"
+    puts "ilink_bot_id:  #{status[:ilink_bot_id]}"
+    puts "base_url:      #{status[:baseurl]}"
+    break
+  when "scaned"
+    puts "Scanned, waiting for confirmation..."
+  when "expired"
+    puts "QR code expired, request a new one"
+    break
+  when "scaned_but_redirect"
+    # IDC redirect — switch polling host
+    puts "Redirecting to #{status[:redirect_host]}"
+  end
+end
+```
+
+### Polling Messages
+
+```ruby
+bot = ILink::Bot.new(token: "your_bot_token")
+
+buf = ""
+loop do
+  resp = bot.get_updates(buf: buf)
+  buf = resp[:get_updates_buf] || buf
+
+  (resp[:msgs] || []).each do |msg|
+    from = msg[:from_user_id]
+    msg[:item_list]&.each do |item|
+      case item[:type]
+      when ILink::MessageItemType::TEXT
+        puts "#{from}: #{item[:text_item][:text]}"
+      when ILink::MessageItemType::IMAGE
+        puts "#{from}: [image] #{item[:image_item][:url]}"
+      end
+    end
+  end
+end
+```
+
+### Sending Messages
+
+```ruby
+# Send a simple text message
+bot.send_text(to: "user_id", text: "Hello from Ruby!")
+
+# Send with session ID
+bot.send_text(to: "user_id", text: "Reply in session", session_id: "session_123")
+
+# Send a custom message (image, file, video, etc.)
+bot.send_message({
+  to_user_id: "user_id",
+  message_type: ILink::MessageType::BOT,
+  message_state: ILink::MessageState::FINISH,
+  item_list: [
+    {
+      type: ILink::MessageItemType::IMAGE,
+      image_item: {
+        media: { encrypt_query_param: "...", aes_key: "..." }
+      }
+    }
+  ]
+})
+```
+
+### Media Upload
+
+```ruby
+resp = bot.upload_url(
+  media_type:  ILink::UploadMediaType::IMAGE,
+  to_user_id:  "user_id",
+  rawsize:     File.size("photo.jpg"),
+  rawfilemd5:  Digest::MD5.hexdigest(File.read("photo.jpg")),
+  filesize:    encrypted_size,
+  aeskey:      aes_key_hex
+)
+
+puts resp[:upload_full_url]        # Pre-signed upload URL
+puts resp[:upload_param]           # Upload encryption param
+puts resp[:thumb_upload_param]     # Thumbnail upload param (if applicable)
+```
+
+### Typing Indicators
+
+```ruby
+# Get the typing ticket first
+config = bot.get_config(user_id: "user_id")
+ticket = config[:typing_ticket]
+
+# Show "typing..."
+bot.send_typing(user_id: "user_id", ticket: ticket)
+
+# Cancel typing
+bot.cancel_typing(user_id: "user_id", ticket: ticket)
+```
+
+### Bot Config
+
+```ruby
+config = bot.get_config(user_id: "user_id", context_token: "optional_token")
+puts config[:typing_ticket]
+```
+
+## Constants
+
+```ruby
+ILink::UploadMediaType::IMAGE  # 1
+ILink::UploadMediaType::VIDEO  # 2
+ILink::UploadMediaType::FILE   # 3
+ILink::UploadMediaType::VOICE  # 4
+
+ILink::MessageType::USER       # 1
+ILink::MessageType::BOT        # 2
+
+ILink::MessageItemType::TEXT   # 1
+ILink::MessageItemType::IMAGE  # 2
+ILink::MessageItemType::VOICE  # 3
+ILink::MessageItemType::FILE   # 4
+ILink::MessageItemType::VIDEO  # 5
+
+ILink::MessageState::NEW        # 0
+ILink::MessageState::GENERATING # 1
+ILink::MessageState::FINISH     # 2
+
+ILink::TypingStatus::TYPING    # 1
+ILink::TypingStatus::CANCEL    # 2
+```
+
+## Error Handling
+
+```ruby
+begin
+  bot.send_text(to: "user_id", text: "hi")
+rescue ILink::AuthenticationError => e
+  puts "Auth failed (#{e.status}): #{e.body}"
+rescue ILink::ApiError => e
+  puts "API error (#{e.status}): #{e.body}"
+rescue Net::ReadTimeout
+  puts "Request timed out"
+end
+```
+
+## Full Echo Bot Example
+
+```ruby
+require "ilink"
+
+ILink.configure do |c|
+  c.token = ENV["ILINK_BOT_TOKEN"]
+end
+
+bot = ILink::Bot.new
+buf = ""
+
+puts "Bot started, waiting for messages..."
+
+loop do
+  resp = bot.get_updates(get_updates_buf: buf)
+  buf = resp[:get_updates_buf] || buf
+
+  (resp[:msgs] || []).each do |msg|
+    next unless msg[:message_type] == ILink::MessageType::USER
+
+    from = msg[:from_user_id]
+    msg[:item_list]&.each do |item|
+      next unless item[:type] == ILink::MessageItemType::TEXT
+
+      text = item.dig(:text_item, :text)
+      puts "Received: #{text} from #{from}"
+      bot.send_text(to: from, text: "Echo: #{text}", session_id: msg[:session_id])
+    end
+  end
+rescue ILink::ApiError => e
+  warn "API error: #{e.message}"
+  sleep 3
+end
+```
+
+## License
+
+MIT

data/lib/ilink/bot.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module ILink
+  # Main entry point for the iLink Bot API.
+  #
+  #   bot = ILink::Bot.new(token: "your_bot_token")
+  #   bot.get_updates
+  #   bot.send_text(to: "user_id", text: "Hello!")
+  #   bot.upload_url(media_type: 1, to_user_id: "user_id", ...)
+  #   bot.send_typing(user_id: "...", ticket: "...")
+  #   bot.get_config(user_id: "...")
+  #   bot.create_qr_code
+  #
+  class Bot
+    attr_reader :configuration
+
+    def initialize(token: nil, base_url: nil, **options)
+      @configuration = ILink.configuration.dup
+      @configuration.token    = token    if token
+      @configuration.base_url = base_url if base_url
+
+      options.each do |key, value|
+        @configuration.public_send(:"#{key}=", value) if @configuration.respond_to?(:"#{key}=")
+      end
+    end
+
+    # Long-poll for new messages.
+    #
+    # @param buf [String] opaque cursor from previous call ("" on first call)
+    # @return [Hash] parsed response with :ret, :msgs, :get_updates_buf, etc.
+    def get_updates(buf: "")
+      connection.post("/ilink/bot/getupdates",
+                       { get_updates_buf: buf },
+                       timeout: @configuration.long_poll_timeout)
+    rescue Net::ReadTimeout, Net::OpenTimeout
+      { ret: 0, msgs: [], get_updates_buf: buf }
+    end
+
+    # Send a message.
+    #
+    # @param message [Hash] a WeixinMessage hash with keys like :to_user_id, :item_list, etc.
+    # @return [Hash] parsed response
+    def send_message(message)
+      connection.post("/ilink/bot/sendmessage", { msg: message })
+    end
+
+    # Convenience: send a text message to a user.
+    #
+    # @param to [String] target user ID
+    # @param text [String] message text
+    # @param session_id [String, nil] optional session ID
+    # @return [Hash]
+    def send_text(to:, text:, session_id: nil)
+      message = {
+        to_user_id: to,
+        message_type: MessageType::BOT,
+        message_state: MessageState::FINISH,
+        item_list: [
+          { type: MessageItemType::TEXT, text_item: { text: text } }
+        ]
+      }
+      message[:session_id] = session_id if session_id
+      send_message(message)
+    end
+
+    # Get a pre-signed CDN upload URL.
+    #
+    # @param params [Hash] :filekey, :media_type, :to_user_id, :rawsize, :rawfilemd5,
+    #   :filesize, :aeskey, :thumb_rawsize, :thumb_rawfilemd5, :thumb_filesize, :no_need_thumb
+    # @return [Hash] { upload_param:, thumb_upload_param:, upload_full_url: }
+    def upload_url(**params)
+      connection.post("/ilink/bot/getuploadurl", params)
+    end
+
+    # Send a typing indicator.
+    #
+    # @param user_id [String] ilink user ID
+    # @param ticket  [String] typing ticket (from get_config)
+    # @return [Hash]
+    def send_typing(user_id:, ticket:)
+      set_typing(user_id: user_id, ticket: ticket, status: TypingStatus::TYPING)
+    end
+
+    # Cancel a typing indicator.
+    #
+    # @param user_id [String] ilink user ID
+    # @param ticket  [String] typing ticket
+    # @return [Hash]
+    def cancel_typing(user_id:, ticket:)
+      set_typing(user_id: user_id, ticket: ticket, status: TypingStatus::CANCEL)
+    end
+
+    def set_typing(user_id:, ticket:, status:)
+      connection.post("/ilink/bot/sendtyping", {
+        ilink_user_id: user_id,
+        typing_ticket: ticket,
+        status: status
+      }, timeout: 10)
+    end
+
+    # Fetch bot config for a user (includes typing_ticket).
+    #
+    # @param user_id       [String]      ilink user ID
+    # @param context_token [String, nil] optional context token
+    # @return [Hash] { ret:, typing_ticket:, ... }
+    def get_config(user_id:, context_token: nil)
+      body = { ilink_user_id: user_id, context_token: context_token }.compact
+      connection.post("/ilink/bot/getconfig", body, timeout: 10)
+    end
+
+    # Request a new QR code for login.
+    #
+    # @param bot_type [String] bot type identifier (default "3")
+    # @return [Hash] { qrcode:, qrcode_img_content: }
+    def qrcode(bot_type: "3")
+      connection.get("/ilink/bot/get_bot_qrcode?bot_type=#{URI.encode_www_form_component(bot_type)}", timeout: 5)
+    end
+
+    # Poll QR code scan status (long-poll).
+    #
+    # @param qrcode [String] qrcode value from #create_qr_code
+    # @return [Hash] { status:, bot_token:, ilink_bot_id:, baseurl:, ilink_user_id:, redirect_host: }
+    def qrcode_status(qrcode:)
+      connection.get("/ilink/bot/get_qrcode_status?qrcode=#{URI.encode_www_form_component(qrcode)}",
+                      timeout: @configuration.long_poll_timeout)
+    rescue Net::ReadTimeout, Net::OpenTimeout
+      { status: "wait" }
+    end
+
+    private
+      def connection
+        Connection.new(@configuration)
+      end
+  end
+end

data/lib/ilink/configuration.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module ILink
+  class Configuration
+    attr_accessor :base_url, :token
+    attr_accessor :app_id, :app_version
+    attr_accessor :timeout, :long_poll_timeout, :route_tag
+
+    DEFAULT_BASE_URL          = "https://ilinkai.weixin.qq.com"
+    DEFAULT_APP_ID            = "bot"
+    DEFAULT_APP_VERSION       = "2.1.1"
+    DEFAULT_TIMEOUT           = 15
+    DEFAULT_LONG_POLL_TIMEOUT = 35
+
+    def initialize
+      @base_url          = DEFAULT_BASE_URL
+      @app_id            = DEFAULT_APP_ID
+      @app_version       = DEFAULT_APP_VERSION
+      @timeout           = DEFAULT_TIMEOUT
+      @long_poll_timeout = DEFAULT_LONG_POLL_TIMEOUT
+      @token             = nil
+      @route_tag         = nil
+    end
+
+    # Encode version string "M.N.P" as uint32: 0x00MMNNPP
+    def client_version_int
+      parts = (app_version || "0.0.0").split(".").map(&:to_i)
+      ((parts[0] & 0xFF) << 16) | ((parts[1].to_i & 0xFF) << 8) | (parts[2].to_i & 0xFF)
+    end
+  end
+end

data/lib/ilink/connection.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "uri"
+require "json"
+require "base64"
+require "securerandom"
+require "net/http"
+
+module ILink
+  # Low-level HTTP connection using Ruby's built-in net/http.
+  # Builds proper iLink headers, handles timeouts, and parses JSON responses.
+  class Connection
+    attr_reader :config
+
+    def initialize(config)
+      @config = config
+    end
+
+    def get(endpoint, timeout: config.timeout, headers: {})
+      uri = build_uri(endpoint)
+      request = Net::HTTP::Get.new(uri)
+      common_headers.merge(headers).each { |k, v| request[k] = v }
+
+      execute(uri, request, timeout: timeout)
+    end
+
+    def post(endpoint, body = {}, timeout: config.timeout, headers: {})
+      uri = build_uri(endpoint)
+      payload = body.merge(base_info: { channel_version: config.app_version })
+      json_body = JSON.generate(payload)
+
+      request = Net::HTTP::Post.new(uri)
+      post_headers.merge(headers).each { |k, v| request[k] = v }
+      request.body = json_body
+
+      execute(uri, request, timeout: timeout)
+    end
+
+    private
+      def build_uri(endpoint)
+        URI.join(config.base_url.to_s, endpoint)
+      end
+
+      def common_headers
+        headers = {
+          "iLink-App-Id"            => config.app_id,
+          "iLink-App-ClientVersion" => config.client_version_int.to_s
+        }
+        headers["SKRouteTag"] = config.route_tag if config.route_tag
+        headers
+      end
+
+      def post_headers
+        headers = common_headers.merge(
+          "Content-Type"      => "application/json",
+          "AuthorizationType" => "ilink_bot_token",
+          "X-WECHAT-UIN"     => random_wechat_uin
+        )
+        headers["Authorization"] = "Bearer #{config.token}" if config.token
+        headers
+      end
+
+      def random_wechat_uin
+        uint32 = SecureRandom.random_number(2**32)
+        Base64.strict_encode64(uint32.to_s)
+      end
+
+      def execute(uri, request, timeout:)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl       = (uri.scheme == "https")
+        http.open_timeout  = [timeout, 10].min
+        http.read_timeout  = timeout
+        http.write_timeout = timeout
+
+        response = http.request(request)
+        handle_response(response)
+      end
+
+      def handle_response(response)
+        case response.code.to_i
+        when 200..299
+          body = response.body.to_s
+          body.empty? ? {} : JSON.parse(body, symbolize_names: true)
+        when 401, 403
+          raise AuthenticationError.new(response.code.to_i, response.body)
+        else
+          raise ApiError.new(response.code.to_i, response.body)
+        end
+      end
+  end
+end

data/lib/ilink/constants.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ILink
+  # Media type for upload requests
+  module UploadMediaType
+    IMAGE = 1
+    VIDEO = 2
+    FILE  = 3
+    VOICE = 4
+  end
+
+  # Message sender type
+  module MessageType
+    NONE = 0
+    USER = 1
+    BOT  = 2
+  end
+
+  # Message content type
+  module MessageItemType
+    NONE  = 0
+    TEXT  = 1
+    IMAGE = 2
+    VOICE = 3
+    FILE  = 4
+    VIDEO = 5
+  end
+
+  # Message lifecycle state
+  module MessageState
+    NEW        = 0
+    GENERATING = 1
+    FINISH     = 2
+  end
+
+  # Typing indicator status
+  module TypingStatus
+    TYPING = 1
+    CANCEL = 2
+  end
+end

data/lib/ilink/errors.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ILink
+  class Error < StandardError; end
+
+  # Raised on non-2xx HTTP responses
+  class ApiError < Error
+    attr_reader :status, :body
+
+    def initialize(status, body)
+      @status = status
+      @body   = body
+      super("iLink API error #{status}: #{body}")
+    end
+  end
+
+  # Raised when long-poll times out.
+  class TimeoutError < Error; end
+
+  # Raised on authentication failures (401/403)
+  class AuthenticationError < ApiError; end
+end

data/lib/ilink/resources/messages.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module ILink
+  module Resources
+    # RESTful resource for message operations.
+    #
+    #   bot.messages.get_updates - long-poll for new messages (getUpdates)
+    #   bot.messages.send(msg)   - send a message to a user
+    class Messages < Base
+      # Long-poll for new messages.
+      #
+      # @param get_updates_buf [String] opaque cursor from previous poll ("" on first call)
+      # @return [Hash] parsed response with :ret, :msgs, :get_updates_buf, etc.
+      def poll(get_updates_buf: "")
+        post("/ilink/bot/getupdates",
+             { get_updates_buf: get_updates_buf },
+             timeout: connection.config.long_poll_timeout)
+      rescue Net::ReadTimeout, Net::OpenTimeout
+        # Long-poll timeout is normal; return empty response so caller can retry
+        { ret: 0, msgs: [], get_updates_buf: get_updates_buf }
+      end
+
+      # Send a message.
+      #
+      # @param message [Hash] a WeixinMessage hash with keys like :to_user_id, :item_list, etc.
+      # @return [Hash] parsed response
+      def send(message)
+        post("/ilink/bot/sendmessage", { msg: message })
+      end
+
+      # Convenience: send a text message to a user.
+      #
+      # @param to [String] target user ID
+      # @param text [String] message text
+      # @param session_id [String, nil] optional session ID
+      # @return [Hash]
+      def send_text(to:, text:, session_id: nil)
+        message = {
+          to_user_id: to,
+          message_type: MessageType::BOT,
+          message_state: MessageState::FINISH,
+          item_list: [
+            {
+              type: MessageItemType::TEXT,
+              text_item: { text: text }
+            }
+          ]
+        }
+        message[:session_id] = session_id if session_id
+        send(message)
+      end
+    end
+  end
+end

data/lib/ilink/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ILink
+  VERSION = "0.1.2"
+end

data/lib/ilink.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "ilink/version"
+require_relative "ilink/errors"
+require_relative "ilink/constants"
+require_relative "ilink/configuration"
+require_relative "ilink/connection"
+require_relative "ilink/bot"
+
+module ILink
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: ilink
+version: !ruby/object:Gem::Version
+  version: 0.1.2
+platform: ruby
+authors:
+- Songji Zeng
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |
+  A lightweight Ruby SDK for building WeChat bots via the iLink Bot API.
+  Handles QR login, long-polling for messages, sending replies, and typing indicators.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/ilink.rb
+- lib/ilink/bot.rb
+- lib/ilink/configuration.rb
+- lib/ilink/connection.rb
+- lib/ilink/constants.rb
+- lib/ilink/errors.rb
+- lib/ilink/resources/messages.rb
+- lib/ilink/version.rb
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.9
+specification_version: 4
+summary: Ruby SDK for the WeChat iLink Bot API
+test_files: []