xiaomi-push 0.2.4 → 0.3.0

data/bin/xmp

@@ -6,7 +6,7 @@ require 'bundler/setup'
 require 'xiaomi/push'
 
 program :version, Xiaomi::Push::VERSION
-program :description, 'xiaomi push command line tool'
+program :description, '小米推送命令行工具'
 
 program :help, 'Author', 'icyleaf'
 program :help, 'Website', 'icyleaf.cn@gmail.com'

data/lib/xiaomi/push.rb

@@ -3,9 +3,12 @@ require 'xiaomi/push/error'
 require 'xiaomi/push/const'
 require 'xiaomi/push/client'
 
-require 'xiaomi/push/devices/ios'
-require 'xiaomi/push/devices/android'
+require 'xiaomi/push/platforms/ios'
+require 'xiaomi/push/platforms/android'
 
 require 'xiaomi/push/services/message'
+require 'xiaomi/push/services/messages'
 require 'xiaomi/push/services/topic'
-require 'xiaomi/push/services/feedback'
+require 'xiaomi/push/services/user'
+require 'xiaomi/push/services/job'
+require 'xiaomi/push/services/feedback'

data/lib/xiaomi/push/client.rb

@@ -1,42 +1,96 @@
-require "rest-client"
-require "multi_json"
+require 'http'
+require 'json'
 
 module Xiaomi
   module Push
+    # 小米推送内置客户端
+    #
+    # 实际情况并不会直接被使用，而是使用 iOS 或 Android 的实例化
+    #
+    # @example 实例化 iOS 推送客户端(环境使用 :sandbox)
+    #   client = Xiaomi::Push::IOS('Fill your app secret', :sandbox)
+    # @example 实例化 Android 推送客户端
+    #   client = Xiaomi::Push::Android('Fill your app secret')
+    #
+    # @see https://dev.mi.com/console/doc/detail?pId=68 小米推送服务启用指南
     class Client
       include Const
 
-      attr_reader :device, :secret, :header
-      def initialize(secret)
-        @device = self.class.name.split('::')[-1].upcase
-        @secret = secret
+      attr_reader :device, :client
 
-        unless DEVICES.include?@device
-          raise NameError, 'Instance using Xiaomi::Push::Android or Xiaomi::Push::IOS'
-        end
+      # 实例化一个新的客户端
+      #
+      # @see https://dev.mi.com/console/doc/detail?pId=68 小米推送服务启用指南
+      #
+      # @param [String] secret 小米应用的 App Secret
+      # @param [Symbol] env 推送环境，可用的环境有 :production/:sandbox
+      #
+      # @raise [RequestError] 必须使用 Xiaomi::Push::Android 或 Xiaomi::Push::IOS 实例化
+      # @raise [RequestError] Android 使用 sandbox 推送环境引发异常
+      def initialize(secret, env = :production)
+        @device = self.class.name.split('::')[-1].upcase
+        @client = HTTP.headers(authorization: "key=#{secret}")
 
-        @header = {
-          'Authorization' => "key=#{@secret}"
-        }
+        determine_platform!(env)
 
-        use_production!
+        env == :production ? use_production! : use_sandbox!
       end
 
+      # 单条消息
       def message
         @message ||= Services::Message.new(self)
       end
 
+      # 多条消息
+      def messages
+        @messages ||= Services::Messages.new(self)
+      end
+
+      # 标签
       def topic
         @topic ||= Services::Topic.new(self)
       end
 
+      # 用户查询
+      def user
+        @user ||= Services::User.new(self)
+      end
+
+      # Feedback
       def feedback
         @feedback ||= Services::Feedback.new(self)
       end
 
