paypal-rest-api 0.0.2 → 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

@@ -9,18 +9,18 @@ module PaypalAPI
   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
@@ -29,12 +29,12 @@ module PaypalAPI
       # @param request [Request] Original request
       # @param response [Response] Original response
       #
-      # @return [FailedRequestError] Built FailedRequestError
+      # @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

@@ -26,10 +26,10 @@ module PaypalAPI
       # @param request [Request] Original request
       # @param error [StandardError] Original error
       #
-      # @return [NetworkError] Built NetworkError
+      # @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/response.rb

@@ -7,7 +7,11 @@ 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

data/lib/paypal-api.rb

@@ -20,9 +20,7 @@ module PaypalAPI
     # Sets client
     attr_writer :client
 
-    # @!method post
-    #
-    #   Executes POST http request
+    # @!macro [new] request
     #
     #   @param path [String] Request path
     #   @param query [Hash, nil] Request query parameters
@@ -31,53 +29,31 @@ module PaypalAPI
     #
     #   @return [Response] Response object
     #
+
+    # @!method post(path, query: nil, body: nil, headers: nil)
     #
-    # @!method get
+    #   Executes POST http request
+    #   @macro request
     #
-    #   Executes GET http 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 get(path, query: nil, body: nil, headers: nil)
     #
+    #   Executes GET http request
+    #   @macro request
     #
-    # @!method patch
+    # @!method patch(path, query: nil, body: nil, headers: nil)
     #
     #   Executes PATCH http request
+    #   @macro 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 put
+    # @!method put(path, query: nil, body: nil, headers: nil)
     #
     #   Executes PUT http 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
-    #
+    #   @macro request
 
-    # @!method delete
+    # @!method delete(path, query: nil, body: nil, headers: nil)
     #
     #   Executes DELETE http 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
+    #   @macro request
     #
     [:post, :get, :patch, :put, :delete].each do |method_name|
       define_method(method_name) do |path, query: nil, body: nil, headers: nil|
@@ -89,19 +65,39 @@ module PaypalAPI
     # @!method authentication
     #   @return [Authentication]
     #
+    # @!method authorized_payments
+    #   @return [AuthorizedPayments]
+    #
+    # @!method captured_payments
+    #   @return [CapturedPayments]
+    #
+    # @!method catalog_products
+    #   @return [CatalogProducts]
+    #
     # @!method orders
     #   @return [Orders]
     #
-    # @!method payments
-    #   @return [Payments]
+    # @!method refunds
+    #   @return [Refunds]
+    #
+    # @!method shipment_tracking
+    #   @return [ShipmentTracking]
+    #
+    # @!method subscriptions
+    #   @return [Subscriptions]
     #
     # @!method webhooks
     #   @return [Webhooks]
     #
     %i[
       authentication
+      authorized_payments
+      captured_payments
+      catalog_products
       orders
-      payments
+      refunds
+      shipment_tracking
+      subscriptions
       webhooks
     ].each do |method_name|
       define_method(method_name) do
@@ -119,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"
@@ -128,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.2
+  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,39 +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
-    #
-    # Common class and instance methods
-    #
-    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,54 +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
-    #
-    # Common class and instance methods
-    #
-    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

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

@@ -1,58 +0,0 @@
-# frozen_string_literal: true
-
-module PaypalAPI
-  #
-  # https://developer.paypal.com/docs/api/webhooks/v1/
-  #
-  class Webhooks < Collection
-    #
-    # Common class and instance methods
-    #
-    module APIs
-      #
-      # @see https://developer.paypal.com/docs/api/webhooks/v1/#webhooks_post
-      #
-      def create(query: nil, body: nil, headers: nil)
-        client.post("/v1/notifications/webhooks", query: query, body: body, headers: headers)
-      end
-
-      #
-      # @see https://developer.paypal.com/docs/api/webhooks/v1/#webhooks_delete
-      #
-      def delete(webhook_id, query: nil, body: nil, headers: nil)
-        client.delete("/v1/notifications/webhooks/#{webhook_id}", query: query, body: body, headers: headers)
-      end
-
-      #
-      # @see https://developer.paypal.com/docs/api/webhooks/v1/#webhooks_list
-      #
-      def list(query: nil, body: nil, headers: nil)
-        client.get("/v1/notifications/webhooks", query: query, body: body, headers: headers)
-      end
-
-      #
-      # @see https://developer.paypal.com/docs/api/webhooks/v1/#webhooks_get
-      #
-      def show(webhook_id, query: nil, body: nil, headers: nil)
-        client.get("/v1/notifications/webhooks/#{webhook_id}", query: query, body: body, headers: headers)
-      end
-
-      #
-      # @see https://developer.paypal.com/docs/api/webhooks/v1/#webhooks_update
-      #
-      def update(webhook_id, query: nil, body: nil, headers: nil)
-        client.patch("/v1/notifications/webhooks/#{webhook_id}", query: query, body: body, headers: headers)
-      end
-
-      #
-      # @see https://developer.paypal.com/docs/api/webhooks/v1/#verify-webhook-signature_post
-      #
-      def verify(query: nil, body: nil, headers: nil)
-        client.post("/v1/notifications/verify-webhook-signature", query: query, body: body, headers: headers)
-      end
-    end
-
-    include APIs
-    extend APIs
-  end
-end