userlist 0.2.2 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: f6f2d40e30040c90510fd29c62e3b7738a323c11
-  data.tar.gz: 3c4a710406464f67038df488ee9d796bb18fe220
+SHA256:
+  metadata.gz: 1f8e5ee8f9d8d18f98ebc7744ced642b9641ec6bd156fff4fbf0352be37dbaa2
+  data.tar.gz: a532a136941e347e7c7dc454f3ec7a735990f53abd8ddaff1bdf50eb67a3c219
 SHA512:
-  metadata.gz: 096e7606aa25d4bdfdb52b96e4f17d0a10fb187d087e90d21dc70c8acf24acf221657e0cf68f0983ed53831083116357279ca9a591a6f3d14de2e48f761c8020
-  data.tar.gz: e6716c672ca4dd340dd57cc14c5a808e5af74630b5b18de48b8921167392418c5ece53d7f07a94f6535d3dc264ecd6ef11c3be6df7388d996055f99cf0a4c085
+  metadata.gz: 9065b7f9af8fc5692b334bcfa97410ee3260544f02cd6440cea57150d3daceb1e62c5b8fba8780f4309da764603966842b59064baad786918f1f23381a8ba0b5
+  data.tar.gz: f01918dafbaa9a837b25503f667b1387998036a5a626cce75fe3f45ef80539cb6e57aa9ab512bf8813f039b959eb138039ab0086bd98342dec5ef61f2d129969

data/.github/workflows/test.yml

@@ -0,0 +1,21 @@
+name: Tests
+on: [push]
+jobs:
+  build:
+    strategy:
+      matrix:
+        ruby:
+          - 2.4
+          - 2.5
+          - 2.6
+          - 2.7
+          - 3.0
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - name: RSpec
+        run: bundle exec rake

data/.gitignore

@@ -10,3 +10,4 @@
 
 # rspec failure tracking
 .rspec_status
+/.env

data/.rubocop.yml

@@ -1,10 +1,11 @@
 AllCops:
-  TargetRubyVersion: 2.2
+  TargetRubyVersion: 2.4
+  NewCops: enable
   Exclude:
     - 'bin/*'
     - 'Guardfile'
 
-Metrics/LineLength:
+Layout/LineLength:
   Enabled: false
 
 Metrics/ModuleLength:
@@ -32,13 +33,13 @@ Layout/ElseAlignment:
 Lint/AssignmentInCondition:
   Enabled: false
 
-Lint/EndAlignment:
+Layout/EndAlignment:
   EnforcedStyleAlignWith: start_of_line
 
 Layout/AccessModifierIndentation:
   EnforcedStyle: outdent
 
-Layout/AlignParameters:
+Layout/ParameterAlignment:
   EnforcedStyle: with_fixed_indentation
 
 Style/FrozenStringLiteralComment:

data/Gemfile

@@ -6,3 +6,6 @@ gemspec
 
 gem 'guard-rspec', '~> 4.7'
 gem 'guard-rubocop', '~> 1.3'
+gem 'rubocop', '~> 0.68'
+
+gem 'sidekiq'

data/README.md

