paypal-rest-api 0.0.1 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb3399d7f3412a84242a4ba9bf2c38447cc1987ca7a90a7e9a51a2628edb7809
-  data.tar.gz: ab029c43b63e930b30727a127b356c75388df84d8410fd45aac8edac2a37fa53
+  metadata.gz: 9dac5031d1b2e2fe6f58b269801cd0e818280d4ed9b54fafc948e1b758d99b87
+  data.tar.gz: 4992abcc8678eca0bbc31702d49e6d6a596f7e614f3e8d6966a5716004adde26
 SHA512:
-  metadata.gz: b33f4638da4db6992030b9a5fcae5d8836e6cf50cf600adbec07518e8e182f79cb86802f271b8b7276d2391078e8ec11f4a1472865af8bc4a496bbd42f7cb290
-  data.tar.gz: 583f9a28508b386c282fd9d1b793042abe461425da3cc4227d17f033263e71b8c17ad2abff09c722f90f62d598f09fe5bbf84c0a9ce789cbf29e948d7c223957
+  metadata.gz: 63cc5c666b4483eb92bd6d5282173cb2841b517eb39762421c5c546b23d4c2b1e44fe689495aa75dca15f1a86ac66064e9db7fa77d4d389deb1f0e370de107aa
+  data.tar.gz: 2e0e52e4fb9e324017f2af0fefe410daab14b01a3f7b322a686c00fb64ca8c1987bec7ece18958eb0c85327bb25f5f20e5fefdb5111043023efa29a049c8a893

data/README.md

@@ -16,9 +16,7 @@ bundle add paypal-rest-api
 
 ## Usage
 
-- All APIs accept `:query`, `:body` and `:headers` keyword parameters.
-- Some APIs (like show, update, delete) require positional parameters with ID of
-  a resource.
+- All APIs accept optional `:query`, `:body` and `:headers` keyword parameters.
 - Response has `#body` method to get parsed JSON body.
   This body has `symbolized` hash keys.
 - Response contains methods to get original HTTP response.
@@ -34,13 +32,13 @@ client = PaypalAPI::Client.new(
   live: false
 )
 
-# APIs calls examples:
+# Usage example:
 response = client.orders.create(body: body)
 response = client.orders.show(order_id)
-response = client.payments.capture(authorization_id, headers: headers)
+response = client.authorized_payments.capture(authorization_id, headers: headers)
 response = client.webhooks.list(query: query)
 
-# Client can be used directly to send request to any path
+# Client also can send requests directly, bypassing specific resources methods
 response = client.post(path, query: query, body: body, headers: headers)
 response = client.get(path, query: query, body: body, headers: headers)
 response = client.patch(path, query: query, body: body, headers: headers)
@@ -48,7 +46,7 @@ response = client.put(path, query: query, body: body, headers: headers)
 response = client.delete(path, query: query, body: body, headers: headers)
 
 # Getting response
-response.body # parsed JSON. Parsed with `JSON.load(http_body, symbolyzed_keys: true)`
+response.body # Parsed JSON. JSON is parsed lazyly, keys are symbolized.
 response[:foo] # Gets :foo attribute from parsed body
 response.fetch(:foo) # Fetches :foo attribute from parsed body
 response.http_response # original Net::HTTP::Response
@@ -62,7 +60,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 +93,7 @@ When `live` is `false` all requests will be send to the sandbox endpoints.
 
 ```ruby
 client = PaypalAPI::Client.new(
-  live: true,
+  live: true
   # ...
 )
 ```
@@ -137,24 +139,25 @@ All APIs can raise error in case of network error or non-2xx response status cod
 Errors structure:
 
 - `PaypalAPI::Error`
