kit-rb 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa9f06f61a89d938cb719fcbd0cad578e8dd6d6ffc35fcf9b17d356f6a9160b3
-  data.tar.gz: 6279b4801b2cd8738b11bcc43babad6b8654739683ace8ff86389e040b8a994b
+  metadata.gz: a162f45f8175f25dc05e677013062f320dc8e3b494d7fc8e7bd998b9b3a72a1b
+  data.tar.gz: cd4c78b1b42fb6019a6013863501c3091ea49019ca7dbfc7551f0c26c8b0633e
 SHA512:
-  metadata.gz: 3cc4008cae00b1fe78391e5816b3e19040103c86b5d4feedbc8a03fdce856325e969840f4d568c583f2f5a1bd579f69ffd403c7e515cfca611a3ea0eca24b636
-  data.tar.gz: 279c04700c82548a16c64637d72269d1ad36a06419228e5ba738e603f98f23983f60183078a79c5a166dee45bc40d5f36a50c4b841a969d020acdaa6bdebf8b7
+  metadata.gz: c9c8a1a2e81b6fedce1c815a9cbf2fd02df62aea031c50df3fd06aba94c380164f0290115060f16029617b811ee145efb45b3b95d93803907e96fda9283e8956
+  data.tar.gz: 0eb5b408eb466cdf4fd4c19de9d50c7e23ad36d4e743e9c8c920b4523c502abd346dd87e74c8f79a345f341e8bb3a2bfa4378cf16d4e9acfb2bc99bca1b0f073

data/.githooks/pre-commit

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Lint the Ruby files that are actually staged so the commit gate matches the
+# commit. RuboCop exits non-zero on any offense, which set -e turns into an
+# aborted commit — no output pattern is parsed, so a singular "1 offense
+# detected" can no longer slip through.
+# (A while-read loop rather than mapfile: macOS ships bash 3.2, which lacks it.)
+staged=()
+while IFS= read -r file; do
+  staged+=("$file")
+done < <(
+  git diff --cached --name-only --diff-filter=ACM |
+    grep -E '(\.(rb|rake|gemspec)|Rakefile|Gemfile)$' || true
+)
+
+if [ "${#staged[@]}" -eq 0 ]; then
+  exit 0
+fi
+
+exec bundle exec rubocop --force-exclusion "${staged[@]}"

data/.githooks/pre-push

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Run the full default gate (spec + rubocop + steep) before anything leaves the
+# machine. exec propagates rake's exit code, so a red gate blocks the push.
+exec bundle exec rake

data/CHANGELOG.md

@@ -4,6 +4,83 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres
 to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.3.0] - 2026-09-06
+
+The hardening pass (`docs/TASKS.md`): two real-API bugs fixed, the surface
+completed to all 83 documented operations, receiver-side webhook support, and
+contract tests over every envelope, request body and 204.
+
+### Added
+- The two operations 0.2.0 lacked: `subscribers.update_location` (PATCH) and
+  `webhook_endpoints.update` (PATCH: rename, change URL, pause/resume with
+  `status`, replace `events`). All 83 documented operations now have a method.
+- Incoming webhooks: `Kit::Webhooks::Signature.verify!`/`verify?` (HMAC-SHA256
+  `X-Kit-Signature`, replay window, rotation-aware, multiple secrets),
+  `Kit::Webhooks::Delivery.from_request`/`parse` with typed `Event`s, and the
+  event-name constants `Kit::Webhooks::Events` (28) / `LegacyEvents` (15, with
+  `REQUIRED_PARAM`).
+- `Kit::Objects::WebhookEndpoint#secret` — the signing secret Kit returns only on
+  `create` and `rotate_secret`.
+- `Pagination#total_count` / `Collection#total_count` (send
+  `include_total_count: true`); `Collection#size`, `#length`, `#empty?`, `#[]`
+  and a compact `#inspect`.
+- Response fields the spec declares: `Account#timezone`/`#plan` (typed) and
+  `#sending_addresses`; `Post#content`; `SequenceEmail#content`;
+  `Subscriber#added_at`/`#tagged_at`/`#referrer`/`#referrer_utm_parameters`/
+  `#attribution`/`#tags`/`#tag_names`/`#tag_ids`/`#stats`; `Tag#tagged_at`;
+  `CustomField#created_at`.
+- `sequences.get`/`sequences.email` accept `include: "stats"`;
+  `subscribers.stats` accepts `email_sent_after`/`email_sent_before`.
+- Error classes: `ConflictError` (409), `PayloadTooLargeError` (413),
+  `UnexpectedResponseError` (a 2xx whose body is not the documented shape),
+  `TransportError` with `TimeoutError` and `ConnectionError` (the http.rb
+  exception is kept as `cause`). `APIError#method`/`#path`; messages now read
+  `"GET /v4/subscribers/1 failed with status 404: ..."`.
+- `Connection#request_with_status`.
+
+### Changed
+- **Breaking:** the `bulk` methods return `Kit::Objects::BulkResult`
+  (`items`, typed `failures`, `async?` for a 202) instead of the raw Hash.
+- **Breaking:** `broadcasts.create/update`, `sequences.create/update`,
+  `sequences.create_email/update_email`, `snippets.create/update` and
+  `purchases.create` take explicit keyword arguments (the fields the spec
+  documents) instead of `**attributes`; an unknown field raises
+  `ArgumentError`. Fields not passed are omitted; an explicit `nil` is sent,
+  which Kit uses to clear `send_days`/`email_template_id`/`send_at`.
+- **Breaking:** `subscribers.unsubscribe` returns `nil` (the API answers 204).
+- Retries: `Retry-After` is capped at `max_backoff`; a 5xx or transport
+  failure is retried only for idempotent verbs (never a POST); a 429 is still
+  retried for every verb.
+- Follow-up page requests drop `include_total_count` and any `before` cursor.
+- `Client`, `Configuration`, `Connection`, `Auth::*` and `OAuth::Token`
+  mask credentials in `#inspect`.
+- Path ids are percent-encoded; a nil/blank id raises `ArgumentError`.
+- One http.rb client is built per `Connection` instead of per request.
+
+### Fixed
+- `subscribers.unsubscribe` raised `NoMethodError` against the real API (204,
+  no body).
+- `webhook_endpoints.create`/`rotate_secret` silently discarded the one-time
+  signing secret.
+- A response with an unexpected shape raised `KeyError`/`NoMethodError`
+  instead of a `Kit::Error`.
+- The error-mapping specs really slept through retries (60 s per CI run).
+
+## [0.2.0] - 2026-09-04
+
+### Changed
+- **Breaking:** the stats and analytics endpoints now return typed value objects
+  instead of raw hashes, matching every other resource:
+  `broadcasts.stats`/`stats_list` → `Objects::BroadcastStats` (the nested metrics
+  flattened), `broadcasts.clicks` → `Collection[Objects::BroadcastClick]`,
+  `subscribers.stats` → `Objects::SubscriberStats`, `account.email_stats` →
+  `Objects::EmailStats`, and `account.growth_stats` → `Objects::GrowthStats`.
+
+### Removed
+- `Objects::Raw` (the identity used by the old raw-hash stats returns).
+
 ## [0.1.0] - 2026-09-04
 
 First feature-complete release: the entire Kit API v4 surface — all 81 documented
@@ -45,3 +122,9 @@ vertical slice. Not yet feature-complete — resources land in 0.1.0 per docs/DE
 - Cursor pagination engine (`Kit::Collection#auto_paging_each`) and automatic
   429/5xx retry with backoff.
 - RBS signatures for the public surface.
+
+[Unreleased]: https://github.com/linyiru/kit-rb/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/linyiru/kit-rb/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/linyiru/kit-rb/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/linyiru/kit-rb/compare/7ce3329...v0.1.0
+[0.0.0]: https://rubygems.org/gems/kit-rb/versions/0.0.0

data/README.md

@@ -4,9 +4,9 @@ A modern, fully-typed Ruby client for the **Kit** (formerly ConvertKit) **API v4
 
 The gem is named `kit-rb`; the public namespace is the clean `Kit`.
 
