push_builder 0.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format documentation

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Philipe Fatio
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/PAYLOAD.md

@@ -0,0 +1,18 @@
+# Anatomy of a Payload
+
+JSON dictionary ([RFC 4627](http://www.rfc-editor.org/rfc/rfc4627.txt)) weighing in at a max of 256 bytes.
+
+Must contain `aps` dictionary with at least one of the following keys:
+
+- `alert` (string or dictionary): The message to display or a dictionary which let's you specify further things (see below).
+- `badge` (number): The number to add to the app icon. If absent, the current badge is not changed. 0 clears the badge.
+- `sound` (string): The identifier of a sound to play.
+
+The `alert` dictionary can contain the following keys:
+
+- `body` (string): The message to display.
+- `action-loc-key` (string or null): The localization key of the string to use in place of "View" in the right button. Specify null to only show the "OK" button.
+- `loc-key` (string): The localization key of the string that is used as the message.
+- `loc-args` (array of strings): The arguments to appear in place of the format specifiers in `low-key`.
+- `launch-image` (string): The filename of an image file in the application bundle (may omit the extension).
+

data/README.md

@@ -0,0 +1,53 @@
+# PushBuilder
+
+PushBuilder was born with one mission only: construct JSON payloads for Apple's push notification service.
+
+## What it Does
+
+- Automatically crops the alert so that the payload does not exceed the allowed 256 bytes.
+- Supports specifying custom data (data that the iOS app can read from the push notification).
+- Supports specifying data for a third party (data that is intended for a "man in the middle" such as Urban Airship; this data is assumed to be stripped from the payload by the third party and thus does not count towards the 256 bytes limit).
+- Performs some basic type checking.
+
+## Usage
+
+```ruby
+PushBuilder.build(alert: 'Hello World!', badge: 3, sound: 'default').to_json
+# => {"aps":{"badge":3,"alert":"Hello World!","sound":"default"}}
+
+# Specifying custom data:
+payload = PushBuilder.build(alert: 'Hello World!')
+payload.custom_data[:notification_id] = 1234
+payload.to_json
+# => {"notification_id":1234,"aps":{"alert":"Hello World!"}}
+
+# Specifying third party data (such as UrbanAirship aliases):
+payload = PushBuilder.build(alert: 'Hello World!')
+payload.third_party_data[:aliases] = %w[ 123 456 789 ]
+payload.to_json
+# => {"aliases":["123","456","789"],"aps":{"alert":"Hello World!"}}
+
+# Auto crops alerts to not exceed max payload size of 256 bytes:
+PushBuilder.build(alert: 'Hello World ' * 100, badge: 3, sound: 'default').to_json
+# => {"aps":{"badge":3,"alert":"Hello World [...] H…","sound":"default"}}
+```
+
+## Limitations
+
+The `alert` key of the `aps` dictionary only supports strings at the moment.
+Technically, the alert can be customized further as described in [PAYLOAD.md](PAYLOAD.md).
+
+## Additional Information
+
+### Useful Links
+
+- [Anatomy of a Payload](PAYLOAD.md)
+- [Local and Push Notification Programming Guide](http://developer.apple.com/library/mac/#documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/ApplePushService/ApplePushService.html)
+
+### Maintainers
+
+- Philipe Fatio ([@fphilipe](https://github.com/fphilipe))
+
+### License
+
+MIT License. Copyright 2013 Philipe Fatio

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/lib/push_builder.rb

@@ -0,0 +1,15 @@
+require 'push_builder/version'
+require 'push_builder/payload'
+require 'push_builder/aps'
+require 'push_builder/compiler'
+require 'push_builder/string_cropper'
+
+module PushBuilder
+  TypeError = Class.new(StandardError)
+
+  def self.build(args={})
+    Payload.new.tap do |payload|
+      args.each { |k, v| payload.aps.send("#{k}=", v) }
+    end
+  end
+end

data/lib/push_builder/aps.rb

@@ -0,0 +1,25 @@
+module PushBuilder
+  class APS
+    attr_reader :alert, :badge, :sound
+
+    def badge=(badge)
+      @badge = badge.nil? ? nil : Integer(badge)
+    rescue ArgumentError
+      fail TypeError, 'Invalid number for badge'
+    end
+
+    def alert=(alert)
+      @alert = alert.nil? ? nil : String(alert)
+    end
+
+    def sound=(sound)
+      @sound = sound.nil? ? nil : String(sound)
+    end
+
+    def to_hash(opts={})
+      { badge: badge, alert: alert, sound: sound }.reject do |_,v|
+        v.nil?
+      end
+    end
+  end
+end

data/lib/push_builder/compiler.rb

@@ -0,0 +1,39 @@
+require 'multi_json'
+
+module PushBuilder
+  class Compiler
+    MAX_PAYLOAD_SIZE = 256
+
+    attr_reader :payload, :third_party_data
+
+    def initialize(payload, third_party_data={})
+      @payload = payload
+      @third_party_data = third_party_data
+    end
+
+    def compile
+      crop_alert_if_necessary!
+
+      to_json(third_party_data.merge(payload))
+    end
+
+    private
+
+    def crop_alert_if_necessary!
+      if (alert = payload.fetch(:aps, {})[:alert])
+        payload[:aps][:alert] =
+          StringCropper
+            .new(alert)
+            .crop_bytes(size(payload) - MAX_PAYLOAD_SIZE)
+      end
+    end
+
+    def size(data)
+      to_json(data).bytesize
+    end
+
+    def to_json(data)
+      MultiJson.dump(data)
+    end
+  end
+end

data/lib/push_builder/payload.rb

@@ -0,0 +1,40 @@
+module PushBuilder
+  class Payload
+    attr_reader :aps, :custom_data, :third_party_data
+
+    def initialize(args={})
+      @aps = APS.new
+      @custom_data = {}
+      @third_party_data = {}
+    end
+
+    def aps=(aps)
+      if aps.is_a?(APS)
+        @aps = aps
+      else
+        fail TypeError, 'Trying to set aps to a non APS object.'
+      end
+    end
+
+    def custom_data=(data)
+      if data.is_a?(Hash)
+        @custom_data = data
+      else
+        fail TypeError, 'Trying to set custom_data to something other than Hash.'
+      end
+    end
+
+    def third_party_data=(data)
+      if data.is_a?(Hash)
+        @third_party_data = data
+      else
+        fail TypeError, 'Trying to set third_party_data to something other than Hash.'
+      end
+    end
+
+    def to_json
+      payload = custom_data.merge(aps: aps.to_hash)
+      Compiler.new(payload, third_party_data).compile
+    end
+  end
+end

data/lib/push_builder/string_cropper.rb

@@ -0,0 +1,40 @@
+# coding: UTF-8
+
+module PushBuilder
+  class StringCropper
+    DEFAULT_CROP_INDICATOR = ?…
+
+    attr_reader :string, :indicator
+
+    def initialize(string, indicator=DEFAULT_CROP_INDICATOR)
+      @string = string
+      @indicator = indicator
+    end
+
+    def crop_bytes(bytes_to_crop)
+      return string  if bytes_to_crop <= 0
+
+      bytes_to_crop += indicator.bytesize
+      remaining_bytes = string.bytesize - bytes_to_crop
+
+      string_with_bytes(remaining_bytes) + indicator
+    end
+
+    private
+
+    def string_with_bytes(bytes)
+      char_count = char_count_fitting_in_bytes(bytes)
+
+      string[0, char_count]
+    end
+
+    def char_count_fitting_in_bytes(bytes)
+      string.each_char.with_index.inject(0) do |byte_sum, (char, char_count)|
+        byte_sum += char.bytesize
+        break char_count if byte_sum > bytes
+
+        byte_sum
+      end
+    end
+  end
+end

data/lib/push_builder/version.rb

@@ -0,0 +1,3 @@
+module PushBuilder
+  VERSION = "0.0.1"
+end

data/push_builder.gemspec

@@ -0,0 +1,21 @@
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'push_builder/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = 'push_builder'
+  gem.version       = PushBuilder::VERSION
+  gem.authors       = ['Philipe Fatio']
+  gem.email         = ['me@phili.pe']
+  gem.summary       = %q{Easily construct JSON payloads for Apple's push notification service.}
+  gem.description   = gem.summary
+  gem.homepage      = 'https://github.com/fphilipe/push_builder'
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+
+  gem.add_development_dependency 'rspec', '~> 2.12'
+
+  gem.add_dependency 'multi_json', '~> 1.0'
+end

data/spec/spec_helper.rb

@@ -0,0 +1,8 @@
+require 'push_builder'
+
+RSpec.configure do |config|
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.run_all_when_everything_filtered = true
+  config.filter_run :focus
+  config.order = 'random'
+end

data/spec/unit/aps_spec.rb

@@ -0,0 +1,87 @@
+require 'spec_helper'
+
+describe PushBuilder::APS do
+  subject(:aps) { described_class.new }
+
+  describe '#badge=' do
+    it 'raises for non numeric values' do
+      expect { aps.badge = 'test' }.to raise_error(PushBuilder::TypeError)
+    end
+
+    it 'accepts numeric strings' do
+      aps.badge = '123'
+      aps.badge.should be 123
+    end
+
+    it 'accepts numbers' do
+      aps.badge = 123
+      aps.badge.should be 123
+    end
+
+    it 'accepts nil' do
+      aps.badge = nil
+      aps.badge.should be_nil
+    end
+  end
+
+  describe '#alert=' do
+    it 'accepts strings' do
+      aps.alert = 'foobar'
+      aps.alert.should eq 'foobar'
+    end
+
+    it 'accepts values convertable to strings' do
+      aps.alert = 123
+      aps.alert.should eq '123'
+    end
+
+    it 'accepts nil' do
+      aps.alert = nil
+      aps.alert.should be_nil
+    end
+  end
+
+  describe '#sound=' do
+    it 'accepts strings' do
+      aps.sound = 'foobar'
+      aps.sound.should eq 'foobar'
+    end
+
+    it 'accepts values convertable to strings' do
+      aps.sound = 123
+      aps.sound.should eq '123'
+    end
+
+    it 'accepts nil' do
+      aps.sound = nil
+      aps.sound.should be_nil
+    end
+  end
+
+  describe '#to_hash' do
+    before do
+      aps.badge = 1
+      aps.alert = 'foo'
+      aps.sound = 'bar'
+    end
+
+    let(:expected_hash) do
+      { badge: 1, alert: 'foo', sound: 'bar' }
+    end
+
+    it 'returns a hash' do
+      aps.to_hash.should eq expected_hash
+    end
+
+    [:badge, :alert, :sound].each do |key|
+      context "when #{key} is nil" do
+        it 'does not include it' do
+          aps.send("#{key}=", nil)
+          expected_hash.delete(key)
+
+          aps.to_hash.should eq expected_hash
+        end
+      end
+    end
+  end
+end

data/spec/unit/compiler_spec.rb

@@ -0,0 +1,44 @@
+# coding: UTF-8
+
+require 'spec_helper'
+
+describe PushBuilder::Compiler do
+  describe '#compile' do
+    it 'crops the alert if necessary' do
+      alert = 50.times.map { 'foobar' }.join
+      payload = { aps: { alert: alert } }
+
+      json = described_class.new(payload).compile
+      json.bytesize.should be 256
+      json.should =~ %r{"alert":"[fobar]+…"}
+    end
+
+    it 'does not crop the alert if not necessary' do
+      payload = { aps: { alert: 'foobar' } }
+
+      json = described_class.new(payload).compile
+      json.bytesize.should be < 256
+      json.should include '"alert":"foobar"'
+    end
+
+    context 'when third party data is large' do
+      it 'does not crop the alert if not necessary' do
+        payload = { aps: { alert: 'foobar' } }
+        third_party_data = { test: 50.times.map { 'foobar' }.join }
+
+        json = described_class.new(payload, third_party_data).compile
+        json.bytesize.should be > 256
+        json.should include '"alert":"foobar"'
+      end
+    end
+
+    context 'when no alert present' do
+      it 'does not include an alert key' do
+        payload = { aps: { badge: 4 } }
+
+        json = described_class.new(payload).compile
+        json.should_not include '"alert":'
+      end
+    end
+  end
+end

data/spec/unit/payload_spec.rb

@@ -0,0 +1,59 @@
+# coding: UTF-8
+
+require 'spec_helper'
+
+describe PushBuilder::Payload do
+  subject(:payload) { described_class.new }
+
+  describe '#aps' do
+    it 'is an APS' do
+      payload.aps.should be_a(PushBuilder::APS)
+    end
+  end
+
+  describe '#aps=' do
+    it 'accepts an APS object' do
+      aps = PushBuilder::APS.new
+      payload.aps = aps
+      payload.aps.should be aps
+    end
+
+    it 'raises when object is not an APS' do
+      expect { payload.aps = 'foobar' }.
+        to raise_error(PushBuilder::TypeError)
+    end
+  end
+
+  %w[ custom_data third_party_data ].each do |method|
+    describe "##{method}" do
+      it 'is an emtpy hash by default' do
+        payload.send(method).should == {}
+      end
+    end
+
+    describe "##{method}=" do
+      it 'accepts a Hash' do
+        payload.send("#{method}=", { foo: 'bar' })
+        payload.send(method)[:foo].should eq 'bar'
+      end
+
+      it 'raises when object is not a Hash' do
+        expect { payload.send("#{method}=", 123) }.
+          to raise_error(PushBuilder::TypeError)
+      end
+    end
+  end
+
+  describe '#to_json' do
+    it 'returns a JSON string' do
+      payload.aps.stub(to_hash: { foo: 'bar' })
+      payload.custom_data[:abc] = 123
+      payload.third_party_data[:xyz] = true
+
+      json = payload.to_json
+      json.should include '"abc":123'
+      json.should include '"aps":{"foo":"bar"}'
+      json.should include '"xyz":true'
+    end
+  end
+end

data/spec/unit/push_builder.rb

@@ -0,0 +1,14 @@
+require 'spec_helper'
+
+describe PushBuilder do
+  describe '.build' do
+    it 'returns a Payload' do
+      payload = PushBuilder.build(alert: 'Hello', sound: 'default', badge: 5)
+
+      payload.should be_a described_class::Payload
+      payload.aps.alert.should eq 'Hello'
+      payload.aps.sound.should eq 'default'
+      payload.aps.badge.should eq 5
+    end
+  end
+end

data/spec/unit/string_cropper_spec.rb

@@ -0,0 +1,26 @@
+# coding: UTF-8
+
+require 'spec_helper'
+
+describe PushBuilder::StringCropper do
+  describe '#crop_bytes' do
+    def crop_bytes(string, bytes, indicator='')
+      PushBuilder::StringCropper.new(string, indicator).crop_bytes(bytes)
+    end
+
+    specify { crop_bytes('abcdefg', -1).    should eq 'abcdefg' }
+    specify { crop_bytes('abcdefg', 0).     should eq 'abcdefg' }
+    specify { crop_bytes('abcdefg', 1).     should eq 'abcdef'  }
+    specify { crop_bytes('abcdefg', 1, '…').should eq 'abc…'    }
+    specify { crop_bytes('abcdefg', 4, '…').should eq '…'       }
+
+    specify { crop_bytes('aäoöuüe', 2).     should eq 'aäoöu' }
+    specify { crop_bytes('aäoöuüe', 3).     should eq 'aäoöu' }
+    specify { crop_bytes('aäoöuüe', 4).     should eq 'aäoö'  }
+    specify { crop_bytes('aäoöuüe', 5).     should eq 'aäo'   }
+    specify { crop_bytes('aäoöuüe', 1, '…').should eq 'aäoö…' }
+    specify { crop_bytes('aäoöuüe', 2, '…').should eq 'aäo…'  }
+    specify { crop_bytes('aäoöuüe', 3, '…').should eq 'aäo…'  }
+    specify { crop_bytes('aäoöuüe', 4, '…').should eq 'aä…'   }
+  end
+end

metadata

@@ -0,0 +1,104 @@
+--- !ruby/object:Gem::Specification
+name: push_builder
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Philipe Fatio
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-02-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.12'
+- !ruby/object:Gem::Dependency
+  name: multi_json
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Easily construct JSON payloads for Apple's push notification service.
+email:
+- me@phili.pe
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- Gemfile
+- LICENSE.txt
+- PAYLOAD.md
+- README.md
+- Rakefile
+- lib/push_builder.rb
+- lib/push_builder/aps.rb
+- lib/push_builder/compiler.rb
+- lib/push_builder/payload.rb
+- lib/push_builder/string_cropper.rb
+- lib/push_builder/version.rb
+- push_builder.gemspec
+- spec/spec_helper.rb
+- spec/unit/aps_spec.rb
+- spec/unit/compiler_spec.rb
+- spec/unit/payload_spec.rb
+- spec/unit/push_builder.rb
+- spec/unit/string_cropper_spec.rb
+homepage: https://github.com/fphilipe/push_builder
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Easily construct JSON payloads for Apple's push notification service.
+test_files:
+- spec/spec_helper.rb
+- spec/unit/aps_spec.rb
+- spec/unit/compiler_spec.rb
+- spec/unit/payload_spec.rb
+- spec/unit/push_builder.rb
+- spec/unit/string_cropper_spec.rb
+has_rdoc: