iterable-api-client 0.1.0 → 0.2.0

data/lib/iterable.rb

@@ -1,4 +1,34 @@
-files = %w[]
+require 'json'
+require 'net/http'
+require 'uri'
+
+require 'multi_json'
+
+files = %w[
+  api_resource
+  config
+  response
+  request
+  lists
+  campaigns
+  channels
+  events
+  message_types
+  templates
+  email_templates
+  push_templates
+  users
+  workflows
+  metadata
+  metadata_table
+  experiments
+  email
+  device
+  commerce
+  export
+  json_exporter
+  csv_exporter
+]
 
 files.each { |path| require_relative "./iterable/#{path}" }
 
@@ -6,4 +36,34 @@ files.each { |path| require_relative "./iterable/#{path}" }
 #
 # Iterable module for API interactions
 module Iterable
+  DATE_FORMAT = '%Y-%m-%d'.freeze
+
+  module_function
+
+  ##
+  #
+  # Configure a default [Iterable::Config] object to be used when interacting
+  # with API endpoints
+  #
+  # @example Configuring with token
+  #   Iterable.configure do |conf|
+  #     conf.token = 'secret-token'
+  #   end
+  def configure
+    config.tap do |conf|
+      yield conf
+    end
+  end
+
+  ##
+  #
+  # @return [Iterable::Config] The default config for API endpoints
+  def config
+    @config ||= Config.new
+  end
+
+  # @!visibility private
+  def request(conf, path, params = {})
+    Request.new conf, path, params
+  end
 end

data/lib/iterable/api_resource.rb

@@ -0,0 +1,39 @@
+module Iterable
+  ##
+  #
+  # ApiResource is a parent class for rest resources for the
+  # Iterable API. It allows for request conifugration to be
+  # set per request if needed, otherwise the default global
+  # Iterable.config is used
+  class ApiResource
+    attr_reader :conf
+
+    ##
+    #
+    # Initialize a new ApiResource with an optional config. Will default to
+    # the global [Iterable::Config] via `Iterable.config`
+    #
+    # @return [Iterable::ApiResource]
+    def initialize(conf = nil)
+      @conf = conf ? conf : default_config
+    end
+
+    ##
+    #
+    # Global Iterable config accessor for class
+    #
+    # @return [Iterable::Config]
+    def self.default_config
+      Iterable.config
+    end
+
+    ##
+    #
+    # Global Iterable config accessor for instance
+    #
+    # @return [Iterable::Config]
+    def default_config
+      self.class.default_config
+    end
+  end
+end

data/lib/iterable/campaigns.rb

@@ -0,0 +1,68 @@
+module Iterable
+  ##
+  #
+  # Interact with /campaigns API endpoints
+  #
+  # @example Creating campaigns endpoint object
+  #   # With default config
+  #   campaigns = Iterable::Campaigns.new
+  #   campaigns.all
+  #
+  #   # With custom config
+  #   conf = Iterable::Config.new(token: 'new-token')
+  #   campaigns = Iterable::Campaigns.new(config)
+  class Campaigns < ApiResource
+    ##
+    #
+    # Get all campaigns
+    #
+    # @return [Iterable::Response] A response object
+    def all
+      Iterable.request(conf, '/campaigns').get
+    end
+
+    ##
+    #
+    # Create a new campaign. Requires a name, templateId and at least one listId
+    #
+    # @param name [String] The name of the campaign
+    # @param template_id [Integer] The templateId to use for the campaign
+    # @param list_ids [Array] Array of listIds to use for the campaign
+    # @param attrs [Hash] Any other campaign attributes to set
+    #
+    # @return [Iterable::Response] A response object
+    def create(name, template_id, list_ids = [], attrs = {})
+      body = attrs.merge(name: name, templateId: template_id, listIds: list_ids)
+      Iterable.request(conf, '/campaigns/create').post(body)
+    end
+
+    ##
+    #
+    # Get recurring child campaigns for a campaign
+    #
+    # @param campaign_id [Integer] Root campaign ID to get child recurring campaigns for
+    #
+    # @return [Iterable::Response] A response object
+    def recurring(campaign_id)
+      Iterable.request(conf, "/campaigns/recurring/#{campaign_id}/childCampaigns").get
+    end
+
+    ##
+    #
+    # Export metrics in CSV format for one or more campaigns
+    #
+    # @param name [Array] An array of campaign ids, must have at least one
+    # @param start_time [Date|Time] Start of metrics to query for
+    # @param end_time [Date|Time] End of metrics to query for
+    #
+    # @return [Iterable::Response] A response object
+    def metrics(campaign_ids = [], start_time = nil, end_time = nil)
+      params = { campaignId: campaign_ids }
+      if start_time
+        params[:startTime] = start_time.to_date.strftime(Iterable::DATE_FORMAT)
+        params[:endTime] = end_time.to_date.strftime(Iterable::DATE_FORMAT)
+      end
+      Iterable.request(conf, '/campaigns/metrics', params).get
+    end
+  end
+end