-> Status: the full v4 surface is implemented — every one of the 81 documented
-> operations across all resources, verified against the vendored OpenAPI
-> document. See [`docs/DESIGN.md`](docs/DESIGN.md).
+> Status: the full v4 surface is implemented — every one of the 83 documented
+> operations across all resources, pinned to the vendored OpenAPI document by
+> contract tests. See [`docs/DESIGN.md`](docs/DESIGN.md).
 
 ## Install
 
@@ -31,21 +31,25 @@ info = client.account.get       # => Kit::Objects::AccountInfo
 info.account.plan_type          # => "creator_pro"
 ```
 
-Responses are immutable `Data` value objects. Errors are typed:
+Responses are immutable `Data` value objects. Errors are typed, and every one
+is a `Kit::Error`:
 
 ```ruby
 begin
-  client.account.get
-rescue Kit::AuthenticationError => e   # 401
-  warn e.status                        # => 401
+  client.subscribers.get(42)
+rescue Kit::NotFoundError => e         # 404 — also 401/403/409/413/422 classes
+  warn e.message                       # => "GET /v4/subscribers/42 failed with status 404: ..."
 rescue Kit::RateLimitError => e        # 429 — honours Retry-After
   sleep e.retry_after
-rescue Kit::APIError => e              # any other non-2xx
-  warn e.errors                        # => ["..."] from Kit's body
+rescue Kit::APIError => e              # any other non-2xx: e.status, e.errors, e.method, e.path
+rescue Kit::TimeoutError, Kit::ConnectionError => e  # never got a response (< Kit::TransportError)
+rescue Kit::UnexpectedResponseError => e # 2xx whose body is not the documented shape
 end
 ```
 
-Transient failures (429 and 5xx) are retried automatically with backoff.
+A 429 is retried for every request (with `Retry-After`, capped at
+`max_backoff`); 5xx and transport failures are retried only for idempotent
+verbs, so a POST is never replayed. Credentials are masked in `#inspect`.
 
 ## Resources
 
@@ -56,15 +60,44 @@ click reports), `email_templates`, `segments`, `posts`, `snippets`, `purchases`,
 
 ### Pagination
 
-List endpoints return a `Kit::Collection` — `Enumerable` over the current page,
-with lazy cursor following:
+List endpoints return a `Kit::Collection` — `Enumerable` over the current page
+(`size`, `empty?`, `[]`), with lazy cursor following:
 
 ```ruby
 client.subscribers.list.each { |s| ... }              # current page
 client.subscribers.list.auto_paging_each { |s| ... }  # every page, lazily
-client.subscribers.list(status: "active", per_page: 100)
+page = client.subscribers.list(status: "active", per_page: 100, include_total_count: true)
+page.total_count                                      # => 1234 (first page only, as Kit asks)
 ```
 
+### Bulk
+
+The `bulk` endpoints (OAuth only) return a `Kit::Objects::BulkResult`:
+
+```ruby
+result = client.bulk.create_tags([{ name: "vip" }, { name: "" }])
+result.async?           # true when Kit queued the batch (202) and will POST to callback_url
+result.items            # the affected records (raw Hashes; shape varies per endpoint)
+result.failures         # => [#<BulkFailure item={"name"=>""} errors=["Name can't be blank"]>]
+```
+
+### Receiving webhooks
+
+Endpoints created with `client.webhook_endpoints.create` return their signing
+`secret` once. Verify and parse each delivery with it:
+
+```ruby
+delivery = Kit::Webhooks::Delivery.from_request(
+  request.raw_post, request.headers["X-Kit-Signature"], secret: ENV.fetch("KIT_WEBHOOK_SECRET")
+)                                                     # raises Kit::Webhooks::SignatureError
+delivery.events.each { |e| handle(e.type, e.data) unless seen?(e.id) }
+
+Kit::Webhooks::Events::SUBSCRIBER_TAG_ADDED           # => "subscriber.tag_added" (all 28 listed)
+```
+
+Signatures are HMAC-SHA256 over `"#{t}.#{raw_body}"` with a 300 s replay window;
+both secrets are accepted during a rotation.
+
 ### OAuth 2.0
 
 ```ruby
@@ -88,14 +121,18 @@ rejects it on the resource endpoints — account access needs the consent flow).
 The suite is layered:
 
 - **Unit** — every method against WebMock stubs.
-- **Contract** — each list resource is pinned to the vendored OpenAPI document,
-  so reading the wrong response envelope fails automatically.
+- **Contract** — every list and single-object operation, every create/update
+  request body, and every 204 response is pinned to the vendored OpenAPI
+  document, so reading the wrong envelope, sending an undocumented field, or
+  parsing a no-content response fails automatically. A weekly workflow diffs
+  the vendored document against Kit's and fails on drift.
 - **Integration** — real recorded responses (VCR cassettes, secrets scrubbed)
   replayed in CI, proving the live shapes still parse into our value objects.
 - **Smoke** — `rake smoke` hits every read endpoint live (needs `KIT_API_KEY`).
 - **E2E** — an opt-in (`KIT_E2E=1`) create→update→list→delete lifecycle that
   cleans up after itself.
-- **Types** — full RBS signatures, checked with Steep.
+- **Types** — full RBS signatures (explicit keywords on every create/update),
+  checked with Steep. Line and branch coverage are enforced at 90%.
 
 ```sh
 bin/setup
