khl 1.0.0

data/lib/khl/http/guild.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module KHL
+  module HTTP
+    # 服务器相关接口
+    # https://developer.kaiheila.cn/doc/http/guild
+    class Guild < Base
+      # 获取当前用户加入的服务器列表
+      # @param [Hash] options 可选参数
+      # @option options [Integer] :page 页数
+      # @option options [Integer] :page_size 每页数据数量
+      # @option options [String] :sort 代表排序的字段，比如 -id 代表 id 按 DESC 排序，id 代表 id 按 ASC 排序
+      # @return [KHL::HTTP::Response]
+      def list(options = {})
+        get(options)
+      end
+
+      # 获取服务器详情
+      # @param [String] guild_id 服务器 ID
+      # @return [KHL::HTTP::Response]
+      def view(guild_id)
+        get(guild_id: guild_id)
+      end
+
+      # 获取服务器中的用户列表
+      # @param [String] guild_id 服务器 ID
+      # @param [Hash] options 可选参数
+      # @option options [String] :channel_id 频道 ID
+      # @option options [String] :search 搜索关键字，在用户名或昵称中搜索
+      # @option options [Integer] :role_id 角色 ID，获取特定角色的用户列表
+      # @option options [Integer] :mobile_verified 只能为 0 或 1，0 是未认证，1 是已认证
+      # @option options [Integer] :active_time 根据活跃时间排序，0 是顺序排列，1 是倒序排列
+      # @option options [Integer] :joined_at 根据加入时间排序，0 是顺序排列，1 是倒序排列
+      # @option options [Integer] :page 页数
+      # @option options [Integer] :page_size 每页数据数量
+      # @option options [String] :filter_user_id 获取指定 ID 所属用户的信息
+      # @return [KHL::HTTP::Response]
+      def user_list(guild_id, options = {})
+        get(options.merge(guild_id: guild_id))
+      end
+
+      # 修改服务器中用户的昵称
+      # @param [String] guild_id 服务器 ID
+      # @param [Hash] options 可选参数
+      # @option options [String] :nickname 昵称，2-64 长度，不传则清空昵称
+      # @option options [String] :user_id 用户 ID，不传则修改当前登陆用户的昵称
+      # @return [KHL::HTTP::Response]
+      def nickname(guild_id, options = {})
+        post(options.merge(guild_id: guild_id))
+      end
+
+      # 离开服务器
+      # @param [String] guild_id 服务器 ID
+      # @return [KHL::HTTP::Response]
+      def leave(guild_id)
+        post(guild_id: guild_id)
+      end
+
+      # 踢出服务器
+      # @param [String] guild_id 服务器 ID
+      # @param [String] target_id 用户 ID
+      # @return [KHL::HTTP::Response]
+      def kickout(guild_id, target_id)
+        post(guild_id: guild_id, target_id: target_id)
+      end
+    end
+  end
+end

data/lib/khl/http/guild_emoji.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module KHL
+  module HTTP
+    # 服务器表情相关接口
+    # https://developer.kaiheila.cn/doc/http/guild-emoji
+    class GuildEmoji < Base
+      # 获取服务器表情列表
+      # @param [String] guild_id 服务器 ID
+      # @param [Hash] options 可选参数
+      # @option options [Integer] :page 页数
+      # @option options [Integer] :page_size 每页数据数量
+      # @return [KHL::HTTP::Response]
+      def list(guild_id, options = {})
+        get(options.merge(guild_id: guild_id))
+      end
+
+      # 创建服务器表情
+      # @param [String] guild_id 服务器 ID
+      # @param [IO] emoji 表情文件。必须为 PNG 类型，大小不能超过 256 KB
+      # @param [Hash] options 可选参数
+      # @option options [String] :name 表情名。长度限制 2-32 字符，如果不写，则为随机字符串
+      # @return [KHL::HTTP::Response]
+      def create(guild_id, emoji, options = {})
+        post_file(options.merge(content_type: "multipart/form-data", guild_id: guild_id, emoji: emoji))
+      end
+
+      # 更新服务器表情
+      # @param [String] name 表情名。长度限制 2-32 字符，如果不写，则为随机字符串
+      # @param [String] id 表情 ID
+      # @return [KHL::HTTP::Response]
+      def update(name, id)
+        post(name: name, id: id)
+      end
+
+      # 删除服务器表情
+      # @param [String] id 表情 ID
+      # @return [KHL::HTTP::Response]
+      def delete(id)
+        post(id: id)
+      end
+    end
+  end
+end

