appygram 1.0.0 → 1.0.1

data/README.md

@@ -0,0 +1,118 @@
+# Appygram <http://www.appygram.com>
+
+Appygram is a simple service to handle messages from your web
+or mobile app. This gem provides communication with the Appygram
+service via a simple API. Useful features higher in the stack
+are found in gems that depend on this one, e.g. appygram-rails,
+which automatically turns uncaught Rails exceptions into traces.
+
+## Installation
+
+1.  Add gem entry to Gemfile
+    
+    ```ruby
+    gem 'appygram'
+    ```
+    
+2.  Run <code>bundle install</code>
+
+3.  Configure your API Key in an initializer, e.g. config/appygram.rb
+    
+    ```ruby
+    Appygram.configure :api_key => 'your_api_key'
+    ```
+    
+    using a valid API key for your app provided by Appygram
+
+## Invocation
+
+```ruby
+require 'appygram'
+
+# Sending an appygram
+Appygram.send :topic => 'Test', :message => 'This is a test.'
+
+# Sending a trace
+Appygram.trace some_exception
+
+# Sending a trace with accompanying appygram fields
+Appygram.trace some_exception, :email => 'some_user@domain'
+```
+
+## Supported fields in an appygram
+
+*   topic - of principal importance in message routing
+*   subject
+*   message
+*   name
+*   email
+*   phone
+*   platform ('web' by default for this connector)
+*   software ('appygram.rb [VERSION]' by default for this connector)
+*   app_json - Any object assigned to this field will be serialized
+    into JSON. If it is a hash, top level keys will be addressable
+    in the message routing and formatting.
+
+## Traces
+
+*   Traces send the current stack trace from your application.
+*   Appygram deduplicates traces and treats them statistically;
+    traces are converted to notifications based on rules agreed by
+    the system and the user.
+*   If you send fields (like "name" and "email") along with the
+    trace, Appygram can put that information into notifications.
+    For example, if you generate a trace because of an unexpected
+    exception, and you include the contact information for the
+    logged-in user who experienced the exception, responders can
+    more easily identify and communicate with the affected user
+    about what might have led to the exception.
+
+## Additional configuration options
+
+You can call Appygram.configure multiple times safely, or pack
+all the options you need into one call.
+
+To minimize network bandwidth in the event that your app generates
+a LOT of traces, you can throttle the trace sender when you configure
+Appygram. You can throttle all traces on a per-second basis, or
+duplicate traces per day.
+
+```ruby
+Appygram.configure :max_traces_per_second => 3
+# and/or
+Appygram.configure :max_duplicate_traces_per_day => 1
+```
+
+You can set defaults for the platform or software at configuration time.
+
+```ruby
+Appygram.configure :platform => 'Ruboto'
+# and/or
+Appygram.configure :software => 'awesomesauce'
+```
+
+The standard endpoints for Appygram are built in. If you need to change
+them, you can configure <code>:appygram_endpoint</code> and
+<code>:trace_endpoint</code> to the full URL destination where data is
+to be sent.
+
+If you send traces, you can provide a map of uri stubs to paths
+within your application. Appygram will use these to hyperlink
+the traces to the appropriate repository online. This map may
+be also populated by higher level gems, like appygram_rails;
+anything you supply here will be additively merged.
+
+```ruby
+Appygram.add_trace_uris 'lib' => 'http://github.com/anythinglabs/appygram.rb'
+```
+
+## Rules for improvement
+
+*   This gem must not have other dependencies.
+*   This gem may take advantage of other gems (e.g. async i/o,
+    background queueing, http pooling) if detected, and the advantage
+    is related directly to communication with the service
+*   Effort should be made to retain parity with other fully supported
+    connectors
+
+Copyright © 2012 Solertium

data/Rakefile

@@ -1 +1,7 @@
 require "bundler/gem_tasks"
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'lib/appygram'
+  t.test_files = FileList['test/*.rb']
+end

data/lib/appygram.rb

@@ -1,14 +1,28 @@
 require "appygram/version"
 require 'net/http'
 require 'net/https'