-      def request(url, params)
-        r = RestClient.post url, params, @header
-        data = MultiJson.load r
+      # 以 GET 方式的网络请求
+      #
+      # @param [String] url
+      # @param [Hash] params
+      # @return [Hash] 小米返回数据结构
+      def get(url, params = nil)
+        r = @client.get(url, params: params)
+        data = JSON.parse(r)
+      end
+
+      # 以 POST 方式的网络请求
+      #
+      # @param [String] url
+      # @param [Hash] params
+      # @return [Hash] 小米返回数据结构
+      def post(url, params = nil)
+        r = @client.post(url, form: params)
+        data = JSON.parse(r)
+      end
+
+      private
+
+      def determine_platform!(env)
+        unless DEVICES.include?@device
+          raise RequestError, '必须使用 Xiaomi::Push::Android 或 Xiaomi::Push::IOS 实例化'
+        end
+
+        if env == :sandbox && @device == 'ANDROID'
+          raise RequestError, 'Android 环境不能支持 sandbox 测试环境'
+        end
       end
     end
   end

data/lib/xiaomi/push/commands.rb

@@ -1,2 +1,3 @@
 require 'xiaomi/push/commands/message'
+require 'xiaomi/push/commands/user'
 require 'xiaomi/push/commands/feedback'

data/lib/xiaomi/push/commands/feedback.rb

@@ -1,10 +1,10 @@
 command :feedback do |c|
   c.syntax = 'xmp feedback [options]'
   c.summary = '获取小米无效的设备列表'
-  c.description = ''
+  c.description = '获取小米无效的设备列表'
 
   # normal params
-  c.option '--device DEVICE', %w('android', 'ios'), '设备类型'
+  c.option '--device DEVICE', %w(android, ios), '设备类型'
   c.option '--secret SECRET', '应用密钥'
 
   c.action do |args, options|
@@ -24,16 +24,15 @@ command :feedback do |c|
   def feedback!
     client = Xiaomi::Push.const_get(@device).new(@secret)
     r = client.feedback.invalid
-
     puts r
   end
 
   def determine_device!
     devices = %w(Android iOS).freeze
-    @device = choose "选择推送设备:", *devices
+    @device = choose("选择推送设备:", *devices)
   end
 
   def determine_secret!
-    @secret ||= ask '小米应用密钥:'
+    @secret ||= ask('小米应用密钥:')
   end
 end

data/lib/xiaomi/push/commands/message.rb

@@ -1,19 +1,23 @@
 command :message do |c|
   c.syntax = 'xmp message [options]'
   c.summary = '发送小米推送消息'
-  c.description = '使用小米推送消息（目前仅支持 regid/alias/topic 推送方式）'
+  c.description = '使用小米推送消息（目前仅支持 regid/alias/user/topic 推送方式）'
 
-  # normal params
-  c.option '--device DEVICE', %w('android', 'ios'), '设备类型'
+  # 必须参数
+  c.option '--device DEVICE', %w(android ios), '设备类型'
   c.option '--secret SECRET', '应用密钥'
 
-  # type
+  # 推送类型
   c.option '--regid REGID', 'reg id'
   c.option '--alias ALIAS', '别名'
-  c.option '--topic TOPIC', '订阅名'
-
-  # message
-  c.option '-i', '--title TITLE', '消息标题（仅 Android 有效）'
+  c.option '--user USER', '用户'
+  c.option '--topic TOPIC', '标签/群组'
+
+  # 消息体
+  c.option '-i', '--title TITLE', '消息标题（适用于 Android 或 iOS 10 以上设备）'
+  c.option '-s', '--subtitle SUBTITLE', '消息副标题（仅适用于 iOS 10 以上设备）'
+  c.option '-m', '--image IMAGE', '消息图片地址（仅适用于 iOS 10 以上设备）'
+  # c.option '-c', '--image IMAGE', '消息图片地址（仅适用于 iOS 10 以上设备）'
   c.option '-d', '--description DESCRIPTION', '消息主体描述'
   c.option '-b', '--badge BADGE', Integer, '消息数字'
   c.option '-e', '--extras KEY=VALUE', Array, '自定义数据(使用 KEY=VALUE 方式，多个以逗号不带空格分隔)'