data/lib/khl/http/guild_mute.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module KHL
+  module HTTP
+    # 服务器静音闭麦相关接口
+    # https://developer.kaiheila.cn/doc/http/guild
+    class GuildMute < Base
+      # 服务器静音闭麦列表
+      # @param [String] guild_id 服务器 ID
+      # @param [Hash] options 可选参数
+      # @option options [String] :return_type 返回格式，建议为 "detail", 其他情况仅作为兼容
+      # @return [KHL::HTTP::Response]
+      def list(guild_id, options = {})
+        get(options.merge(guild_id: guild_id))
+      end
+
+      # 添加服务器静音或闭麦
+      # @param [String] guild_id 服务器 ID
+      # @param [String] user_id 用户 ID
+      # @param [Integer] type 静音类型，1 代表麦克风闭麦，2 代表耳机静音
+      # @return [KHL::HTTP::Response]
+      def create(guild_id, user_id, type)
+        post(guild_id: guild_id, user_id: user_id, type: type)
+      end
+
+      # 删除服务器静音或闭麦
+      # @param [String] guild_id 服务器 ID
+      # @param [String] user_id 用户 ID
+      # @param [Integer] type 静音类型，1 代表麦克风闭麦，2 代表耳机静音
+      # @return [KHL::HTTP::Response]
+      def delete(guild_id, user_id, type)
+        post(guild_id: guild_id, user_id: user_id, type: type)
+      end
+    end
+  end
+end

data/lib/khl/http/guild_role.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module KHL
+  module HTTP
+    # 服务器角色权限相关接口
+    # https://developer.kaiheila.cn/doc/http/guild-role
+    class GuildRole < Base
+      # 获取服务器角色列表
+      # @param [String] guild_id 服务器 ID
+      # @param [Hash] options 可选参数
+      # @option options [Integer] :page 页数
+      # @option options [Integer] :page_size 每页数据数量
+      # @return [KHL::HTTP::Response]
+      def list(guild_id, options = {})
+        get(options.merge(guild_id: guild_id))
+      end
+
+      # 创建服务器角色
+      # @param [String] guild_id 服务器 ID
+      # @param [Hash] options 可选参数
+      # @option options [String] :name 角色名称，如果不写，则为 "新角色"
+      # @return [KHL::HTTP::Response]
+      def create(guild_id, options = {})
+        post(options.merge(guild_id: guild_id))
+      end
+
+      # 更新服务器角色
+      # @param [String] guild_id 服务器 ID
+      # @param [Integer] role_id 角色 ID
+      # @param [Hash] options 可选参数
+      # @option options [String] :name 角色名称
+      # @option options [Integer] :color 颜色
+      # @option options [Integer] :hoist 只能为 0 或者 1，是否把该角色的用户在用户列表排到前面
+      # @option options [Integer] :mentionable 只能为 0 或者 1，该角色是否可以被提及
+      # @option options [Integer] :permissions 权限
+      # @return [KHL::HTTP::Response]
+      def update(guild_id, role_id, options = {})
+        post(options.merge(guild_id: guild_id, role_id: role_id))
+      end
+
+      # 删除服务器角色
+      # @param [String] guild_id 服务器 ID
+      # @param [Integer] role_id 角色 ID
+      # @return [KHL::HTTP::Response]
+      def delete(guild_id, role_id)
+        post(guild_id: guild_id, role_id: role_id)
+      end
+
+      # 赋予用户角色
+      # @param [String] guild_id 服务器 ID
+      # @param [String] user_id 用户 ID
+      # @param [Integer] role_id 角色 ID
+      # @return [KHL::HTTP::Response]
+      def grant(guild_id, user_id, role_id)
+        post(guild_id: guild_id, user_id: user_id, role_id: role_id)
+      end
+
+      # 删除用户角色
+      # @param [String] guild_id 服务器 ID
+      # @param [String] user_id 用户 ID
+      # @param [Integer] role_id 角色 ID
+      # @return [KHL::HTTP::Response]
+      def revoke(guild_id, user_id, role_id)
+        post(guild_id: guild_id, user_id: user_id, role_id: role_id)
+      end
+    end
+  end
+end

data/lib/khl/http/intimacy.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module KHL
+  module HTTP
+    # 亲密度相关接口
+    # https://developer.kaiheila.cn/doc/http/intimacy
+    class Intimacy < Base
+      # 获取用户亲密度
+      # @param [String] user_id 用户 ID
+      # @return [KHL::HTTP::Response]
+      def index(user_id)
+        get(user_id: user_id)
+      end
+
+      # 更新用户亲密度
+      # @param [String] user_id 用户 ID
+      # @param [Hash] options 可选参数
+      # @option options [Integer] :score 亲密度，0-2200
+      # @option options [String] :social_info 机器人与用户的社交信息，500 字以内
+      # @option options [String] :img_id 表情 ID
+      # @return [KHL::HTTP::Response]
+      def update(user_id, options = {})
+        post(options.merge(user_id: user_id))
+      end
+    end
+  end
+end

