bento-sdk 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c620722fa7d6cb6cfa291f2a8aeda31dbc237a6096387dd43534868d934d3396
+  data.tar.gz: 6426e53c3fdb01e6c38bfe48602f1bc8e95a66280335775932bce4c0e0792c95
+SHA512:
+  metadata.gz: 50c445e4580135141dcf05baf11bb68a354c90b85352d221abfeeac83f0d4acc16beadfdf22561221bb3302b8ee422723a04afbd53e41684a11647190aa3e9e1
+  data.tar.gz: a5564c55a86070b04120d4e8125c6a3b8df694ad860584bdb5f5b48eecf2848b5889178e0fcff4c98ea3af6ff38eaa5322459246e0265ec61921162c3902eb2f

data/lib/bento/analytics.rb

@@ -0,0 +1,47 @@
+require "bento/sdk/version"
+require "bento/sdk/defaults"
+require "bento/sdk/utils"
+require "bento/sdk/field_parser"
+require "bento/sdk/client"
+require "bento/sdk/worker"
+require "bento/sdk/transport"
+require "bento/sdk/response"
+require "bento/sdk/logging"
+
+module Bento
+  class << self
+    attr_writer :write_key
+  end
+
+  def self.configure(&block)
+    yield self
+  end
+
+  class Analytics
+    # Initializes a new instance of {Bento::Analytics::Client}, to which all
+    # method calls are proxied.
+    #
+    # @param options includes options that are passed down to
+    #   {Bento::Analytics::Client#initialize}
+    # @option options [Boolean] :stub (false) If true, requests don't hit the
+    #   server and are stubbed to be successful.
+    def initialize(options = {})
+      Transport.stub = options[:stub] if options.key?(:stub)
+      @client = Bento::Analytics::Client.new options
+    end
+
+    def method_missing(message, *args, &block)
+      if @client.respond_to? message
+        @client.send message, *args, &block
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      @client.respond_to?(method_name) || super
+    end
+
+    include Logging
+  end
+end

data/lib/bento/core/client.rb

@@ -0,0 +1,47 @@
+module Bento
+  # Client class for interacting with the Bento API.
+  # This class provides methods for making HTTP GET and POST requests to the API,
+  # handles authentication, connection errors, and response parsing.
+  # It also supports a development mode for local testing.
+  class Client
+    def get(endpoint)
+      handle_connection_errors { parse_response(conn.get(endpoint)) }
+    end
+
+    def post(endpoint, payload = nil)
+      handle_connection_errors { parse_response(conn.post(endpoint, payload)) }
+    end
+
+    private
+
+    def parse_response(response)
+      if response.success?
+        JSON.parse(response.body)
+      else
+        Bento::Error.raise_with_response(response)
+      end
+    end
+
+    def authorization
+      @authorization ||= "Basic #{Base64.strict_encode64("#{Bento.publishable_key}:#{Bento.secret_key}")}"
+    end
+
+    def conn
+      Faraday.new(
+        url: Bento.dev_mode ? 'http://localhost:3000' : 'https://app.bentonow.com',
+        headers: {
+          'Content-Type' => 'application/json',
+          'Accept' => 'application/json',
+          'User-Agent' => 'bento-rails-' + Bento.site_uuid,
+          'Authorization' => authorization
+        }
+      )
+    end
+
+    def handle_connection_errors
+      yield
+    rescue Faraday::ConnectionFailed => exception
+      raise Bento::ConnectionError, "Failed to connect to the server: #{exception.message}"
+    end
+  end
+end

data/lib/bento/core/error.rb

@@ -0,0 +1,26 @@
+module Bento
+  # Custom error class for handling Bento API errors.
+  # This class encapsulates the HTTP response and provides
+  # a formatted error message for easier debugging and error handling.
+  class Error < StandardError
+    attr_reader :response
+
+    def initialize(response)
+      @response = response
+      super(formatted_error_message)
+    end
+
+    # Raises an instance of Bento::Error with the given response
+    def self.raise_with_response(response)
+      raise new(response)
+    end
+
+    private
+
+    def formatted_error_message
+      "HTTP #{response.status}: #{response.body}"
+    end
+  end
+end
+# Example usage:
+# Bento::Error.raise_with_response(response)