@@ -103,6 +140,11 @@ bundle exec rake        # spec + rubocop + steep
 bundle exec rake smoke  # live read-only smoke (needs a key)
 ```
 
+`bin/setup` points `core.hooksPath` at `.githooks/`, so a **pre-commit** hook
+runs RuboCop on staged Ruby files and a **pre-push** hook runs the full
+`bundle exec rake` gate. Both rely on exit codes, not parsed output — a red gate
+cannot be committed or pushed.
+
 ## License
 
 MIT.

data/docs/DESIGN.md

@@ -3,6 +3,11 @@
 A modern, fully-typed Ruby client for the **Kit** (formerly ConvertKit) **API v4**.
 The existing Ruby gems all stop at API v3/v2; kit-rb targets v4 to a high bar.
 
+> **Status: shipped.** All phases below are complete. v0.2.0 is on RubyGems;
+> the post-0.2.0 hardening pass (`docs/TASKS.md`) completed the surface to all
+> 83 documented operations, each pinned to the vendored OpenAPI document by
+> contract tests.
+
 ## Locked decisions
 
 | area | choice | why |
@@ -19,7 +24,7 @@ The existing Ruby gems all stop at API v3/v2; kit-rb targets v4 to a high bar.
 Kit::Client            # entry: picks an auth strategy, holds one Connection
  ├─ Kit::Configuration # immutable; validates exactly-one-credential
  ├─ Kit::Auth::ApiKey  # X-Kit-Api-Key header
- ├─ Kit::Auth::OAuth   # Bearer; authorize/refresh/PKCE land in P1
+ ├─ Kit::Auth::OAuth   # Bearer; authorize/exchange/refresh/PKCE/revoke/client_credentials
  ├─ Kit::Connection    # http.rb transport, JSON, auth injection, error mapping
  ├─ Kit::Error (tree)  # typed exceptions mapped from HTTP status
  ├─ Kit::Objects::*    # Data value objects, `.from(hash)` constructors
@@ -27,24 +32,43 @@ Kit::Client            # entry: picks an auth strategy, holds one Connection
 ```
 
 Facts pinned from the OpenAPI spec (`developers.kit.com/api-reference/v4.json`,
-OpenAPI 3.0.3, "Kit API 4.0", host `https://api.kit.com`, 52 paths): API-key
+OpenAPI 3.0.3, "Kit API 4.0", host `https://api.kit.com`, 52 paths / 83 operations,
+vendored to `spec/support/kit-v4.openapi.json`): API-key
 header `X-Kit-Api-Key`; OAuth authorize/token at `/v4/oauth/*`, scopes read/write;
 rate limits 120/60s (key) and 600/60s (OAuth); cursor pagination (`after`/`before`
 + `per_page`, response carries a `pagination` object).
 
-## Phases
+## Phases — all complete ✅
 
-- **P0 — foundations (this).** Gem skeleton on the clean `Kit` namespace, gates
+- **P0 — foundations. ✅** Gem skeleton on the clean `Kit` namespace, gates
   (rspec + rubocop + steep) green in CI (Ruby 3.2–3.4), and a walking-skeleton
   vertical slice: `GET /v4/account` end to end (auth → request → typed error →
   `Data` object) with full spec coverage.