+require 'json'
 
 module Appygram
   def self.configure(params)
-    Appygram::Config.api_key = params[:api_key]
-    endpoint = params[:endpoint] || 'https://appygram.herokuapp.com/appygrams'
-    Appygram::Config.endpoint = URI endpoint
-    Appygram::Config.platform = params[:platform] || 'web'
-    Appygram::Config.software = params[:software] || "appygram.rb #{Appygram::VERSION}"
+    if params[:api_key]
+      Appygram::Config.api_key = params[:api_key]
+    end
+    if params[:appygram_endpoint]
+      appygram_endpoint = params[:appygram_endpoint] || 'https://appygram.herokuapp.com/appygrams'
+      Appygram::Config.appygram_endpoint = URI appygram_endpoint
+    end
+    if params[:trace_endpoint]
+      trace_endpoint = params[:trace_endpoint] || 'https://appygram.appspot.com/traces'
+      Appygram::Config.trace_endpoint = URI trace_endpoint
+    end
+    if params[:platform]
+      Appygram::Config.platform = params[:platform] || 'web'
+    end
+    if params[:software]
+      Appygram::Config.software = params[:software] || "appygram.rb #{Appygram::VERSION}"
+    end
+    # TODO: respect throttling per readme
   end
 
   def self.send(params)
@@ -16,8 +30,38 @@ module Appygram
     pc[:api_key] = Appygram::Config.api_key
     pc[:platform] = Appygram::Config.platform unless pc[:platform]
     pc[:software] = Appygram::Config.software unless pc[:software]
-    url = Appygram::Config.endpoint
+    if pc[:app_json]
+      pc[:app_json] = JSON pc[:app_json]
+    end
+    url = Appygram::Config.appygram_endpoint
+    req = Net::HTTP::Post.new url.request_uri
+    req.form_data = pc
+    session = Net::HTTP.new(url.hostname, url.port)
+    session.use_ssl = true
+    session.start {|http|
+      http.request(req)
+    }
+  end
+
+  def self.trace(exception, params = {})
+    pc = params.clone
+    pc[:api_key] = Appygram::Config.api_key
+    pc[:platform] = Appygram::Config.platform unless pc[:platform]
+    pc[:software] = Appygram::Config.software unless pc[:software]
+    if pc[:app_json]
+      pc[:app_json] = JSON pc[:app_json]
+    end
+    url = Appygram::Config.trace_endpoint
     req = Net::HTTP::Post.new url.request_uri
+    trace = []
+    exception.backtrace.each do |line|
+      trace << line.split(':')
+    end
+    pc[:trace] = JSON({
+      'class' => exception.class.name,
+      'message' => exception.message,
+      'backtrace' => trace
+    })
     req.form_data = pc
     session = Net::HTTP.new(url.hostname, url.port)
     session.use_ssl = true
@@ -28,12 +72,15 @@ module Appygram
 
   class Config
     class << self
-      attr_accessor :api_key, :endpoint, :software, :platform
+      attr_accessor :api_key, :appygram_endpoint, :trace_endpoint, :software, :platform
       def api_key
         return @api_key unless @api_key.nil?
       end
-      def endpoint
-        return @endpoint unless @endpoint.nil?
+      def appygram_endpoint
+        return @appygram_endpoint unless @appygram_endpoint.nil?
+      end
+      def trace_endpoint
+        return @trace_endpoint unless @trace_endpoint.nil?
       end
       def software
         return @software unless @software.nil?

data/lib/appygram/version.rb

@@ -1,3 +1,3 @@
 module Appygram
-  VERSION = "1.0.0"
+  VERSION = "1.0.1"
 end

data/test/local.rb

