paypal-rest-api 0.0.1 → 0.0.3

data/lib/paypal-api/error.rb

@@ -5,92 +5,119 @@ module PaypalAPI
   # Common interface for all errors
   #
   class Error < StandardError
-    attr_reader :response, :request, :error_name, :error_message, :error_debug_id, :error_details
+    # @return [Response, nil] Returned response with non-200 status code
+    attr_reader :response
+
+    # @return [Request] Sent request
+    attr_reader :request
+
+    # @return [String] Error name provided by PayPal or Net::HTTP network error name
+    attr_reader :error_name
+
+    # @return [String] Error message provided by PayPal or Net::HTTP network error message
+    attr_reader :error_message
+
+    # @return [String, nil] Error debug_id returned by PayPal
+    attr_reader :error_debug_id
+
+    # @see https://developer.paypal.com/api/rest/responses/#link-examples
+    # @return [Array, nil] Error details returned by PayPal
+    attr_reader :error_details
+
+    # @return [String, nil] PayPal-Request-Id header assigned to request
+    attr_reader :paypal_request_id
   end
 
   #
-  # Raised when PayPal responds with any status code except 200, 201, 202, 204
+  # Namespace for specific PaypalAPI errors
   #
-  class FailedRequest < Error
-    def initialize(message = nil, request:, response:)
-      super(message)
-      @request = request
-      @response = response
-
-      body = response.body
-      data = body.is_a?(Hash) ? body : {}
-      @error_name = data[:name] || data[:error] || response.http_response.class.name
-      @error_message = data[:message] || data[:error_description] || response.http_body.to_s
-      @error_debug_id = data[:debug_id]
-      @error_details = data[:details]
+  module Errors
+    #
+    # Raised when PayPal responds with any status code except 200, 201, 202, 204
+    #
+    class FailedRequest < Error
+      def initialize(message = nil, request:, response:)
+        super(message)
+        @request = request
+        @response = response
+
+        body = response.body
+        data = body.is_a?(Hash) ? body : {}
+        @error_name = data[:name] || data[:error] || response.http_response.class.name
+        @error_message = data[:message] || data[:error_description] || response.http_body.to_s
+        @error_debug_id = data[:debug_id]
+        @error_details = data[:details]
+        @paypal_request_id = request.http_request["paypal-request-id"]
+      end
     end
-  end
 
-  #
-  # Raised when a network raised when executing the request
-  # List of network errors can be found in errors/network_error_builder.rb
-  #
-  class NetworkError < Error
-    def initialize(message = nil, request:, error:)
-      super(message)
-      @request = request
-      @response = nil
-      @error_name = error.class.name
-      @error_message = error.message
-      @error_debug_id = nil
-      @error_details = nil
+    #
+    # Raised when a network raised when executing the request
+    # List of network errors can be found in errors/network_error_builder.rb
+    #
+    class NetworkError < Error
+      def initialize(message = nil, request:, error:)
+        super(message)
+        @request = request
+        @response = nil
+        @error_name = error.class.name
+        @error_message = error.message
+        @error_debug_id = nil
+        @error_details = nil
+        @paypal_request_id = request.http_request["paypal-request-id"]
+      end
     end
-  end
 
-  # 400
-  class BadRequestError < FailedRequest
-  end
+    # 400
+    class BadRequest < FailedRequest
+    end
 
-  # 401
-  class UnauthorizedError < FailedRequest
-  end
+    # 401
+    class Unauthorized < FailedRequest
+    end
 
-  # 403
-  class ForbiddenError < FailedRequest
-  end
+    # 403
+    class Forbidden < FailedRequest
+    end
 
-  # 404
-  class NotFoundError < FailedRequest
-  end
+    # 404
+    class NotFound < FailedRequest
+    end
 
-  # 405
-  class MethodNotAllowedError < FailedRequest
-  end
+    # 405
+    class MethodNotAllowed < FailedRequest
+    end
 
-  # 406
-  class NotAcceptableError < FailedRequest
-  end
+    # 406
+    class NotAcceptable < FailedRequest
+    end
 
-  # 409
-  class ConflictError < FailedRequest
-  end
+    # 409
+    class Conflict < FailedRequest
+    end
 
-  # 415
-  class UnsupportedMediaTypeError < FailedRequest
-  end
+    # 415
+    class UnsupportedMediaType < FailedRequest
+    end
 
