heap 0.3.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 992e7bd97687607e875d6e2dac4707d7960e7291
-  data.tar.gz: a6427ae5dc85adf302fc2c93678645de9bf689b6
+  metadata.gz: b7f4270c4f06512b348491c08a91e7e44c293337
+  data.tar.gz: d7f95a6e3e4dbb399ee899dca956690eec30aef6
 SHA512:
-  metadata.gz: 3324a105c31d73f7e4bea0133abac9bbd420b99d51b868b439b329095760c345d42b1161e8dae6db60f990b1863c8963a0826d7e165944934c072476df137625
-  data.tar.gz: fa93c36b25573134b8599296f774a2d44bfeb6e5d472fcd437dba328e17cbb65fccb6f46259527b1970fbcb10a9cda44b71736b8dc6857a1c3ee6064d19e3c3d
+  metadata.gz: d873b49995396816be5c824b3dc47848a69ee614fd3228b9c3e62208e24a65e884303bd31c72e648597207289ef8b5e614e98bb0f9ca6f7591421c18ef3e0584
+  data.tar.gz: 8b27c441c8c46d0e2c15260006818dab9eed08f83f79567fd4564232e2fb73c33ff23aa918f575d11080f6fa71d7bcc194349b6b1938d49598ff27cdaa555911

data/.travis.yml

@@ -0,0 +1,16 @@
+sudo: false
+language: ruby
+matrix:
+  include:
+    - rvm: 1.8.7
+      gemfile: Gemfile187
+    - rvm: 1.9.3
+      gemfile: Gemfile
+    - rvm: 2.0.0
+      gemfile: Gemfile
+    - rvm: 2.1.8
+      gemfile: Gemfile
+    - rvm: 2.2.4
+      gemfile: Gemfile
+    - rvm: 2.3.0
+      gemfile: Gemfile

data/Gemfile

@@ -1,12 +1,15 @@
-source "https://rubygems.org"
+source 'https://rubygems.org'
 
-  gem "httparty", "~> 0.13"
+# Add dependencies required to use your gem here.
+gem 'faraday', '>= 0.8.11'
+gem 'faraday_middleware', '>= 0.8.0'
 
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
 group :development do
-  gem "shoulda", ">= 0"
-  gem "rdoc", "~> 3.12"
-  gem "bundler", "~> 1.0"
-  gem "jeweler", "~> 2.0.1"
-  gem "simplecov", ">= 0"
-  gem "webmock", "~>1.20"
+  gem 'minitest', '>= 0'
+  gem 'yard', '>= 0.8.7.6'
+  gem 'rdoc', '>= 3.12'
+  gem 'bundler', '>= 1.0'
+  gem 'jeweler', '>= 2.0.1'
 end

data/Gemfile187

