userlist-rails 0.5.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9fe4b336d98e1d3015aa44aa9a261c37bf160747573d6507f44f533a14e6e4dd
-  data.tar.gz: 77261e5a6972ce2b0f0d0ea43e141c3d4c33011790c01a8fd32749743c35b342
+  metadata.gz: ca257f164074da93de47984ddd695b818510ab5e671a1e4545eb986663d34335
+  data.tar.gz: 6fb32d37480a4af75a79f82c8ee76e180d0a29eed7b6a86fa09ea12e749544c2
 SHA512:
-  metadata.gz: a3843cb90d6f4868179c43972e3b0877f8d1cd2e02637b03799f9778571d1115c44ee6c7dc320407d50e0cea7305d1b019d6bb63526b42f8dd109d180b015834
-  data.tar.gz: 5147105865f3bfccc0750823f69889e76c34d7cd2f18b149fc6cd4ffc8bb7e80a3103cccd88dc14a2f3520bf9747b1cfbceaee1cf313ae37ecec3cf2a5fcc406
+  metadata.gz: '049815dabf0844173db83e9186e19e1736db9f0c14a9754f14203bcca1129b8be5411127e48212830b7951f6ff4d35cb9e36647c7af7214b607d47932400b96c'
+  data.tar.gz: ab1a3d8c38682a1de52ed54cae85c210a13b037e4fef8e83dc8c1cbc6381fcdad6727813e294e82411ae060169397963f282739722df38007a9e186d4127e4f7

data/Gemfile

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

data/README.md

@@ -47,6 +47,7 @@ In addition to the configuration options of the [userlist](http://github.com/use
 | --------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------- |
 | `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.                                                     |
 
@@ -101,36 +102,181 @@ It's also possible to customize the payload sent to Userlist by passing a hash i
 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)
 ```
 
-### 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.events.push(name: 'project_created', user: current_user, properties: { project_name: project.name })
+Userlist::Push.companies.push(company)
 ```
 
-It is possible to make the `user` property optional by setting it for the entire request using an `around_action` callback in your `ApplicationController`.
+It's also possible to customize the payload sent to Userlist by passing a hash instead of the company object.
 
 ```ruby
-class ApplicationController < ActionController::Base
-  around_action :setup_userlist_current_user
+Userlist::Push.companies.push(identifier: company.id, name: company.name, properties: { projects: company.projects.count })
+```
 
-  def setup_userlist_current_user(&block)
-    Userlist::Rails.with_current_user(current_user, &block)
+
+#### 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 Account < ApplicationRecord
+  def userlist_push?
+    !deleted? && active_subscription?
   end
 end
 ```
 
-This simplifies the tracking call for the current request.
+#### Deleting companies
+
+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
+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.',
+      }
+    }
+  ]
+}
+```
+
+Similar to users and events, these relationships may define a `userlist_properties` method to provide addition properties that describe the relationship.
+
+```ruby
+class Membership < ApplicationRecord
+  belongs_to :user
+  belongs_to :account
+
+  def userlist_properties
+    { role: role }
+  end
+end
+```
+
+
+#### 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
+class User < ApplicationRecord
+  def userlist_relationships
+    memberships.where(role: 'owner')
+  end
+end
+```
+
+If you don't have a dedicated model describing the relationship, you can return a hash including both the user and the company model.
+
+```ruby
+class User < ApplicationRecord
+  def userlist_relationships
+    [
+      {
+        user: self,
+        company: account
+      }
+    ]
+  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', properties: { project_name: project.name })
+Userlist::Push.events.push(name: 'project_created', user: current_user, company: current_account, properties: { project_name: project.name })
 ```
 
 ### Enabling in-app messages

data/lib/userlist/rails.rb

@@ -3,6 +3,14 @@ require 'userlist/rails/railtie'
 
 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
@@ -28,7 +36,9 @@ module Userlist
     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
@@ -49,6 +59,12 @@ module Userlist
       from.reflect_on_all_associations.find { |r| r.class_name == to.to_s }
     end
 
