bundle_update 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff9cacf9bd094dae3d26c13b3b405c2913b45015f89e1637851ff4e69465ece1
-  data.tar.gz: 709fa2001e10aa9b047c352bd4bc8e4c0f661c47ead65e2cd001bc2d270a7286
+  metadata.gz: dca4dd6ff6a6b352adc75bb532667af67aaaa9351ff97450195d01834c197508
+  data.tar.gz: cdb977853a4317e77999c161db056e1d074690d9a433f0e55bbc4cc8ab0224fb
 SHA512:
-  metadata.gz: cbb064521095197336c0702a80e473a57e6eeddb722cd0b358414f2b2a79ca9bffd14a13dc7c12607ef841cde7a80b91b658792e47365e6e31b49d8fda1cfc86
-  data.tar.gz: 899139a2be9bdf5cf7699c2296aee23f0f990382321ec2efb16c25c5a74a61102db2a7f389817a3afb72108ad10a6351241ee93f5cf6f9903a86a76d4bd5e424
+  metadata.gz: '097523c9cfac9ac26557a5cb159d307095f2ab9bb0f84cc92b50974a1ab1e47cc0d3dbe24f42319a4376de98a6952f1a0945aaf09eac93259ad3c97f54ff7e99'
+  data.tar.gz: 4b53e1c6e5a80f18417270f97b2d4dfd0ebec1b75af72fc017e37ae2b67176f71eb7ce270934a0204b80392a4ce00b25056c52d3027973775b23c240fb005192

data/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-13
+
+### Added
+
+- `bundle_update` CLI executable: wraps `bundle update`, forwarding all
+  arguments verbatim and preserving bundler's exit code exactly.
+  Subcommands `report`, `auth KEY`, `status`, and `version`, with a `--`
+  separator to force passthrough when a client gem is literally named
+  `report` or similar.
+- Bundler plugin mode (`bundle plugin install bundle_update`): the same
+  reporting pipeline runs automatically on `bundle install`/`bundle
+  update`, no CLI wrapper required.
+- Free tier (no API key): a lockfile diff classified into
+  major/minor/patch/other severities, printed as a terminal summary and
+  written as a local markdown report under `bundle_update_reports/`.
+  Works fully offline.
+- Paid tier (API key configured): POSTs both lockfiles to
+  bundleupdate.com and writes back the hosted changelog report — the
+  rich version on a synchronous cache hit, a link to poll later
+  (`bundle_update report`) on a cache miss. Any API failure — timeout,
+  connection error, malformed response, unexpected status — falls back
+  to the local report with exactly one warning line; never blocks or
+  fails the underlying `bundle update`.
+- Layered configuration: built-in defaults →
+  `~/.config/bundle_update/config.yml` → `./.bundle_update.yml` →
+  environment variables (`BUNDLE_UPDATE_API_KEY`, `BUNDLE_UPDATE_API_URL`,
+  `BUNDLE_UPDATE_DISABLED`, `BUNDLE_UPDATE_DEBUG`). API keys are always
+  masked wherever they might be echoed or logged.
+- Zero runtime dependencies — stdlib only (`net/http`, `json`, `yaml`,
+  `zlib`, `fileutils`, `optparse`, `openssl`).
+
+[Unreleased]: https://github.com/deadbro-com/bundle_update/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/deadbro-com/bundle_update/releases/tag/v0.1.0

data/DECISIONS.md

@@ -0,0 +1,129 @@
+# Decisions
+
+Ambiguities encountered while building this gem, and what was decided.
+Investigated against the actual installed Bundler source
+(`bundler-4.0.13`, satisfies `>= 2.3`) rather than guessed.
+
+## Bundler plugin hook names
+
+Bundler defines these plugin events in `lib/bundler/plugin/events.rb`:
+
+| Constant | String | Fired with | Fired from |
+|---|---|---|---|
+| `GEM_BEFORE_INSTALL_ALL` | `"before-install-all"` | `definition.dependencies` | `Bundler::Installer.install`, before `installer.run` |
+| `GEM_AFTER_INSTALL_ALL` | `"after-install-all"` | `definition.dependencies` | `Bundler::Installer.install`, after `installer.run` |
+| `GEM_BEFORE_INSTALL` / `GEM_AFTER_INSTALL` | per-gem | a `SpecInstallation` | `ParallelInstaller#install_gem_from_spec` |
+| `GEM_BEFORE_REQUIRE_ALL` / `GEM_AFTER_REQUIRE_ALL` | `"before-require-all"` / `"after-require-all"` | `dependencies` | `Runtime#require` |
+
+We use `before-install-all` / `after-install-all`. The per-gem hooks pass a
+`SpecInstallation` (one gem, install-time metadata) — not a lockfile
+snapshot, and firing once per gem is the wrong granularity for a
+whole-lockfile diff. The require-all hooks fire on `require`, not
+`install`/`update`, so they wouldn't fire at all for `bundle update
+--no-install`-style flows and fire at the wrong time (require, not
+install) otherwise.
+
+## Both `bundle install` and `bundle update` fire the same hooks
+
+`Bundler::Installer.install` is the single method both `cli/install.rb`
+and `cli/update.rb` call to do the actual install work — `bundle update`
+just builds a `Definition` that unlocks specific gems before calling it.
+Both hooks fire for a plain `bundle install` too. Decision: don't special
+case this in the plugin — `Runner#report` already no-ops silently on an
+empty diff, so a plain install (or a re-run with nothing to update) is a
+no-op through the normal fail-open path, not a separate code path.
+
+## Lockfile write timing relative to `after-install-all`
+
+Traced `Installer.install`:
+
+```ruby
+def self.install(root, definition, options = {})
+  installer = new(root, definition)
+  Plugin.hook(Plugin::Events::GEM_BEFORE_INSTALL_ALL, definition.dependencies)
+  installer.run(options)   # <- calls @definition.lock internally (installer.rb:232), which writes the file
+  Plugin.hook(Plugin::Events::GEM_AFTER_INSTALL_ALL, definition.dependencies)
+  installer
+end
+```
+
+On Bundler 4.0.13, the lockfile **is** already rewritten to disk by the
+time `after-install-all` fires, because `Installer#run` calls
+`@definition.lock` (which calls `write_lock`) before returning. This
+ordering isn't part of the documented plugin contract, though, and the
+task brief specifically flagged it as a known cross-version caveat — so
+we don't rely on it. Decision: in the `after-install-all` hook, prefer
+`Bundler.definition.to_lock` (`LockfileGenerator.generate(self)` — a pure
+computation from the already-resolved in-memory `Definition`, so it's
+correct regardless of whether the file has been flushed yet), and fall
+back to re-reading the file if that raises. An `at_exit` handler is
+registered as a last-resort second attempt, guarded so it never
+double-reports if the primary hook already succeeded.
+
+## Hook registration API and compatibility
+
+`Bundler::Plugin.add_hook(event, &block)` and `Bundler::Plugin.hook(event,
+*args)` are `module_function`s on `Bundler::Plugin` (`plugin.rb`).
+`PLUGIN_FILE_NAME = "plugins.rb"` — confirmed constant, loaded from the
+gem root via `Kernel#load(path, true)` (wrapped in an anonymous module,
+so top-level `require`s in `plugins.rb` still populate global constants
+normally — this is the standard pattern used by real-world Bundler
+plugins).
+
+Decision: `BundleUpdate::Plugin.install!` checks
+`Bundler::Plugin.respond_to?(:add_hook)` and
+`Bundler::Plugin::Events.defined_event?(name)` for both events before
+registering anything, and the whole method is wrapped in `rescue
+StandardError`. If a future or ancient Bundler renames/removes this API,
+`install!` silently returns `false` instead of raising — `plugins.rb`
+itself also wraps the `require`+`install!` call in a `begin/rescue`, so a
+plugin bug can never break the host's `bundle install`/`update`.
+
+## `--` separator for the subcommand/gem-name collision
+
+A client could have a gem literally named `report`, `auth`, `status`, or
+`version` and want `bundle_update report` to mean "update the gem named
+report", not run our `report` subcommand. Decision: `bundle_update --
+report` forwards everything after `--` to `bundle update` verbatim,
+bypassing subcommand detection entirely (`bundle_update -- --conservative
+report` → `bundle update --conservative report`). Without `--`, a
+recognized subcommand name in the first position is always treated as
+ours — this matches the common CLI convention (git, npm, etc.) and keeps
+the common case (no collision) simple.
+
+## API key masking format
+
+The brief showed `bu_live_a1b2…` as an example. Decision: reveal at most
+`min(length - 4, 12)` leading characters, then `…`; keys of 4 characters
+or fewer reveal nothing (`…`). This mirrors how Stripe/GitHub-style
+tokens are usually masked — enough to recognize which key you're looking
+at, never enough to reconstruct it.
+
+## `bundle_update status` API reachability check
+
+The brief asks for "API reachability" in `status` output. Decision: this
+is a bare TCP/TLS connect to the configured API host (`Net::HTTP#start`
+with a 2s timeout), not a call against the `/api/v1/reports` contract —
+reachability shouldn't depend on report-endpoint semantics, and we
+didn't want to invent an undocumented health-check endpoint.
+
+## Report filename collisions within the same second
+
+`ReportWriter` originally wrote `<timestamp>_report.md` with
+second-granularity timestamps. Two runs completing in the same second (a
+path-sourced gem update runs in well under a second) collided. The first
+fix (append a bare `-2` suffix on collision) was itself broken: `-2` (
+`-` = 0x2D) sorts *before* the plain filename (`_` = 0x5F) in ASCII, so
+`Dir.glob(...).last` could return the *older* report. Fixed by always
+writing a zero-padded sequence (`<timestamp>_01_report.md`,
+`<timestamp>_02_report.md`, ...), which sorts correctly in write order.
+Caught by the real end-to-end integration spec, not a unit test — worth
+noting since it's exactly the kind of ordering bug that only shows up
+against a real, fast filesystem round-trip.
+
+## Zero runtime dependencies, dev deps in the Gemfile
+
+`bundle_update.gemspec` declares zero runtime dependencies. Development
+dependencies (rspec, webmock, rubocop, rake) live in the `Gemfile`, not
+the gemspec (`Gemspec/DevelopmentDependencies` — the modern Bundler
+convention), so `gem install bundle_update` never resolves them.

