mailchimp-rest-api 0.3.0 → 0.4.1

data/lib/mailchimp-api/client.rb

@@ -1,14 +1,22 @@
 # frozen_string_literal: true
 
 module MailchimpAPI
+  # Client class for interacting with the Mailchimp REST API
+  # @api public
   class Client
+    # Current API version
     API_VERSION = MailchimpAPI::API_VERSION
 
     include APIMethods
     include BatchMethods
 
-    attr_reader :api_key, :api_url, :api_version, :authorization_token, :config
-
+    # Initializes a new Mailchimp API client
+    # @param api_key [String] Mailchimp API key in format <token>-<dc>
+    # @param http_opts [Hash] Optional HTTP client configuration
+    # @param retries [Integer] Number of retries for failed requests
+    # @raise [ArgumentError] if api_key is invalid
+    # @example
+    #   client = MailchimpAPI::Client.new(api_key: "your-api-key-here")
     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
@@ -19,28 +27,78 @@ module MailchimpAPI
       @config = Config.new(http_opts: http_opts, retries: retries)
     end
 
+    # Sends a POST request to the Mailchimp API
+    # @param path [String] API endpoint path
+    # @param query [Hash] Optional query parameters
+    # @param body [Hash] Optional request body
+    # @param headers [Hash] Optional request headers
+    # @return [Response] API response
+    # @example
+    #   client.post("/lists", body: { name: "New List" })
     def post(path, query: nil, body: nil, headers: nil)
       execute(Net::HTTP::Post, path, query: query, body: body, headers: headers)
     end
 
+    # Sends a GET request to the Mailchimp API
+    # @param path [String] API endpoint path
+    # @param query [Hash] Optional query parameters
+    # @param body [Hash] Optional request body
+    # @param headers [Hash] Optional request headers
+    # @return [Response] API response
+    # @example
+    #   client.get("/lists")
     def get(path, query: nil, body: nil, headers: nil)
       execute(Net::HTTP::Get, path, query: query, body: body, headers: headers)
     end
 
+    # Sends a PATCH request to the Mailchimp API
+    # @param path [String] API endpoint path
+    # @param query [Hash] Optional query parameters
+    # @param body [Hash] Optional request body
+    # @param headers [Hash] Optional request headers
+    # @return [Response] API response
+    # @example
+    #   client.patch("/lists/123", body: { name: "Updated List" })
     def patch(path, query: nil, body: nil, headers: nil)
       execute(Net::HTTP::Patch, path, query: query, body: body, headers: headers)
     end
 
+    # Sends a PUT request to the Mailchimp API
+    # @param path [String] API endpoint path
+    # @param query [Hash] Optional query parameters
+    # @param body [Hash] Optional request body
+    # @param headers [Hash] Optional request headers
+    # @return [Response] API response
+    # @example
+    #   client.put("/lists/123", body: { name: "Updated List" })
     def put(path, query: nil, body: nil, headers: nil)
       execute(Net::HTTP::Put, path, query: query, body: body, headers: headers)
     end
 
+    # Sends a DELETE request to the Mailchimp API
+    # @param path [String] API endpoint path
+    # @param query [Hash] Optional query parameters
+    # @param body [Hash] Optional request body
+    # @param headers [Hash] Optional request headers
+    # @return [Response] API response
+    # @example
+    #   client.delete("/lists/123")
     def delete(path, query: nil, body: nil, headers: nil)
       execute(Net::HTTP::Delete, path, query: query, body: body, headers: headers)
     end
 
     private
 
+    attr_reader :api_key
+
+    attr_reader :api_url
+
+    attr_reader :api_version
+
+    attr_reader :authorization_token
+
+    attr_reader :config
+
     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)

data/lib/mailchimp-api/config.rb

@@ -1,25 +1,31 @@
 # frozen_string_literal: true
 
 module MailchimpAPI
-  #
-  # Stores client requests configuration
-  #
+  # Internal class for storing and managing client configuration
+  # @api private
   class Config
-    # Default config options
+    # Default configuration options
+    # @return [Hash] Frozen hash containing default settings
     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
+    # @return [Hash] HTTP client configuration options
+    attr_reader :http_opts
 