data/lib/bento/core/response.rb

@@ -0,0 +1,23 @@
+module Bento
+  # Represents a response from the Bento API.
+  # This class encapsulates the API response data and provides
+  # methods to check the status of the operation (success or failure)
+  # based on the number of successful and failed results.
+  class Response
+    attr_reader :results, :failed
+
+    def initialize(response)
+      @response = response
+      @results = response['results'].to_i
+      @failed = response['failed'].to_i
+    end
+
+    def success?
+      failed.zero?
+    end
+
+    def failure?
+      failed.positive?
+    end
+  end
+end

data/lib/bento/core/validators/base.rb

@@ -0,0 +1,18 @@
+module Bento
+  module Validators
+    module Base
+      def validate_email(email)
+        raise ArgumentError, 'Email is required' if email.nil? || email.empty?
+        raise ArgumentError, 'Invalid email format' unless email =~ /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i
+      end
+
+      def validate_type(type)
+        raise ArgumentError, 'Type is required' if type.nil? || type.empty?
+      end
+
+      def validate_fields(fields)
+        raise ArgumentError, 'Fields must be a hash' unless fields.is_a?(Hash)
+      end
+    end
+  end
+end

data/lib/bento/core/validators/email_validators.rb

@@ -0,0 +1,10 @@
+module Bento
+  module Validators
+    module EmailValidators
+      def validate_author(author)
+        raise ArgumentError, 'Author is required' if author.nil? || author.empty?
+        # Additional validation can be implemented based on system requirements
+      end
+    end
+  end
+end

data/lib/bento/core/validators/event_validators.rb

@@ -0,0 +1,46 @@
+module Bento
+  module Validators
+    module EventValidators
+      def validate_details(details)
+        raise ArgumentError, 'Details must be a hash' unless details.is_a?(Hash)
+        validate_unique(details[:unique]) if details.key?(:unique)
+        validate_value(details[:value]) if details.key?(:value)
+        validate_cart(details[:cart]) if details.key?(:cart)
+      end
+
+      def validate_unique(unique)
+        raise ArgumentError, 'Unique must be a hash' unless unique.is_a?(Hash)
+        raise ArgumentError, 'Unique key is required' unless unique.key?(:key)
+      end
+
+      def validate_value(value)
+        raise ArgumentError, 'Value must be a hash' unless value.is_a?(Hash)
+        raise ArgumentError, 'Currency is required in value' unless value.key?(:currency)
+        raise ArgumentError, 'Amount is required in value' unless value.key?(:amount)
+      end
+
+      def validate_cart(cart)
+        raise ArgumentError, 'Cart must be a hash' unless cart.is_a?(Hash)
+        validate_cart_items(cart[:items]) if cart.key?(:items)
+      end
+
+      def validate_cart_items(items)
+        raise ArgumentError, 'Cart items must be an array' unless items.is_a?(Array)
+        items.each do |item|
+          raise ArgumentError, 'Cart item must be a hash' unless item.is_a?(Hash)
+          raise ArgumentError, 'Product SKU is required in cart item' unless item.key?(:product_sku)
+          raise ArgumentError, 'Product name is required in cart item' unless item.key?(:product_name)
+          raise ArgumentError, 'Quantity is required in cart item' unless item.key?(:quantity)
+        end
+      end
+
+      def validate_event(event)
+        raise ArgumentError, 'Event must be a hash' unless event.is_a?(Hash)
+        validate_email(event[:email])
+        validate_type(event[:type])
+        validate_fields(event[:fields]) if event.key?(:fields)
+        validate_details(event[:details]) if event.key?(:details)
+      end
+    end
+  end
+end

