speedy-bg 0.1.0

data/docs/RESPONSE_CONTRACTS.md

@@ -0,0 +1,55 @@
+# Offline response contracts
+
+`spec/response_property_examples_spec.rb` exercises every endpoint shortcut in
+`Speedy::ClientResources` through a real configured client and a local Faraday
+test adapter. It makes no HTTP requests. A coverage assertion fails when a new
+public shortcut lacks a scenario; the calculation alias is listed explicitly.
+
+The checked-in `spec/fixtures/responses/*.json` files contain one synthetic
+example per response type, assembled from the official schema snapshot. They exercise optional
+properties as well as the required ones. They are examples of response shapes,
+not successful live recordings or evidence that every optional property occurs
+together. Tests never load the gitignored `schema/` directory. The authoritative
+reference is the [Speedy API documentation](https://api.speedy.bg/api/docs/).
+
+The recursive `expect_response_properties(actual, raw)` assertion derives a
+snake_case accessor independently from each original JSON key. It calls the
+accessor and compares every leaf with the original response value, including
+false, zero, explicit null, nested models and every array item. The three
+explicit dictionary structures (`details`, `detailsLocal`, and
+`externalCarrierParcelNumbersDetails`) use hash-key lookup, not dot readers;
+dictionaries retain the client's existing snake_case normalization
+of keys, and typed dictionary values are checked using their model accessors.
+Unknown scalar attributes are also checked. Regression examples prove the
+helper rejects absent accessors, dropped nested fields, incorrect values and
+raw hashes in place of typed nested models.
+
+There are two explicit conversions rather than consulting the model's field
+definitions to manufacture expected values: documented Date accessors use
+`Date.parse`, and a null parcel array becomes `[]` under the existing array
+casting contract. CSV cases independently list every expected column and its
+typed value. Scalar client IDs and barcode lists are compared directly; empty
+success objects have no leaf properties. PDF methods compare unchanged bytes,
+including binary data. Error objects are checked through both a resource and a
+collection response.
+
+## Schema limitations and discrepancies
+
+- Extended print's schema describes `data` as an integer array, while the
+  documentation describes a base64 string. Its example follows the documented
+  JSON representation.
+- External carrier parcel details are documented as a map, so populated maps
+  now return typed values instead of being treated as arrays. Empty arrays
+  seen in recordings remain readable for compatibility.
+- Calculation additional services, courier-service allowances and office
+  maximum parcel dimensions now expose schema-backed nested model readers.
+- The schema's unresolved `OfficeRoutingInformation` reference is covered by
+  the documentation's [RoutingInformation definition, section 3.34](https://api.speedy.bg/api/docs/#href-routing-information)
+  and [Tour definition, section 3.34.1](https://api.speedy.bg/api/docs/#href-routing-information-tour).
+  Office responses now expose typed routing and tour readers; all three office
+  JSON examples contain populated routing data checked recursively.
+- `WorkDayType` and `DeliveryLimitViolationAutoAdjustment` have unresolved references in the
+  available schema snapshot. Their example values are null; no nested contract
+  is invented for these structures.
+- These examples test parsing and accessor fidelity. Existing VCR/live specs
+  remain the evidence for actual server behavior and account restrictions.

data/docs/VCR.md

@@ -0,0 +1,161 @@
+# VCR contract testing
+
+The opt-in contract suite records real read-only API responses and replays them
+later with external network access disabled. Each endpoint has an independent
+cassette. Public nomenclature contracts run with stable Bulgarian defaults;
+account and shipment reads require the fixture identifiers described in
+`.env.example` and are structurally sanitized before being written.
+
+CI runs the committed recordings separately from the opt-in live suite:
+
+```bash
+SPEEDY_VCR_REPLAY=1 bundle exec rspec spec/recorded_contract_spec.rb
+```
+
+Replay does not load `.env` files or require carrier credentials. It uses
+`record: :none`, rejects unmatched requests, and blocks network access even if
+a cassette's record mode is overridden. Missing cassettes cannot be recorded by CI.
+
+PDF printing has read-only contracts in `spec/live/printing_contract_spec.rb`.
+They use existing demo parcel/shipment IDs and never pass `printerName`, so no
+physical printing is requested. Raw PDF bodies and base64 PDF data are replaced
+entirely before recording; metadata is structurally sanitized. Replays verify
+the response envelope, document signature and metadata types, not PDF contents
+or visual correctness. The retained PDF signature is only kept when the actual
+document starts with `%PDF-`; unexpected opaque bodies are replaced with a
+non-PDF marker so a failed request cannot become a passing PDF fixture.
+
+To record these contracts, set `SPEEDY_CONTRACT_PARCEL_IDS` and
+`SPEEDY_CONTRACT_SHIPMENT_IDS` to existing, printable demo fixtures, then run:
+
+```bash
+SPEEDY_LIVE_TESTS=1 bundle exec rspec spec/live/printing_contract_spec.rb
+```
+
+ZPL output is not covered by these PDF-specific contracts.
+
+Offline request-shape specs exercise every explicit public keyword at least
+once. Hash payloads and `**options` pass through generic serialization, so their
+documented representative fields and model casting are tested without trying
+every possible field combination. Live contracts use the smallest meaningful
+payload for each server behavior; they are not a parameter-permutation suite.
+
+## Coverage policy
+
+| Endpoint kind | Contract approach |
+| --- | --- |
+| Public location and service nomenclatures | Recorded directly, one cassette per endpoint |
+| Client, payout, calculation, shipment, tracking, and label-info reads | Recorded with dedicated demo fixtures and structural response redaction |
+| Bulk CSV nomenclatures | Opt-in because Speedy may require account permission; one cassette per dataset |
+| PDF labels, extended PDF labels, and PDF vouchers | Read-only fixtures; opaque document contents replaced entirely before recording |
+| ZPL output | Offline coverage only; no live ZPL contract yet |
+| Shipment, pickup, contact, and courier mutations | Excluded from the read-only suite; use the lifecycle pattern below |
+
+## Mutating endpoints
+
+VCR only records HTTP; it does not roll back the carrier. Projects that test
+creation or updates against a real sandbox usually record a complete scenario:
+
+1. create a uniquely identifiable shipment/contact/pickup in a dedicated demo
+   account;
+2. exercise the update, handover, or cancellation;
+3. query and assert the resulting server state;
+4. cancel or delete the fixture in an `ensure` cleanup block; and
+5. record and verify the cleanup response in the same cassette.
+
+Recording is manual. CI only replays reviewed cassettes and must never have
+network access or carrier credentials. If cleanup is unavailable or unreliable,
+use a provider-reset sandbox, disposable pre-provisioned fixtures, or an offline
+request-shape test instead of a live mutation.
+
+Before committing a recording, verify cleanup in the carrier UI, inspect the
+diff, scan for credentials and personal data, and retain JSON types when
+replacing identifiers. Never bulk re-record the entire suite automatically;
+delete and refresh one cassette at a time.
+
+## Reviewed mutation example
+
+`spec/live/shipment_mutation_contract_spec.rb` implements the lifecycle above
+for shipment creation. It creates a synthetic office-delivery shipment and
+cancels it in an `ensure` block, then calls `shipment_info` to document that
+Speedy retains the cancelled shipment as a historical record. It then tracks
+the created parcel with its full operation history. The demo recording returns
+an empty operation list immediately after cancellation, which the example
+asserts. All four interactions are stored in
+`speedy_api/shipment_create_cancel_and_verify.yml`; the generated shipment ID
+is filtered.
+
+The example requires an additional, deliberate opt-in:
+
+```bash
+SPEEDY_LIVE_TESTS=1 SPEEDY_MUTATING_LIVE_TESTS=1 \
+  bundle exec rspec spec/live/shipment_mutation_contract_spec.rb
+```
+
+Before recording, verify that `SPEEDY_CONTRACT_OFFICE_ID` accepts service 505
+and that the configured sender client may create shipments. A successful
+`shipment/cancel` response is the authoritative cleanup confirmation. The
+documented `shipment/info` response has no cancellation-status field, so the
+final lookup verifies record retention and the generated identifier but cannot
+independently prove cancellation. Tracking operation `128` means Canceled, but
+the recorded uncollected shipment has no tracking operations after cancellation.
+Neither an empty tracking history nor a retained shipment record independently
+proves cancellation. This lifecycle relies on the documented successful cancel
+response for cleanup confirmation. There is no documented dedicated cancellation
+status field in the shipment information response.
+
+## Mutation cleanup inventory
+
+The classifications below describe the published API, not a guarantee that a
+demo account accepts every payload. Cancellation is compensating cleanup: it
+leaves a historical record and does not roll back all stored data.
+Sources: [shipment, pickup, and contact API documentation](https://api.speedy.bg/api/docs/).
+
+### Clear documented cleanup paths
+
+| Endpoint | Scenario and cleanup | Recording status |
+| --- | --- | --- |
+| Create and cancel shipment | Create an uncollected shipment without requesting pickup; cancel it in `ensure` | Existing demo cassette confirms successful cancellation |
+| Update shipment | Create a disposable shipment, replace its contents, query the changed contents, cancel | Recorded as `shipment_update_and_cancel` |
+| Update shipment properties | Create a disposable shipment, change the `contents` property, query it, cancel | Recorded as `shipment_properties_and_cancel` |
+
+All scenarios are in `spec/live/shipment_mutation_contract_spec.rb` and use
+separate cassettes. Cleanup runs even if an operation or assertion fails after
+creation returns an identifier. If creation times out before returning an ID,
+automatic cleanup cannot identify the remote fixture; reconcile the account
+before retrying. Cleanup failures fail the example and require manual review.
+No pickup or handover is performed.
+
+Existing cassettes replay as usual; do not delete them without planning another
+disposable fixture. Read-back assertions check contents before cleanup. Successful
+`shipment/cancel` remains the cancellation confirmation, not tracking history.
+
+### Unavailable in the standard demo account
+
+Adding parcels and finalizing a pending shipment require permission to create
+with `pendingParcels`. The standard test account does not have this permission,
+so these endpoints have offline request/model coverage only. The live lifecycle
+and its capability flag were removed. Cancelling the parent shipment is the
+documented cleanup approach for an authorized account, but that path has not
+been verified in the demo environment.
+
+### Suggested cleanup with uncertain effectiveness
+
+| Endpoint | Possible approach | Uncertainty |
+| --- | --- | --- |
+| Request pickup | Cancel every associated disposable shipment, then ask the carrier to cancel/reset the pickup order | Cancelling shipments is not documented to cancel the courier visit or pickup order; no pickup cancellation endpoint is exposed |
+
+This is a suggestion only and has no live mutation spec. Confirm order-level
+cleanup with the carrier before recording it.
+
+### No obvious API cleanup path
+
+| Endpoint/action | Missing inverse |
+| --- | --- |
+| Create contact | No contact-delete endpoint; overwriting a contact would not remove it and could alter an existing account record |
+| Handover to courier | No undo-handover endpoint; do not assume shipment cancellation reverses a registered handover |
+| Handover to midway carrier | No undo for the registered external handover |
+| Direct printing using `printerName` | Physical printing cannot be undone through the API; read-only print contracts omit this option |
+
+These need carrier-managed reset or explicitly disposable fixtures. They remain
+covered offline rather than by automatic live mutation scenarios.

data/docs/schema-notes.md

@@ -0,0 +1,38 @@
+# Speedy schema fidelity notes
+
+The implementation is based on the JSON schemas distributed with Speedy's API
+documentation. Those files describe payload shapes, but a schema file alone is
+not evidence that a public HTTP route exists or remains enabled for every
+account.
+
+## Address search schemas without a route
+
+The schema bundle contains `SearchAddressRequest`, `SearchAddressResponse`, and
+`SearchAddress`. The request describes site, complex, street,
+point-of-interest, and building-number inputs, while the response contains
+address suggestions. However, the provided endpoint documentation does not
+associate those types with an HTTP path.
+
+No route is inferred from the Java package identifier or type name because an
+incorrect route could create an apparently supported API that fails against
+real accounts. Consequently, `Speedy::Client` does not expose address search.
+It can be added compatibly when Speedy publishes an authoritative route and
+request contract.
+
+## Representation decisions
+
+- JSON object responses with documented fields use typed `Speedy::Model`
+  subclasses.
+- Batch responses use `Speedy::Collection`, preserving top-level API errors.
+- PDF and ZPL endpoints return binary strings; the gem does not decode or write
+  them to disk.
+- CSV nomenclature exports are parsed into the same model classes as JSON
+  nomenclature results.
+- Fields whose nested shape is not defined authoritatively remain arrays,
+  hashes, or untyped model attributes rather than speculative classes.
+- Undocumented fields are preserved in `Model#to_h`, so additive carrier
+  changes do not discard information.
+
+These notes describe documentation-derived support. They are not a substitute
+for testing with the Speedy environment and permissions assigned to a specific
+contract.

data/lib/speedy/camel_case_middleware.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'faraday'
+
+module Speedy
+  class CamelCaseMiddleware < Faraday::Middleware
+    DEFAULT_ACRONYMS = {
+      'id' => 'Id',
+      'ids' => 'Ids',
+      'cod' => 'COD',
+      'pudo' => 'PUDO'
+    }.freeze
+
+    def initialize(app, acronyms: {}, replace_defaults: false)
+      super(app)
+      @acronyms =
+        if acronyms.nil?
+          {}
+        elsif replace_defaults
+          acronyms.transform_keys(&:to_s)
+        else
+          DEFAULT_ACRONYMS.merge(acronyms.transform_keys(&:to_s))
+        end
+      @acronym_reverse = @acronyms.each_with_object({}) { |(key, value), hash| hash[value] = key }
+    end
+
+    def call(env)
+      env.body = deep_transform_keys(env.body) { |key| to_camel_case(key) } if env.body.is_a?(Hash)
+      @app.call(env)
+    end
+
+    def on_complete(env)
+      env.body = deep_transform_keys(env.body) { |key| to_snake_case(key) } if env.body.is_a?(Hash)
+    end
+
+    private
+
+    def to_camel_case(key)
+      parts = key.to_s.split('_')
+      first = parts.shift
+
+      first + parts.map { |part| @acronyms.fetch(part, part.capitalize) }.join
+    end
+
+    def to_snake_case(key)
+      str = key.to_s
+      @acronym_reverse.keys.sort_by { |acro| -acro.length }.each do |acro|
+        str = str.gsub(/#{acro}(?=[A-Z]|$)/) { "_#{@acronym_reverse[acro]}_" }
+      end
+
+      str
+        .gsub(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2')
+        .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+        .downcase
+        .gsub(/__+/, '_')
+        .sub(/^_/, '')
+        .sub(/_$/, '')
+    end
+
+    def deep_transform_keys(obj, &block)
+      case obj
+      when Array
+        obj.map { |item| deep_transform_keys(item, &block) }
+      when Hash
+        obj.each_with_object({}) { |(key, value), hash| hash[yield(key)] = deep_transform_keys(value, &block) }
+      else
+        obj
+      end
+    end
+  end
+end

data/lib/speedy/client.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+require 'logger'
+
+module Speedy
+  class Client
+    include Speedy::ClientResources
+
+    class << self
+      attr_reader :instance
+
+      def configure
+        @instance ||= new
+        yield(@instance) if block_given?
+        @instance.setup_connection!
+      end
+
+      def connection
+        instance&.connection || raise('Speedy::Client is not configured. Call Speedy::Client.configure first.')
+      end
+    end
+
+    attr_accessor :username, :password, :base_url, :adapter,
+                  :language, :client_system_id,
+                  :acronyms, :replace_acronym_defaults,
+                  :debug, :debug_bodies, :debug_logger,
+                  :open_timeout, :read_timeout, :write_timeout
+
+    def initialize
+      @base_url = 'https://api.speedy.bg/v1/'
+      @adapter = Faraday.default_adapter
+      @language = nil
+      @client_system_id = nil
+      @acronyms = {}
+      @replace_acronym_defaults = false
+      @debug = false
+      @debug_bodies = false
+      @debug_logger = Logger.new($stdout)
+      @open_timeout = 30
+      @read_timeout = 30
+      @write_timeout = 30
+    end
+
+    def add_acronyms(hash)
+      @acronyms = (@acronyms || {}).merge(hash.transform_keys(&:to_s))
+    end
+
+    def setup_connection!
+      validate_credentials!
+
+      @connection = Faraday.new(base_url) do |conn|
+        configure_timeouts(conn)
+        conn.use Speedy::CamelCaseMiddleware,
+                 acronyms: @acronyms,
+                 replace_defaults: @replace_acronym_defaults
+        conn.request :json
+        conn.response :json, content_type: 'application/json'
+        configure_debug_logging(conn) if debug
+        conn.adapter(*Array(adapter))
+        conn.headers['User-Agent'] = "SpeedyRubyClient/#{Speedy::VERSION}"
+      end
+    end
+
+    def connection
+      @connection || raise('Connection is not initialized. Call Speedy::Client.configure first.')
+    end
+
+    def credentials
+      {
+        user_name: username,
+        password: password,
+        language: language,
+        client_system_id: client_system_id
+      }.compact
+    end
+
+    private
+
+    def configure_debug_logging(connection)
+      connection.response :logger, debug_logger, bodies: debug_bodies do |formatter|
+        [username, password, client_system_id].each do |value|
+          formatter.filter(value.to_s, '[FILTERED]') unless value.to_s.empty?
+        end
+      end
+    end
+
+    def configure_timeouts(connection)
+      connection.options.open_timeout = open_timeout
+      connection.options.timeout = read_timeout
+      connection.options.write_timeout = write_timeout if connection.options.respond_to?(:write_timeout=)
+    end
+
+    def validate_credentials!
+      creds_missing = [username, password].any? { |credential| credential.to_s.empty? }
+      raise 'Username and password must be set' if creds_missing
+    end
+  end
+end