rate-card 0.1.0

data/lib/rate_card/constants/cubic_tiers.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module RateCard
+  module Constants
+    # The ten official USPS cubic-pricing tiers (Ground Advantage Cubic,
+    # Priority Mail Cubic): the tier a package prices under is decided by
+    # which bounding cube its dimensions fit inside, not by its weight — so
+    # each tier pairs a fixed cube with the weight cap USPS prices it under.
+    # Ported from ../../rate_table_builder/constants.rb's CUBIC_PARAMS.
+    module CubicTiers
+      TIERS = [
+        { tier: 1,  length: 3.0,   width: 3.0,   height: 3.0,   weight_oz: 128 },
+        { tier: 2,  length: 6.0,   width: 6.0,   height: 6.0,   weight_oz: 128 },
+        { tier: 3,  length: 7.5,   width: 7.5,   height: 7.5,   weight_oz: 128 },
+        { tier: 4,  length: 8.5,   width: 8.5,   height: 8.5,   weight_oz: 128 },
+        { tier: 5,  length: 9.0,   width: 9.0,   height: 9.0,   weight_oz: 128 },
+        { tier: 6,  length: 10.0,  width: 10.0,  height: 10.0,  weight_oz: 128 },
+        { tier: 7,  length: 10.5,  width: 10.5,  height: 10.5,  weight_oz: 128 },
+        { tier: 8,  length: 11.0,  width: 11.0,  height: 11.0,  weight_oz: 128 },
+        { tier: 9,  length: 11.25, width: 11.25, height: 11.25, weight_oz: 240 },
+        { tier: 10, length: 11.75, width: 11.75, height: 11.75, weight_oz: 240 }
+      ].freeze
+
+      module_function
+
+      def ids
+        TIERS.map { |t| t[:tier] }
+      end
+
+      def find(tier_id)
+        TIERS.find { |t| t[:tier] == tier_id }
+      end
+
+      def dims(tier_id)
+        tier = find(tier_id)
+        return nil unless tier
+
+        { length: tier[:length], width: tier[:width], height: tier[:height] }
+      end
+
+      def weight_oz(tier_id)
+        find(tier_id)&.fetch(:weight_oz)
+      end
+
+      def label(tier_id)
+        "Tier #{tier_id}"
+      end
+
+      # One display choice per tier, for the wizard's multi-select, e.g.
+      # ["Tier 1 — 3x3x3in, ≤8lb", 1].
+      def choices
+        TIERS.map { |t| [choice_label(t), t[:tier]] }
+      end
+
+      def choice_label(tier)
+        dims_label = "#{fmt(tier[:length])}x#{fmt(tier[:width])}x#{fmt(tier[:height])}in"
+        "#{label(tier[:tier])} — #{dims_label}, ≤#{tier[:weight_oz] / 16}lb"
+      end
+
+      # Trims a whole-number float's trailing ".0" so tier labels read "3x3x3in"
+      # rather than "3.0x3.0x3.0in".
+      def fmt(number)
+        number == number.to_i ? number.to_i.to_s : number.to_s
+      end
+    end
+  end
+end

data/lib/rate_card/csv_writer.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'csv'
+require 'fileutils'
+require 'pathname'
+
+module RateCard
+  # Writes the grid to disk: one CSV per service per rate key, into the run's
+  # timestamped directory. A nil cell is an empty field, never 0.0.
+  class CsvWriter
+    # Called before fetching, so a bad destination is reported up front rather
+    # than after a few hundred calls and a minute of waiting have been spent.
+    def self.ensure_writable!(base)
+      base = Pathname.new(base)
+      FileUtils.mkdir_p(base)
+      raise OutputNotWritable, "cannot write to #{base}" unless base.writable?
+    rescue SystemCallError => e
+      raise OutputNotWritable, "cannot create #{base}: #{e.message}"
+    end
+
+    def initialize(grid:, spec:)
+      @grid = grid
+      @spec = spec
+    end
+
+    # Returns Array<Pathname> of the files written.
+    def write
+      FileUtils.mkdir_p(spec.run_dir)
+
+      spec.services.flat_map do |service|
+        spec.rate_keys.map { |rate_key| write_file(service, rate_key) }
+      end
+    end
+
+    private
+
+    attr_reader :grid, :spec
+
+    def write_file(service, rate_key)
+      path = spec.run_dir.join("#{service.file_slug}_#{rate_key}.csv")
+
+      CSV.open(path, 'w') do |csv|
+        csv << [spec.row_header, *spec.zones]
+        spec.rows.each { |row| csv << row_for(service, rate_key, row) }
+      end
+
+      path
+    end
+
+    def row_for(service, rate_key, row)
+      cells = spec.zones.map do |zone|
+        grid.value(service_id: service.id, rate_key: rate_key, weight: row, zone: zone)
+      end
+
+      [spec.row_label(row), *cells]
+    end
+  end
+end

data/lib/rate_card/failure.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module RateCard
+  # One rate call that did not succeed. Keyed by (weight, zone) rather than by
+  # service, because a single call covers every selected service — when it
+  # fails, they all lose the same cell.
+  Failure = Struct.new(:weight, :zone, :message, keyword_init: true)
+end

data/lib/rate_card/grid.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require 'parallel'
+
+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.
+  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) }
+    end
+
+    attr_reader :spec
+
+    def initialize(spec)
+      @spec = spec
+      @cells = {}
+      @failures = []
+      @warnings = Hash.new(0)
+      @succeeded = 0
+      @mutex = Mutex.new
+    end
+
+    def value(service_id:, rate_key:, weight:, zone:)
+      @cells[[service_id, rate_key, weight, zone]]
+    end
+
+    def failures
+      @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
+
+    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)
+        @mutex.synchronize { on_progress&.call }
+      end
+    end
+
+    def cell_coordinates
+      spec.rows.product(spec.zones)
+    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)
+      @mutex.synchronize { @succeeded += 1 }
+    rescue Unauthorized
+      # No later call can succeed; let it abort the whole run.
+      raise
+    rescue StandardError => e
+      @mutex.synchronize do
+        @failures << Failure.new(weight: weight, zone: zone, message: e.message)
+      end
+    end
+
+    def fetch_with_transient_retry(client, payload, retry_sleeper)
+      attempt = 0
+      loop do
+        body = client.fetch_rates(payload)
+        return body unless transient_error?(body) && 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)
+
+      @mutex.synchronize do
+        record_warnings(body, by_id)
+
+        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])
+          end
+        end
+      end
+    end
+
+    # Caller holds @mutex.
+    def record_warnings(body, by_id)
+      response_warnings(body).each { |message| @warnings[[message, Warning::ACCOUNT]] += 1 }
+
+      spec.services.each do |service|
+        detail = error_detail(by_id[service.id])
+        next if detail.nil?
+
+        @warnings[["#{service.name} (#{service.id}): #{detail}", Warning::SERVICE]] += 1
+      end
+    end
+
+    def scope_rank(warning)
+      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?
+
+      Float(raw)
+    rescue ArgumentError, TypeError
+      nil
+    end
+  end
+end

data/lib/rate_card/input.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module RateCard
+  # Parsing and defaults for the free-text answers. Extracted from Wizard when
+  # the prompt flow moved to TUI::App: the parsing is not tied to how the
+  # question is asked, and keeping it separate is what lets it be tested
+  # without a terminal.
+  module Input
+    # Fallback only. Valid package types are a property of the service
+    # (services[].package_types[].type), so the catalogue is preferred; this
+    # covers a catalogue that reports none.
+    PACKAGE_TYPES = %w[parcel flat_rate_envelope flat_rate_box soft_pack].freeze
+    DEFAULT_WEIGHT_RANGE = '1-16'
+
+    module_function
+
+    # Parses "1-8", "1,3,5" or a mix into a sorted unique Array<Integer>.
+    def parse_range(input)
+      input.to_s.split(',').flat_map do |part|
+        part = part.strip
+        if (match = part.match(/\A(\d+)\s*-\s*(\d+)\z/))
+          low, high = match.captures.map(&:to_i)
+          low <= high ? (low..high).to_a : []
+        elsif part.match?(/\A\d+\z/)
+          [part.to_i]
+        else
+          []
+        end
+      end.uniq.sort
+    end
+  end
+end

data/lib/rate_card/run_spec.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require 'time'
+
+module RateCard
+  # Everything one run of the tool needs to know, validated. The wizard's sole
+  # output; every component downstream consumes only this. Nothing here prompts
+  # or performs I/O.
+  #
+  # Written as a subclass of an anonymous Struct rather than `Struct.new do ... end`
+  # on purpose. Constant *assignment* inside a Struct block resolves lexically, so
+  # RATE_KEY_FIELDS there lands on RateCard, not on RunSpec — silently, with no
+  # warning — and every external `RunSpec::RATE_KEY_FIELDS` reference then raises
+  # NameError. A real class body puts the constants where they belong.
+  class RunSpec < Struct.new(
+    :token, :customer_name, :customer_id, :carrier, :services, :zones,
+    :weight_unit, :weights, :package_type, :rate_keys, :output_base,
+    :show_table, :started_at, :rate_mode, :cubic_tiers,
+    keyword_init: true
+  )
+    # Our rate-key name => the field it arrives as in service_rates. Getting
+    # this backwards would put meter rates in the shipper-rate column: a
+    # plausible-looking, entirely wrong rate card.
+    RATE_KEY_FIELDS = { shipper_rate: 'rate', meter_rate: 'meter_rate' }.freeze
+    RATE_KEY_LABELS = { shipper_rate: 'shipper rate', meter_rate: 'meter rate' }.freeze
+    WEIGHT_UNITS = %i[oz lbs].freeze
+
+    # One call returns rates for every enabled service, so service count does
+    # not affect call volume.
+    def call_count
+      rows.length * zones.length
+    end
+
+    def service_names
+      services.map(&:name)
+    end
+
+    def rate_key_labels
+      rate_keys.map { |key| rate_key_label(key) }
+    end
+
+    def zone_summary
+      self.class.compact_range(zones)
+    end
+
+    # [1,2,3,5] => "1-3,5". Runs of three or more collapse; a pair stays listed,
+    # since "4,5" is no longer than "4-5" and reads as what the user typed.
+    def self.compact_range(numbers)
+      sorted = numbers.to_a.sort.uniq
+      runs = sorted.slice_when { |a, b| b != a + 1 }.to_a
+      runs.map { |run| run.length >= 3 ? "#{run.first}-#{run.last}" : run.join(',') }.join(',')
+    end
+
+    # The API always takes ounces; the chosen unit is an input concern only.
+    def weight_in_oz(weight)
+      weight_unit == :lbs ? weight * 16 : weight
+    end
+
+    # Weight mode when not set, so every existing caller — none of which
+    # mentions rate_mode — keeps building a weight x zone card exactly as
+    # before.
+    def rate_mode
+      self[:rate_mode] || :weight
+    end
+
+    # The row axis Grid/CsvWriter/TableRenderer actually sweep: integer
+    # weights in weight mode, selected USPS cubic tier ids in cubic mode.
+    # Downstream code reads only this plus #row_label and #row_header, so
+    # neither has to know which mode produced it.
+    def rows
+      rate_mode == :cubic ? cubic_tiers : weights
+    end
+
+    def row_label(row)
+      rate_mode == :cubic ? Constants::CubicTiers.label(row) : row.to_s
+    end
+
+    def row_header
+      rate_mode == :cubic ? 'cubic_tier' : 'weight'
+    end
+
+    # The weight actually sent on the wire for one row: the tier's fixed
+    # cap in cubic mode (cubic pricing is volume-driven, not weight-driven,
+    # so the display weight_unit plays no part), or the usual oz/lbs
+    # conversion in weight mode.
+    def weight_in_oz_for(row)
+      rate_mode == :cubic ? Constants::CubicTiers.weight_oz(row) : weight_in_oz(row)
+    end
+
+    # nil in weight mode, so Shipment keeps its own fixed nominal box.
+    def dims_for(row)
+      rate_mode == :cubic ? Constants::CubicTiers.dims(row) : nil
+    end
+
+    def validate_rows!
+      if rate_mode == :cubic
+        raise ArgumentError, 'select at least one cubic tier' if cubic_tiers.nil? || cubic_tiers.empty?
+
+        unknown = cubic_tiers - Constants::CubicTiers.ids
+        raise ArgumentError, "unknown cubic tier: #{unknown.join(', ')}" unless unknown.empty?
+      else
+        raise ArgumentError, 'select at least one weight' if weights.nil? || weights.empty?
+      end
+    end
+
+    def address_for(zone)
+      Constants::Addresses.for_carrier(carrier)[zone]
+    end
+
+    def rate_key_label(key)
+      RATE_KEY_LABELS.fetch(key, key.to_s.tr('_', ' '))
+    end
+
+    def weight_label
+      rate_mode == :cubic ? 'cubic tier' : "wt(#{weight_unit})"
+    end
+
+    # Apostrophes are dropped rather than collapsed, so "Bob's" slugs to "bobs"
+    # and not "bob_s". Everything else non-alphanumeric becomes a single
+    # underscore. Note the customer name is usually an email address, since eHub
+    # tokens carry no customer name.
+    def slug
+      cleaned = customer_name.to_s.downcase
+                             .gsub(/['’`]/, '')
+                             .gsub(/[^a-z0-9]+/, '_')
+                             .gsub(/\A_+|_+\z/, '')
+
+      # Token always supplies a non-blank name, but an empty slug would build a
+      # directory called '_1042_...', so do not rely on that from here.
+      cleaned.empty? ? 'customer' : cleaned
+    end
+
+    def timestamp
+      started_at.utc.strftime('%Y-%m-%dT%H-%M-%SZ')
+    end
+
+    def run_dir
+      Pathname.new(output_base).join("#{slug}_#{customer_id}_#{timestamp}")
+    end
+
+    def validate!
+      raise ArgumentError, 'select at least one service' if services.nil? || services.empty?
+      raise ArgumentError, 'select at least one zone' if zones.nil? || zones.empty?
+      validate_rows!
+      raise ArgumentError, 'select at least one rate column' if rate_keys.nil? || rate_keys.empty?
+
+      unknown = rate_keys - RATE_KEY_FIELDS.keys
+      raise ArgumentError, "unknown rate column: #{unknown.join(', ')}" unless unknown.empty?
+
+      unless WEIGHT_UNITS.include?(weight_unit)
+        raise ArgumentError, "weight unit must be one of #{WEIGHT_UNITS.join(', ')}"
+      end
+
+      zones.each do |zone|
+        next if address_for(zone)
+
+        raise ArgumentError, "no address for zone #{zone} on carrier #{carrier}"
+      end
+
+      self
+    end
+  end
+end

data/lib/rate_card/runner.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module RateCard
+  # Reports one completed run: render, write, report. Returns the process exit
+  # code.
+  #
+  # The fetch itself moved into TUI::App when this switched to Bubbletea — it
+  # has to happen inside the event loop for the progress bar to be live — so
+  # this now takes the finished Grid rather than building one. Everything here
+  # runs after the terminal is back to normal, which is why it is all plain
+  # printing.
+  class Runner
+    def initialize(spec:, grid:, ui:)
+      @spec = spec
+      @grid = grid
+      @ui = ui
+    end
+
+    def run
+      @ui.print_tables(TableRenderer.new(grid: grid, spec: spec).tables) if spec.show_table
+      @ui.failure_report(grid.failures, spec: spec)
+      @ui.warning_report(grid.warnings)
+
+      if grid.all_failed?
+        @ui.error('every rate call failed — no files written')
+        return 1
+      end
+
+      unless grid.any_rates?
+        @ui.error('the calls succeeded but returned no rates for the selected ' \
+                  'services — check the service, package type and weight range')
+        return 1
+      end
+
+      @ui.saved(CsvWriter.new(grid: grid, spec: spec).write)
+      0
+    end
+
+    private
+
+    attr_reader :spec, :grid
+  end
+end

data/lib/rate_card/service.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module RateCard
+  # One shipping service the customer has enabled, as discovered from a probe call.
+  Service = Struct.new(:id, :code, :name, :carrier, :package_types, keyword_init: true) do
+    # The package types this service accepts, from services[].package_types.
+    # Always an array: callers offer these as choices, and a nil would have to
+    # be guarded at every one of them.
+    def package_types
+      Array(self[:package_types])
+    end
+
+    # What the wizard checkbox shows.
+    def label
+      "#{name} (#{id})"
+    end
+
+    # Basis for output filenames; must be filesystem-safe and never empty.
+    #
+    # Falls through on the SANITISED value, not the raw one: a code like '###'
+    # is non-empty but sanitises to nothing, and an empty slug would produce a
+    # file named '_shipper_rate.csv' on the user's disk.
+    def file_slug
+      [code, name].each do |candidate|
+        slug = sanitize(candidate)
+        return slug unless slug.empty?
+      end
+
+      sanitize("service_#{id}")
+    end
+
+    private
+
+    def sanitize(value)
+      value.to_s.gsub(/[^A-Za-z0-9]+/, '_').gsub(/\A_+|_+\z/, '')
+    end
+  end
+end

data/lib/rate_card/service_catalog.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module RateCard
+  # Turns the /services response into the list of services the wizard can offer.
+  # Read live rather than from a hardcoded list so a service id that has drifted
+  # cannot silently produce a card of blank cells.
+  module ServiceCatalog
+    module_function
+
+    # Returns Array<Service>, de-duplicated and sorted for display.
+    def from_response(body)
+      entries = body.is_a?(Hash) ? (body['services'] || []) : []
+
+      services = entries.filter_map { |entry| build_service(entry) }.uniq(&:id)
+      sort_for_display(services)
+    end
+
+    # Returns { carrier => Array<Service> } with carriers in display order.
+    def group_by_carrier(services)
+      services.group_by(&:carrier)
+              .sort_by { |carrier, _| carrier_rank(carrier) }
+              .to_h
+    end
+
+    def build_service(entry)
+      id = entry['service_id']
+      return nil if id.nil?
+
+      code = entry['service_code'].to_s
+      name = entry['service'].to_s
+      name = code if name.strip.empty?
+
+      Service.new(
+        id: id.to_i,
+        code: code,
+        name: name,
+        carrier: Constants::Carriers.for_carrier_code(entry['carrier_code']),
+        package_types: package_types(entry)
+      )
+    end
+
+    # services[].package_types is an array of {type, name}; only the type is
+    # sent back in a rate request.
+    def package_types(entry)
+      Array(entry['package_types']).filter_map do |package_type|
+        next package_type.to_s unless package_type.is_a?(Hash)
+
+        type = package_type['type'].to_s
+        type.empty? ? nil : type
+      end.uniq
+    end
+
+    def sort_for_display(services)
+      services.sort_by { |service| [carrier_rank(service.carrier), service.name.to_s] }
+    end
+
+    def carrier_rank(carrier)
+      index = Constants::Carriers.display_order.index(carrier)
+      index || Constants::Carriers.display_order.length
+    end
+  end
+end