data/lib/khl/http/invite.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module KHL
+  module HTTP
+    # 邀请相关接口
+    # https://developer.kaiheila.cn/doc/http/invite
+    class Invite < Base
+      # 获取邀请列表
+      # @param [Hash] options 可选参数
+      # @option options [String] :guild_id 服务器 ID
+      # @option options [String] :channel_id 频道 ID
+      # @option options [Integer] :page 页数
+      # @option options [Integer] :page_size 每页数据数量
+      # @return [KHL::HTTP::Response]
+      def list(options = {})
+        get(options)
+      end
+
+      # 创建邀请链接
+      # @option options [String] :guild_id 服务器 ID
+      # @option options [String] :channel_id 频道 ID
+      # @option options [Integer] :duration 邀请链接有效时长（秒），默认 7 天。
+      #   可选值： 0（永不）、1800（0.5 小时）、3600（1 小时）、21600（6 小时）、43200（12小时）、86400（1 天）、604800（7 天）
+      # @option options [Integer] :setting_times 设置的次数，默认-1。可选值：-1（无限制）、1、5、10、25、50、100
+      # @return [KHL::HTTP::Response]
+      def create(options = {})
+        post(options)
+      end
+
+      # 删除邀请链接
+      # @param [String] url_code 邀请码
+      # @param [Hash] options 可选参数
+      # @option options [String] :guild_id 服务器 ID
+      # @option options [String] :channel_id 频道 ID
+      # @return [KHL::HTTP::Response]
+      def delete(url_code, options = {})
+        post(options.merge(url_code: url_code))
+      end
+    end
+  end
+end

data/lib/khl/http/message.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module KHL
+  module HTTP
+    # 频道消息相关接口
+    # https://developer.kaiheila.cn/doc/http/message
+    class Message < Base
+      # 获取频道聊天消息列表
+      # @note 此接口非标准分页，需要根据参考消息来查询相邻分页的消息
+      # @param [String] target_id 频道 ID
+      # @param [Hash] options 可选参数
+      # @option options [String] :msg_id 参考消息 ID，不传则查询最新消息
+      # @option options [Integer] :pin 只能为 0 或者 1，是否查询置顶消息。置顶消息只支持查询最新的消息
+      # @option options [String] :flag 查询模式，有三种模式可以选择 before、around、after。不传则默认查询最新的消息
+      # @option options [Integer] :page_size 当前分页消息数量，默认 50
+      # @return [KHL::HTTP::Response]
+      def list(target_id, options = {})
+        get(options.merge(target_id: target_id))
+      end
+
+      # 获取频道聊天消息详情
+      # @param [String] msg_id 消息 ID
+      # @return [KHL::HTTP::Response]
+      def view(msg_id)
+        get(msg_id: msg_id)
+      end
+
+      # 发送频道聊天消息
+      # @note 此接口与频道相关接口下的 "发送频道聊天消息" 功能相同
+      # @warning 强列建议过滤掉机器人发送的消息，再进行回应。否则会很容易形成两个机器人循环自言自语导致发送量过大，进而导致机器人被封禁。如果确实需要机器人联动的情况，慎重进行处理，防止形成循环
+      # @param [String] target_id 频道 ID
+      # @param [String] content 消息内容
+      # @param [Hash] options 可选参数
+      # @option options [Integer] :type 消息类型，不传默认为 1，代表文本类型。9 代表 kmarkdown 消息，10 代表卡片消息
+      # @option options [String] :quote 回复某条消息的 msg_id
+      # @option options [String] :nonce 随机字符串，服务端不做处理，原样返回
+      # @option options [String] :temp_target_id 用户 ID，如果传了，代表该消息是临时消息，该消息不会存数据库，但是会在频道内只给该用户推送临时消息。用于在频道内针对用户的操作进行单独的回应通知等
+      # @return [KHL::HTTP::Response]
+      def create(target_id, content, options = {})
+        post(options.merge(target_id: target_id, content: content))
+      end
+
+      # 更新频道聊天消息
+      # @note 目前支持消息 type 为 9、10 的修改，即 KMarkdown 和 CardMessage
+      # @param [String] msg_id 消息 ID
+      # @param [String] content 消息内容
+      # @param [Hash] options 可选参数
+      # @option options [String] :quote 回复某条消息的 msg_id。如果为空，则代表删除回复，不传则无影响
+      # @option options [String] :temp_target_id 用户 ID，针对特定用户临时更新消息，必须是正常消息才能更新。与发送临时消息概念不同，但同样不保存数据库
+      # @return [KHL::HTTP::Response]
+      def update(msg_id, content, options = {})
+        post(options.merge(msg_id: msg_id, content: content))
+      end
+
+      # 删除频道聊天消息
+      # @note 普通用户只能删除自己的消息，有权限的用户可以删除权限范围内他人的消息
+      # @param [String] msg_id 消息 ID
+      # @return [KHL::HTTP::Response]
+      def delete(msg_id)
+        post(msg_id: msg_id)
+      end
+
+      # 获取频道消息某回应的用户列表
+      # @param [String] msg_id 频道消息 ID
+      # @param [String] emoji Emoji ID，可以为 GuilEmoji 或者 Emoji，注意：在 GET 中，应该进行 urlencode
+      # @return [KHL::HTTP::Response]
+      def reaction_list(msg_id, emoji)
+        get(msg_id: msg_id, emoji: emoji)
+      end
+
+      # 给某个消息添加回应
+      # @param [String] msg_id 频道消息 ID
+      # @param [String] emoji Emoji ID，可以为 GuilEmoji 或者 Emoji，注意：在 GET 中，应该进行 urlencode
+      # @return [KHL::HTTP::Response]
+      def add_reaction(msg_id, emoji)
+        post(msg_id: msg_id, emoji: emoji)
+      end
+
+      # 删除消息的某个回应
+      # @param [String] msg_id 频道消息 ID
+      # @param [String] emoji Emoji ID，可以为 GuilEmoji 或者 Emoji，注意：在 GET 中，应该进行 urlencode
+      # @param [Hash] options 可选参数
+      # @option options [String] :user_id 用户 ID, 如果不填则为自己的 ID。删除别人的回应需要有管理频道消息的权限
+      # @return [KHL::HTTP::Response]
+      def delete_reaction(msg_id, emoji, options = {})
+        post(options.merge(msg_id: msg_id, emoji: emoji))
+      end
+    end
+  end
+end

