userlist-rails 0.3.0 → 0.5.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f4ac0764bfdecbc381ea029d3fa9e8e2b04aa7f668eff35f7f54d14b7e20d1e9
-  data.tar.gz: 31e4be6a0b8fe3b5a7cf172b9a07af9e6e5dac7a9edd38751b39416ddee8ad9e
+  metadata.gz: 5c07d01a265094da4cbd48cf116bb6f883e22a2d3c4f6f70f36866ee02081f28
+  data.tar.gz: 2f6c5bf68403019e08188ce1cd7aeea7bda6233634633d7025161ffd54dee6f2
 SHA512:
-  metadata.gz: 3053ce85e9cc0d218dec274d0a11b5e0fb9caac714b999a2e3a0995946b17ae5f0180159fd978ecc91c890230cf8c744d3e9ddcfe67f1b035eb19c610ce49bbd
-  data.tar.gz: 0a426f64b71938dfea7112c62d96b97e568a47db3a8f1780571ad3612d0f7f39e8cc8c6f2511a5344b95785ad4efe18e8a5f9e912c886a9f2587601716bf2b46
+  metadata.gz: a009f824dbc922c3dca025e0fccc6e162d19fa23f87b15d6bfd65747a155e1307666a62c04b4266778f631c6a79c0167dfc19ce490ecc91f36c5d4c8d811de94
+  data.tar.gz: 950db541f0a4715430319f116eebd90a1fdca6dbf4cadb2d15d75e384b6fe24796dc3cd43c55eb26dae2fe3f680e968b8eaedf9ee70cb55f5d44267070dd6fc0

data/.github/workflows/test.yml

@@ -0,0 +1,22 @@
+name: Tests
+on: [push]
+jobs:
+  build:
+    strategy:
+      matrix:
+        ruby:
+          - 2.4
+          - 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/.rubocop.yml

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

data/CODE_OF_CONDUCT.md

@@ -55,7 +55,7 @@ further defined and clarified by project maintainers.
 ## Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting the project team at benedikt@benediktdeicke.com. All
+reported by contacting the project team at support@userlist.com. All
 complaints will be reviewed and investigated and will result in a response that
 is deemed necessary and appropriate to the circumstances. The project team is
 obligated to maintain confidentiality with regard to the reporter of an incident.

data/Gemfile

@@ -4,7 +4,7 @@ git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
 gemspec
 
-gem 'userlist', github: 'userlistio/userlist-ruby', branch: 'master'
+gem 'userlist', github: 'userlist/userlist-ruby', branch: 'master'
 
 gem 'guard-rspec', '~> 4.7'
 gem 'guard-rubocop', '~> 1.3'

data/README.md

@@ -1,6 +1,6 @@
-# Userlist::Rails [![Build Status](https://travis-ci.com/userlistio/userlist-rails.svg?branch=master)](https://travis-ci.com/userlistio/userlist-rails)
+# Userlist for Ruby on Rails [![Build Status](https://github.com/userlist/userlist-rails/workflows/Tests/badge.svg)](https://github.com/userlist/userlist-rails)
 
