mailchimp-rest-api 0.3.0 → 0.4.1

data/lib/mailchimp-api/response.rb

@@ -3,9 +3,8 @@
 require "json"
 
 module MailchimpAPI
-  #
-  # MailchimpAPI::Response object
-  #
+  # Response class for handling Mailchimp API responses
+  # @api public
   class Response
     # List of Net::HTTP responses that can be retried
     RETRYABLE_RESPONSES = [
@@ -19,14 +18,12 @@ module MailchimpAPI
     # @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
-    #
+    # @example
+    #   response = MailchimpAPI::Response.new(http_response, request: request)
     def initialize(http_response, request:)
       @request = request
       @http_response = http_response
@@ -38,74 +35,94 @@ module MailchimpAPI
 
     # Parses JSON body if response body contains JSON or returns original
     # http body string
-    #
     # @return [Hash, String] Parsed response body (with symbolized keys)
+    # @example
+    #   response.body # => { id: "123", name: "Example List" }
     def body
       @body ||= json_response? ? parse_json(http_body) : http_body
     end
 
     # @return [Integer] HTTP status as Integer
+    # @example
+    #   response.http_status # => 200
     def http_status
       @http_status ||= http_response.code.to_i
     end
 
     # @return [Hash] HTTP headers as Hash
+    # @example
+    #   response.http_headers # => { "content-type" => "application/json" }
     def http_headers
       @http_headers ||= http_response.each_header.to_h
     end
 
     # @return [String] Original http body
+    # @example
+    #   response.http_body # => '{"id":"123","name":"Example List"}'
     def http_body
       @http_body ||= http_response.body
     end
 
     # Takes specific key from body, returns nil if key not present in parsed body
+    # @param key [String, Symbol] Key to fetch from response body
+    # @return [Object, nil] Value for the given key or nil if not found
+    # @example
+    #   response[:id] # => "123"
     def [](key)
       body[key.to_sym] if body.is_a?(Hash)
     end
 
     # Fetches specific key from body, raises error if key not exists
+    # @param key [String, Symbol] Key to fetch from response body
+    # @return [Object] Value for the given key
+    # @raise [KeyError] if key is not found in response body
+    # @example
+    #   response.fetch(:id) # => "123"
     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)
+    # @example
+    #   response.success? # => true
     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
+    # @example
+    #   response.failed? # => false
     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
-    #
+    # @return [String] String representation of the response
+    # @example
+    #   response.inspect # => "#<MailchimpAPI::Response (200)>"
     def inspect
       "#<#{self.class.name} (#{http_response.code})>"
     end
 
     private
 
+    # @api private
     def json_response?
       content_type = http_response["content-type"]
       !content_type.nil? && content_type.include?("json")
     end
 
+    # @api private
     def parse_json(json)
       JSON.parse(json, symbolize_names: true)
     rescue JSON::ParserError, TypeError

data/lib/mailchimp-api/uri_builder.rb

@@ -1,8 +1,21 @@
 # frozen_string_literal: true
 
 module MailchimpAPI
+  # Internal class for building and manipulating URIs
+  # @api private
   class URIBuilder
     class << self
+      # Builds a URI from base URL, path, and query parameters
+      # @param url [String] Base URL
+      # @param path [String] Path to append to URL
+      # @param query [Hash, nil] Optional query parameters
+      # @return [URI] Built URI with query parameters
+      # @example
+      #   URIBuilder.call(
+      #     url: "https://api.mailchimp.com/3.0",
+      #     path: "lists",
+      #     query: { count: 10 }
+      #   )
       def call(url:, path:, query:)
         uri =
           if path.start_with?("/")

data/lib/mailchimp-api.rb

@@ -2,45 +2,152 @@
 
 require "forwardable"
 
+# Main module for the Mailchimp REST API client
+# @api public
 module MailchimpAPI
+  # Current Mailchimp API version
   API_VERSION = "3.0"
 
   class << self
     extend Forwardable
 
+    # @!attribute [w] client
+    # Sets the client instance for the MailchimpAPI module
+    # @param value [Client] the client instance to set
     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_interest_categories,
-      :audience_interests,
-      :audience_member_tags,
-      :audience_members,
-      :audience_webhooks
+    # @!group HTTP Methods
 
