paypal-rest-api 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb3399d7f3412a84242a4ba9bf2c38447cc1987ca7a90a7e9a51a2628edb7809
-  data.tar.gz: ab029c43b63e930b30727a127b356c75388df84d8410fd45aac8edac2a37fa53
+  metadata.gz: 01d19ac0652fbd1ee8cf49d9e5d91d2fd46071b38dfdd5524bf926d2ad9cf6b1
+  data.tar.gz: 68eb65741710644c17b329fa4dff432671badafa4d1f325e9ba6003be934fb58
 SHA512:
-  metadata.gz: b33f4638da4db6992030b9a5fcae5d8836e6cf50cf600adbec07518e8e182f79cb86802f271b8b7276d2391078e8ec11f4a1472865af8bc4a496bbd42f7cb290
-  data.tar.gz: 583f9a28508b386c282fd9d1b793042abe461425da3cc4227d17f033263e71b8c17ad2abff09c722f90f62d598f09fe5bbf84c0a9ce789cbf29e948d7c223957
+  metadata.gz: 1728d99460680ef7b8ce8f2cb98447e00a82d7186e0fe3d84c6883e20e089fe1fa52c7041bcce96e5ee415bde6f09959b2cb08cdac55a2e4c1eb1efce7cb36cd
+  data.tar.gz: 3bcfd687d6e0300dfb0d2463954e7706dd18cfaf176fce356050f4ae5b5ffd62f9f877299c17671ecedd5147947bc570e9d72af75901db87a7e9fd55fd6ebda7

data/README.md

@@ -62,7 +62,11 @@ Also PaypalAPI client can be added globally and class methods can be used instea
 
 ```ruby
 # in config/initializers/paypal_api.rb
-PaypalAPI.client = PaypalAPI::Client.new(...)
+PaypalAPI.client = PaypalAPI::Client.new(
+  client_id: ENV['PAYPAL_CLIENT_ID'],
+  client_secret: ENV['PAYPAL_CLIENT_SECRET'],
+  live: false
+)
 
 # in your business logic
 response = PaypalAPI.orders.create(body: body)
@@ -91,7 +95,7 @@ When `live` is `false` all requests will be send to the sandbox endpoints.
 
 ```ruby
 client = PaypalAPI::Client.new(
-  live: true,
+  live: true
   # ...
 )
 ```
@@ -167,7 +171,16 @@ All errors have additional methods:
 begin
   response = PaypalAPI.payments.capture(authorization_id, body: body)
 rescue PaypalAPI::Error => error
-  YourLogger.error(...)
+  YourLogger.error(
+    error,
+    context: {
+      error_name: error.error_name,
+      error_message: error.error_message,
+      error_debug_id: error.error_debug_id,
+      error_details: error.error_details
+    }
+  )
+  # `error.request` and `error.response` methods can be used also
 end
 
 ```

data/VERSION

@@ -1 +1 @@
-0.0.1
+0.0.2

data/lib/paypal-api/access_token.rb

@@ -7,6 +7,16 @@ module PaypalAPI
   class AccessToken
     attr_reader :requested_at, :expires_at, :authorization_string
 
+    #
+    # Initializes AccessToken object
+    #
+    # @param requested_at [Time] Time when token was requested
+    # @param expires_in [Integer] Count of seconds until token expires
+    # @param access_token [String] Aceess token string generated by PayPal
+    # @param token_type [String] Aceess token type, which is constantly `Bearer`
+    #
+    # @return [AccessToken] Generated AccessToken object
+    #
     def initialize(requested_at:, expires_in:, access_token:, token_type:)
       @requested_at = requested_at
       @expires_at = requested_at + expires_in
@@ -14,10 +24,16 @@ module PaypalAPI
       freeze
     end
 
+    #
+    # Shows if current AccessToken was expired
+    #
     def expired?
       Time.now >= expires_at
     end
 
+    #
+    # Instance representation string. Default was overwritten to hide original access_token
+    #
     def inspect
       "#<#{self.class.name} methods: (requested_at, expires_at, expired?, authorization_string)>"
     end

data/lib/paypal-api/client.rb

@@ -7,6 +7,16 @@ module PaypalAPI
   class Client
     attr_reader :config
 
