shipengine_ruby 0.0.1

data/lib/shipengine/enums/carriers_names.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module ShipEngine
+  module Enums
+    module CarrierNames
+      ACCESS_WORLDWIDE = "access_worldwide"
+
+      AMAZON_BUY_SHIPPING = "amazon_buy_shipping"
+
+      AMAZON_SHIPPING_UK = "amazon_shipping_uk"
+
+      APC = "apc"
+
+      ASENDIA = "asendia"
+
+      AUSTRALIA_POST = "australia_post"
+
+      CANADA_POST = "canada_post"
+
+      DHL_ECOMMERCE = "dhl_ecommerce"
+
+      DHL_EXPRESS = "dhl_express"
+
+      DHL_EXPRESS_AU = "dhl_express_au"
+
+      DHL_EXPRESS_CA = "dhl_express_ca"
+
+      DHL_EXPRESS_UK = "dhl_express_uk"
+
+      DPD = "dpd"
+
+      ENDICIA = "endicia"
+
+      FEDEX = "fedex"
+
+      FEDEX_UK = "fedex_uk"
+
+      FIRSTMILE = "firstmile"
+
+      IMEX = "imex"
+
+      NEWGISTICS = "newgistics"
+
+      ONTRAC = "ontrac"
+
+      PUROLATOR_CANADA = "purolator_canada"
+
+      ROYAL_MAIL = "royal_mail"
+
+      RR_DONNELLEY = "rr_donnelley"
+
+      SEKO = "seko"
+
+      SENDLE = "sendle"
+
+      STAMPS_COM = "stamps_com"
+
+      UPS = "ups"
+
+      ALL = [
+        ACCESS_WORLDWIDE,
+        AMAZON_BUY_SHIPPING,
+        AMAZON_SHIPPING_UK,
+        APC,
+        ASENDIA,
+        AUSTRALIA_POST,
+        CANADA_POST,
+        DHL_ECOMMERCE,
+        DHL_EXPRESS,
+        DHL_EXPRESS_AU,
+        DHL_EXPRESS_CA,
+        DHL_EXPRESS_UK,
+        DPD,
+        ENDICIA,
+        FEDEX,
+        FEDEX_UK,
+        FIRSTMILE,
+        IMEX,
+        NEWGISTICS,
+        ONTRAC,
+        PUROLATOR_CANADA,
+        ROYAL_MAIL,
+        RR_DONNELLEY,
+        SEKO,
+        SENDLE,
+        STAMPS_COM,
+        UPS,
+      ].freeze
+    end
+  end
+end

data/lib/shipengine/enums/label_status.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ShipEngine
+  module Enums
+    module LabelStatus
+      PROCESSING = "processing"
+
+      COMPLETED = "completed"
+
+      ERROR = "error"
+
+      VOIDED = "voided"
+
+      ALL = [
+        PROCESSING,
+        COMPLETED,
+        ERROR,
+        VOIDED,
+      ].freeze
+    end
+  end
+end

data/lib/shipengine/enums/message_types.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module ShipEngine
+  module Enums
+    module MessageStatus
+      #
+      # Info messages will describe the partial or complete level of accuracy available for the Address Validation.
+      #
+      INFO = "info"
+
+      #
+      # Warning messages will usually consist of significant changes* or
+      # additions to the data that was provided in the request
+      #
+      WARNING = "warning"
+
+      #
+      # Error messages will usually describe a portion of the data sent in the request,
+      # that could not be validated with any measure of accuracy
+      #
+      ERROR = "error"
+
+      ALL = [
+        INFO,
+        WARNING,
+        ERROR,
+      ].freeze
+    end
+  end
+end

data/lib/shipengine/enums/validate_address_types.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module ShipEngine
+  module Enums
+    module ValidateAddress
+      NO_VALIDATION = "no_validation"
+
+      VALIDATE_ONLY = "validate_only"
+
+      VALIDATE_AND_CLEAN = "validate_and_clean"
+
+      ALL = [
+        NO_VALIDATION,
+        VALIDATE_ONLY,
+        VALIDATE_AND_CLEAN,
+      ].freeze
+    end
+  end
+end

