rate-card 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 45fc9c209efdd18d8586a8cbbb2e02ff0c83c410c2d27c75762dd93999b9276a
+  data.tar.gz: a0aaf2c79154dc92586953af3c9a89abfe7997cbab3825ba9188e53bd250c730
+SHA512:
+  metadata.gz: 520df789fc49541ed4254432db087d217ecf66b5367f5d3a25564334fc9ef80712a246e874a309f87ee843cbb73cf5d60656d7e2c31f72c3f30a82e62020c988
+  data.tar.gz: 6cfb5ebd7544fb624fac46a6bc8567dd0175814b2f1116cd7ef7d8a111f1b9c099922d0b2cea8b7264b5e12446701214ffe44a66302b368c070b3417566bbf8c

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 eHub
+
+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

@@ -0,0 +1,226 @@
+# 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`.
+
+## 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
+```
+
+`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:
+
+```bash
+bin/release
+```
+
+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
+
+```bash
+bundle exec exe/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:
+
+```bash
+ln -s "$PWD/exe/rate-card" ~/bin/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
+
+```bash
+NO_COLOR=1 bundle exec rspec
+```
+
+**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

@@ -0,0 +1,101 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'optparse'
+require 'pathname'
+
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+require 'rate_card'
+
+DEFAULT_OUTPUT_BASE = Pathname.new(Dir.home).join('Downloads', 'rate_cards')
+
+options = { output_base: DEFAULT_OUTPUT_BASE, show_table: true }
+
+parser = OptionParser.new do |opts|
+  opts.banner = 'Usage: rate-card [options]'
+  opts.separator ''
+  opts.separator 'Generates a shipping rate card from the eHub production API.'
+  opts.separator 'All rate-card inputs are collected interactively.'
+  opts.separator ''
+
+  opts.on('--output-dir DIR', "Where to save CSVs (default: #{DEFAULT_OUTPUT_BASE})") do |dir|
+    options[:output_base] = Pathname.new(File.expand_path(dir))
+  end
+
+  opts.on('--no-table', 'Do not print the rate tables to stdout') do
+    options[:show_table] = false
+  end
+
+  opts.on('-v', '--version', 'Print the version') do
+    puts RateCard::VERSION
+    exit 0
+  end
+
+  opts.on('-h', '--help', 'Print this message') do
+    puts opts
+    exit 0
+  end
+end
+
+begin
+  parser.parse!(ARGV)
+rescue OptionParser::ParseError => e
+  warn e.message
+  warn parser.help
+  exit 1
+end
+
+ui = RateCard::UI.new(io: $stdout)
+ui.banner
+
+# 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?
+  ui.info('Cancelled — nothing was built.')
+  exit 0
+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])
+runner = Bubbletea::Runner.new(app)
+app.notifier = runner
+
+begin
+  runner.run
+rescue Interrupt
+  ui.blank
+  ui.info('Cancelled.')
+  exit 130
+end
+
+if app.cancelled?
+  ui.info('Cancelled — nothing was built.')
+  exit 0
+end
+
+# Errors are carried out of the loop rather than raised through it, so the
+# terminal is restored before anything is printed.
+case app.error
+when nil then nil
+when RateCard::Unauthorized
+  ui.error('Production rejected that token. Check it is a current eHub API token.')
+  exit 1
+when RateCard::NoServices
+  ui.error('This token has no shipping services enabled — nothing to build a card from.')
+  exit 1
+when RateCard::OutputNotWritable
+  ui.error(app.error.message)
+  exit 1
+else
+  ui.error(app.error.message)
+  exit 1
+end
+
+spec = app.spec
+spec.show_table = options[:show_table]
+
+exit RateCard::Runner.new(spec: spec, grid: app.grid, ui: ui).run

data/lib/rate_card/client.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+
+module RateCard
+  # 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

