rate-card 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 45fc9c209efdd18d8586a8cbbb2e02ff0c83c410c2d27c75762dd93999b9276a
-  data.tar.gz: a0aaf2c79154dc92586953af3c9a89abfe7997cbab3825ba9188e53bd250c730
+  metadata.gz: 320d6905617967d73305befafac57482eed231ff28b39d3282d61a8ae31549ff
+  data.tar.gz: a54e83be25c1f657dd5fe6eb4a416a02a8fb1f88e38439523f43d2a1c9fd9878
 SHA512:
-  metadata.gz: 520df789fc49541ed4254432db087d217ecf66b5367f5d3a25564334fc9ef80712a246e874a309f87ee843cbb73cf5d60656d7e2c31f72c3f30a82e62020c988
-  data.tar.gz: 6cfb5ebd7544fb624fac46a6bc8567dd0175814b2f1116cd7ef7d8a111f1b9c099922d0b2cea8b7264b5e12446701214ffe44a66302b368c070b3417566bbf8c
+  metadata.gz: d4c28f5cc71b01a00e5e7cd41e785acda43c117d26c456ea313239819fb95b9779efdc0a7b20c20f96a5013049e108c715386bdc28337e7d7bfbc14f0c917c07
+  data.tar.gz: c02ecec88df73aa9fa01d33cd6107d8b1e4911e367bc6d54bb996a92834ee4cfce6add454a5b5209b283509322d276e44548f263af07eaad74fe8e40d4c10f20

data/README.md

@@ -1,226 +1,34 @@
 # rate-card
 
 Interactive CLI that generates a shipping rate card — a weight × zone grid of rates — from the
-**eHub production API**. Prints the card to your terminal and saves CSVs to `~/Downloads`.
+eHub production API. Prints the card to your terminal and saves CSVs to `~/Downloads`.
 
 ## Install
 
-Homebrew — nothing else needed, and no Ruby setup of your own:
-
-```bash
-brew install jxsoren/tools/rate-card
-rate-card
-```
-
-> The tap repo (`jxsoren/homebrew-tools`) does not exist yet, so this command does not
-> work until it is created — see **Release** below. The gem install underneath it does.
-
-Homebrew installs its own Ruby and keeps every gem inside the keg, so this cannot
-collide with an rbenv or system Ruby you already have.
-
-If you already work in Ruby, the gem is equivalent:
-
-```bash
-gem install rate-card
-```
-
-To upgrade: `brew upgrade rate-card`, or `gem update rate-card`.
-
-## Develop
-
 ```bash
-bundle install
-bundle exec exe/rate-card
-NO_COLOR=1 bundle exec rspec
+cd ~ && brew install jxsoren/tools/rate-card
 ```
 