data/lib/bento/core/version.rb

@@ -0,0 +1,3 @@
+module Bento
+  VERSION = "0.5.0".freeze
+end

data/lib/bento/resources/emails.rb

@@ -0,0 +1,59 @@
+module Bento
+  class Emails
+    class << self
+      include Bento::Validators::Base
+      include Bento::Validators::EmailValidators
+      # Send an email that honors subscription status
+      def send(to:, from:, subject:, html_body:, personalizations: {})
+        validate_email(to)
+        validate_author(from)
+
+        payload = {
+          to: to,
+          from: from,
+          subject: subject,
+          html_body: html_body,
+          personalizations: personalizations
+        }
+
+        send_bulk([payload])
+      end
+
+      # Send a transactional email that always sends, even if user is unsubscribed
+      def send_transactional(to:, from:, subject:, html_body:, personalizations: {})
+        validate_email(to)
+        validate_author(from)
+
+        payload = {
+          to: to,
+          from: from,
+          subject: subject,
+          html_body: html_body,
+          personalizations: personalizations,
+          transactional: true
+        }
+
+        send_bulk([payload])
+      end
+
+      def send_bulk(emails)
+        raise ArgumentError, 'Emails must be an array' unless emails.is_a?(Array)
+        emails.each { |email| validate_email(email[:to]); validate_email(email[:from]) }
+
+        payload = { emails: emails }.to_json
+        response = client.post("api/v1/batch/emails?#{URI.encode_www_form(default_params)}", payload)
+        Bento::Response.new(response)
+      end
+
+      private
+
+      def client
+        @client ||= Bento::Client.new
+      end
+
+      def default_params
+        { site_uuid: Bento.config.site_uuid }
+      end
+    end
+  end
+end

data/lib/bento/resources/events.rb

@@ -0,0 +1,77 @@
+module Bento
+  class Events
+    class << self
+      include Bento::Validators::Base
+      include Bento::Validators::EventValidators
+      # Track an event
+      # Usage examples:
+      #
+      # Basic event:
+      # Bento::Events.track(email: 'test@test.com', type: '$completed_onboarding')
+      #
+      # Event with fields:
+      # Bento::Events.track(
+      #   email: 'test@test.com',
+      #   type: '$completed_onboarding',
+      #   fields: { first_name: 'Jesse', last_name: 'Pinkman' }
+      # )
+      #
+      # Complex event with fields and details:
+      # Bento::Events.track(
+      #   email: 'test@test.com',
+      #   type: '$purchase',
+      #   fields: { first_name: 'Jesse' },
+      #   details: {
+      #     unique: { key: 'test123' },
+      #     value: { currency: 'USD', amount: 8000 },
+      #     cart: {
+      #       items: [
+      #         {
+      #           product_sku: 'SKU123',
+      #           product_name: 'Test',
+      #           quantity: 100
+      #         }
+      #       ],
+      #       abandoned_checkout_url: 'https://test.com'
+      #     }
+      #   }
+      # )
+      def track(email:, type:, fields: {}, details: {})
+        validate_email(email)
+        validate_type(type)
+        validate_fields(fields)
+        validate_details(details)
+
+        event = {
+          email: email,
+          type: type
+        }
+        event[:fields] = fields unless fields.empty?
+        event[:details] = details unless details.empty?
+
+        import([event])
+      end
+
+      # Batch track multiple events
+      # Usage: Bento::Events.import([{email: 'test@bentonow.com', type: 'Login'}, {email: 'test@bentonow.com', type: 'Purchase', fields: { first_name: 'Jesse', last_name: 'Hanley' }}])
+      def import(events)
+        raise ArgumentError, 'Events must be an array' unless events.is_a?(Array)
+        events.each { |event| validate_event(event) }
+
+        payload = { events: events }.to_json
+        response = client.post("api/v1/batch/events?#{URI.encode_www_form(default_params)}", payload)
+        Bento::Response.new(response)
+      end
+
+      private
+
+      def client
+        @client ||= Bento::Client.new
+      end
+
+      def default_params
+        { site_uuid: Bento.config.site_uuid }
+      end
+    end
+  end
+end