-- **P1 — core, by hand.** Flesh out the transport: cursor auto-pagination
-  (lazy Enumerator), 429 rate-limit-aware retry with backoff, the full OAuth
-  authorization-code grant + refresh + PKCE, and instrumentation hooks.
-- **P2 — resources, spec-driven + local models.** One class + objects + specs per
-  resource group (subscribers, tags, custom fields, forms, sequences, broadcasts,
-  purchases, webhooks, email templates, segments, snippets), generated against
-  the OpenAPI spec via `forge`, gated by `rspec`/`steep`.
-- **P3 — quality.** Contract tests against the OpenAPI spec, edge cases
-  (pagination tail, nulls, large payloads), coverage floor.
-- **P4 — DX & release.** YARD docs, examples, signed gem, release automation.
+- **P1 — core, by hand. ✅** Cursor auto-pagination (lazy Enumerator, POST-based
+  lists supported), 429/5xx retry with backoff, and the full OAuth suite:
+  authorization-code grant, single-use refresh, PKCE (S256), RFC 7009 revocation,
+  and the client_credentials grant.
+- **P2 — resources, spec-driven + local models. ✅** Every resource group shipped
+  with objects + specs — subscribers, tags, custom fields, forms, sequences (+
+  emails), broadcasts (+ stats/clicks), purchases, webhooks, webhook endpoints,
+  email templates, segments, posts, snippets, account extras, and bulk. Early
+  batches were dogfooded through `forge` against a local model on mbp; that
+  surfaced the `Base#one`/`#collection` abstractions, after which the surface was
+  completed by hand. 81 operations shipped in 0.2.0; the two PATCH operations
+  landed in the hardening pass. **All 83 operations covered**, pinned by the
+  contract specs.
+- **P3 — quality. ✅** An OpenAPI list-envelope contract test (each list resource
+  pinned to the vendored spec), plus VCR integration cassettes (secrets scrubbed)
+  replayed in CI, `rake smoke` (live read-only), and an opt-in e2e lifecycle.
+  99%+ line coverage; full RBS checked by Steep.
+- **P4 — DX & release. ✅** README with usage/OAuth/testing docs, `rubygems_mfa_
+  required`, and a GitHub Actions **OIDC Trusted Publishing** workflow (tag `v*`
+  → gated release, no stored key). v0.1.0 and v0.2.0 published this way.
+  Deferred (optional): a hosted YARD site and cryptographic gem signing.
+- **P5 — hardening (2026-09-06). ✅** A full audit against the OpenAPI document
+  and the live docs, tracked row by row in `docs/TASKS.md`: two real-API bugs
+  (204 unsubscribe, dropped webhook secret), safety (credential masking, path
+  id validation, no POST replay, Retry-After cap), the missing PATCH
+  operations and response fields, incoming-webhook verification, typed bulk
+  results and transport errors, explicit keyword bodies with tightened RBS,
+  and contract tests over object envelopes, request bodies and 204s.

data/docs/TASKS.md