data/lib/rate_card/constants/addresses.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module RateCard
+  module Constants
+    # Hand-verified destination addresses, one per zone per carrier. Zone
+    # membership is a property of a real address and a real carrier's zone chart,
+    # so these are curated by hand and never derived at runtime.
+    #
+    # Ported from ../rate_table_builder/constants/address_constants.rb.
+    #
+    # One deliberate normalisation: that file spells 130 Braewick Rd / 84103 as
+    # 'SLC' in its USPS table and 'Salt Lake City' in its UPS table. We use
+    # 'Salt Lake City' in both. Zone membership follows the postal code, and we
+    # send validation_level 'basic', which some address validators fail on the
+    # abbreviation. Do not "restore" 'SLC'.
+    module Addresses
+      ORIGIN = {
+        company: 'Rate Card Builder',
+        address1: '9490 S 300 W',
+        city: 'Sandy',
+        state: 'UT',
+        postal_code: '84070',
+        country: 'US',
+        phone: '000-000-0000'
+      }.freeze
+
+      USPS = {
+        1 => { address1: '1206 W 9440 S', city: 'South Jordan', state: 'UT', postal_code: '84094', country: 'US' },
+        2 => { address1: '130 Braewick Rd', city: 'Salt Lake City', state: 'UT', postal_code: '84103', country: 'US' },
+        3 => { address1: '1526 21st St', city: 'Cody', state: 'WY', postal_code: '82414', country: 'US' },
+        4 => { address1: '1954 E Fountain St', city: 'Mesa', state: 'AZ', postal_code: '85203', country: 'US' },
+        5 => { address1: '2909 Woodland Ave', city: 'West Des Moines', state: 'IA', postal_code: '50266', country: 'US' },
+        6 => { address1: '19813 Crescent Ave', city: 'Lynwood', state: 'IL', postal_code: '60411', country: 'US' },
+        7 => { address1: '922 Maple Ave', city: 'Pittsburgh', state: 'PA', postal_code: '15234', country: 'US' },
+        8 => { address1: '3149 Brickell Ave', city: 'Miami', state: 'FL', postal_code: '33129', country: 'US' }
+      }.freeze
+
+      UPS = {
+        1 => { address1: '9121 S Village Shop D', city: 'Sandy', state: 'UT', postal_code: '84094', country: 'US' },
+        2 => { address1: '130 Braewick Rd', city: 'Salt Lake City', state: 'UT', postal_code: '84103', country: 'US' },
+        3 => { address1: '1526 21st St', city: 'Cody', state: 'WY', postal_code: '82414', country: 'US' },
+        4 => { address1: '1954 E Fountain St', city: 'Mesa', state: 'AZ', postal_code: '85203', country: 'US' },
+        5 => { address1: '2909 Woodland Ave', city: 'West Des Moines', state: 'IA', postal_code: '50266', country: 'US' },
+        6 => { address1: '19813 Crescent Ave', city: 'Lynwood', state: 'IL', postal_code: '60411', country: 'US' },
+        7 => { address1: '922 Maple Ave', city: 'Pittsburgh', state: 'PA', postal_code: '15234', country: 'US' },
+        8 => { address1: '3149 Brickell Ave', city: 'Miami', state: 'FL', postal_code: '33129', country: 'US' }
+      }.freeze
+
+      FEDEX = {
+        1 => { address1: '50 S Main Street', city: 'Salt Lake City', state: 'UT', postal_code: '84101', country: 'US' },
+        2 => { address1: '1700 Lincoln Street', city: 'Denver', state: 'CO', postal_code: '80203', country: 'US' },
+        3 => { address1: '411 E Wisconsin Avenue', city: 'Phoenix', state: 'AZ', postal_code: '85004', country: 'US' },
+        4 => { address1: '1201 Elm Street', city: 'Dallas', state: 'TX', postal_code: '75270', country: 'US' },
+        5 => { address1: '233 S Wacker Drive', city: 'Chicago', state: 'IL', postal_code: '60606', country: 'US' },
+        6 => { address1: '191 Peachtree Street NE', city: 'Atlanta', state: 'GA', postal_code: '30303', country: 'US' },
+        7 => { address1: '350 Fifth Avenue', city: 'New York', state: 'NY', postal_code: '10118', country: 'US' },
+        8 => { address1: '1 Beacon Street', city: 'Boston', state: 'MA', postal_code: '02108', country: 'US' }
+      }.freeze
+
+      # DHL eCommerce's zone calculator (ehub's
+      # app/services/carriers/dhl_ecommerce/zone_calculator.rb) is an
+      # unmodified subclass of USPS's zone calculator, so DHL eCommerce
+      # zones are USPS zones. This is the same chart, not a coincidence to
+      # keep in sync by hand - if DHL eCommerce ever gets its own zone
+      # 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
+
+      module_function
+
+      # Raises rather than falling back. The old USPS default meant asking for
+      # a carrier we have no chart for produced a full, plausible-looking card
+      # priced to USPS zone addresses and labeled Z1-Z8 — wrong in a way
+      # nothing downstream could detect. A missing chart is a missing chart.
+      def for_carrier(carrier)
+        BY_CARRIER.fetch(carrier.to_s) do
+          raise UnsupportedCarrier,
+                "no curated zone chart for #{carrier} — rate cards are only " \
+                "available for #{supported_carriers.join(', ')}. Adding one means " \
+                "hand-verifying a destination address per zone against that " \
+                'carrier\'s own zone chart and adding it to Addresses::BY_CARRIER.'
+        end
+      end
+
+      def supported?(carrier)
+        BY_CARRIER.key?(carrier.to_s)
+      end
+
+      def supported_carriers
+        BY_CARRIER.keys
+      end
+
+      # [] for a carrier with no chart, so the wizard can ask about zones
+      # without having to rescue.
+      def available_zones(carrier)
+        supported?(carrier) ? for_carrier(carrier).keys.sort : []
+      end
+    end
+  end
+end

