gibbon 3.5.0 → 4.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61103c56f7d3ff60ca48fab8a2ca7c71949c1c01c784abd7ddb062dbd74d4560
-  data.tar.gz: 93f18505844eb71b72d189622547c61c0bda3c416bdb2a2caa4ec0358899e52b
+  metadata.gz: 421fe35f5c093158bac5d59d0a684325e8b77888257b6758fd805d9c86608520
+  data.tar.gz: cd15c1fa018171363d7fe32c6dddbe14e14985ed02ca1cbdcb313240e39c1640
 SHA512:
-  metadata.gz: 7e4203bc006c80cc20c5fff0217673543faa842a28b57eb3620a373a63409c0e1b5f503335d44ff05d8ba8d124db1f5b984dcf5f98632aaa8ee077d525d0a413
-  data.tar.gz: ecc7c39379e218a5a10d92c4597fdb9e5f28c90c8297ef5a19d04189044a0b86a0f84120151369ecca4c989c3d88bb359fcc651de9527497cba368b608225d9d
+  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,4 +1,14 @@
-## [3.5.0, unreleased] - 2022-06-05
+## [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
+- Modernize development setup: loosen rspec pin, remove Rubinius leftovers, update CI matrix to Ruby 3.1 through 4.0
+
+## [3.5.0] - 2023-06-07
 - Remove support for retired Export API
 
 ## [3.4.4] - 2022-02-24

data/Gemfile

@@ -1,11 +1,3 @@
 source "https://rubygems.org"
 
-platforms :rbx do
-  gem 'rubinius-developer_tools'
-end
-
-group :development, :test do
-  gem 'webmock', '~> 3.8'
-end
-
 gemspec

data/README.markdown

@@ -1,22 +1,33 @@
 # gibbon
 
-Gibbon is an API wrapper for MailChimp's [API](http://kb.mailchimp.com/api/).
+Gibbon is an API wrapper for MailChimp's [API](https://mailchimp.com/developer/marketing/api/).
 
-[![Build Status](https://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](http://kb.mailchimp.com/api/article/api-3-overview).
+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](http://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:
 
@@ -35,12 +46,20 @@ gibbon.timeout = 30
 gibbon.open_timeout = 30
 ```
 
-You can read about `timeout` and `open_timeout` in the [Net::HTTP](https://ruby-doc.org/stdlib-2.3.3/libdoc/net/http/rdoc/Net/HTTP.html) doc.
+You can read about `timeout` and `open_timeout` in the [Net::HTTP](https://docs.ruby-lang.org/en/master/Net/HTTP.html) doc.
 
-Now you can make requests using the resources defined in [MailChimp's docs](http://kb.mailchimp.com/api/resources). Resource IDs
+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,15 +93,64 @@ 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
 gibbon = Gibbon::Request.new(api_key: "your_api_key", symbolize_keys: true)
 ```
 
-MailChimp's [resource documentation](http://kb.mailchimp.com/api/resources) is a list of available resources.
+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
 
@@ -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)
@@ -241,7 +307,7 @@ gibbon.batches(batch_id).retrieve
 ```
 
 ***Note*** This response truncated for brevity. Reference the MailChimp
-[API documentation for Batch Operations](http://developer.mailchimp.com/documentation/mailchimp/reference/batches/) for more details.
+[API documentation for Batch Operations](https://mailchimp.com/developer/marketing/api/batches/) for more details.
 
 ### Fields
 
@@ -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](http://kb.mailchimp.com/api/resources/lists/interest-categories/interests/lists-interests-collection), 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,24 +449,9 @@ 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](http://apidocs.mailchimp.com/oauth2/)):
+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/)):
 
 ```ruby
 Gibbon::Request.api_endpoint = "https://us1.api.mailchimp.com"
@@ -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

@@ -7,23 +7,33 @@ Gem::Specification.new do |s|
   s.version     = Gibbon::VERSION
   s.authors     = ["Amro Mousa"]
   s.email       = ["amromousa@gmail.com"]
-  s.homepage    = "http://github.com/amro/gibbon"
+  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.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
-  s.required_ruby_version = '>= 2.4.0'
+  s.required_ruby_version = '>= 3.1.0'
 
   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.5.0"
+  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
 
@@ -106,6 +131,10 @@ module Gibbon
     # Helpers
 
     def handle_error(error)
+      # Errors we raised ourselves (e.g. unparseable response bodies) already
+      # carry their details; re-wrapping them here would strip those attributes
+      raise error if error.is_a?(MailChimpError)
+
       error_params = {}
 
       begin
@@ -146,7 +175,7 @@ module Gibbon
     end
 
     def rest_client
-      client = Faraday.new(self.api_url, proxy: self.proxy, ssl: { version: "TLSv1_2" }) do |faraday|
+      client = Faraday.new(self.api_url, proxy: self.proxy, ssl: { min_version: :TLS1_2 }) do |faraday|
         faraday.response :raise_error
         faraday.adapter adapter
         if @request_builder.debug

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