data/Gemfile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+group :development, :test do
+  gem "bundler", ">= 2.3"
+  gem "rake", "~> 13.0"
+  gem "rspec", "~> 3.13"
+  gem "rubocop", "~> 1.65"
+  gem "webmock", "~> 3.23"
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emanuel Comsa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -1,3 +1,234 @@
 # bundle_update
 
-Placeholder gem to reserve the name. No functionality.
+`bundle_update` wraps `bundle update` / `bundle install`, diffs your
+`Gemfile.lock` before and after, and tells you what changed —
+major/minor/patch counts and a per-gem table, printed to your terminal and
+saved as markdown. With a [bundleupdate.com](https://www.bundleupdate.com)
+API key it also fetches a full changelog report for every updated gem.
+
+Works completely offline with no API key. Zero runtime dependencies.
+Never blocks, slows down, or fails your `bundle update` — see
+[Fail-open guarantee](#fail-open-guarantee).
+
+## 30-second quickstart (CLI mode)
+
+```bash
+gem install bundle_update
+```
+
+Then use `bundle_update` exactly where you'd use `bundle update`:
+
+```bash
+bundle_update                  # instead of: bundle update
+bundle_update sidekiq --strict # instead of: bundle update sidekiq --strict
+```
+
+That's it. On success, you'll see a summary like:
+
+```
+1 major, 1 minor, 1 patch updates
+
+Major
+  rack   2.2.6.4 → 3.0.8
+Minor
+  rake   13.0.6 → 13.1.0
+Patch
+  rexml  3.2.5 → 3.2.6
+
+Report written to bundle_update_reports/20260713120000_01_report.md
+```
+
+and a markdown file under `bundle_update_reports/`. If `bundle update`
+fails, `bundle_update` prints nothing extra and exits with bundler's exact
+exit code — nothing about your workflow changes.
+
+Add an API key (see [Free vs. paid tier](#free-vs-paid-tier)) and you'll
+also get a hosted changelog report:
+
+```bash
+bundle_update auth bu_live_your_key_here
+```
+
+## Plugin mode (zero-effort)
+
+Skip the `bundle_update` wrapper entirely and have the report generate
+automatically on every `bundle install`/`bundle update`:
+
+```bash
+bundle plugin install bundle_update
+```
+
+From then on, plain `bundle update` (run by you, a script, or a
+teammate who's never heard of this gem) triggers the same reporting
+pipeline. A plain `bundle install` with no lockfile changes stays
+silent — nothing is printed and no report is written.
+
+Plugin mode and the CLI wrapper can be used together or independently;
+they share the same configuration and the same `bundle_update_reports/`
+output directory.
+
+## Free vs. paid tier
+
+| | Free (no API key) | Paid (API key configured) |
+|---|---|---|
+| Works offline | Yes | No (falls back to free tier on any network issue) |
+| Version diff, severity classification | Yes | Yes |
+| Terminal summary | Yes | Yes |
+| Local markdown report | Yes | Yes, replaced by the hosted report when available |
+| Per-gem changelog / release notes | No | Yes |
+| Security advisory notes | No | Yes |
+| Hosted, shareable report URL | No | Yes |
+
+The server pre-warms changelog data for every gem in your `Gemfile` via
+an hourly crawler, so the API call is expected to be fast (typically
+under 3 seconds) and synchronous. On a cache miss, you get a link to poll
+later with `bundle_update report`.
+
+### Sample: free tier report (`bundle_update_reports/*.md`)
+
+```markdown
+# bundle_update report — my-app
+
+_2026-07-13 12:00 +0000_
+
+## Summary
+
+- 1 major, 1 minor, 1 patch updates
+- 1 gem added
+
+## Security
+
+_Security advisory checks aren't available in the free tier. [Get a
+bundleupdate.com API key](https://www.bundleupdate.com) for CVE-aware
+changelog reports._
+
+## Changes
+
+### Major
+
+| Gem | From | To |
+|---|---|---|
+| rack | 2.2.6.4 | 3.0.8 |
+
+### Minor
+
+| Gem | From | To |
+|---|---|---|
+| rake | 13.0.6 | 13.1.0 |
+```
+
+### Sample: paid tier report (cache miss, 202)
+
+```markdown
+# bundle_update report — my-app
+...(same local summary as above)...
+
+---
+
+**Full changelog report generating:** https://www.bundleupdate.com/r/abc123
+
+Run `bundle_update report` to fetch the complete version once it's ready.
+```
+
+On a cache hit (200), the file is replaced entirely by the rich markdown
+bundleupdate.com returns — full changelogs, breaking-change notes, and
+security advisories per gem.
+
+## Configuration reference
+
+Each layer overrides the one before it: built-in defaults →
+`~/.config/bundle_update/config.yml` → `./.bundle_update.yml`
+(per-project — handy for agencies running per-client keys) → environment
+variables.
+
+| Key (YAML) | Env var | Default | Notes |
+|---|---|---|---|
+| `api_key` | `BUNDLE_UPDATE_API_KEY` | _(none)_ | Never put this in your `Gemfile`. `bundle_update auth KEY` writes it to the user-level config file. |
+| `api_url` | `BUNDLE_UPDATE_API_URL` | `http://bundleupdate.test` _(temporary — will be `https://bundleupdate.com` at launch)_ | Override for a staging/dev backend. |
+| `project_name` | _(none)_ | git remote basename, else directory name | Shown as the report title. |
+| `git_remote_url` | _(none)_ | normalized git remote (`host/path`), else _(none)_ | Identifies the project on bundleupdate.com — required, so a repo with no git remote configured can't submit a report. Survives directory renames and `project_name` changes. |
+| `reports_dir` | _(none)_ | `bundle_update_reports` | Where markdown reports are written. |
+| `disabled` | `BUNDLE_UPDATE_DISABLED` | `false` | Set to skip the reporting pipeline entirely — bundler behavior is completely unaffected either way. |
+| `debug` | `BUNDLE_UPDATE_DEBUG` | `false` | See [Troubleshooting](#troubleshooting). |
+
+```yaml
+# .bundle_update.yml (per project) or ~/.config/bundle_update/config.yml
+api_key: bu_live_...
+project_name: my-app
+```
+
+## Fail-open guarantee
+
+`bundle_update` is designed to never be the reason your `bundle update`
+is slow, noisy, or broken:
+
+- The entire reporting pipeline runs after bundler has already finished
+  and exited successfully — it never delays or blocks the bundler
+  process itself.
+- A `bundle update`/`bundle install` failure is passed straight through:
+  exact exit code, no extra output, no reporting attempted.
+- If an API key is configured and the API call fails for any reason
+  (timeout, connection error, bad response, unexpected status), you get
+  **exactly one** short warning line and a local report — never a crash,
+  never a hang.
+- If something goes wrong in the local pipeline itself (a bug in this
+  gem, a permissions error, anything), it prints nothing and exits
+  cleanly. Your bundle run is unaffected either way.
+- In plugin mode, every hook body is wrapped so an exception here can
+  never propagate into your `bundle install`/`update`.
+
+## Privacy
+
+When an API key is configured, `bundle_update` sends exactly this to
+`POST https://bundleupdate.com/api/v1/reports` (gzipped JSON,
+`Authorization: Bearer <key>`) — nothing else:
+
+```json
+{
+  "project": "my-app",
+  "lockfile_before": "<raw Gemfile.lock content before the update>",
+  "lockfile_after": "<raw Gemfile.lock content after the update>",
+  "gem_version": "0.1.0",
+  "ran_at": "2026-07-13T12:00:00Z"
+}
+```
+
+No environment variables, no other file contents, no git history, no
+Ruby/OS version scanning beyond what's already in the lockfile itself.
+Without an API key configured, `bundle_update` makes no network requests
+at all.
+
+## Troubleshooting
+
+- **Nothing happens after `bundle update`.** That's expected when nothing
+  changed in `Gemfile.lock` (e.g. a plain `bundle install`, or an update
+  that resolved to the same versions) — no report is written, by design.
+- **A report never shows up even though gems clearly changed.** Set
+  `BUNDLE_UPDATE_DEBUG=1` and re-run. Full backtraces are written to
+  `.bundle_update/debug.log` (never to your terminal) instead of being
+  swallowed silently.
+- **Paid tier keeps falling back to the free tier.** Run `bundle_update
+  status` to check your key and API reachability. Check
+  `.bundle_update/debug.log` (with `BUNDLE_UPDATE_DEBUG=1`) for the
+  underlying network error.
+- **I don't want this running at all, temporarily.**
+  `BUNDLE_UPDATE_DISABLED=1 bundle_update` (CLI mode), or set it in your
+  shell profile / CI env to cover plugin mode too.
+- **A client gem is literally named `report`, `auth`, `status`, or
+  `version`.** Use `bundle_update -- report` — everything after `--` is
+  forwarded to `bundle update` verbatim, bypassing subcommand detection.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+See [DECISIONS.md](DECISIONS.md) for the Bundler internals this gem's
+plugin mode relies on, and why.
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/bundle_update.gemspec

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "lib/bundle_update/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "bundle_update"
+  spec.version = BundleUpdate::VERSION
+  spec.authors = ["Emanuel Comsa"]
+  spec.email = ["office@rubydev.ro"]
+
+  spec.summary = "Reports what changed after `bundle update` — free local summaries, optional hosted changelog reports."
+  spec.description = <<~DESC
+    bundle_update wraps `bundle update` / `bundle install`, diffs your Gemfile.lock
+    before and after, and prints a concise summary of what changed (major/minor/patch).
+    With a bundleupdate.com API key it also fetches a rich changelog report for every
+    updated gem. Works fully offline with no API key. Zero runtime dependencies.
+  DESC
+  spec.homepage = "https://www.bundleupdate.com"
+  spec.license = "MIT"
+
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/deadbro-com/bundle_update"
+  spec.metadata["changelog_uri"] = "https://github.com/deadbro-com/bundle_update/blob/main/CHANGELOG.md"
+  spec.metadata["bug_tracker_uri"] = "https://github.com/deadbro-com/bundle_update/issues"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  gemspec_dir = __dir__
+  spec.files = Dir.chdir(gemspec_dir) do
+    Dir.glob("**/*", File::FNM_DOTMATCH).select { |f| File.file?(f) }.reject do |f|
+      f.start_with?(".git/", "spec/", "sig/", ".github/") ||
+        f.match?(/\A(?:\.gitignore|\.rspec|\.rubocop\.yml|Gemfile\.lock|Rakefile)\z/) ||
+        f.end_with?(".gem")
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = ["bundle_update"]
+  spec.require_paths = ["lib"]
+
+  # Zero runtime dependencies by design — only stdlib (net/http, json, yaml,
+  # zlib, fileutils, optparse). Bundler is a host-provided dependency, not
+  # a gem dependency: it is always present wherever this gem runs. Dev
+  # dependencies live in the Gemfile, not here.
+end

data/exe/bundle_update

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundle_update"
+require "bundle_update/cli"
+
+exit(BundleUpdate::CLI.start(ARGV))

data/lib/bundle_update/api_client.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "uri"
+require "json"
+require "zlib"
+require "stringio"
+require "time"
+
+module BundleUpdate
+  # Talks to the bundleupdate.com API over Net::HTTP with zero gem
+  # dependencies. Never raises: every failure mode (timeout, connection
+  # refused, malformed JSON, HTTP error status) comes back as a Response with
+  # status: :error so callers can fail open without a rescue of their own.
+  class ApiClient
+    Response = Struct.new(:status, :report_id, :url, :markdown, :error, :error_detail, keyword_init: true) do
+      def ready?
+        status == :ready
+      end
+
+      def pending?
+        status == :pending
+      end
+
+      def error?
+        status == :error
+      end
+    end
+
+    OPEN_TIMEOUT = 2
+    READ_TIMEOUT = 8
+
+    RETRYABLE_ERRORS = [
+      Errno::ECONNREFUSED,
+      Errno::ECONNRESET,
+      Errno::ETIMEDOUT,
+      Errno::EHOSTUNREACH,
+      SocketError,
+      Net::OpenTimeout,
+      Net::ReadTimeout,
+      IOError,
+      OpenSSL::SSL::SSLError
+    ].freeze
+
+    def initialize(config)
+      @config = config
+    end
+
+    # POST /api/v1/reports — expects 200 (cache hit, synchronous markdown),
+    # 202 (cache miss, generating async), 401 (bad key), or 422 (validation).
+    def create_report(lockfile_before:, lockfile_after:, ran_at:)
+      payload = {
+        project: @config.project_name,
+        git_remote_url: @config.git_remote_url,
+        lockfile_before: lockfile_before,
+        lockfile_after: lockfile_after,
+        gem_version: BundleUpdate::VERSION,
+        ran_at: ran_at.utc.iso8601
+      }
+      request(:post, "/api/v1/reports", payload)
+    end
+
+    # GET /api/v1/reports/:id — used by `bundle_update report` to poll a
+    # report that was still generating when create_report returned 202.
+    def fetch_report(report_id)
+      request(:get, "/api/v1/reports/#{report_id}")
+    end
+
+    private
+
+    def request(method, path, payload = nil)
+      perform(method, path, payload)
+    rescue *RETRYABLE_ERRORS
+      begin
+        perform(method, path, payload)
+      rescue *RETRYABLE_ERRORS => e
+        Response.new(status: :error, error: :connection_failed, error_detail: e.message)
+      end
+    end
+
+    def perform(method, path, payload)
+      uri = URI.join(@config.api_url, path)
+      http_response = build_http(uri).request(build_request(method, uri, payload))
+      parse_response(http_response)
+    end
+
+    def build_http(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = OPEN_TIMEOUT
+      http.read_timeout = READ_TIMEOUT
+      http
+    end
+
+    def build_request(method, uri, payload)
+      request = method == :post ? Net::HTTP::Post.new(uri) : Net::HTTP::Get.new(uri)
+      request["Authorization"] = "Bearer #{@config.api_key}"
+      request["User-Agent"] = "bundle_update/#{BundleUpdate::VERSION}"
+      if payload
+        request["Content-Type"] = "application/json"
+        request["Content-Encoding"] = "gzip"
+        request.body = gzip(JSON.generate(payload))
+      end
+      request
+    end
+
+    def parse_response(http_response)
+      case http_response.code.to_i
+      when 200
+        with_parsed_body(http_response) do |data|
+          Response.new(status: :ready, report_id: data["report_id"], url: data["url"], markdown: data["markdown"])
+        end
+      when 202
+        with_parsed_body(http_response) do |data|
+          Response.new(status: :pending, report_id: data["report_id"], url: data["url"])
+        end
+      when 401
+        Response.new(status: :error, error: :unauthorized)
+      when 422
+        Response.new(status: :error, error: :validation_error, error_detail: http_response.body)
+      else
+        Response.new(status: :error, error: :http_error, error_detail: http_response.code)
+      end
+    end
+
+    def with_parsed_body(http_response)
+      data = JSON.parse(http_response.body.to_s)
+      yield data
+    rescue JSON::ParserError, TypeError
+      Response.new(status: :error, error: :malformed_response)
+    end
+
+    def gzip(string)
+      io = StringIO.new
+      writer = Zlib::GzipWriter.new(io)
+      writer.write(string)
+      writer.close
+      io.string
+    end
+  end
+end