-    # Initializes Config
-    #
-    # @param http_opts [Hash] Net::Http opts for all requests
-    # @param retries [Hash] Retries configuration
-    #
-    # @return [Client] Initialized config object
-    #
+    # @return [Hash] Retry configuration options
+    attr_reader :retries
+
+    # Creates a new configuration instance
+    # @param http_opts [Hash] Net::Http options for all requests
+    # @param retries [Hash] Retry configuration options
+    # @return [Config] Frozen configuration instance
+    # @example
+    #   config = MailchimpAPI::Config.new(
+    #     http_opts: { read_timeout: 30 },
+    #     retries: { count: 3 }
+    #   )
     def initialize(http_opts: nil, retries: {})
       @http_opts = http_opts.dup.freeze || DEFAULTS[:http_opts]
       @retries = DEFAULTS[:retries].merge(retries || {}).freeze

data/lib/mailchimp-api/error.rb

@@ -1,9 +1,7 @@
 # frozen_string_literal: true
 
 module MailchimpAPI
-  #
-  # Common interface for all errors
-  #
+  # Base error class for all Mailchimp API errors
   class Error < StandardError
     # @return [Response, nil] Returned response with non-200 status code
     attr_reader :response
@@ -30,14 +28,21 @@ module MailchimpAPI
     attr_reader :error_fields
   end
 
-  #
-  # Namespace for specific MailchimpAPI errors
-  #
+  # Namespace for specific Mailchimp API errors
   module Errors
-    #
     # Raised when Mailchimp responds with any status code except 200, 201, 202, 204
-    #
     class FailedRequest < Error
+      # Initializes a new FailedRequest error
+      # @param message [String, nil] Error message
+      # @param request [Request] The request that failed
+      # @param response [Response] The response received from Mailchimp
+      # @example
+      #   begin
+      #     client.get("/lists/123")
+      #   rescue MailchimpAPI::Errors::FailedRequest => e
+      #     puts e.error_title # => "Resource Not Found"
+      #     puts e.error_detail # => "The requested resource could not be found."
+      #   end
       def initialize(message = nil, request:, response:)
         @request = request
         @response = response
@@ -56,11 +61,19 @@ module MailchimpAPI
       end
     end
 
-    #
-    # Raised when a network raised when executing the request
-    # List of network errors can be found in errors/network_error_builder.rb
-    #
+    # Raised when a network error occurs while executing the request
     class NetworkError < Error
+      # Initializes a new NetworkError
+      # @param message [String, nil] Error message
+      # @param request [Request] The request that failed
+      # @param error [Exception] The original network error
+      # @example
+      #   begin
+      #     client.get("/lists")
+      #   rescue MailchimpAPI::Errors::NetworkError => e
+      #     puts e.error_title # => "Net::OpenTimeout"
+      #     puts e.error_detail # => "execution expired"
+      #   end
       def initialize(message = nil, request:, error:)
         super(message)
         @request = request
@@ -75,43 +88,43 @@ module MailchimpAPI
       end
     end
 
-    # 400
+    # Raised when Mailchimp returns a 400 Bad Request status code
     class BadRequest < FailedRequest
     end
 
-    # 401
+    # Raised when Mailchimp returns a 401 Unauthorized status code
     class Unauthorized < FailedRequest
     end
 
-    # 403
+    # Raised when Mailchimp returns a 403 Forbidden status code
     class Forbidden < FailedRequest
     end
 
-    # 404
+    # Raised when Mailchimp returns a 404 Not Found status code
     class NotFound < FailedRequest
     end
 
-    # 405
+    # Raised when Mailchimp returns a 405 Method Not Allowed status code
     class MethodNotAllowed < FailedRequest
     end
 
-    # 414
+    # Raised when Mailchimp returns a 414 Request URI Too Long status code
     class RequestURITooLong < FailedRequest
     end
 
-    # 422
+    # Raised when Mailchimp returns a 422 Unprocessable Entity status code
     class UnprocessableEntity < FailedRequest
     end
 
-    # 426
+    # Raised when Mailchimp returns a 426 Upgrade Required status code
     class UpgradeRequired < FailedRequest
     end
 
-    # 429
+    # Raised when Mailchimp returns a 429 Too Many Requests status code
     class TooManyRequests < FailedRequest
     end
 
-    # 5xx
+    # Raised when Mailchimp returns a 5xx Server Error status code
     class ServerError < FailedRequest
     end
   end

data/lib/mailchimp-api/failed_request_error_builder.rb

@@ -3,11 +3,11 @@
 require "net/http"
 
 module MailchimpAPI
-  #
-  # Builds MailchimpAPI::FailedRequest error
-  #
+  # Internal class for building failed request error instances
+  # @api private
   class FailedRequestErrorBuilder