+    # @!method post
+    # Delegates POST requests to the client
+    # @return [Response] API response
+    # @see Client#post
+    def_delegators :@client, :post
+
+    # @!method get
+    # Delegates GET requests to the client
+    # @return [Response] API response
+    # @see Client#get
+    def_delegators :@client, :get
+
+    # @!method patch
+    # Delegates PATCH requests to the client
+    # @return [Response] API response
+    # @see Client#patch
+    def_delegators :@client, :patch
+
+    # @!method put
+    # Delegates PUT requests to the client
+    # @return [Response] API response
+    # @see Client#put
+    def_delegators :@client, :put
+
+    # @!method delete
+    # Delegates DELETE requests to the client
+    # @return [Response] API response
+    # @see Client#delete
+    def_delegators :@client, :delete
+
+    # @!endgroup
+
+    # @!group Batch Methods
+
+    # @!method batch
+    # Sends batch request
+    # @return [Response] API response
+    # @see Client#batch
+    def_delegators :@client, :batch
+
+    # @!method batch_get_request
+    # Prepares a GET request for batch operation
+    # @return [BatchRequest] batch request instance
+    # @see Client#batch_get_request
+    def_delegators :@client, :batch_get_request
+
+    # @!method batch_post_request
+    # Prepares a POST request for batch operation
+    # @return [BatchRequest] batch request instance
+    # @see Client#batch_post_request
+    def_delegators :@client, :batch_post_request
+
+    # @!method batch_put_request
+    # Prepares a PUT request for batch operation
+    # @return [BatchRequest] batch request instance
+    # @see Client#batch_put_request
+    def_delegators :@client, :batch_put_request
+
+    # @!method batch_patch_request
+    # Prepares a PATCH request for batch operation
+    # @return [BatchRequest] batch request instance
+    # @see Client#batch_patch_request
+    def_delegators :@client, :batch_patch_request
+
+    # @!method batch_delete_request
+    # Prepares a DELETE request for batch operation
+    # @return [BatchRequest] batch request instance
+    # @see Client#batch_delete_request
+    def_delegators :@client, :batch_delete_request
+
+    # @!endgroup
+
+    # @!group API Resources
+
+    # @!method audience_interest_categories
+    # Builds audience interest categories API resource
+    # @return [Audience::InterestCategories]
+    #   the interest categories APIs collection
+    # @see Audience::InterestCategories#audience_interest_categories
+    def_delegators :@client, :audience_interest_categories
+
+    # @!method audience_interests
+    # Builds audience interests API resource
+    # @return [Audience::Interests]
+    #   the interests APIs collection
+    # @see Audience::Interests#audience_interests
+    def_delegators :@client, :audience_interests
+
+    # @!method audience_member_tags
+    # Builds audience member tags API resource
+    # @return [Audience::MemberTags]
+    #   the member tags APIs collection
+    # @see Audience::MemberTags#audience_member_tags
+    def_delegators :@client, :audience_member_tags
+
+    # @!method audience_members
+    # Builds audience members API resource
+    # @return [Audience::Members]
+    #   the members APIs collection
+    # @see Audience::Members#audience_members
+    def_delegators :@client, :audience_members
+
+    # @!method audience_segment_members
+    # Builds audience segment members API resource
+    # @return [Audience::SegmentMembers]
+    #   the segment members APIs collection
+    # @see Audience::SegmentMembers#audience_segment_members
+    def_delegators :@client, :audience_segment_members
+
+    # @!method audience_segments
+    # Builds audience segments API resource
+    # @return [Audience::Segments]
+    #   the segments APIs collection
+    # @see Audience::Segments#audience_segments
+    def_delegators :@client, :audience_segments
+
+    # @!method audience_webhooks
+    # Builds audience webhooks API resource
+    # @return [Audience::Webhooks]
+    #   the webhooks APIs collection
+    # @see Audience::Webhooks#audience_webhooks
+    def_delegators :@client, :audience_webhooks
+
+    # @!endgroup
+
+    # Returns the configured client instance
+    # @raise [RuntimeError] if client is not configured
+    # @return [Client] the configured client instance
+    # @example
+    #   MailchimpAPI.client # => #<MailchimpAPI::Client>
     def client
       raise "#{name}.client must be set" unless @client
 
@@ -58,6 +165,8 @@ require_relative "mailchimp-api/resources/audience/interests"
 require_relative "mailchimp-api/resources/audience/member_tags"
 require_relative "mailchimp-api/resources/audience/members"
 require_relative "mailchimp-api/resources/audience/webhooks"
+require_relative "mailchimp-api/resources/audience/segments"
+require_relative "mailchimp-api/resources/audience/segment_members"
 require_relative "mailchimp-api/batch_request"
 require_relative "mailchimp-api/client/api_methods"
 require_relative "mailchimp-api/client/batch_methods"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mailchimp-rest-api
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Andrey Glushkov
@@ -36,6 +36,8 @@ files:
 - lib/mailchimp-api/resources/audience/interests.rb
 - lib/mailchimp-api/resources/audience/member_tags.rb
 - lib/mailchimp-api/resources/audience/members.rb
+- lib/mailchimp-api/resources/audience/segment_members.rb
+- lib/mailchimp-api/resources/audience/segments.rb
 - lib/mailchimp-api/resources/audience/utils/subscriber_hash.rb
 - lib/mailchimp-api/resources/audience/webhooks.rb
 - lib/mailchimp-api/response.rb
@@ -46,9 +48,11 @@ homepage: https://github.com/andreyruby/mailchimp-rest-api
 licenses:
 - MIT
 metadata:
-  source_code_uri: https://github.com/andreyruby/mailchimp-rest-api
-  documentation_uri: https://www.rubydoc.info/gems/mailchimp-rest-api
-  changelog_uri: https://github.com/andreyruby/mailchimp-rest-api/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/andreyruby/mailchimp-rest-api/issues
+  changelog_uri: https://github.com/andreyruby/mailchimp-rest-api/CHANGELOG.md
+  documentation_uri: https://github.com/andreyruby/mailchimp-rest-api/README.md
+  homepage_uri: https://github.com/andreyruby/mailchimp-rest-api
+  source_code_uri: https://github.com/andreyruby/mailchimp-rest-api/tree/v0.4.1
 rdoc_options: []
 require_paths:
 - lib