@@ -0,0 +1,47 @@
+# Tasks
+
+Progress tracker for the post-0.2.0 hardening pass. Each row lands as one atomic
+commit with its own specs; the row is ticked in the same commit. Findings come
+from the 2026-09-04 audit of the gem against the vendored OpenAPI document
+(`spec/support/kit-v4.openapi.json`, 52 paths / 83 operations) and the live docs.
+
+Legend: `[ ]` todo · `[x]` done (commit noted).
+
+## P0 — breaks against the real API
+
+- [x] `subscribers.unsubscribe` calls `one(...)` on a 204 no-body response → `NoMethodError`. (`fix: subscribers.unsubscribe handles the 204 no-content response`)
+- [x] `WebhookEndpoint` drops `secret`, the only time Kit returns the signing secret (`create`, `rotate_secret`). (`fix: WebhookEndpoint carries the one-time signing secret`)
+- [x] `Retry-After` on 429 is honoured without the `max_backoff` cap (a 30 s header blocks the caller for 60 s). (`fix: cap Retry-After at max_backoff`)
+- [x] Error-mapping specs really sleep: the 429 example alone costs 60 s per CI run. (`test: stop error-mapping specs from really sleeping`)
+- [x] Unexpected response shapes surface as `KeyError` / `NoMethodError` instead of a `Kit::Error`. (`fix: raise Kit::UnexpectedResponseError on drifted 2xx bodies`)
+- [x] Path ids are interpolated unescaped and unvalidated (`get("1/unsubscribe?x")`, `get(nil)`). (`fix: validate and percent-encode path ids`)
+- [x] Non-idempotent POSTs are retried on 5xx (duplicate creates). (`fix: do not replay POSTs after a 5xx`)
+
+## P1 — security / correctness
+
+- [x] `Client`, `Configuration`, `Auth::*`, `OAuth::Token` `#inspect` print the credential in plaintext. (`fix: mask credentials in inspect output`)
+- [x] `total_count` is discarded by `Pagination.from`; auto-paging resends `include_total_count` on every page; a `before:` param leaks into `after:` follow-ups. (`feat: surface total_count and fix follow-up page params`)
+- [x] No error classes for 409 (rotate_secret conflict) and 413 (bulk quota). (`feat: typed errors for 409 and 413`)
+- [x] 202 (async bulk) indistinguishable from 200; bulk methods return raw Hashes. (`feat: typed BulkResult with async (202) detection`)
+- [x] Error messages omit the request method and path. (`feat: name the failed request in APIError messages`)
+
+## P2 — API coverage
+
+- [x] `PATCH /v4/subscribers/{id}/location` (`subscribers.update_location`). (`feat: subscribers.update_location and stats date window`)
+- [x] `PATCH /v4/webhook_endpoints/{id}` (`webhook_endpoints.update`). (`feat: webhook_endpoints.update`)
+- [x] `sequences.get` / `sequences.email` cannot send `include=stats`; `subscribers.stats` cannot send `email_sent_after/before`. (`feat: include=stats on sequences.get and sequences.email`, `feat: subscribers.update_location and stats date window`)
+- [x] Missing response fields: `Account` (`timezone`, `plan`, `sending_addresses`), `Post#content`, `SequenceEmail#content`, `Subscriber` (`added_at`, `referrer`, `referrer_utm_parameters`, `tagged_at`, `attribution`, `tags`), `Tag#tagged_at`, `CustomField#created_at`. (`feat: complete the value objects against the spec's response schemas`)
+- [x] Incoming webhooks: `X-Kit-Signature` HMAC-SHA256 verification and delivery-envelope parsing. (`feat: verify and parse incoming webhook deliveries`)
+- [x] Webhook event-name constants. (`feat: webhook event-name constants`)
+
+## P3 — engineering quality / DX
+
+- [x] `Collection` lacks `size`, `empty?`, `[]`, and a readable `inspect`. (`feat: Collection#size, #empty?, #[] and a readable inspect`)
+- [x] Transport errors (timeouts, connection refused) collapse into the generic `Kit::Error`. (`feat: typed transport errors, retried for idempotent requests`)
+- [x] One `HTTP::Client` per request: no persistent connections. Client is now built once per Connection; true keep-alive (`HTTP.persistent`) is deliberately not used because it is not thread-safe while `Kit::Client` is documented as shareable. (`perf: build the http.rb client once per Connection`)
+- [x] Stale P0/P1 comments in `auth/oauth.rb`, `resources/account.rb`, `sig/kit-rb.rbs`; unused `Auth::OAuth::*_URL` constants; template comments in the gemspec. (`chore: drop stale phase comments, dead constants, and gemspec boilerplate`)
+- [x] README / DESIGN.md claim 81 operations; the spec has 83. (`docs: document the hardening pass in README, DESIGN and CHANGELOG`)
+- [x] CI matrix lacks Ruby 3.5; no Dependabot; no branch coverage. (`ci: test on Ruby 3.5, add Dependabot, enforce branch coverage`)
+- [x] RBS: 22 methods take `**untyped`; tighten the fixed-key bodies (broadcasts, sequences, sequence emails, snippets, purchases). List query params stay `**params`. (`refactor: explicit keyword bodies for create/update methods`)
+- [x] OpenAPI contract test covers only list envelopes; extend to single-object envelopes and request bodies. (`test: contract-check object envelopes, request bodies, and 204s against the spec`)
+- [x] `rake contract:fetch` is manual; add a scheduled drift check. (`ci: weekly OpenAPI drift check`)