+    def self.find_association_between(from, to)
+      return unless association = Userlist::Rails.find_reflection(from, to)
+
+      association.through_reflection || association
+    end
+
     def self.setup_callbacks(model, scope)
       return if model.instance_variable_get(:@userlist_callbacks_registered)
 
@@ -80,5 +96,37 @@ module Userlist
       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

data/lib/userlist/rails/config.rb

@@ -34,6 +34,10 @@ module Userlist
         (model = super) && model.is_a?(Class) ? model : model&.to_s&.constantize
       end
 
+      def relationship_model
+        (model = super) && model.is_a?(Class) ? model : model&.to_s&.constantize
+      end
+
       Userlist::Config.send(:prepend, self)
     end
   end

data/lib/userlist/rails/railtie.rb

@@ -53,17 +53,19 @@ module Userlist
             Userlist.logger.info('Automatically discovering models')
 
             userlist.user_model = Userlist::Rails.detect_model('User')
-            userlist.company_model = Userlist::Rails.detect_model('Account', 'Company')
+            userlist.company_model = Userlist::Rails.detect_model('Account', 'Company', 'Team', 'Organization')
             userlist.relationship_model = Userlist::Rails.detect_relationship(userlist.user_model, userlist.company_model)
           end
 
           if user_model = userlist.user_model
             Userlist.logger.info("Preparing user model #{user_model}")
+            Userlist::Rails.check_deprecations(user_model)
             Userlist::Rails.setup_callbacks(user_model, :users)
           end
 
           if company_model = userlist.company_model
             Userlist.logger.info("Preparing company model #{company_model}")
+            Userlist::Rails.check_deprecations(company_model)
             Userlist::Rails.setup_callbacks(company_model, :companies)
           end
 

data/lib/userlist/rails/transform.rb

@@ -11,7 +11,7 @@ module Userlist
       end
 
       def [](name)
-        public_send(name) if key?(name)
+        model.try("userlist_#{name}") || public_send("default_#{name}") if key?(name)
       end
 
       def key?(name)
@@ -27,11 +27,11 @@ module Userlist
       end
 
       def push?
-        (!model.respond_to?(:push?) || model.push?)
+        (!model.respond_to?(:userlist_push?) || model.userlist_push?)
       end
 
       def delete?
-        (!model.respond_to?(:delete?) || model.delete?)
+        (!model.respond_to?(:userlist_delete?) || model.userlist_delete?)
       end
 
     private

data/lib/userlist/rails/transforms/company.rb

@@ -1,9 +1,12 @@
 require 'userlist/rails/transform'
+require 'userlist/rails/transforms/has_relationships'
 
 module Userlist
   module Rails
     module Transforms
       class Company < Userlist::Rails::Transform
+        include HasRelationships
+
         def self.attributes
           @attributes ||= [
             :identifier,
@@ -14,26 +17,37 @@ module Userlist
           ]
         end
 
-        def identifier
-          model.try(:userlist_identifier) || "#{model.class.name}-#{model.id}".parameterize
+        def default_identifier
+          "#{model.class.name}-#{model.id}".parameterize
         end
 
-        def properties
-          model.try(:userlist_properties) || {}
+        def default_properties
+          {}
         end
 
-        def relationships
-          relationships_method = Userlist::Rails.find_reflection(config.company_model, config.relationship_model)&.name
+        def default_name
+          model.try(:name)
+        end
 
-          model.try(:userlist_relationships) || (relationships_method && model.try(relationships_method))
+        def default_signed_up_at
+          model.try(:created_at)
         end
 
-        def name
-          model.try(:userlist_name) || model.try(:name)
+      private
+
+        def build_relationship(record)
+          {
+            user: record,
+            company: model
+          }
         end
 
-        def signed_up_at
-          model.try(:created_at)
+        def relationship_from
+          config.company_model
+        end
+
+        def relationship_to
+          config.user_model
         end
       end
     end

data/lib/userlist/rails/transforms/has_relationships.rb