data/lib/shipengine/enums/webhooks_types.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module ShipEngine
+  module Enums
+    module WebhooksTypes
+      ##
+      # Batch completed
+      # #/
+      API_BATCH = "batch"
+
+      ##
+      # Shipment rate updated
+      # #/
+      API_RATE = "rate"
+
+      ##
+      # Any tracking event
+      # #/
+      API_TRACK = "track"
+
+      ##
+      # Carrier connected
+      # #/
+      API_CARRIER_CONNECTED = "carrier_connected"
+
+      ##
+      # Sales Orders imported (Beta)
+      # #/
+      API_SALES_ORDERS_IMPORTED = "sales_orders_imported"
+
+      ##
+      # Order Source refresh complete (Beta)
+      # #/
+      API_ORDER_SOURCE_REFRESH_COMPLETE = "order_source_refresh_complete"
+
+      ##
+      # A requested report is ready
+      # #/
+      API_REPORT_COMPLETE = "report_complete"
+
+      ALL = [
+        API_BATCH,
+        API_RATE,
+        API_TRACK,
+        API_CARRIER_CONNECTED,
+        API_SALES_ORDERS_IMPORTED,
+        API_ORDER_SOURCE_REFRESH_COMPLETE,
+        API_REPORT_COMPLETE,
+      ].freeze
+    end
+  end
+end

data/lib/shipengine/enums.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "shipengine/enums/address_residential_indicator_types"
+require "shipengine/enums/address_status"
+require "shipengine/enums/batch_status"
+require "shipengine/enums/carriers_names"
+require "shipengine/enums/label_status"
+require "shipengine/enums/message_types"
+require "shipengine/enums/webhooks_types"