data/lib/bento/resources/spam.rb

@@ -0,0 +1,26 @@
+module Bento
+  class Spam
+    class << self
+      def valid?(email)
+        payload = {
+          email: email
+        }
+
+        response = client.post('api/v1/experimental/validation', payload.to_json)
+        
+        return response['valid']
+      end
+
+      # Example: Bento::Spam.risky?('test@bentonow.com')
+      def risky?(email)
+        !self.valid?(email)
+      end
+
+      private
+
+      def client
+        @client ||= Bento::Client.new
+      end
+    end
+  end
+end

data/lib/bento/resources/subscribers.rb

@@ -0,0 +1,137 @@
+module Bento
+  class Subscribers
+    class << self
+      # Find a subscriber by email or uuid
+      # Usage: Bento::Subscribers.find_by(email: 'test@bentonow.com')
+      # or: Bento::Subscribers.find_by(uuid: 'subscriber-uuid')
+      def find_by(email: nil, uuid: nil)
+        params = default_params
+        params[:email] = email if email
+        params[:uuid] = uuid if uuid
+        response = client.get("api/v1/fetch/subscribers?#{URI.encode_www_form(params)}")
+        
+        if response['data'].nil?
+          raise StandardError, 'Bento Error: No user found with the given email or uuid'
+        else
+          Subscriber.new(response['data'])
+        end
+      end
+      
+      # Find or create a subscriber by email or uuid
+      # Usage: Bento::Subscribers.find_or_create_by(email: 'test@bentonow.com')
+      # or: Bento::Subscribers.find_or_create_by(uuid: 'subscriber-uuid')
+      def find_or_create_by(email: nil)
+        params = default_params
+        payload = {
+          subscriber: {
+            email: email
+          }.compact
+        }.to_json
+
+        response = client.post("api/v1/fetch/subscribers?#{URI.encode_www_form(params)}", payload)
+        
+        if response['data'].nil?
+          raise StandardError, 'Bento Error: No user found with the given email or uuid'
+        else
+          Subscriber.new(response['data'])
+        end
+      end
+
+      # Import or update subscribers in bulk
+      # Usage: Bento::Subscribers.import([{email: 'user1@example.com', first_name: 'John'}, {email: 'user2@example.com', last_name: 'Doe'}])
+      def import(subscribers)
+        payload = { subscribers: subscribers }.to_json
+        response = client.post("api/v1/batch/subscribers?#{URI.encode_www_form(default_params)}", payload)
+        Bento::Response.new(response)
+      end
+
+      # Run a command to change a subscriber's data
+      # Usage: Bento::Subscribers.run_command(command: 'add_tag', email: 'test@bentonow.com', query: 'new_tag')
+      def run_command(command:, email:, query: nil)
+        payload = {
+          command: [{
+            command: command,
+            email: email,
+            query: query
+          }]
+        }.to_json
+        
+        response = client.post("api/v1/fetch/commands?#{URI.encode_www_form(default_params)}", payload)
+        Bento::Response.new(response)
+      end
+
+      # Add a tag to a subscriber
+      # Usage: Bento::Subscribers.add_tag(email: 'test@bentonow.com', tag: 'new_tag')
+      def add_tag(email:, tag:)
+        run_command(command: 'add_tag', email: email, query: tag)
+      end
+
+      # Add a tag to a subscriber via an event
+      # Usage: Bento::Subscribers.add_tag_via_event(email: 'test@bentonow.com', tag: 'event_tag')
+      def add_tag_via_event(email:, tag:)
+        run_command(command: 'add_tag_via_event', email: email, query: tag)
+      end
+
+      # Remove a tag from a subscriber
+      # Usage: Bento::Subscribers.remove_tag(email: 'test@bentonow.com', tag: 'old_tag')
+      def remove_tag(email:, tag:)
+        run_command(command: 'remove_tag', email: email, query: tag)
+      end
+
+      # Add a field to a subscriber
+      # Usage: Bento::Subscribers.add_field(email: 'test@bentonow.com', key: 'company', value: 'Acme Inc')
+      def add_field(email:, key:, value:)
+        run_command(command: 'add_field', email: email, query: { key: key, value: value })
+      end
+
+      # Remove a field from a subscriber
+      # Usage: Bento::Subscribers.remove_field(email: 'test@bentonow.com', field: 'company')
+      def remove_field(email:, field:)
+        run_command(command: 'remove_field', email: email, query: field)
+      end
+
+      # Subscribe a user
+      # Usage: Bento::Subscribers.subscribe(email: 'test@bentonow.com')
+      def subscribe(email:)
+        run_command(command: 'subscribe', email: email)
+      end
+
+      # Unsubscribe a user
+      # Usage: Bento::Subscribers.unsubscribe(email: 'test@bentonow.com')
+      def unsubscribe(email:)
+        run_command(command: 'unsubscribe', email: email)
+      end
+
+      # Change a subscriber's email
+      # Usage: Bento::Subscribers.change_email(old_email: 'old@example.com', new_email: 'new@example.com')
+      def change_email(old_email:, new_email:)
+        run_command(command: 'change_email', email: old_email, query: new_email)
+      end
+
+      private
+
+      def client
+        @client ||= Bento::Client.new
+      end
+
+      def default_params
+        { site_uuid: Bento.config.site_uuid }
+      end
+    end
+  end
+
+  class Subscriber
+    attr_reader :id, :uuid, :email, :fields, :cached_tag_ids, :unsubscribed_at, :navigation_url
+
+    def initialize(data)
+      @id = data['id']
+      attributes = data['attributes']
+      @uuid = attributes['uuid']
+      @email = attributes['email']
+      @fields = attributes['fields']
+      @cached_tag_ids = attributes['cached_tag_ids']
+      @unsubscribed_at = attributes['unsubscribed_at']
+      @navigation_url = attributes['navigation_url']
+    end
+  end
+end