-  # 422
-  class UnprocessableEntityError < FailedRequest
-  end
+    # 422
+    class UnprocessableEntity < FailedRequest
+    end
 
-  # 429
-  class TooManyRequestsError < FailedRequest
-  end
+    # 429
+    class TooManyRequests < FailedRequest
+    end
 
-  # 5xx
-  class FatalError < FailedRequest
-  end
+    # 5xx
+    class FatalError < FailedRequest
+    end
 
-  # 500
-  class InternalServerError < FatalError
-  end
+    # 500
+    class InternalServerError < FatalError
+    end
 
-  # 503
-  class ServiceUnavailableError < FatalError
+    # 503
+    class ServiceUnavailable < FatalError
+    end
   end
 end

data/lib/paypal-api/failed_request_error_builder.rb

@@ -7,26 +7,34 @@ module PaypalAPI
   # Builds PaypalAPI::FailedRequest error
   #
   class FailedRequestErrorBuilder
+    # Matchings for Net::HTTP response class to PaypalAPI::Error class
     RESPONSE_ERROR_MAP = {
-      Net::HTTPBadRequest => BadRequestError,                     # 400
-      Net::HTTPUnauthorized => UnauthorizedError,                 # 401
-      Net::HTTPForbidden => ForbiddenError,                       # 403
-      Net::HTTPNotFound => NotFoundError,                         # 404
-      Net::HTTPMethodNotAllowed => MethodNotAllowedError,         # 405
-      Net::HTTPNotAcceptable => NotAcceptableError,               # 406
-      Net::HTTPConflict => ConflictError,                         # 409
-      Net::HTTPUnsupportedMediaType => UnsupportedMediaTypeError, # 415
-      Net::HTTPUnprocessableEntity => UnprocessableEntityError,   # 422
-      Net::HTTPTooManyRequests => TooManyRequestsError,           # 429
-      Net::HTTPInternalServerError => InternalServerError,        # 500
-      Net::HTTPServiceUnavailable => ServiceUnavailableError      # 503
+      Net::HTTPBadRequest => Errors::BadRequest,                     # 400
+      Net::HTTPUnauthorized => Errors::Unauthorized,                 # 401
+      Net::HTTPForbidden => Errors::Forbidden,                       # 403
+      Net::HTTPNotFound => Errors::NotFound,                         # 404
+      Net::HTTPMethodNotAllowed => Errors::MethodNotAllowed,         # 405
+      Net::HTTPNotAcceptable => Errors::NotAcceptable,               # 406
+      Net::HTTPConflict => Errors::Conflict,                         # 409
+      Net::HTTPUnsupportedMediaType => Errors::UnsupportedMediaType, # 415
+      Net::HTTPUnprocessableEntity => Errors::UnprocessableEntity,   # 422
+      Net::HTTPTooManyRequests => Errors::TooManyRequests,           # 429
+      Net::HTTPInternalServerError => Errors::InternalServerError,   # 500
+      Net::HTTPServiceUnavailable => Errors::ServiceUnavailable      # 503
     }.freeze
 
     class << self
+      # Builds FailedRequestError instance
+      #
+      # @param request [Request] Original request
+      # @param response [Response] Original response
+      #
+      # @return [Errors::FailedRequestError] error object
+      #
       def call(request:, response:)
         http_response = response.http_response
         error_message = "#{http_response.code} #{http_response.message}"
-        error_class = RESPONSE_ERROR_MAP.fetch(http_response.class, FailedRequest)
+        error_class = RESPONSE_ERROR_MAP.fetch(http_response.class, Errors::FailedRequest)
         error_class.new(error_message, response: response, request: request)
       end
     end

data/lib/paypal-api/network_error_builder.rb

@@ -5,6 +5,7 @@ module PaypalAPI
   # Builds PaypalAPI::NetowrkError error
   #
   class NetworkErrorBuilder
+    # List of possible Network errors
     ERRORS = [
       EOFError,
       Errno::ECONNABORTED,
@@ -20,8 +21,15 @@ module PaypalAPI
     ].freeze
 
     class << self
+      # Builds NetworkError instance
+      #
+      # @param request [Request] Original request
+      # @param error [StandardError] Original error
+      #
+      # @return [Errors::NetworkError] Built NetworkError
+      #
       def call(request:, error:)
-        NetworkError.new(error.message, request: request, error: error)
+        Errors::NetworkError.new(error.message, request: request, error: error)
       end
     end
   end

