lucid_intercom 0.4.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e093b7cbc34689c682b5f4f1d3fd4fdef7ac033c9cf0fba38b0404e54f50c9a8
-  data.tar.gz: e08a13e91779a38d92d076bcfad7a7e6003ad5b3ea4de3086cfc0ca9432d162e
+  metadata.gz: 1a133b6b1ae95502c5f15501cd40ea84d155d7f703cccc56befe4a32500533d6
+  data.tar.gz: 4e0b268ce267c890be6bbf61fc52f8bfbca449d37a45ee68a1db8db25f5be494
 SHA512:
-  metadata.gz: b02dbad3e5c7284f146b53f02e2bac8ed500edb95662ed5cfc1a709330b80db817c035973a451f2d9af7a58f3d62d2dcb33df4f1b1b04a188d71fb186ce90703
-  data.tar.gz: e2de118f2b5767081d4f8bea3d75ec8e359644799f94e1542c69917d248d12635a3af5d0348ac1f98674242c90f992d33437ee7316ac07d3657e80d83d2e0c33
+  metadata.gz: 6b089504958e012d93ca00a847ced2243ee5c22fbe93e2395250898be6063726f5ba87d3b2a2fae48383a3214996e73fb4ccbbb9cd958d56a50cfaec1f898762
+  data.tar.gz: 470849470d05d34ed775f382af97866684559fd9e0c0fdb95fdad207729f74dc0f6169cf6a6c2916fe2341c61c13d1ec39e7918787866a1aec2916f476bf6e64

data/README.md

@@ -14,7 +14,7 @@ Usage
 
 ### Configure the default API credentials
 
