active_notifier 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bbb1a3370063f78b39543cb4d5fc05d8acea444503c2f230f9bfd2d19abdd979
-  data.tar.gz: 81999de8ce52f5cee7ec78f6fadbab107b9ca74fdceef9d34eaee7dc70074867
+  metadata.gz: 24d5eac70996ae751cbfac298f4bd78074b53f913c19325347bf50bfcd557eb9
+  data.tar.gz: 7716f56010b04db00fe06e7a3b5773350a9a58ffcb4b117a64bfd17ed3fe18a7
 SHA512:
-  metadata.gz: 885d46d316433753c76d29c8be098b1f1b8d9c67da748fc0122ce1d54253ad76aaa4b0be76a4f13efe56286ea1284637ca47ed773f58cfcb3cfc9dde1ca87f7f
-  data.tar.gz: d98d5c3cf396d0e8d71fdf29c5121d2fda78e029a3fdfa80a5d9a59935e8274e9a04de877da0ad9d2302999f0dbb2abc012e9f7144fa88e038e6ed93eb3a0992
+  metadata.gz: c4793839706e3f4fad3151255736fc0b820611997cd044e793c125b93e1375aab281dd476165525748f6229cd6b45693d0536dad31cc66a47a3924f43119adf4
+  data.tar.gz: 77e1fa443c84606455d712a7340d474b607ebcfa3fb59567f334a19a370384d5d7656fd94a9cd0f9fe4a7265c8b42139ca210e5dfe83cbf8567918e991fc00a5

data/README.md

