mailchimp-rest-api 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f7356505754644055f03ee2a25a23910247fc87fb350672e6a1fa3f3ead64626
+  data.tar.gz: f95ac89a0685693ed4be9afb6f5d78fb2948b724b96ac7d7a130e151ae275573
+SHA512:
+  metadata.gz: d40b3c60e6ab469604cbca9c7d10da2a91483e9c9653d461d5c9485c84243162b2996ce17e1466607d25ae970a6da3d2075dcbe39c870b6c13ed5f12603444b6
+  data.tar.gz: ace08ae4987164126a36da7879ae75a7f4acb571b2f1ca8b61df51a5788410636b5c7d105bae535e51e973f21b67984aece570b221e9f951a1d03f0f400c0bb8

data/README.md

@@ -0,0 +1,154 @@
+# Mailchimp REST API (Marketing)
+
+## Installation
+
+```bash
+bundle add mailchimp-rest-api
+```
+
+## Features
+
+- Supported Ruby Versions - *(2.6 .. 3.3), head, jruby-9.4, truffleruby-24*
+- No dependencies;
+- Auto-retries (configured);
+- Pagination methods
+
+## Usage
+
+```ruby
+# Setup client
+MailchimpAPI.client = MailchimpAPI::Client.new(api_key: ENV['MAILCHIMP_API_KEY'])
+
+# Call any HTTP API
+MailchimpAPI.post(path, query: query, body: body, headers: headers)
+MailchimpAPI.get(path, query: query, body: body, headers: headers)
+MailchimpAPI.patch(path, query: query, body: body, headers: headers)
+MailchimpAPI.put(path, query: query, body: body, headers: headers)
+MailchimpAPI.delete(path, query: query, body: body, headers: headers)
+
+# Call any defined REST API (defined in lib/resources)
+MailchimpAPI::Audience::Members.show(audience_id, email, query: query)
+MailchimpAPI::Audience::Members.create(audience_id, body: body)
+
+# Or call it via shortcuts (defined in lib/client/api_methods.rb)
+MailchimpAPI.audience_members.show(audience_id, email, query: query)
+MailchimpAPI.audience_members.create(audience_id, body: body)
+```
+
+### Response
+
+`Response` object is returned after each `API` request.
+
+#### Original HTTP response data
+
+- `response.http_status` - response HTTP status as Integer
+- `response.http_body` - response body as String
+- `response.http_headers` - response headers as Hash with String keys
+- `response.http_response` - original Net::HTTP::Response object
+- `response.request` - Request object that was used to get this response
+
+#### Parsed JSON body methods
+
+- `response.body` - parsed JSON body, keys are Symbols
+- `response[:field]` - gets `:field` attribute from parsed body,
+  returns nil if response have no such key
+- `response.fetch(:field)` - gets `:field` attribute from parsed body,
+  raises KeyError if response has no such key
+
+#### Error check methods
+
+- `response.success?` - checks HTTP status code is 2xx
+- `response.failed?` - checks HTTP status code is not 2xx
+
+## Configuration options
+
+MailchimpAPI client accepts this additional options:
+
+- `:retries`
+- `:http_opts`
+
+### Option `:retries`
+
+This is a Hash with retries configuration.
+By default retries are enabled, 4 retries with 0, 0.25, 0.75, 1.5 seconds delay.
+Default config: `{enabled: true, count: 4, sleep: [0, 0.25, 0.75, 1.5]}`.
+New options are merged with defaults.
+Please keep `sleep` array same size as `count`.
+
+Retries happen on any network error, on 409, 429, 5xx response status code.
+
+```ruby
+client = MailchimpAPI::Client.new(
+  retries: {enabled: !Rails.env.test?, count: 5, sleep: [0, 0.25, 0.75, 1.5, 2]}
+  # ...
+)
+```
+
+### Option `:http_opts`
+
+This are the options that are provided to the `Net::HTTP.start` method,
+like `:read_timeout`, `:write_timeout`, etc.
+
+You can find full list of available options here <https://docs.ruby-lang.org/en/master/Net/HTTP.html#method-c-start>
+(Please choose you version of ruby).
+
+By default it is an empty hash.
+
+```ruby
+client = MailchimpAPI::Client.new(
+  http_opts: {read_timeout: 30, write_timeout: 30, open_timeout: 30}
+  # ...
+)
+```
+
+## Pagination
+
+We have two specific methods:
+
+- `MailchimpAPI#each_page(response)` - iterates over current and each next page
+- `MailchimpAPI#each_page_item(response, items_field_name)` - iterates over
+  items on each page
+
+Example:
+
+```ruby
+first_page = MailchimpAPI.audience_members.list(list_id, query: { count: 100 }
+
+MailchimpAPI.each_page(first_page) do |response|
+  puts response.body
+end
+
+MailchimpAPI.each_page_item(first_page, :members) do |item|
+  puts item[:email_address]
+end
+```
+
+## Request
+
+...
+
+## Errors
+
+...
+
+## APIs
+
+...
+
+## Development
+
+```bash
+  rubocop
+  rspec
+  mdl README.md CHANGELOG.md RELEASE.md
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at <https://github.com/aglushkov/mailchimp-rest-api>.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+[pagination]: #pagination

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/lib/mailchimp-api/batch_request.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module MailchimpAPI
+  class BatchRequest
+    API_VERSION_PREFIX = "/#{MailchimpAPI::API_VERSION}"
+
+    attr_reader :request, :operation_id
+
+    def initialize(request, operation_id: nil)
+      @request = request
+      @operation_id = operation_id
+    end
+
+    # Make a batch operation request
+    # https://mailchimp.com/developer/marketing/guides/run-async-requests-batch-endpoint/#make-a-batch-operations-request
+    def operation
+      operation = {
+        method: request.method, # "GET", "POST", "PUT", "PATCH", "DELETE"
+        path: request.path.delete_prefix(API_VERSION_PREFIX) # Path relative to version prefix
+      }
+
+      body = request.body
+      operation[:body] = body if body
+
+      params = request.query
+      operation[:params] = params unless params.empty?
+
+      operation[:operation_id] = operation_id if operation_id
+      operation
+    end
+  end
+end

data/lib/mailchimp-api/client/api_methods.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module MailchimpAPI
+  class Client
+    #
+    # Methods to access API resources
+    #
+    module APIMethods
+      def audience_members
+        Audience::Members.new(self)
+      end
+
+      def audience_member_tags
+        Audience::MemberTags.new(self)
+      end
+    end
+  end
+end

data/lib/mailchimp-api/client/batch_methods.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module MailchimpAPI
+  class Client
+    #
+    # Methods to create and run batch requests
+    #
+    module BatchMethods
+      def batch_get_request(path, query: nil, body: nil, headers: nil, operation_id: nil)
+        new_batch_request(Net::HTTP::Get, path, query: query, body: body, headers: headers, operation_id: operation_id)
+      end
+
+      def batch_post_request(path, query: nil, body: nil, headers: nil, operation_id: nil)
+        new_batch_request(Net::HTTP::Post, path, query: query, body: body, headers: headers, operation_id: operation_id)
+      end
+
+      def batch_put_request(path, query: nil, body: nil, headers: nil, operation_id: nil)
+        new_batch_request(Net::HTTP::Put, path, query: query, body: body, headers: headers, operation_id: operation_id)
+      end
+
+      def batch_patch_request(path, query: nil, body: nil, headers: nil, operation_id: nil)
+        new_batch_request(Net::HTTP::Patch, path, query: query, body: body, headers: headers, operation_id: operation_id)
+      end
+
+      def batch_delete_request(path, query: nil, body: nil, headers: nil, operation_id: nil)
+        new_batch_request(Net::HTTP::Delete, path, query: query, body: body, headers: headers, operation_id: operation_id)
+      end
+
+      def batch(batch_requests, query: nil)
+        operations = batch_requests.map(&:operation)
+        post("batches", query: query, body: {operations: operations})
+      end
+
+      private
+
+      # rubocop:disable Metrics/ParameterLists
+      def new_batch_request(http_method, path, query: nil, body: nil, headers: nil, operation_id: nil)
+        request = new_request(http_method, path: path, query: query, body: body, headers: headers)
+        BatchRequest.new(request, operation_id: operation_id)
+      end
+      # rubocop:enable Metrics/ParameterLists
+    end
+  end
+end

data/lib/mailchimp-api/client/pagination_methods.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module MailchimpAPI
+  class Client
+    module PaginationMethods
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      def next_page(response)
+        unless response.body.key?(:total_items)
+          raise Error, "Please ensure `total_items` field is not excluded from response"
+        end
+
+        request = response.request
+        query = request.query
+
+        count = query.key?(:count) ? query[:count].to_i : 10
+        offset = query.key?(:offset) ? query[:offset].to_i : 0
+
+        body = response.body
+        total_items = body[:total_items].to_i
+        is_final_page = ((offset + count) >= total_items)
+        return if is_final_page
+
+        new_query = query.merge(offset: offset + count, count: count)
+
+        get(
+          request.path,
+          query: new_query,
+          body: request.body,
+          headers: request.headers
+        )
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+      def each_page(response, &block)
+        return enum_for(:each_page, response) unless block
+
+        page = response
+        yield(page)
+        yield(page) while (page = next_page(page))
+      end
+
+      def each_page_item(response, items_field_name, &block)
+        return enum_for(:each_page_item, response, items_field_name) unless block
+
+        each_page(response) do |page|
+          page.body.fetch(items_field_name).each(&block)
+        end
+      end
+    end
+  end
+end

data/lib/mailchimp-api/client.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module MailchimpAPI
+  class Client
+    API_VERSION = MailchimpAPI::API_VERSION
+
+    include APIMethods
+    include BatchMethods
+    include PaginationMethods
+
+    attr_reader :api_key, :api_url, :api_version, :authorization_token, :config
+
+    def initialize(api_key:, http_opts: nil, retries: nil)
+      raise ArgumentError, "Invalid api_key" unless /\w+-\w+/.match?(api_key) # <token>-<dc>
+      dc = api_key.split("-", 2).last # initial api_key must have format
+
+      @api_key = api_key
+      @api_url = "https://#{dc}.api.mailchimp.com/#{API_VERSION}/"
+      @authorization_token = "Bearer #{api_key}"
+      @config = Config.new(http_opts: http_opts, retries: retries)
+    end
+
+    def post(path, query: nil, body: nil, headers: nil)
+      execute(Net::HTTP::Post, path, query: query, body: body, headers: headers)
+    end
+
+    def get(path, query: nil, body: nil, headers: nil)
+      execute(Net::HTTP::Get, path, query: query, body: body, headers: headers)
+    end
+
+    def patch(path, query: nil, body: nil, headers: nil)
+      execute(Net::HTTP::Patch, path, query: query, body: body, headers: headers)
+    end
+
+    def put(path, query: nil, body: nil, headers: nil)
+      execute(Net::HTTP::Put, path, query: query, body: body, headers: headers)
+    end
+
+    def delete(path, query: nil, body: nil, headers: nil)
+      execute(Net::HTTP::Delete, path, query: query, body: body, headers: headers)
+    end
+
+    private
+
+    def execute(http_method, path, query:, body:, headers:)
+      headers = {"authorization" => authorization_token}.merge!(headers || {})
+      request = new_request(http_method, path: path, query: query, body: body, headers: headers)
+      RequestExecutor.new(request, http_opts: config.http_opts, retries: config.retries).call
+    end
+
+    def new_request(http_method, path:, query:, body:, headers:)
+      Request.new(http_method, url: api_url, path: path, query: query, body: body, headers: headers)
+    end
+  end
+end

data/lib/mailchimp-api/config.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module MailchimpAPI
+  #
+  # Stores client requests configuration
+  #
+  class Config
+    # Default config options
+    DEFAULTS = {
+      http_opts: {}.freeze,
+      retries: {enabled: true, count: 4, sleep: [0, 0.25, 0.75, 1.5].freeze}.freeze
+    }.freeze
+
+    attr_reader :http_opts, :retries
+
+    # Initializes Config
+    #
+    # @param http_opts [Hash] Net::Http opts for all requests
+    # @param retries [Hash] Retries configuration
+    #
+    # @return [Client] Initialized config object
+    #
+    def initialize(http_opts: nil, retries: {})
+      @http_opts = http_opts.dup.freeze || DEFAULTS[:http_opts]
+      @retries = DEFAULTS[:retries].merge(retries || {}).freeze
+
+      freeze
+    end
+  end
+end

data/lib/mailchimp-api/error.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module MailchimpAPI
+  #
+  # Common interface for all errors
+  #
+  class Error < StandardError
+    # @return [Response, nil] Returned response with non-200 status code
+    attr_reader :response
+
+    # @return [Request] Sent request
+    attr_reader :request
+
+    # @return [String, nil] Error type returned by Mailchimp
+    attr_reader :error_type
+
+    # @return [String] Error title returned by Mailchimp or response error class name
+    attr_reader :error_title
+
+    # @return [String] Error status returned by Mailchimp or response HTTP status
+    attr_reader :error_status
+
+    # @return [String, nil] Error description returned by Mailchimp
+    attr_reader :error_detail
+
+    # @return [String, nil] Error ID returned by Mailchimp
+    attr_reader :error_instance
+
+    # @return [Hash, nil] Fields specific errors returned by Mailchimp
+    attr_reader :error_fields
+  end
+
+  #
+  # Namespace for specific MailchimpAPI errors
+  #
+  module Errors
+    #
+    # Raised when Mailchimp responds with any status code except 200, 201, 202, 204
+    #
+    class FailedRequest < Error
+      def initialize(message = nil, request:, response:)
+        @request = request
+        @response = response
+
+        body = response.body
+        data = body.is_a?(Hash) ? body : {}
+        @error_type = data[:type]
+        @error_title = data[:title] || response.http_response.class.name
+        @error_detail = data[:detail]
+        @error_status = data[:status] || response.http_status
+        @error_fields = data[:errors]
+        @error_instance = data[:instance]
+
+        message += "\n  #{response.http_body}" unless data.empty?
+        super(message)
+      end
+    end
+
+    #
+    # Raised when a network raised when executing the request
+    # List of network errors can be found in errors/network_error_builder.rb
+    #
+    class NetworkError < Error
+      def initialize(message = nil, request:, error:)
+        super(message)
+        @request = request
+        @response = nil
+
+        @error_type = nil
+        @error_title = error.class.name
+        @error_detail = error.message
+        @error_status = nil
+        @error_fields = nil
+        @error_instance = nil
+      end
+    end
+
+    # 400
+    class BadRequest < FailedRequest
+    end
+
+    # 401
+    class Unauthorized < FailedRequest
+    end
+
+    # 403
+    class Forbidden < FailedRequest
+    end
+
+    # 404
+    class NotFound < FailedRequest
+    end
+
+    # 405
+    class MethodNotAllowed < FailedRequest
+    end
+
+    # 414
+    class RequestURITooLong < FailedRequest
+    end
+
+    # 422
+    class UnprocessableEntity < FailedRequest
+    end
+
+    # 426
+    class UpgradeRequired < FailedRequest
+    end
+
+    # 429
+    class TooManyRequests < FailedRequest
+    end
+
+    # 5xx
+    class ServerError < FailedRequest
+    end
+  end
+end

data/lib/mailchimp-api/failed_request_error_builder.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "net/http"
+
+module MailchimpAPI
+  #
+  # Builds MailchimpAPI::FailedRequest error
+  #
+  class FailedRequestErrorBuilder
+    # Matchings for Net::HTTP response class to MailchimpAPI::Error class
+    RESPONSE_ERROR_MAP = {
+      Net::HTTPBadRequest => Errors::BadRequest,                     # 400
+      Net::HTTPUnauthorized => Errors::Unauthorized,                 # 401
+      Net::HTTPForbidden => Errors::Forbidden,                       # 403
+      Net::HTTPNotFound => Errors::NotFound,                         # 404
+      Net::HTTPMethodNotAllowed => Errors::MethodNotAllowed,         # 405
+      Net::HTTPRequestURITooLong => Errors::RequestURITooLong,       # 414
+      Net::HTTPUnprocessableEntity => Errors::UnprocessableEntity,   # 422
+      Net::HTTPUpgradeRequired => Errors::UpgradeRequired,           # 426
+      Net::HTTPTooManyRequests => Errors::TooManyRequests,           # 429
+      Net::HTTPServerError => Errors::ServerError                    # 5xx
+    }.freeze
+
+    class << self
+      # Builds FailedRequestError instance
+      #
+      # @param request [Request] Original request
+      # @param response [Response] Original response
+      #
+      # @return [Errors::FailedRequestError] error object
+      #
+      def call(request:, response:)
+        http_response = response.http_response
+        error_message = "#{http_response.code} #{http_response.message}"
+        error_class = find_error_class(http_response)
+
+        error_class.new(error_message, response: response, request: request)
+      end
+
+      private
+
+      def find_error_class(http_response)
+        found_class = RESPONSE_ERROR_MAP.keys.find { |http_error_class| http_response.is_a?(http_error_class) }
+        found_class ? RESPONSE_ERROR_MAP[found_class] : Errors::FailedRequest
+      end
+    end
+  end
+end

data/lib/mailchimp-api/network_error_builder.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module MailchimpAPI
+  #
+  # Builds MailchimpAPI::Errors::NetowrkError error
+  #
+  class NetworkErrorBuilder
+    # List of possible Network errors
+    ERRORS = [
+      IOError,
+      Errno::ECONNABORTED,
+      Errno::ECONNREFUSED,
+      Errno::ECONNRESET,
+      Errno::EHOSTUNREACH,
+      Errno::EPIPE,
+      Errno::ETIMEDOUT,
+      OpenSSL::SSL::SSLError,
+      SocketError,
+      Timeout::Error # Net::OpenTimeout, Net::ReadTimeout
+    ].freeze
+
+    class << self
+      # Builds NetworkError instance
+      #
+      # @param request [Request] Original request
+      # @param error [StandardError] Original error
+      #
+      # @return [Errors::NetworkError] Built NetworkError
+      #
+      def call(request:, error:)
+        Errors::NetworkError.new(error.message, request: request, error: error)
+      end
+    end
+  end
+end

data/lib/mailchimp-api/request.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "json"
+
+module MailchimpAPI
+  class Request
+    attr_reader \
+      :init_http_method,
+      :init_base_url,
+      :init_path,
+      :init_query,
+      :init_body,
+      :init_headers,
+      :http_request
+
+    # rubocop:disable Metrics/ParameterLists, Metrics/MethodLength
+    def initialize(http_method, url:, path:, query: nil, body: nil, headers: nil)
+      @init_http_method = http_method
+      @init_url = url
+      @init_path = path
+      @init_query = query
+      @init_body = body
+      @init_headers = headers
+
+      uri = prepare_uri(url, path, query)
+      headers = prepare_headers(headers)
+      body = prepare_body(body)
+      http_method = prepare_http_method(http_method, headers)
+
+      @http_request = build_http_request(http_method, uri: uri, body: body, headers: headers)
+    end
+    # rubocop:enable Metrics/ParameterLists, Metrics/MethodLength
+
+    # @return [String] HTTP request method name
+    def method
+      http_request.method # "GET", "POST", "PUT", "PATCH", "DELETE"
+    end
+
+    # @return [String] HTTP request full path
+    def path
+      http_request.path
+    end
+
+    # @return [URI] HTTP request URI
+    def uri
+      http_request.uri
+    end
+
+    # @return [String, nil] HTTP request body
+    def body
+      http_request.body
+    end
+
+    # @return [Hash] HTTP request query params
+    def query
+      @query ||= uri.query ? URI.decode_www_form(uri.query).to_h.transform_keys!(&:to_sym) : {}
+    end
+
+    # @return [Hash] HTTP request headers
+    def headers
+      http_request.each_header.to_h
+    end
+
+    private
+
+    def build_http_request(http_method, uri:, body:, headers:)
+      http_request = http_method.new(uri, "accept-encoding" => nil, "content-type" => "application/json")
+
+      headers.each { |key, value| http_request[key] = value }
+      http_request.body = body
+
+      http_request
+    end
+
+    def prepare_uri(url, path, query)
+      URIBuilder.call(url: url, path: path, query: query)
+    end
+
+    def prepare_headers(headers)
+      return {} unless headers
+
+      headers.transform_keys { |key| key.to_s.downcase }
+    end
+
+    def prepare_body(body)
+      JSON.dump(body) unless body.nil?
+    end
+
+    def prepare_http_method(default_http_method, headers)
+      headers["x-http-method-override"] ? Net::HTTP::Post : default_http_method
+    end
+  end
+end

data/lib/mailchimp-api/request_executor.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module MailchimpAPI
+  class RequestExecutor
+    attr_reader :request, :http_opts, :retries
+
+    def initialize(request, http_opts: {}, retries: {})
+      @request = request
+      @http_opts = http_opts
+      @retries = retries
+    end
+
+    #
+    # @return [Response] Response
+    #
+    def call
+      response = execute_request
+      raise FailedRequestErrorBuilder.call(request: request, response: response) if response.failed?
+
+      response
+    end
+
+    private
+
+    def execute_request(retry_number: 0)
+      response = execute_net_http_request
+    rescue => error
+      unknown_network_error?(error) ? handle_unknown_error(error) : handle_network_error(error, retry_number)
+    else
+      response.success? ? response : handle_failed_response(response, retry_number)
+    end
+
+    def handle_network_error(error, retry_number)
+      will_retry = retries[:enabled] && !retries_limit_reached?(retry_number)
+      raise NetworkErrorBuilder.call(request: request, error: error) unless will_retry
+
+      retry_request(retry_number)
+    end
+
+    def handle_failed_response(response, retry_number)
+      will_retry = retries[:enabled] && retryable?(response, retry_number)
+      will_retry ? retry_request(retry_number) : response
+    end
+
+    def execute_net_http_request
+      uri = request.uri
+
+      http_response =
+        Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, **http_opts) do |http|
+          http.max_retries = 0 # we have custom retries logic
+          http.request(request.http_request)
+        end
+
+      Response.new(http_response, request: request)
+    end
+
+    def retry_request(current_retry_number)
+      sleep_time = retry_sleep_seconds(current_retry_number)
+      sleep(sleep_time) if sleep_time.positive?
+      execute_request(retry_number: current_retry_number + 1)
+    end
+
+    def retries_limit_reached?(retry_number)
+      retry_number >= retries[:count]
+    end
+
+    def retry_sleep_seconds(current_retry_number)
+      seconds_per_retry = retries[:sleep]
+      seconds_per_retry[current_retry_number] || seconds_per_retry.last || 1
+    end
+
+    def retryable?(response, retry_number)
+      response.failed? && response.retryable? && !retries_limit_reached?(retry_number)
+    end
+
+    def unknown_network_error?(error)
+      NetworkErrorBuilder::ERRORS.none? { |network_error_class| error.is_a?(network_error_class) }
+    end
+
+    def handle_unknown_error(error)
+      raise error
+    end
+  end
+end

data/lib/mailchimp-api/resource.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module MailchimpAPI
+  class Resource
+    # @return current client
+    attr_reader :client
+
+    # Initializes Resource
+    #
+    # @param client [Client] current client
+    #
+    # @return [Collection] APIs collection
+    #
+    def initialize(client)
+      @client = client
+    end
+
+    # @return global client
+    def self.client
+      MailchimpAPI.client
+    end
+  end
+end

data/lib/mailchimp-api/resources/audience/member_tags.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module MailchimpAPI
+  module Audience
+    class MemberTags < Resource
+      module APIs
+        def list(audience_id, email, query: nil, body: nil, headers: nil)
+          path = "/lists/#{audience_id}/members/#{subscriber_hash(email)}/tags"
+          client.get(path, query: query, body: body, headers: headers)
+        end
+
+        def create(audience_id, email, query: nil, body: nil, headers: nil)
+          path = "/lists/#{audience_id}/members/#{subscriber_hash(email)}/tags"
+          client.post(path, query: query, body: body, headers: headers)
+        end
+      end
+
+      include MailchimpAPI::Audience::Utils
+      extend MailchimpAPI::Audience::Utils
+      include APIs
+      extend APIs
+    end
+  end
+end

data/lib/mailchimp-api/resources/audience/members.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module MailchimpAPI
+  module Audience
+    class Members < Resource
+      module APIs
+        def list(audience_id, query: nil, body: nil, headers: nil)
+          path = "/lists/#{audience_id}/members"
+          client.get(path, query: query, body: body, headers: headers)
+        end
+
+        def create(audience_id, query: nil, body: nil, headers: nil)
+          path = "/lists/#{audience_id}/members"
+          client.post(path, query: query, body: body, headers: headers)
+        end
+
+        def show(audience_id, email, query: nil, body: nil, headers: nil)
+          path = "/lists/#{audience_id}/members/#{subscriber_hash(email)}"
+          client.get(path, query: query, body: body, headers: headers)
+        end
+
+        def archive(audience_id, email, query: nil, body: nil, headers: nil)
+          path = "/lists/#{audience_id}/members/#{subscriber_hash(email)}"
+          client.delete(path, query: query, body: body, headers: headers)
+        end
+
+        def update(audience_id, email, query: nil, body: nil, headers: nil)
+          path = "/lists/#{audience_id}/members/#{subscriber_hash(email)}"
+          client.patch(path, query: query, body: body, headers: headers)
+        end
+
+        def add_or_update(audience_id, email, query: nil, body: nil, headers: nil)
+          path = "/lists/#{audience_id}/members/#{subscriber_hash(email)}"
+          client.put(path, query: query, body: body, headers: headers)
+        end
+
+        def delete_permanent(audience_id, email, query: nil, body: nil, headers: nil)
+          path = "/lists/#{audience_id}/members/#{subscriber_hash(email)}/actions/delete-permanent"
+          client.post(path, query: query, body: body, headers: headers)
+        end
+      end
+
+      include MailchimpAPI::Audience::Utils
+      extend MailchimpAPI::Audience::Utils
+      include APIs
+      extend APIs
+    end
+  end
+end

data/lib/mailchimp-api/resources/audience/utils/subscriber_hash.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module MailchimpAPI
+  module Audience
+    module Utils
+      class SubscriberHash
+        def self.call(email)
+          Digest::MD5.hexdigest(email.downcase)
+        end
+      end
+
+      private
+
+      def subscriber_hash(email)
+        SubscriberHash.call(email)
+      end
+    end
+  end
+end

data/lib/mailchimp-api/response.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "json"
+
+module MailchimpAPI
+  #
+  # MailchimpAPI::Response object
+  #
+  class Response
+    # List of Net::HTTP responses that can be retried
+    RETRYABLE_RESPONSES = [
+      Net::HTTPServerError,    # 5xx
+      Net::HTTPTooManyRequests # 429
+    ].freeze
+
+    # @return [Net::HTTP::Response] Original Net::HTTP::Response object
+    attr_reader :http_response
+
+    # @return [Request] Request object
+    attr_reader :request
+
+    #
+    # Initializes Response object
+    #
+    # @param http_response [Net::HTTP::Response] original response
+    # @param request [Request] Request that generates this response
+    #
+    # @return [Response] Initialized Response object
+    #
+    def initialize(http_response, request:)
+      @request = request
+      @http_response = http_response
+      @http_status = nil
+      @http_headers = nil
+      @http_body = nil
+      @body = nil
+    end
+
+    # Parses JSON body if response body contains JSON or returns original
+    # http body string
+    #
+    # @return [Hash, String] Parsed response body (with symbolized keys)
+    def body
+      @body ||= json_response? ? parse_json(http_body) : http_body
+    end
+
+    # @return [Integer] HTTP status as Integer
+    def http_status
+      @http_status ||= http_response.code.to_i
+    end
+
+    # @return [Hash] HTTP headers as Hash
+    def http_headers
+      @http_headers ||= http_response.each_header.to_h
+    end
+
+    # @return [String] Original http body
+    def http_body
+      @http_body ||= http_response.body
+    end
+
+    # Takes specific key from body, returns nil if key not present in parsed body
+    def [](key)
+      body[key.to_sym] if body.is_a?(Hash)
+    end
+
+    # Fetches specific key from body, raises error if key not exists
+    def fetch(key)
+      data = body.is_a?(Hash) ? body : {}
+      data.fetch(key.to_sym)
+    end
+
+    # Checks http status code is 2xx
+    #
+    # @return [Boolean] Returns true if response has success status code (2xx)
+    def success?
+      http_response.is_a?(Net::HTTPSuccess)
+    end
+
+    # Checks http status code is not 2xx
+    #
+    # @return [Boolean] Returns true if response has not success status code
+    def failed?
+      !success?
+    end
+
+    # Checks if response status code is retriable (5xx, 409, 429)
+    # @api private
+    #
+    # @return [Boolean] Returns true if status code is retriable (5xx, 409, 429)
+    def retryable?
+      failed? && RETRYABLE_RESPONSES.any? { |retryable_class| http_response.is_a?(retryable_class) }
+    end
+
+    #
+    # Instance representation string. Default was overwritten to hide secrets
+    #
+    def inspect
+      "#<#{self.class.name} (#{http_response.code})>"
+    end
+
+    private
+
+    def json_response?
+      content_type = http_response["content-type"]
+      !content_type.nil? && content_type.include?("json")
+    end
+
+    def parse_json(json)
+      JSON.parse(json, symbolize_names: true)
+    rescue JSON::ParserError, TypeError
+      json
+    end
+  end
+end

data/lib/mailchimp-api/uri_builder.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module MailchimpAPI
+  class URIBuilder
+    class << self
+      def call(url:, path:, query:)
+        uri =
+          if path.start_with?("/")
+            call(url: url, path: path[1, path.size - 1], query: nil)
+          elsif path.start_with?("0", "1", "2", "3", "4", "5", "6", "7", "8", "9")
+            URI.join(url, "/" + path)
+          else
+            URI.join(url, path)
+          end
+
+        add_query_params(uri, query)
+        uri
+      end
+
+      private
+
+      def add_query_params(uri, query)
+        return if !query || query.empty?
+
+        # We should merge query params with uri query params to not remove them
+        uri_query_string = uri.query
+
+        if uri_query_string && !uri_query_string.empty?
+          old_query = URI.decode_www_form(uri_query_string).to_h
+          query = old_query.transform_keys!(&:to_sym).merge!(query.transform_keys(&:to_sym))
+        end
+
+        uri.query = URI.encode_www_form(query)
+      end
+    end
+  end
+end

data/lib/mailchimp-api/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module MailchimpAPI
+  # MailchimpAPI gem version
+  #
+  # @return [String] SemVer gem version
+  #
+  VERSION = File.read(File.join(File.dirname(__FILE__), "../../VERSION")).strip
+end

data/lib/mailchimp-api.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module MailchimpAPI
+  API_VERSION = "3.0"
+
+  class << self
+    extend Forwardable
+
+    attr_writer :client
+
+    # HTTP methods
+    def_delegators :@client,
+      :post,
+      :get,
+      :patch,
+      :put,
+      :delete
+
+    # Batch methods
+    def_delegators :@client,
+      :batch,
+      :batch_get_request,
+      :batch_post_request,
+      :batch_put_request,
+      :batch_patch_request,
+      :batch_delete_request
+
+    # Pagination methods
+    def_delegators :@client,
+      :each_page,
+      :each_page_item,
+      :next_page
+
+    # Resources
+    def_delegators :@client,
+      :audience_members,
+      :audience_member_tags
+
+    def client
+      raise "#{name}.client must be set" unless @client
+
+      @client
+    end
+  end
+end
+
+require_relative "mailchimp-api/resource"
+require_relative "mailchimp-api/resources/audience/utils/subscriber_hash"
+require_relative "mailchimp-api/resources/audience/member_tags"
+require_relative "mailchimp-api/resources/audience/members"
+require_relative "mailchimp-api/batch_request"
+require_relative "mailchimp-api/client/api_methods"
+require_relative "mailchimp-api/client/batch_methods"
+require_relative "mailchimp-api/client/pagination_methods"
+require_relative "mailchimp-api/client"
+require_relative "mailchimp-api/config"
+require_relative "mailchimp-api/error"
+require_relative "mailchimp-api/failed_request_error_builder"
+require_relative "mailchimp-api/network_error_builder"
+require_relative "mailchimp-api/request"
+require_relative "mailchimp-api/request_executor"
+require_relative "mailchimp-api/response"
+require_relative "mailchimp-api/uri_builder"

data/lib/mailchimp-rest-api.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "mailchimp-api"

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: mailchimp-rest-api
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Andrey Glushkov
+bindir: bin
+cert_chain: []
+date: 2025-04-28 00:00:00.000000000 Z
+dependencies: []
+description: Marketing Mailchimp REST API with no dependencies.
+email:
+- aglushkov@shakuro.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- VERSION
+- lib/mailchimp-api.rb
+- lib/mailchimp-api/batch_request.rb
+- lib/mailchimp-api/client.rb
+- lib/mailchimp-api/client/api_methods.rb
+- lib/mailchimp-api/client/batch_methods.rb
+- lib/mailchimp-api/client/pagination_methods.rb
+- lib/mailchimp-api/config.rb
+- lib/mailchimp-api/error.rb
+- lib/mailchimp-api/failed_request_error_builder.rb
+- lib/mailchimp-api/network_error_builder.rb
+- lib/mailchimp-api/request.rb
+- lib/mailchimp-api/request_executor.rb
+- lib/mailchimp-api/resource.rb
+- lib/mailchimp-api/resources/audience/member_tags.rb
+- lib/mailchimp-api/resources/audience/members.rb
+- lib/mailchimp-api/resources/audience/utils/subscriber_hash.rb
+- lib/mailchimp-api/response.rb
+- lib/mailchimp-api/uri_builder.rb
+- lib/mailchimp-api/version.rb
+- lib/mailchimp-rest-api.rb
+homepage: https://github.com/aglushkov/mailchimp-rest-api
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/aglushkov/mailchimp-rest-api
+  documentation_uri: https://www.rubydoc.info/gems/mailchimp-rest-api
+  changelog_uri: https://github.com/aglushkov/mailchimp-rest-api/blob/master/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Mailchimp REST API (Marketing)
+test_files: []