data/lib/shipengine/errors/error_code.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+module ShipEngine
+  module Errors
+    ##
+    ##  This class has the ability to return a specific error code.
+    ##
+    ## @see https://www.shipengine.com/docs/errors/codes/#error-code
+    # #/
+    class ErrorCode
+      # @param [Symbol | String] key
+      # @return [String] error type
+      def self.get(key)
+        @codes[key.upcase.to_sym]
+      end
+
+      @codes = {
+        ##
+        #	Only certain carriers support pre-paid balances.
+        # So you can only add funds to those carriers.
+        # If you attempt to add funds to a carrier that doesn't support it, then you'll get this error code.
+        # #/
+        AUTO_FUND_NOT_SUPPORTED: "auto_fund_not_supported",
+
+        ##
+        #	Once a batch has started [processing]/reference/process-batch),
+        # it cannot be modified. Attempting to modify it will cause this error.
+        # #/
+        BATCH_CANNOT_BE_MODIFIED: "batch_cannot_be_modified",
+
+        ##
+        #	You attempted to perform an operation on multiple shipments from different carriers.
+        # Try performing separate operations for each carrier instead.
+        # #/
+        CARRIER_CONFLICT: "carrier_conflict",
+
+        ##
+        #	This error means that you're trying to use a carrier that hasn't been setup yet.
+        # You can setup carriers from your ShipEngine dashboard, or via the API.
+        # #/
+        CARRIER_NOT_CONNECTED: "carrier_not_connected",
+
+        ##
+        #	The operation you are performing isn't supported by the specified carrier.
+        # #/
+        CARRIER_NOT_SUPPORTED: "carrier_not_supported",
+
+        ##
+        #	Some forms of delivery confirmation aren't supported by some carriers.
+        # This error means that the combination of carrier and delivery confirmation are not supported.
+        # #/
+        CONFIRMATION_NOT_SUPPORTED: "confirmation_not_supported",
+
+        ##
+        #	This error means that two or more fields in your API request are mutually exclusive or
+        # contain conflicting values. The error will include a fields array that lists the conflicting fields.
+        # #/
+        FIELD_CONFLICT: "field_conflict",
+
+        ##
+        #	A required field is missing or empty. The field_name property indicates which field is missing.
+        # Note that some fields are conditionally required, based on the values of other fields or
+        # the type of operation being performed.
+        # #/
+        FIELD_VALUE_REQUIRED: "field_value_required",
+
+        ##
+        #	You attempted to perform an operation that you don't have permissions to do.
+        # Check your API key to ensure that you're using the correct one.
+        # Or contact our support team to ensure that your account has the necessary permissions.
+        # #/
+        FORBIDDEN: "forbidden",
+
+        ##
+        #	A few parts of the ShipEngine API allow you to provide your own ID for resources.
+        # These IDs must be unique; otherwise, you'll get this error code.
+        # #/
+        IDENTIFIER_CONFLICT: "identifier_conflict",
+
+        ##
+        #	When updating a resource (such as a [shipment](/reference/update-shipment or warehouse),
+        # the ID in the URL and in the request body must match.
+        # #/
+        IDENTIFIERS_MUST_MATCH: "identifiers_must_match",
+
+        ##
+        #	When creating a return label, you can optionally pair it to an outbound_label_id.
+        # The outbound label must be from the same carrier as the return label.
+        # #/
+        INCOMPATIBLE_PAIRED_LABELS: "incompatible_paired_labels",
+
+        ##
+        #	The mailing address that you provided is invalid.
+        # Try using our address validation API to verify addresses before using them.
+        # #/
+        INVALID_ADDRESS: "invalid_address",
+
+        ##
+        #	You attempted to perform an operation that isn't allowed for your billing plan.
+        # Contact our sales team for assistance.
+        # #/
+        INVALID_BILLING_PLAN: "invalid_billing_plan",
+
+        ##
+        # When creating a label or creating a return label,
+        # if you set the charge_event field to a value that isn't offered by the carrier,
+        # then you will receive this error. You can leave the charge_event field unset,
+        # or set it to carrier_default instead.
+        # #/
+        INVALID_CHARGE_EVENT: "invalid_charge_event",
+
+        ##
+        #	One of the fields in your API request has an invalid value.
+        # The field_name property indicates which field is invalid.
+        # #/
+        INVALID_FIELD_VALUE: "invalid_field_value",
+
+        ##
+        #	This error is similar to invalid_field_value, but is specifically for ID fields,
+        # such as label_id, shipment_id, carrier_id, etc. The field_name property indicates which field is invalid.
+        # #/
+        INVALID_IDENTIFIER: "invalid_identifier",
+
+        ##
+        #	The operation you're attempting to perform is not allowed because the resource is in the wrong status.
+        # For example, if a label's status is "voided", then it cannot be included in a manifest.
+        # #/
+        INVALID_STATUS: "invalid_status",
+
+        ##
+        #	A string field in your API request is either too short or too long.
+        # The field_name property indicates which field is invalid,
+        # and the min_length and max_length properties indicate the allowed length.
+        # #/
+        INVALID_STRING_LENGTH: "invalid_string_length",
+
+        ##
+        #	Not all carriers allow you to add custom images to labels.
+        # You can only set the label_image_id for supported carriers
+        # #/
+        LABEL_IMAGES_NOT_SUPPORTED: "label_images_not_supported",
+
+        ##
+        #	This error indicates a problem with your FedEx account.
+        # Please contact FedEx to resolve the issue.
+        # #/
+        METER_FAILURE: "meter_failure",
+
+        ##
+        #	You have exceeded a rate limit.
+        # Check the the error_source field to determine whether the rate limit was imposed by ShipEngine or
+        # by a third-party, such as a carrier. If the rate limit is from ShipEngine,
+        # then consider using bulk operations to reduce the number of API calls,
+        # or contact our support team about increasing your rate limit.
+        # #/
+        RATE_LIMIT_EXCEEDED: "rate_limit_exceeded",
+
+        ##
+        #	The API call requires a JSON request body.
+        # See the corresponding documentation page for details about the request structure.
+        # #/
+        REQUEST_BODY_REQUIRED: "request_body_required",
+
+        ##
+        #	You may receive this error if you attempt to schedule a pickup for a return label.
+        # #/
+        RETURN_LABEL_NOT_SUPPORTED: "return_label_not_supported",
+
+        ##
+        #	You may receive this error if you attempt to perform an operation that requires a subscription.
+        # Please contact our sales department to discuss a ShipEngine enterprise contract.
+        # #/
+        SUBSCRIPTION_INACTIVE: "subscription_inactive",
+
+        ##
+        #	Some carriers require you to accept their terms and conditions before you can use them via ShipEngine.
+        # If you get this error, then please login to the ShipEngine dashboard to read and accept the carrier's terms.
+        # #/
+        TERMS_NOT_ACCEPTED: "terms_not_accepted",
+
+        ##
+        #	This error will occur if you attempt to track a package for a carrier that doesn't offer that service.
+        # #/
+        TRACKING_NOT_SUPPORTED: "tracking_not_supported",
+
+        ##
+        #	You may receive this error if your free trial period has expired and
+        # you have not upgraded your account or added billing information.
+        # #/
+        TRIAL_EXPIRED: "trial_expired",
+
+        ##
+        #	Your API key is incorrect, expired, or missing.
+        # Check our authentication guide to learn more about authentication with ShipEngine.
+        # #/
+        UNAUTHORIZED: "unauthorized",
+
+        ##
+        #	This error has not yet been assigned a code.
+        # See the notes above about how to handle these.
+        # #/
+        UNSPECIFIED: "unspecified",
+
+        ##
+        #	When verifying your account (by email, SMS, phone call, etc.) this error indicates that
+        # the verification code is incorrect. Please re-start the verification process to get a new code.
+        # #/
+        VERIFICATION_FAILURE: "verification_failure",
+
+        ##
+        #	You attempted to perform an operation on multiple shipments from different warehouses.
+        # Try performing separate operations for each warehouse instead.
+        # #/
+        WAREHOUSE_CONFLICT: "warehouse_conflict",
+
+        ##
+        #	ShipEngine only allows you to have one webhook of each type.
+        # If you would like to replace a webhook with a new one, please delete the old one first.
+        # #/
+        WEBHOOK_EVENT_TYPE_CONFLICT: "webhook_event_type_conflict",
+      }.freeze
+    end
+  end
+end