data/lib/iterable/channels.rb

@@ -0,0 +1,24 @@
+module Iterable
+  ##
+  #
+  # Interact with /channels API endpoints
+  #
+  # @example Creating channels endpoint object
+  #   # With default config
+  #   campaigns = Iterable::Channels.new
+  #   campaigns.all
+  #
+  #   # With custom config
+  #   conf = Iterable::Config.new(token: 'new-token')
+  #   campaigns = Iterable::Channels.new(config)
+  class Channels < ApiResource
+    ##
+    #
+    # Get all channels
+    #
+    # @return [Iterable::Response] A response object
+    def all
+      Iterable.request(conf, '/channels').get
+    end
+  end
+end

data/lib/iterable/commerce.rb

@@ -0,0 +1,53 @@
+module Iterable
+  ##
+  #
+  # Interact with /commerce API endpoints
+  #
+  # @example Creating commerce endpoint object
+  #   # With default config
+  #   commerce = Iterable::Commerce.new
+  #   commerce.all
+  #
+  #   # With custom config
+  #   conf = Iterable::Config.new(token: 'new-token')
+  #   commerce = Iterable::Commerce.new(config)
+  class Commerce < ApiResource
+    ##
+    #
+    # Track a purchase. 'shoppingCartItems' field on the user profile is cleared.
+    # User profile is also updated (created otherwise) using the user request field
+    #
+    # @param total [Float] Total order amount
+    # @param items [Array[Hash]] Array of hashes of commerce items
+    # @param user [Hash] User update request details to update or create user
+    # @param attrs [Hash] Track purchase request additional fields
+    #
+    # @return [Iterable::Response] A response object
+    def track_purchase(total, items = [], user = {}, attrs = {})
+      data = {
+        total: total,
+        items: items,
+        user: user
+      }
+      data.merge!(attrs)
+      Iterable.request(conf, '/commerce/trackPurchase').post(data)
+    end
+
+    ##
+    #
+    # Updates the 'shoppingCartItems' field on the user profile with shopping
+    # cart items. User profile is updated (created otherwise) via the user field.
+    #
+    # @param user [Hash] User update request details to update or create user
+    # @param items [Array[Hash]] Array of hashes of commerce items
+    #
+    # @return [Iterable::Response] A response object
+    def update_cart(user = {}, items = [])
+      data = {
+        items: items,
+        user: user
+      }
+      Iterable.request(conf, '/commerce/updateCart').post(data)
+    end
+  end
+end

data/lib/iterable/config.rb

@@ -0,0 +1,39 @@
+module Iterable
+  ##
+  # Config provides a class to configre the API calls when interacting with
+  # REST endpoints
+  #
+  # @example Creating a config object
+  #   Iterable::Config.new token: 'secret-token'
+  class Config
+    DEFAULT_VERSION = '1.8'.freeze
+    DEFAULT_HOST = 'https://api.iterable.com'.freeze
+    DEFAULT_URI = "#{DEFAULT_HOST}/api".freeze
+    DEFAULT_PORT = 443
+
+    attr_accessor :token
+    attr_reader :host, :port, :version
+
+    ##
+    #
+    # initialize a new [Iterable::Config] object for requests
+    #
+    # @param token [String] Iterable API token
+    # @return [Iterable::Config]
+    def initialize(token: nil)
+      @host = DEFAULT_HOST
+      @port = DEFAULT_PORT
+      @version = DEFAULT_VERSION
+      @token = token
+    end
+
+    ##
+    #
+    # Creates a [URI] for the API host
+    #
+    # @return [URI] API URI object
+    def uri
+      URI.parse("#{@host || DEFAULT_HOST}:#{@port || DEFAULT_PORT}/api")
+    end
+  end
+end

data/lib/iterable/csv_exporter.rb

@@ -0,0 +1,19 @@
+module Iterable
+  ##
+  #
+  # Subclass of [Iterable::Export] for CSV exporting of data
+  #
+  # @example Creating a CSV Exporter
+  #   # With default config
+  #   exporter = Iterable::CsvExporter.new Iterable::Export::EMAIL_SEND_TYPE
+  #   exporter.export
+  #
+  #   # With custom config
+  #   conf = Iterable::Config.new(token: 'new-token')
+  #   exporter = Iterable::CsvExporter.new(Iterable::Export::EMAIL_SEND_TYPE, nil, nil, nil, config)
+  class CsvExporter < Export
+    def format
+      'csv'
+    end
+  end
+end

data/lib/iterable/device.rb