data/lib/rate_card/constants/carriers.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module RateCard
+  module Constants
+    # Turns the carrier_code that /services reports into the display name the
+    # wizard groups by.
+    module Carriers
+      OTHER = 'Other'
+
+      DISPLAY_ORDER = ['USPS', 'UPS', 'FedEx', 'DHL', 'Amazon', OTHER].freeze
+
+      # Every /services entry carries a lowercase carrier_code. Anything not
+      # listed here keeps its own code, upcased: an unrecognised carrier is
+      # still better named by itself than lumped into 'Other'.
+      #
+      # DHL eCommerce reaches /services as 'dhl_ecommerce' and maps to 'DHL'
+      # here, aliased to Addresses::USPS because DHL eCommerce's zone
+      # calculator in the Rails monolith is a verified unmodified subclass of
+      # USPS's zone calculator. The bare 'dhl' code is DHL Express, a distinct
+      # carrier with unverified zones, so it gets its own display name
+      # ('DHL Express') rather than sharing 'DHL' — with no chart of its own
+      # in Addresses, it correctly raises UnsupportedCarrier instead of
+      # silently inheriting USPS's zones.
+      # Do not add another DHL code to the 'DHL' key unless its zones are
+      # likewise verified identical to USPS's — otherwise it needs its own
+      # distinct display name here AND its own chart in Addresses, or it will
+      # silently inherit the wrong zone chart.
+      CARRIER_CODES = {
+        'usps' => 'USPS', 'ups' => 'UPS', 'fedex' => 'FedEx',
+        'dhl' => 'DHL Express', 'dhl_ecommerce' => 'DHL', 'amazon' => 'Amazon'
+      }.freeze
+
+      module_function
+
+      # OTHER is only for a malformed entry with no code at all, so a service is
+      # still offered rather than dropped or left with a nil carrier.
+      def for_carrier_code(code)
+        key = code.to_s.strip.downcase
+        return OTHER if key.empty?
+
+        CARRIER_CODES.fetch(key) { key.upcase }
+      end
+
+      def display_order
+        DISPLAY_ORDER
+      end
+    end
+  end
+end