data/lib/shipengine/errors/error_source.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module ShipEngine
+  module Errors
+    ##
+    ##  This class has the ability to return a specific error source.
+    ##
+    ## @see https://www.shipengine.com/docs/errors/codes/#error-source
+    # #/
+    class ErrorSource
+      # @param [Symbol | String] key
+      # @return [String] error type
+      def self.get(key)
+        @sources[key.upcase.to_sym] || @sources[:SHIPENGINE]
+      end
+
+      @sources = {
+        ##
+        #	The error is from ShipEngine. If you have any questions or require support, please contact us
+        # #/
+        SHIPENGINE: "shipengine",
+
+        ##
+        #	The error came from a shipping carrier (such as UPS, FedEx, DHL, etc).
+        # ShipEngine support may be able to help clarify the error for you,
+        # but if the problem is with your carrier account, then you will need to contact them directly.
+        # #/
+        CARRIER: "carrier",
+
+        ##
+        #	The error came from an order source (such as Shopify, Ebay, WalMart, etc).
+        # ShipEngine support may be able to help clarify the error for you,
+        # but if the problem is with your seller account, then you will need to contact them directly.
+        # #/
+        ORDER_SOURCE: "order_source",
+      }.freeze
+    end
+  end
+end

data/lib/shipengine/errors/error_type.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module ShipEngine
+  module Errors
+    ##
+    ##  This class has the ability to return a specific error type.
+    # #/
+    class ErrorType
+      # @param [Symbol | String] key
+      # @return [String] error type
+      def self.get(key)
+        @types[key.upcase.to_sym]
+      end
+
+      @types = {
+        # There is a problem with your account. This may be your ShipEngine account
+        # or a third-party account. See the the error source to determine which
+        # account needs your attention.
+        ACCOUNT_STATUS: "account_status",
+
+        # There was a business rule violation. Business rules are requirements or
+        # limitations of a system. If the error source is ShipEngine, then please
+        # read the relevant documentation to find out what limitations or requirements
+        # apply. Or contact our support for help. If the error source is the carrier
+        # or order source, then ShipEngine support may still be able to help clarify
+        # the problem or propose a solution, or you may need to contact the third-party
+        # for assistance.
+        BUSINESS_RULES: "business_rules",
+
+        # Something is wrong with the input provided, such as missing a required field,
+        # or an illegal value or combination of values. This error type always means
+        # that some change needs to be made to the input before retrying.
+        VALIDATION: "validation",
+
+        # A security error will occur if your API key is invalid or expired, or if
+        # you attempt to perform an operation that is not permitted for your account.
+        SECURITY: "security",
+
+        # An unknown or unexpected error occurred in our system. Or an error occurred
+        # that has not yet been assigned a specific error_type. If you receive
+        # persistent system errors, then please contact our support or check our API
+        # status page to see if there's a known issue.
+        SYSTEM: "system",
+
+        INTEGRATIONS: "integrations",
+      }.freeze
+    end
+  end
+end