@@ -0,0 +1,74 @@
+module Iterable
+  ##
+  #
+  # Interact with user device API endpoints
+  #
+  # @example Creating device endpoint object
+  #   # With default config
+  #   campaigns = Iterable::Device.new 'token', 'app-name', Iterable::Device::APNS
+  #   campaigns.all
+  #
+  #   # With custom config
+  #   conf = Iterable::Device.new(token: 'new-token')
+  #   campaigns = Iterable::Device.new('token', 'app-name', Iterable::Device::APNS, config)
+  class Device < ApiResource
+    PLATFORMS = [
+      APNS = 'APNS'.freeze,
+      APNS_SANDBOX = 'APNS_SANDBOX'.freeze,
+      GCM = 'GCM'.freeze
+    ].freeze
+
+    attr_reader :app, :data_fields, :platform, :token
+
+    ##
+    #
+    # Initialize an [Iterable::Device] to register for a user
+    #
+    # @param token [String] The device token
+    # @param app [String] The application name for mobile push
+    # @param platform [String] The device device platform; one of [Iterable::Device::PLATFORMS]
+    # @param data_fields [Hash] Additional device data fields
+    # @param conf [Iterable::Config] A config to optionally pass for requests
+    #
+    # @return [Iterable::Device]
+    def initialize(token, app, platform, data_fields = {}, conf = nil)
+      @token = token
+      @app = app
+      @platform = platform
+      @data_fields = data_fields
+      super conf
+    end
+
+    ##
+    #
+    # Register a device for a user email or id
+    #
+    # @param email [String] Email of user to associate device with
+    # @param user_id [String] User ID to associate device with instead of email
+    #
+    # @return [Iterable::Response] A response object
+    def register(email, user_id = nil)
+      attrs = {
+        device: device_data
+      }
+      attrs[:email] = email if email
+      attrs[:userId] = user_id if user_id
+      Iterable.request(conf, base_path).post(attrs)
+    end
+
+    private
+
+    def base_path
+      '/users/registerDeviceToken'
+    end
+
+    def device_data
+      {
+        token: @token,
+        applicationName: @app,
+        platform: @platform,
+        dataFields: @data_fields
+      }
+    end
+  end
+end

data/lib/iterable/email.rb

@@ -0,0 +1,28 @@
+module Iterable
+  ##
+  #
+  # Interact with /email API endpoints
+  #
+  # @example Creating email endpoint object
+  #   # With default config
+  #   templates = Iterable::Email.new
+  #   templates.get
+  #
+  #   # With custom config
+  #   conf = Iterable::Config.new(token: 'new-token')
+  #   templates = Iterable::Email.new(config)
+  class Email < ApiResource
+    ##
+    #
+    # View an email message sent
+    #
+    # @param email [String] Email of user who received the message to view
+    # @param message_id [String|Integer] Message id for message sent
+    #
+    # @return [Iterable::Response] A response object
+    def view(email, message_id)
+      params = { email: email, messageId: message_id }
+      Iterable.request(conf, '/email/viewInBrowser', params).get
+    end
+  end
+end

data/lib/iterable/email_templates.rb

@@ -0,0 +1,54 @@
+module Iterable
+  ##
+  #
+  # Interact with /templates/email API endpoints
+  #
+  # @example Creating email templates endpoint object
+  #   # With default config
+  #   templates = Iterable::EmailTemplates.new
+  #   templates.get
+  #
+  #   # With custom config
+  #   conf = Iterable::Config.new(token: 'new-token')
+  #   templates = Iterable::EmailTemplates.new(config)
+  class EmailTemplates < ApiResource
+    ##
+    #
+    # Get an email template
+    #
+    # @param template_id [String|Integer] An email template ID
+    # @param params [Hash] Additional params to use such as locale
+    #
+    # @return [Iterable::Response] A response object
+    def get(template_id, params = {})
+      params['templateId'] = template_id
+      Iterable.request(conf, '/templates/email/get', params).get
+    end
+
+    ##
+    #
+    # Update an email template
+    #
+    # @param template_id [String|Integer] An email template ID
+    # @param attrs [Hash] Update attributes
+    #
+    # @return [Iterable::Response] A response object
+    def update(template_id, attrs = {})
+      attrs['templateId'] = template_id
+      Iterable.request(conf, '/templates/email/update').post(attrs)
+    end
+
+    ##
+    #
+    # Upsert an email template by client template ID
+    #
+    # @param client_template_id [String] A client template id to use or create
+    # @param attrs [Hash] Update attributes
+    #
+    # @return [Iterable::Response] A response object
+    def upsert(client_template_id, attrs = {})
+      attrs['clientTemplateId'] = client_template_id
+      Iterable.request(conf, '/templates/email/upsert').post(attrs)
+    end
+  end
+end