houston 0.2.4 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e5aecadd372ded4ba46d1ae9eca31fbcab168644
-  data.tar.gz: f39b14600dbfe3610cc3b6d6024b5cdee0941471
+  metadata.gz: cfbcea0735347e252416d11e2ae57e506ba71ffd
+  data.tar.gz: 7e9b26d48fd1ad27fe068ec0f3a7cfe2c2f307d9
 SHA512:
-  metadata.gz: 22539e7ac680df2138dc00a1e1688dbeb1e7c7c0973687f6c1bad64b1e64676cf7b8ecf88e3b209fcc49f743b7acc778c23d5a8e470d72d877815d86e7a55c3a
-  data.tar.gz: f95928800e51dda1313e1df4aeec8da7a1b0fb8543e6d124e7ff162dd01f7dfbd0307ede39ea56b6eff4c3ae2c2677dab98e891cbd52d00517a632506ece07cf
+  metadata.gz: f6104dd4c1221816bc7e8f779c508c0fed230210d8c5b387d804e9d1120d83b88785ccfa398410190be4eb34ffa28ead665f9c836f76cb6224661c64924fb529
+  data.tar.gz: 301d4d835c5de3497aa5ed4330f3bb4207e0a0f54849a7747f6bd6927c414b1cff15700df430f7b3a91a7a68ad63720ffb49dd14f7beba22c23df7ff9c153176

data/Gemfile

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

data/Gemfile.lock

@@ -1,24 +1,44 @@
 PATH
   remote: .
   specs:
-    houston (0.2.4)
+    houston (2.2.3)
       commander (~> 4.1)
       json
 
 GEM
   remote: https://rubygems.org/
   specs:
-    commander (4.1.3)
+    commander (4.2.0)
       highline (~> 1.6.11)
-    highline (1.6.19)
-    json (1.8.0)
-    rake (0.9.2.2)
-    rspec (0.6.4)
+    diff-lcs (1.2.5)
+    docile (1.1.5)
+    highline (1.6.21)
+    json (1.8.1)
+    multi_json (1.10.1)
+    rake (10.3.2)
+    rspec (3.0.0)
+      rspec-core (~> 3.0.0)
+      rspec-expectations (~> 3.0.0)
+      rspec-mocks (~> 3.0.0)
+    rspec-core (3.0.3)
+      rspec-support (~> 3.0.0)
+    rspec-expectations (3.0.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.0.0)
+    rspec-mocks (3.0.3)
+      rspec-support (~> 3.0.0)
+    rspec-support (3.0.3)
+    simplecov (0.9.0)
+      docile (~> 1.1.0)
+      multi_json
+      simplecov-html (~> 0.8.0)
+    simplecov-html (0.8.0)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
   houston!