@@ -1,8 +1,8 @@
-# Userlist
+# Userlist for Ruby  [![Build Status](https://github.com/userlist/userlist-ruby/workflows/Tests/badge.svg)](https://github.com/userlist/userlist-ruby)
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/userlist`. To experiment with that code, run `bin/console` for an interactive prompt.
+This gem helps with integrating [Userlist](https://userlist.com) into Ruby applications.
 
-TODO: Delete this and the text above, and describe your gem
+> To integrate Userlist into a Ruby on Rails application, please use [userlist-rails](https://github.com/userlist/userlist-rails)
 
 ## Installation
 
@@ -20,9 +20,180 @@ Or install it yourself as:
 
     $ gem install userlist
 
+## Configuration
+
+The only required configuration is the Push API key. You can get your Push API key via the [Push API settings](https://app.userlist.com/settings/push) in your Userlist account.
+
+Configuration values can either be set via the `Userlist.configure` method or as environment variables. The environment variables take precedence over configuration values from the initializer.
+
+Configuration via environment variables:
+
+```shell
+USERLIST_PUSH_KEY=VvB7pjDrv0V2hoaOCeZ5rIiUEPbEhSUN
+USERLIST_PUSH_ID=6vPkJl44cm82y4aLBIzaOhuEHJd0Bm7b
+```
+
+Configuration via an initializer:
+
+```ruby
+Userlist.configure do |config|
+  config.push_key = 'VvB7pjDrv0V2hoaOCeZ5rIiUEPbEhSUN'
+  config.push_id = '6vPkJl44cm82y4aLBIzaOhuEHJd0Bm7b'
+end
+```
+
+The possible configuration values are listed in the table below.
+
+| Name                    | Default value                | Description                                                                                                                 |
+| ----------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `push_key`              | `nil`                        | The push key for your account. See [Push API settings](https://app.userlist.com/settings/push).                             |
+| `push_id`               | `nil`                        | The push id for your account. See [Push API settings](https://app.userlist.com/settings/push).                              |
+| `push_endpoint`         | `https://push.userlist.com/` | The HTTP endpoint that the library will send data to.                                                                       |
+| `push_strategy`         | `:threaded`                  | The strategy to use to send data to the HTTP endpoint. Possible values are `:threaded`, `:sidekiq`, `:direct`, and `:null`. |
+| `push_strategy_options` | `{}`                         | Any additional options for the push strategy.                                                                               |
+| `log_level`             | `:warn`                      | The log level for Userlist related log messages. Possible values are `:debug`, `:error`, `:fatal`, `:info`, and `:warn`     |
+| `token_lifetime`        | `3600`                       | The lifetime of generated in-app messages tokens in seconds                                                                 |
+
+### Disabling in development and test environments
+
+As sending test and development data into data into Userlist isn't very desirable, you can disable transmissions by setting the push strategy to `:null`.
+
+```ruby
+Userlist.configure do |config|
+  config.push_strategy = :null
+end
+```
+
 ## Usage
 
-TODO: Write usage instructions here
+This library is a wrapper for Userlist's Push API. For details about the accepted payloads, please check [its documentation](https://userlist.com/docs/getting-started/integration-guide/).
+
+### Tracking Users
+
+To manually send user data into Userlist, use the `Userlist::Push.users.push` method.
+
+```ruby
+Userlist::Push.users.push(
+  identifier: 'user-1',
+  email: 'foo@example.com',
+  properties: {
+    first_name: 'Foo',
+    last_name: 'Example'
+  }
+)
+```
+
+It's also possible to delete a user from Userlist, using the `Userlist::Push.users.delete` method.
+
+```ruby
+Userlist::Push.users.delete('user-1')
+```
+
+### Tracking Companies
+
+To manually send company data into Userlist, use the `Userlist::Push.companies.push` method.
+
+```ruby
+Userlist::Push.companies.push(
+  identifier: 'company-1',
+  email: 'Example, Inc.',
+  properties: {
+    industry: 'Software Testing'
+  }
+)
+```
+
+It's also possible to delete a user from Userlist, using the `Userlist::Push.companies.delete` method.
+
+```ruby
+Userlist::Push.companies.delete('user-1')
+```
+
+### Tracking Relationships
+
+Tracking relationships can either be done using nested properties in user or company payloads or via the `Userlist::Push.relationships.push` method.
+
+```ruby
+Userlist::Push.relationships.push(
+  user: 'user-1',
+  company: 'company-1',
+  properties: {
+    role: 'owner'
+  }
+)
+```
+
+This is equivalent to specifying the relationship on the user model.
+
+```ruby
+Userlist::Push.users.push(
+  identifier: 'user-1',
+  relationships: [
+    {
+      company: 'company-1',
+      properties: {
+        role: 'owner'
+      }
+    }
+  ]
+)
+```
+
+It's also equivalent specifying the relationship on the company model.
+
+```ruby
+Userlist::Push.companies.push(
+  identifier: 'company-1',
+  relationships: [
+    {
+      user: 'user-1',
+      properties: {
+        role: 'owner'
+      }
+    }
+  ]
+)
+```
+
+### Tracking Events
+
+To track custom events use the `Userlist::Push.events.push` method.
+
+```ruby
+Userlist::Push.events.push(
+  name: 'project_created',
+  user: 'user-1',
+  properties: {
+    project_name: 'Example project'
+  }
+)
+```
+
+Instead of just sending a user or company identifier, it's also possible to expand the properties into objects. This will update the user / company record as well as trigger the event in one operation.
+
+```ruby
+Userlist::Push.events.push(
+  name: 'project_created',
+  user: {
+    identifier: 'user-1',
+    properties: {
+      projects: 5
+    }
+  },
+  properties: {
+    project_name: 'Example project'
+  }
+)
+```
+
+### Tokens for in-app messages
+
+In order to use in-app messages, you must create a JWT token for the currently signed in user on the server side. To do this, please configure both the `push_key` and the `push_id` configuration variables. Afterwards, you can use the `Userlist::Token.generate` method to get a signed token for the given user identifier.
+
+```ruby
+Userlist::Token.generate('user-1')
+# => "eyJraWQiOiI2dlBrSmw0NGNtODJ5NGFMQkl6YU9odU...kPGe8KX8JZBTQ"
+```
 
 ## Development
 
