gibbon 4.0.0 → 4.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1cb1352737a9335535ba7d79420ec208817700b6e8b4fcf07a449499837b721f
-  data.tar.gz: 5fd15b6c055607e95a2e81f8b4fda95b606dc6be3ac7aa147057acd13c946a1a
+  metadata.gz: 421fe35f5c093158bac5d59d0a684325e8b77888257b6758fd805d9c86608520
+  data.tar.gz: cd15c1fa018171363d7fe32c6dddbe14e14985ed02ca1cbdcb313240e39c1640
 SHA512:
-  metadata.gz: 20bd382a94c31402452f63037c0f266cdb291493b72b93b1aab2c15021fb108fbf9a45b4ced1f3070c2c2a18aaee3bd117ef98dc4b8846b3a07f44ac042c864f
-  data.tar.gz: a030570ce92ecd7744ee1ed8dead15f0a176e3b178fd0b410e4c11a870f90ebbc0ba5909a82ae59b55959cf1ae3c06f0fd612826b5fdf93a26954907aba96729
+  metadata.gz: 0da6bfbdd8f9bff5ffbeac3943f3c3f571204b9a38869dfa2e75cba7bc1ba2863aa7dcdcb82e3167b54ed9dd0222d118a7b74606b2d7d8f92ec8fc8681529d24
+  data.tar.gz: 0ff34fa92007f022b7faf7368cf1285ed995efa43e964b0328928e8c466bc1661d0cdc0a32f0fed612e4cb5d54deaba74dfdfecae5dc264e4215ddb4bfc39ddf

data/.document

@@ -1,5 +1,5 @@
 lib/**/*.rb
-bin/*
-- 
-features/**/*.feature
+-
+README.markdown
+CHANGELOG.md
 LICENSE.txt

data/.github/workflows/ci.yml

@@ -0,0 +1,18 @@
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ['3.1', '3.2', '3.3', '3.4', '4.0']
+    steps:
+      - uses: actions/checkout@v5
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - run: bundle exec rake

data/.yardopts

@@ -0,0 +1,7 @@
+--markup markdown
+--readme README.markdown
+--no-private
+lib/**/*.rb
+-
+CHANGELOG.md
+LICENSE.txt

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+## [4.0.1] - 2026-10-23
+- Honor explicit `false` instance overrides for `symbolize_keys` and `debug`, while preserving class defaults for omitted options and `nil`.
+- Constrain `json` to versions below 3.0 to preserve compatibility with the `multi_json` adapter available on Ruby 3.1.
+- Expand API documentation, update usage examples, and add gem metadata links.
+
 ## [4.0.0] - 2026-07-23
 - Require Ruby 3.1+ (drops support for EOL Rubies 2.4 through 3.0)
 - Require TLS 1.2 as a minimum instead of pinning it exactly, allowing TLS 1.3

data/README.markdown

@@ -2,21 +2,32 @@
 
 Gibbon is an API wrapper for MailChimp's [API](https://mailchimp.com/developer/marketing/api/).
 