data/lib/khl/http/response.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module KHL
+  module HTTP
+    class Response
+      attr_reader :http_code, :body
+
+      # @param [Net::HTTPResponse] raw_response The raw HTTP response
+      def initialize(raw_response)
+        @raw_response = raw_response
+        @http_code = raw_response.code.to_i
+        @body = JSON.parse(@raw_response.body)
+      end
+
+      def data
+        @body["data"]
+      end
+
+      # The code in the response body
+      def code
+        @body["code"]
+      end
+
+      def max_request_limit
+        @raw_response["X-Rate-Limit-Limit"].to_i
+      end
+
+      def remain_request_limit
+        @raw_response["X-Rate-Limit-Remaining"].to_i
+      end
+
+      def reset_limit_time
+        @raw_response["X-Rate-Limit-Reset"].to_i
+      end
+
+      def limit_bucket
+        @raw_response["X-Rate-Limit-Bucket"]
+      end
+
+      def limit?
+        @http_code == 429 || !@raw_response["X-Rate-Limit-Global"].nil?
+      end
+
+      def success?
+        http_code == 200 && code.zero?
+      end
+
+      def error?
+        !success?
+      end
+
+      def message
+        @body["message"]
+      end
+
+      def page
+        data.dig("meta", "page") || 0
+      end
+
+      def page_size
+        data.dig("meta", "page_size") || 0
+      end
+
+      def page_total
+        data.dig("meta", "total") || 0
+      end
+    end
+  end
+end

data/lib/khl/http/user.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module KHL
+  module HTTP
+    # 用户相关接口
+    # https://developer.kaiheila.cn/doc/http/user
+    class User < Base
+      # 获取当前用户信息
+      # @return [KHL::HTTP::Response]
+      def me
+        get
+      end
+
+      # 获取目标用户信息
+      # @param [String] user_id 用户 ID
+      # @param [Hash] options 可选参数
+      # @option options [String] :guild_id 服务器 ID
+      # @return [KHL::HTTP::Response]
+      def view(user_id, options = {})
+        get(options.merge(user_id: user_id))
+      end
+
+      # 下线机器人
+      # @return [KHL::HTTP::Response]
+      def offline
+        post
+      end
+    end
+  end
+end

