ups 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8bbb686432266ab1abecf098744a453d0c1747eb51a40629335c6f7ce083475b
+  data.tar.gz: fbe3f140f3c29831f21cc340fe272916d26efc9365183f01cdd6dceb8c06ea58
+SHA512:
+  metadata.gz: 791b16e26b54f1e9f0a02353d73d0a4b84c89f459461334d20292341e4ba707ab569a249e617cdc5eaa69f99964177b358ea2f13bd58295998f5627dec871292
+  data.tar.gz: 8483e06fa271c7a514b0d073a9763011f960b7df38d08843ff9d2760dc5fa457b9d5286b429718e39a082ca0002f232a0f63aa72ee0fbbadb7ca847a55c00460

data/README.md

@@ -0,0 +1,107 @@
+# UPS Shipping Ruby Gem
+
+A Ruby wrapper for the UPS Shipping API that allows you to get shipping rates and create shipping labels.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'ups'
+```
+
+## Configuration
+
+```ruby
+Ups.configure do |config|
+  config.client_id = Rails.application.credentials.ups.client_id
+  config.client_secret = Rails.application.credentials.ups.client_secret
+  config.account_number = Rails.application.credentials.ups.account
+  config.sandbox = false
+end
+```
+
+## Usage
+
+### Getting Shipping Rates
+
+```ruby
+# Create addresses
+shipper = Ups::Address.new(
+  company_name: "ACME Corp",
+  address_line_1: "123 Main St",
+  city: "Atlanta",
+  state: "GA",
+  postal_code: "30309",
+  country_code: "US",
+  phone: "1234567890"
+)
+
+ship_to = Ups::Address.new(
+  name: "John Doe",
+  address_line_1: "456 Oak Ave",
+  city: "New York",
+  state: "NY",
+  postal_code: "10001",
+  country_code: "US"
+)
+
+# Create package
+package = Ups:Package.new(
+  length: 10,
+  width: 8,
+  height: 6,
+  weight: 5
+)
+
+# Create rate request
+rate_request = Ups::RateRequest.new(
+  shipper: shipper,
+  ship_to: ship_to,
+  ship_from: shipper,
+  service_code: "03" # UPS Ground
+)
+rate_request.add_package(package)
+
+# Get rates
+rating_service = Ups::Rating.new(Ups.client)
+rates = rating_service.get_rates(rate_request)
+
+rates.each do |rate|
+  puts "#{rate[:service_name]}: $#{rate[:total_cost]} #{rate[:currency]}"
+end
+```
+
+### Creating Shipping Labels
+
+```ruby
+# Create ship request (using same addresses and packages from above)
+ship_request = Ups::ShipRequest.new(
+  shipper: shipper,
+  ship_to: ship_to,
+  ship_from: shipper,
+  service_code: "03",
+  description: "Test shipment"
+)
+ship_request.add_package(package)
+
+# Create shipment
+shipping_service = Ups::Shipping.new(Ups.client)
+result = shipping_service.create_shipment(ship_request)
+
+puts "Tracking Number: #{result[:tracking_number]}"
+puts "Total Cost: $#{result[:total_cost]} #{result[:currency]}"
+puts "Label URL: #{result[:label_url]}"
+```
+
+## Service Codes
+
+- 01: UPS Next Day Air
+- 02: UPS 2nd Day Air
+- 03: UPS Ground
+- 07: UPS Worldwide Express
+- 08: UPS Worldwide Expedited
+- 11: UPS Standard
+- 12: UPS 3 Day Select
+- 13: UPS Next Day Air Saver
+- 14: UPS Next Day Air Early AM

data/lib/ups/client.rb

@@ -0,0 +1,77 @@
+module Ups
+  class Client
+    include HTTParty
+
+    attr_reader :config, :access_token
+
+    def initialize(config)
+      @config = config
+      @access_token = nil
+      authenticate
+    end
+
+    def get(endpoint, options = {})
+      request(:get, endpoint, options)
+    end
+
+    def post(endpoint, options = {})
+      request(:post, endpoint, options)
+    end
+
+    private
+
+    def auth_headers
+      {
+        'Authorization' => "Basic #{auth_string}",
+        'X-Merchant-Id' => @config.client_id,
+        'Accept' => 'application/json',
+        'Content-Type' => 'application/x-www-form-urlencoded'
+      }
+    end
+
+    def auth_string
+      @auth_string ||= Base64.strict_encode64("#{@config.client_id}:#{@config.client_secret}")
+    end
+
+    def authenticate
+      response = HTTParty.post(@config.oauth_url, { headers: auth_headers, body: 'grant_type=client_credentials' })
+
+      if response.success?
+        @access_token = response.parsed_response['access_token']
+      else
+        raise AuthenticationError, "Failed to authenticate: #{response.body}"
+      end
+    end
+
+    def request_headers
+      {
+        'Authorization' => "Bearer #{@access_token}",
+        'Content-Type' => 'application/json'
+      }
+    end
+
+    def request(method, endpoint, opts = {})
+      url = "#{@config.base_url}#{endpoint}"
+      response = HTTParty.send(method, url, { headers: request_headers.merge(opts[:headers] || {}), body: opts[:body]&.to_json })
+      handle_response(response)
+    end
+
+    def handle_response(response)
+      case response.code
+      when 200, 201
+        response.parsed_response
+      when 401
+        authenticate
+        raise AuthenticationError, "Authentication failed"
+      when 400
+        raise BadRequestError, response.body
+      when 404
+        raise NotFoundError, response.body
+      when 500
+        raise ServerError, response.body
+      else
+        raise APIError, "HTTP #{response.code}: #{response.body}"
+      end
+    end
+  end
+end

data/lib/ups/configuration.rb

@@ -0,0 +1,17 @@
+module Ups
+  class Configuration
+    attr_accessor :client_id, :client_secret, :account_number, :sandbox
+
+    def initialize
+      @sandbox = true
+    end
+
+    def base_url
+      @sandbox ? "https://wwwcie.ups.com" : "https://onlinetools.ups.com"
+    end
+
+    def oauth_url
+      @sandbox ? "https://wwwcie.ups.com/security/v1/oauth/token" : "https://onlinetools.ups.com/security/v1/oauth/token"
+    end
+  end
+end

data/lib/ups/errors.rb

@@ -0,0 +1,10 @@
+module Ups
+  class Error < StandardError; end
+  class AuthenticationError < Error; end
+  class ValidationError < Error; end
+  class BadRequestError < Error; end
+  class NotFoundError < Error; end
+  class ServerError < Error; end
+  class APIError < Error; end
+end
+

data/lib/ups/models/address.rb

@@ -0,0 +1,20 @@
+module Ups
+  class Address
+    attr_accessor :name, :company_name, :attention_name, :address_line_1, :address_line_2, :city, :state, :postal_code, :country_code, :phone, :tax_id
+
+    def initialize(attrs = {})
+      attrs.map{|k, v| send("#{k}=", v) if respond_to?("#{k}=") }
+    end
+
+    def validate!
+      errors = []
+      errors << "Address line 1 is required" if address_line_1.nil? || address_line_1.strip.empty?
+      errors << "City is required" if city.nil? || city.strip.empty?
+      errors << "State is required" if state.nil? || state.strip.empty?
+      errors << "Postal code is required" if postal_code.nil? || postal_code.strip.empty?
+      errors << "Country code is required" if country_code.nil? || country_code.strip.empty?
+
+      raise ValidationError, errors.join(", ") unless errors.empty?
+    end
+  end
+end

data/lib/ups/models/package.rb

@@ -0,0 +1,23 @@
+module Ups
+  class Package
+    attr_accessor :description, :packaging_type, :length, :width, :height, :weight, :dimension_unit, :weight_unit, :value
+
+    def initialize(attrs = {})
+      attrs.map{|k,v| send("#{k}=", v) if respond_to?("#{k}=") }
+
+      @dimension_unit ||= 'IN'
+      @weight_unit ||= 'LBS'
+      @packaging_type ||= '02' # Customer Supplied Package
+    end
+
+    def validate!
+      errors = []
+      errors << "Length is required" if length.nil? || length <= 0
+      errors << "Width is required" if width.nil? || width <= 0
+      errors << "Height is required" if height.nil? || height <= 0
+      errors << "Weight is required" if weight.nil? || weight <= 0
+
+      raise ValidationError, errors.join(", ") unless errors.empty?
+    end
+  end
+end

data/lib/ups/models/rate_request.rb

@@ -0,0 +1,33 @@
+module Ups
+  class RateRequest
+    attr_accessor :shipper, :ship_to, :ship_from, :packages, :service_code, :reference, :dcis_type
+
+    def initialize(attrs = {})
+      attrs.map{|k, v| send("#{k}=", v) if respond_to?("#{k}=") }
+      @packages = []
+    end
+
+    def add_package(package)
+      @packages << package
+    end
+
+    def validate!
+      errors = []
+      errors << "Shipper is required" if shipper.nil?
+      errors << "Ship to address is required" if ship_to.nil?
+      errors << "Ship from address is required" if ship_from.nil?
+      errors << "At least one package is required" if packages.empty?
+
+      begin
+        shipper&.validate!
+        ship_to&.validate!
+        ship_from&.validate!
+        packages.each(&:validate!)
+      rescue ValidationError => e
+        errors << e.message
+      end
+
+      raise ValidationError, errors.join(", ") unless errors.empty?
+    end
+  end
+end

data/lib/ups/models/ship_request.rb

@@ -0,0 +1,34 @@
+module Ups
+  class ShipRequest
+    attr_accessor :shipper, :ship_to, :ship_from, :packages, :service_code, :reference, :description, :label_format
+
+    def initialize(attrs = {})
+      attrs.map{|k, v| send("#{k}=", v) if respond_to?("#{k}=") }
+      @packages = []
+      @label_format ||= "GIF"
+    end
+
+    def add_package(package)
+      @packages << package
+    end
+
+    def validate!
+      errors = []
+      errors << "Shipper is required" if shipper.nil?
+      errors << "Ship to address is required" if ship_to.nil?
+      errors << "Ship from address is required" if ship_from.nil?
+      errors << "At least one package is required" if packages.empty?
+
+      begin
+        shipper&.validate!
+        ship_to&.validate!
+        ship_from&.validate!
+        packages.each(&:validate!)
+      rescue ValidationError => e
+        errors << e.message
+      end
+
+      raise ValidationError, errors.join(", ") unless errors.empty?
+    end
+  end
+end

data/lib/ups/rating.rb

@@ -0,0 +1,146 @@
+module Ups
+  class Rating
+    attr_reader :client, :account_number
+
+    def initialize(client, account_number: nil)
+      @client = client
+      @account_number = account_number || client.config.account_number
+    end
+
+    def get_rates(rate_request)
+      endpoint = "/api/rating/v2409/Shop"
+      payload = build_rate_payload(rate_request)
+      response = client.post(endpoint, body: payload)
+      parse_rate_response(response)
+    end
+
+    private
+
+    def build_rate_payload(rate_request)
+      {
+        RateRequest: {
+          Request: {
+            RequestOption: "Rate",
+            TransactionReference: {
+              CustomerContext: rate_request.reference || "Rating Request"
+            }
+          },
+          Shipment: {
+            ShipmentDate: Date.today.to_s,
+            Shipper: {
+              Name: rate_request.shipper.company_name,
+              ShipperNumber: client.config.account_number,
+              Address: address_hash(rate_request.shipper)
+            },
+            ShipTo: {
+              Name: rate_request.ship_to.company_name || rate_request.ship_to.name,
+              Address: address_hash(rate_request.ship_to)
+            },
+            ShipFrom: {
+              Name: rate_request.ship_from.company_name || rate_request.ship_from.name,
+              Address: address_hash(rate_request.ship_from)
+            },
+            PaymentInformation: {
+              ShipmentCharge: {
+                Type: "01",
+                BillShipper: {
+                  AccountNumber: account_number
+                }
+              }
+            },
+#            ShipmentServiceOptions: {
+#              DeliveryConfirmation: {
+#                DCISType: rate_request.dcis_type || 0 # "2" = Signature Required
+#              }
+#            },
+            Package: rate_request.packages.map { |pkg| package_hash(pkg) },
+            Service: {
+              Code: rate_request.service_code || "03"
+            }
+          }
+        }
+      }
+    end
+
+    def address_hash(address)
+      {
+        AddressLine: [address.address_line_1, address.address_line_2].compact,
+        City: address.city,
+        StateProvinceCode: address.state,
+        PostalCode: address.postal_code,
+        CountryCode: address.country_code
+      }
+    end
+
+    def package_hash(package)
+      {
+        PackagingType: {
+          Code: package.packaging_type || "02"
+        },
+        Dimensions: {
+          UnitOfMeasurement: {
+            Code: package.dimension_unit || "IN"
+          },
+          Length: package.length.to_s,
+          Width: package.width.to_s,
+          Height: package.height.to_s
+        },
+        PackageWeight: {
+          UnitOfMeasurement: {
+            Code: package.weight_unit || "LBS"
+          },
+          Weight: package.weight.to_s
+        },
+        PackageServiceOptions: {
+          DeclaredValue: {
+            CurrencyCode: "USD",
+            MonetaryValue: package.value
+          }
+        }
+      }
+    end
+
+    def parse_rate_response(response)
+      rates = []
+
+      if response['RateResponse'] && response['RateResponse']['RatedShipment']
+        rated_shipments = response['RateResponse']['RatedShipment']
+        rated_shipments = [rated_shipments] unless rated_shipments.is_a?(Array)
+
+        rated_shipments.each do |shipment|
+          rates << {
+            service_code: shipment['Service']['Code'],
+            service_name: get_service_name(shipment['Service']['Code']),
+            total: shipment['TotalCharges']['MonetaryValue'].to_f,
+            currency: shipment['TotalCharges']['CurrencyCode'],
+            transit_time: shipment['GuaranteedDelivery'] ? shipment['GuaranteedDelivery']['BusinessDaysInTransit'] : nil
+          }
+        end
+      end
+
+      rates
+    end
+
+    def get_service_name(code)
+      service_names[code] || "Unknown Service (#{code})"
+    end
+
+    def service_names
+      @service_names ||= {
+        '01' => 'UPS Next Day Air',
+        '02' => 'UPS 2nd Day Air',
+        '03' => 'UPS Ground',
+        '07' => 'UPS Worldwide Express',
+        '08' => 'UPS Worldwide Expedited',
+        '11' => 'UPS Standard',
+        '12' => 'UPS 3 Day Select',
+        '13' => 'UPS Next Day Air Saver',
+        '14' => 'UPS Next Day Air Early AM',
+        '54' => 'UPS Worldwide Express Plus',
+        '59' => 'UPS 2nd Day Air AM',
+        '65' => 'UPS Saver'
+      }
+    end
+
+  end
+end

data/lib/ups/shipping.rb

@@ -0,0 +1,131 @@
+module Ups
+  class Shipping
+    attr_reader :client, :account_number
+
+    def initialize(client, account_number: nil)
+      @client = client
+      @account_number = account_number || client.config.account_number
+    end
+
+    def create_shipment(ship_request)
+      endpoint = "/api/shipments/v2409/ship"
+      payload = build_ship_payload(ship_request)
+      response = client.post(endpoint, body: payload)
+      parse_ship_response(response)
+    end
+
+    private
+
+    def build_ship_payload(ship_request)
+      {
+        ShipmentRequest: {
+          Request: {
+            RequestOption: "nonvalidate",
+            TransactionReference: {
+              CustomerContext: ship_request.reference || "Shipping Request"
+            }
+          },
+          Shipment: {
+            ShipmentDate: Date.today.to_s,
+            Description: ship_request.description || "Package",
+            Shipper: {
+              Name: ship_request.shipper.company_name,
+              AttentionName: ship_request.shipper.attention_name,
+              TaxIdentificationNumber: ship_request.shipper.tax_id,
+              Phone: {
+                Number: ship_request.shipper.phone
+              },
+              ShipperNumber: client.config.account_number,
+              Address: address_hash(ship_request.shipper)
+            },
+            ShipTo: {
+              Name: ship_request.ship_to.company_name || ship_request.ship_to.name,
+              AttentionName: ship_request.ship_to.attention_name,
+              Phone: {
+                Number: ship_request.ship_to.phone
+              },
+              Address: address_hash(ship_request.ship_to)
+            },
+            ShipFrom: {
+              Name: ship_request.ship_from.company_name || ship_request.ship_from.name,
+              AttentionName: ship_request.ship_from.attention_name,
+              Phone: {
+                Number: ship_request.ship_from.phone
+              },
+              Address: address_hash(ship_request.ship_from)
+            },
+            PaymentInformation: {
+              ShipmentCharge: {
+                Type: "01",
+                BillShipper: {
+                  AccountNumber: account_number
+                }
+              }
+            },
+            Service: {
+              Code: ship_request.service_code || "02",
+              Description: "Service Code"
+            },
+            Package: ship_request.packages.map { |pkg| package_hash(pkg) }
+          },
+          LabelSpecification: {
+            LabelImageFormat: {
+              Code: ship_request.label_format || "GIF"
+            },
+            HTTPUserAgent: "UPS Rate Fetch"
+          }
+        }
+      }
+    end
+
+    def address_hash(address)
+      {
+        AddressLine: [address.address_line_1, address.address_line_2].compact,
+        City: address.city,
+        StateProvinceCode: address.state,
+        PostalCode: address.postal_code,
+        CountryCode: address.country_code
+      }
+    end
+
+    def package_hash(package)
+      {
+        Description: package.description || "Package",
+        Packaging: {
+          Code: package.packaging_type || "02"
+        },
+        Dimensions: {
+          UnitOfMeasurement: {
+            Code: package.dimension_unit || "IN"
+          },
+          Length: package.length.to_s,
+          Width: package.width.to_s,
+          Height: package.height.to_s
+        },
+        PackageWeight: {
+          UnitOfMeasurement: {
+            Code: package.weight_unit || "LBS"
+          },
+          Weight: package.weight.to_s
+        }
+      }
+    end
+
+    def parse_ship_response(response)
+      if response['ShipmentResponse'] && response['ShipmentResponse']['ShipmentResults']
+        results = response['ShipmentResponse']['ShipmentResults']
+        {
+          tracking_number: results['ShipmentIdentificationNumber'],
+          label: results['PackageResults'][0]['ShippingLabel']['GraphicImage'],
+          extension: results['PackageResults'][0]['ShippingLabel']['ImageFormat']['Code'],
+          cost: results['ShipmentCharges']['TotalCharges']['MonetaryValue'].to_f,
+          currency: results['ShipmentCharges']['TotalCharges']['CurrencyCode'],
+          data: response.as_json(except: ["GraphicImage", "HTMLImage"]),
+          alerts: response['ShipmentResponse']['Response']['Alert']&.map{|s| s['Description'] }
+        }
+      else
+        raise APIError, "Invalid shipment response: #{response}"
+      end
+    end
+  end
+end

data/lib/ups/version.rb

@@ -0,0 +1,4 @@
+module Ups
+  VERSION = "0.0.1"
+end
+

data/lib/ups.rb

@@ -0,0 +1,30 @@
+require 'httparty'
+require 'json'
+require 'base64'
+
+require_relative 'ups/version'
+require_relative 'ups/configuration'
+require_relative 'ups/client'
+require_relative 'ups/rating'
+require_relative 'ups/shipping'
+require_relative 'ups/models/address'
+require_relative 'ups/models/package'
+require_relative 'ups/models/rate_request'
+require_relative 'ups/models/ship_request'
+require_relative 'ups/errors'
+
+module Ups
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def client
+      @client ||= Client.new(configuration)
+    end
+  end
+end

metadata

@@ -0,0 +1,126 @@
+--- !ruby/object:Gem::Specification
+name: ups
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- JD Warren
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-06-13 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: json
+  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: 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: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+description: A Ruby gem that provides easy access to UPS shipping rates and label
+  creation using the new OAuth authentication
+email:
+- johndavid400@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/ups.rb
+- lib/ups/client.rb
+- lib/ups/configuration.rb
+- lib/ups/errors.rb
+- lib/ups/models/address.rb
+- lib/ups/models/package.rb
+- lib/ups/models/rate_request.rb
+- lib/ups/models/ship_request.rb
+- lib/ups/rating.rb
+- lib/ups/shipping.rb
+- lib/ups/version.rb
+homepage: https://github.com/johndavid400/ups
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Ruby wrapper for UPS Shipping API
+test_files: []