-    LucidIntercom.credentials = LucidIntercom::Credentials.new(
+    LucidIntercom.config = LucidIntercom::Config.new(
       '...', # access_token
       '...', # secret
       '...', # app_id
@@ -23,13 +23,10 @@ Usage
 
 Here, ‘app_prefix’ is the snakecased app name, e.g. ‘smart_order_tags’
 
-Alternatively, a credentials object may optionally be passed as a
-keyword argument to any of the classes listed below.
-
 
 ### Render the browser snippet
 
-    LucidIntercom::RenderSnippet.new(shop_attributes, app_attributes).()
+    LucidIntercom::RenderSnippet.new.(shopify_data, app_data)
 
 This returns an HTML string which you can use in your view layout.
 
@@ -40,12 +37,14 @@ See the source code for documentation of arguments.
 
 When a user installs/uninstalls the app, or changes their plan:
 
-    LucidIntercom::Events::Installed.new(shop_attributes).(plan_name)
-    LucidIntercom::Events::Uninstalled.new(shop_attributes).()
-    LucidIntercom::Events::ChangedPlan.new(shop_attributes).(plan_name)
+    event = LucidIntercom::InstalledEvent.new(shopify_data, new_plan)
+    event = LucidIntercom::UninstalledEvent.new(shopify_data)
+    event = LucidIntercom::ChangedPlanEvent.new(shopify_data, new_plan)
+
+    LucidIntercom::SendEvent.new.(event)
 
-Note that the `shop_attributes` hash for uninstalled events cannot
-be read from the API (as the access token is invalid at this stage).
+Note that the `shopify_data` hash for uninstalled events cannot be
+read from the API (as the access token is invalid at this stage).
 You should use the data hash provided with Shopify’s ‘app/uninstalled’
 webhook instead.
 
@@ -61,16 +60,7 @@ For free apps, use ‘free’.
 For partner-friendly app installs, use ‘partner’.
 
 
-### Send a custom event
-
-    LucidIntercom::SendEvent.new(shop_attributes).(event_name, event_metadata)
-
-See the source code for documentation of arguments.
-
-
-### Update a user
-
-    LucidIntercom::UpdateUser.new(shop_attributes, app_attributes).()
+### Custom events
 
-When this is called, and the user did not previously exist, the
-user will be created.
+To define a custom event, subclass `LucidIntercom::Event`. See the
+source code for documentation.

data/lib/lucid_intercom/attributes.rb

@@ -1,57 +1,25 @@
 # frozen_string_literal: true
 
-require 'lucid_intercom/attributes/user'
-require 'lucid_intercom/attributes/company'
-require 'lucid_intercom/attributes/custom'
+require 'dry-initializer'
+
+require 'lucid_intercom/convert'
 
 module LucidIntercom
   class Attributes
-    #
-    # @see LucidIntercom::Attributes::Base#initialize
-    #
-    def initialize(*args)
-      @args = args
-    end
+    extend Dry::Initializer
 
-    #
-    # @return [Hash]
-    #
-    def user
-      user_browser.reject { |k, _| k == :user_hash }
-    end
+    # @return [Hash] shop attributes as returned by the Shopify API
+    param :shopify_data, reader: :private
 
     #
-    # User attributes for browser (with 'user_hash').
-    #
-    # @return [Hash]
+    # @abstract
     #
-    def user_browser
-      User.new(*@args).()
-    end
-
-    #
-    # @return [Hash]
-    #
-    def company
-      Company.new(*@args).()
-    end
-
-    #
-    # Company attributes for browser (expects 'id', not 'company_id').
-    #
-    # @return [Hash]
-    #
-    def company_browser
-      company2 = company
-      company2[:id] = company2.delete(:company_id)
-      company2
-    end
-
+    # @param convert [#call]
     #
     # @return [Hash]
     #
-    def custom
-      Custom.new(*@args).()
+    def to_h(convert: Convert.new)
+      convert.({})
     end
   end
 end

data/lib/lucid_intercom/changed_plan_event.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'lucid_intercom/event'
+
+module LucidIntercom
+  class ChangedPlanEvent < Event
+    # @return [String, nil] e.g. 'free', or nil to unset
+    param :new_plan
+
+    event :changed_plan
+
+    #
+    # @return [Hash]
+    #
+    def event_metadata
+      {
+        company_id: company.to_h[:company_id],
+        new_plan: new_plan,
+      }
+    end
+
+    #
+    # @return [Hash]
+    #
+    def app_data
+      {
+        plan: new_plan,
+      }
+    end
+  end
+end

data/lib/lucid_intercom/company_attributes.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'lucid_intercom/attributes'
+
+module LucidIntercom
+  class CompanyAttributes < Attributes
+    #
+    # @param browser [Boolean] format for browser snippet
+    # @param convert [#call]
+    #
+    # @return [Hash]
+    #
+    def to_h(browser: false, convert: Convert.new)
+      convert.({}.tap do |h|
+        h[browser ? :id : :company_id] = shopify_data['myshopify_domain']
+        h[:name] = shopify_data['name']
+        h[:plan] = shopify_data['plan_name']
+      end)
+    end
+  end
+end

data/lib/lucid_intercom/company_custom_attributes.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'lucid_intercom/attributes'
+require 'lucid_intercom/config'
+
+module LucidIntercom
+  class CompanyCustomAttributes < Attributes
+    # @return [Hash] app attributes (unprefixed)
+    param :app_data, reader: :private
+
+    #
+    # @param convert [#call]
+    #
+    # @return [Hash]
+    #
+    def to_h(convert: Convert.new)
+      convert.(shopify.merge(app))
+    end
+
+    #
+    # These attributes are prefixed with 'merchant_' to distinguish them from
+    # the Shopify intergration's 'shopify_' prefix.
+    #
+    # @return [Hash]
+    #
+    private def shopify
+      {
+        merchant_domain: shopify_data['domain'],
+        merchant_myshopify_domain: shopify_data['myshopify_domain'],
+        merchant_shop_owner: shopify_data['shop_owner'],
+        merchant_timezone: shopify_data['timezone'],
+      }
+    end
+
+    #
+    # Any app-specific attributes.
+    #
+    # @return [Hash]
+    #
+    private def app
+      prefix = LucidIntercom.app_prefix
+
+      app_data.each_with_object({}) do |(k, v), h|
+        h["#{prefix}_#{k}"] = v
+      end
+    end
+  end
+end

data/lib/lucid_intercom/config.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'dry-initializer'
+require 'forwardable'
+
+require 'lucid_intercom/error'
+
+module LucidIntercom
+  NotConfiguredError = Class.new(Error)
+
+  class << self
+    extend Forwardable
+
+    # TODO: *Config.dry_initializer.attributes (version 2.0.0+)
+    def_delegators :config, :access_token, :secret, :app_id, :app_prefix
+
+    # @param config [Config]
+    attr_writer :config
+
+    #
+    # @return [Config]
+    #
+    # @raise [NotConfiguredError] if config is unset
+    #
+    def config
+      raise LucidIntercom::NotConfiguredError unless @config
+
+      @config
+    end
+  end
+
+  class Config
+    extend Dry::Initializer
+
+    # @return [String]
+    param :access_token
+    # @return [String]
+    param :secret
+    # @return [String]
+    param :app_id
+    # @return [String] the snakecased app name, e.g. 'smart_order_tags'
+    param :app_prefix
+  end
+end

data/lib/lucid_intercom/convert.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module LucidIntercom
+  class Convert
+    #
+    # @param attributes [Hash]
+    #
+    # @return [Hash]
+    #
+    def call(attributes)
+      attributes.each_with_object({}) do |(k, obj), h|
+        h[k] = convert(obj)
+      end
+    end
+
+    #
+    # @param obj [Object]
+    #
+    # @return [Object] a valid Intercom type
+    #
+    private def convert(obj)
+      case obj
+      when Numeric, nil # nil to unset
+        obj
+      when Time
+        obj.to_i
+      else
+        obj.to_s
+      end
+    end
+  end
+end

data/lib/lucid_intercom/event.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'lucid_intercom/company_attributes'
+require 'lucid_intercom/company_custom_attributes'
+require 'lucid_intercom/config'
+require 'lucid_intercom/user_attributes'
+
+module LucidIntercom
+  class Event
+    extend Dry::Initializer
+
+    # @return [Hash] shop attributes as returned by the Shopify API
+    param :shopify_data
+    # @return [CompanyAttributes]
+    option :company, default: proc { CompanyAttributes.new(shopify_data) }
+    # @return [CompanyCustomAttributes]
+    option :company_custom, default: proc { CompanyCustomAttributes.new(shopify_data, app_data) }
+    # @return [UserAttributes]
+    option :user, default: proc { UserAttributes.new(shopify_data) }
+
+    #
+    # Set the event name for the subclass.
+    #
+    # @param event_name [String, #to_s]
+    #
+    # @example
+    #   event :changed_plan
+    #
+    def self.event(event_name)
+      define_method(:event_name) do
+        "#{LucidIntercom.app_prefix}_#{event_name}"
+      end
+    end
+
+    #
+    # @abstract
+    #
+    # @return [String]
+    #
+    def event_name
+      raise NotImplementedError
+    end
+
+    #
+    # @abstract
+    #
+    # @return [Hash]
+    #
+    def event_metadata
+      raise NotImplementedError
+    end
+
+    #
+    # Additional custom attributes related to the event (unprefixed).
+    #
+    # @example
+    #   {plan: 'free'}
+    #
+    # @example
+    #   {plan: nil}
+    #
+    # @return [Hash]
+    #
+    def app_data
+      {}
+    end
+
+    #
+    # @return [Hash]
+    #
+    def user_id
+      {
+        user.id_key => user.id,
+      }
+    end
+  end
+end

data/lib/lucid_intercom/installed_event.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'lucid_intercom/event'
+
+module LucidIntercom
+  class InstalledEvent < Event
+    # @return [String] e.g. 'free'
+    param :new_plan
+
+    event :installed
+
+    #
+    # @return [Hash]
+    #
+    def event_metadata
+      {
+        company_id: company.to_h[:company_id],
+        new_plan: new_plan,
+      }
+    end
+
+    #
+    # @return [Hash]
+    #
+    def app_data
+      {
+        plan: new_plan,
+      }
+    end
+  end
+end

data/lib/lucid_intercom/post_request.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'http'
+
+require 'lucid_intercom/config'
+require 'lucid_intercom/response'
+
+module LucidIntercom
+  class PostRequest
+    #
+    # @param path [String] path relative to the domain
+    # @param data [Hash]
+    #
+    # @return [Response]
+    #
+    def call(path, data)
+      res = HTTP.headers(
+        'Authorization' => "Bearer #{LucidIntercom.access_token}",
+        'Accept' => 'application/json',
+        'Content-Type' => 'application/json'
+      ).post("https://api.intercom.io/#{path}", json: data)
+
+      Response.new(res.code)
+    end
+  end
+end

data/lib/lucid_intercom/render_snippet.rb

@@ -1,46 +1,50 @@
 # frozen_string_literal: true
 
 require 'erb'
-require 'lucid_intercom/attributes'
-require 'lucid_intercom/credentials'
+
+require 'lucid_intercom/config'
 
 module LucidIntercom
   class RenderSnippet
     TEMPLATE = ERB.new(File.read("#{__dir__}/snippet.html.erb")).freeze
 
     #
-    # Leave arguments unset for unauthenticated visitors.
-    #
-    # @param credentials [LucidIntercom::Credentials]
+    # @param shopify_data [Hash] shop attributes as returned by the Shopify API
+    # @param app_data [Hash] app attributes (unprefixed)
     #
-    # @see LucidIntercom::Attributes#initialize
+    # @example Unauthenticated visitor
+    #   render_snippet.()
     #
-    def initialize(shop_attributes = {}, app_attributes = {}, credentials = LucidIntercom.credentials)
-      @credentials = credentials
-      @attributes = Attributes.new(shop_attributes, app_attributes, credentials) if shop_attributes.empty?
-    end
-
-    # @return [LucidIntercom::Attributes]
-    attr_reader :attributes
-    # @return [LucidIntercom::Credentials]
-    attr_reader :credentials
-
+    # @example
+    #   render_snippet.(shopify_data, app_data)
     #
-    # @return [String] the rendered HTML
+    # @return [String]
     #
-    def call
+    def call(shopify_data = {}, app_data = {})
+      company = CompanyAttributes.new(shopify_data).to_h(browser: true)
+      company_custom = CompanyCustomAttributes.new(shopify_data, app_data).to_h
+      user = UserAttributes.new(shopify_data).to_h(browser: true)
+
       TEMPLATE.result(binding)
     end
 
     #
-    # Quote and escape a value for the window.intercomSettings object.
+    # Quote and escape a value for JavaScript.
     #
-    private def h(v)
-      v.is_a?(String) ? ?" + v.gsub(/./) { |c| escape_char(c) } + ?" : v
-    end
+    # @param obj [Object]
+    #
+    # @return [Object]
+    #
+    def escape(obj)
+      return obj unless obj.is_a?(String)
+
+      s = obj.gsub(/./) do |c|
+        return c unless %w(" ' / < > \\).include?(c)
+
+        "\\#{c}"
+      end
 
-    private def escape_char(c)
-      %w(" ' / < > \\).include?(c) ? '\%s' % c : c
+      "\"#{s}\""
     end
   end
 end

data/lib/lucid_intercom/response.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'dry-initializer'
+
+require 'lucid_intercom/error'
+
+module LucidIntercom
+  class Response
+    #
+    # @abstract
+    #
+    class Error < LucidIntercom::Error
+      extend Dry::Initializer
+
+      # @return [Integer]
+      param :status_code
+
+      #
+      # @return [String]
+      #
+      def message
+        "bad response (#{status_code})"
+      end
+    end
+
+    ClientError = Class.new(Error)
+    ServerError = Class.new(Error)
+
+    extend Dry::Initializer
+
+    # @return [Integer]
+    param :status_code
+
+    #
+    # @return [Boolean]
+    #
+    # @raise [ClientError] for status 4xx
+    # @raise [ServerError] for status 5xx
+    #
+    def assert!
+      case status_code
+      when 400..499
+        raise ClientError.new(status_code)
+      when 500..599
+        raise ServerError.new(status_code)
+      end
+
+      true
+    end
+  end
+end

data/lib/lucid_intercom/send_event.rb

@@ -1,80 +1,42 @@
 # frozen_string_literal: true
 
-require 'json'
-require 'net/http'
-require 'uri'
-require 'lucid_intercom/attributes'
-require 'lucid_intercom/credentials'
-require 'lucid_intercom/errors'
+require 'dry-initializer'
+
+require 'lucid_intercom/post_request'
 
 module LucidIntercom
   class SendEvent
-    #
-    # @param shop_attributes [Hash] shop attributes in format returned by the Shopify API
-    # @param credentials [LucidIntercom::Credentials]
-    #
-    def initialize(shop_attributes, credentials = LucidIntercom.credentials)
-      @attributes = Attributes.new(shop_attributes, {}, credentials)
-      @credentials = credentials
-    end
-
-    # @return [LucidIntercom::Attributes]
-    attr_reader :attributes
-    # @return [LucidIntercom::Credentials]
-    attr_reader :credentials
-
-    #
-    # Send event for user identified by attributes.
-    #
-    # @param event_name [String]
-    # @param event_metadata [Hash]
-    #
-    # @raise [LucidIntercom::RequestError] if the response status >= 400
-    #
-    def call(event_name, event_metadata)
-      res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
-        http.request(req, data(event_name, event_metadata))
-      end
+    extend Dry::Initializer
 
-      status = res.code.to_i
-
-      if status >= 400 # rubocop:disable Style/GuardClause
-        raise LucidIntercom::RequestError.new(status), 'invalid response code %s' % status
-      end
-    end
+    # @return [PostRequest]
+    option :post_request, default: proc { PostRequest.new }
+    # @return [UpdateUser]
+    option :update_user, default: proc { UpdateUser.new }
 
     #
-    # @return [URI::HTTPS]
+    # @param event [Events::Event]
     #
-    private def uri
-      URI('https://api.intercom.io/events')
-    end
-
+    # @raise [Response::ClientError] for status 4xx
+    # @raise [Response::ServerError] for status 5xx
     #
-    # @return [Net::HTTP::Post]
-    #
-    private def req
-      req = Net::HTTP::Post.new(uri)
-      req['Authorization'] = "Bearer #{credentials.access_token}"
-      req['Content-Type'] = 'application/json'
+    def call(event)
+      post_request.('events', data(event)).assert!
 
-      req
+      update_user.(event)
     end
 
     #
-    # @param event_name [String]
-    # @param event_metadata [Hash]
+    # @param event [Events::Event]
     #
     # @return [Hash]
     #
-    private def data(event_name, event_metadata)
-      event = {}
-      event[:email] = attributes.user[:email]
-      event[:event_name] = event_name
-      event[:created_at] = Time.now.utc.to_i
-      event[:metadata] = event_metadata
-
-      event.to_json
+    private def data(event)
+      {
+        **event.user_id,
+        event_name: event.event_name,
+        created_at: Time.now.utc.to_i,
+        metadata: event.event_metadata,
+      }
     end
   end
 end