@@ -0,0 +1,35 @@
+require 'minitest/autorun'
+require 'appygram'
+
+describe Appygram do
+  describe "when invoking the gem" do
+    it "must have a version number" do
+      Appygram::VERSION.wont_be_nil
+    end
+  end
+  describe "when configuring" do
+    it "must support setting the API key" do
+      Appygram.configure :api_key => '123'
+      Appygram::Config.api_key.must_equal '123'
+    end
+    it "must support setting the platform" do
+      Appygram.configure :platform => 'test_plat'
+      Appygram::Config.platform.must_equal 'test_plat'
+    end
+    it "must support setting the software" do
+      Appygram.configure :software => 'test_sw'
+      Appygram::Config.software.must_equal 'test_sw'
+    end
+    it "must support overriding the appygram endpoint" do
+      Appygram.configure :appygram_endpoint => 'http://a/b'
+      Appygram::Config.appygram_endpoint.to_s.must_equal 'http://a/b'
+    end
+    it "must support overriding the trace endpoint" do
+      Appygram.configure :trace_endpoint => 'http://a/b'
+      Appygram::Config.trace_endpoint.to_s.must_equal 'http://a/b'
+    end
+    it "must not clobber values set earlier" do
+      Appygram::Config.platform.must_equal 'test_plat'
+    end
+  end
+end

data/test/network.rb

@@ -0,0 +1,23 @@
+require 'minitest/autorun'
+require 'appygram'
+
+describe Appygram do
+  before do
+    Appygram.configure :api_key => '6135441b70dc91c092fef59cb983f97eada68b75',
+      :appygram_endpoint => 'https://appygram.herokuapp.com/appygrams',
+      :trace_endpoint => 'https://appygram.appspot.com/traces'
+  end
+  describe "When connected to real servers" do
+    it "sends appygrams" do
+      Appygram.send :topic => 'Test', :message => 'This is a test.',
+        :app_json => { 'key' => 'value' }
+    end
+    it "sends traces" do
+      begin
+        raise "boom"
+      rescue StandardError => e
+        Appygram.trace e
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: appygram
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-09-13 00:00:00.000000000 Z
+date: 2012-11-03 00:00:00.000000000 Z
 dependencies: []
 description: Discovers topics and sends messages
 email:
@@ -20,11 +20,13 @@ extra_rdoc_files: []
 files:
 - .gitignore
 - Gemfile
-- README.markdown
+- README.md
 - Rakefile
 - appygram.gemspec
 - lib/appygram.rb
 - lib/appygram/version.rb
+- test/local.rb
+- test/network.rb
 homepage: https://github.com/anythinglabs/appygram.rb
 licenses: []
 post_install_message: 
@@ -45,8 +47,11 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: appygram
-rubygems_version: 1.8.15
+rubygems_version: 1.8.17
 signing_key: 
 specification_version: 3
 summary: Communicate with the Appygram message routing service
-test_files: []
+test_files:
+- test/local.rb
+- test/network.rb
+has_rdoc: 

data/README.markdown

@@ -1,55 +0,0 @@
-# Appygram <http://www.appygram.com>
-
-Appygram is a simple service to handle messages from your web
-or mobile app. This gem provides communication with the Appygram
-service via a simple API. Useful features higher in the stack
-are found in gems that depend on this one, e.g. appygram-rails,
-which turns uncaught Rails exceptions into appygrams.
-
-## Installation
-
-1.  Add gem entry to Gemfile
-    
-    ```ruby
-    gem 'appygram'
-    ```
-    
-2.  Run <code>bundle install</code>
-
-3.  Configure your API Key in an initializer, e.g. config/appygram.rb
-    
-    ```ruby
-    Appygram.configure :api_key => 'your_api_key'
-    ```
-    
-    using a valid API key for your app provided by Appygram
-
-## Invocation
-
-   ```ruby
-   require 'appygram'
-
-   Appygram.send :topic => 'Test', :message => 'This is a test.'
-   ```
-
-## Supported fields in an appygram
-
-* topic
-* subject
-* message
-* name
-* email
-* phone
-* platform ('web' by default for this connector)
-* software ('appygram.rb [VERSION]' by default for this connector)
-
-## Rules for improvement
-
-* This gem must not have other dependencies.
-* This gem may take advantage of other gems (e.g. async i/o,
-  background queueing, http pooling) if detected, and the advantage
-  is related directly to communication with the service
-* Effort should be made to retain parity with other fully supported
-  connectors
-
-Copyright © 2012 Solertium