-   - `PaypalAPI::NetworkError` - any network error
-   - `PaypalAPI::FailedRequest` - any non-2xx code error
-      - 400 - `PaypalAPI::BadRequestError`
-      - 401 - `PaypalAPI::UnauthorizedError`
-      - 403 - `PaypalAPI::ForbiddenError`
-      - 404 - `PaypalAPI::NotFoundError`
-      - 405 - `PaypalAPI::MethodNotAllowedError`
-      - 406 - `PaypalAPI::NotAcceptableError`
-      - 409 - `PaypalAPI::ConflictError`
-      - 415 - `PaypalAPI::UnsupportedMediaTypeError`
-      - 422 - `PaypalAPI::UnprocessableEntityError`
-      - 429 - `PaypalAPI::TooManyRequestsError`
-      - 5xx - `PaypalAPI::FatalError`
-         - 500 - `PaypalAPI::InternalServerError`
-         - 503 - `PaypalAPI::ServiceUnavailableError`
+   - `PaypalAPI::Errors::NetworkError` - any network error
+   - `PaypalAPI::Errors::FailedRequest` - any non-2xx code error
+      - 400 - `PaypalAPI::Errors::BadRequest`
+      - 401 - `PaypalAPI::Errors::Unauthorized`
+      - 403 - `PaypalAPI::Errors::Forbidden`
+      - 404 - `PaypalAPI::Errors::NotFound`
+      - 405 - `PaypalAPI::Errors::MethodNotAllowed`
+      - 406 - `PaypalAPI::Errors::NotAcceptable`
+      - 409 - `PaypalAPI::Errors::Conflict`
+      - 415 - `PaypalAPI::Errors::UnsupportedMediaType`
+      - 422 - `PaypalAPI::Errors::UnprocessableEntity`
+      - 429 - `PaypalAPI::Errors::TooManyRequests`
+      - 5xx - `PaypalAPI::Errors::FatalError`
+         - 500 - `PaypalAPI::Errors::InternalServerError`
+         - 503 - `PaypalAPI::Errors::ServiceUnavailable`
 
 All errors have additional methods:
 
+- `#paypal_request_id` - PayPal-Request-Id header sent with request
 - `#response` - Original response object, can be nil in case of NetworkError
 - `#request` - Original request object
 - `#error_name` - Original error name
@@ -167,7 +170,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.3

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/{collection.rb → api_collection.rb}

@@ -4,13 +4,21 @@ module PaypalAPI
   #
   # Base class for all PayPal API collections classes
   #
-  class Collection
+  class APICollection
+    # @return current client
     attr_reader :client
 
+    # Initializes API 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 → api_collections}/authentication.rb

@@ -6,7 +6,7 @@ module PaypalAPI
   #
   # @see https://developer.paypal.com/api/rest/authentication/
   #
-  class Authentication < Collection
+  class Authentication < APICollection
     #
     # Generate access-token API request path
     #