@@ -62,7 +66,10 @@ command :message do |c|
 
   def determine_ios_message!(options)
     @message = Xiaomi::Push::Message::IOS.new(
+      title: @title,
+      subtitle: @subtitle,
       description: @description,
+      image: @image,
       badge: @badge,
       extras: @extras
     )
@@ -70,7 +77,9 @@ command :message do |c|
 
   def determine_message!(options)
     @title = options.title
+    @subtitle = options.subtitle
     @description = options.description
+    @image = options.image
     @badge = options.badge
 
     @extras =
@@ -90,7 +99,7 @@ command :message do |c|
 
   def determine_device!
     devices = %w(Android iOS).freeze
-    @device = choose "选择推送设备:", *devices
+    @device = choose('选择推送设备:', *devices)
   end
 
   def determine_secret!
@@ -98,15 +107,15 @@ command :message do |c|
   end
 
   def determine_channel!(options)
-    channles = %w(regid alias topic).freeze
+    channles = %w(regid alias user topic).freeze
     @channel = channles.select { |k| options.__hash__.key?k.to_sym }
 
     if @channel.count > 0
       @channel = @channel[0]
       @channel_id = options.__hash__[@channel.to_sym]
     else
-      @channel = choose "选择推送方式:", *channles
-      @channel_id = ask "输入 #{@channel} 的值:"
+      @channel = choose('选择推送方式:', *channles)
+      @channel_id = ask("输入 #{@channel} 的值:")
     end
   end
 end

data/lib/xiaomi/push/commands/user.rb

@@ -0,0 +1,69 @@
+command :user do |c|
+  c.syntax = 'xmp user [options]'
+  c.summary = '小米 aliases/topics 查询工具'
+  c.description = '通过 reg id 查找用户绑定的 alias 和 topic'
+
+  # normal params
+  c.option '--device DEVICE', %w(android, ios), '设备类型'
+  c.option '--secret SECRET', '应用密钥'
+  c.option '--reg-id REG_ID', 'Reg id'
+  c.option '--package-name PACKAGE_NAME', '包的唯一标识，android 是 package name， ios 是 bundle identiflier'
+
+  c.action do |args, options|
+    puts options if $verbose
+
+    @device = options.device.capitalize if options.device
+    @secret = options.secret
+    @reg_id = options.reg_id
+    @package_name = options.package_name
+
+    determine_device! unless @device
+    determine_secret! unless @secret
+
+    @client = Xiaomi::Push.const_get(@device).new(@secret)
+
+    find_aliases!
+    find_topics!
+  end
+
+  private
+
+  def find_aliases!
+    r = @client.user.aliases(@reg_id, @package_name)
+    if r['result'] == 'ok'
+      print_data(r, :alias)
+    else
+      user_error(r, :alias)
+    end
+  end
+
+  def find_topics!
+    r = @client.user.topices(@reg_id, @package_name)
+    if r['result'] == 'ok'
+      print_data(r, :topic)
+    else
+      user_error(r, :topic)
+    end
+  end
+
+  def print_data(data, type)
+    say "#{type.to_s} count: #{data['data']['list'].count}"
+    data['data']['list'].each do |key|
+      say_ok " * #{key}"
+    end
+  end
+
+  def user_error(data, type)
+    say_error "#{type.to_s} error."
+    say_error "[#{data['code']}] #{data['description']}: #{data['reason']}"
+  end
+
+  def determine_device!
+    devices = %w(Android iOS).freeze
+    @device = choose("选择推送设备:", *devices)
+  end
+
+  def determine_secret!
+    @secret ||= ask('小米应用密钥:')
+  end
+end

data/lib/xiaomi/push/const.rb

@@ -3,31 +3,49 @@ require 'uri'
 module Xiaomi
   module Push
     module Const
+      # 支持设备
       DEVICES = %w(ANDROID IOS).freeze
-
+      # 产品环境
       PRODUCTION_URL = 'https://api.xmpush.xiaomi.com'.freeze
+      # 沙盒环境（仅支持 iOS）
       SANDBOX_URL = 'https://sandbox.xmpush.xiaomi.com'.freeze
 
       attr_reader :base_url
 
