iter 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0e2f0aa5860775ce8a35e8071cea50f55340a251d177e6ea71c52acc6a30165b
+  data.tar.gz: 0fad5fafa01504d396598a07184eaeaadc3675f60317e04d51f74b8ffc1fd3f4
+SHA512:
+  metadata.gz: e5269a14093d64f8b193cdb72d2f5838a418cc7c6ff910a0d560cdfcc371cfe7edf1baf0cdeb334427b09e1aa5c394a08d8960c63b0133d52b6f35f94b438c3c
+  data.tar.gz: e42058290262b82e5d20215694fb00598e4fa839e7e4e3d0a43abb5382576293ce21a85f09d886316c736af8e82608f319baa3cd4ebc0d48776a984014b271ab

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,17 @@
+# Omakase Ruby styling for Rails
+inherit_gem: { rubocop-rails-omakase: rubocop.yml }
+
+AllCops:
+  TargetRubyVersion: 3.2.2
+
+Style/StringLiterals:
+  Enabled: false
+
+Layout/SpaceInsideArrayLiteralBrackets:
+  Enabled: false
+
+Style/TrailingCommaInHashLiteral:
+  Enabled: false
+
+Style/TrailingCommaInArrayLiteral:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## [0.1.0] - 2025-03-11
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 HouseAccount, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,113 @@
+Iter - a Ruby client for the Iterable API
+======================================================
+
+Iter helps you write apps that need to interact with Iterable.
+
+The **source code** is available on [GitHub](https://github.com/claudiob/iter) and the **documentation** on [RubyDoc](http://www.rubydoc.info/gems/iter/frames).
+
+[![Code Climate](https://codeclimate.com/github/claudiob/iter.png)](https://codeclimate.com/github/claudiob/iter)
+[![Code coverage](https://img.shields.io/badge/code_coverage-100%25-44d298)](https://github.com/claudiob/bookmaker/actions)
+[![Rubygems](https://img.shields.io/gem/v/iter)](https://rubygems.org/gems/iter)
+
+After [registering your app](#configuring-your-app), you can run commands like:
+
+
+```ruby
+Iter::User.new(id:).update email:, fields:
+Iter::User.new(id:).delete
+Iter::Event.create(user_id:, name:, fields:)
+```
+
+The **full documentation** is available at [rubydoc.info](http://www.rubydoc.info/gems/iter/frames).
+
+How to install
+==============
+
+To install on your system, run
+
+    gem install iter
+
+To use inside a bundled Ruby project, add this line to the Gemfile:
+
+    gem 'iter', '~> 1.0'
+
+Since the gem follows [Semantic Versioning](http://semver.org),
+indicating the full version in your Gemfile (~> *major*.*minor*.*patch*)
+guarantees that your project won’t occur in any error when you `bundle update`
+and a new version of Iter is released.
+
+Configuring your app
+====================
+
+In order to use Iter you must have credentials to the [Iterable](https://www.iterable.com/) API.
+
+Add them to your code with the following snippet of code (replacing with your own credentials):
+
+```ruby
+Iter.configure do |config|
+  config.api_key = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ012345'
+end
+```
+
+Mocking the Iterable API
+======================
+
+Sometimes you want to mock the API requests to Iterable and obtain results that
+are equivalent to the original API calls. This can be useful to test your flow
+without hitting the API.
+
+
+Configuring with environment variables
+--------------------------------------
+
+As an alternative to the approach above, you can configure your app with
+variables. Setting the following environment variables:
+
+```bash
+export ITER_API_KEY="ABCDEFGHIJKLMNOPQRSTUVWXYZ012345"
+```
+
+is equivalent to the previous approach so pick the one you prefer.
+If a variable is set in both places, then `Iter.configure` takes precedence.
+
+How to test
+===========
+
+To run tests:
+
+```bash
+rspec
+```
+
+By default, tests are run with real HTTP calls to Iterable that must be
+set with the environment variables specified above.
+
+If you do not have access to Iterable, you can still run the tests mocked:
+
+```bash
+ITER_MOCK=1 rspec
+```
+
+How to release new versions
+===========================
+
+If you are a manager of this project, remember to upgrade the [Iter gem](http://rubygems.org/gems/iter)
+whenever a new feature is added or a bug gets fixed.
+Make sure all the tests are passing and the code is 100% test-covered.
+Document the changes in CHANGELOG.md and README.md, bump the version, then run:
+
+    rake release
+
+Remember that the iter gem follows [Semantic Versioning](http://semver.org).
+Any new release that is fully backward-compatible should bump the *minor* version (1.x).
+Any new version that breaks compatibility should bump the *major* version (x.0)
+
+How to contribute
+=================
+
+Iter needs your support!
+The goal of Iter is to provide a Ruby interface for all the methods exposed by the Iterable API.
+
+If you find that a method is missing, fork the project, add the missing code,
+write the appropriate tests, then submit a pull request, and it will gladly
+be merged!

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/iter/config.rb

@@ -0,0 +1,45 @@
+require 'iter/configuration'
+
+# An object-oriented Ruby client for Iterable.
+# @see http://www.rubydoc.info/gems/iter/
+module Iter
+  # Provides methods to read and write global configuration settings.
+  #
+  # A typical usage is to set the API key for the API calls.
+  #
+  # @example Set the API key for the API client:
+  #   Iter.configure do |config|
+  #     config.api_key = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ012345'
+  #   end
+  #
+  module Config
+    # Yields the global configuration to the given block.
+    #
+    # @example
+    #   Iter.configure do |config|
+    #     config.api_key = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ012345'
+    #   end
+    #
+    # @yield [Iter::Models::Configuration] The global configuration.
+    def configure
+      yield configuration if block_given?
+    end
+
+    # Returns the global {Iter::Models::Configuration} object.
+    #
+    # While this method _can_ be used to read and write configuration settings,
+    # it is easier to use {Iter::Config#configure} Iter.configure}.
+    #
+    # @example
+    #     Iter.configuration.api_key = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ012345'
+    #
+    # @return [Iter::Models::Configuration] The global configuration.
+    def configuration
+      @configuration ||= Iter::Configuration.new
+    end
+  end
+
+  # @note Config is the only module auto-loaded in the Iter module,
+  #       in order to have a syntax as easy as Iter.configure
+  extend Config
+end

data/lib/iter/configuration.rb

@@ -0,0 +1,39 @@
+module Iter
+  # Provides an object to store global configuration settings.
+  #
+  # This class is typically not used directly, but by calling
+  # {Iter::Config#configure Iter.configure}, which creates and updates a single
+  # instance of {Iter::Models::Configuration}.
+  #
+  # @example Set the API key for the API client:
+  #   Iter.configure do |config|
+  #     config.api_key = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ012345'
+  #   end
+  #
+  # @see Iter::Config for more examples.
+  #
+  # An alternative way to set global configuration settings is by storing
+  # them in the following environment variables:
+  #
+  # * +ITER_API_KEY+ to store the API key for the Iterable API
+  #
+  # In case both methods are used together,
+  # {Iter::Config#configure Iter.configure} takes precedence.
+  #
+  # @example Set the API credentials
+  #   ENV['ITER_API_KEY'] = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ012345'
+  class Configuration
+    # @return [String] the API key for the API calls.
+    attr_accessor :api_key
+
+    # @return [Boolean] whether to mock the HTTP calls to Iterable
+    attr_accessor :mock
+
+    # Initialize the global configuration settings, using the values of
+    # the specified following environment variables by default.
+    def initialize
+      @api_key = ENV['ITER_API_KEY']
+      @mock = ENV['ITER_MOCK'] == '1'
+    end
+  end
+end

data/lib/iter/connection_error.rb

@@ -0,0 +1,5 @@
+module Iter
+  # A wrapper around StandardError.
+  class ConnectionError < StandardError
+  end
+end

data/lib/iter/error.rb

@@ -0,0 +1,5 @@
+module Iter
+  # A wrapper around StandardError.
+  class Error < StandardError
+  end
+end

data/lib/iter/http_request.rb

@@ -0,0 +1,88 @@
+require 'json'
+require 'net/http'
+
+require 'iter/connection_error'
+require 'iter/error'
+
+module Iter
+  # A wrapper around +Net::HTTP+ to send HTTP requests to the Iterable API and
+  # return their result or raise an error if the result is unexpected.
+  # The basic way to use HTTPRequest is by calling +run+ on an instance.
+  # @example List the species of all breeds.
+  #   path = '/api/v1/resources/breeds/'
+  #   body = {securityToken: api_key}
+  #   response = Iter::HTTPRequest.new(path: path, body: body).run
+  #   response['Breeds'].map{|breed| breed['species']}
+  # @api private
+  class Request
+    # Initializes an HTTPRequest object.
+    # @param [Hash] options the options for the request.
+    # @option options [String] :path The path of the request URI.
+    # @option options [Hash] :body The body of the request.
+    def initialize(options = {})
+      @path = options[:path]
+      @body = options[:body]
+    end
+
+    # Sends the request and returns the body parsed from the JSON response.
+    # @return [Hash] the body parsed from the JSON response.
+    # @raise [Iter::ConnectionError] if the request fails.
+    # @raise [Iter::Error] if parsed body includes errors.
+    def run
+      return {} if response.body.empty?
+      JSON(response.body).tap do |data|
+        raise Error, "#{data['errMsg']} #{data['Errors']}" unless data['errNo'].zero?
+      end
+    end
+
+  private
+
+    # Run the request and memoize the response or the server error received.
+    def response
+      @response ||= Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
+        http.request http_request
+      end
+    rescue *server_errors => e
+      raise ConnectionError, e.message
+    end
+
+    # @return [URI::HTTPS] the (memoized) URI of the request.
+    def uri
+      attributes = { host: 'https://api.iterable.com', path: @path }
+      @uri ||= URI::HTTPS.build attributes
+    end
+
+    # @return [Net::HTTPRequest] the full HTTP request object,
+    #   inclusive of headers of request body.
+    def http_request
+      http_class = @query.any? ? Net::HTTP::Get : Net::HTTP::Post
+
+      @http_request ||= http_class.new(uri.request_uri).tap do |request|
+        set_request_body! request
+        set_request_headers! request
+      end
+    end
+
+    # Adds the request headers to the request in the appropriate format.
+    # The User-Agent header is also set to recognize the request.
+    def set_request_headers!(request)
+      request.initialize_http_header 'Content-Type' => 'application/json'
+      request.add_field 'User-Agent', 'Iter::HTTPRequest'
+    end
+
+    # Adds the request body to the request in the appropriate format.
+    def set_request_body!(request)
+      request.body = @body.to_json if @body
+    end
+
+    # Returns the list of server errors worth retrying the request once.
+    def server_errors
+      [
+        Errno::ECONNRESET, Errno::EHOSTUNREACH, Errno::ENETUNREACH,
+        Errno::ETIMEDOUT, Errno::ECONNREFUSED, Net::HTTPServerError,
+        OpenSSL::SSL::SSLError, OpenSSL::SSL::SSLErrorWaitReadable,
+        Net::OpenTimeout, SocketError,
+      ]
+    end
+  end
+end

data/lib/iter/mock_request.rb

@@ -0,0 +1,34 @@
+module Iter
+  # A mock version of HTTPRequest which returns pre-built responses.
+  # @example Updates the email of a user.
+  #   path = '/api/users/update'
+  #   body = {userId: '666', email: 'iter@example.com'}
+  #   response = Iter::Request.new(path: path, body: body).run
+  #   response['msg'] # => User successfully created/updated.
+  # @api private
+  class Request
+    # Initializes an MockRequest object.
+    # @param [Hash] options the options for the request.
+    # @option options [String] :path The path of the request URI.
+    # @option options [Hash] :body The body of the request.
+    def initialize(options = {})
+      @path = options[:path]
+      @body = options[:body]
+    end
+
+    # Sends the request and returns the body parsed from the JSON response.
+    # @return [Hash] the body parsed from the JSON response.
+    # @raise [Iter::ConnectionError] if the request fails.
+    # @raise [Iter::Error] if parsed body includes errors.
+    def run
+      case @path
+      when '/api/users/update'
+        # if @body[:email].include? '@'
+          { "msg" => "User successfully created/updated.", "code" => "Success" }
+        # else
+          # raise Error.new '{"msg"=>"Invalid email: iterexample.com", "code": "InvalidEmailAddressError"}'
+        # end
+      end
+    end
+  end
+end

data/lib/iter/relation.rb

@@ -0,0 +1,89 @@
+module Iter
+  # Provides methods to iterate through collections of Iterable resources.
+  # @private
+  class Relation
+    include Enumerable
+
+    # @yield [Hash] the options to change which items to iterate through.
+    def initialize(options = {}, &item_block)
+      @options = {parts: ['objectID', 'isActive'], next_page: 1}
+      @options.merge! options
+      @item_block = item_block
+    end
+
+    # Specifies which items to fetch when hitting the data API.
+    # @param [Hash<Symbol, String>] conditions The conditions for the items.
+    # @return [Iter::Relation] itself.
+    def where(conditions = {})
+      if @options[:conditions] != conditions
+        @items = []
+        @options.merge! conditions: conditions
+      end
+      self
+    end
+
+    # Specifies which parts of the resource to fetch when hitting the data API.
+    # @param [Array<Symbol>] parts The parts to fetch.
+    # @return [Iter::Relation] itself.
+    def select(*parts)
+      if @options[:parts] != parts + ['objectID', 'isActive']
+        @items = nil
+        @options.merge! parts: (parts + ['objectID', 'isActive'])
+      end
+      self
+    end
+
+    def each
+      @last_index = 0
+      while next_item = find_next
+        yield next_item
+      end
+    end
+
+  private
+
+    def request(path:, body: {}, query: {}, include_api_key: true)
+      if query.none? && include_api_key
+        body = body.merge securityToken: Iter.configuration.api_key
+      end
+
+      response_for path:, body:, query:
+    end
+
+    def response_for(path:, body: {}, query: {})
+      instrument do |data|
+        Request.new(path: path, query: query, body: body).run
+      end
+    end
+
+    def find_next
+      @items ||= []
+      if @items[@last_index].nil? && more_pages?
+        body = @options[:conditions].merge pageSize: 500, pageNo: @options[:next_page], sortMode: 3, sortDirection: 0
+
+        response_body = request path: '/api/v1/data/Contacts/', body: body
+
+        more_items = response_body['Contacts'].map do |contact_data|
+          Iter::Contact.new contact_data.slice(*@options[:parts])
+        end
+        @options.merge! next_page: (more_items.size == 500 ? @options[:next_page] + 1 : 1)
+        @items.concat more_items
+      end
+      @items[(@last_index +=1) -1]
+    end
+
+    def more_pages?
+      @last_index.zero? || @options[:next_page] > 1
+    end
+
+    # Provides instrumentation to ActiveSupport listeners
+    def instrument(&block)
+      data = { class_name: 'Iter::Contact' }
+      if defined?(ActiveSupport::Notifications)
+        ActiveSupport::Notifications.instrument 'Iter.request', data, &block
+      else
+        block.call data
+      end
+    end
+  end
+end

data/lib/iter/resource.rb

@@ -0,0 +1,12 @@
+require ENV['ITER_MOCK'] ? 'iter/mock_request' : 'iter/http_request'
+
+module Iter
+  # Provides an abstract class for every Iterable resource.
+  class Resource
+  private
+
+    def self.request(path:, body: {})
+      Request.new(path: path, body: body).run
+    end
+  end
+end

data/lib/iter/user.rb

@@ -0,0 +1,26 @@
+module Iter
+  # Provides methods to interact with Iterable users.
+  class User < Resource
+    PATH = '/api/v1/data/Clients/'
+
+    attr_reader :id, :email
+
+    def initialize(id:)
+      @id = id
+    end
+
+
+    def self.update(email:, fields:)
+      body = {
+        userId: id,
+        email: email,
+        dataFields: fields,
+      }
+
+      data = request path: '/api/users/update', body: body
+
+      email = value_for_field data, 238
+      new id: contact_id, email: email
+    end
+  end
+end

data/lib/iter/version.rb

@@ -0,0 +1,3 @@
+module Iter
+  VERSION = '0.1.0'
+end

data/lib/iter.rb

@@ -0,0 +1,10 @@
+# Used by multiple resources
+require 'uri'
+require_relative 'iter/error'
+require_relative 'iter/config'
+
+# Individual resources
+require_relative 'iter/connection_error'
+require_relative 'iter/event'
+require_relative 'iter/user'
+require_relative 'iter/version'

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: iter
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- claudiob
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A Ruby client for the Iterable API.
+email:
+- claudiob@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/iter.rb
+- lib/iter/config.rb
+- lib/iter/configuration.rb
+- lib/iter/connection_error.rb
+- lib/iter/error.rb
+- lib/iter/http_request.rb
+- lib/iter/mock_request.rb
+- lib/iter/relation.rb
+- lib/iter/resource.rb
+- lib/iter/user.rb
+- lib/iter/version.rb
+homepage: https://rubygems.org/gems/iter
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://rubygems.org/gems/iter
+  source_code_uri: https://github.com/claudiob/iter
+  changelog_uri: https://github.com/claudiob/iter/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: A Ruby client for the Iterable API.
+test_files: []