+    # Initializes Client
+    #
+    # @param client_id [String] PayPal client id
+    # @param client_secret [String] PayPal client secret
+    # @param live [Boolean] PayPal live/sandbox mode
+    # @param http_opts [Hash] Net::Http opts for all requests
+    # @param retries [Hash] Retries configuration
+    #
+    # @return [Client] Initialized client
+    #
     def initialize(client_id:, client_secret:, live: nil, http_opts: nil, retries: nil)
       @config = PaypalAPI::Config.new(
         client_id: client_id,
@@ -19,12 +29,22 @@ module PaypalAPI
       @access_token = nil
     end
 
+    #
+    # Checks cached access token is expired and returns it or generates new one
+    #
+    # @return [AccessToken] AccessToken object
+    #
     def access_token
       (@access_token.nil? || @access_token.expired?) ? refresh_access_token : @access_token
     end
 
+    #
+    # Generates and caches new AccessToken
+    #
+    # @return [AccessToken] new AccessToken object
+    #
     def refresh_access_token
-      response = authorization.generate_access_token
+      response = authentication.generate_access_token
 
       @access_token = AccessToken.new(
         requested_at: response.requested_at,
@@ -34,38 +54,92 @@ module PaypalAPI
       )
     end
 
+    #
+    # Executes POST 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
+    #
     def post(path, query: nil, body: nil, headers: nil)
       execute_request(Net::HTTP::Post, path, query: query, body: body, headers: headers)
     end
 
+    #
+    # 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
+    #
     def get(path, query: nil, body: nil, headers: nil)
       execute_request(Net::HTTP::Get, path, query: query, body: body, headers: headers)
     end
 
+    #
+    # Executes PATCH 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
+    #
     def patch(path, query: nil, body: nil, headers: nil)
       execute_request(Net::HTTP::Patch, path, query: query, body: body, headers: headers)
     end
 
+    #
+    # 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
+    #
     def put(path, query: nil, body: nil, headers: nil)
       execute_request(Net::HTTP::Put, path, query: query, body: body, headers: headers)
     end
 
+    #
+    # 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
+    #
     def delete(path, query: nil, body: nil, headers: nil)
       execute_request(Net::HTTP::Delete, path, query: query, body: body, headers: headers)
     end
 
-    def authorization
+    # @return [Authentication] Authentication APIs collection
+    def authentication
       Authentication.new(self)
     end
 
+    # @return [Orders] Orders APIs collection
     def orders
       Orders.new(self)
     end
 
+    # @return [Payments] Payments APIs collection
     def payments
       Payments.new(self)
     end
 
+    # @return [Webhooks] Webhooks APIs collection
     def webhooks
       Webhooks.new(self)
     end

data/lib/paypal-api/collection.rb

@@ -5,12 +5,20 @@ module PaypalAPI
   # Base class for all PayPal API collections classes
   #
   class Collection
+    # @return current client
     attr_reader :client
 
+    # Initializes APIs collection
+    #
+    # @param client [Client] current client
+    #
+    # @return [Collection] APIs collection
+    #
     def initialize(client)
       @client = client
     end
 
+    # @return global client
     def self.client
       PaypalAPI.client
     end

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

@@ -33,7 +33,7 @@ module PaypalAPI
       #
       # @param query [Hash, nil] Request query string parameters
       # @param body [Hash, nil] Request body parameters
-      # @param body [Hash, nil] Request headers
+      # @param headers [Hash, nil] Request headers
       #
       # @raise [Error] on network error or non 2** status code returned from PayPal
       # @return [Response] detailed http request-response representation

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

@@ -7,6 +7,9 @@ module PaypalAPI
   # 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

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

@@ -8,6 +8,9 @@ module PaypalAPI
   # 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

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

@@ -5,44 +5,47 @@ module PaypalAPI
   # https://developer.paypal.com/docs/api/webhooks/v1/
   #
   class Webhooks < Collection
+    #
+    # Common class and instance methods
+    #
     module APIs
       #
-      # https://developer.paypal.com/docs/api/webhooks/v1/#webhooks_post
+      # @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
 
       #
-      # https://developer.paypal.com/docs/api/webhooks/v1/#webhooks_delete
+      # @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
 
       #
-      # https://developer.paypal.com/docs/api/webhooks/v1/#webhooks_list
+      # @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
 
       #
-      # https://developer.paypal.com/docs/api/webhooks/v1/#webhooks_get
+      # @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
 
       #
-      # https://developer.paypal.com/docs/api/webhooks/v1/#webhooks_update
+      # @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
 
       #
-      # https://developer.paypal.com/docs/api/webhooks/v1/#verify-webhook-signature_post
+      # @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)

data/lib/paypal-api/config.rb

@@ -1,21 +1,35 @@
 # frozen_string_literal: true
 
 module PaypalAPI
-  LIVE_URL = "https://api-m.paypal.com"
-  SANDBOX_URL = "https://api-m.sandbox.paypal.com"
-
-  DEFAULTS = {
-    live: false,
-    http_opts: {}.freeze,
-    retries: {enabled: true, count: 3, sleep: [0.25, 0.75, 1.5].freeze}.freeze
-  }.freeze
-
   #
   # Stores configuration for PaypalAPI Client
   #
   class Config
+    # Live PayPal URL
+    LIVE_URL = "https://api-m.paypal.com"
+
+    # Sandbox PayPal URL
+    SANDBOX_URL = "https://api-m.sandbox.paypal.com"
+
+    # Default config options
+    DEFAULTS = {
+      live: false,
+      http_opts: {}.freeze,
+      retries: {enabled: true, count: 3, sleep: [0.25, 0.75, 1.5].freeze}.freeze
+    }.freeze
+
     attr_reader :client_id, :client_secret, :live, :http_opts, :retries
 
+    # Initializes Config
+    #
+    # @param client_id [String] PayPal client id
+    # @param client_secret [String] PayPal client secret
+    # @param live [Boolean] PayPal live/sandbox mode
+    # @param http_opts [Hash] Net::Http opts for all requests
+    # @param retries [Hash] Retries configuration
+    #
+    # @return [Client] Initialized config object
+    #
     def initialize(client_id:, client_secret:, live: nil, http_opts: nil, retries: nil)
       @client_id = client_id
       @client_secret = client_secret
@@ -25,10 +39,14 @@ module PaypalAPI
       freeze
     end
 
+    # @return [String] PayPal live or sandbox URL
     def url
       live ? LIVE_URL : SANDBOX_URL
     end
 
+    #
+    # Instance representation string. Default was overwritten to hide secrets
+    #
     def inspect
       "#<#{self.class.name} live: #{live}>"
     end

data/lib/paypal-api/failed_request_error_builder.rb

@@ -7,6 +7,7 @@ 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
@@ -23,6 +24,13 @@ module PaypalAPI
     }.freeze
 
     class << self