-    # Matchings for Net::HTTP response class to MailchimpAPI::Error class
+    # Maps HTTP response classes to corresponding Mailchimp API error classes
+    # @return [Hash] Mapping of Net::HTTP response classes to MailchimpAPI::Error classes
     RESPONSE_ERROR_MAP = {
       Net::HTTPBadRequest => Errors::BadRequest,                     # 400
       Net::HTTPUnauthorized => Errors::Unauthorized,                 # 401
@@ -22,13 +22,10 @@ module MailchimpAPI
     }.freeze
 
     class << self
-      # Builds FailedRequestError instance
-      #
-      # @param request [Request] Original request
-      # @param response [Response] Original response
-      #
-      # @return [Errors::FailedRequestError] error object
-      #
+      # Creates a new error instance based on the HTTP response
+      # @param request [Request] The original request that failed
+      # @param response [Response] The response containing the error
+      # @return [Errors::FailedRequest] Appropriate error instance
       def call(request:, response:)
         http_response = response.http_response
         error_message = "#{http_response.code} #{http_response.message}"
@@ -39,6 +36,9 @@ module MailchimpAPI
 
       private
 
+      # Determines the appropriate error class based on the HTTP response
+      # @param http_response [Net::HTTPResponse] The HTTP response
+      # @return [Class] The appropriate MailchimpAPI::Error class
       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

data/lib/mailchimp-api/network_error_builder.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
 module MailchimpAPI
-  #
-  # Builds MailchimpAPI::Errors::NetowrkError error
-  #
+  # Internal class for building network error instances
+  # @api private
   class NetworkErrorBuilder
-    # List of possible Network errors
+    # List of network-related error classes that should be wrapped in NetworkError
+    # @return [Array<Class>] Array of error classes that indicate network issues
     ERRORS = [
       IOError,
       Errno::ECONNABORTED,
@@ -20,13 +20,10 @@ module MailchimpAPI
     ].freeze
 
     class << self
-      # Builds NetworkError instance
-      #
-      # @param request [Request] Original request
-      # @param error [StandardError] Original error
-      #
-      # @return [Errors::NetworkError] Built NetworkError
-      #
+      # Creates a new network error instance
+      # @param request [Request] The original request that failed
+      # @param error [StandardError] The original network error
+      # @return [Errors::NetworkError] Wrapped network error instance
       def call(request:, error:)
         Errors::NetworkError.new(error.message, request: request, error: error)
       end

data/lib/mailchimp-api/pagination/list_each_item_helper.rb

@@ -1,10 +1,22 @@
 # frozen_string_literal: true
 
 module MailchimpAPI
+  # Namespace for methods related to pagination
+  # @api private
   module Pagination
+    # Internal module for handling pagination of list items
+    # @api private
     module ListEachItemHelper
       private
 
+      # Iterates through all items in a paginated list
+      # @param items_field [Symbol] The field name containing the items in the response
+      # @param args [Array] Arguments to pass to the list method
+      # @param query [Hash] Query parameters
+      # @param body [Hash] Request body
+      # @param headers [Hash] Request headers
+      # @yield [Hash] Each item from the list
+      # @return [Enumerator] If no block given
       def list_each_item(items_field, *args, query: nil, body: nil, headers: nil, &block)
         return enum_for(:list_each_item, items_field, *args, query: query, body: body, headers: headers) unless block
 

data/lib/mailchimp-api/pagination/prepare_query_params.rb

@@ -2,8 +2,14 @@
 
 module MailchimpAPI
   module Pagination
+    # Internal class for preparing query parameters for paginated requests
+    # @api private
     class PrepareQueryParams
       class << self
+        # Prepares query parameters for paginated requests
+        # @param query [Hash] Original query parameters
+        # @param items_field [Symbol] Field name containing the items
+        # @return [Hash] Prepared query parameters
         def call(query, items_field:)
           query ||= {}
           query = query.transform_keys(&:to_sym)
@@ -11,8 +17,8 @@ module MailchimpAPI
           prepare_offset(query)
           prepare_count(query)
 
-          ensure_fields_included(query, items_field: items_field, total_field: "total_items")
-          ensure_fields_not_excluded(query, items_field: items_field, total_field: "total_items")
+          ensure_fields_included(query, items_field: items_field.to_s, total_field: "total_items")
+          ensure_fields_not_excluded(query, items_field: items_field.to_s, total_field: "total_items")
           query
         end
 
@@ -29,7 +35,14 @@ module MailchimpAPI
 
         def ensure_fields_included(query, items_field:, total_field:)
           fields = query[:fields] || ""