@@ -0,0 +1,35 @@
+require 'userlist/rails/transform'
+
+module Userlist
+  module Rails
+    module Transforms
+      module HasRelationships
+        def default_relationships
+          return unless association = Userlist::Rails.find_association_between(relationship_from, relationship_to)
+
+          records = model.try(association.name)
+
+          if association.klass == config.relationship_model
+            records
+          elsif association.klass == relationship_to
+            Array.wrap(records).map { |record| build_relationship(record) }
+          end
+        end
+
+      private
+
+        def build_relationship(_record)
+          raise NotImplementedError
+        end
+
+        def relationship_to
+          raise NotImplementedError
+        end
+
+        def relationship_from
+          raise NotImplementedError
+        end
+      end
+    end
+  end
+end

data/lib/userlist/rails/transforms/relationship.rb

@@ -12,20 +12,20 @@ module Userlist
           ]
         end
 
-        def properties
-          model.try(:userlist_properties) || {}
+        def default_properties
+          {}
         end
 
-        def user
+        def default_user
           user_method = Userlist::Rails.find_reflection(config.relationship_model, config.user_model)&.name
 
-          model.try(:userlist_user) || (user_method && model.try(user_method))
+          user_method && model.try(user_method)
         end
 
-        def company
+        def default_company
           company_method = Userlist::Rails.find_reflection(config.relationship_model, config.company_model)&.name
 
-          model.try(:userlist_company) || (company_method && model.try(company_method))
+          company_method && model.try(company_method)
         end
       end
     end

data/lib/userlist/rails/transforms/user.rb

@@ -1,9 +1,12 @@
 require 'userlist/rails/transform'
+require 'userlist/rails/transforms/has_relationships'
 
 module Userlist
   module Rails
     module Transforms
       class User < Userlist::Rails::Transform
+        include HasRelationships
+
         def self.attributes
           @attributes ||= [
             :identifier,
@@ -14,26 +17,37 @@ module Userlist
           ]
         end
 
-        def identifier
-          model.try(:userlist_identifier) || "#{model.class.name}-#{model.id}".parameterize
+        def default_identifier
+          "#{model.class.name}-#{model.id}".parameterize
         end
 
-        def properties
-          model.try(:userlist_properties) || {}
+        def default_properties
+          {}
         end
 
-        def relationships
-          relationships_method = Userlist::Rails.find_reflection(config.user_model, config.relationship_model)&.name
+        def default_email
+          model.try(:email)
+        end
 
-          model.try(:userlist_relationships) || (relationships_method && model.try(relationships_method))
+        def default_signed_up_at
+          model.try(:created_at)
         end
 
-        def email
-          model.try(:userlist_email) || model.try(:email)
+      private
+
+        def build_relationship(record)
+          {
+            user: model,
+            company: record
+          }
         end
 
-        def signed_up_at
-          model.try(:created_at)
+        def relationship_from
+          config.user_model
+        end
+
+        def relationship_to
+          config.company_model
         end
       end
     end

data/lib/userlist/rails/version.rb

@@ -1,5 +1,5 @@
 module Userlist
   module Rails
-    VERSION = '0.5.0'.freeze
+    VERSION = '0.6.1'.freeze
   end
 end

data/userlist-rails.gemspec

@@ -23,7 +23,7 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency 'activesupport', '>= 5.0'
   spec.add_dependency 'railties', '>= 5.0'
-  spec.add_dependency 'userlist', '~> 0.5'
+  spec.add_dependency 'userlist', '~> 0.6'
 
   spec.add_development_dependency 'actionpack', '>= 5.0'
   spec.add_development_dependency 'activerecord', '>= 5.0'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: userlist-rails
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Benedikt Deicke
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-01-22 00:00:00.000000000 Z
+date: 2021-05-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -44,14 +44,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.5'
+        version: '0.6'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.5'
+        version: '0.6'
 - !ruby/object:Gem::Dependency
   name: actionpack
   requirement: !ruby/object:Gem::Requirement
@@ -189,6 +189,7 @@ files:
 - lib/userlist/rails/tasks/userlist.rake
 - lib/userlist/rails/transform.rb
 - lib/userlist/rails/transforms/company.rb
+- lib/userlist/rails/transforms/has_relationships.rb
 - lib/userlist/rails/transforms/relationship.rb
 - lib/userlist/rails/transforms/user.rb
 - lib/userlist/rails/version.rb