data/lib/bento/sdk/backoff_policy.rb

@@ -0,0 +1,49 @@
+require "bento/sdk/defaults"
+
+module Bento
+  class Analytics
+    class BackoffPolicy
+      include Bento::Analytics::Defaults::BackoffPolicy
+
+      # @param [Hash] opts
+      # @option opts [Numeric] :min_timeout_ms The minimum backoff timeout
+      # @option opts [Numeric] :max_timeout_ms The maximum backoff timeout
+      # @option opts [Numeric] :multiplier The value to multiply the current
+      #   interval with for each retry attempt
+      # @option opts [Numeric] :randomization_factor The randomization factor
+      #   to use to create a range around the retry interval
+      def initialize(opts = {})
+        @min_timeout_ms = opts[:min_timeout_ms] || MIN_TIMEOUT_MS
+        @max_timeout_ms = opts[:max_timeout_ms] || MAX_TIMEOUT_MS
+        @multiplier = opts[:multiplier] || MULTIPLIER
+        @randomization_factor = opts[:randomization_factor] || RANDOMIZATION_FACTOR
+
+        @attempts = 0
+      end
+
+      # @return [Numeric] the next backoff interval, in milliseconds.
+      def next_interval
+        interval = @min_timeout_ms * (@multiplier**@attempts)
+        interval = add_jitter(interval, @randomization_factor)
+
+        @attempts += 1
+
+        [interval, @max_timeout_ms].min
+      end
+
+      private
+
+      def add_jitter(base, randomization_factor)
+        random_number = rand
+        max_deviation = base * randomization_factor
+        deviation = random_number * max_deviation
+
+        if random_number < 0.5
+          base - deviation
+        else
+          base + deviation
+        end
+      end
+    end
+  end
+end