mailchimp-rest-api 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e12dd5f9138dd42df18a44d79b07a9d7d280a8c09694a64e5c9e7963dd6d992
-  data.tar.gz: 7fd21428cd4d12c5881e2eea7bc4c3a045742bfd9120b01cf1a62704e834b814
+  metadata.gz: 428009c6c680a7c4bc6ec3b80fe5e4c1485df70e358928655fefabbf0b76637c
+  data.tar.gz: bd8307d56a558d64a4d7a7551a21cacf9dfe1e44036882191421c359c1b2682a
 SHA512:
-  metadata.gz: 4fdebf9fbf90a37a171ec67d64c3ff8c53361cf4bc0d90a22649ddb14f962e76f4f4742ef7ac16b6bdbcc8be49677557f3debe8a2f6dd229101d58641ec9a993
-  data.tar.gz: 948ee7442f8a69395c4d1743cb4b91140f32820f96d4bf4709e4c625699bc551092cc2648700540c5e26418f5f05a0523957b90baa8e5d1d45daeec138544906
+  metadata.gz: c3f2cc4b7561902a8ba1991b8acb68be65714a506854adea22cd3d0f1a7fa449aae6cea82267cb55d4b45a9ea7f11f6c4ba41b5e602d8a75ecb6f6f4df8a3102
+  data.tar.gz: f4bb0e6175805b8363ed59df417c4f103ee6b70c5bc40dd6003e7f8ac7eaef3ac5ac992a251b055d224981ab6142f9c460e2a0924ce7691bfbf0cc560e922f7f

data/README.md

@@ -60,6 +60,52 @@ MailchimpAPI.audience_members.create(audience_id, body: body)
 - `response.success?` - checks HTTP status code is 2xx
 - `response.failed?` - checks HTTP status code is not 2xx
 
+## Errors
+
+All error classes inherit from `MailchimpAPI::Error` and provide:
+
+- `error_type` - Error type returned by Mailchimp
+- `error_title` - Error title or response error class name
+- `error_status` - Error status or HTTP status
+- `error_detail` - Error description from Mailchimp
+- `error_fields` - Field-specific errors
+- `error_instance` - Error ID from Mailchimp
+- `response` - Response object
+- `request` - Request object
+
+MailchimpAPI provides specific error classes for different types of errors:
+
+### Network Errors
+
+- `MailchimpAPI::Errors::NetworkError` - Raised when a network error occurs
+  during request execution
+
+### HTTP Status Code Errors
+
+- `MailchimpAPI::Errors::BadRequest` (400) - Invalid request parameters
+- `MailchimpAPI::Errors::Unauthorized` (401) - Invalid API key
+- `MailchimpAPI::Errors::Forbidden` (403) - Insufficient permissions
+- `MailchimpAPI::Errors::NotFound` (404) - Resource not found
+- `MailchimpAPI::Errors::MethodNotAllowed` (405) - HTTP method not allowed
+- `MailchimpAPI::Errors::RequestURITooLong` (414) - Request URI too long
+- `MailchimpAPI::Errors::UnprocessableEntity` (422) - Request validation failed
+- `MailchimpAPI::Errors::UpgradeRequired` (426) - API version upgrade required
+- `MailchimpAPI::Errors::TooManyRequests` (429) - Rate limit exceeded
+- `MailchimpAPI::Errors::ServerError` (5xx) - Mailchimp server error
+
+Example:
+
+```ruby
+begin
+  MailchimpAPI.audience_members.create(audience_id, body: body)
+rescue MailchimpAPI::Errors::UnprocessableEntity => e
+  puts "Validation failed: #{e.error_detail}"
+  puts "Field errors: #{e.error_fields}"
+rescue MailchimpAPI::Errors::NetworkError => e
+  puts "Network error: #{e.error_detail}"
+end
+```
+
 ## Configuration options
 
 MailchimpAPI client accepts this additional options:
@@ -103,38 +149,65 @@ client = MailchimpAPI::Client.new(
 
 ## Pagination
 
-We have two specific methods:
-
-- `MailchimpAPI#each_page(response)` - iterates over current and each next page
-  response
-- `MailchimpAPI#each_page_item(response, items: :members)` - iterates over
-  each item (each member in this case)
-
-Example:
+All REST resources have `#each` method. Example:
 
 ```ruby
-first_page = MailchimpAPI.audience_members.list(list_id, query: { count: 100 }
+MailchimpAPI.audience_members.each(list_id) { |member| ... }
+MailchimpAPI.audience_member_tags.each(list_id, member_id) { |tag| ... }
+```
 
-MailchimpAPI.each_page(first_page) do |response|
-  puts response.body
-end
+`Each` method accepts `query`, `body` and `headers` as any other API.
+By default it requests 1000 items on each page, but it is configurable through
+`query` parameter. Example:
 
-MailchimpAPI.each_page_item(first_page, items: :members) do |item|
-  puts item[:email_address]
-end
+```ruby
+MailchimpAPI.audience_members.each(list_id, query: { count: 100 }) { |member| ... }
 ```
 
 ## Request
 
 ...
 
-## Errors
+## APIs
 
-...
+### Audience Members
 
-## APIs
+- List `MailchimpAPI.audience_members.get(audience_id)`
+- Create `MailchimpAPI.audience_members.create(audience_id, body: body)`
+- Show `MailchimpAPI.audience_members.show(audience_id, email)`
+- Update `MailchimpAPI.audience_members.update(audience_id, email, body: body)`
+- Add or Update `MailchimpAPI.audience_members.add_or_update(audience_id, email, body: body)`
+- Archive `MailchimpAPI.audience_members.delete(audience_id, email)`
+- Delete Permanently `MailchimpAPI.audience_members.delete(audience_id, email)`
 
-...
+### Audience Member Tags
+
+- List `MailchimpAPI.audience_member_tags.get(audience_id, email)`
+- Create `MailchimpAPI.audience_member_tags.create(audience_id, email, body: body)`
+
+### Audience Webhooks
+
+- List `MailchimpAPI.audience_webhooks.get(audience_id)`
+- Create `MailchimpAPI.audience_webhooks.create(audience_id, body: body)`
+- Show `MailchimpAPI.audience_webhooks.show(audience_id, webhook_id)`
+- Update `MailchimpAPI.audience_webhooks.update(audience_id, webhook_id, body: body)`
+- Delete `MailchimpAPI.audience_webhooks.delete(audience_id, webhook_id)`
+
+### Audience Interest Categories
+
+- List `MailchimpAPI.audience_interest_categories.get(audience_id)`
+- Create `MailchimpAPI.audience_interest_categories.create(audience_id, body: body)`
+- Show `MailchimpAPI.audience_interest_categories.show(audience_id, webhook_id)`
+- Update `MailchimpAPI.audience_interest_categories.update(audience_id, webhook_id, body: body)`
+- Delete `MailchimpAPI.audience_interest_categories.delete(audience_id, webhook_id)`
+
+### Audience Interests
+
+- List `MailchimpAPI.audience_interests.get(audience_id)`
+- Create `MailchimpAPI.audience_interests.create(audience_id, body: body)`
+- Show `MailchimpAPI.audience_interests.show(audience_id, webhook_id)`
+- Update `MailchimpAPI.audience_interests.update(audience_id, webhook_id, body: body)`
+- Delete `MailchimpAPI.audience_interests.delete(audience_id, webhook_id)`
 
 ## Development
 

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.3.0

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

@@ -6,13 +6,25 @@ module MailchimpAPI
     # Methods to access API resources
     #
     module APIMethods
-      def audience_members
-        Audience::Members.new(self)
+      def audience_interest_categories
+        Audience::InterestCategories.new(self)
+      end
+
+      def audience_interests
+        Audience::Interests.new(self)
       end
 
       def audience_member_tags
         Audience::MemberTags.new(self)
       end
+
+      def audience_members
+        Audience::Members.new(self)
+      end
+
+      def audience_webhooks
+        Audience::Webhooks.new(self)
+      end
     end
   end
 end

data/lib/mailchimp-api/client.rb

@@ -6,7 +6,6 @@ module MailchimpAPI
 
     include APIMethods
     include BatchMethods
-    include PaginationMethods
 
     attr_reader :api_key, :api_url, :api_version, :authorization_token, :config
 

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module MailchimpAPI
+  module Pagination
+    module ListEachItemHelper
+      private
+
+      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
+
+        query = PrepareQueryParams.call(query, items_field: items_field)
+
+        loop do
+          response = list(*args, query: query, body: body, headers: headers)
+          response.body.fetch(items_field).each(&block)
+
+          total_received_items_count = query.fetch(:offset) + query.fetch(:count)
+          break if total_received_items_count >= response.body.fetch(:total_items)
+
+          query[:offset] = total_received_items_count
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module MailchimpAPI
+  module Pagination
+    class PrepareQueryParams
+      class << self
+        def call(query, items_field:)
+          query ||= {}
+          query = query.transform_keys(&:to_sym)
+
+          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")
+          query
+        end
+
+        private
+
+        def prepare_offset(query)
+          query[:offset] = query[:offset].to_i
+        end
+
+        def prepare_count(query)
+          query[:count] = query[:count].to_i
+          query[:count] = 1000 if query[:count] == 0
+        end
+
+        def ensure_fields_included(query, items_field:, total_field:)
+          fields = query[:fields] || ""
+          query[:fields] = (fields.split(",") + [items_field.to_s, total_field]).uniq.join(",")
+        end
+
+        def ensure_fields_not_excluded(query, items_field:, total_field:)
+          excluded_fields = query[:excluded_fields]
+          return unless excluded_fields
+
+          excluded_fields = (excluded_fields.split(",") - [items_field.to_s, total_field]).join(",")
+          excluded_fields.empty? ? query.delete(:excluded_fields) : query[:excluded_fields] = excluded_fields
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module MailchimpAPI
+  module Audience
+    class InterestCategories < Resource
+      module APIs
+        include Pagination::ListEachItemHelper
+
+        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
+
+        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
+
+        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
+
+        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
+
+        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
+
+        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
+      end
+
+      include APIs
+      extend APIs
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module MailchimpAPI
+  module Audience
+    class Interests < Resource
+      module APIs
+        include Pagination::ListEachItemHelper
+
+        def list(list_id, interest_category_id, query: nil, body: nil, headers: nil)
+          path = "/lists/#{list_id}/interest-categories/#{interest_category_id}/interests"
+          client.get(path, query: query, body: body, headers: headers)
+        end
+
+        def create(list_id, interest_category_id, query: nil, body: nil, headers: nil)
+          path = "/lists/#{list_id}/interest-categories/#{interest_category_id}/interests"
+          client.post(path, query: query, body: body, headers: headers)
+        end
+
+        def show(list_id, interest_category_id, interest_id, query: nil, body: nil, headers: nil)
+          path = "/lists/#{list_id}/interest-categories/#{interest_category_id}/interests/#{interest_id}"
+          client.get(path, query: query, body: body, headers: headers)
+        end
+
+        def delete(list_id, interest_category_id, interest_id, query: nil, body: nil, headers: nil)
+          path = "/lists/#{list_id}/interest-categories/#{interest_category_id}/interests/#{interest_id}"
+          client.delete(path, query: query, body: body, headers: headers)
+        end
+
+        def update(list_id, interest_category_id, interest_id, query: nil, body: nil, headers: nil)
+          path = "/lists/#{list_id}/interest-categories/#{interest_category_id}/interests/#{interest_id}"
+          client.patch(path, query: query, body: body, headers: headers)
+        end
+
+        def each(list_id, interest_category_id, query: nil, body: nil, headers: nil, &block)
+          list_each_item(:interests, list_id, interest_category_id, query: query, body: body, headers: headers, &block)
+        end
+      end
+
+      include APIs
+      extend APIs
+    end
+  end
+end

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

@@ -4,15 +4,21 @@ 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"
+        include Pagination::ListEachItemHelper
+
+        def list(list_id, email, query: nil, body: nil, headers: nil)
+          path = "/lists/#{list_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"
+        def create(list_id, email, query: nil, body: nil, headers: nil)
+          path = "/lists/#{list_id}/members/#{subscriber_hash(email)}/tags"
           client.post(path, query: query, body: body, headers: headers)
         end
+
+        def each(list_id, email, query: nil, body: nil, headers: nil, &block)
+          list_each_item(:tags, list_id, email, query: query, body: body, headers: headers, &block)
+        end
       end
 
       include MailchimpAPI::Audience::Utils

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

@@ -4,40 +4,46 @@ module MailchimpAPI
   module Audience
     class Members < Resource
       module APIs
-        def list(audience_id, query: nil, body: nil, headers: nil)
-          path = "/lists/#{audience_id}/members"
+        include Pagination::ListEachItemHelper
+
+        def list(list_id, query: nil, body: nil, headers: nil)
+          path = "/lists/#{list_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"
+        def create(list_id, query: nil, body: nil, headers: nil)
+          path = "/lists/#{list_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)}"
+        def show(list_id, email, query: nil, body: nil, headers: nil)
+          path = "/lists/#{list_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)}"
+        def archive(list_id, email, query: nil, body: nil, headers: nil)
+          path = "/lists/#{list_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)}"
+        def update(list_id, email, query: nil, body: nil, headers: nil)
+          path = "/lists/#{list_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)}"
+        def add_or_update(list_id, email, query: nil, body: nil, headers: nil)
+          path = "/lists/#{list_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"
+        def delete_permanent(list_id, email, query: nil, body: nil, headers: nil)
+          path = "/lists/#{list_id}/members/#{subscriber_hash(email)}/actions/delete-permanent"
           client.post(path, query: query, body: body, headers: headers)
         end
+
+        def each(list_id, query: nil, body: nil, headers: nil, &block)
+          list_each_item(:members, list_id, query: query, body: body, headers: headers, &block)
+        end
       end
 
       include MailchimpAPI::Audience::Utils

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module MailchimpAPI
+  module Audience
+    class Webhooks < Resource
+      module APIs
+        include Pagination::ListEachItemHelper
+
+        def list(list_id, query: nil, body: nil, headers: nil)
+          path = "/lists/#{list_id}/webhooks"
+          client.get(path, query: query, body: body, headers: headers)
+        end
+
+        def create(list_id, query: nil, body: nil, headers: nil)
+          path = "/lists/#{list_id}/webhooks"
+          client.post(path, query: query, body: body, headers: headers)
+        end
+
+        def show(list_id, webhook_id, query: nil, body: nil, headers: nil)
+          path = "/lists/#{list_id}/webhooks/#{webhook_id}"
+          client.get(path, query: query, body: body, headers: headers)
+        end
+
+        def delete(list_id, webhook_id, query: nil, body: nil, headers: nil)
+          path = "/lists/#{list_id}/webhooks/#{webhook_id}"
+          client.delete(path, query: query, body: body, headers: headers)
+        end
+
+        def update(list_id, webhook_id, query: nil, body: nil, headers: nil)
+          path = "/lists/#{list_id}/webhooks/#{webhook_id}"
+          client.patch(path, query: query, body: body, headers: headers)
+        end
+
+        def each(list_id, query: nil, body: nil, headers: nil, &block)
+          list_each_item(:webhooks, list_id, query: query, body: body, headers: headers, &block)
+        end
+      end
+
+      include APIs
+      extend APIs
+    end
+  end
+end

data/lib/mailchimp-api.rb

@@ -35,8 +35,11 @@ module MailchimpAPI
 
     # Resources
     def_delegators :@client,
+      :audience_interest_categories,
+      :audience_interests,
+      :audience_member_tags,
       :audience_members,
-      :audience_member_tags
+      :audience_webhooks
 
     def client
       raise "#{name}.client must be set" unless @client
@@ -46,14 +49,18 @@ module MailchimpAPI
   end
 end
 
+require_relative "mailchimp-api/pagination/list_each_item_helper"
+require_relative "mailchimp-api/pagination/prepare_query_params"
 require_relative "mailchimp-api/resource"
 require_relative "mailchimp-api/resources/audience/utils/subscriber_hash"
+require_relative "mailchimp-api/resources/audience/interest_categories"
+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/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"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: mailchimp-rest-api
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Andrey Glushkov
 bindir: bin
 cert_chain: []
-date: 2025-04-28 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: Marketing Mailchimp REST API with no dependencies.
 email:
@@ -23,17 +23,21 @@ files:
 - 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/pagination/list_each_item_helper.rb
+- lib/mailchimp-api/pagination/prepare_query_params.rb
 - lib/mailchimp-api/request.rb
 - lib/mailchimp-api/request_executor.rb
 - lib/mailchimp-api/resource.rb
+- lib/mailchimp-api/resources/audience/interest_categories.rb
+- 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/utils/subscriber_hash.rb
+- lib/mailchimp-api/resources/audience/webhooks.rb
 - lib/mailchimp-api/response.rb
 - lib/mailchimp-api/uri_builder.rb
 - lib/mailchimp-api/version.rb
@@ -59,7 +63,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.8
 specification_version: 4
 summary: Mailchimp REST API (Marketing)
 test_files: []

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

@@ -1,51 +0,0 @@
-# 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:, &block)
-        return enum_for(:each_page_item, response, items: items) unless block
-
-        each_page(response) do |page|
-          page.body.fetch(items).each(&block)
-        end
-      end
-    end
-  end
-end