torque_api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a216d635ef659ea2f23c07ba8ce670693edc8a6b8358048eb921b2c6a1739af0
+  data.tar.gz: c80a94e86e03fe9cc7829ba2e077c177d61de5c42bebf5f2899af13f27f49520
+SHA512:
+  metadata.gz: 00b9dafb12806bf974976e9194269d003c426a91292d0c41923fcaea6ff92545726ecf9c6ebc4650fe5f7dda91bb883d27ca26aa0e12cb1723548abc3e37ec8a
+  data.tar.gz: 6637619950bcecee7e8164d3351bff9b3eddc24505a3569fdbd403a4b2cb82d36a9e0c69bb053667c73ed559b65c1174dade3117dc8bec7a8bac79db6fccb7c1

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## [0.1.0] - 2025-03-04
+
+### Added
+- Initial release
+- `TorqueAPI::Client` with Faraday, Basic auth, sandbox toggle, and client-specific headers
+- `TorqueAPI::PreAdviceResource` — POST `/preAdvice` (passthrough payload)
+- `TorqueAPI::ReturnRmaResource` — GET `/returnRma` with typed response objects
+- `TorqueAPI::Object` — OpenStruct-based response wrapper with auto snake_case keys and `original_response`
+- Comprehensive error hierarchy: `APIError`, `AuthenticationError`, `ValidationError`, `NotFoundError`, `RateLimitError`, `ServerError`

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 PostCo
+
+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,112 @@
+# TorqueAPI
+
+Ruby client for the [Torque WMS](https://torque.eu/) (Warehouse Management System) API.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "torque_api", git: "https://github.com/PostCo/torque_api", branch: "main"
+```
+
+## Usage
+
+### Initialize a client
+
+```ruby
+client = TorqueAPI::Client.new(
+  api_key: "your_api_key",
+  client_defaults: {
+    "CLIENT_ID" => "AM",
+    "CLIENT_GROUP" => "AMVIS",
+    "SITE_ID" => "WO6",
+    "CONFIG_ID" => "P1",
+    "OWNER_ID" => "TORQUE",
+    "PALLET_CONFIG" => "MD"
+  },
+  sandbox: true  # Use test environment
+)
+```
+
+### Create a Pre Advice
+
+```ruby
+payload = [
+  {
+    "Record_Type" => "PAH",
+    "Pre_Advice_Id" => "12345",
+    "Status" => "Released",
+    "PreAdviceLines" => [
+      {
+        "Record_Type" => "PAL",
+        "Pre_Advice_Id" => "12345",
+        "Sku_Id" => "SKU-001",
+        "Qty_Due" => 1,
+        "Line_Id" => 1
+      }
+    ]
+  }
+]
+
+response = client.pre_advice.create(payload)
+```
+
+### Poll Return RMA items
+
+```ruby
+items = client.return_rma.list
+# Returns an array of TorqueAPI::Objects::ReturnRma
+
+items.each do |item|
+  puts item.orderid          # snake_case accessors
+  puts item.sku_id
+  puts item.sampling_type
+  puts item.raw              # Access original (frozen) response data
+end
+```
+
+### Error handling
+
+```ruby
+begin
+  client.pre_advice.create(payload)
+rescue TorqueAPI::AuthenticationError => e
+  # 401/403 responses
+  puts e.message
+  puts e.status_code
+  puts e.response  # Full Faraday response
+rescue TorqueAPI::ValidationError => e
+  # 400 responses
+rescue TorqueAPI::NotFoundError => e
+  # 404 responses
+rescue TorqueAPI::ServerError => e
+  # 500-599 responses
+rescue TorqueAPI::APIError => e
+  # All other error responses
+end
+```
+
+### Sandbox mode
+
+Toggle between test and live Torque environments:
+
+```ruby
+# Test: https://wms-api.torque.eu/torqueapitest/api/v1
+client = TorqueAPI::Client.new(api_key: key, sandbox: true)
+
+# Live: https://wms-api.torque.eu/torqueapi/api/v1
+client = TorqueAPI::Client.new(api_key: key, sandbox: false)
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec        # Run tests
+bundle exec standardrb   # Run linter
+```
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt).

data/lib/torque_api/client.rb

@@ -0,0 +1,43 @@
+require "faraday"
+
+module TorqueAPI
+  class Client
+    LIVE_BASE_URL = "https://wms-api.torque.eu/torqueapi/api/v1/"
+    TEST_BASE_URL = "https://wms-api.torque.eu/torqueapitest/api/v1/"
+
+    attr_reader :api_key, :client_defaults, :adapter
+
+    def initialize(api_key:, client_defaults: {}, sandbox: false, adapter: Faraday.default_adapter)
+      @api_key = api_key
+      @client_defaults = client_defaults
+      @sandbox = sandbox
+      @adapter = adapter
+    end
+
+    def pre_advice
+      @pre_advice ||= PreAdviceResource.new(self)
+    end
+
+    def return_rma
+      @return_rma ||= ReturnRmaResource.new(self)
+    end
+
+    def connection
+      @connection ||= Faraday.new do |conn|
+        conn.url_prefix = sandbox? ? TEST_BASE_URL : LIVE_BASE_URL
+        conn.headers["Authorization"] = "Basic #{api_key}"
+        conn.headers["Accept"] = "application/json"
+        client_defaults.each { |key, value| conn.headers[key.to_s] = value.to_s }
+        conn.request :json
+        conn.response :json, content_type: "application/json"
+        conn.adapter adapter
+      end
+    end
+
+    private
+
+    def sandbox?
+      @sandbox
+    end
+  end
+end

data/lib/torque_api/errors.rb

@@ -0,0 +1,18 @@
+module TorqueAPI
+  class Error < StandardError
+    attr_reader :response, :status_code
+
+    def initialize(message = nil, response: nil, status_code: nil)
+      super(message)
+      @response = response
+      @status_code = status_code
+    end
+  end
+
+  class APIError < Error; end
+  class AuthenticationError < Error; end
+  class ValidationError < Error; end
+  class NotFoundError < Error; end
+  class RateLimitError < Error; end
+  class ServerError < Error; end
+end

data/lib/torque_api/object.rb

@@ -0,0 +1,60 @@
+require "ostruct"
+require "active_support/core_ext/string/inflections"
+
+module TorqueAPI
+  class Base < OpenStruct
+    attr_reader :original_response
+
+    def initialize(attributes)
+      @original_response = deep_freeze(attributes)
+      super(to_ostruct(attributes))
+    end
+
+    def to_hash
+      ostruct_to_hash(self)
+    end
+
+    def raw
+      @original_response
+    end
+
+    private
+
+    def to_ostruct(obj)
+      case obj
+      when Hash
+        OpenStruct.new(
+          obj.transform_keys { |key| key.to_s.underscore }
+            .transform_values { |val| to_ostruct(val) }
+        )
+      when Array
+        obj.map { |o| to_ostruct(o) }
+      else
+        obj
+      end
+    end
+
+    def deep_freeze(obj)
+      case obj
+      when Hash then obj.transform_values { |v| deep_freeze(v) }.freeze
+      when Array then obj.map { |i| deep_freeze(i) }.freeze
+      else obj.respond_to?(:freeze) ? obj.freeze : obj
+      end
+    end
+
+    def ostruct_to_hash(object)
+      case object
+      when OpenStruct
+        object.each_pair.to_h
+          .transform_keys(&:to_s)
+          .transform_values { |v| ostruct_to_hash(v) }
+      when Array then object.map { |i| ostruct_to_hash(i) }
+      when Hash
+        object.transform_keys(&:to_s)
+          .transform_values { |v| ostruct_to_hash(v) }
+      else
+        object
+      end
+    end
+  end
+end

data/lib/torque_api/objects/return_rma.rb

@@ -0,0 +1,5 @@
+module TorqueAPI
+  module Objects
+    class ReturnRma < Base; end
+  end
+end

data/lib/torque_api/resource.rb

@@ -0,0 +1,50 @@
+module TorqueAPI
+  class Resource
+    attr_reader :client
+
+    def initialize(client)
+      @client = client
+    end
+
+    private
+
+    def get_request(url, params: {}, headers: {})
+      handle_response client.connection.get(url, params, headers)
+    rescue Faraday::Error => e
+      raise APIError, "Network error: #{e.message}"
+    end
+
+    def post_request(url, body:, headers: {})
+      handle_response client.connection.post(url, body, headers)
+    rescue Faraday::Error => e
+      raise APIError, "Network error: #{e.message}"
+    end
+
+    def handle_response(response)
+      return response.body if response.status.between?(200, 299)
+
+      error_class, prefix = error_mapping(response.status)
+      message = "#{prefix} (HTTP #{response.status}): #{extract_error_message(response.body)}"
+      raise error_class.new(message, response: response, status_code: response.status)
+    end
+
+    def error_mapping(status)
+      case status
+      when 400 then [ValidationError, "Bad request"]
+      when 401, 403 then [AuthenticationError, "Authentication failed"]
+      when 404 then [NotFoundError, "Resource not found"]
+      when 429 then [RateLimitError, "Rate limited"]
+      when 500..599 then [ServerError, "Server error"]
+      else [APIError, "API error"]
+      end
+    end
+
+    def extract_error_message(body)
+      case body
+      when Hash then body["message"] || body["error"] || body.to_s
+      when String then body
+      else body.to_s
+      end
+    end
+  end
+end

data/lib/torque_api/resources/pre_advice_resource.rb

@@ -0,0 +1,7 @@
+module TorqueAPI
+  class PreAdviceResource < Resource
+    def create(payload)
+      post_request("preAdvice", body: payload)
+    end
+  end
+end

data/lib/torque_api/resources/return_rma_resource.rb

@@ -0,0 +1,8 @@
+module TorqueAPI
+  class ReturnRmaResource < Resource
+    def list
+      data = get_request("returnRma")
+      Array(data).map { |item| Objects::ReturnRma.new(item) }
+    end
+  end
+end

data/lib/torque_api/version.rb

@@ -0,0 +1,3 @@
+module TorqueAPI
+  VERSION = "0.1.0"
+end

data/lib/torque_api.rb

@@ -0,0 +1,20 @@
+require_relative "torque_api/version"
+
+module TorqueAPI
+  autoload :Client, "torque_api/client"
+  autoload :Base, "torque_api/object"
+  autoload :Resource, "torque_api/resource"
+  autoload :Error, "torque_api/errors"
+  autoload :APIError, "torque_api/errors"
+  autoload :AuthenticationError, "torque_api/errors"
+  autoload :ValidationError, "torque_api/errors"
+  autoload :NotFoundError, "torque_api/errors"
+  autoload :RateLimitError, "torque_api/errors"
+  autoload :ServerError, "torque_api/errors"
+  autoload :PreAdviceResource, "torque_api/resources/pre_advice_resource"
+  autoload :ReturnRmaResource, "torque_api/resources/return_rma_resource"
+
+  module Objects
+    autoload :ReturnRma, "torque_api/objects/return_rma"
+  end
+end

metadata

@@ -0,0 +1,143 @@
+--- !ruby/object:Gem::Specification
+name: torque_api
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- PostCo
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-net_http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A Ruby wrapper for the Torque Warehouse Management System API, supporting
+  Pre Advice creation and Return RMA polling.
+email:
+- dev@postco.co
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/torque_api.rb
+- lib/torque_api/client.rb
+- lib/torque_api/errors.rb
+- lib/torque_api/object.rb
+- lib/torque_api/objects/return_rma.rb
+- lib/torque_api/resource.rb
+- lib/torque_api/resources/pre_advice_resource.rb
+- lib/torque_api/resources/return_rma_resource.rb
+- lib/torque_api/version.rb
+homepage: https://github.com/PostCo/torque_api
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/PostCo/torque_api
+  source_code_uri: https://github.com/PostCo/torque_api
+  changelog_uri: https://github.com/PostCo/torque_api/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Ruby client for the Torque WMS API
+test_files: []