data/lib/khl/http/user_chat.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module KHL
+  module HTTP
+    # 私信聊天会话相关接口
+    # https://developer.kaiheila.cn/doc/http/user-chat
+    class UserChat < Base
+      # 获取私信聊天会话列表
+      # @param [Hash] options 可选参数
+      # @option options [Integer] :page 页数
+      # @option options [Integer] :page_size 每页数据数量
+      # @return [KHL::HTTP::Response]
+      def list(options = {})
+        get(options)
+      end
+
+      # 获取私信聊天会话详情
+      # @param [String] chat_code 私聊会话 Code
+      # @return [KHL::HTTP::Response]
+      def view(chat_code)
+        get(chat_code: chat_code)
+      end
+
+      # 创建私信聊天会话
+      # @param [String] target_id 用户 ID
+      # @return [KHL::HTTP::Response]
+      def create(target_id)
+        post(target_id: target_id)
+      end
+
+      # 删除私信聊天会话
+      # @note 只能删除自己的消息
+      # @param [String] target_id 用户 ID
+      # @return [KHL::HTTP::Response]
+      def delete(target_id)
+        post(target_id: target_id)
+      end
+    end
+  end
+end

data/lib/khl/version.rb

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

data/lib/khl/web_socket/client.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "eventmachine"
+require "faye/websocket"
+require "json"
+require "uri"
+require "zlib"
+
+require_relative "message"
+
+module KHL
+  module WebSocket
+    # Client for the KHL WebSocket API
+    # @example
+    # client = KHL::WebSocket.new(token: "bot_token")
+    # Thread.new { client.run }
+    # client.message.pop # Get message from queue
+    class Client
+      attr_reader :config, :url, :messages, :state
+
+      # @param config [String] :token Bot token
+      # @option config [String] :token_type Token type
+      # @option config [String] :language Language
+      # @option config [Boolean] :compress Compress
+      def initialize(config)
+        config[:compress] ||= false
+
+        @config = config
+        @http_gateway = HTTP::Gateway.new(config)
+        @url = gateway_url
+        @messages = Queue.new
+        @sn = 0
+        @state = :disconnected
+        @ping_signal = false
+        @resume_signal = false
+        @ws = nil
+      end
+
+      # Only receive messages from the server
+      def run
+        EM.run {
+          Signal.trap("INT") { EventMachine.stop }
+          Signal.trap("TERM") { EventMachine.stop }
+
+          @ws = Faye::WebSocket::Client.new(gateway_url)
+          @state = :connecting
+
+          EventMachine.add_periodic_timer(30) do
+            EventMachine.add_timer(6) do
+              if @ping_signal
+                @state = :timeout
+
+                unless reconnect
+                  unless resume
+                    @state = :disconnected
+                    EventMachine.stop
+                    rerun
+                  end
+                end
+              end
+            end
+
+            # Send ping message
+            @ws.send({s: 2, sn: @sn}.to_json)
+            @ping_signal = true
+          end
+
+          @ws.on :message do |event|
+            raw = config[:compress] ? Zlib::Inflate.inflate(event.data.pack("C*")) : event.data
+            msg = Message.parse(raw)
+
+            if msg.hello?
+              @state = :connected
+            elsif msg.pong?
+              @ping_signal = false
+            elsif msg.resume_ack?
+              @resume_signal = false
+            elsif msg.reconnect?
+              @state = :reconnecting
+              rerun
+            elsif msg.event?
+              messages << msg
+              @sn = msg.sn
+            end
+          end
+        }
+      end
+
+      private
+
+      def gateway_url
+        response = @http_gateway.index
+        return nil unless response.success?
+
+        uri = URI(response.data["url"])
+        query = CGI.parse(uri.query)
+        query["compress"] = config[:compress] ? 1 : 0
+        uri.query = URI.encode_www_form(query)
+        uri.to_s
+      end
+
+      def reconnect
+        @state = :reconnecting
+        @ping_signal = false
+
+        @ws.send({s: 2, sn: @sn}.to_json)
+        @ping_signal = true
+        sleep(2)
+        return true unless @ping_signal
+
+        @ws.send({s: 2, sn: @sn}.to_json)
+        @ping_signal = true
+        sleep(4)
+        return true unless @ping_signal
+
+        false
+      end
+
+      def resume
+        @state = :resuming
+        @resume_signal = false
+
+        @ws.send({s: 4, sn: @sn}.to_json)
+        @resume_signal = true
+        sleep(8)
+        return true unless @resume_signal
+
+        @ws.send({s: 4, sn: @sn}.to_json)
+        @resume_signal = true
+        sleep(16)
+        return true unless @resume_signal
+
+        false
+      end
+
+      def rerun
+        @url = gateway_url
+        @messages.clear
+        @sn = 0
+        @state = :disconnected
+        @ping_signal = false
+        @resume_signal = false
+        @ws = nil
+
+        EventMachine.stop
+        run
+      end
+    end
+  end
+end