@@ -0,0 +1,23 @@
+source 'https://rubygems.org'
+
+# Add dependencies required to use your gem here.
+gem 'faraday', '~> 0.8.11'
+gem 'faraday_middleware', '~> 0.8.0'
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem 'minitest', '>= 0'
+  gem 'yard', '>= 0.8.7.6'
+  gem 'rdoc', '>= 3.12'
+  gem 'bundler', '>= 1.0'
+
+  # NOTE: The latest versions of these dependencies do not support Ruby 1.8.7.
+  gem 'jeweler', '~> 1.8.8'
+
+  # NOTE: These are dependencies of the gems that we require whose latest
+  #       versions do not support Ruby 1.8.7.
+  gem 'addressable', '~> 2.3.8'
+  gem 'git', '~> 1.2.9'
+  gem 'highline', '~> 1.6.21'
+end

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2014 Dennis de Reus
+Copyright (c) 2016 Heap Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the
@@ -17,4 +17,4 @@ 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.
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,120 @@
+# Heap Server-Side API Client for Ruby
+
+[![Build Status](https://travis-ci.org/heap/heap-ruby.svg?branch=master)](https://travis-ci.org/heap/heap-ruby)
+[![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://rubydoc.info/github/heap/heap-ruby/master/frames)
+[![Gem Version](https://badge.fury.io/rb/heap.svg)](https://badge.fury.io/rb/heap)
+
+This is a Ruby client for the [Heap](https://heapanalytics.com/)
+[server-side API](https://heapanalytics.com/docs/server-side).
+
+
+## Prerequisites
+
+This gem is tested on Ruby 1.8.7 and above.
+
+
+## Installation
+
+If you're using [bundler](http://bundler.io/), add the following line to your
+[Gemfile](http://bundler.io/v1.11/gemfile.html).
+
+```ruby
+gem 'heap', '~> 1.0'
+```
+
+Otherwise, install the [heap](https://rubygems.org/gems/heap) gem and activate
+it in your code manually.
+
+```bash
+gem install heap
+```
+
+```ruby
+require 'heap'
+```
+
+
+## Setup
+
+Place the following code in a file that executes when your application
+initializes.
+
+```ruby
+Heap.app_id = 'YOUR_APP_ID'
+```
+
+In a Ruby on Rails application, place the following snippet in an initializer,
+such as `config/initializers/heap.rb`.
+
+```ruby
+if Rails.env.production?
+  Heap.app_id = 'YOUR_APP_ID'
+else
+  Heap.app_id = 'YOUR_DEV_APP_ID'
+end
+```
+
+In some testing environments, connecting to outside servers is undesirable. Set
+the `stubbed` accessor to `true` to have all API calls succeed without
+generating any network traffic.
+
+```ruby
+class StubbedHeapTest < MiniTest::Test
+  def setup
+    Heap.stubbed = true
+  end
+
+  def teardown
+    Heap.stubbed = false
+  end
+
+  ...
+end
+```
+
+
+## Usage
+
+[Track](https://heapanalytics.com/docs/server-side#track) a server-side event.
+The properties are optional.
+
+```ruby
+Heap.track 'user-handle', 'event-name', property: 'value'
+```
+
+[Add properties](https://heapanalytics.com/docs/server-side#identify) to a
+user.
+
+```ruby
+Heap.add_user_properties 'user-handle', plan: 'premium1'
+```
+
+If the global API client instance stored in `Heap` is not a good fit for your
+application's architecture, create your own client instances.
+
+```ruby
+heap_client = Heap.new app_id: 'YOUR_APP_ID'
+heap_client.track 'user-handle', 'event-name', property: 'value'
+```
+
+
+## Legacy Gem Releases
+
+Gem versions below 1.0 come from
+[this repository](https://github.com/HectorMalot/heap), which is an entirely
+different codebase. We are very grateful to
+[@HectorMalot](https://github.com/HectorMalot) for donating the `heap` gem name
+to us.
+
+If you are using a pre-1.0 gem, please consider upgrading to an officially
+supported release. In the meantime, you can pin the old version in your
+`Gemfile`.
+
+```ruby
+gem 'heap', '~> 0.3'
+```
+
+
+## Copyright
+
+Copyright (c) 2016 Heap Inc., released under the MIT license.

data/Rakefile

@@ -15,13 +15,12 @@ require 'jeweler'
 Jeweler::Tasks.new do |gem|
   # gem is a Gem::Specification... see http://guides.rubygems.org/specification-reference/ for more options
   gem.name = "heap"
-  gem.homepage = "http://github.com/HectorMalot/heap"
+  gem.homepage = "http://github.com/heap/heap-ruby"
   gem.license = "MIT"
-  gem.summary = %Q{Easy integration of heapanalytics into your ruby app}
-  gem.description = %Q{Easy integration of heapanalytics into your ruby app}
-  gem.email = "dennisdereus@gmail.com"
-  gem.homepage = "https://github.com/HectorMalot/heap"
-  gem.authors = ["Dennis de Reus"]
+  gem.summary = %Q{Heap server-side API client}
+  gem.description = %Q{Implements Heap's server-side API}
+  gem.email = "victor@heapanalytics.com"
+  gem.authors = ["Victor Costan"]
   # dependencies defined in Gemfile
 end
 Jeweler::RubygemsDotOrgTasks.new
@@ -29,24 +28,11 @@ Jeweler::RubygemsDotOrgTasks.new
 require 'rake/testtask'
 Rake::TestTask.new(:test) do |test|
   test.libs << 'lib' << 'test'
-  test.pattern = 'test/**/test_*.rb'
+  test.pattern = 'test/**/*_test.rb'
   test.verbose = true
 end
 
-desc "Code coverage detail"
-task :simplecov do
-  ENV['COVERAGE'] = "true"
-  Rake::Task['test'].execute
-end
-
 task :default => :test
 
-require 'rdoc/task'
-Rake::RDocTask.new do |rdoc|
-  version = File.exist?('VERSION') ? File.read('VERSION') : ""
-
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "heap #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
+require 'yard'
+YARD::Rake::YardocTask.new

data/VERSION

@@ -1 +1 @@
-0.3.0
+1.0.0

data/heap.gemspec

@@ -2,76 +2,75 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: heap 0.3.0 ruby lib
+# stub: heap 1.0.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "heap"
-  s.version = "0.3.0"
+  s.version = "1.0.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib"]
-  s.authors = ["Dennis de Reus"]
-  s.date = "2015-09-04"
-  s.description = "Easy integration of heapanalytics into your ruby app"
-  s.email = "dennisdereus@gmail.com"
+  s.authors = ["Victor Costan"]
+  s.date = "2016-02-29"
+  s.description = "Implements Heap's server-side API"
+  s.email = "victor@heapanalytics.com"
   s.extra_rdoc_files = [
-    "CHANGELOG.mdown",
     "LICENSE.txt",
-    "README.mdown"
+    "README.md"
   ]
   s.files = [
     ".document",
-    "CHANGELOG.mdown",
+    ".travis.yml",
     "Gemfile",
-    "Gemfile.lock",
+    "Gemfile187",
     "LICENSE.txt",
-    "README.mdown",
+    "README.md",
     "Rakefile",
     "VERSION",
     "heap.gemspec",
-    "lib/generators/heap/install_generator.rb",
-    "lib/generators/templates/heap.rb",
     "lib/heap.rb",
-    "lib/heap/events.rb",
-    "lib/heap/railtie.rb",
-    "lib/heap/view_helpers.rb",
-    "test/helper.rb",
-    "test/test_heap.rb",
-    "test/test_view_helper.rb"
+    "lib/heap/client.rb",
+    "lib/heap/errors.rb",
+    "lib/heap/validations.rb",
+    "test/client_add_user_properties_test.rb",
+    "test/client_test.rb",
+    "test/client_track_test.rb",
+    "test/heap_test.rb",
+    "test/helper.rb"
   ]
-  s.homepage = "https://github.com/HectorMalot/heap"
+  s.homepage = "http://github.com/heap/heap-ruby"
   s.licenses = ["MIT"]
-  s.rubygems_version = "2.4.6"
-  s.summary = "Easy integration of heapanalytics into your ruby app"
+  s.rubygems_version = "2.5.1"
+  s.summary = "Heap server-side API client"
 
   if s.respond_to? :specification_version then
     s.specification_version = 4
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_runtime_dependency(%q<httparty>, ["~> 0.13"])
-      s.add_development_dependency(%q<shoulda>, [">= 0"])
-      s.add_development_dependency(%q<rdoc>, ["~> 3.12"])
-      s.add_development_dependency(%q<bundler>, ["~> 1.0"])
-      s.add_development_dependency(%q<jeweler>, ["~> 2.0.1"])
-      s.add_development_dependency(%q<simplecov>, [">= 0"])
-      s.add_development_dependency(%q<webmock>, ["~> 1.20"])
+      s.add_runtime_dependency(%q<faraday>, [">= 0.8.11"])
+      s.add_runtime_dependency(%q<faraday_middleware>, [">= 0.8.0"])
+      s.add_development_dependency(%q<minitest>, [">= 0"])
+      s.add_development_dependency(%q<yard>, [">= 0.8.7.6"])
+      s.add_development_dependency(%q<rdoc>, [">= 3.12"])
+      s.add_development_dependency(%q<bundler>, [">= 1.0"])
+      s.add_development_dependency(%q<jeweler>, [">= 2.0.1"])
     else
-      s.add_dependency(%q<httparty>, ["~> 0.13"])
-      s.add_dependency(%q<shoulda>, [">= 0"])
-      s.add_dependency(%q<rdoc>, ["~> 3.12"])
-      s.add_dependency(%q<bundler>, ["~> 1.0"])
-      s.add_dependency(%q<jeweler>, ["~> 2.0.1"])
-      s.add_dependency(%q<simplecov>, [">= 0"])
-      s.add_dependency(%q<webmock>, ["~> 1.20"])
+      s.add_dependency(%q<faraday>, [">= 0.8.11"])
+      s.add_dependency(%q<faraday_middleware>, [">= 0.8.0"])
+      s.add_dependency(%q<minitest>, [">= 0"])
+      s.add_dependency(%q<yard>, [">= 0.8.7.6"])
+      s.add_dependency(%q<rdoc>, [">= 3.12"])
+      s.add_dependency(%q<bundler>, [">= 1.0"])
+      s.add_dependency(%q<jeweler>, [">= 2.0.1"])
     end
   else
-    s.add_dependency(%q<httparty>, ["~> 0.13"])
-    s.add_dependency(%q<shoulda>, [">= 0"])
-    s.add_dependency(%q<rdoc>, ["~> 3.12"])
-    s.add_dependency(%q<bundler>, ["~> 1.0"])
-    s.add_dependency(%q<jeweler>, ["~> 2.0.1"])
-    s.add_dependency(%q<simplecov>, [">= 0"])
-    s.add_dependency(%q<webmock>, ["~> 1.20"])
+    s.add_dependency(%q<faraday>, [">= 0.8.11"])
+    s.add_dependency(%q<faraday_middleware>, [">= 0.8.0"])
+    s.add_dependency(%q<minitest>, [">= 0"])
+    s.add_dependency(%q<yard>, [">= 0.8.7.6"])
+    s.add_dependency(%q<rdoc>, [">= 3.12"])
+    s.add_dependency(%q<bundler>, [">= 1.0"])
+    s.add_dependency(%q<jeweler>, [">= 2.0.1"])
   end
 end
 

data/lib/heap.rb

@@ -1,25 +1,12 @@
-require 'httparty'
-require 'heap/events'
-require 'heap/railtie' if defined?(Rails)
-
-class Heap
-  include HTTParty
-  base_uri 'https://heapanalytics.com/api'
-  headers "Content-Type" => "application/json"
-
-  def self.app_id=(obj)
-    @@app_id = obj
-  end
-
-  def self.app_id
-    @@app_id
-  end
+# Namespace for all the classes in this gem.
+module HeapAPI
+  # @return {String} the version of this gem
+  VERSION = File.read(File.join(File.dirname(__FILE__), '..', 'VERSION')).strip
+end
 
-  def self.default_handle_type=(value)
-    @@handle_type = value
-  end
+require 'heap/client.rb'
+require 'heap/errors.rb'
+require 'heap/validations.rb'
 
-  def self.default_handle_type
-    @@handle_type ||= 'email'
-  end
-end
+# A global instance of {HeapAPI::Client}.
+Heap = HeapAPI::Client.new

data/lib/heap/client.rb

@@ -0,0 +1,192 @@
+require 'faraday'
+require 'faraday_middleware'
+
+# This is the class of the Heap object.
+class HeapAPI::Client
+  # @return [String] the Heap application ID from
+  #   https://heapanalytics.com/app/install
+  attr_accessor :app_id
+
+  # @return [Boolean] if true, all the requests to the Heap API are stubbed to
+  #   return successfully; this overrides the Faraday-related options
+  attr_reader :stubbed
+
+  # @return [Symbol] the Faraday adapter used by the Heap API server connection
+  # @see http://www.rubydoc.info/gems/faraday/
+  attr_reader :faraday_adapter
+
+  # @return [Array] arguments to the Faraday adapter used by the Heap API
+  #   server connection
+  attr_reader :faraday_adapter_args
+
+  # @return [String] the User-Agent header value
+  attr_accessor :user_agent
+
+  # Creates a new client for the Heap server-side API.
+  #
+  # For simplicity, consider using the global client instance referenced by the
+  # Heap constant instead of creating and managing new instances.
+  #
+  # @param [Hash<Symbol, Object>] options initial values for attributes
+  # @option options [String] app_id the Heap application ID from
+  # @option options [Hash<Symbol, Object>] js_options default heap.js advanced
+  #   options
+  # @option options [Boolean] stubbed if true, all the requests to the Heap API
+  #   are stubbed to return successfully; this overrides the Faraday-related
+  #   options
+  # @option options [Symbol] faraday_adapter the Faraday adapter used by the
+  #   Heap API server connection
+  # @option options [Array] faraday_adapter_args arguments to the Faraday
+  #   adapter used by the Heap API server connection
+  def initialize(options = {})
+    @app_id = nil
+    @live_connection = nil
+    @stubbed_connection = false
+    @stubbed = false
+    @faraday_adapter = Faraday.default_adapter
+    @faraday_adapter_args = []
+    @user_agent = "heap-ruby/#{HeapAPI::VERSION} " +
+        "faraday/#{Faraday::VERSION} ruby/#{RUBY_VERSION} (#{RUBY_PLATFORM})"
+
+    options.each do |key, value|
+      self.send :"#{key}=", value
+    end
+  end
+
+  def stubbed=(new_value)
+    @connection = nil
+    @stubbed = new_value
+  end
+
+  def faraday_adapter=(new_adapter)
+    raise RuntimeError, 'Faraday connection already initialized' if @connection
+    @faraday_adapter = new_adapter
+  end
+
+  def faraday_adapter_args=(new_args)
+    raise RuntimeError, 'Faraday connection already initialized' if @connection
+    unless new_args.instance_of? Array
+      raise ArgumentErrorm, "Arguments must be an array"
+    end
+    @faraday_adapter_args = new_args
+  end
+
+  # Assign custom properties to an existing user.
+  #
+  # @param [String] identity an e-mail, handle, or Heap-generated user ID
+  # @param [Hash<String, String|Number>] properties key-value properties
+  #   associated with the event; each key must have fewer than 1024 characters;
+  #   each value must be a Number or String with fewer than 1024 characters
+  # @return [HeapAPI::Client] self
+  # @see https://heapanalytics.com/docs/server-side#identify
+  def add_user_properties(identity, properties)
+    ensure_valid_app_id!
+    ensure_valid_properties! properties
+
+    body = {
+      :app_id => @app_id,
+      :identity => identity.to_s,
+      :properties => properties,
+    }
+    response = connection.post '/api/identify', body,
+        'User-Agent' => user_agent
+    raise HeapAPI::ApiError.new(response) unless response.success?
+    self
+  end
+
+  # Sends a custom event to the Heap API servers.
+  #
+  # @param [String] event the name of the server-side event; limited to 1024
+  #   characters
+  # @param [String] identity an e-mail, handle, or Heap-generated user ID
+  # @param [Hash<String, String|Number>] properties key-value properties
+  #   associated with the event; each key must have fewer than 1024 characters;
+  #   each value must be a Number or String with fewer than 1024 characters
+  # @return [HeapAPI::Client] self
+  # @see https://heapanalytics.com/docs/server-side#track
+  def track(event, identity, properties = nil)
+    ensure_valid_app_id!
+
+    event_name = event.to_s
+    ensure_valid_event_name! event_name
+
+    body = {
+      :app_id => @app_id,
+      :identity => identity.to_s,
+      :event => event,
+    }
+    unless properties.nil?
+      body[:properties] = properties
+      ensure_valid_properties! properties
+    end
+
+    response = connection.post '/api/track', body,
+        'User-Agent' => user_agent
+    raise HeapAPI::ApiError.new(response) unless response.success?
+    self
+  end
+
+  # The underlying Faraday connection used to make HTTP requests.
+  #
+  # @return [Faraday::Connection] a Faraday connection object
+  def connection
+    @connection ||= @stubbed ? stubbed_connection : live_connection
+  end
+
+  # The Faraday connection used to make HTTP requests to the Heap API server.
+  #
+  # This is used when {#stubbed?} is false.
+  #
+  # @return [Faraday::Connection] a Faraday connection object
+  def live_connection
+    @live_connection ||= live_connection!
+  end
+  private :live_connection
+
+  # The Faraday connection that stubs API calls to the Heap servers.
+  #
+  # This is used when {#stubbed?} is true.
+  #
+  # @return [Faraday::Connection] a Faraday connection object
+  def stubbed_connection
+    @stubbed_connection ||= stubbed_connection!
+  end
+  private :stubbed_connection
+
+  # Creates a new Faraday connection to the Heap API server.
+  #
+  # @return [Faraday::Connection] a Faraday connection object
+  def live_connection!
+    Faraday.new 'https://heapanalytics.com' do |c|
+      c.request :json
+      c.adapter @faraday_adapter, *@faraday_adapter_args
+    end
+  end
+  private :live_connection!
+
+  # Creates a new Faraday connection that stubs API calls to the Heap servers.
+  #
+  # @return [Faraday::Connection] a Faraday connection object
+  def stubbed_connection!
+    stubs = Faraday::Adapter::Test::Stubs.new do |stub|
+      stub.post('/api/identify') { |env| [204, {}, ''] }
+      stub.post('/api/track') { |env| [204, {}, ''] }
+    end
+
+    Faraday.new 'https://heapanalytics.com' do |c|
+      c.request :json
+      c.adapter :test, stubs
+    end
+  end
+  private :stubbed_connection!
+
+  # Creates a new client instance.
+  #
+  # This is defined here so `Heap.new` can be used as a shorthand for
+  # `HeapAPI::Client.new`.
+  #
+  # @see {HeapAPI::Client#initialize}
+  def new(*args)
+    HeapAPI::Client.new(*args)
+  end
+end