+      # Builds FailedRequestError instance
+      #
+      # @param request [Request] Original request
+      # @param response [Response] Original response
+      #
+      # @return [FailedRequestError] Built FailedRequestError
+      #
       def call(request:, response:)
         http_response = response.http_response
         error_message = "#{http_response.code} #{http_response.message}"

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,6 +21,13 @@ module PaypalAPI
     ].freeze
 
     class << self
+      # Builds NetworkError instance
+      #
+      # @param request [Request] Original request
+      # @param error [StandardError] Original error
+      #
+      # @return [NetworkError] Built NetworkError
+      #
       def call(request:, error:)
         NetworkError.new(error.message, request: request, error: error)
       end

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

@@ -9,6 +9,14 @@ module PaypalAPI
   class Response
     attr_reader :http_response, :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 +26,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,27 +2,104 @@
 
 #
 # 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
 
+    # @!method post
+    #
+    #   Executes POST 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
+    #
+    #   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 patch
+    #
+    #   Executes PATCH 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 put
+    #
+    #   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
+    #
+
+    # @!method delete
+    #
+    #   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
+    #
     [: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 orders
+    #   @return [Orders]
+    #
+    # @!method payments
+    #   @return [Payments]
+    #
+    # @!method webhooks
+    #   @return [Webhooks]
+    #
     %i[
-      authorization
+      authentication
       orders
       payments
       webhooks
@@ -32,6 +109,7 @@ module PaypalAPI
       end
     end
 
+    # Globally set Client object
     def client
       raise "#{name}.client must be set" unless @client
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: paypal-rest-api
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Andrey Glushkov