@@ -1,8 +1,6 @@
 # ActiveNotifier
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/active_notifier`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+Notify message through webhooks.
 
 ## Installation
 
@@ -22,7 +20,116 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+### Basic
+
+```ruby
+ActiveNotifer.config.channel_tokens = { default: "xxx" }
+ActiveNotifier.exec(:default)
+# This will notifier message, use options:
+#   token: config.channel_tokens[:default],
+#   template: "#{config.template_home}/default.*.erb"
+
+ActiveNotifier.exec(:default, template: "orders/create")
+# Use specific template file but not get by channel
+# This will notifier message, use options:
+#   token: config.channel_tokens[:default],
+#   template: "#{config.template_home}/orders/create.*.erb"
+
+ActiveNotifier.exec(:default, token: "special_token", data: { title: "Title", message: "Message" })
+# Use specific token but not get by channel
+# This will notifier message, use options:
+#   token: "special_token",
+#   template: "#{config.template_home}/default.*.erb"
+# And the Hash data will inject to template, and get a dynamic message after parse template
+```
+
+### Use custom template
+
+Set token and template home for Rails application
+
+```ruby
+ActiveNotifier.configure do |config|
+  config.channel_tokens = { default: "xxx" }
+  config.template_home = Rails.root.join("app", "views", "active_notifier")
+end
+```
+
+Set the default message template
+
+> app/views/active_notifier/default.markdown.erb
+
+```erb
+## #{data[:title]}
+> #{data[:message]}
+```
+
+Notify message
+
+```ruby
+ActiveNotifier.exec(:default, data: { title: "Title", message: "Message" }) # => Notifer OK
+```
+
+### Send message with dynamic type
+
+Message type will dynamic set according by valid template files, when we
+set a template named `order.text.erb`
+
+```ruby
+ActiveNotifier.configure do |config|
+  config.channel_tokens = { order: "xxx" }
+  config.template_home = Rails.root.join("app", "views", "active_notifier")
+```
+
+> app/views/active_notifier/order.text.erb
+
+```erb
+title: #{data[:title]}
+message: #{data[:message]}
+```
+
+When there is only text type template for order, it will be OK the
+notify message without set type option
+
+```ruby
+ActiveNotifier.exec(:default, data: { title: "Title", message: "Message" }) # => Notifer message OK
+```
+
+Also, even though there are multiple types templates, like both `order.text.erb` and `order.markdown.erb`
+are exist, we still can make it OK which no need for type option, just
+set the priority type
+
+> app/views/active_notifier/order.text.erb
+
+```erb
+title: #{data[:title]}
+message: #{data[:message]}
+```
+
+> app/views/active_notifier/order.markdown.erb
+
+```erb
+## #{data[:title]}
+> #{data[:message]}
+```
+
+```ruby
+# default priority_type is :markdown
+ActiveNotifer.config.priority_type = :text
+
+# Now this will choose text by default
+ActiveNotifier.exec(:default, data: { title: "Title", message: "Message" }) # => Notifer message OK by text type template
+```
+
+### Set a short constant to notify(Rails initializer will set this by default)
+
+```ruby
+ActiveNotifer.config.const_name = :Notifier
+Notifer.exec(...)
+```
+
+### Other
+
+See complete abilities of ActiveNotifier, please follow [Spec files](https://github.com/pinewong/active_notifier/blob/master/spec/active_adapter_spec.rb)
 
 ## Development
 

data/lib/active_notifier/adaptable.rb

@@ -1,8 +1,6 @@
 module ActiveNotifier
   module Adaptable
-    def self.included(base)
-      base.extend ClassMethods
-    end
+    extend ActiveSupport::Concern
 
     module ClassMethods
       def adapters

data/lib/active_notifier/adapters/abstract_adapter.rb

@@ -6,6 +6,16 @@ module ActiveNotifier
       @adapter = adapter_class.new
     end
 
+    # Notify message
+    # @abstract Implement through setting a real adapter, like :dingtalk
+    # @param token [String] Channel webhook token
+    # @param type [Symbol] Message type
+    # @param message [String] Message body
+    # @param options [Hash] ({}) Adapter message options,
+    #   some adapters require some another options
+    # @raise [AdapterOptionsInvalidError]
+    # @raise [AdapterTypeInvalidError]
+    # @raise [MessageBlankError]
     def notify(token, type, message, **options)
       adapter.notify(token, type, message, **options)
     end

data/lib/active_notifier/adapters/dingtalk_adapter.rb

@@ -8,9 +8,9 @@ module ActiveNotifier
         error_message = "适配器 type 暂时只支持：#{VALID_TYPES.join(', ')}"
         raise ActiveNotifier::AdapterTypeInvalidError, error_message
       end
-      raise ActiveNotifier::MessageBlankError, "消息不能为空, 请检查 template 模板" if message.empty?
+      raise ActiveNotifier::MessageBlankError, "message can't be blank, please check template file" if message.empty?
       title = options[:title].to_s
-      raise ActiveNotifier::AdapterOptionsInvalidError, "钉钉适配器还需提供必须值：title" if title.empty?
+      raise ActiveNotifier::AdapterOptionsInvalidError, "Dingtalk adapter require other options: title" if title.empty?
 
       body = {
         'msgtype' => type,

data/lib/active_notifier/configurable.rb

@@ -1,75 +1,103 @@
 module ActiveNotifier
   module Configurable
-    def self.included(base)
-      base.extend ClassMethods
-    end
+    extend ActiveSupport::Concern
 
     module ClassMethods
-      def config
-        @config ||= Configuration.new
-      end
-
+      # Configure for ActiveNotifier
+      # @yield [config] Give a Configuration instance for settings
+      # @raise [ConfigureError]
+      # @example
+      #   ActiveNotifier.configure do |config|
+      #     config.const_name = :Message
+      #     config.adapter = :slack
+      #     # ...
+      #   end
       def configure
         yield config
       end
+
+      def config
+        @config ||= Configuration.new
+      end
     end
 
     class Configuration
-      # 常量名, 简化调用, 符号，默认 :Notifier (如果被占用请更换)
+      # Alias const for ActiveNotifier
+      # @!attribute [r]
       attr_reader :const_name
 
+      # Set alias const for ActiveNotifier
+      # @param const_name [#to_sym] (:Notifier) Alias const name
+      # @example
+      #   ActiveNotifier.config.const_name = :Message
+      #   ::Message == ::ActiveNotifier # => true
       def const_name=(const_name)
         const_name = const_name.to_sym
-        const_name = "Notifier" if const_name.empty?
-        raise ActiveNotifier::ConfigureError, "const_name 已经存在，请配置其他值" if Kernel.const_defined?(const_name)
+        const_name = :Notifier if const_name.empty?
+        error_message = "const_name is already defined, please set another value"
+        raise ActiveNotifier::ConfigureError, error_message if Kernel.const_defined?(const_name)
         Kernel.const_set(const_name, ActiveNotifier)
         @const_name = const_name
       end
 
-      # 消息适配器, 字符串, 默认 :dingtalk
+      # Message Adapter
       def adapter
         @adapter || :dingtalk
       end
 
+      # Set message Adapter
+      # @param adapter [#to_sym] (:dingtalk)
       def adapter=(adapter)
         adapter = adapter.to_sym
         unless adapters_with_base_url.key?(adapter)
-          raise ActiveNotifier::ConfigureError, "adapter 当前只支持：#{adapters_with_base_url.keys.join(', ')}"
+          raise ActiveNotifier::ConfigureError, "adapter only support: #{adapters_with_base_url.keys.join(', ')}"
         end
         @adapter = adapter
       end
 
-      # 消息渠道的 channel_tokens 设置
+      # The tokens of channel
       def channel_tokens
         @channel_tokens || {}
       end
 
+      # Set the tokens of channel
+      # @param channel_tokens [Hash] ({})
+      # @example
+      #   ActiveNotifier.config.channel_tokens = {
+      #     default: "xxx",
+      #     order: "xxx"
+      #   }
       def channel_tokens=(channel_tokens)
         channel_tokens = channel_tokens.to_h.symbolize_keys
         @channel_tokens = channel_tokens
       end
 
-      # 消息模版主目录, 字符串, 默认 views/notifier/application), 不需要加模版后缀
+      # The template home directory
       def template_home
         @template_home || "#{File.expand_path(__dir__)}/templates"
       end
 
+      # Set the template home directory
+      # @param template_home [String] (lib/active_notifier/templates)
       def template_home=(template_home)
         template_home = template_home.to_s
-        raise ActiveNotifier::ConfigureError, "模板主目录不能为空" if template_home.empty?
+        raise ActiveNotifier::ConfigureError, "template_home value can't be blank" if template_home.empty?
         @template_home = template_home
       end
 
-      # 消息优先类型, 字符串, 默认 :markdown, 对应模板后缀名，如果未指定该参数且存在多个模板，则优先选择此类型
+      # The priority type for message, if notifier execute without type option and there are multiple valid types,
+      # then ActiveNotifier will use the template with this type first
       def priority_type
         @priority_type || :markdown
       end
 
+      # Set the priority type
+      # @param priority_type [#to_sym] (:markdown)
       def priority_type=(priority_type)
         @priority_type = priority_type.to_sym
       end
 
-      # 适配器以及基本连接
+      # The adapters and its base url
       def adapters_with_base_url
         @adapters_with_base_url ||= {
           dingtalk: "https://oapi.dingtalk.com/robot/send?access_token="

data/lib/active_notifier/core.rb

@@ -1,25 +1,38 @@
 module ActiveNotifier
   module Core
-    def self.included(base)
-      base.extend ClassMethods
-    end
+    extend ActiveSupport::Concern
 
     module ClassMethods
-      # Params:
-      #   channel: 消息渠道, 符号,
-      #            例如设置为 :order, 则使用 channel_tokens[:order] 和 order.markdown.erb 模板发送消息
-      #   options:
-      #     template: 消息模版, 字符串, 默认 "default", 不需要加模版后缀
-      #     token: webhook token, 类型符号则取 chanenl_tokens[:symbol] 值，类型字符串则使用原值
-      #     type: 消息类型, 符号, 默认 :markdown, 对应模板后缀名
-      #     data: 传递数据, Hash, 默认 {}
-      #     其他键的值会被当成适配器选项值，直接传到适配器中处理
+      # Message execute
+      # @param channel [#to_sym] Message channel, it will set template and token together
+      # @param options [Hash] ({})
+      # @option options [String] :template (nil) Message template, will use `options[:channel]` when this value is blank
+      # @option options [String, Symbol] :token (nil) Message webhook token,
+      #   will use `options[:channel]` when this value is blank
+      # @option options [Symbol] :type (nil) Message type, it will use a specific template file, for example,
+      #   when type is :text and template is order, then ActiveNotifier will choose `order.text.erb` for template file
+      # @option options [Hash] :data ({}) Message variable data for template, it can used in erb template file:
+      #   ## #{data[:title]}
+      #   > #{data[:order].to_json}
+      # @option options [Anything] Other options will used in adapter message execute,
+      #   like Dingtalk require title for message, we can pass it here:
+      #   `ActiveNotifer.exec(:default, title: "dingtalk title")`
+      # @raise [TemplateNotFoundError]
+      # @raise [UndefinedTokenError]
+      # @raise [AdapterOptionsInvalidError]
+      # @raise [AdapterTypeInvalidError]
+      # @raise [MessageBlankError]
+      # @example
+      #   ActiveNotifer.config.channel_tokens = {
+      #     default: "xxx"
+      #   }
+      #   ActiveNotifier.exec(:default)
       def exec(channel, **options)
         channel = channel&.to_sym
-        raise ArgumentError, "Channel 不能为空" if channel.blank?
+        raise ArgumentError, ":channel can't be blank" if channel.blank?
         template = options[:template].to_s.presence || channel.to_s
         token = get_token(channel, options[:token])
-        raise UndefinedTokenError, "Token 值未定义" if token.blank?
+        raise UndefinedTokenError if token.blank?
         type = options[:type]&.to_sym.presence || guess_type_by_files(template)
         data = options[:data].to_h
 

data/lib/active_notifier/errors.rb

@@ -1,22 +1,9 @@
 module ActiveNotifier
-  # 顶级错误
   class Error < StandardError; end
-
-  # 配置错误
   class ConfigureError < Error; end
-
-  # 模板未找到
   class TemplateNotFoundError < Error; end
-
-  # 消息为空
   class MessageBlankError < Error; end
-
-  # 适配器 type 无效
   class AdapterTypeInvalidError < Error; end
-
-  # 适配器 options 无效
   class AdapterOptionsInvalidError < Error; end
-
-  # Token 未定义
   class UndefinedTokenError < Error; end
 end

data/lib/active_notifier/version.rb

@@ -1,3 +1,3 @@
 module ActiveNotifier
-  VERSION = "0.1.0".freeze
+  VERSION = "0.2.0".freeze
 end

data/lib/active_notifier.rb

@@ -1,5 +1,4 @@
 require "active_notifier/version"
-require "active_support"
 require "active_support/all"
 
 module ActiveNotifier

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: active_notifier
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Pine Wong
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-07-23 00:00:00.000000000 Z
+date: 2018-07-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport