bluexpress 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bf2fd85cf12df5b1a882fae6c993366b4aa6511505ed000f485561445a926ad9
+  data.tar.gz: 0d7782e8f5f0f87219e39db53a2feecf6a23c7f7bf049860cf4c69e71628714a
+SHA512:
+  metadata.gz: 46c35f2c04e62dfc4dd0d62c7b0b17f2b0bf93d52a98b9cf8473d6ec4e02c61e12e3ef6ca50a16be0a5d25bf2e85d076cc023acda366dd05b77182be2791012a
+  data.tar.gz: 8c2a82fc1a36e9fc6f8169561529042b1403fd20e6aa72e6ba441d63a06cd6d2bf9d8a6d19fb1aa6630a7dd786cbf314a6db7dd30dec1f25334c8e496ce7eca7

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Bootic
+
+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,129 @@
+# Bluexpress
+
+Unofficial Ruby gem for integrating with BlueX shipping APIs.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'bluexpress'
+```
+
+Or install directly:
+
+```bash
+gem install bluexpress
+```
+
+## Usage
+
+```ruby
+require 'bluexpress'
+
+client = Bluexpress::Client.new(
+  api_key: ENV['BLUEXPRESS_API_KEY'],
+  environment: :qa,  # or :production, :dev
+  account_name: 'https://your-store.com'
+)
+
+# Get shipping pricing
+pricing = client.get_pricing(
+  from: { country: 'CL', district: 'SCL' },
+  to: { country: 'CL', district: 'PRO' },
+  service_type: 'EX',
+  bultos: [{ largo: 10, ancho: 10, alto: 10, sku: 'SKU1', peso_fisico: 1, cantidad: 1 }],
+  declared_value: 10000,
+  familia_producto: 'PAQU'
+)
+
+# Resolve geolocation
+geo = client.get_geolocation(
+  address: 'Providencia',
+  region_code: '13'
+)
+
+# Check integration status
+status = client.validate_integration_status
+
+# Update credentials
+client.update_integration_credentials(
+  store_id: 'store-123',
+  client_key: 'your_key',
+  client_secret: 'your_secret'
+)
+
+# Send order webhook
+client.send_order_webhook(order_payload: { id: 1001, shipping_lines: 'bluex-express' })
+
+# Send log webhook
+client.send_log_webhook(error: 'Pricing failed', order: { id: 1001 })
+```
+
+## Error Handling
+
+```ruby
+begin
+  client.get_pricing(...)
+rescue Bluexpress::ConfigError => e
+  puts "Configuration error: #{e.message}"
+rescue Bluexpress::ValidationError => e
+  puts "Validation error at #{e.endpoint}: #{e.issues}"
+rescue Bluexpress::ApiError => e
+  puts "API error #{e.http_status} at #{e.endpoint}: #{e.body}"
+end
+```
+
+## CLI
+
+Install the gem and use the `bluexpress` command:
+
+```bash
+# Set environment variables
+export BLUEXPRESS_API_KEY=your_api_key
+export BLUEXPRESS_ENV=qa
+
+# Get pricing
+bluexpress pricing \
+  --from-country=CL --from-district=SCL \
+  --to-country=CL --to-district=PRO \
+  --service-type=EX --familia-producto=PAQU \
+  --declared-value=10000 \
+  --bultos='[{"largo":10,"ancho":10,"alto":10,"sku":"SKU1","pesoFisico":1,"cantidad":1}]'
+
+# Get geolocation
+bluexpress geolocation --address="Providencia" --region-code="13"
+
+# Check integration status
+bluexpress status
+
+# Update credentials
+bluexpress credentials --store-id="store-123" --client-key="key" --client-secret="secret"
+
+# Send order webhook
+bluexpress order --payload='{"id":1001}'
+
+# Send log
+bluexpress log --error="Error message" --order='{"id":1001}'
+```
+
+## Development
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests
+rake spec
+
+# Run specific test types
+rake spec_unit
+rake spec_contract
+
+# Lint
+rake lint
+```
+
+## License
+
+MIT License - see LICENSE file

data/bin/bluexpress

@@ -0,0 +1,264 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bluexpress"
+require "json"
+require "optparse"
+
+module Bluexpress
+  class CLI
+    def initialize
+      @config = {}
+      parse_options!
+      load_env_vars!
+      validate_config!
+    end
+
+    def run
+      case @config[:command]
+      when "pricing"
+        run_pricing
+      when "geolocation"
+        run_geolocation
+      when "status"
+        run_status
+      when "credentials"
+        run_credentials
+      when "order"
+        run_order
+      when "log"
+        run_log
+      else
+        puts help_text
+        exit 1
+      end
+    end
+
+    private
+
+    def parse_options!
+      OptionParser.new do |opts|
+        opts.banner = "Usage: bluexpress [options] [command] [command_options]"
+
+        opts.on("--api-key=KEY", "BlueX API key") { |v| @config[:api_key] = v }
+        opts.on("--environment=ENV", [:production, :qa, :dev], "Environment (production, qa, dev)") { |v| @config[:environment] = v }
+        opts.on("--account-name=NAME", "Account name (URL)") { |v| @config[:account_name] = v }
+        opts.on("--base-url=URL", "Custom base URL") { |v| @config[:base_url] = v }
+        opts.on("--timeout=SECONDS", Integer, "Request timeout (default: 30)") { |v| @config[:timeout] = v }
+        opts.on("-h", "--help", "Show this help") { puts opts; exit }
+      end.parse!
+
+      @config[:command] = ARGV[0]
+      @config[:command_args] = ARGV[1..]
+    end
+
+    def load_env_vars!
+      @config[:api_key] ||= ENV["BLUEXPRESS_API_KEY"]
+      @config[:environment] ||= (ENV["BLUEXPRESS_ENV"] || "production").to_sym
+      @config[:account_name] ||= ENV["BLUEXPRESS_ACCOUNT_NAME"]
+      @config[:base_url] ||= ENV["BLUEXPRESS_BASE_URL"]
+      @config[:timeout] ||= (ENV["BLUEXPRESS_TIMEOUT"] || 30).to_i
+    end
+
+    def validate_config!
+      raise "api_key is required. Set BLUEXPRESS_API_KEY or use --api-key" unless @config[:api_key]
+    end
+
+    def client
+      @client ||= Bluexpress::Client.new(
+        api_key: @config[:api_key],
+        environment: @config[:environment],
+        account_name: @config[:account_name],
+        base_url: @config[:base_url],
+        timeout: @config[:timeout]
+      )
+    end
+
+    def run_pricing
+      args = parse_pricing_args!
+      puts JSON.pretty_generate(client.get_pricing(**args))
+    end
+
+    def parse_pricing_args!
+      opts = {}
+
+      OptionParser.new do |p|
+        p.on("--from-country=COUNTRY") { |v| opts[:from] ||= {}; opts[:from][:country] = v }
+        p.on("--from-district=DISTRICT") { |v| opts[:from] ||= {}; opts[:from][:district] = v }
+        p.on("--from-state=STATE") { |v| opts[:from] ||= {}; opts[:from][:state] = v }
+        p.on("--to-country=COUNTRY") { |v| opts[:to] ||= {}; opts[:to][:country] = v }
+        p.on("--to-district=DISTRICT") { |v| opts[:to] ||= {}; opts[:to][:district] = v }
+        p.on("--to-state=STATE") { |v| opts[:to] ||= {}; opts[:to][:state] = v }
+        p.on("--service-type=TYPE") { |v| opts[:service_type] = v }
+        p.on("--familia-producto=FAM") { |v| opts[:familia_producto] = v }
+        p.on("--declared-value=VALUE", Integer) { |v| opts[:declared_value] = v }
+        p.on("--domain=URL") { |v| opts[:domain] = v }
+        p.on("--bultos=JSON") { |v| opts[:bultos] = JSON.parse(v) }
+        p.on("-h", "--help", "Show pricing help") { puts p; exit }
+      end.parse!(@config[:command_args])
+
+      required = [:from, :to, :service_type, :bultos, :declared_value, :familia_producto]
+      missing = required.reject { |k| opts[k] }
+      raise "Missing required options: #{missing.join(', ')}" unless missing.empty?
+
+      opts[:bultos] = opts[:bultos].map do |b|
+        {
+          largo: b["largo"] || b[:largo],
+          ancho: b["ancho"] || b[:ancho],
+          alto: b["alto"] || b[:alto],
+          sku: b["sku"] || b[:sku],
+          peso_fisico: b["pesoFisico"] || b[:peso_fisico],
+          cantidad: b["cantidad"] || b[:cantidad]
+        }
+      end
+
+      opts
+    end
+
+    def run_geolocation
+      args = parse_geolocation_args!
+      puts JSON.pretty_generate(client.get_geolocation(**args))
+    end
+
+    def parse_geolocation_args!
+      opts = {}
+
+      OptionParser.new do |p|
+        p.on("--address=ADDRESS") { |v| opts[:address] = v }
+        p.on("--region-code=CODE") { |v| opts[:region_code] = v }
+        p.on("--is-pudo=[true|false]") { |v| opts[:is_pudo] = v == "true" }
+        p.on("--agency-id=ID") { |v| opts[:agency_id] = v }
+        p.on("--type=TYPE") { |v| opts[:type] = v }
+        p.on("--shop=URL") { |v| opts[:shop] = v }
+        p.on("-h", "--help", "Show geolocation help") { puts p; exit }
+      end.parse!(@config[:command_args])
+
+      raise "Missing required: --address and --region-code" unless opts[:address] && opts[:region_code]
+
+      opts
+    end
+
+    def run_status
+      puts JSON.pretty_generate(client.validate_integration_status)
+    end
+
+    def run_credentials
+      args = parse_credentials_args!
+      puts JSON.pretty_generate(client.update_integration_credentials(**args))
+    end
+
+    def parse_credentials_args!
+      opts = {}
+
+      OptionParser.new do |p|
+        p.on("--store-id=ID") { |v| opts[:store_id] = v }
+        p.on("--client-key=KEY") { |v| opts[:client_key] = v }
+        p.on("--client-secret=SECRET") { |v| opts[:client_secret] = v }
+        p.on("--ecommerce=NAME") { |v| opts[:ecommerce] = v }
+        p.on("-h", "--help", "Show credentials help") { puts p; exit }
+      end.parse!(@config[:command_args])
+
+      required = [:store_id, :client_key, :client_secret]
+      missing = required.reject { |k| opts[k] }
+      raise "Missing required options: #{missing.join(', ')}" unless missing.empty?
+
+      opts
+    end
+
+    def run_order
+      args = parse_order_args!
+      puts JSON.pretty_generate(client.send_order_webhook(**args))
+    end
+
+    def parse_order_args!
+      opts = {}
+
+      OptionParser.new do |p|
+        p.on("--payload=JSON") { |v| opts[:order_payload] = JSON.parse(v) }
+        p.on("-h", "--help", "Show order help") { puts p; exit }
+      end.parse!(@config[:command_args])
+
+      raise "Missing required: --payload JSON" unless opts[:order_payload]
+
+      opts
+    end
+
+    def run_log
+      args = parse_log_args!
+      puts JSON.pretty_generate(client.send_log_webhook(**args))
+    end
+
+    def parse_log_args!
+      opts = {}
+
+      OptionParser.new do |p|
+        p.on("--error=MESSAGE") { |v| opts[:error] = v }
+        p.on("--order=JSON") { |v| opts[:order] = JSON.parse(v) }
+        p.on("-h", "--help", "Show log help") { puts p; exit }
+      end.parse!(@config[:command_args])
+
+      required = [:error, :order]
+      missing = required.reject { |k| opts[k] }
+      raise "Missing required options: #{missing.join(', ')}" unless missing.empty?
+
+      opts
+    end
+
+    def help_text
+      <<~HELP
+        BlueXpress CLI - Ruby client for BlueX shipping API
+
+        Usage:
+          bluexpress [global options] command [command options]
+
+        Global Options:
+          --api-key=KEY          BlueX API key (or BLUEXPRESS_API_KEY env)
+          --environment=ENV      Environment: production, qa, dev (default: production)
+          --account-name=URL     Account name (or BLUEXPRESS_ACCOUNT_NAME env)
+          --base-url=URL         Custom base URL (or BLUEXPRESS_BASE_URL env)
+          --timeout=SECONDS      Request timeout (default: 30)
+
+        Commands:
+          pricing                Get shipping pricing
+          geolocation            Resolve geographic codes
+          status                 Check integration status
+          credentials            Update integration credentials
+          order                  Send order webhook
+          log                    Send log webhook
+
+        Examples:
+          bluexpress pricing --from-country=CL --from-district=SCL \\
+                             --to-country=CL --to-district=PRO \\
+                             --service-type=EX --familia-producto=PAQU \\
+                             --declared-value=10000 \\
+                             --bultos='[{"largo":10,"ancho":10,"alto":10,"sku":"SKU1","pesoFisico":1,"cantidad":1}]'
+
+          bluexpress geolocation --address="Providencia" --region-code="13"
+
+          bluexpress status
+
+          bluexpress credentials --store-id="store-123" --client-key="key" --client-secret="secret"
+
+          bluexpress order --payload='{"id":1001,"shipping_lines":"bluex-express"}'
+
+          bluexpress log --error="Pricing failed" --order='{"id":1001}'
+
+        Environment Variables:
+          BLUEXPRESS_API_KEY       Your BlueX API key
+          BLUEXPRESS_ENV           Environment (production, qa, dev)
+          BLUEXPRESS_ACCOUNT_NAME  Your store URL
+          BLUEXPRESS_BASE_URL      Custom base URL
+          BLUEXPRESS_TIMEOUT       Request timeout in seconds
+      HELP
+    end
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  begin
+    Bluexpress::CLI.new.run
+  rescue => e
+    $stderr.puts "Error: #{e.message}"
+    exit 1
+  end
+end

data/lib/bluexpress/client.rb

@@ -0,0 +1,296 @@
+# frozen_string_literal: true
+
+require "httparty"
+
+module Bluexpress
+  class Client
+    attr_reader :api_key, :account_name, :base_url, :timeout
+
+    def initialize(api_key:, environment: :production, account_name: nil, base_url: nil, timeout: 30)
+      validate_config(api_key: api_key, base_url: base_url, environment: environment)
+
+      @api_key = api_key
+      @account_name = account_name
+      @environment = environment
+      @base_url = base_url || BASE_URLS.fetch(environment)
+      @timeout = timeout
+    end
+
+    def get_pricing(from:, to:, service_type:, bultos:, declared_value:, familia_producto:, domain: nil)
+      input = {
+        from: from,
+        to: to,
+        service_type: service_type,
+        bultos: bultos,
+        declared_value: declared_value,
+        familia_producto: familia_producto,
+        domain: domain || account_name
+      }
+
+      result = Validators.validate_pricing_request(input)
+      raise ValidationError.new("Payload does not match expected contract", endpoint: "/eplin/pricing/v1", issues: result.errors) unless result.valid?
+
+      payload = build_pricing_payload(input)
+
+      request(
+        method: :post,
+        path: "/eplin/pricing/v1",
+        body: payload,
+        extra_headers: { "price" => String(declared_value) },
+        response_schema: :pricing
+      )
+    end
+
+    def get_geolocation(address:, region_code:, is_pudo: false, agency_id: nil, type: "woocommerce", shop: nil)
+      input = {
+        address: address,
+        region_code: region_code,
+        is_pudo: is_pudo,
+        agency_id: agency_id,
+        type: type,
+        shop: shop || account_name
+      }
+
+      result = Validators.validate_geolocation_request(input)
+      raise ValidationError.new("Payload does not match expected contract", endpoint: "/api/ecommerce/comunas/v1/bxgeo", issues: result.errors) unless result.valid?
+
+      path = is_pudo ? "/api/ecommerce/comunas/v1/bxgeo/v2" : "/api/ecommerce/comunas/v1/bxgeo"
+
+      request(
+        method: :post,
+        path: path,
+        body: build_geolocation_payload(input),
+        response_schema: :geolocation
+      )
+    end
+
+    def validate_integration_status(ecommerce: "Woocommerce", account_name: nil)
+      input = {
+        ecommerce: ecommerce,
+        account_name: account_name || self.account_name
+      }
+
+      request(
+        method: :post,
+        path: "/api/ecommerce/token/v1/ecommerce/integration-status",
+        body: snake_to_camel(input.compact),
+        response_schema: :integration_status
+      )
+    end
+
+    def update_integration_credentials(store_id:, client_key:, client_secret:, ecommerce: "Woocommerce", account_name: nil)
+      input = {
+        store_id: store_id,
+        credentials: {
+          client_key: client_key,
+          client_secret: client_secret
+        },
+        ecommerce: ecommerce,
+        account_name: account_name || self.account_name
+      }
+
+      result = Validators.validate_update_credentials_request(input)
+      raise ValidationError.new("Payload does not match expected contract", endpoint: "/api/ecommerce/token/v1/ecommerce/update-tokens", issues: result.errors) unless result.valid?
+
+      request(
+        method: :post,
+        path: "/api/ecommerce/token/v1/ecommerce/update-tokens",
+        body: build_update_credentials_payload(input),
+        response_schema: :integration_status
+      )
+    end
+
+    def send_order_webhook(order_payload)
+      request(
+        method: :post,
+        path: "/api/integr/woocommerce-wh/v1/order",
+        body: order_payload,
+        response_schema: :webhook
+      )
+    end
+
+    def send_log_webhook(error:, order:)
+      input = { error: error, order: order }
+
+      result = Validators.validate_log_webhook_request(input)
+      raise ValidationError.new("Payload does not match expected contract", endpoint: "/api/ecommerce/custom/logs/v1", issues: result.errors) unless result.valid?
+
+      request(
+        method: :post,
+        path: "/api/ecommerce/custom/logs/v1",
+        body: snake_to_camel(input),
+        response_schema: :webhook
+      )
+    end
+
+    private
+
+    def validate_config(api_key:, base_url:, environment:)
+      raise ConfigError, "api_key is required" if api_key.nil? || api_key.to_s.strip.empty?
+
+      if base_url
+        begin
+          uri = URI.parse(base_url)
+          unless uri.scheme && uri.host
+            raise ConfigError, "base_url must be a valid absolute URL (e.g., https://api.example.com)"
+          end
+        rescue URI::Error
+          raise ConfigError, "base_url must be a valid absolute URL (e.g., https://api.example.com)"
+        end
+      end
+
+      unless VALID_ENVIRONMENTS.include?(environment)
+        raise ConfigError, "environment must be one of: #{VALID_ENVIRONMENTS.join(', ')}"
+      end
+    end
+
+    def request(method:, path:, body: nil, extra_headers: {}, response_schema: nil)
+      url = URI.join(base_url, path).to_s
+      headers = {
+        "Content-Type" => "application/json",
+        "x-api-key" => api_key
+      }.merge(extra_headers)
+
+      options = {
+        headers: headers,
+        timeout: timeout
+      }
+
+      options[:body] = body.to_json if body
+
+      begin
+        response = HTTParty.send(method, url, options)
+        handle_response(response, url, response_schema)
+      rescue Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNREFUSED, SocketError => e
+        raise ApiError.new("BlueX API request failed: #{e.message}", http_status: nil, endpoint: url, body: nil)
+      end
+    end
+
+    def handle_response(response, url, schema)
+      if response.code == 200 || response.code == 201
+        parse_response_body(response.body, schema, url)
+      else
+        error_body = parse_json(response.body)
+        message = extract_error_message(error_body) || response.message
+        raise ApiError.new(message, http_status: response.code, endpoint: url, body: error_body)
+      end
+    rescue ApiError
+      raise
+    rescue JSON::ParserError
+      raise ApiError.new("Invalid JSON response from BlueX API", http_status: response.code, endpoint: url, body: response.body)
+    end
+
+    def parse_json(body)
+      return {} if body.nil? || body.strip.empty?
+
+      JSON.parse(body, symbolize_names: true)
+    rescue JSON::ParserError
+      {}
+    end
+
+    def parse_response_body(body, schema, url)
+      data = parse_json(body)
+
+      case schema
+      when :pricing
+        validate_pricing_response(data, url)
+      when :geolocation
+        validate_geolocation_response(data, url)
+      when :integration_status
+        validate_integration_status_response(data, url)
+      when :webhook
+        data
+      else
+        data
+      end
+    end
+
+    def validate_pricing_response(data, url)
+      required_keys = [:code, :message]
+      missing = required_keys.reject { |k| data.key?(k) || data.key?(k.to_s) }
+
+      raise ValidationError.new("Response from BlueX does not match expected contract", endpoint: url, issues: ["Missing keys: #{missing.join(', ')}"]) unless missing.empty?
+
+      camel_to_snake(data)
+    end
+
+    def validate_geolocation_response(data, url)
+      raise ValidationError.new("Response from BlueX does not match expected contract", endpoint: url, issues: ["Empty response"]) if data.nil? || data.empty?
+
+      camel_to_snake(data)
+    end
+
+    def validate_integration_status_response(data, url)
+      camel_to_snake(data)
+    end
+
+    def build_pricing_payload(input)
+      {
+        from: snake_to_camel(input[:from]),
+        to: snake_to_camel(input[:to]),
+        serviceType: input[:service_type],
+        domain: input[:domain],
+        datosProducto: {
+          producto: "P",
+          familiaProducto: input[:familia_producto],
+          bultos: input[:bultos].map { |b| snake_to_camel(b) }
+        }
+      }
+    end
+
+    def build_geolocation_payload(input)
+      {
+        address: input[:address],
+        type: input[:type],
+        shop: input[:shop],
+        regionCode: input[:region_code],
+        agencyId: input[:agency_id] || ""
+      }
+    end
+
+    def build_update_credentials_payload(input)
+      {
+        storeId: input[:store_id],
+        ecommerce: input[:ecommerce],
+        credentials: {
+          accessToken: input[:credentials][:client_key],
+          secretKey: input[:credentials][:client_secret],
+          accountName: input[:account_name]
+        }
+      }
+    end
+
+    def snake_to_camel(hash)
+      hash.transform_keys do |key|
+        key.to_s.gsub(/_([a-z]|[A-Z])/) { |m| m[1].upcase }.to_sym
+      end
+    end
+
+    def camel_to_snake(hash)
+      return hash unless hash.is_a?(Hash)
+
+      hash.transform_keys do |key|
+        key.to_s
+           .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+           .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+           .tr("-", "_")
+           .downcase
+           .to_sym
+      end.transform_values do |value|
+        if value.is_a?(Hash)
+          camel_to_snake(value)
+        elsif value.is_a?(Array)
+          value.map { |v| v.is_a?(Hash) ? camel_to_snake(v) : v }
+        else
+          value
+        end
+      end
+    end
+
+    def extract_error_message(body)
+      return nil unless body.is_a?(Hash)
+
+      body["message"] || body["error"] || body["errors"]&.first
+    end
+  end
+end

data/lib/bluexpress/errors.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Bluexpress
+  class ConfigError < StandardError
+    def initialize(message)
+      super(message)
+    end
+  end
+
+  class ValidationError < StandardError
+    attr_reader :endpoint, :issues
+
+    def initialize(message, endpoint: nil, issues: nil)
+      super(message)
+      @endpoint = endpoint
+      @issues = issues
+    end
+  end
+
+  class ApiError < StandardError
+    attr_reader :http_status, :endpoint, :body
+
+    def initialize(message, http_status: nil, endpoint: nil, body: nil)
+      super(message)
+      @http_status = http_status
+      @endpoint = endpoint
+      @body = body
+    end
+  end
+end

data/lib/bluexpress/validators.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Bluexpress
+  module Validators
+    class ValidationResult
+      attr_reader :data, :errors
+
+      def initialize(data, errors)
+        @data = data
+        @errors = errors
+      end
+
+      def valid?
+        errors.empty?
+      end
+    end
+
+    def self.validate_pricing_request(input)
+      errors = []
+
+      unless input[:from].is_a?(Hash) && input[:from][:country] && input[:from][:district]
+        errors << "from must be a hash with :country and :district"
+      end
+
+      unless input[:to].is_a?(Hash) && input[:to][:country] && input[:to][:district]
+        errors << "to must be a hash with :country and :district"
+      end
+
+      unless input[:service_type].is_a?(String) && !input[:service_type].empty?
+        errors << "service_type is required and must be a non-empty string"
+      end
+
+      unless input[:bultos].is_a?(Array) && input[:bultos].any?
+        errors << "bultos must be a non-empty array"
+      end
+
+      if input[:bultos]
+        input[:bultos].each_with_index do |bulto, idx|
+          required_fields = [:largo, :ancho, :alto, :sku, :peso_fisico, :cantidad]
+          missing = required_fields.reject { |f| bulto[f] }
+          errors << "bultos[#{idx}] missing required fields: #{missing.join(', ')}" unless missing.empty?
+
+          numeric_fields = [:largo, :ancho, :alto, :peso_fisico, :cantidad]
+          numeric_fields.each do |field|
+            unless bulto[field].is_a?(Numeric) && bulto[field] > 0
+              errors << "bultos[#{idx}][#{field}] must be a positive number"
+            end
+          end
+        end
+      end
+
+      unless input[:declared_value].is_a?(Numeric) && input[:declared_value] >= 0
+        errors << "declared_value must be a non-negative number"
+      end
+
+      unless input[:familia_producto].is_a?(String) && !input[:familia_producto].empty?
+        errors << "familia_producto is required and must be a non-empty string"
+      end
+
+      ValidationResult.new(input, errors)
+    end
+
+    def self.validate_geolocation_request(input)
+      errors = []
+
+      unless input[:address].is_a?(String) && !input[:address].empty?
+        errors << "address is required and must be a non-empty string"
+      end
+
+      unless input[:region_code].is_a?(String) && !input[:region_code].empty?
+        errors << "region_code is required and must be a non-empty string"
+      end
+
+      ValidationResult.new(input, errors)
+    end
+
+    def self.validate_update_credentials_request(input)
+      errors = []
+
+      unless input[:store_id].is_a?(String) && !input[:store_id].empty?
+        errors << "store_id is required and must be a non-empty string"
+      end
+
+      unless input[:credentials].is_a?(Hash)
+        errors << "credentials must be a hash"
+      end
+
+      if input[:credentials]
+        unless input[:credentials][:client_key].is_a?(String) && !input[:credentials][:client_key].empty?
+          errors << "credentials[:client_key] is required and must be a non-empty string"
+        end
+        unless input[:credentials][:client_secret].is_a?(String) && !input[:credentials][:client_secret].empty?
+          errors << "credentials[:client_secret] is required and must be a non-empty string"
+        end
+      end
+
+      ValidationResult.new(input, errors)
+    end
+
+    def self.validate_log_webhook_request(input)
+      errors = []
+
+      unless input[:error].is_a?(String) && !input[:error].empty?
+        errors << "error is required and must be a non-empty string"
+      end
+
+      unless input[:order].is_a?(Hash)
+        errors << "order must be a hash"
+      end
+
+      ValidationResult.new(input, errors)
+    end
+
+    def self.camelize_keys(hash)
+      hash.transform_keys do |key|
+        key.to_s.gsub(/_([a-z]|[A-Z])/) { |m| m[1].upcase }.to_sym
+      end.transform_values do |value|
+        if value.is_a?(Hash)
+          camelize_keys(value)
+        elsif value.is_a?(Array)
+          value.map { |v| v.is_a?(Hash) ? camelize_keys(v) : v }
+        else
+          value
+        end
+      end
+    end
+
+    def self.underscore_keys(hash)
+      hash.transform_keys do |key|
+        key.to_s
+           .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+           .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+           .tr("-", "_")
+           .downcase
+           .to_sym
+      end.transform_values do |value|
+        if value.is_a?(Hash)
+          underscore_keys(value)
+        elsif value.is_a?(Array)
+          value.map { |v| v.is_a?(Hash) ? underscore_keys(v) : v }
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/bluexpress/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Bluexpress
+  VERSION = "0.1.0".freeze
+end

data/lib/bluexpress.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Bluexpress
+  BASE_URLS = {
+    production: "https://eplin.api.blue.cl",
+    qa: "https://eplin.api.qa.blue.cl",
+    dev: "https://eplin.api.dev.blue.cl"
+  }.freeze
+
+  VALID_ENVIRONMENTS = BASE_URLS.keys.freeze
+end
+
+require_relative "bluexpress/version"
+require "bluexpress/errors"
+require "bluexpress/validators"
+require "bluexpress/client"

metadata

@@ -0,0 +1,122 @@
+--- !ruby/object:Gem::Specification
+name: bluexpress
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tomás Pollak
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.19'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.19'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Unofficial Ruby gem for integrating with BlueX shipping APIs, based on
+  the official BlueX WooCommerce plugin contracts.
+email:
+- tomas@onbolder.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- bin/bluexpress
+- lib/bluexpress.rb
+- lib/bluexpress/client.rb
+- lib/bluexpress/errors.rb
+- lib/bluexpress/validators.rb
+- lib/bluexpress/version.rb
+homepage: https://github.com/bootic/bluexpress-ruby-client
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.6
+signing_key:
+specification_version: 4
+summary: Ruby client for BlueX shipping API
+test_files: []