five_mobile_push 0.3.0 → 0.3.1

data/.gitignore

@@ -2,3 +2,5 @@
 .bundle
 Gemfile.lock
 pkg/*
+doc/*
+.yardoc

data/.yardopts

@@ -0,0 +1 @@
+--no-private lib/**/*.rb 

data/five_mobile_push.gemspec

@@ -19,10 +19,11 @@ Gem::Specification.new do |s|
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
   
-  s.add_dependency "multi_json", ["~> 0.0.5"]
-  s.add_dependency "faraday", ["~> 0.5.7"]
-  s.add_development_dependency "rspec", ["~> 2.5.0"]
+  s.add_dependency "multi_json",              ["~> 0.0.5"]
+  s.add_dependency "faraday",                 ["~> 0.5.7"]
+  s.add_development_dependency "rspec",       ["~> 2.5.0"]
   s.add_development_dependency "yajl-ruby"
   s.add_development_dependency "webmock"
   s.add_development_dependency "fabrication", ["~> 0.9.5"]
+  s.add_development_dependency "yard",        ["~> 0.6.5"]
 end

data/lib/five_mobile_push/notifier.rb

@@ -1,34 +1,120 @@
 module FiveMobilePush
+  # @todo Validate provided platforms
+  # @todo Simplify platform selection
   class Notifier
 
+    # The following are platforms supported by the Five Mobile Push platform
+
+    ALL        = "all"
+    IPHONE     = "iphone"
+    BLACKBERRY = "blackberry"
+    ANDROID    = "android"
+
+    # @param [FiveMobilePush::Client] client The Client object to use when
+    #   sending notices
     def initialize(client)
       @client = client
     end
 
+    # Broadcast a notification to one or more platforms of an application.
+    #
+    # == Supported Platforms
+    #
+    # * all
+    # * iphone
+    # * blackberry
+    # * android
+    #
+    # @param [Array<String>, String] platforms Any of the supported platforms.
+    #
+    # @yield [message] Provides a mini-DSL for constructing the message to
+    #   broadcast.
+    #
+    # @yieldparam [Message] message (see Message)
+    #
+    # @example Simple usage
+    #   n = FiveMobilePush::Notifier.new(client)
+    #   n.broadcast(FiveMobilePush::Notifier::ALL) do |message|
+    #     message.body "Downtime this weekend"
+    #   end
     def broadcast(platforms, &block)
       @client.post 'notify/broadcast',
         :platforms => build_platforms_string(platforms),
-        :payload   => capture_payload(&block).to_json
+        :payload   => capture_message(&block).to_json
     end
 
+    # Send a notification to any number of specified devices
+    #
+    # @param [Array<String>] devices A list of device ID values
+    #
+    # @yield [message] Provides a mini-DSL for constructing the message to
+    #   broadcast.
+    #
+    # @yieldparam [Message] message (see Message)
+    #
+    # @example Simple usage
+    #   n = FiveMobilePush::Notifier.new(client)
+    #   n.notify_devices(['1234']) do |message|
+    #     message.body "Downtime this weekend"
+    #   end
     def notify_devices(devices, &block)
       @client.post 'notify/toDevices',
         :id_type   => FiveMobilePush::DEFAULT_ID_TYPE,
         :id_values => devices.join(','),
-        :payload   => capture_payload(&block).to_json
+        :payload   => capture_message(&block).to_json
     end
 
+    # Notifies any device registered with the provided tags.
+    #
+    # == Supported Platforms
+    #
+    # * all
+    # * iphone
+    # * blackberry
+    # * android
+    #
+    # @param [Array<String>, String] platforms Any of the supported platforms.
+    # @param [Array<String>] tags Any tag that is registered
+    #
+    # @yield [message] Provides a mini-DSL for constructing the message to
+    #   broadcast.
+    #
+    # @yieldparam [Message] message (see Message)
+    #
+    # @example Simple usage
+    #   n = FiveMobilePush::Notifier.new(client)
+    #   n.notify_by_tags(FiveMobilePush::Notifier::ALL, ['muffin', 'bacon']) do |message|
+    #     message.body "Downtime this weekend"
+    #   end
     def notify_by_tags(platforms, tags, &block)
       @client.post 'notify/toTags',
         :platforms => build_platforms_string(platforms),
         :tags      => tags.join(','),
-        :payload   => capture_payload(&block).to_json
+        :payload   => capture_message(&block).to_json
+    end
+
+    # Simple proxy class for building messages. Do not use this class directly.
+    class Message
+      # @param [String] body The text to send
+      def body(body)
+        @body = body
+      end
+
+      # @param [Hash] meta_data (optional) The optional meta data to send.
+      def meta_data(meta_data)
+        @meta_data = meta_data
+      end
+
+      # @private
+      def to_payload
+        FiveMobilePush::Payload.new(@message, @meta_data)
+      end
     end
 
     private
 
-    def capture_payload(&block)
-      payload_proxy = PayloadProxy.new
+    def capture_message(&block)
+      payload_proxy = Message.new
       block.call(payload_proxy)
       payload_proxy.to_payload
     end
@@ -41,19 +127,5 @@ module FiveMobilePush
       end
     end
 
-    class PayloadProxy
-      def message(message)
-        @message = message
-      end
-
-      def meta_data(meta_data)
-        @meta_data = meta_data
-      end
-
-      def to_payload
-        FiveMobilePush::Payload.new(@message, @meta_data)
-      end
-    end
-
   end
 end

data/lib/five_mobile_push/payload.rb

@@ -1,4 +1,6 @@
 module FiveMobilePush
+  # @private Used internally. You'll never use this class directly.
+  #   Documented for the benefit of contributors.
   class Payload
     attr_reader   :message
     attr_accessor :meta_data

data/lib/five_mobile_push/version.rb

@@ -1,3 +1,3 @@
 module FiveMobilePush
-  VERSION = "0.3.0"
+  VERSION = "0.3.1"
 end

metadata

@@ -2,7 +2,7 @@
 name: five_mobile_push
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors: 
 - Kevin Faustino
@@ -80,6 +80,17 @@ dependencies:
         version: 0.9.5
   type: :development
   version_requirements: *id006
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id007 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 0.6.5
+  type: :development
+  version_requirements: *id007
 description: API wrapper for Five Mobile Push notification service
 email: 
 - kevin.faustino@gmail.com
@@ -93,6 +104,7 @@ extra_rdoc_files: []
 files: 
 - .gitignore
 - .rspec
+- .yardopts
 - Gemfile
 - Rakefile
 - five_mobile_push.gemspec