data/lib/kit/auth/api_key.rb

@@ -19,6 +19,13 @@ module Kit
       def headers
         { HEADER => @key }
       end
+
+      # Never print the key: a client or config that ends up in a log line or an
+      # exception message must not leak the credential.
+      def inspect
+        "#<#{self.class.name} key=#{Credential.mask(@key)}>"
+      end
+      alias to_s inspect
     end
   end
 end

data/lib/kit/auth/credential.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Kit
+  module Auth
+    # Renders a secret for #inspect output: the last four characters behind a
+    # fixed-width mask, so two clients can be told apart in a log without the
+    # log ever containing a usable credential. Short secrets are fully masked.
+    module Credential
+      MASK = "****"
+      VISIBLE = 4
+
+      def self.mask(secret)
+        return "nil" if secret.nil?
+
+        value = secret.to_s
+        return MASK if value.length <= VISIBLE * 2
+
+        "#{MASK}#{value[-VISIBLE..]}"
+      end
+    end
+  end
+end

data/lib/kit/auth/oauth.rb

@@ -5,15 +5,9 @@ module Kit
     # OAuth 2.0 bearer-token authentication: sends `Authorization: Bearer <token>`.
     #
     # Rate limit is 600 requests / 60s, and OAuth is required for the bulk and
-    # purchase-creation endpoints.
-    #
-    # P0 scope: carry an already-obtained access token. The authorization-code
-    # grant (authorize/token URLs at /v4/oauth/*), refresh, and PKCE helper land
-    # in P1 — this class is the seam they plug into.
+    # purchase-creation endpoints. Obtaining and refreshing tokens is
+    # Kit::OAuth::Client's job; this class only carries an access token.
     class OAuth
-      AUTHORIZE_URL = "https://api.kit.com/v4/oauth/authorize"
-      TOKEN_URL = "https://api.kit.com/v4/oauth/token"
-
       def initialize(access_token)
         raise ConfigurationError, "OAuth access token cannot be blank" if access_token.nil? || access_token.empty?
 
@@ -23,6 +17,11 @@ module Kit
       def headers
         { "Authorization" => "Bearer #{@access_token}" }
       end
+
+      def inspect
+        "#<#{self.class.name} access_token=#{Credential.mask(@access_token)}>"
+      end
+      alias to_s inspect
     end
   end
 end

data/lib/kit/connection.rb

@@ -10,45 +10,74 @@ module Kit
   # Resources talk to the API only through this.
   class Connection
     JSON_TYPE = "application/json"
-    RETRYABLE = [RateLimitError, ServerError].freeze
+    RETRYABLE = [RateLimitError, ServerError, TransportError].freeze
+    # Verbs safe to replay after a 5xx: the server may have applied the request
+    # before failing, and replaying these cannot create a second resource.
+    IDEMPOTENT = %i[get head put delete].freeze
 
     def initialize(config)
       @config = config
+      # Built once: an http.rb client is an immutable options chain, safe to
+      # share across threads, and each request still opens its own socket.
+      # (HTTP.persistent would keep one socket alive but is not thread-safe,
+      # and a Client is documented as shareable — so it is not used.)
+      @client = HTTP
+                .headers(default_headers)
+                .timeout(connect: @config.open_timeout, read: @config.read_timeout)
     end
 
     # Issues a request and returns the parsed JSON body (a Hash) on success.
     # 429s honour `Retry-After`; 5xx use exponential backoff with jitter; both
     # give up after `config.max_retries` and re-raise the typed error.
     #
+    # A 429 is retried for every verb (Kit rejected the request, so nothing was
+    # applied). A 5xx or a transport failure (timeout, dropped connection) is
+    # retried only for idempotent verbs: a POST that created a subscriber
+    # before the gateway failed would be created twice.
+    #
     # @param method [Symbol] :get, :post, :put, :delete
     # @param path [String] e.g. "/v4/account" (leading slash, no host)
     # @param params [Hash] query string params
     # @param body [Hash, nil] JSON request body
     def request(method, path, params: {}, body: nil)