data/lib/paypal-api/request.rb

@@ -13,10 +13,30 @@ module PaypalAPI
   # - assigns content-type header
   #
   class Request
-    attr_reader :client, :http_request
+    # @return [Client] Current PaypalAPI Client
+    attr_reader :client
+
+    # @return [Net::HTTPRequest] Generated Net::HTTPRequest
+    attr_reader :http_request
+
+    # @return [Time, nil] Time when request was sent
     attr_accessor :requested_at
 
     # rubocop:disable Metrics/ParameterLists
+
+    # Initializes Request object
+    #
+    # @param client [Client] PaypalAPI client
+    # @param request_type [Class] One of: Net::HTTP::Post, Net::HTTP::Get,
+    #  Net::HTTP::Put, Net::HTTP::Patch, Net::HTTP::Delete
+    # @param path [String] Request path
+    #
+    # @param query [Hash, nil] Request query
+    # @param body [Hash, nil] Request body
+    # @param headers [Hash, nil] Request headers
+    #
+    # @return [Request] Request object
+    #
     def initialize(client, request_type, path, body: nil, query: nil, headers: nil)
       @client = client
       @http_request = build_http_request(request_type, path, body: body, query: query, headers: headers)

data/lib/paypal-api/request_executor.rb

@@ -5,6 +5,7 @@ module PaypalAPI
   # Executes PaypalAPI::Request and returns PaypalAPI::Response or raises PaypalAPI::Error
   #
   class RequestExecutor
+    # List of Net::HTTP responses that must be retried
     RETRYABLE_RESPONSES = [
       Net::HTTPServerError,    # 5xx
       Net::HTTPConflict,       # 409
@@ -12,6 +13,13 @@ module PaypalAPI
     ].freeze
 
     class << self
+      #
+      # Executes prepared Request, handles retries and preparation of errors
+      #
+      # @param [Request] request
+      #
+      # @return [Response] Response
+      #
       def call(request)
         http_response = execute(request)
         response = Response.new(http_response, requested_at: request.requested_at)

data/lib/paypal-api/response.rb

@@ -7,8 +7,20 @@ module PaypalAPI
   # PaypalAPI::Response object
   #
   class Response
-    attr_reader :http_response, :requested_at
+    # @return [Net::HTTP::Response] Original Net::HTTP::Response object
+    attr_reader :http_response
 
+    # @return [Time] Time when request was sent
+    attr_reader :requested_at
+
+    #
+    # Initializes Response object
+    #
+    # @param http_response [Net::HTTP::Response] original response
+    # @param requested_at [Time] Time when original response was requested
+    #
+    # @return [Response] Initialized Response object
+    #
     def initialize(http_response, requested_at:)
       @requested_at = requested_at
       @http_response = http_response
@@ -18,31 +30,43 @@ module PaypalAPI
       @body = nil
     end
 
+    # Parses JSON body if response body contains JSON or returns original
+    # http body string
+    #
+    # @return [Hash, String] Parsed response body (with symbolized keys)
     def body
       @body ||= json_response? ? parse_json(http_body) : http_body
     end
 
+    # @return [Integer] HTTP status as Integer
     def http_status
       @http_status ||= http_response.code.to_i
     end
 
+    # @return [Hash] HTTP headers as Hash
     def http_headers
       @http_headers ||= http_response.each_header.to_h
     end
 
+    # @return [String] Original http body
     def http_body
       @http_body ||= http_response.body
     end
 
+    # Takes specific key from body, returns nil if key not present in parsed body
     def [](key)
       body[key.to_sym] if body.is_a?(Hash)
     end
 
+    # Fetches specific key from body, raises error if key not exists
     def fetch(key)
       data = body.is_a?(Hash) ? body : {}
       data.fetch(key.to_sym)
     end
 
+    #
+    # Instance representation string. Default was overwritten to hide secrets
+    #
     def inspect
       "#<#{self.class.name} (#{http_response.code})>"
     end

data/lib/paypal-api.rb

@@ -2,29 +2,102 @@
 
 #
 # PaypalAPI is a main gem module.
+#
 # It can store global PaypalAPI::Client for easier access to APIs.
 #
-# For example:
-#   # setup client in an initializer
-#   PaypalAPI.client = PaypalAPI::Client.new(...)
+# @example Initializing new global client
+#   PaypalAPI.client = PaypalAPI::Client.new(
+#     client_id: ENV.fetch('PAYPAL_CLIENT_ID'),
+#     client_secret: ENV.fetch('PAYPAL_CLIENT_SECRET'),
+#     live: false
+#   )
 #