+      # 切换产品环境
       def use_production!
         production
       end
 
+      # 切换沙盒环境
       def use_sandbox!
         sandbox
       end
 
+      # :nodoc:
       def production
         @base_url ||= PRODUCTION_URL
       end
 
+      # :nodoc:
       def sandbox
         @base_url ||= SANDBOX_URL
       end
 
+      # :nodoc:
       def build_uri(uri)
-        URI.join(@base_url, "v2/#{uri}").to_s
+        version =
+          if uri.start_with?('stats', 'trace', 'alias', 'reg_id') || uri == 'topic/all'
+            # 获取消息的统计数据/追踪消息状态/某个用户目前设置的所有 Alias 和订阅的所有 Topic
+            'v1'
+          elsif uri.start_with?('message')
+            # 发送消息支持多包使用 v3 版本
+            'v3'
+          else
+            'v2'
+          end
+
+        File.join(@base_url, version, uri)
       end
     end
   end

data/lib/xiaomi/push/platforms/android.rb

@@ -0,0 +1,17 @@
+module Xiaomi
+  module Push
+    # Android 推送
+    #
+    # @example
+    #   Xiaomi::Push::Message::Android.new(
+    #     title:'标题要有吸引力',
+    #     description:'描述可以在手机显示两行',
+    #     notify_type:'DEFAULT_ALL',
+    #     extras: {
+    #       source: 'mpush'
+    #     }
+    #   )
+    class Android < Xiaomi::Push::Client
+    end
+  end
+end

data/lib/xiaomi/push/platforms/ios.rb

@@ -0,0 +1,20 @@
+module Xiaomi
+  module Push
+    # iOS 推送
+    #
+    # @example
+    #   Xiaomi::Push::Message::iOS.new(
+    #     description:'iOS 主要显示描述',
+    #     badge:10,
+    #     extras: {
+    #       uri: 'app://bbs?id=8624',
+    #       source: 'mpush'
+    #     }
+    #   )
+    class IOS < Xiaomi::Push::Client
+    end
+
+    # 用于 cli 的别名
+    Ios = IOS
+  end
+end

data/lib/xiaomi/push/services/feedback.rb

@@ -1,6 +1,9 @@
 module Xiaomi
   module Push
     module Services
+      # 适用于 iOS 推送获取设备 Feedback API
+      #
+      # @attr [Client] context
       class Feedback
         attr_reader :context
 
@@ -8,10 +11,14 @@ module Xiaomi
           @context = context
         end
 
+        # 获取失效的 device token
+        #
+        # @see https://dev.mi.com/console/doc/detail?pId=1163#_4_1
+        #
+        # @return [Hash] 小米返回数据结构
         def invalid
           url = 'https://feedback.xmpush.xiaomi.com/v1/feedback/fetch_invalid_regids'
-          r = RestClient.get url, @context.header
-          MultiJson.load r
+          @context.get(url)
         end
       end
     end

data/lib/xiaomi/push/services/job.rb

@@ -0,0 +1,36 @@
+module Xiaomi
+  module Push
+    module Services
+      # 定时任务类 API
+      #
+      # @see https://dev.mi.com/console/doc/detail?pId=1163#_7
+      #
+      # @attr [Client] context
+      class Job
+        attr_reader :context
+
+        def initialize(context)
+          @context = context
+        end
+
+        # 检测定时任务是否存在
+        #
+        # @param [String] job_id 任务 id
+        # @return [Hash] 小米返回数据结构
+        def exist?(job_id)
+          url = @context.build_uri('schedule_job/exist')
+          @context.post(url, { job_id: job_id })
+        end
+
+        # 删除定时任务
+        #
+        # @param [String] job_id 任务 id
+        # @return [Hash] 小米返回数据结构
+        def destory(job_id)
+          url = @context.build_uri('schedule_job/delete')
+          @context.post(url, { job_id: job_id })
+        end
+      end
+    end
+  end
+end