+      request_with_status(method, path, params: params, body: body).last
+    end
+
+    # As #request, but returns [status, body] for the callers that must tell a
+    # 200 (applied now) from a 202 (queued; the bulk endpoints).
+    def request_with_status(method, path, params: {}, body: nil)
       attempt = 0
       begin
-        handle(perform(method, path, params, body))
+        handle(perform(method, path, params, body), method, path)
       rescue *RETRYABLE => e
         attempt += 1
-        raise if attempt > @config.max_retries
+        raise if attempt > @config.max_retries || !retryable?(method, e)
 
         backoff_sleep(backoff_for(e, attempt))
         retry
       end
     end
 
+    # The memoised http.rb client carries the auth header, so the default
+    # inspect would print the credential.
+    def inspect
+      "#<#{self.class.name} base_url=#{@config.base_url.inspect} auth=#{@config.auth.inspect}>"
+    end
+
     private
 
-    def perform(method, path, params, body)
-      client.request(method, "#{@config.base_url}#{path}", params: params, json: body)
-    rescue HTTP::Error => e
-      raise Error, "HTTP transport error: #{e.message}"
+    def retryable?(method, error)
+      error.is_a?(RateLimitError) || IDEMPOTENT.include?(method)
     end
 
-    def client
-      HTTP
-        .headers(default_headers)
-        .timeout(connect: @config.open_timeout, read: @config.read_timeout)
+    def perform(method, path, params, body)
+      @client.request(method, "#{@config.base_url}#{path}", params: params, json: body)
+    rescue HTTP::TimeoutError => e
+      raise TimeoutError, "#{method.to_s.upcase} #{path} timed out: #{e.message}"
+    rescue HTTP::ConnectionError => e
+      raise ConnectionError, "#{method.to_s.upcase} #{path} could not connect: #{e.message}"
+    rescue HTTP::Error => e
+      raise TransportError, "#{method.to_s.upcase} #{path} failed in transport: #{e.message}"
     end
 
     def default_headers
@@ -59,12 +88,12 @@ module Kit
       }.merge(@config.auth.headers)
     end
 
-    def handle(response)
+    def handle(response, method, path)
       status = response.status.to_i
       parsed = parse(response)
-      return parsed if (200..299).cover?(status)
+      return [status, parsed] if (200..299).cover?(status)
 
-      raise error_for(status, parsed, response)
+      raise error_for(status, parsed, response, method, path)
     end
 
     def parse(response)
@@ -76,21 +105,25 @@ module Kit
       raw
     end
 
-    def error_for(status, body, response)
+    def error_for(status, body, response, method, path)
       klass = Error.class_for(status)
       if klass == RateLimitError
-        klass.new(status: status, body: body, response: response,
+        klass.new(status: status, body: body, response: response, method: method, path: path,
                   retry_after: response.headers["Retry-After"]&.to_i)
       else
-        klass.new(status: status, body: body, response: response)
+        klass.new(status: status, body: body, response: response, method: method, path: path)
       end
     end
 
     # Seconds to wait before the next attempt: the server's Retry-After when it
-    # sent one (429), else exponential backoff (base * 2^(n-1)) with jitter,
-    # capped at config.max_backoff.
+    # sent a usable one (429), else exponential backoff (base * 2^(n-1)) with
+    # jitter. Both are capped at config.max_backoff — a Retry-After of 300 must
+    # not block the caller for five minutes; past the cap the typed error is
+    # raised and the caller decides. A Retry-After that parses to 0 (an
+    # HTTP-date, or garbage) falls through to the exponential schedule.
     def backoff_for(error, attempt)
-      return error.retry_after if error.is_a?(RateLimitError) && error.retry_after
+      retry_after = error.retry_after if error.is_a?(RateLimitError)
+      return [retry_after, @config.max_backoff].min if retry_after&.positive?
 
       base = @config.retry_backoff * (2**(attempt - 1))
       [base + (rand * @config.retry_backoff), @config.max_backoff].min