@@ -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/api_collections/authorized_payments.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module PaypalAPI
+  #
+  # Authorized payments APIs `/v2/payments/authorizations`
+  #
+  # @see https://developer.paypal.com/docs/api/payments/v2
+  #
+  class AuthorizedPayments < APICollection
+    #
+    # Common class and instance methods
+    #
+    module APIs
+      # @!macro [new] request
+      #   @param query [Hash, nil] Request query parameters
+      #   @param body [Hash, nil] Request body parameters
+      #   @param headers [Hash, nil] Request headers
+      #   @return [Response] Response object
+
+      #
+      # Show details for authorized payment
+      #
+      # @see https://developer.paypal.com/docs/api/payments/v2/#authorizations_get
+      #
+      # @param authorization_id [String] Authorization ID
+      # @macro request
+      #
+      def show(authorization_id, query: nil, body: nil, headers: nil)
+        client.get("/v2/payments/authorizations/#{authorization_id}", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Capture authorized payment
+      #
+      # @see https://developer.paypal.com/docs/api/payments/v2/#authorizations_capture
+      #
+      # @param authorization_id [String] Authorization ID
+      # @macro request
+      #
+      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
+
+      # Reauthorize authorized payment
+      #
+      # @see https://developer.paypal.com/docs/api/payments/v2/#authorizations_capture
+      #
+      # @param authorization_id [String] Authorization ID
+      # @macro request
+      #
+      def reauthorize(authorization_id, query: nil, body: nil, headers: nil)
+        client.post("/v2/payments/authorizations/#{authorization_id}/reauthorize", query: query, body: body, headers: headers)
+      end
+
+      # Void authorized payment
+      #
+      # @see https://developer.paypal.com/docs/api/payments/v2/#authorizations_void
+      #
+      # @param authorization_id [String] Authorization ID
+      # @macro request
+      #
+      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/api_collections/captured_payments.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module PaypalAPI
+  #
+  # Captured payments APIs `/v2/payments/captures`
+  #
+  # @see https://developer.paypal.com/docs/api/payments/v2
+  #
+  class CapturedPayments < APICollection
+    #
+    # Common class and instance methods
+    #
+    module APIs
+      # @!macro [new] request
+      #   @param query [Hash, nil] Request query parameters
+      #   @param body [Hash, nil] Request body parameters
+      #   @param headers [Hash, nil] Request headers
+      #   @return [Response] Response object
+
+      #
+      # Show captured payment details
+      #
+      # @see https://developer.paypal.com/docs/api/payments/v2/#captures_get
+      #
+      # @param capture_id [String] Capture ID
+      # @macro request
+      #
+      def show(capture_id, query: nil, body: nil, headers: nil)
+        client.get("/v2/payments/captures/#{capture_id}", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Refund captured payment
+      #
+      # @see https://developer.paypal.com/docs/api/payments/v2/#captures_refund
+      #
+      # @param capture_id [String] Capture ID
+      # @macro request
+      #
+      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
+    end
+
+    include APIs
+    extend APIs
+  end
+end

data/lib/paypal-api/api_collections/catalog_products.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module PaypalAPI
+  #
+  # Merchants can use the Catalog Products API to create products, which are goods and services.
+  #
+  # @see https://developer.paypal.com/docs/api/catalog-products/v1/
+  #
+  class CatalogProducts < APICollection
+    #
+    # Common class and instance methods
+    #
+    module APIs
+      # @!macro [new] request
+      #   @param query [Hash, nil] Request query parameters
+      #   @param body [Hash, nil] Request body parameters
+      #   @param headers [Hash, nil] Request headers
+      #   @return [Response] Response object
+
+      #
+      # Create product
+      #
+      # @see https://developer.paypal.com/docs/api/catalog-products/v1/#products_create
+      #
+      # @macro request
+      #
+      def create(query: nil, body: nil, headers: nil)
+        client.post("/v1/catalogs/products", query: query, body: body, headers: headers)
+      end
+
+      #
+      # List products
+      #
+      # @see https://developer.paypal.com/docs/api/catalog-products/v1/#products_list
+      #
+      # @macro request
+      #
+      def list(query: nil, body: nil, headers: nil)
+        client.get("/v1/catalogs/products", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Show product details
+      #
+      # @see https://developer.paypal.com/docs/api/catalog-products/v1/#products_get
+      #
+      # @param product_id [String] Product ID
+      # @macro request
+      #
+      def show(product_id, query: nil, body: nil, headers: nil)
+        client.get("/v1/catalogs/products/#{product_id}", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Update product
+      #
+      # @see https://developer.paypal.com/docs/api/catalog-products/v1/#products_patch
+      #
+      # @param product_id [String] Product ID
+      # @macro request
+      #
+      def update(product_id, query: nil, body: nil, headers: nil)
+        client.patch("/v1/catalogs/products/#{product_id}", query: query, body: body, headers: headers)
+      end
+    end
+
+    include APIs
+    extend APIs
+  end
+end

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

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module PaypalAPI
+  #
+  # Create, update, retrieve, authorize, and capture orders.
+  #
+  # @see https://developer.paypal.com/docs/api/orders/v2/
+  #
+  class Orders < APICollection
+    #
+    # Common class and instance methods
+    #
+    module APIs
+      # @!macro [new] request
+      #   @param query [Hash, nil] Request query parameters
+      #   @param body [Hash, nil] Request body parameters
+      #   @param headers [Hash, nil] Request headers
+      #   @return [Response] Response object
+
+      #
+      # Create Order
+      #
+      # @see https://developer.paypal.com/docs/api/orders/v2/#orders_create
+      #
+      # @macro request
+      #
+      def create(query: nil, body: nil, headers: nil)
+        client.post("/v2/checkout/orders", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Show order details
+      #
+      # @see https://developer.paypal.com/docs/api/orders/v2/#orders_get
+      #
+      # @param id [String] Order ID
+      # @macro request
+      #
+      def show(id, query: nil, body: nil, headers: nil)
+        client.get("/v2/checkout/orders/#{id}", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Update order
+      #
+      # @see https://developer.paypal.com/docs/api/orders/v2/#orders_patch
+      #
+      # @param id [String] Order ID
+      # @macro request
+      #
+      def update(id, query: nil, body: nil, headers: nil)
+        client.patch("/v2/checkout/orders/#{id}", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Confirm the Order
+      #
+      # @see https://developer.paypal.com/docs/api/orders/v2/#orders_confirm
+      #
+      # @param id [String] Order ID
+      # @macro request
+      #
+      def confirm(id, query: nil, body: nil, headers: nil)
+        client.post("/v2/checkout/orders/#{id}/confirm-payment-source", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Authorize payment for order
+      #
+      # @see https://developer.paypal.com/docs/api/orders/v2/#orders_authorize
+      #
+      # @param id [String] Order ID
+      # @macro request
+      #
+      def authorize(id, query: nil, body: nil, headers: nil)
+        client.post("/v2/checkout/orders/#{id}/authorize", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Capture payment for order
+      #
+      # @see https://developer.paypal.com/docs/api/orders/v2/#orders_capture
+      #
+      # @param id [String] Order ID
+      # @macro request
+      #
+      def capture(id, query: nil, body: nil, headers: nil)
+        client.post("/v2/checkout/orders/#{id}/capture", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Add tracking information for an Order
+      #
+      # @see https://developer.paypal.com/docs/api/orders/v2/#orders_track_create
+      #
+      # @param id [String] Order ID
+      # @macro request
+      #
+      def track(id, query: nil, body: nil, headers: nil)
+        client.post("/v2/checkout/orders/#{id}/track", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Update or cancel tracking information for a PayPal order
+      #
+      # @see https://developer.paypal.com/docs/api/orders/v2/#orders_trackers_patch
+      #
+      # @param id [String] Order ID
+      # @param tracker_id [String] Tracker ID
+      # @macro request
+      #
+      def update_tracker(id, tracker_id, query: nil, body: nil, headers: nil)
+        client.patch("/v2/checkout/orders/#{id}/trackers/#{tracker_id}", query: query, body: body, headers: headers)
+      end
+    end
+
+    include APIs
+    extend APIs
+  end
+end

data/lib/paypal-api/api_collections/refunds.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module PaypalAPI
+  #
+  # Refunds APIs `/v2/payments/refunds`
+  #
+  # @see https://developer.paypal.com/docs/api/payments/v2
+  #
+  class Refunds < APICollection
+    #
+    # Common class and instance methods
+    #
+    module APIs
+      #
+      # Show refund details
+      #
+      # @see https://developer.paypal.com/docs/api/payments/v2/#refunds_get
+      #
+      # @param refund_id [String]
+      # @macro request
+      #
+      def show(refund_id, query: nil, body: nil, headers: nil)
+        client.get("/v2/payments/refunds/#{refund_id}", query: query, body: body, headers: headers)
+      end
+    end
+
+    include APIs
+    extend APIs
+  end
+end

data/lib/paypal-api/api_collections/shipment_tracking.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module PaypalAPI
+  #
+  # Manages tracking information
+  #
+  # @see https://developer.paypal.com/docs/api/tracking/v1/
+  #
+  class ShipmentTracking < APICollection
+    #
+    # Common class and instance methods
+    #
+    module APIs
+      # @!macro [new] request
+      #   @param query [Hash, nil] Request query parameters
+      #   @param body [Hash, nil] Request body parameters
+      #   @param headers [Hash, nil] Request headers
+      #   @return [Response] Response object
+
+      #
+      # Add tracking information for multiple PayPal transactions
+      #
+      # @see https://developer.paypal.com/docs/api/tracking/v1/#trackers-batch_post
+      #
+      # @macro request
+      #
+      def add(query: nil, body: nil, headers: nil)
+        client.post("/v1/shipping/trackers-batch", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Update or cancel tracking information for PayPal transaction
+      #
+      # @see https://developer.paypal.com/docs/api/tracking/v1/#trackers_put
+      #
+      # @param id [String] Tracker ID
+      # @macro request
+      #
+      def update(id, query: nil, body: nil, headers: nil)
+        client.put("/v1/shipping/trackers/#{id}", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Shows tracking information, by tracker ID, for a PayPal transaction.
+      #
+      # @see https://developer.paypal.com/docs/api/tracking/v1/#trackers_get
+      #
+      # @param id [String] Order ID
+      # @macro request
+      #
+      def show(id, query: nil, body: nil, headers: nil)
+        client.get("/v1/shipping/trackers/#{id}", query: query, body: body, headers: headers)
+      end
+    end
+
+    include APIs
+    extend APIs
+  end
+end