-This gem helps with integrating [Userlist.io](http://userlist.io) into Ruby on Rails applications.
+This gem helps with integrating [Userlist](http://userlist.com) into Ruby on Rails applications.
 
 ## Installation
 
@@ -20,14 +20,15 @@ Or install it yourself as:
 
 ## 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.io/settings/push) in your Userlist.io account.
+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 an initializer or as environment variables. The environment take precedence over configuration values from the initializer. Please refer to the [userlist-ruby](http://github.com/userlistio/userlist-ruby) gem for additional configuration options.
+Configuration values can either be set via an initializer or as environment variables. The environment take precedence over configuration values from the initializer. Please refer to the [userlist](http://github.com/userlist/userlist-ruby) gem for additional configuration options.
 
 Configuration via environment variables:
 
 ```shell
-USERLIST_PUSH_KEY=401e5c498be718c0a38b7da7f1ce5b409c56132a49246c435ee296e07bf2be39
+USERLIST_PUSH_KEY=VvB7pjDrv0V2hoaOCeZ5rIiUEPbEhSUN
+USERLIST_PUSH_ID=6vPkJl44cm82y4aLBIzaOhuEHJd0Bm7b
 ```
 
 Configuration via an initializer:
@@ -35,13 +36,24 @@ Configuration via an initializer:
 ```ruby
 # config/initializer/userlist.rb
 Userlist.configure do |config|
-  config.push_key = '401e5c498be718c0a38b7da7f1ce5b409c56132a49246c435ee296e07bf2be39'
+  config.push_key = 'VvB7pjDrv0V2hoaOCeZ5rIiUEPbEhSUN'
+  config.push_id = '6vPkJl44cm82y4aLBIzaOhuEHJd0Bm7b'
 end
 ```
 
+In addition to the configuration options of the [userlist](http://github.com/userlist/userlist-ruby#configuration) gem, the following options are available.
+
+| Name            | Default value                | Description                                                                                                          |
+| --------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `user_model`    | `nil`                        | The user model to use. Will be automatically set when `auto_discover` is `true`                                      |
+| `company_model` | `nil`                        | The company model to use. Will be automatically set when `auto_discover` is `true`                                   |
+| `relationship_model` | `nil`                        | The relationship model to use. Will be automatically infered from the user and company models                                   |
+| `auto_discover` | `true`                       | The gem will try to automatically identify your `User` and `Company` models. Possible values are `true` and `false`. |
+| `script_url`    | `https://js.userlist.com/v1` | The script url to load the Userlist in-app messages script from.                                                     |
+
 ### Disabling in development and test environments
 
-As sending test and development data into data into Userlist isn't very desireable, you can disable transmissions by setting the push strategy to `:null`.
+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
 # config/initializer/userlist.rb
@@ -50,9 +62,10 @@ Userlist.configure do |config|
 end
 ```
 
-
 ## Usage
 
+> ⚠️ **Important:** If you're using [Segment](https://segment.com) in combination with this gem, please make sure that both are using the same user identifier. By default, this gem will send `"user-#{id}"` (a combination of the user's primary key in the database and the `user-` prefix) as identifier. Either customize the `userlist_identifier` method on your User model, or ensure that you use the same identifier in your Segment integration.
+
 ### Tracking Users
 
 #### Sending user data automatically
@@ -79,40 +92,191 @@ end
 
 To manually send user data into Userlist, use the `Userlist::Push.users.push` method.
 
+```ruby
+Userlist::Push.users.push(user)
+```
+
+It's also possible to customize the payload sent to Userlist by passing a hash instead of the user object.
+
 ```ruby
 Userlist::Push.users.push(identifier: user.id, email: user.email, properties: { first_name: user.first_name, last_name: user.last_name })
 ```
 
+#### Ignoring users
+
+For cases where you don't want to send specific user to Userlist you can add a `userlist_push?` method. Whenever this method doesn't return a falsey value, this user will not be sent to Userlist. This also applies to any events or relationships this user is involved in.
+
+```ruby
+class User < ApplicationRecord
+  def userlist_push?
+    !deleted? && !guest?
+  end
+end
+```
+
+#### Deleting users
+
 It's also possible to delete a user from Userlist, using the `Userlist::Push.users.delete` method.
 
 ```ruby
-Userlist::Push.users.delete(user.id)
+Userlist::Push.users.delete(user)
 ```
 
-### Tracking Events
 
-To track custom events use the `Userlist::Push.events.push` method.
+### Tracking Companies
+
+#### Sending company data automatically
+
+By default, this gem will automatically detect your company model (like `Account`, `Company`, `Team`, `Organization`) and create, update, and delete the corresponding company inside of Userlist. To customize the `identifier`, `name`, or `properties` transmitted for a company, you can overwrite the according methods in your company model.
+
+```ruby
+class Account < ApplicationRecord
+  def userlist_properties
+    { projects: projects.count }
+  end
+
+  def userlist_identifier
+    "account-#{id}"
+  end
+
+  def userlist_name
+    name
+  end
+end
+```
+
+
+#### Sending company data manually
+
+To manually send company data into Userlist, use the `Userlist::Push.companies.push` method.
+
+```ruby
+Userlist::Push.companies.push(user)
+```
+
+It's also possible to customize the payload sent to Userlist by passing a hash instead of the company object.
+
+```ruby
+Userlist::Push.companies.push(identifier: company.id, name: company.name, properties: { projects: company.projects.count })
+```
+
+
+#### Ignoring companies
+
+For cases where you don't want to send specific company to Userlist you can add a `userlist_push?` method. Whenever this method doesn't return a falsey value, this company will not be sent to Userlist. This also applies to any events or relationships this company is involved in.
+
+```ruby
+class User < ApplicationRecord
+  def userlist_push?
+    !deleted? && !guest?
+  end
+end
+```
+
+#### Deleting users
+
+It's also possible to delete a company from Userlist, using the `Userlist::Push.companies.delete` method.
+
+```ruby
+Userlist::Push.companies.delete(company)
+```
+
+### Tracking relationships
+
+Userlist supports n:m relationships between users and companies. This gem will try to figure out the model your application uses to describe these relationships by looking at the associations defined in your user and company models. When sending a user to Userlist, this gem will try to automatically include the user's relationships as well. This includes information about the relationships and companies this user is associated with, but not information about other users associated with any of the companies. This works the other way around as well. When sending a company, it'll try to automatically include the company's relationships, but not any information about the associated users' other companies.
 
 ```ruby
-Userlist::Push.events.push(name: 'project_created', user: current_user, properties: { project_name: project.name })
+user = User.create(email: 'foo@example.com')
+user.companies.create(name: 'Example, Inc.')
+
+Userlist::Push.users.push(user)
+
+# Payload sent to Userlist
+{
+  identifier: 'user-1',
+  email: 'foo@example.com',
+  relationships: [
+    {
+      user: 'user-identifier',
+      company: {
+        identifier: 'company-identifier',
+        name: 'Example, Inc.',
+      }
+    }
+  ]
+}
 ```
 
-It is possible to make the `user` property optional by setting it for the entire request using an `around_action` callback in your `ApplicationController`.
+Similar to users and events, these relationships may define a `userlist_properties` method to provide addition properties that describe the relationship.
 
 ```ruby
-class ApplicationController < ActionController::Base
-  around_action :setup_userlist_current_user
+class Membership < ApplicationRecord
+  belongs_to :user
+  belongs_to :account
 
-  def setup_userlist_current_user(&block)
-    Userlist::Rails.with_current_user(current_user, &block)
+  def userlist_properties
+    { role: role }
   end
 end
 ```
 
-This simplifies the tracking call for the current request.
+
+#### Customizing relationship lookup
+
+It's possible to customize the way this gem looks up relationships for users and companies by specifying a `userlist_relationships` method on the user and/or company model.  
 
 ```ruby
-Userlist::Push.events.push(name: 'project_created', properties: { project_name: project.name })
+class User < ApplicationRecord
+  def userlist_relationships
+    memberships.where(role: 'owner')
+  end
+end
+```
+
+
+#### Ignoring relationships
+
+This gem automatically ignore relationship if either the user or the company is ignored. However, in some cases it might be desirable to ignore relationships even when they connect to valid objects. A typical example for this are pending invitations. To support this use case, you can provide a `userlist_push?` method. Whenever this method doesn't return a falsey value, this relationship will not be sent to Userlist.
+
+```ruby
+class Membership < ApplicationRecord
+  belongs_to :user
+  belongs_to :account
+
+  def userlist_push?
+    pending?
+  end
+end
+```
+
+#### Deleting relationships
+
+It's also possible to delete a relationship from Userlist, using the `Userlist::Push.relationship.delete` method.
+
+```ruby
+Userlist::Push.relationship.delete(membership)
+```
+
+### Tracking Events
+
+To track custom events use the `Userlist::Push.events.push` method. Events can be related to a user, a company, or both.
+
+```ruby
+Userlist::Push.events.push(name: 'project_created', user: current_user, company: current_account, properties: { project_name: project.name })
+```
+
+### Enabling in-app messages
+
+In order to use in-app messages, please set both the `push_key` and `push_id` configuration variables. Afterwards, include the `userlist_script_tag` helper into your application's layout for signed in users.
+
+```erb
+<%= userlist_script_tag %>
+```
+
+By default, the helper will try to use the `current_user` helper to read the currently signed in user. You can change the default bebahvior by passing a different user. The passed object must respond to the `userlist_identifier` method.
+
+```erb
+<%= userlist_script_tag(user) %>
 ```
 
 ### Batch importing
@@ -131,7 +295,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/userlistio/userlist-rails. 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-rails>. 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
 
@@ -139,4 +303,12 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Userlist::Rails project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/userlistio/userlist-rails/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the Userlist::Rails project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/userlist/userlist-rails/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/rails.rb

@@ -1,11 +1,16 @@
 require 'userlist/rails/config'
 require 'userlist/rails/railtie'
 
-require 'userlist/rails/extensions/resource'
-require 'userlist/rails/extensions/event'
-
 module Userlist
   module Rails
+    DEPRECATED_MODEL_METHODS = [
+      :userlist_push,
+      :userlist_delete,
+      :userlist_payload,
+      :userlist_company,
+      :userlist_user
+    ].freeze
+
     def self.with_current_user(user)
       Thread.current[:userlist_current_user] = user
       yield
@@ -17,10 +22,23 @@ module Userlist
       Thread.current[:userlist_current_user]
     end
 
+    def self.with_current_company(company)
+      Thread.current[:userlist_current_company] = company
+      yield
+    ensure
+      Thread.current[:userlist_current_company] = nil
+    end
+
+    def self.current_company
+      Thread.current[:userlist_current_company]
+    end
+
     def self.detect_model(*names)
       names.each do |name|
         begin
-          return name.constantize
+          model = name.constantize
+
+          return model if model.is_a?(Class)
         rescue NameError
           false
         end
@@ -28,5 +46,81 @@ module Userlist
 
       nil
     end
+
+    def self.detect_relationship(from, to)
+      return unless reflection = find_reflection(from, to)
+
+      reflection.through_reflection.klass if reflection.through_reflection?
+    end
+
+    def self.find_reflection(from, to)
+      return unless from && to
+
+      from.reflect_on_all_associations.find { |r| r.class_name == to.to_s }
+    end
+
+    def self.setup_callbacks(model, scope)
+      return if model.instance_variable_get(:@userlist_callbacks_registered)
+
+      setup_callback(:create,  model, scope, :push)
+      setup_callback(:update,  model, scope, :push)
+      setup_callback(:destroy, model, scope, :delete)
+
+      model.instance_variable_set(:@userlist_callbacks_registered, true)
+    end
+
+    def self.setup_callback(type, model, scope, method)
+      return unless callback_method = [:after_commit, :"after_#{type}"].find { |m| model.respond_to?(m) }
+
+      callback = lambda do
+        begin
+          relation = Userlist::Push.public_send(scope)
+          relation.public_send(method, self)
+        rescue Userlist::Error => e
+          Userlist.logger.error "Failed to #{method} #{method.to_s.singularize}: #{e.message}"
+        end
+      end
+
+      model.public_send(callback_method, callback, on: type)
+    end
+
+    def self.setup_extensions
+      Userlist::Push::User.include(Userlist::Rails::Extensions::User)
+      Userlist::Push::Company.include(Userlist::Rails::Extensions::Company)
+      Userlist::Push::Relationship.include(Userlist::Rails::Extensions::Relationship)
+      Userlist::Push::Event.include(Userlist::Rails::Extensions::Event)
+    end
+
+    def self.check_deprecations(type)
+      deprecated_methods = (type.instance_methods + type.private_instance_methods) & DEPRECATED_MODEL_METHODS
+
+      if deprecated_methods.any?
+        raise <<~MESSAGE
+          Deprecation warning for userlist-rails
+
+          Customizing the way userlist-rails works has changed.
+
+          Using the #{deprecated_methods.to_sentence} method(s) on your #{type.name} model is not supported anymore.
+
+          For details on how to customize the gem's behavior, please see https://github.com/userlist/userlist-rails or reach out to support@userlist.com
+        MESSAGE
+      end
+
+      deprecated_methods = type.private_instance_methods.grep(/userlist_/)
+
+      if deprecated_methods.any?
+        raise <<~MESSAGE
+          Deprecation warning for userlist-rails
+
+          Customizing the way userlist-rails works has changed.
+
+          Using private methods (like #{deprecated_methods.to_sentence}) on your #{type.name} model is not supported anymore. Please use public methods instead.
+
+          For details on how to customize the gem's behavior, please see https://github.com/userlist/userlist-rails or reach out to support@userlist.com
+        MESSAGE
+      end
+
+      true
+    end
   end
 end