-  rake (~> 0.9)
-  rspec (~> 0.6)
+  rake
+  rspec (~> 3.0)
+  simplecov

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2012 Mattt Thompson (http://mattt.me/)
+Copyright (c) 2012–2015 Mattt Thompson (http://mattt.me/)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,18 +1,18 @@
-![Houston](https://raw.github.com/mattt/nomad-cli.com/assets/houston-banner.png)
+![Houston](https://raw.github.com/nomad/nomad.github.io/assets/houston-banner.png)
 
 Push Notifications don't have to be difficult.
 
 Houston is a simple gem for sending Apple Push Notifications. Pass your credentials, construct your message, and send it.
 
-In a production application, you will probably want to schedule or queue notifications into a background job. Whether you're using [queue_classic](https://github.com/ryandotsmith/queue_classic), [resque](https://github.com/defunkt/resque), or rolling you own infrastructure, integrating Houston couldn't be simpler.
+In a production application, you will probably want to schedule or queue notifications into a background job. Whether you're using [queue_classic](https://github.com/ryandotsmith/queue_classic), [resque](https://github.com/resque/resque), or rolling you own infrastructure, integrating Houston couldn't be simpler.
 
-Another caveat is that Houston doesn't manage device tokens for you. For that, you should check out [Helios](http://helios.io)
+Another caveat is that Houston doesn't manage device tokens for you. For that, you should check out [Helios](http://github.com/helios-framework/helios).
 
-> Houston's is named for [Houston, TX](http://en.wikipedia.org/wiki/Houston), the metonymical home of [NASA's Johnson Space Center](http://en.wikipedia.org/wiki/Lyndon_B._Johnson_Space_Center), as in _Houston, We Have Liftoff!_.
+> Houston is named for [Houston, TX](http://en.wikipedia.org/wiki/Houston), the metonymical home of [NASA's Johnson Space Center](http://en.wikipedia.org/wiki/Lyndon_B._Johnson_Space_Center), as in _Houston, We Have Liftoff!_.
 
-> It's part of a series of world-class command-line utilities for iOS development, which includes [Cupertino](https://github.com/mattt/cupertino) (Apple Dev Center management), [Shenzhen](https://github.com/mattt/shenzhen) (Building & Distribution), [Venice](https://github.com/mattt/venice) (In-App Purchase Receipt Verification), and [Dubai](https://github.com/mattt/dubai) (Passbook pass generation).
+> It's part of a series of world-class command-line utilities for iOS development, which includes [Cupertino](https://github.com/nomad/cupertino) (Apple Dev Center management), [Shenzhen](https://github.com/nomad/shenzhen) (Building & Distribution), [Venice](https://github.com/nomad/venice) (In-App Purchase Receipt Verification), [Dubai](https://github.com/nomad/dubai) (Passbook pass generation), and [Nashville](https://github.com/nomad/nashville) (iTunes Store API).
 
-> This project is also part of a series of open source libraries covering the mission-critical aspects of an iOS app's infrastructure. Be sure to check out its sister projects: [GroundControl](https://github.com/mattt/GroundControl), [SkyLab](https://github.com/mattt/SkyLab), [houston](https://github.com/mattt/houston), and [Orbiter](https://github.com/mattt/Orbiter).
+> This project is also part of a series of open source libraries covering the mission-critical aspects of an iOS app's infrastructure. Be sure to check out its sister projects: [GroundControl](https://github.com/mattt/GroundControl), [SkyLab](https://github.com/mattt/SkyLab), [houston](https://github.com/nomad/houston), and [Orbiter](https://github.com/mattt/Orbiter).
 
 ## Installation
 
@@ -21,56 +21,133 @@ Another caveat is that Houston doesn't manage device tokens for you. For that, y
 ## Usage
 
 ```ruby
+require 'houston'
+
 # Environment variables are automatically read, or can be overridden by any specified options. You can also
 # conveniently use `Houston::Client.development` or `Houston::Client.production`.
 APN = Houston::Client.development
-APN.certificate = File.read("/path/to/apple_push_notification.pem")
+APN.certificate = File.read('/path/to/apple_push_notification.pem')
 
 # An example of the token sent back when a device registers for notifications
-token = "<ce8be627 2e43e855 16033e24 b4c28922 0eeda487 9c477160 b2545e95 b68b5969>"
+token = '<ce8be627 2e43e855 16033e24 b4c28922 0eeda487 9c477160 b2545e95 b68b5969>'
 
 # Create a notification that alerts a message to the user, plays a sound, and sets the badge on the app
 notification = Houston::Notification.new(device: token)
-notification.alert = "Hello, World!"
+notification.alert = 'Hello, World!'
 
-# Notifications can also change the badge count, have a custom sound, indicate available Newsstand content, or pass along arbitrary data.
+# Notifications can also change the badge count, have a custom sound, have a category identifier, indicate available Newsstand content, or pass along arbitrary data.
 notification.badge = 57
-notification.sound = "sosumi.aiff"
+notification.sound = 'sosumi.aiff'
+notification.category = 'INVITE_CATEGORY'
 notification.content_available = true
-notification.custom_data = {foo: "bar"}
+notification.mutable_content = true
+notification.custom_data = { foo: 'bar' }
+notification.url_args = %w[boarding A998]
+notification.thread_id = 'notify-team-ios'
 
 # And... sent! That's all it takes.
 APN.push(notification)
 ```
 
+To generate a `.pem` file, it is recommended to use [fastlane pem](https://fastlane.tools/pem), which completely automates the process of creating the certificate.
+
+## Configuration
+
+Houston will attempt to load configuration data from environment variables, if they're present. The following variables will be used.
+
+| Environment Variable | Description |
+| --- | --- |
+| `APN_GATEWAY_URI` | The base URI for the APNS service to use. If left blank, will use the default APNS Production Gateway URI. |
+| `APN_FEEDBACK_URI` | The base URI for the APNS feedback service to use. If left blank, will use the default APNS Production Feedback URI. |
+| `APN_CERTIFICATE` | The file path to a valid APNS push certificate in `.pem` format (see "[Converting Your Certificate](#converting-your-certificate)" below). |
+| `APN_CERTIFICATE_DATA` | The contents of a valid APNS push certificate in `.pem` format (see "[Converting Your Certificate](#converting-your-certificate)" below); used in lieu of `APN_CERTIFICATE` if that variable is not provided. |
+| `APN_CERTIFICATE_PASSPHRASE` | If the APNS certificate is protected by a passphrase, provide this variable to use when decrypting it. |
+| `APN_TIMEOUT` | The timeout used when communicating with APNS. If not provided, the default of 0.5 seconds is used. |
+
+### Error Handling
+
+If an error occurs when sending a particular notification, its `error` attribute will be populated:
+
+```ruby
+puts "Error: #{notification.error}." if notification.error
+```
+
+### Silent Notifications
+
+To send a silent push notification, set `sound` to an empty string (`''`):
+
+```ruby
+Houston::Notification.new(sound: '', content_available: true)
+```
+
+### Mutable Notifications
+
+To send a mutable push notification (supported by iOS 10+), set `mutable_content` to `true`:
+
+```ruby
+Houston::Notification.new(mutable_content: true)
+```
+
 ### Persistent Connections
 
 If you want to manage your own persistent connection to Apple push services, such as for background workers, here's how to do it:
 
 ```ruby
-certificate = File.read("/path/to/apple_push_notification.pem")
-passphrase = "..."
-connection = Houston::Connection.new(APPLE_DEVELOPMENT_GATEWAY_URI, certificate, passphrase)
+certificate = File.read('/path/to/apple_push_notification.pem')
+passphrase = '...'
+connection = Houston::Connection.new(Houston::APPLE_DEVELOPMENT_GATEWAY_URI, certificate, passphrase)
 connection.open
 
 notification = Houston::Notification.new(device: token)
-notification.alert = "Hello, World!"
+notification.alert = 'Hello, World!'
 connection.write(notification.message)
 
 connection.close
 ```
 
+### Feedback Service
+
+Apple provides a feedback service to query for unregistered device tokens, these are devices that have failed to receive a push notification and should be removed from your application. You should periodically query for and remove these devices, Apple audits providers to ensure they are removing unregistered devices. To obtain the list of unregistered device tokens:
+
+```ruby
+Houston::Client.development.devices
+```
+
+In practice, you'll use a reference to instance of the APN object you create (see the Usage section). Here's a rake job that marks device tokens as invalid based on the feedback service from Apple. This example assumes devices are tracked in a model called Device (i.e. `User.devices`).
+
+In `lib/tasks/notifications.rake`:
+
+```ruby
+namespace :notifications do
+  task device_token_feedback: [:environment] do
+    APN.unregistered_devices.each do |device_hash|
+      # Format: { token: token, timestamp: timestamp }
+      device = Device.find_by(token: device_hash[:token])
+      next unless device.present?
+      # Remove device token
+      device.update_attribute(:device_token, nil)
+    end
+  end
+end
+```
+
+## Versioning
+
+Houston 2.0 supports the new [enhanced notification format](https://developer.apple.com/library/ios/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/CommunicatingWIthAPS.html#//apple_ref/doc/uid/TP40008194-CH101-SW4). Support for the legacy notification format is available in 1.x releases.
+
 ## Command Line Tool
 
 Houston also comes with the `apn` binary, which provides a convenient way to test notifications from the command line.
 
-    $ apn push "<token>" -c /path/to/apple_push_notification.pem -m "Hello from the command line!"
+    $ apn push "<token>" -c /path/to/apple_push_notification.pem -m "Hello from the command line! "
 
 ## Enabling Push Notifications on iOS
 
-### AppDelegate.m
+### Objective-C
 
 ```objective-c
+// AppDelegate.m
+
 - (void)applicationDidFinishLaunching:(UIApplication *)application {
   // ...
 
@@ -92,6 +169,24 @@ didFailToRegisterForRemoteNotificationsWithError:(NSError *)error
 }
 ```
 
+### Swift 
+```swift
+// AppDelegate.swift
+
+func application(_ application: UIApplication, willFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey : Any]? = nil) -> Bool {
+    application.registerForRemoteNotifications()
+    return true
+}
+
+func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
+    // Register the device token with a webservice
+}
+
+func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
+    print("error \(error)")
+}
+```
+
 ## Converting Your Certificate
 
 > These instructions come from the [APN on Rails](https://github.com/PRX/apn_on_rails) project, which is another great option for sending push notifications.
@@ -103,17 +198,21 @@ and the apple certificate as p12 files. Here is a quick walkthrough on how to do
 2. Right click and choose `Export 2 items…`.
 3. Choose the p12 format from the drop down and name it `cert.p12`.
 
-Now covert the p12 file to a pem file:
+Now convert the p12 file to a pem file:
+
+**Unencrypted private key (do not store this certificate in version control)**
 
     $ openssl pkcs12 -in cert.p12 -out apple_push_notification.pem -nodes -clcerts
 
-## Contact
+**Encrypted private key**
+
+    $ openssl pkcs12 -in cert.p12 -out apple_push_notification.pem -aes256 -clcerts
+
+You'll have to specify the password in the `APN_CERTIFICATE_PASSPHRASE` environment variable if you use the encrypted option.
 
-Mattt Thompson
+## Creator
 
-- http://github.com/mattt
-- http://twitter.com/mattt
-- m@mattt.me
+Mattt Thompson ([@mattt](https://twitter.com/mattt))
 
 ## License
 

data/Rakefile

@@ -1,10 +1,6 @@
-require "bundler"
-Bundler.setup
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 
-gemspec = eval(File.read("houston.gemspec"))
+RSpec::Core::RakeTask.new(:spec)
 
-task :build => "#{gemspec.full_name}.gem"
-
-file "#{gemspec.full_name}.gem" => gemspec.files + ["houston.gemspec"] do
-  system "gem build houston.gemspec"
-end
+task default: :spec

data/bin/apn

@@ -25,6 +25,7 @@ command :push do |c|
   c.option '-m', '--alert ALERT', 'Body of the alert to send in the push notification'
   c.option '-b', '--badge NUMBER', 'Badge number to set with the push notification'
   c.option '-s', '--sound SOUND', 'Sound to play with the notification'
+  c.option '-y', '--category CATEGORY', 'Category of notification'
   c.option '-n', '--[no]-newsstand', 'Indicates content available for Newsstand'
   c.option '-d', '--data KEY=VALUE', Array, 'Passes custom data to payload (as comma-delimited "key=value" declarations)'
   c.option '-P', '--payload PAYLOAD', 'JSON payload for notifications'
@@ -42,12 +43,13 @@ command :push do |c|
     say_error "Missing certificate file option (-c /path/to/certificate.pem)" and abort unless @certificate
     say_error "Could not find certificate file '#{@certificate}'" and abort unless File.exists?(@certificate)
 
-    @passphrase = options.passphrase ? password : ""
+    @passphrase = options.passphrase ? password : nil
 
     @alert = options.alert
     @badge = options.badge.nil? ? nil : options.badge.to_i
     @sound = options.sound
-    @content_available = options.newsstand
+    @category = options.category
+    @content_available = !!options.newsstand
 
     if options.payload
       begin
@@ -63,7 +65,7 @@ command :push do |c|
       end
     end
 
-    unless @alert or @badge or @newsstand or @data
+    unless @alert or @badge or @content_available or @data
       placeholder = "Enter your alert message"
       @alert = ask_editor placeholder
       say_error "Payload contents required" and abort if @alert.nil? or @alert == placeholder
@@ -76,21 +78,84 @@ command :push do |c|
       notification.alert = @alert if @alert
       notification.badge = @badge if @badge
       notification.sound = @sound if @sound
+      notification.category = @category if @category
       notification.content_available = @content_available if @content_available
 
       @notifications << notification
     end
 
-    client = @environment == :production ? Houston::Client.production : Houston::Client.development
+    client = (@environment == :production) ? Houston::Client.production : Houston::Client.development
     client.certificate = File.read(@certificate)
     client.passphrase = @passphrase
 
     begin
       client.push(*@notifications)
+
+      sent, unsent = @notifications.partition{|notification| notification.sent?}
+
+      if sent.any?
+        case sent.length
+        when 1
+          say_ok "1 push notification sent successfully"
+        else
+          say_ok "#{sent.length} push notifications sent successfully"
+        end
+      end
+
+      if unsent.any?
+        tokens = unsent.map{|notification| "\n - #{notification.token}"}.join
+
+        case unsent.length
+        when 1
+          say_error "1 push notification unsuccessful (#{tokens})"
+        else
+          say_error "#{unsent.length} push notifications unsuccessful (#{tokens})"
+        end
+      end
+
     rescue => message
       say_error "Exception sending notification: #{message}" and abort
     end
+  end
+end
+
+command :feedback do |c|
+  c.syntax = 'apn feedback [...]'
+  c.summary = 'Queries the APN Feedback Service for failed device tokens.'
+  c.description = ''
+
+  c.example 'description', 'apn feedback -c /path/to/apple_push_certificate.pem'
+  c.option '-c', '--certificate CERTIFICATE', 'Path to certificate (.pem) file'
+  c.option '-e', '--environment ENV', [:production, :development], 'Environment to send push notification (production or development (default))'
+  c.option '-p', '--[no]-passphrase', 'Prompt for a certificate passphrase'
+
+  c.action do |args, options|
+
+    @environment = options.environment.downcase.to_sym rescue :development
+    say_error "Invalid environment,'#{@environment}' (should be either :development or :production)" and abort unless [:development, :production].include?(@environment)
+
+    @certificate = options.certificate
+    say_error "Missing certificate file option (-c /path/to/certificate.pem)" and abort unless @certificate
+    say_error "Could not find certificate file '#{@certificate}'" and abort unless File.exists?(@certificate)
+
+    @passphrase = options.passphrase ? password : nil
+
+    client = (@environment == :production) ? Houston::Client.production : Houston::Client.development
+    client.certificate = File.read(@certificate)
+    client.passphrase = @passphrase
+
+    begin
+      feedbackDevices = client.unregistered_devices
+
+      if feedbackDevices.any? && feedbackDevices.length > 0
+        puts feedbackDevices.to_json
+      else
+        say_ok "No feedback available"
+      end
+
+    rescue => message
+      say_error "Exception querying feedback: #{message}" and abort
+    end
 
-    say_ok "Push notifications successfully sent"
   end
 end