rate-card 0.1.0 → 0.1.2

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

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module RateCard
+  module Providers
+    module EHub
+      # Implements the provider interface documented in
+      # docs/superpowers/specs/2026-09-02-provider-abstraction-design.md by
+      # delegating to the eHub-specific classes in this directory.
+      class Provider
+        LABEL = 'eHub'
+
+        # eHub answers a disguised-success rate-limit hiccup as an HTTP 201 with a
+        # per-service errors field describing it, so Client's status-code retry
+        # never sees it. 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
+
+        def label
+          LABEL
+        end
+
+        def read_credential(ui:, io: $stdin)
+          TokenPrompt.read(ui: ui, io: io)
+        end
+
+        def identify(credential)
+          Token.decode(credential)
+        end
+
+        def client(credential)
+          Client.new(token: credential)
+        end
+
+        def parse_services(body)
+          ServiceCatalog.from_response(body)
+        end
+
+        def build_payload(spec:, weight:, address:)
+          Shipment.new(spec: spec, weight: weight, address: address).payload
+        end
+
+        # Normalizes one /rates response into what Grid needs to record a cell:
+        # - transient: a disguised-success rate-limit hiccup that should be retried
+        # - warnings: the response-level warnings array (account-wide)
+        # - service_errors: { service_id => message } for selected services only
+        # - service_values: { service_id => { rate_key => raw_value_or_nil } }
+        def parse_rate_response(body, spec:)
+          by_id = index_by_service_id(body)
+          {
+            transient: transient?(spec, by_id),
+            warnings: response_warnings(body),
+            service_errors: service_errors(spec, by_id),
+            service_values: service_values(spec, by_id)
+          }
+        end
+
+        private
+
+        def transient?(spec, by_id)
+          spec.services.any? { |service| error_detail(by_id[service.id]) =~ TRANSIENT_ERROR_PATTERN }
+        end
+
+        def service_errors(spec, by_id)
+          spec.services.each_with_object({}) do |service, acc|
+            detail = error_detail(by_id[service.id])
+            acc[service.id] = detail if detail
+          end
+        end
+
+        # RunSpec::RATE_KEY_FIELDS stays top-level rather than provider-owned (see
+        # its own comment), but the field names it maps to ('rate', 'meter_rate')
+        # are an eHub API fact — a provider whose response uses different field
+        # names would need RATE_KEY_FIELDS to become provider-specific too.
+        def service_values(spec, by_id)
+          spec.services.each_with_object({}) do |service, acc|
+            entry = by_id[service.id]
+            acc[service.id] = spec.rate_keys.each_with_object({}) do |rate_key, values|
+              field = RunSpec::RATE_KEY_FIELDS.fetch(rate_key)
+              values[rate_key] = entry && entry[field]
+            end
+          end
+        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
+      end
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module RateCard
+  module Providers
+    module EHub
+      # 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
+
+        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
+  end
+end

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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module RateCard
+  module Providers
+    module EHub
+      # Builds the request body for one (weight, zone) rate call.
+      #
+      # The shape follows the documented rate request
+      # (https://docs.ehub.com/rates/rate-request). The customs blocks are sent even
+      # for domestic cards because international services error without them; the
+      # docs mark the parcel-level one as required for international shipments.
+      class Shipment
+        DIMENSION = 2
+        ITEM_VALUE = 18.99
+        HS_TARIFF_CODE = '1704.90.3000'
+
+        def initialize(spec:, weight:, address:)
+          @spec = spec
+          @weight = weight
+          @address = address
+        end
+
+        def payload
+          {
+            shipment: {
+              from_location: Constants::Addresses::ORIGIN,
+              to_location: to_location,
+              parcels: [parcel]
+            }
+          }
+        end
+
+        private
+
+        attr_reader :spec, :weight, :address
+
+        def to_location
+          {
+            company: 'Rate Card Builder',
+            phone: '000-000-0000'
+          }.merge(address)
+        end
+
+        def parcel
+          box = dims
+          {
+            package_type: spec.package_type,
+            length: box[:length],
+            width: box[:width],
+            height: box[:height],
+            weight: spec.weight_in_oz_for(weight),
+            parcel_items: [parcel_item],
+            customs_data: customs_data
+          }
+        end
+
+        def dims
+          spec.dims_for(weight) || { length: DIMENSION, width: DIMENSION, height: DIMENSION }
+        end
+
+        # The parcel as a whole. One item at quantity 1, so this mirrors the item's
+        # declaration; the docs require it for international shipments.
+        def customs_data
+          {
+            content_type: 'merchandise',
+            value: ITEM_VALUE,
+            hs_tariff_code: HS_TARIFF_CODE
+          }
+        end
+
+        def parcel_item
+          {
+            name: 'Candy',
+            quantity: 1,
+            price: ITEM_VALUE,
+            customs_data: customs_data
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'json'
+
+module RateCard
+  module Providers
+    module EHub
+      # Reads claims out of an eHub JWT so we can show the user which customer a
+      # pasted token belongs to. We decode so the user can confirm they are pointed at
+      # the intended production account before a run starts. Deliberately does NOT
+      # verify the signature: these claims are displayed, never trusted for
+      # authorization. The API's 401 is the only real check.
+      module Token
+        class DecodeError < Error; end
+
+        module_function
+
+        def decode(raw)
+          payload = payload_from(raw)
+          user = payload.dig('data', 'user') || {}
+
+          customer_id = user['customer_id'] if user['customer_id'].is_a?(Integer)
+          email = presence(user['email'])
+          # FIXME - I don't even think we need a name field here tbh
+          name = email || (customer_id ? "customer #{customer_id}" : 'unknown customer')
+
+          { name: name, customer_id: customer_id, email: email }
+        end
+
+        def presence(value)
+          string = value.to_s.strip
+          string.empty? ? nil : string
+        end
+
+        def payload_from(raw)
+          segments = raw.to_s.split('.')
+          raise DecodeError, 'token is not a JWT (expected three segments)' unless segments.length == 3
+
+          # urlsafe_decode64 restores missing '=' padding itself, which matters
+          # because real JWT segments are always unpadded.
+          parsed = JSON.parse(Base64.urlsafe_decode64(segments[1]))
+          raise DecodeError, 'token payload is not a JSON object' unless parsed.is_a?(Hash)
+
+          parsed
+        rescue ArgumentError, JSON::ParserError
+          raise DecodeError, 'this does not look like an eHub API token — please try again'
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'io/console'
+
+module RateCard
+  module Providers
+    module EHub
+      # Reads the API token before the TUI takes the terminal.
+      #
+      # This is deliberately NOT a TUI field. bubbletea-ruby's input reader returns
+      # one key per poll and discards the rest of the buffered bytes, so a pasted
+      # 200-character JWT arrives as a single character and the other 199 are lost
+      # — verified against 0.1.4, and bracketed_paste does not help. Typing is
+      # unaffected at any speed, so every other answer is safe inside the loop; the
+      # token is the one field that is always pasted.
+      #
+      # Reading it here also means the terminal's own line editing handles the
+      # paste, which is what makes it work.
+      module TokenPrompt
+        # DEC private mode reset for bracketed paste. A crashed or Ctrl-C'd
+        # prior run can leave the TUI's bracketed paste mode on in the
+        # terminal (iTerm2 persists terminal modes across process launches
+        # within a pane, which is where this has actually been observed); the
+        # next plain `gets` here then reads the paste's literal \e[200~ /
+        # \e[201~ wrapper as part of the token. Harmless on a terminal that
+        # never turned bracketed paste on.
+        BRACKETED_PASTE_OFF = "\e[?2004l"
+        PASTE_START = "\e[200~"
+        PASTE_END = "\e[201~"
+
+        module_function
+
+        def read(ui:, io: $stdin)
+          loop do
+            $stdout.print(BRACKETED_PASTE_OFF) if io.tty?
+            ui.prompt('eHub API token: ')
+            raw = read_masked(io)
+            return nil if raw.nil?
+
+            raw = strip_paste_markers(raw).strip
+            if raw.empty?
+              ui.error('no token on that line — paste the token')
+              next
+            end
+
+            begin
+              Token.decode(raw)
+              return raw
+            rescue Token::DecodeError => e
+              ui.error("#{e.message} — paste the token again")
+            end
+          end
+        end
+
+        def read_masked(io)
+          if io.respond_to?(:noecho) && io.tty?
+            value = io.noecho(&:gets)
+            puts
+            value
+          else
+            io.gets
+          end
+        end
+
+        def strip_paste_markers(raw)
+          raw.delete_prefix(PASTE_START).delete_suffix("#{PASTE_END}\n").delete_suffix(PASTE_END)
+        end
+      end
+    end
+  end
+end

data/lib/rate_card/providers.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module RateCard
+  # Maps a provider key to the object that builds it. Adding a provider later
+  # means adding one entry here plus its providers/<name>/ implementation —
+  # nothing else here changes.
+  module Providers
+    REGISTRY = {
+      ehub: -> { EHub::Provider.new }
+    }.freeze
+
+    module_function
+
+    def all
+      REGISTRY.keys
+    end
+
+    def build(key)
+      REGISTRY.fetch(key) { raise ArgumentError, "unknown provider: #{key}" }.call
+    end
+  end
+end

data/lib/rate_card/service.rb

@@ -3,6 +3,20 @@
 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
+    # Returns { carrier => Array<Service> } with carriers in display order.
+    # Provider-agnostic: any provider's #parse_services returns these same
+    # structs, so grouping them for display doesn't belong to any one provider.
+    def self.group_by_carrier(services)
+      services.group_by(&:carrier)
+              .sort_by { |carrier, _| carrier_rank(carrier) }
+              .to_h
+    end
+
+    def self.carrier_rank(carrier)
+      index = Constants::Carriers.display_order.index(carrier)
+      index || Constants::Carriers.display_order.length
+    end
+
     # 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.

data/lib/rate_card/tui/app.rb

@@ -34,10 +34,11 @@ module RateCard
       # the only way a worker thread can get a message onto the event loop.
       attr_writer :notifier
 
-      def initialize(token:, output_base:,
-                     client_factory: ->(tok) { Client.new(token: tok) })
+      def initialize(token:, output_base:, provider:,
+                     client_factory: ->(tok) { provider.client(tok) })
         @token = token
         @output_base = Pathname.new(output_base)
+        @provider = provider
         @client_factory = client_factory
 
         @stage = :loading
@@ -220,7 +221,7 @@ module RateCard
       # chart is dropped from the menu rather than offered and then refused
       # mid-run by Addresses.for_carrier.
       def selectable_carriers
-        carriers = ServiceCatalog.group_by_carrier(@services)
+        carriers = Service.group_by_carrier(@services)
                                  .keys
                                  .select { |carrier| Constants::Addresses.supported?(carrier) }
         return carriers & ['USPS'] if @answers[:rate_mode] == :cubic
@@ -339,7 +340,7 @@ module RateCard
       def start_loading
         client = @client_factory.call(@token)
         lambda do
-          services = ServiceCatalog.from_response(client.fetch_services)
+          services = @provider.parse_services(client.fetch_services)
           if services.empty?
             LoadFailed.new(NoServices.new('the API returned no services for this token'))
           elsif (rateable = with_supported_carrier(services)).empty?
@@ -384,12 +385,13 @@ module RateCard
         client = @client_factory.call(@token)
         notifier = @notifier
         spec = @spec
+        provider = @provider
 
         lambda do
           completed = 0
           failed = 0
           mutex = Mutex.new
-          grid = Grid.build(spec: spec, client: client, on_progress: lambda {
+          grid = Grid.build(spec: spec, client: client, provider: provider, on_progress: lambda {
             mutex.synchronize { completed += 1 }
             notifier&.send(ProgressAdvanced.new(completed: completed, failed: failed))
           })
@@ -438,7 +440,7 @@ module RateCard
       end
 
       def identity
-        @identity ||= Token.decode(@token)
+        @identity ||= @provider.identify(@token)
       end
 
       # ----------------------------------------------------------------- view

data/lib/rate_card/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RateCard
-  VERSION = '0.1.0'
+  VERSION = '0.1.2'
 end

data/lib/rate_card.rb

@@ -25,18 +25,21 @@ module RateCard
   class UnsupportedCarrier < Error; end
 end
 
-require_relative 'rate_card/token'
-require_relative 'rate_card/token_prompt'
+require_relative 'rate_card/providers/ehub/token'
+require_relative 'rate_card/providers/ehub/token_prompt'
 require_relative 'rate_card/service'
 require_relative 'rate_card/failure'
 require_relative 'rate_card/constants/carriers'
 require_relative 'rate_card/constants/addresses'
 require_relative 'rate_card/constants/cubic_tiers'
-require_relative 'rate_card/client'
-require_relative 'rate_card/service_catalog'
+require_relative 'rate_card/providers/ehub/client'
+require_relative 'rate_card/providers/ehub/service_catalog'
 require_relative 'rate_card/input'
 require_relative 'rate_card/run_spec'
-require_relative 'rate_card/shipment'
+require_relative 'rate_card/providers/ehub/shipment'
+require_relative 'rate_card/providers/ehub/provider'
+require_relative 'rate_card/providers'
+require_relative 'rate_card/provider_prompt'
 require_relative 'rate_card/warning'
 require_relative 'rate_card/grid'
 require_relative 'rate_card/csv_writer'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rate-card
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - eHub
@@ -136,7 +136,6 @@ files:
 - README.md
 - exe/rate-card
 - lib/rate_card.rb
-- lib/rate_card/client.rb
 - lib/rate_card/constants/addresses.rb
 - lib/rate_card/constants/carriers.rb
 - lib/rate_card/constants/cubic_tiers.rb
@@ -144,14 +143,18 @@ files:
 - lib/rate_card/failure.rb
 - lib/rate_card/grid.rb
 - lib/rate_card/input.rb
+- lib/rate_card/provider_prompt.rb
+- lib/rate_card/providers.rb
+- lib/rate_card/providers/ehub/client.rb
+- lib/rate_card/providers/ehub/provider.rb
+- lib/rate_card/providers/ehub/service_catalog.rb
+- lib/rate_card/providers/ehub/shipment.rb
+- lib/rate_card/providers/ehub/token.rb
+- lib/rate_card/providers/ehub/token_prompt.rb
 - lib/rate_card/run_spec.rb
 - lib/rate_card/runner.rb
 - lib/rate_card/service.rb
-- lib/rate_card/service_catalog.rb
-- lib/rate_card/shipment.rb
 - lib/rate_card/table_renderer.rb
-- lib/rate_card/token.rb
-- lib/rate_card/token_prompt.rb
 - lib/rate_card/tui/app.rb
 - lib/rate_card/tui/fields/multi_select.rb
 - lib/rate_card/tui/fields/select.rb

data/lib/rate_card/client.rb

@@ -1,124 +0,0 @@
-# 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