jumingo 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6233763808ce1fed9b129928f7db7e3aed8d26415efd276ec8dcf3ffbe914abc
+  data.tar.gz: 240cb46f9433f6761d50f3af48ffe80761207d97daba215e8d0e90beba1e0695
+SHA512:
+  metadata.gz: efe908457dac34c1b8fe1052b19bec09ac888fd98f4b0b6e3aaabdf17e14844cedecbe9387020485f77892f2bfeb047ae44ec6e177340f9c70a9b74e0eedcde9
+  data.tar.gz: f3a79cf35dac453a21a693985787ddeb6b7b871788f06cc58dc221cea141daf2cbe600e61c370608f0816c1932407513671cc4330991eba8b4f810a090f8142e

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-02-03
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 florian2
+
+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,110 @@
+# Jumingo
+
+Ruby client for the Jumingo shipping API.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add jumingo
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install jumingo
+```
+
+## Usage
+
+```ruby
+require "jumingo"
+
+client = Jumingo::Client.new(
+  Jumingo::Configuration.new.tap do |config|
+    config.api_key = "your-api-key"
+    config.base_url = "https://api.jumingo.com"
+    config.timeout = 30
+    config.open_timeout = 10
+  end
+)
+```
+
+### Jumingo::Client API Reference
+
+Carrier:
+- `POST /v1/carrier/access-points-search` → `carrier_access_points_search(payload)`
+
+Cart:
+- `POST /v1/cart/total` → `cart_total(payload)`
+
+Connections:
+- `GET /v1/connections` → `list_connections(params: {})`
+- `GET /v1/connections/{uuid}` → `get_connection(uuid)`
+- `POST /v1/connections` → `create_connection(payload)`
+
+Orders:
+- `GET /v1/orders` → `list_orders(params: {})`
+- `GET /v1/orders/{id}` → `get_order(id)`
+- `GET /v1/orders/{id}/documents` → `get_order_documents(id)`
+- `POST /v1/orders` → `create_order(payload)`
+
+Shipments:
+- `GET /v1/shipments` → `list_shipments(params: {})`
+- `GET /v1/shipments/{shipment_id}` → `get_shipment(shipment_id)`
+- `POST /v1/shipments` → `create_shipment(payload)`
+- `PUT /v1/shipments/{shipment_id}` → `update_shipment(shipment_id, payload)`
+- `PATCH /v1/shipments/{shipment_id}` → `patch_shipment(shipment_id, payload)`
+- `DELETE /v1/shipments/{shipment_id}` → `delete_shipment(shipment_id)`
+- `POST /v1/shipments/cheapest` → `cheapest_shipment_rate(payload, params: {})`
+- `POST /v1/shipments/{uuid}/file/upload/{type}` → `upload_shipment_file(uuid, type, file)`
+- `DELETE /v1/shipments/{uuid}/file/upload/{type}` → `delete_shipment_file(uuid, type)`
+
+Shipment Rates:
+- `POST /v1/shipment-rates` → `create_shipment_rate(payload)`
+
+### Example Calls
+
+```ruby
+client.list_orders(params: { page: 1, itemsPerPage: 20 })
+client.create_shipment({ reference: "ORDER-123" })
+client.upload_shipment_file("s_fbf8e2a57185478194fa264583b5b388", "commercial-invoice", "/path/to/invoice.pdf")
+```
+
+### Pagination Helper
+
+```ruby
+client.each_page("/orders", params: { itemsPerPage: 50 }) do |orders|
+  puts orders.count
+end
+```
+
+### Error Handling
+
+```ruby
+begin
+  client.get_order("missing-id")
+rescue Jumingo::Errors::NotFound => e
+  puts e.status
+  puts e.body
+end
+```
+
+### OpenAPI Source
+
+The OpenAPI definition used to implement this client is stored at `openapi/jumingo.yaml`.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/florian2/jumingo.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/jumingo/client.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/multipart"
+require "json"
+
+module Jumingo
+  class Client
+    BASE_PATH = "/v1"
+
+    def initialize(configuration = Jumingo.configuration)
+      @configuration = configuration
+    end
+
+    def carrier_access_points_search(payload)
+      request_json(:post, "#{BASE_PATH}/carrier/access-points-search", body: payload)
+    end
+
+    def cart_total(payload)
+      request_json(:post, "#{BASE_PATH}/cart/total", body: payload)
+    end
+
+    def list_connections(params: {})
+      request_json(:get, "#{BASE_PATH}/connections", params: params)
+    end
+
+    def get_connection(uuid)
+      request_json(:get, "#{BASE_PATH}/connections/#{uuid}")
+    end
+
+    def create_connection(payload)
+      request_json(:post, "#{BASE_PATH}/connections", body: payload)
+    end
+
+    def list_orders(params: {})
+      request_json(:get, "#{BASE_PATH}/orders", params: params)
+    end
+
+    def get_order(id)
+      request_json(:get, "#{BASE_PATH}/orders/#{id}")
+    end
+
+    def get_order_documents(id)
+      request_json(:get, "#{BASE_PATH}/orders/#{id}/documents")
+    end
+
+    def create_order(payload)
+      request_json(:post, "#{BASE_PATH}/orders", body: payload)
+    end
+
+    def list_shipments(params: {})
+      request_json(:get, "#{BASE_PATH}/shipments", params: params)
+    end
+
+    def get_shipment(shipment_id)
+      request_json(:get, "#{BASE_PATH}/shipments/#{shipment_id}")
+    end
+
+    def create_shipment(payload)
+      request_json(:post, "#{BASE_PATH}/shipments", body: payload)
+    end
+
+    def update_shipment(shipment_id, payload)
+      request_json(:put, "#{BASE_PATH}/shipments/#{shipment_id}", body: payload)
+    end
+
+    def patch_shipment(shipment_id, payload)
+      request_json(:patch, "#{BASE_PATH}/shipments/#{shipment_id}", body: payload)
+    end
+
+    def delete_shipment(shipment_id)
+      request_json(:delete, "#{BASE_PATH}/shipments/#{shipment_id}")
+    end
+
+    def cheapest_shipment_rate(payload, params: {})
+      request_json(:post, "#{BASE_PATH}/shipments/cheapest", params: params, body: payload)
+    end
+
+    def create_shipment_rate(payload)
+      request_json(:post, "#{BASE_PATH}/shipment-rates", body: payload)
+    end
+
+    def upload_shipment_file(uuid, type, file)
+      file_part = file_part_for(file)
+      request_multipart(:post, "#{BASE_PATH}/shipments/#{uuid}/file/upload/#{type}", body: { file: file_part })
+    end
+
+    def delete_shipment_file(uuid, type)
+      request_json(:delete, "#{BASE_PATH}/shipments/#{uuid}/file/upload/#{type}")
+    end
+
+    def each_page(path, params: {}, items_per_page: 50)
+      return enum_for(:each_page, path, params: params, items_per_page: items_per_page) unless block_given?
+
+      page = 1
+      loop do
+        response = request_json(:get, path, params: params.merge(page: page, itemsPerPage: items_per_page))
+        yield response
+        break unless response.is_a?(Array)
+        break if response.length < items_per_page
+
+        page += 1
+      end
+    end
+
+    private
+
+    def request_json(method, path, params: nil, body: nil)
+      response = connection.public_send(method) do |req|
+        apply_headers(req)
+        req.url(path)
+        req.params.update(params) if params
+        req.body = body if body
+      end
+      handle_response(response)
+    end
+
+    def request_multipart(method, path, body:)
+      response = connection(multipart: true).public_send(method) do |req|
+        apply_headers(req)
+        req.url(path)
+        req.body = body
+      end
+      handle_response(response)
+    end
+
+    def apply_headers(request)
+      request.headers["X-AUTH-TOKEN"] = @configuration.api_key if @configuration.api_key
+      request.headers["Accept"] = "application/json"
+    end
+
+    def connection(multipart: false)
+      builder = Faraday.new(url: @configuration.base_url) do |f|
+        f.request :multipart if multipart
+        f.request :json
+        f.response :json, content_type: /\bjson$/
+        f.adapter Faraday.default_adapter
+      end
+      builder.options.timeout = @configuration.timeout
+      builder.options.open_timeout = @configuration.open_timeout
+      builder
+    end
+
+    def file_part_for(file)
+      return file if file.is_a?(Faraday::Multipart::FilePart)
+      return Faraday::Multipart::FilePart.new(file, "application/octet-stream") if file.is_a?(String)
+
+      raise ArgumentError, "file must be a path or Faraday::Multipart::FilePart"
+    end
+
+    def handle_response(response)
+      status = response.status
+      body = response.body
+      headers = response.headers
+
+      return Models.parse(body) if status.between?(200, 299)
+
+      error_class = case status
+                    when 400 then Errors::BadRequest
+                    when 401 then Errors::Unauthorized
+                    when 403 then Errors::Forbidden
+                    when 404 then Errors::NotFound
+                    when 409 then Errors::Conflict
+                    when 422 then Errors::UnprocessableEntity
+                    when 429 then Errors::RateLimited
+                    when 500..599 then Errors::ServerError
+                    else Error
+                    end
+
+      message = body.is_a?(Hash) ? body["message"] || body["error"] : body.to_s
+      raise error_class.new(message, status: status, body: body, headers: headers)
+    end
+  end
+end

data/lib/jumingo/configuration.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Jumingo
+  class Configuration
+    DEFAULT_BASE_URL = "https://api.jumingo.com"
+    DEFAULT_TIMEOUT = 30
+    DEFAULT_OPEN_TIMEOUT = 10
+    DEFAULT_RETRIES = 0
+
+    attr_accessor :base_url, :api_key, :timeout, :open_timeout, :retries, :logger
+
+    def initialize
+      @base_url = DEFAULT_BASE_URL
+      @api_key = nil
+      @timeout = DEFAULT_TIMEOUT
+      @open_timeout = DEFAULT_OPEN_TIMEOUT
+      @retries = DEFAULT_RETRIES
+      @logger = nil
+    end
+  end
+end

data/lib/jumingo/errors.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Jumingo
+  class Error < StandardError
+    attr_reader :status, :body, :headers
+
+    def initialize(message = nil, status: nil, body: nil, headers: nil)
+      super(message)
+      @status = status
+      @body = body
+      @headers = headers
+    end
+  end
+
+  module Errors
+    class BadRequest < Error; end
+    class Unauthorized < Error; end
+    class Forbidden < Error; end
+    class NotFound < Error; end
+    class Conflict < Error; end
+    class UnprocessableEntity < Error; end
+    class RateLimited < Error; end
+    class ServerError < Error; end
+  end
+end

data/lib/jumingo/models.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Jumingo
+  module Models
+    class Object
+      def initialize(attributes = {})
+        @attributes = attributes.transform_keys { |key| key.to_s }
+      end
+
+      def [](key)
+        @attributes[key.to_s]
+      end
+
+      def to_h
+        @attributes.dup
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        @attributes.key?(name.to_s) || super
+      end
+
+      def method_missing(name, *args, &block)
+        return @attributes[name.to_s] if @attributes.key?(name.to_s)
+
+        super
+      end
+    end
+
+    def self.parse(value)
+      case value
+      when Array
+        value.map { |item| parse(item) }
+      when Hash
+        Object.new(value.transform_values { |v| parse(v) })
+      else
+        value
+      end
+    end
+  end
+end

data/lib/jumingo/version.rb

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

data/lib/jumingo.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "jumingo/version"
+require_relative "jumingo/configuration"
+require_relative "jumingo/errors"
+require_relative "jumingo/models"
+require_relative "jumingo/client"
+
+module Jumingo
+  def self.configure
+    yield(configuration)
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+end