-          query[:fields] = (fields.split(",") + [items_field.to_s, total_field]).uniq.join(",")
+          fields_list = fields.split(",")
+
+          has_items_field = fields_list.any? { |field| field.start_with?("#{items_field}.") }
+          has_total_field = fields_list.include?(total_field)
+
+          fields_list.push(items_field) unless has_items_field
+          fields_list.push(total_field) unless has_total_field
+          query[:fields] = fields_list.uniq.join(",")
         end
 
         def ensure_fields_not_excluded(query, items_field:, total_field:)

data/lib/mailchimp-api/request.rb

@@ -3,7 +3,16 @@
 require "json"
 
 module MailchimpAPI
+  # Request class for handling Mailchimp API requests
+  # @api public
   class Request
+    # @return [Net::HTTP::Request] The HTTP request object
+    # @return [String] The initial HTTP method
+    # @return [String] The initial base URL
+    # @return [String] The initial path
+    # @return [Hash] The initial query parameters
+    # @return [Hash] The initial request body
+    # @return [Hash] The initial request headers
     attr_reader \
       :init_http_method,
       :init_base_url,
@@ -13,7 +22,20 @@ module MailchimpAPI
       :init_headers,
       :http_request
 
-    # rubocop:disable Metrics/ParameterLists, Metrics/MethodLength
+    # Initializes a new API request
+    # @param http_method [Net::HTTP::Request] HTTP method class
+    # @param url [String] Base URL for the request
+    # @param path [String] API endpoint path
+    # @param query [Hash] Optional query parameters
+    # @param body [Hash] Optional request body
+    # @param headers [Hash] Optional request headers
+    # @example
+    #   request = MailchimpAPI::Request.new(
+    #     Net::HTTP::Get,
+    #     url: "https://us1.api.mailchimp.com/3.0/",
+    #     path: "/lists",
+    #     query: { count: 10 }
+    #   )
     def initialize(http_method, url:, path:, query: nil, body: nil, headers: nil)
       @init_http_method = http_method
       @init_url = url
@@ -29,40 +51,52 @@ module MailchimpAPI
 
       @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
+    # @example
+    #   request.method # => "GET"
     def method
       http_request.method # "GET", "POST", "PUT", "PATCH", "DELETE"
     end
 
     # @return [String] HTTP request full path
+    # @example
+    #   request.path # => "/lists?count=10"
     def path
       http_request.path
     end
 
     # @return [URI] HTTP request URI
+    # @example
+    #   request.uri # => #<URI::HTTPS https://us1.api.mailchimp.com/3.0/lists?count=10>
     def uri
       http_request.uri
     end
 
     # @return [String, nil] HTTP request body
+    # @example
+    #   request.body # => '{"name":"New List"}'
     def body
       http_request.body
     end
 
     # @return [Hash] HTTP request query params
+    # @example
+    #   request.query # => { count: 10 }
     def query
       @query ||= uri.query ? URI.decode_www_form(uri.query).to_h.transform_keys!(&:to_sym) : {}
     end
 
     # @return [Hash] HTTP request headers
+    # @example
+    #   request.headers # => { "content-type" => "application/json" }
     def headers
       http_request.each_header.to_h
     end
 
     private
 
+    # @api private
     def build_http_request(http_method, uri:, body:, headers:)
       http_request = http_method.new(uri, "accept-encoding" => nil, "content-type" => "application/json")
 
@@ -72,20 +106,24 @@ module MailchimpAPI
       http_request
     end
 
+    # @api private
     def prepare_uri(url, path, query)
       URIBuilder.call(url: url, path: path, query: query)
     end
 
+    # @api private
     def prepare_headers(headers)
       return {} unless headers
 
       headers.transform_keys { |key| key.to_s.downcase }
     end
 
+    # @api private
     def prepare_body(body)
       JSON.dump(body) unless body.nil?
     end
 
+    # @api private
     def prepare_http_method(default_http_method, headers)
       headers["x-http-method-override"] ? Net::HTTP::Post : default_http_method
     end

data/lib/mailchimp-api/request_executor.rb

@@ -1,18 +1,32 @@
 # frozen_string_literal: true
 
 module MailchimpAPI
+  # Internal class for executing HTTP requests with retry logic
+  # @api private
   class RequestExecutor
-    attr_reader :request, :http_opts, :retries
+    # @return [Request] The request to be executed
+    attr_reader :request
 