-`NO_COLOR=1` is required when running the specs from a terminal — five specs assert on
-uncoloured rendered output, and lipgloss colours whenever stdout is a tty. See the comment
-in `spec/spec_helper.rb`.
-
-Ruby 3.3.4 (pinned in `.ruby-version`); the gemspec floor is 3.2, and Homebrew currently
-builds against Ruby 4.0.
-
-The TUI is [bubbletea-ruby](https://github.com/marcoroth/bubbletea-ruby) with `bubbles` and
-`lipgloss`. These ship precompiled native binaries, so no Go toolchain is needed to install
-them. Note that `bubbles` is a shared gem name — `0.0.x` is an unrelated gem that pulls in
-`aws-sdk` — which is why the gemspec pins `~> 0.1`.
-
-## Release
-
-Bump `lib/rate_card/version.rb`, commit, then:
+Then run it:
 
 ```bash
-bin/release
+rate-card
 ```
 
-That runs the specs, builds and pushes the gem, and rewrites the formula's `url` and
-`sha256` to match what was pushed. The tap commit is left to you — see the script's
-closing output. `packaging/homebrew/rate-card.rb` is the source of truth for the formula;
-the tap's `Formula/rate-card.rb` is a copy.
-
-## Use
+If you already work in Ruby, the gem is equivalent:
 
 ```bash
-bundle exec exe/rate-card
+gem install rate-card
 ```
 
-No flags needed — the wizard asks for everything:
-
-1. **eHub API token** — pasted, masked. Decoded so you can confirm the account before the run
-   starts. Never written to disk. A malformed token re-prompts rather than ending the run.
-2. **Rate by** — Weight or Cubic dimensions. Only asked when the token has USPS
-   services, since USPS cubic pricing (Ground Advantage Cubic, Priority Mail Cubic) is
-   priced by which of ten official volume tiers the package falls into, not by weight.
-   Choosing Cubic restricts the carrier to USPS and replaces the weight-unit and
-   weight-range questions with a multi-select of the ten tiers. Choosing Cubic does not check
-   that the service you go on to pick is actually cubic-priced — you're responsible for
-   selecting a cubic-rated USPS service (e.g. "USPS Ground Advantage Cubic").
-3. **Carrier**, then **services** — the list comes from the customer's own service catalogue
-   (`GET /api/v2/services?category=shipping`), so it is exactly what that customer has enabled,
-   including services that would not quote at a single probe weight.
-4. **Zones** (`1-8`, or `1,3,5`); then, in weight mode, **weight unit** (`oz`/`lbs`) and
-   **weight range** — or, in cubic mode, the **cubic tiers** to include; then
-   **package type**, **rate columns** (shipper rate, meter rate).
-5. A recap of every answer, with the call count, and a **Run** / **Back** choice. It opens on
-   **Back**, so a stray enter carried over from the previous question goes back rather than
-   spending 128 production calls; `ctrl-c` abandons the session outright.
-
-Bad input at the zone or weight prompt re-prompts; it never costs you the run.
-
-`esc` steps back to the previous question at any point in the wizard, including from the recap.
-The question you land on reopens on the answer it already has; the answers that came *after* it
-are forgotten, since they were given against a choice you are about to change.
-
-### Keys
-
-| Key | Effect |
-| --- | --- |
-| `↑` / `↓`, `k` / `j` | Move between choices |
-| `space` | Tick or untick (services, rate columns) |
-| `a` | Tick or untick everything |
-| `enter` | Confirm the answer |
-| `esc` | Go back to the previous question |
-| `ctrl-c` | Abandon the run at any point |
-
-Answered questions stay on screen as you go, and the fetch shows a live bar with a running
-count of failed cells — so a run that is going wrong can be abandoned early rather than waited
-out.
-
-### One caveat: paste only the token
-
-The token prompt is deliberately a plain readline **before** the TUI starts, because
-bubbletea-ruby 0.1.4's input reader returns one key per poll and discards the rest of the
-buffered bytes: a pasted 200-character JWT arrives as a single character. Typing is unaffected
-at any speed, so every other answer is safe inside the TUI — but **type** the zone and weight
-ranges rather than pasting them.
-
-To reproduce the underlying bug: run a bare Bubbletea model that logs every `KeyMessage`, then
-write 36 bytes to its pty in one call. One message arrives, carrying one rune; the other 35
-bytes are discarded.
-
-For a bare `rate-card` command:
+## Update
 
 ```bash
-ln -s "$PWD/exe/rate-card" ~/bin/rate-card
+cd ~ && brew update && brew upgrade rate-card
 ```
 
-### Flags
-
-| Flag | Effect |
-| --- | --- |
-| `--output-dir DIR` | Save CSVs somewhere other than `~/Downloads/rate_cards` |
-| `--no-table` | Skip printing tables to stdout |
-| `--version`, `--help` | As expected |
-
-Everything else is interactive by design — a second input path would let flags and wizard
-answers disagree.
-
-## Output
-
-Both to your terminal and to disk:
-
-```
-  ops@acme.test (1042) · USPS Ground Advantage · shipper rate
-┌────────┬──────┬──────┬──────┬──────┬──────┬──────┬──────┬──────┐
-│ wt(oz) │   Z1 │   Z2 │   Z3 │   Z4 │   Z5 │   Z6 │   Z7 │   Z8 │
-├────────┼──────┼──────┼──────┼──────┼──────┼──────┼──────┼──────┤
-│      1 │ 1.11 │ 2.22 │ 3.33 │ 4.44 │ 5.55 │ 6.66 │ 7.77 │ 8.88 │
-│      2 │ 2.11 │ 3.22 │ 4.33 │ 5.44 │    — │ 7.66 │ 8.77 │ 9.88 │
-└────────┴──────┴──────┴──────┴──────┴──────┴──────┴──────┴──────┘
-
-  ⚠ 1 cell failed
-      wt 2  Z5  → 500 upstream carrier error
-
-  ✓ Saved 2 files to ~/Downloads/rate_cards/ops_acme_test_1042_2026-09-01T12-00-00Z
-      GroundAdvantage_shipper_rate.csv
-      GroundAdvantage_meter_rate.csv
-```
-
-The rates above are invented placeholders, not a real quote.
-
-One CSV per service per rate column. Header is `weight` plus one column per zone. The run
-directory is timestamped, so a new card never clobbers an old one.
-
-**A missing rate is an empty cell, never `0.00`.** A zero in a rate table reads as a genuine
-free rate; `../rate_table_builder` writes `0.0` there and this tool deliberately does not.
-Failures are listed after the tables with weight, zone and reason, and a run with holes still
-writes its files.
-
-## Call volume
-
-One API call per (weight × zone). **Services are free**: one response carries every service the
-customer has enabled, so checking six costs the same as one. A 16-weight, 8-zone card is 128
-calls, fanned out 8 at a time.
-
-Two distinct no-output cases, which the tool does not conflate:
-
-- **Every call failed** → likely network or token.
-- **Calls succeeded but nothing was priced** → your service, package type or weight range.
-  USPS First Class is not quoted above 13 oz, for instance.
-
-A carrier failure is not a failed call: eHub answers 201 and puts the reason in the response
-`warnings` array, or in a service's `errors` field. Both are reported under
-*the API reported N warnings*, deduplicated with an occurrence count.
-
-## Tests
+## Uninstall
 
 ```bash
-NO_COLOR=1 bundle exec rspec
+brew uninstall rate-card
 ```
-
-**No test contacts production** — `Client` is the only network seam, and specs stub it via
-Faraday's test adapter.
-
-## Design
-
-The wizard's only product is a validated `RunSpec`; everything downstream consumes only that.
-So the fetch/assemble/render engine is testable with no prompting and no network.
-
-| File | Responsibility |
-| --- | --- |
-| `exe/rate-card` | Entrypoint: flags → wizard → runner. Every error becomes one clean line |
-| `client.rb` | The only network seam. Every outcome becomes a Hash, `Unauthorized`, or `RequestFailed` |
-| `token.rb` | Decodes the JWT payload to name the account. Does not verify the signature |
-| `service_catalog.rb` | Service catalogue response → `Service` objects, grouped by carrier |
-| `run_spec.rb` | The validated inputs for one run |
-| `shipment.rb` | One (weight, zone) request payload |
-| `grid.rb` | Fans out the calls, assembles cells and failures |
-| `csv_writer.rb` / `table_renderer.rb` | Peers reading the same `Grid`, so files and terminal cannot disagree |
-| `ui.rb` | Every byte the tool prints |
-| `wizard.rb` / `runner.rb` | Ask; then orchestrate |
-
-`constants/addresses.rb` holds hand-verified zone addresses — zone membership is a property of
-a real address and a carrier's zone chart, so it is never derived at runtime.
-
-## Related tools
-
-- `../rate_sheet_builder` — batch, multi-customer, YAML roster. Use it for many customers at once.
-- `../rate_table_builder` — the abandoned predecessor to this tool.
-
-## Not done
-
-`spec/fixtures/rates_response.json` was never captured, so no test pins the production response
-field names (`service_rates`, `service_id`, `rate`, `meter_rate`, `errors`). If eHub renames one, the tool
-will produce empty cells rather than failing loudly. Capturing one real response would close
-that gap — see Task 16 of `docs/superpowers/plans/2026-08-31-rate-card-cli.md`.

data/exe/rate-card

@@ -14,6 +14,8 @@ options = { output_base: DEFAULT_OUTPUT_BASE, show_table: true }
 parser = OptionParser.new do |opts|
   opts.banner = 'Usage: rate-card [options]'
   opts.separator ''
+  # eHub is the only registered provider today (see RateCard::Providers) — this
+  # line should name the provider generically once a second one exists.
   opts.separator 'Generates a shipping rate card from the eHub production API.'
   opts.separator 'All rate-card inputs are collected interactively.'
   opts.separator ''
@@ -48,11 +50,14 @@ end
 ui = RateCard::UI.new(io: $stdout)
 ui.banner
 
+provider_key = RateCard::ProviderPrompt.read(ui: ui)
+provider = RateCard::Providers.build(provider_key)
+
 # Read before the TUI starts. bubbletea-ruby 0.1.4 drops all but the first
-# character of a pasted burst, and the token is the one answer that is always
-# pasted; out here the terminal's own line editing handles it. See TokenPrompt.
-token = RateCard::TokenPrompt.read(ui: ui)
-if token.nil?
+# character of a pasted burst, and the credential is the one answer that is
+# always pasted; out here the terminal's own line editing handles it.
+credential = provider.read_credential(ui: ui)
+if credential.nil?
   ui.info('Cancelled — nothing was built.')
   exit 0
 end
@@ -60,7 +65,7 @@ end
 # The TUI owns the terminal from here until it quits: the catalogue lookup, the
 # remaining answers and the fetch all happen inside its event loop. Reporting
 # happens after, on a terminal that has been handed back.
-app = RateCard::TUI::App.new(token: token, output_base: options[:output_base])
+app = RateCard::TUI::App.new(token: credential, output_base: options[:output_base], provider: provider)
 runner = Bubbletea::Runner.new(app)
 app.notifier = runner
 
@@ -82,6 +87,8 @@ end
 case app.error
 when nil then nil
 when RateCard::Unauthorized
+  # Wording is eHub-specific — fine while eHub is the only registered provider;
+  # generalize once a second one exists.
   ui.error('Production rejected that token. Check it is a current eHub API token.')
   exit 1
 when RateCard::NoServices

data/lib/rate_card/constants/addresses.rb

@@ -65,7 +65,12 @@ module RateCard
       # calculator, split this back into its own hand-verified hash.
       DHL_ECOMMERCE = USPS
 
-      BY_CARRIER = { 'USPS' => USPS, 'UPS' => UPS, 'FedEx' => FEDEX, 'DHL' => DHL_ECOMMERCE }.freeze
+      # OSM's zone calculator in ehub (app/services/carriers/osm/zone_calculator.rb)
+      # is likewise an unmodified subclass of USPS's, so OSM zones are USPS
+      # zones - same reasoning as DHL_ECOMMERCE above.
+      OSM = USPS
+
+      BY_CARRIER = { 'USPS' => USPS, 'UPS' => UPS, 'FedEx' => FEDEX, 'DHL' => DHL_ECOMMERCE, 'OSM' => OSM }.freeze
 
       module_function
 

data/lib/rate_card/constants/carriers.rb

@@ -7,7 +7,7 @@ module RateCard
     module Carriers
       OTHER = 'Other'
 
-      DISPLAY_ORDER = ['USPS', 'UPS', 'FedEx', 'DHL', 'Amazon', OTHER].freeze
+      DISPLAY_ORDER = ['USPS', 'UPS', 'FedEx', 'DHL', 'OSM', 'Amazon', OTHER].freeze
 
       # Every /services entry carries a lowercase carrier_code. Anything not
       # listed here keeps its own code, upcased: an unrecognised carrier is
@@ -27,7 +27,7 @@ module RateCard
       # silently inherit the wrong zone chart.
       CARRIER_CODES = {
         'usps' => 'USPS', 'ups' => 'UPS', 'fedex' => 'FedEx',
-        'dhl' => 'DHL Express', 'dhl_ecommerce' => 'DHL', 'amazon' => 'Amazon'
+        'dhl' => 'DHL Express', 'dhl_ecommerce' => 'DHL', 'osm' => 'OSM', 'amazon' => 'Amazon'
       }.freeze
 
       module_function

data/lib/rate_card/grid.rb

@@ -6,29 +6,27 @@ module RateCard
   # The fetch engine and the assembled result.
   #
   # One call per (weight, zone); each response is harvested for every selected
-  # service, since eHub returns rates for all enabled services at once. A cell
-  # whose call failed is nil and is listed in #failures — never 0.0, which in a
-  # rate table reads as a real free rate.
+  # service, via the provider's #parse_rate_response. A cell whose call failed
+  # is nil and is listed in #failures — never 0.0, which in a rate table reads
+  # as a real free rate.
   class Grid
     THREADS = 8
-
-    # eHub answers these as an HTTP 201 "success" with the per-service errors
-    # field describing a hiccup that clears on its own, so Client's status-code
-    # retry never sees them. Left alone, the exact same request prices a
-    # different random set of cells on every run.
-    TRANSIENT_ERROR_PATTERN = /too many requests|please try again|slow down/i
     RETRY_BACKOFF = [0.5, 1.0].freeze
 
     # on_progress: called with no arguments after each completed call.
     # retry_sleeper: injected so retry backoff is testable without waiting.
-    def self.build(spec:, client:, on_progress: nil, retry_sleeper: ->(seconds) { sleep(seconds) })
-      new(spec).tap { |grid| grid.send(:fetch_all, client, on_progress, retry_sleeper) }
+    def self.build(spec:, client:, provider:, on_progress: nil, retry_sleeper: ->(seconds) { sleep(seconds) })
+      new(spec, provider).tap { |grid| grid.send(:fetch_all, client, on_progress, retry_sleeper) }
     end
 
     attr_reader :spec
 
-    def initialize(spec)
+    # provider defaults to nil only for specs that construct a Grid directly to
+    # seed @cells as a fixture and never fetch — #build (the real constructor)
+    # always supplies one.
+    def initialize(spec, provider = nil)
       @spec = spec
+      @provider = provider
       @cells = {}
       @failures = []
       @warnings = Hash.new(0)
@@ -44,36 +42,23 @@ module RateCard
       @failures.sort_by { |f| [f.weight, f.zone] }
     end
 
-    # What the API said went wrong on calls that otherwise succeeded: the
-    # response-level `warnings` array and the per-service `errors` field. Both
-    # arrive with an HTTP 201, so without this a carrier outage would show up as
-    # a card of blank cells with nothing to explain them.
-    #
-    # This card's own services sort first, however loud the account-wide noise
-    # is: one call rates every service on the token, so a token with 37 services
-    # enabled can bury the two warnings that explain this card's blank cells
-    # under thirty about services nobody selected.
     def warnings
       @warnings.map { |(message, scope), count| Warning.new(message: message, count: count, scope: scope) }
                .sort_by { |warning| [scope_rank(warning), -warning.count, warning.message] }
     end
 
-    # True only when no call got through. Deliberately NOT "no cell has a
-    # value": a run can have every call succeed and still price nothing, if the
-    # API does not return the selected service (USPS First Class is not priced
-    # above 13 oz, for instance). Conflating the two would blame the network for
-    # what is really a service or weight selection problem.
     def all_failed?
       @succeeded.zero? && @failures.any?
     end
 
-    # Did any cell actually get a rate? False means we have nothing to write.
     def any_rates?
       @cells.values.any?
     end
 
     private
 
+    attr_reader :provider
+
     def fetch_all(client, on_progress, retry_sleeper)
       Parallel.each(cell_coordinates, in_threads: THREADS) do |weight, zone|
         fetch_cell(client, weight, zone, retry_sleeper)
@@ -86,12 +71,11 @@ module RateCard
     end
 
     def fetch_cell(client, weight, zone, retry_sleeper)
-      payload = Shipment.new(spec: spec, weight: weight, address: spec.address_for(zone)).payload
-      body = fetch_with_transient_retry(client, payload, retry_sleeper)
-      record_response(body, weight, zone)
+      payload = provider.build_payload(spec: spec, weight: weight, address: spec.address_for(zone))
+      result = fetch_with_transient_retry(client, payload, retry_sleeper)
+      record_response(result, weight, zone)
       @mutex.synchronize { @succeeded += 1 }
     rescue Unauthorized
-      # No later call can succeed; let it abort the whole run.
       raise
     rescue StandardError => e
       @mutex.synchronize do
@@ -103,42 +87,33 @@ module RateCard
       attempt = 0
       loop do
         body = client.fetch_rates(payload)
-        return body unless transient_error?(body) && attempt < RETRY_BACKOFF.length
+        result = provider.parse_rate_response(body, spec: spec)
+        return result unless result[:transient] && attempt < RETRY_BACKOFF.length
 
         retry_sleeper.call(RETRY_BACKOFF[attempt])
         attempt += 1
       end
     end
 
-    # True when a selected service's errors field reads as a transient hiccup
-    # rather than a real problem with this request.
-    def transient_error?(body)
-      by_id = index_by_service_id(body)
-      spec.services.any? { |service| error_detail(by_id[service.id]) =~ TRANSIENT_ERROR_PATTERN }
-    end
-
-    def record_response(body, weight, zone)
-      by_id = index_by_service_id(body)
-
+    def record_response(result, weight, zone)
       @mutex.synchronize do
-        record_warnings(body, by_id)
+        record_warnings(result)
 
         spec.services.each do |service|
-          entry = by_id[service.id]
           spec.rate_keys.each do |rate_key|
-            field = RunSpec::RATE_KEY_FIELDS.fetch(rate_key)
-            @cells[[service.id, rate_key, weight, zone]] = coerce(entry && entry[field])
+            raw = result[:service_values].dig(service.id, rate_key)
+            @cells[[service.id, rate_key, weight, zone]] = coerce(raw)
           end
         end
       end
     end
 
     # Caller holds @mutex.
-    def record_warnings(body, by_id)
-      response_warnings(body).each { |message| @warnings[[message, Warning::ACCOUNT]] += 1 }
+    def record_warnings(result)
+      result[:warnings].each { |message| @warnings[[message, Warning::ACCOUNT]] += 1 }
 
       spec.services.each do |service|
-        detail = error_detail(by_id[service.id])
+        detail = result[:service_errors][service.id]
         next if detail.nil?
 
         @warnings[["#{service.name} (#{service.id}): #{detail}", Warning::SERVICE]] += 1
@@ -149,29 +124,6 @@ module RateCard
       warning.account_wide? ? 1 : 0
     end
 
-    def response_warnings(body)
-      return [] unless body.is_a?(Hash)
-
-      Array(body['warnings']).map(&:to_s).reject { |message| message.strip.empty? }
-    end
-
-    # `errors` is documented as populated when a service could not be rated. It
-    # comes back as a string, but an array is accepted so a list of carrier
-    # messages reads as one line instead of raising.
-    def error_detail(entry)
-      raw = entry && entry['errors']
-      detail = Array(raw).map(&:to_s).reject { |message| message.strip.empty? }.join('; ')
-      detail.empty? ? nil : detail
-    end
-
-    def index_by_service_id(body)
-      entries = body.is_a?(Hash) ? (body['service_rates'] || []) : []
-      entries.each_with_object({}) do |entry, acc|
-        id = entry['service_id']
-        acc[id.to_i] = entry unless id.nil?
-      end
-    end
-
     # nil stays nil. Anything numeric becomes a Float. Never defaults to zero.
     def coerce(raw)
       return nil if raw.nil? || raw.to_s.strip.empty?

data/lib/rate_card/provider_prompt.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module RateCard
+  # The one thing printed before the credential prompt, so the run says which
+  # provider it targets before anything is pasted into it. Selecting among
+  # more than one registered provider is not implemented yet, so more than one
+  # key raises rather than silently choosing the first.
+  module ProviderPrompt
+    module_function
+
+    def read(ui:, keys: Providers.all)
+      raise ArgumentError, 'multi-provider selection is not implemented yet' if keys.length > 1
+
+      key = keys.first
+      ui.info("Provider: #{Providers.build(key).label}")
+      key
+    end
+  end
+end

data/lib/rate_card/providers/ehub/client.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+
+module RateCard
+  module Providers
+    module EHub
+      # The single network seam. Talks to eHub production and classifies every
+      # outcome into: a parsed Hash, Unauthorized, or RequestFailed. Callers never
+      # see a Faraday exception.
+      #
+      # The fetch engine depends on this split: it records a nil cell for each
+      # RequestFailed and keeps going, but lets Unauthorized abort the whole run.
+      # Narrowing Unauthorized to 403 only would turn a rejected token into a card
+      # full of blank cells instead of one clear error — do not do that.
+      class Client
+        BASE_URL = 'https://api.ehub.com'
+        # No trailing slash: that is the documented path, and a trailing slash would
+        # rely on a redirect — which can drop the POST body.
+        RATES_PATH = '/api/v2/rates'
+        SERVICES_PATH = '/api/v2/services'
+        # 'ecommerce' services are storefront integrations, not shippable rates.
+        SERVICES_CATEGORY = 'shipping'
+
+        # The rate endpoint answers 201; 200 is accepted too so a change on the
+        # server side cannot turn a good response into a hard failure.
+        SUCCESS = [200, 201].freeze
+        # A rejected token will not improve on retry, so these are never retried.
+        # Production answers 403, but 401 stays in the list: if it ever comes back
+        # instead, we want one clear error rather than a card full of blank cells.
+        UNAUTHORIZED = [401, 403].freeze
+        # 429 and 5xx are transient; everything else is a decision, not a hiccup.
+        # The gateway codes stay in: 502/503/504 are the load balancer, not the
+        # rate engine, and they clear on their own within a backoff or two.
+        RETRYABLE = [429, 500, 502, 503, 504].freeze
+        BACKOFF = [0.5, 1.0].freeze
+
+        # stubs: a Faraday::Adapter::Test::Stubs, for specs only.
+        # sleeper: injected so retry backoff is testable without waiting.
+        def initialize(token:, stubs: nil, sleeper: ->(seconds) { sleep(seconds) })
+          @token = token
+          @stubs = stubs
+          @sleeper = sleeper
+          @connection = build_connection
+        end
+
+        # Returns the parsed response body as a Hash.
+        def fetch_rates(payload)
+          request('rate call') { post(RATES_PATH, payload) }
+        end
+
+        # Returns the parsed body of the service catalogue for this token's customer.
+        # Discovery uses this rather than a rate call: it costs nothing, and it lists
+        # services that would not have quoted at the single probe weight and zone.
+        def fetch_services
+          request('service list call') { get(SERVICES_PATH, category: SERVICES_CATEGORY) }
+        end
+
+        private
+
+        # Shared status handling: every call classifies into a Hash, Unauthorized,
+        # or RequestFailed, and retries the transient statuses the same way.
+        def request(label)
+          attempt = 0
+          loop do
+            status, body = yield
+            return body if SUCCESS.include?(status)
+
+            if UNAUTHORIZED.include?(status)
+              raise Unauthorized,
+                    "production rejected this token (HTTP #{status}). It may be expired, revoked, " \
+                    'or issued for a different environment — generate a new eHub API token and try again.'
+            end
+
+            unless RETRYABLE.include?(status) && attempt < BACKOFF.length
+              raise RequestFailed, "#{label} failed with HTTP #{status}#{error_detail(body)}"
+            end
+
+            @sleeper.call(BACKOFF[attempt])
+            attempt += 1
+          end
+        end
+
+        def post(path, payload)
+          response = @connection.post(path, JSON.generate(payload))
+          [response.status, parse(response.body)]
+        rescue Faraday::Error => e
+          raise RequestFailed, "rate call failed: #{e.message}"
+        end
+
+        def get(path, params)
+          response = @connection.get(path, params)
+          [response.status, parse(response.body)]
+        rescue Faraday::Error => e
+          raise RequestFailed, "service list call failed: #{e.message}"
+        end
+
+        def parse(body)
+          return body if body.is_a?(Hash)
+
+          JSON.parse(body.to_s)
+        rescue JSON::ParserError
+          {}
+        end
+
+        def error_detail(body)
+          message = body.is_a?(Hash) ? (body['error'] || body['message']) : nil
+          message ? " (#{message})" : ''
+        end
+
+        def build_connection
+          Faraday.new(url: BASE_URL) do |f|
+            f.headers['Authorization'] = "Bearer #{@token}"
+            f.headers['Content-Type'] = 'application/json'
+            f.options.timeout = 30
+            f.options.open_timeout = 10
+            if @stubs
+              f.adapter :test, @stubs
+            else
+              f.adapter Faraday.default_adapter
+            end
+          end
+        end
+      end
+    end
+  end
+end