-[![Build Status](https://app.travis-ci.com/amro/gibbon.svg?branch=master)](https://app.travis-ci.com/github/amro/gibbon)
+[![Build Status](https://github.com/amro/gibbon/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/amro/gibbon/actions/workflows/ci.yml)
 
 ## Important Notes
 
 Please read MailChimp's [Getting Started Guide](https://mailchimp.com/developer/marketing/guides/quick-start/).
 
-Gibbon 3.0.0+ returns a `Gibbon::Response` instead of the response body directly. `Gibbon::Response` exposes the parsed response `body` and `headers`.
+Gibbon returns a `Gibbon::Response`, which exposes the parsed response `body` and the response `headers`. See [Responses](#responses) below.
+
+See the [CHANGELOG](CHANGELOG.md) for release history and [Upgrading](#upgrading) for breaking changes.
 
 ## Installation
 
     $ gem install gibbon
 
+Or add it to your `Gemfile`:
+
+```ruby
+gem "gibbon"
+```
+
 ## Requirements
 
-A MailChimp account and API key. You can see your API keys [here](https://admin.mailchimp.com/account/api).
+* **Ruby 3.1 or newer.** Gibbon 4.0 dropped support for Ruby 2.4 through 3.0.
+* A MailChimp account and API key. You can see your API keys [here](https://admin.mailchimp.com/account/api).
+
+Gibbon depends on [Faraday](https://github.com/lostisland/faraday) (both 1.x and 2.x are supported) and [MultiJson](https://github.com/intridea/multi_json). Connections to MailChimp negotiate TLS 1.2 or newer.
 
 ## Usage
 
@@ -26,7 +37,7 @@ First, create a *one-time use instance* of `Gibbon::Request`:
 gibbon = Gibbon::Request.new(api_key: "your_api_key")
 ```
 
-***Note*** Only reuse instances of Gibbon after terminating a call with a verb, which makes a request. Requests are light weight objects that update an internal path based on your call chain. When you terminate a call chain with a verb, a request instance makes a request and resets the path.
+***Note*** Only reuse instances of Gibbon after terminating a call with a verb, which makes a request. Requests are light weight objects that update an internal path based on your call chain. When you terminate a call chain with a verb, a request instance makes a request and resets the path. See [How call chains build paths](#how-call-chains-build-paths).
 
 You can set an individual request's `timeout` and `open_timeout` like this:
 
@@ -40,7 +51,15 @@ You can read about `timeout` and `open_timeout` in the [Net::HTTP](https://docs.
 Now you can make requests using the resources defined in [MailChimp's docs](https://mailchimp.com/developer/marketing/api/). Resource IDs
 are specified inline and a `CRUD` (`create`, `retrieve` (or `get`), `update`, `upsert`, or `delete`) verb initiates the request. `upsert` lets you update a record, if it exists, or insert it otherwise where supported by MailChimp's API.
 
-***Note*** `upsert` requires Gibbon version 2.1.0 or newer!
+Each verb maps to an HTTP method:
+
+| Gibbon verb           | HTTP method | Accepts `body` |
+| --------------------- | ----------- | -------------- |
+| `create`              | `POST`      | yes            |
+| `retrieve` (or `get`) | `GET`       | no             |
+| `update`              | `PATCH`     | yes            |
+| `upsert`              | `PUT`       | yes            |
+| `delete`              | `DELETE`    | no             |
 
 You can specify `headers`, `params`, and `body` when calling a `CRUD` method. For example:
 
@@ -48,8 +67,6 @@ You can specify `headers`, `params`, and `body` when calling a `CRUD` method. Fo
 gibbon.lists.retrieve(headers: {"SomeHeader": "SomeHeaderValue"}, params: {"query_param": "query_param_value"})
 ```
 
-***Note*** `get` can be substituted for `retrieve` as of Gibbon version 3.4.1 or newer!
-
 Of course, `body` is only supported on `create`, `update`, and `upsert` calls. Those map to HTTP `POST`, `PATCH`, and `PUT` verbs respectively.
 
 You can set `api_key`, `timeout`, `open_timeout`, `faraday_adapter`, `proxy`, `symbolize_keys`, `logger`, and `debug` globally:
@@ -76,8 +93,6 @@ You can also set the environment variable `MAILCHIMP_API_KEY` and Gibbon will us
 gibbon = Gibbon::Request.new
 ```
 
-***Note*** Substitute an underscore if a resource name contains a hyphen.
-
 Pass `symbolize_keys: true` to use symbols (instead of strings) as hash keys in API responses.
 
 ```ruby
@@ -86,6 +101,57 @@ gibbon = Gibbon::Request.new(api_key: "your_api_key", symbolize_keys: true)
 
 MailChimp's [resource documentation](https://mailchimp.com/developer/marketing/api/) is a list of available resources.
 
+## How call chains build paths
+
+`Gibbon::Request` defines no methods for MailChimp's resources. Any unknown method appends a segment to an internal path and returns the same object; a CRUD verb turns the accumulated path into a request. So `gibbon.lists(list_id).members.retrieve` builds `lists/<list_id>/members` and issues a `GET`.
+
+Three consequences are worth knowing.
+
+**Underscores become hyphens.** Segments containing a hyphen aren't valid Ruby method names, so write them with underscores and Gibbon converts:
+
+```ruby
+gibbon.lists(list_id).members(subscriber_hash).actions.delete_permanent.create
+# POST lists/<list_id>/members/<subscriber_hash>/actions/delete-permanent
+```
+
+**`send` is special cased.** `Object#send` would otherwise shadow the path segment, so `Gibbon::Request#send` falls through to path building when called with no arguments. That's what makes sending a campaign work:
+
+```ruby
+gibbon.campaigns(campaign_id).actions.send.create
+# POST campaigns/<campaign_id>/actions/send
+```
+
+Called *with* arguments, `send` keeps its usual Ruby meaning and invokes the named method.
+
+**An instance is reusable only after a verb.** The path resets when a verb runs, not when a chain goes out of scope. Abandoning a chain leaves its segments in place and corrupts the next call:
+
+```ruby
+gibbon = Gibbon::Request.new(api_key: "your_api_key")
+
+gibbon.lists               # no verb, so nothing is sent and nothing is reset
+gibbon.campaigns.retrieve  # GET lists/campaigns -- not what you wanted
+```
+
+Use a fresh instance per chain unless you know the previous one ended in a verb.
+
+## Responses
+
+Every CRUD verb returns a `Gibbon::Response` with two attributes:
+
+* `body` — the parsed JSON response, as a `Hash` (or `Array`, depending on the endpoint)
+* `headers` — the response headers, keyed by lower case string
+
+```ruby
+response = gibbon.lists.retrieve
+
+response.body["lists"]           # => [{"id" => "...", "name" => "...", ...}, ...]
+response.headers["content-type"] # => "application/json; charset=utf-8"
+```
+
+`body` respects `symbolize_keys`; `headers` keys are always strings.
+
+A response with an empty body — as with a successful `delete`, which MailChimp answers with `204 No Content` — returns `nil` rather than a `Gibbon::Response`.
+
 ## Debug Logging
 
 Pass `debug: true` to enable debug logging to STDOUT.
@@ -96,7 +162,7 @@ gibbon = Gibbon::Request.new(api_key: "your_api_key", debug: true)
 
 ### Custom logger
 
-Ruby `Logger.new` is used by default, but it can be overrided using:
+Ruby `Logger.new` is used by default, but it can be overridden using:
 
 ```ruby
 gibbon = Gibbon::Request.new(api_key: "your_api_key", debug: true, logger: MyLogger.new)
@@ -268,7 +334,7 @@ campaigns = gibbon.campaigns.retrieve
 Fetch the number of opens for a campaign
 
 ```ruby
-email_stats = gibbon.reports(campaign_id).retrieve["opens"]
+email_stats = gibbon.reports(campaign_id).retrieve.body["opens"]
 ```
 
 Create a new campaign:
@@ -337,7 +403,7 @@ gibbon.campaigns(campaign_id).actions.schedule.create(body: body)
 
 ### Interests
 
-Interests are a little more complicated than other parts of the API, so here's an example of how you would set interests during at subscription time or update them later. The ID of the interests you want to opt in or out of must be known ahead of time so an example of how to find interest IDs is also included.
+Interests are a little more complicated than other parts of the API, so here's an example of how you would set interests at subscription time or update them later. The ID of the interests you want to opt in or out of must be known ahead of time so an example of how to find interest IDs is also included.
 
 Subscribing a member to a list with specific interests up front:
 
@@ -357,13 +423,13 @@ So how do we get the interest IDs? When you query the API for a specific list me
 gibbon.lists(list_id).members(member_id).retrieve
 ```
 
-The response body (i.e. `response.body`) looks someting like this (unrelated things removed):
+The response body (i.e. `response.body`) looks something like this (unrelated things removed):
 
 ```ruby
 {"id"=>"...", "email_address"=>"...", ..., "interests"=>{"3def637141"=>true, "f7cc4ee841"=>false, "fcdc951b9f"=>false, "3daf3cf27d"=>true, "293a3703ed"=>false, "72370e0d1f"=>false, "d434d21a1c"=>false, "bdb1ff199f"=>false, "a54e78f203"=>false, "c4527fd018"=>false} ...}
 ```
 
-The API returns a map of interest ID to boolean value. Now we to get interest details so we know what these interest IDs map to. Looking at [this doc page](https://mailchimp.com/developer/marketing/api/interests/), we need to do this:
+The API returns a map of interest ID to boolean value. Now we need to get interest details so we know what these interest IDs map to. Looking at [this doc page](https://mailchimp.com/developer/marketing/api/interests/), we need to do this:
 
 ```ruby
 gibbon.lists(list_id).interest_categories.retrieve
@@ -383,21 +449,6 @@ gibbon.lists(list_id).interest_categories("0ace7aa498").interests.retrieve
 
 That response gives the interest data, including the ID for the interests themselves, which we can use to update a list member's interests or set them when we call the API to subscribe her or him to a list.
 
-### Error handling
-
-Gibbon raises an error when the API returns an error.
-
-`Gibbon::MailChimpError` has the following attributes: `title`, `detail`, `body`, `raw_body`, `status_code`. Some or all of these may not be
-available depending on the nature of the error. For example:
-
-```ruby
-begin
-  gibbon.lists(list_id).members.create(body: body)
-rescue Gibbon::MailChimpError => e
-  puts "Houston, we have a problem: #{e.message} - #{e.raw_body}"
-end
-```
-
 ### Other
 
 Overriding Gibbon's API endpoint (i.e. if using an access token from OAuth and have the `api_endpoint` from the [metadata](https://mailchimp.com/developer/marketing/guides/access-user-data-oauth-2/)):
@@ -419,73 +470,70 @@ You can set a different [Faraday adapter](https://github.com/lostisland/faraday)
 gibbon = Gibbon::Request.new(api_key: "your_api_key", faraday_adapter: :net_http)
 ```
 
-### Migrating from Gibbon 1.x
+## Error handling
 
-Gibbon 2.x+ exposes a different API from version 1.x. This is because Gibbon maps to MailChimp's API and because version 3 of the API is quite different from version 2. First, the name of the primary class has changed from `API` to `Request`. And the way you pass an API key during initialization is different. A few examples below.
+Gibbon raises two error types, both subclasses of `StandardError`.
 
-#### Initialization
+### Gibbon::GibbonError
 
-Gibbon 1.x:
+Raised *before* a request goes out, when Gibbon can't tell where to send it. In practice that means the API key is missing, or it carries no data center suffix and no `api_endpoint` was set:
 
 ```ruby
-gibbon = Gibbon::API.new("your_api_key")
-```
-
-Gibbon 2.x+:
+Gibbon::Request.new.lists.retrieve
+# => Gibbon::GibbonError: You must set an api_key prior to making a call
 
-```ruby
-gibbon = Gibbon::Request.new(api_key: "your_api_key")
+Gibbon::Request.new(api_key: "your_api_key").lists.retrieve
+# => Gibbon::GibbonError: You must set an api_key prior to making a call
 ```
 
-MailChimp API 3 is a RESTful API, so Gibbon's syntax now requires a trailing call to a verb, as described above.
+A key like `your_api_key-us1` carries its data center (`us1`) and works on its own. Access tokens obtained through OAuth do not, so pass `api_endpoint` alongside them — see [Other](#other) above.
 
-#### Fetching Lists
+### Gibbon::MailChimpError
 
-Gibbon 1.x:
+Raised when a request fails. It exposes `title`, `detail`, `body`, `raw_body`, and `status_code`:
 
 ```ruby
-gibbon.lists.list
+begin
+  gibbon.lists(list_id).members.create(body: body)
+rescue Gibbon::MailChimpError => e
+  puts "Houston, we have a problem: #{e.message} - #{e.raw_body}"
+end
 ```
 
-Gibbon 2.x+:
+Some or all of those attributes may be `nil` depending on the nature of the failure. MailChimp returning a `4xx` or `5xx` populates all of them from the error document. A transport level failure — a timeout, a refused connection — has no response to read, so only `message` is set.
 
-```ruby
-gibbon.lists.retrieve
-```
+Gibbon also raises `Gibbon::MailChimpError` when a *successful* response body isn't valid JSON. That error has a `title` of `"UNPARSEABLE_RESPONSE"` and a `status_code` of `500`, and its message includes the raw body.
 
-#### Fetching List Members
+## Upgrading
 
-Gibbon 1.x:
+Full release history lives in the [CHANGELOG](CHANGELOG.md). The breaking changes are summarized here.
 
-```ruby
-gibbon.lists.members({:id => list_id})
-```
+### Upgrading to 4.0
 
-Gibbon 2.x+:
+Gibbon 4.0 contains no API changes. It changes what it runs on:
 
-```ruby
-gibbon.lists(list_id).members.retrieve
-```
+* **Ruby 3.1 or newer is required.** Rubies 2.4 through 3.0 are EOL and are no longer supported. If you are on an older Ruby, stay on Gibbon 3.5.0.
+* **TLS 1.2 is now a minimum rather than an exact pin.** Connections previously negotiated exactly TLS 1.2; they now accept TLS 1.3 as well. No code change is needed, but if you inspect the negotiated protocol in tests or middleware, expect 1.3.
 
-#### Subscribing a Member to a List
+### Upgrading to 3.0
 
-Gibbon 1.x:
+`create`, `retrieve`/`get`, `update`, `upsert`, and `delete` return a `Gibbon::Response` rather than the parsed body. Add `.body`:
 
 ```ruby
-gibbon.lists.subscribe({:id => list_id, :email => {:email => "foo@bar.com"}, :merge_vars => {:FNAME => "Bob", :LNAME => "Smith"}})
-```
-
-Gibbon 2.x+:
+# Gibbon 2.x
+gibbon.lists.retrieve["lists"]
 
-```ruby
-gibbon.lists(list_id).members.create(body: {email_address: "foo@bar.com", status: "subscribed", merge_fields: {FNAME: "Bob", LNAME: "Smith"}})
+# Gibbon 3.x and newer
+gibbon.lists.retrieve.body["lists"]
 ```
 
+In exchange you also get `.headers`, which carries MailChimp's rate limit and content metadata. See [Responses](#responses).
+
 ## Thanks
 
 Thanks to everyone who has [contributed](https://github.com/amro/gibbon/contributors) to Gibbon's development.
 
 ## Copyright
 
-* Copyright (c) 2010-2022 Amro Mousa. See LICENSE.txt for details.
-* MailChimp (c) 2001-2022 The Rocket Science Group.
+* Copyright (c) 2010-2026 Amro Mousa. See LICENSE.txt for details.
+* MailChimp (c) 2001-2026 The Rocket Science Group.

data/gibbon.gemspec

@@ -10,9 +10,16 @@ Gem::Specification.new do |s|
   s.homepage    = "https://github.com/amro/gibbon"
 
   s.summary     = %q{A wrapper for MailChimp API 3.0}
-  s.description = %q{A wrapper for MailChimp API 3.0}
+  s.description = %q{Gibbon is a Ruby wrapper for MailChimp's Marketing API (version 3.0). Ruby method chains map onto API resource paths, so every documented resource is reachable without waiting on a gem update.}
   s.license     = "MIT"
 
+  s.metadata = {
+    "source_code_uri"   => "https://github.com/amro/gibbon",
+    "changelog_uri"     => "https://github.com/amro/gibbon/blob/master/CHANGELOG.md",
+    "bug_tracker_uri"   => "https://github.com/amro/gibbon/issues",
+    "documentation_uri" => "https://rubydoc.info/gems/gibbon"
+  }
+
   s.files         = `git ls-files`.split("\n")
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
@@ -20,9 +27,13 @@ Gem::Specification.new do |s|
 
   s.add_dependency('faraday', '>= 1.0')
   s.add_dependency('multi_json', '>= 1.11.0')
+  # Ruby 3.1 uses multi_json <= 1.19.1, whose JSON adapter passes options
+  # positionally. JSON 3 requires keyword arguments.
+  s.add_dependency('json', '< 3.0')
 
   s.add_development_dependency 'rake'
   s.add_development_dependency "rspec", "~> 3.13"
   s.add_development_dependency 'webmock', '~> 3.8'
+  s.add_development_dependency 'yard', '~> 0.9'
 
 end

data/lib/gibbon/api_request.rb

@@ -1,11 +1,23 @@
 module Gibbon
+  # Carries out the HTTP request described by a {Request}.
+  #
+  # This is an implementation detail of {Request}, which constructs one per
+  # call and reads its own configuration back out of it. Use {Request}'s CRUD
+  # verbs rather than instantiating this directly.
   class APIRequest
     include Helpers
 
+    # @param builder [Request] the request whose path and configuration to use
     def initialize(builder: nil)
       @request_builder = builder
     end
 
+    # @param params [Hash, nil] query string parameters
+    # @param headers [Hash, nil] additional request headers
+    # @param body [Hash, nil] request body, serialized to JSON
+    # @return [Response, nil] the response, or nil when the body is empty
+    # @raise [GibbonError] if no usable API key is configured
+    # @raise [MailChimpError] if the request fails or the response cannot be parsed
     def post(params: nil, headers: nil, body: nil)
       validate_api_key
 
@@ -19,6 +31,9 @@ module Gibbon
       end
     end
 
+    # @param (see #post)
+    # @return (see #post)
+    # @raise (see #post)
     def patch(params: nil, headers: nil, body: nil)
       validate_api_key
 
@@ -32,6 +47,9 @@ module Gibbon
       end
     end
 
+    # @param (see #post)
+    # @return (see #post)
+    # @raise (see #post)
     def put(params: nil, headers: nil, body: nil)
       validate_api_key
 
@@ -45,6 +63,10 @@ module Gibbon
       end
     end
 
+    # @param params [Hash, nil] query string parameters
+    # @param headers [Hash, nil] additional request headers
+    # @return (see #post)
+    # @raise (see #post)
     def get(params: nil, headers: nil)
       validate_api_key
 
@@ -58,6 +80,9 @@ module Gibbon
       end
     end
 
+    # @param (see #get)
+    # @return (see #post)
+    # @raise (see #post)
     def delete(params: nil, headers: nil)
       validate_api_key
 

data/lib/gibbon/gibbon_error.rb

@@ -1,3 +1,6 @@
 module Gibbon
+  # Raised before a request is sent, when Gibbon cannot determine where to send
+  # it: the API key is missing, or it carries no data center suffix and no
+  # `api_endpoint` was configured.
   class GibbonError < StandardError; end
 end

data/lib/gibbon/gibbon_helpers.rb

@@ -1,13 +1,20 @@
 module Gibbon
+  # Shared helpers mixed into {APIRequest}.
   module Helpers
+    # Extracts the data center prefix from an API key, e.g. `"us1."` from
+    # `"TESTKEY-us1"`.
+    #
+    # @param api_key [String, nil] the API key
+    # @return [String] the prefix including its trailing dot, or an empty string
+    #   when the key carries no data center suffix
     def get_data_center_from_api_key(api_key)
       # Return an empty string for invalid API keys so Gibbon hits the main endpoint
       data_center = ""
 
       if api_key && api_key["-"]
-        # Remove all non-alphanumberic characters in case someone attempts to inject
+        # Remove all non-alphanumeric characters in case someone attempts to inject
         # a different domain into the API key (e.g. when consuming user form-provided keys)
-        # This approach avoids assuming a 3 letter prefix (e.g. is MC were to create 
+        # This approach avoids assuming a 3 letter prefix (e.g. if MC were to create
         # a us10 DC, this would continue to work), and will continue to hit MC's server
         # rather than a would-be attacker's servers.
         data_center = "#{api_key.split('-').last.gsub(/[^0-9a-z ]/i, '')}."

data/lib/gibbon/mailchimp_error.rb

@@ -1,7 +1,25 @@
 module Gibbon
+  # Raised when a request fails.
+  #
+  # A `4xx` or `5xx` from MailChimp populates every attribute from the error
+  # document it returns. A transport level failure, such as a timeout, has no
+  # response to read, so only the message is set. Gibbon also raises this when a
+  # successful response body is not valid JSON, with a {#title} of
+  # `"UNPARSEABLE_RESPONSE"` and a {#status_code} of `500`.
   class MailChimpError < StandardError
-    attr_reader :title, :detail, :body, :raw_body, :status_code
+    # @return [String, nil] MailChimp's short name for the error, e.g. `"Resource Not Found"`
+    attr_reader :title
+    # @return [String, nil] MailChimp's human readable explanation of the error
+    attr_reader :detail
+    # @return [Hash, nil] the parsed error document
+    attr_reader :body
+    # @return [String, nil] the unparsed error response body
+    attr_reader :raw_body
+    # @return [Integer, nil] the HTTP status code
+    attr_reader :status_code
 
+    # @param message [String] the error message
+    # @param params [Hash] any of `:title`, `:detail`, `:body`, `:raw_body`, `:status_code`
     def initialize(message = "", params = {})
       @title       = params[:title]
       @detail      = params[:detail]
@@ -12,6 +30,7 @@ module Gibbon
       super(message)
     end
 
+    # @return [String] the message followed by every populated attribute
     def to_s
       super + " " + instance_variables_to_s
     end

data/lib/gibbon/request.rb

@@ -1,11 +1,42 @@
 module Gibbon
+  # Builds and issues requests against MailChimp's Marketing API.
+  #
+  # `Request` defines no methods for MailChimp's resources. An unknown method
+  # appends a segment to an internal path and returns `self`, so
+  # `gibbon.lists(list_id).members` builds `lists/<list_id>/members`. A CRUD
+  # verb ({#create}, {#retrieve}, {#update}, {#upsert}, {#delete}) then issues
+  # the request and resets the path. Because of that reset, an instance is safe
+  # to reuse only after a verb has run.
+  #
+  # @example Fetching lists
+  #   gibbon = Gibbon::Request.new(api_key: "your_api_key-us1")
+  #   gibbon.lists.retrieve.body["lists"]
+  #
+  # @see https://mailchimp.com/developer/marketing/api/ MailChimp's resource documentation
   class Request
+    # Per-instance configuration. Each falls back to the matching class level
+    # setting, then to an environment variable or built-in default; see
+    # {#initialize} for the resolution order.
     attr_accessor :api_key, :api_endpoint, :timeout, :open_timeout, :proxy, :faraday_adapter, :symbolize_keys, :debug, :logger
 
+    # Default read timeout, in seconds.
     DEFAULT_TIMEOUT = 60
+    # Default connection open timeout, in seconds.
     DEFAULT_OPEN_TIMEOUT = 60
 
-    def initialize(api_key: nil, api_endpoint: nil, timeout: nil, open_timeout: nil, proxy: nil, faraday_adapter: nil, symbolize_keys: false, debug: false, logger: nil)
+    # @param api_key [String, nil] API key or OAuth access token. Falls back to
+    #   `Gibbon::Request.api_key`, then `ENV["MAILCHIMP_API_KEY"]`.
+    # @param api_endpoint [String, nil] Base URL, e.g. `"https://us1.api.mailchimp.com"`.
+    #   Required when the key carries no data center suffix, as OAuth access
+    #   tokens do not; otherwise it is derived from the key.
+    # @param timeout [Integer, nil] Read timeout in seconds. Defaults to {DEFAULT_TIMEOUT}.
+    # @param open_timeout [Integer, nil] Open timeout in seconds. Defaults to {DEFAULT_OPEN_TIMEOUT}.
+    # @param proxy [String, nil] Proxy URL. Falls back to `ENV["MAILCHIMP_PROXY"]`.
+    # @param faraday_adapter [Symbol, nil] Faraday adapter. Defaults to `Faraday.default_adapter`.
+    # @param symbolize_keys [Boolean] Whether parsed response bodies use symbol keys.
+    # @param debug [Boolean] Whether to log requests and responses.
+    # @param logger [Logger, nil] Logger used when `debug` is true. Defaults to `Logger.new(STDOUT)`.
+    def initialize(api_key: nil, api_endpoint: nil, timeout: nil, open_timeout: nil, proxy: nil, faraday_adapter: nil, symbolize_keys: nil, debug: nil, logger: nil)
       @path_parts = []
       @api_key = api_key || self.class.api_key || ENV['MAILCHIMP_API_KEY']
       @api_key = @api_key.strip if @api_key
@@ -14,11 +45,15 @@ module Gibbon
       @open_timeout = open_timeout || self.class.open_timeout || DEFAULT_OPEN_TIMEOUT
       @proxy = proxy || self.class.proxy || ENV['MAILCHIMP_PROXY']
       @faraday_adapter = faraday_adapter || self.class.faraday_adapter || Faraday.default_adapter
-      @symbolize_keys = symbolize_keys || self.class.symbolize_keys || false
-      @debug = debug || self.class.debug || false
+      @symbolize_keys = symbolize_keys.nil? ? (self.class.symbolize_keys || false) : symbolize_keys
+      @debug = debug.nil? ? (self.class.debug || false) : debug
       @logger = logger || self.class.logger || ::Logger.new(STDOUT)
     end
 
+    # Appends the method name to the request path, along with any arguments as
+    # further segments, and returns `self` so calls can be chained.
+    #
+    # @return [Request] self
     def method_missing(method, *args)
       # To support underscores, we replace them with hyphens when calling the API
       @path_parts << method.to_s.gsub("_", "-").downcase
@@ -27,10 +62,19 @@ module Gibbon
       self
     end
 
+    # Every method name is a potential path segment, so this always returns true.
+    #
+    # @return [true]
     def respond_to_missing?(method_name, include_private = false)
       true
     end
 
+    # Appends `send` as a path segment when called with no arguments, so that
+    # `gibbon.campaigns(id).actions.send.create` reaches
+    # `campaigns/<id>/actions/send`. Called with arguments, this behaves like
+    # `Object#send` and invokes the named method.
+    #
+    # @return [Request, Object] self, or the return value of the invoked method
     def send(*args)
       if args.length == 0
         method_missing(:send, args)
@@ -39,38 +83,75 @@ module Gibbon
       end
     end
 
+    # @return [String] the path accumulated so far, e.g. `"lists/abc123/members"`
     def path
       @path_parts.join('/')
     end
 
+    # Issues a `POST` to the accumulated path, then resets it.
+    #
+    # @param params [Hash, nil] query string parameters
+    # @param headers [Hash, nil] additional request headers
+    # @param body [Hash, nil] request body, serialized to JSON
+    # @return [Response, nil] the response, or nil when MailChimp returns an empty body
+    # @raise [GibbonError] if no usable API key is configured
+    # @raise [MailChimpError] if the request fails or the response cannot be parsed
     def create(params: nil, headers: nil, body: nil)
       APIRequest.new(builder: self).post(params: params, headers: headers, body: body)
     ensure
       reset
     end
 
+    # Issues a `PATCH` to the accumulated path, then resets it.
+    #
+    # @param (see #create)
+    # @return (see #create)
+    # @raise (see #create)
     def update(params: nil, headers: nil, body: nil)
       APIRequest.new(builder: self).patch(params: params, headers: headers, body: body)
     ensure
       reset
     end
 
+    # Issues a `PUT` to the accumulated path, then resets it. Updates the record
+    # if it exists and inserts it otherwise, where MailChimp supports it.
+    #
+    # @param (see #create)
+    # @return (see #create)
+    # @raise (see #create)
     def upsert(params: nil, headers: nil, body: nil)
       APIRequest.new(builder: self).put(params: params, headers: headers, body: body)
     ensure
       reset
     end
 
+    # Alias for {#retrieve}.
+    #
+    # @param (see #retrieve)
+    # @return (see #retrieve)
+    # @raise (see #retrieve)
     def get(params: nil, headers: nil)
       retrieve(params: params, headers: headers)
     end
 
+    # Issues a `GET` to the accumulated path, then resets it.
+    #
+    # @param params [Hash, nil] query string parameters
+    # @param headers [Hash, nil] additional request headers
+    # @return [Response, nil] the response, or nil when MailChimp returns an empty body
+    # @raise [GibbonError] if no usable API key is configured
+    # @raise [MailChimpError] if the request fails or the response cannot be parsed
     def retrieve(params: nil, headers: nil)
       APIRequest.new(builder: self).get(params: params, headers: headers)
     ensure
       reset
     end
 
+    # Issues a `DELETE` to the accumulated path, then resets it.
+    #
+    # @param (see #retrieve)
+    # @return (see #retrieve)
+    # @raise (see #retrieve)
     def delete(params: nil, headers: nil)
       APIRequest.new(builder: self).delete(params: params, headers: headers)
     ensure
@@ -84,12 +165,22 @@ module Gibbon
     end
 
     class << self
+      # Class level defaults applied to every new instance. Setting these is a
+      # convenient way to configure Gibbon once, e.g. from a Rails initializer.
       attr_accessor :api_key, :timeout, :open_timeout, :api_endpoint, :proxy, :faraday_adapter, :symbolize_keys, :debug, :logger
 
+      # Starts a call chain on a new instance built from the class level
+      # configuration, so `Gibbon::Request.lists.retrieve` works once
+      # {api_key} has been set.
+      #
+      # @return [Request] a new instance carrying the first path segment
       def method_missing(sym, *args, &block)
         new(api_key: self.api_key, api_endpoint: self.api_endpoint, timeout: self.timeout, open_timeout: self.open_timeout, faraday_adapter: self.faraday_adapter, symbolize_keys: self.symbolize_keys, debug: self.debug, proxy: self.proxy, logger: self.logger).send(sym, *args, &block)
       end
 
+      # Every method name is a potential path segment, so this always returns true.
+      #
+      # @return [true]
       def respond_to_missing?(method_name, include_private = false)
         true
       end

data/lib/gibbon/response.rb

@@ -1,7 +1,20 @@
 module Gibbon
+  # A parsed response from MailChimp, returned by every CRUD verb on {Request}.
+  #
+  # @example
+  #   response = gibbon.lists.retrieve
+  #   response.body["lists"]
+  #   response.headers["content-type"]
   class Response
-    attr_accessor :body, :headers
-    
+    # @return [Hash, Array] the parsed JSON response body. Keys are symbols when
+    #   the request was built with `symbolize_keys: true`, strings otherwise.
+    attr_accessor :body
+
+    # @return [Hash] the response headers, keyed by lower case string.
+    attr_accessor :headers
+
+    # @param body [Hash, Array] the parsed response body
+    # @param headers [Hash] the response headers
     def initialize(body: {}, headers: {})
       @body = body
       @headers = headers

data/lib/gibbon/version.rb

@@ -1,3 +1,4 @@
 module Gibbon
-  VERSION = "4.0.0"
+  # The released version of the gem.
+  VERSION = "4.0.1"
 end

data/lib/gibbon.rb

@@ -10,5 +10,6 @@ require 'gibbon/request'
 require 'gibbon/api_request'
 require 'gibbon/response'
 
+# A Ruby wrapper for MailChimp's Marketing API. See {Gibbon::Request}.
 module Gibbon
 end

data/spec/gibbon/api_request_spec.rb

@@ -1,5 +1,6 @@
 require 'spec_helper'
 require 'webmock/rspec'
+require 'stringio'
 
 describe Gibbon::APIRequest do
   let(:api_key) { "1234-us1" }
@@ -151,6 +152,49 @@ describe Gibbon::APIRequest do
     end
   end
 
+  context "instance overrides of class defaults" do
+    before do
+      allow(Gibbon::Request).to receive(:symbolize_keys).and_return(true)
+      allow(Gibbon::Request).to receive(:debug).and_return(true)
+    end
+
+    let(:log_output) { StringIO.new }
+    let(:gibbon) do
+      Gibbon::Request.new(api_key: api_key, symbolize_keys: false, debug: false, logger: Logger.new(log_output))
+    end
+
+    it "returns string keys, including nested keys, when symbolization is disabled" do
+      stub_request(:get, "#{@api_root}/lists")
+        .to_return(body: '{"lists": [{"id": "abc123"}]}')
+
+      expect(gibbon.lists.retrieve.body).to eq({ "lists" => [{ "id" => "abc123" }] })
+      expect(Gibbon::Request.symbolize_keys).to be true
+    end
+
+    it "preserves error details with string keys when symbolization is disabled" do
+      error_body = '{"title": "Invalid Resource", "detail": "Invalid email address"}'
+      stub_request(:get, "#{@api_root}/lists").to_return(status: 422, body: error_body)
+
+      expect { gibbon.lists.retrieve }.to raise_error(Gibbon::MailChimpError) { |error|
+        expect(error.status_code).to eq 422
+        expect(error.title).to eq "Invalid Resource"
+        expect(error.detail).to eq "Invalid email address"
+        expect(error.body).to eq({ "title" => "Invalid Resource", "detail" => "Invalid email address" })
+        expect(error.raw_body).to eq error_body
+      }
+    end
+
+    it "does not log requests or responses when debug is disabled" do
+      stub_request(:get, "#{@api_root}/lists")
+        .to_return(body: '{"email_address": "private@example.com"}')
+
+      gibbon.lists.retrieve
+
+      expect(log_output.string).to be_empty
+      expect(Gibbon::Request.debug).to be true
+    end
+  end
+
   context "configure_request" do
     it "sets params, headers, body, and timeouts on the request" do
       gibbon = Gibbon::Request.new(api_key: api_key, timeout: 45, open_timeout: 15)

data/spec/gibbon/gibbon_spec.rb

@@ -219,10 +219,26 @@ describe Gibbon do
       expect(Gibbon::Request.new.symbolize_keys).to eq(Gibbon::Request.symbolize_keys)
     end
 
+    it "allows instance symbolize_keys false to override the class setting" do
+      expect(Gibbon::Request.new(symbolize_keys: false).symbolize_keys).to be false
+    end
+
+    it "inherits the class symbolize_keys setting when explicitly passed nil" do
+      expect(Gibbon::Request.new(symbolize_keys: nil).symbolize_keys).to be true
+    end
+
     it "set debug on new instances" do
       expect(Gibbon::Request.new.debug).to eq(Gibbon::Request.debug)
     end
 
+    it "allows instance debug false to override the class setting" do
+      expect(Gibbon::Request.new(debug: false).debug).to be false
+    end
+
+    it "inherits the class debug setting when explicitly passed nil" do
+      expect(Gibbon::Request.new(debug: nil).debug).to be true
+    end
+
     it "set faraday_adapter on new instances" do
       expect(Gibbon::Request.new.faraday_adapter).to eq(Gibbon::Request.faraday_adapter)
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gibbon
 version: !ruby/object:Gem::Version
-  version: 4.0.0
+  version: 4.0.1
 platform: ruby
 authors:
 - Amro Mousa
@@ -37,6 +37,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.11.0
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -79,7 +93,23 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.8'
-description: A wrapper for MailChimp API 3.0
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: Gibbon is a Ruby wrapper for MailChimp's Marketing API (version 3.0).
+  Ruby method chains map onto API resource paths, so every documented resource is
+  reachable without waiting on a gem update.
 email:
 - amromousa@gmail.com
 executables: []
@@ -88,8 +118,9 @@ extra_rdoc_files: []
 files:
 - ".document"
 - ".github/FUNDING.yml"
+- ".github/workflows/ci.yml"
 - ".gitignore"
-- ".travis.yml"
+- ".yardopts"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
@@ -116,7 +147,11 @@ files:
 homepage: https://github.com/amro/gibbon
 licenses:
 - MIT
-metadata: {}
+metadata:
+  source_code_uri: https://github.com/amro/gibbon
+  changelog_uri: https://github.com/amro/gibbon/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/amro/gibbon/issues
+  documentation_uri: https://rubydoc.info/gems/gibbon
 rdoc_options: []
 require_paths:
 - lib
@@ -131,7 +166,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: A wrapper for MailChimp API 3.0
 test_files: []

data/.travis.yml

@@ -1,23 +0,0 @@
-language: ruby
-cache: bundler
-rvm:
-  - 3.1
-  - 3.2
-  - 3.3
-  - 3.4
-jobs:
-  include:
-    # rvm's stable release does not know Ruby 4.0 yet, so boot on 3.4,
-    # then upgrade rvm to master and install 4.0 from there
-    - name: "4.0 (via rvm master)"
-      rvm: 3.4
-      before_install:
-        - rvm get master
-        - rvm install ruby-4.0
-        - rvm use ruby-4.0
-        - ruby -v
-      # Bundler 4 (shipped with Ruby 4.0) removed the --path flag that
-      # Travis's default install step still passes
-      install:
-        - bundle config set --local path vendor/bundle
-        - bundle install --jobs=3 --retry=3