+    # @return [Hash] HTTP client configuration options
+    attr_reader :http_opts
+
+    # @return [Hash] Retry configuration options
+    attr_reader :retries
+
+    # Creates a new request executor
+    # @param request [Request] The request to execute
+    # @param http_opts [Hash] HTTP client configuration options
+    # @param retries [Hash] Retry configuration options
     def initialize(request, http_opts: {}, retries: {})
       @request = request
       @http_opts = http_opts
       @retries = retries
     end
 
-    #
-    # @return [Response] Response
-    #
+    # Executes the request with retry logic
+    # @return [Response] The response from the API
+    # @raise [Errors::FailedRequest] If the request fails and cannot be retried
+    # @raise [Errors::NetworkError] If a network error occurs and cannot be retried
     def call
       response = execute_request
       raise FailedRequestErrorBuilder.call(request: request, response: response) if response.failed?

data/lib/mailchimp-api/resource.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module MailchimpAPI
+  # Base class for all REST APIs collections
+  # @api private
   class Resource
     # @return current client
     attr_reader :client

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

@@ -2,35 +2,98 @@
 
 module MailchimpAPI
   module Audience
+    # Provides methods for interacting with Mailchimp interest categories
+    # Interest categories help organize groups of interests that subscribers can opt into
     class InterestCategories < Resource
+      # Module with endpoints for InterestCategories
       module APIs
         include Pagination::ListEachItemHelper
 
+        # List all interest categories for a specific list
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Optional request body
+        # @param headers [Hash] Optional request headers
+        # @return [Hash] API response containing interest categories
+        # @example Get all interest categories for a list
+        #   interest_categories.list('list123')
         def list(list_id, query: nil, body: nil, headers: nil)
           path = "/lists/#{list_id}/interest-categories"
           client.get(path, query: query, body: body, headers: headers)
         end
 
+        # Create a new interest category
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Interest category attributes
+        # @option body [String] :title The title of the interest category
+        # @option body [String] :type The type of interest category (checkboxes, dropdown, radio, hidden)
+        # @param headers [Hash] Optional request headers
+        # @return [Hash] API response containing the created interest category
+        # @example Create a checkbox interest category
+        #   interest_categories.create('list123', body: {
+        #     title: 'Favorite Products',
+        #     type: 'checkboxes'
+        #   })
         def create(list_id, query: nil, body: nil, headers: nil)
           path = "/lists/#{list_id}/interest-categories"
           client.post(path, query: query, body: body, headers: headers)
         end
 
+        # Show details for a specific interest category
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param interest_category_id [String] The ID of the interest category
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Optional request body
+        # @param headers [Hash] Optional request headers
+        # @return [Hash] API response containing interest category details
+        # @example Get details for an interest category
+        #   interest_categories.show('list123', 'category456')
         def show(list_id, interest_category_id, query: nil, body: nil, headers: nil)
           path = "/lists/#{list_id}/interest-categories/#{interest_category_id}"
           client.get(path, query: query, body: body, headers: headers)
         end
 
+        # Delete an interest category
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param interest_category_id [String] The ID of the interest category to delete
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Optional request body
+        # @param headers [Hash] Optional request headers
+        # @return [Boolean] True if successful
+        # @example Delete an interest category
+        #   interest_categories.delete('list123', 'category456')
         def delete(list_id, interest_category_id, query: nil, body: nil, headers: nil)
           path = "/lists/#{list_id}/interest-categories/#{interest_category_id}"
           client.delete(path, query: query, body: body, headers: headers)
         end
 
+        # Update an interest category
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param interest_category_id [String] The ID of the interest category to update
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Updated interest category attributes
+        # @param headers [Hash] Optional request headers
+        # @return [Hash] API response containing updated interest category
+        # @example Update an interest category title
+        #   interest_categories.update('list123', 'category456', body: {
+        #     title: 'Updated Category Name'
+        #   })
         def update(list_id, interest_category_id, query: nil, body: nil, headers: nil)
           path = "/lists/#{list_id}/interest-categories/#{interest_category_id}"
           client.patch(path, query: query, body: body, headers: headers)
         end
 
+        # Iterate through all interest categories for a list
+        # @param list_id [String] The ID of the Mailchimp list
+        # @param query [Hash] Optional query parameters
+        # @param body [Hash] Optional request body
+        # @param headers [Hash] Optional request headers
+        # @yield [Hash] Each interest category
+        # @example Iterate through interest categories
+        #   interest_categories.each('list123') do |category|
+        #     puts category[:title]
+        #   end
         def each(list_id, query: nil, body: nil, headers: nil, &block)
           list_each_item(:categories, list_id, query: query, body: body, headers: headers, &block)
         end