-#   # And then use anywhere
+#   # And then call any APIs without mentioning the client
 #   PaypalAPI::Webhooks.list # or PaypalAPI.webhooks.list
 #
 module PaypalAPI
   class << self
+    # Sets client
     attr_writer :client
 
+    # @!macro [new] request
+    #
+    #   @param path [String] Request path
+    #   @param query [Hash, nil] Request query parameters
+    #   @param body [Hash, nil] Request body parameters
+    #   @param headers [Hash, nil] Request headers
+    #
+    #   @return [Response] Response object
+    #
+
+    # @!method post(path, query: nil, body: nil, headers: nil)
+    #
+    #   Executes POST http request
+    #   @macro request
+    #
+    # @!method get(path, query: nil, body: nil, headers: nil)
+    #
+    #   Executes GET http request
+    #   @macro request
+    #
+    # @!method patch(path, query: nil, body: nil, headers: nil)
+    #
+    #   Executes PATCH http request
+    #   @macro request
+    #
+    # @!method put(path, query: nil, body: nil, headers: nil)
+    #
+    #   Executes PUT http request
+    #   @macro request
+
+    # @!method delete(path, query: nil, body: nil, headers: nil)
+    #
+    #   Executes DELETE http request
+    #   @macro request
+    #
     [:post, :get, :patch, :put, :delete].each do |method_name|
       define_method(method_name) do |path, query: nil, body: nil, headers: nil|
         client.public_send(method_name, path, query: query, body: body, headers: headers)
       end
     end
 
+    #
+    # @!method authentication
+    #   @return [Authentication]
+    #
+    # @!method authorized_payments
+    #   @return [AuthorizedPayments]
+    #
+    # @!method captured_payments
+    #   @return [CapturedPayments]
+    #
+    # @!method catalog_products
+    #   @return [CatalogProducts]
+    #
+    # @!method orders
+    #   @return [Orders]
+    #
+    # @!method refunds
+    #   @return [Refunds]
+    #
+    # @!method shipment_tracking
+    #   @return [ShipmentTracking]
+    #
+    # @!method subscriptions
+    #   @return [Subscriptions]
+    #
+    # @!method webhooks
+    #   @return [Webhooks]
+    #
     %i[
-      authorization
+      authentication
+      authorized_payments
+      captured_payments
+      catalog_products
       orders
-      payments
+      refunds
+      shipment_tracking
+      subscriptions
       webhooks
     ].each do |method_name|
       define_method(method_name) do
@@ -32,6 +105,7 @@ module PaypalAPI
       end
     end
 
+    # Globally set Client object
     def client
       raise "#{name}.client must be set" unless @client
 
@@ -41,8 +115,8 @@ module PaypalAPI
 end
 
 require_relative "paypal-api/access_token"
+require_relative "paypal-api/api_collection"
 require_relative "paypal-api/client"
-require_relative "paypal-api/collection"
 require_relative "paypal-api/config"
 require_relative "paypal-api/error"
 require_relative "paypal-api/failed_request_error_builder"
@@ -50,7 +124,12 @@ require_relative "paypal-api/network_error_builder"
 require_relative "paypal-api/request"
 require_relative "paypal-api/request_executor"
 require_relative "paypal-api/response"
-require_relative "paypal-api/collections/authentication"
-require_relative "paypal-api/collections/orders"
-require_relative "paypal-api/collections/payments"
-require_relative "paypal-api/collections/webhooks"
+require_relative "paypal-api/api_collections/authentication"
+require_relative "paypal-api/api_collections/authorized_payments"
+require_relative "paypal-api/api_collections/captured_payments"
+require_relative "paypal-api/api_collections/catalog_products"
+require_relative "paypal-api/api_collections/orders"
+require_relative "paypal-api/api_collections/refunds"
+require_relative "paypal-api/api_collections/shipment_tracking"
+require_relative "paypal-api/api_collections/subscriptions"
+require_relative "paypal-api/api_collections/webhooks"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: paypal-rest-api
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.3
 platform: ruby
 authors:
 - Andrey Glushkov
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-08-06 00:00:00.000000000 Z
+date: 2024-08-12 00:00:00.000000000 Z
 dependencies: []
 description: PayPal REST API with no dependencies.
 email:
@@ -21,12 +21,17 @@ files:
 - VERSION
 - lib/paypal-api.rb
 - lib/paypal-api/access_token.rb
+- lib/paypal-api/api_collection.rb
+- lib/paypal-api/api_collections/authentication.rb
+- lib/paypal-api/api_collections/authorized_payments.rb
+- lib/paypal-api/api_collections/captured_payments.rb
+- lib/paypal-api/api_collections/catalog_products.rb
+- lib/paypal-api/api_collections/orders.rb
+- lib/paypal-api/api_collections/refunds.rb
+- lib/paypal-api/api_collections/shipment_tracking.rb
+- lib/paypal-api/api_collections/subscriptions.rb
+- lib/paypal-api/api_collections/webhooks.rb
 - lib/paypal-api/client.rb
-- lib/paypal-api/collection.rb
-- lib/paypal-api/collections/authentication.rb
-- lib/paypal-api/collections/orders.rb
-- lib/paypal-api/collections/payments.rb
-- lib/paypal-api/collections/webhooks.rb
 - lib/paypal-api/config.rb
 - lib/paypal-api/error.rb
 - lib/paypal-api/failed_request_error_builder.rb

data/lib/paypal-api/collections/orders.rb

@@ -1,36 +0,0 @@
-# frozen_string_literal: true
-
-module PaypalAPI
-  #
-  # Create, update, retrieve, authorize, and capture orders.
-  #
-  # https://developer.paypal.com/docs/api/orders/v2/
-  #
-  class Orders < Collection
-    module APIs
-      #
-      # @see https://developer.paypal.com/docs/api/orders/v2/#orders_authorize
-      #
-      def authorize(id, query: nil, body: nil, headers: nil)
-        client.post("/v2/checkout/orders/#{id}/authorize", query: query, body: body, headers: headers)
-      end
-
-      #
-      # @see https://developer.paypal.com/docs/api/orders/v2/#orders_create
-      #
-      def create(query: nil, body: nil, headers: nil)
-        client.post("/v2/checkout/orders", query: query, body: body, headers: headers)
-      end
-
-      #
-      # @see https://developer.paypal.com/docs/api/orders/v2/#orders_get
-      #
-      def show(id, query: nil, body: nil, headers: nil)
-        client.get("/v2/checkout/orders/#{id}", query: query, body: body, headers: headers)
-      end
-    end
-
-    include APIs
-    extend APIs
-  end
-end

data/lib/paypal-api/collections/payments.rb

@@ -1,51 +0,0 @@
-# frozen_string_literal: true
-
-module PaypalAPI
-  #
-  # Use in conjunction with the Orders API to authorize payments, capture authorized payments,
-  # refund payments that have already been captured, and show payment information.
-  #
-  # https://developer.paypal.com/docs/api/payments/v2
-  #
-  class Payments < Collection
-    module APIs
-      #
-      # @see https://developer.paypal.com/docs/api/payments/v2/#authorizations_capture
-      #
-      def capture(authorization_id, query: nil, body: nil, headers: nil)
-        client.post("/v2/payments/authorizations/#{authorization_id}/capture", query: query, body: body, headers: headers)
-      end
-
-      #
-      # @see https://developer.paypal.com/docs/api/payments/v2/#captures_refund
-      #
-      def refund(capture_id, query: nil, body: nil, headers: nil)
-        client.post("/v2/payments/captures/#{capture_id}/refund", query: query, body: body, headers: headers)
-      end
-
-      #
-      # @see https://developer.paypal.com/docs/api/payments/v2/#authorizations_get
-      #
-      def show_authorized(authorization_id, query: nil, body: nil, headers: nil)
-        client.get("/v2/payments/authorizations/#{authorization_id}", query: query, body: body, headers: headers)
-      end
-
-      #
-      # @see https://developer.paypal.com/docs/api/payments/v2/#captures_get
-      #
-      def show_captured(capture_id, query: nil, body: nil, headers: nil)
-        client.get("/v2/payments/captures/#{capture_id}", query: query, body: body, headers: headers)
-      end
-
-      #
-      # @see https://developer.paypal.com/docs/api/payments/v2/#authorizations_void
-      #
-      def void(authorization_id, query: nil, body: nil, headers: nil)
-        client.post("/v2/payments/authorizations/#{authorization_id}/void", query: query, body: body, headers: headers)
-      end
-    end
-
-    include APIs
-    extend APIs
-  end
-end