data/lib/shipengine/exceptions.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "shipengine/errors/error_code"
+require "shipengine/errors/error_source"
+require "shipengine/errors/error_type"
+
+module ShipEngine
+  module Exceptions
+    class ShipEngineError < StandardError
+      # message is inherited
+      attr_reader :source, :type, :code, :url
+
+      def initialize(message:, source:, type:, code:, url: nil)
+        code = ShipEngine::Errors::ErrorCode.get(code) if code.is_a?(String)
+        source = ShipEngine::Errors::ErrorSource.get(source) if source.is_a?(String)
+        super(message)
+        @source = source
+        @type = type
+        @code = code
+        @url = url
+      end
+    end
+
+    class << self
+      # only create custom errors for error "types" (which encompass codes). Prefer to use generic ShipEngine errors.
+      def invalid_field_value_error(message:)
+        ValidationError.new(
+          message: message,
+          code: ShipEngine::Errors::ErrorCode.get(:INVALID_FIELD_VALUE)
+        )
+      end
+
+      def required_error(field_name:)
+        ValidationError.new(
+          message: "#{field_name} must be specified.",
+          code: ShipEngine::Errors::ErrorCode.get(:FIELD_VALUE_REQUIRED)
+        )
+      end
+    end
+
+    # 400 error, or other "user exceptions"
+    class ValidationError < ShipEngineError
+      def initialize(message:, code:, source: nil)
+        super(
+          code: code,
+          source: source,
+          message: message,
+          type: ShipEngine::Errors::ErrorType.get(:VALIDATION),
+        )
+      end
+    end
+
+    class SystemError < ShipEngineError
+      def initialize(message:, code:, source: nil, url: nil)
+        super(
+          url: url,
+          code: code,
+          source: source,
+          message: message,
+          type: ShipEngine::Errors::ErrorType.get(:SYSTEM),
+        )
+      end
+    end
+
+    class RateLimitError < SystemError
+      attr_reader :retries
+
+      def initialize(retries: nil, message: "You have exceeded the rate limit.", source: nil)
+        super(
+          message: message,
+          code: ShipEngine::Errors::ErrorCode.get(:RATE_LIMIT_EXCEEDED),
+          source: source,
+          url: URI("https://www.shipengine.com/docs/rate-limits"),
+        )
+        @retries = retries
+      end
+    end
+  end
+end