@@ -32,7 +203,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/userlist. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at <https://github.com/userlist/userlist-ruby>. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
 ## License
 
@@ -40,4 +211,12 @@ The gem is available as open source under the terms of the [MIT License](http://
 
 ## Code of Conduct
 
-Everyone interacting in the Userlist project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/userlist/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the Userlist project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/userlist/userlist-ruby/blob/master/CODE_OF_CONDUCT.md).
+
+## What is Userlist?
+
+[![Userlist](https://userlist.com/images/external/userlist-logo-github.svg)](https://userlist.com/)
+
+[Userlist](https://userlist.com/) allows you to onboard and engage your SaaS users with targeted behavior-based campaigns using email or in-app messages.
+
+Userlist was started in 2017 as an alternative to bulky enterprise messaging tools. We believe that running SaaS products should be more enjoyable. Learn more [about us](https://userlist.com/about-us/).

data/lib/userlist.rb

@@ -4,8 +4,35 @@ require 'userlist/version'
 require 'userlist/config'
 require 'userlist/logging'
 require 'userlist/push'
+require 'userlist/token'
 
 module Userlist
+  class Error < StandardError; end
+
+  class ArgumentError < Error; end
+
+  class ConfigurationError < Error
+    attr_reader :key
+
+    def initialize(key)
+      @key = key.to_sym
+
+      super <<~MESSAGE
+        Missing required configuration value for `#{key}`
+
+        Please set a value for `#{key}` using an environment variable:
+
+          USERLIST_#{key.to_s.upcase}=some-value-here
+
+        or via the `Userlist.configure` method:
+
+          Userlist.configure do |config|
+            config.#{key} = 'some-value-here'
+          end
+      MESSAGE
+    end
+  end
+
   class << self
     def config
       @config ||= Userlist::Config.new
@@ -13,7 +40,7 @@ module Userlist
 
     def logger
       @logger ||= begin
-        logger = Logger.new(STDOUT)
+        logger = Logger.new($stdout)
         logger.progname = 'userlist'
         logger.level = Logger.const_get(config.log_level.to_s.upcase)
         logger

data/lib/userlist/config.rb

@@ -2,9 +2,12 @@ module Userlist
   class Config
     DEFAULT_CONFIGURATION = {
       push_key: nil,
-      push_endpoint: 'https://push.userlist.io/',
+      push_id: nil,
+      push_endpoint: 'https://push.userlist.com/',
       push_strategy: :threaded,
-      log_level: :warn
+      push_strategy_options: {},
+      log_level: :warn,
+      token_lifetime: 3600
     }.freeze
 
     def initialize(config_from_initialize = {})
@@ -36,6 +39,10 @@ module Userlist
       config == other.config && parent == other.parent
     end
 
+    def token_lifetime
+      self[:token_lifetime]&.to_i
+    end
+
   protected
 
     attr_reader :config, :parent
@@ -52,11 +59,11 @@ module Userlist
     end
 
     def key?(key)
-      config.key?(key) || parent && parent.key?(key)
+      config.key?(key) || parent&.key?(key)
     end
 
     def [](key)
-      config[key] || parent && parent[key]
+      config.key?(key) ? config[key] : parent && parent[key]
     end
 
     def []=(key, value)

data/lib/userlist/push.rb

@@ -1,10 +1,24 @@
 require 'userlist/push/client'
 require 'userlist/push/strategies'
 
+require 'userlist/push/resource'
+require 'userlist/push/resource_collection'
+require 'userlist/push/relation'
+
+require 'userlist/push/operations/create'
+require 'userlist/push/operations/delete'
+
+require 'userlist/push/user'
+require 'userlist/push/company'
+require 'userlist/push/relationship'
+require 'userlist/push/event'
+
+require 'userlist/push/serializer'
+
 module Userlist
   class Push
     class << self
-      [:event, :track, :user, :identify, :company].each do |method|
+      [:event, :track, :user, :identify, :company, :users, :events, :companies, :relationships].each do |method|
         define_method(method) { |*args| default_push_instance.send(method, *args) }
       end
 
@@ -15,53 +29,42 @@ module Userlist
       end
     end
 
-    def initialize(config = {})
-      @config = Userlist.config.merge(config)
-      @mutex = Mutex.new
+    def initialize(configuration = {})
+      @config = Userlist.config.merge(configuration)
+      @strategy = Userlist::Push::Strategies.strategy_for(config.push_strategy, config)
     end
 
-    def event(payload = {})
-      with_mutex do
-        raise ArgumentError, 'Missing required payload hash' unless payload
-        raise ArgumentError, 'Missing required parameter :name' unless payload[:name]
-        raise ArgumentError, 'Missing required parameter :user' unless payload[:user]
-
-        payload[:occured_at] ||= Time.now
+    attr_reader :config, :strategy
 
-        strategy.call(:post, '/events', payload)
-      end
+    def events
+      @events ||= Relation.new(self, Event, [Operations::Create])
     end
-    alias track event
-
-    def user(payload = {})
-      with_mutex do
-        raise ArgumentError, 'Missing required payload hash' unless payload
-        raise ArgumentError, 'Missing required parameter :identifier' unless payload[:identifier]
 
-        strategy.call(:post, '/users', payload)
-      end
+    def users
+      @users ||= Relation.new(self, User, [Operations::Create, Operations::Delete])
     end
-    alias identify user
 
-    def company(payload = {})
-      with_mutex do
-        raise ArgumentError, 'Missing required payload hash' unless payload
-        raise ArgumentError, 'Missing required parameter :identifier' unless payload[:identifier]
-
-        strategy.call(:post, '/companies', payload)
-      end
+    def companies
+      @companies ||= Relation.new(self, Company, [Operations::Create, Operations::Delete])
     end
 
-  private
+    def relationships
+      @relationships ||= Relation.new(self, Relationship, [Operations::Create, Operations::Delete])
+    end
 
-    attr_reader :config
+    def event(payload = {})
+      events.create(payload)
+    end
 
-    def strategy
-      @strategy ||= Userlist::Push::Strategies.strategy_for(config.push_strategy, config)
+    def user(payload = {})
+      users.create(payload)
     end
 
-    def with_mutex(&block)
-      @mutex.synchronize(&block)
+    def company(payload = {})
+      companies.create(payload)
     end
+
+    alias track event
+    alias identify user
   end
 end