paypal-rest-api 0.0.3 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9dac5031d1b2e2fe6f58b269801cd0e818280d4ed9b54fafc948e1b758d99b87
-  data.tar.gz: 4992abcc8678eca0bbc31702d49e6d6a596f7e614f3e8d6966a5716004adde26
+  metadata.gz: 161078b6b9ff7513fe6634bc4e37c181374858dec0cac4261d5cc662d115787c
+  data.tar.gz: 60346804bbd8a930f695a922a6ce07adaefca26e25f7777e70de0d9f5d87a01a
 SHA512:
-  metadata.gz: 63cc5c666b4483eb92bd6d5282173cb2841b517eb39762421c5c546b23d4c2b1e44fe689495aa75dca15f1a86ac66064e9db7fa77d4d389deb1f0e370de107aa
-  data.tar.gz: 2e0e52e4fb9e324017f2af0fefe410daab14b01a3f7b322a686c00fb64ca8c1987bec7ece18958eb0c85327bb25f5f20e5fefdb5111043023efa29a049c8a893
+  metadata.gz: e340f1e223aa903aed6fde693f4a16dc9cdf0ef3d474a633e171b7890eb016d8c42ef593117385419bd07c366bb257bbc0adbbcab8b193cb150523cd3dcaee46
+  data.tar.gz: 74f017ec1aabca6d9a55599bacc32ee7d7d2c425ec109ec076d2f8072819d95047a07d763ed7b5ba0bd4b96a3b91a3aa3b2404d1a0602c2704028661b544a18b

data/README.md

@@ -8,73 +8,63 @@ bundle add paypal-rest-api
 
 ## Features
 
+- Supported Ruby 2.6 - current Head
 - No dependencies;
 - Automatic authorization & reauthorization;
 - Auto-retries (configured);
 - Automatically added Paypal-Request-Id header for idempotent requests if not
   provided;
+- Webhooks Offline verification (needs to download certificate once)
+- Custom callbacks before/after request
 
 ## Usage
 
-- 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.
-- Failed request error (for non `2**` status codes) contains HTTP request and
-  response
-- Failed request error (for network errors) contains request and original error
+There are two options:
+
+- Setting global client
+- Setting local client (for possibility to use multiple PayPal environments)
+
+### Setting global client
 
 ```ruby
-# Initiate client
-client = PaypalAPI::Client.new(
+# in config/initializers/paypal_rest_api.rb
+PaypalAPI.client = PaypalAPI::Client.new(
   client_id: ENV['PAYPAL_CLIENT_ID'],
   client_secret: ENV['PAYPAL_CLIENT_SECRET'],
   live: false
 )
 
-# Usage example:
-response = client.orders.create(body: body)
-response = client.orders.show(order_id)
-response = client.authorized_payments.capture(authorization_id, headers: headers)
-response = client.webhooks.list(query: query)
-
-# 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)
-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. 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
-response.http_body # original response string
-response.http_status # Integer http status
-response.http_headers # Hash with response headers (keys are strings)
-response.requested_at # Time when request was sent
+# in your business logic
+response = PaypalAPI::Orders.show(order_id)
+response = PaypalAPI::Orders.create(body: body)
 ```
 
-Also PaypalAPI client can be added globally and class methods can be used instead:
+### Setting local client
 
 ```ruby
-# in config/initializers/paypal_api.rb
-PaypalAPI.client = PaypalAPI::Client.new(
+# in your business logic
+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)
-response = PaypalAPI.webhooks.verify(body: body)
+response = client.orders.show(order_id)
+response = client.orders.create(body: body)
+```
 
-# same
-PaypalAPI::Orders.create(body: body)
-PaypalAPI::Webhooks.verify(body: body)
+### Client REST methods
+
+Client can call HTTP methods directly:
+
+```ruby
+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)
+response = client.put(path, query: query, body: body, headers: headers)
+response = client.delete(path, query: query, body: body, headers: headers)
 
-# Also now PaypalAPI class can be used as a client
+# Or, after setting global client:
 response = PaypalAPI.post(path, query: query, body: body, headers: headers)
 response = PaypalAPI.get(path, query: query, body: body, headers: headers)
 response = PaypalAPI.patch(path, query: query, body: body, headers: headers)
@@ -82,6 +72,23 @@ response = PaypalAPI.put(path, query: query, body: body, headers: headers)
 response = PaypalAPI.delete(path, query: query, body: body, headers: headers)
 ```
 
+### Parsing response
+
+`response.body` is a main method that returns parsed JSON respoonse as a Hash.
+
+There are also many others helpful methods:
+
+```ruby
+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
+response.http_body # original response string
+response.http_status # Integer http status
+response.http_headers # Hash with response headers (keys are strings)
+response.request # Request that generates this response
+```
+
 ## Configuration options
 
 PaypalAPI client accepts this additional options: `:live`, `:retries`, `:http_opts`
@@ -132,6 +139,108 @@ client = PaypalAPI::Client.new(
 )
 ```
 
+## Webhoooks verification
+
+Webhooks can be verified [offline](https://developer.paypal.com/api/rest/webhooks/rest/#link-selfverificationmethod)
+or [online](https://developer.paypal.com/api/rest/webhooks/rest/#link-postbackmethod).
+Method `PaypalAPI.verify_webhook(webhook_id:, headers:, raw_body:)`
+verifies webhook. It to verify webhook OFFLINE and it fallbacks
+to ONLINE if offline verification returns false to be sure you don't miss a
+valid webhook.
+
+When some required header is missing it will raise
+`PaypalAPI::WebhooksVerifier::MissingHeader` error.
+
+Example of Rails controller with webhook verification:
+
+```ruby
+class Webhooks::PaypalController < ApplicationController
+  def create
+    # PayPal registered webhook ID for current URL
+    webhook_id = ENV['PAYPAL_WEBHOOK_ID']
+    headers = request.headers # must be a Hash
+    raw_body = request.raw_post # must be a raw String body
+
+    webhook_is_valid = PaypalAPI.verify_webhook(
+      webhook_id: webhook_id,
+      headers: headers,
+      raw_body: raw_body
+    )
+
+    if webhook_is_valid
+      handle_valid_webhook_event(body)
+    else
+      handle_invalid_webhook_event(webhook_id, headers, body)
+    end
+
+    head :no_content
+  end
+end
+```
+
+## Callbacks
+
+Callbacks list:
+
+- `:before` - Runs before request
+- `:after_success` - Runs after getting successful response
+- `:after_fail` - Runs after getting failed response (non-2xx) status code
+- `:after_network_error` - Runs after getting network error
+
+Callbacks are registered on `client` object.
+
+Each callback receive `request` and `context` variables.
+`context` can be modified manually to save state between callbacks.
+
+`:after_success` and `:after_fail` callbacks have additional `response` argument
+
+`:after_network_error` callback has additional `error` argument
+
+```ruby
+PaypalAPI.client.add_callback(:before) do |request, context|
+  context[:request_id] = SecureRandom.hex(3)
+  context[:starts_at] = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+end
+
+PaypalAPI.client.add_callback(:after) do |request, context, response|
+  ends_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  duration = ends_at - context[:starts_at]
+
+  SomeLogger.debug(
+    'PaypalAPI success request',
+    method: request.method,
+    uri: request.uri.to_s,
+    duration: duration
+  )
+end
+
+PaypalAPI.client.add_callback(:after_fail) do |request, context, response|
+  SomeLogger.error(
+    'PaypalAPI request failed',
+    method: request.method,
+    uri: request.uri.to_s,
+    response_status: response.http_status,
+    response_body: response.http_body,
+    will_retry: context[:will_retry],
+    retry_number: context[:retry_number],
+    retry_count: context[:retry_count]
+  )
+end
+
+PaypalAPI.client.add_callback(:after_network_error) do |request, context, error|
+  SomeLogger.error(
+    'PaypalAPI network connection error'
+    method: request.method,
+    uri: request.uri.to_s,
+    error: error.message,
+    paypal_request_id: request.headers['paypal-request-id'],
+    will_retry: context[:will_retry],
+    retry_number: context[:retry_number],
+    retry_count: context[:retry_count]
+  )
+end
+```
+
 ## Errors
 
 All APIs can raise error in case of network error or non-2xx response status code.
@@ -168,11 +277,12 @@ All errors have additional methods:
 
 ```ruby
 begin
-  response = PaypalAPI.payments.capture(authorization_id, body: body)
+  response = PaypalAPI.authorized_payments.capture(authorization_id, body: body)
 rescue PaypalAPI::Error => error
   YourLogger.error(
     error,
     context: {
+      paypal_request_id: error.paypal_request_id,
       error_name: error.error_name,
       error_message: error.error_message,
       error_debug_id: error.error_debug_id,
@@ -184,17 +294,183 @@ end
 
 ```
 
+## APIs
+
+All API endpoints accept this parameters:
+
+- `resource_id` - Resource ID (Unless `create`/`list` endpoint)
+- `query` - Hash with request query params
+- `body` - Hash with request body params
+- `headers` - Hash with request headers
+
+### Orders
+
+- `PaypalAPI::Orders.create`
+- `PaypalAPI::Orders.show`
+- `PaypalAPI::Orders.update`
+- `PaypalAPI::Orders.confirm`
+- `PaypalAPI::Orders.authorize`
+- `PaypalAPI::Orders.capture`
+- `PaypalAPI::Orders.track`
+- `PaypalAPI::Orders.update_tracker`
+
+### Payments
+
+- `PaypalAPI::AuthorizedPayment.show`
+- `PaypalAPI::AuthorizedPayment.capture`
+- `PaypalAPI::AuthorizedPayment.reauthorize`
+- `PaypalAPI::AuthorizedPayment.void`
+
+<!-- -->
+
+- `PaypalAPI::CapturedPayment.show`
+- `PaypalAPI::CapturedPayment.refund`
+
+<!-- -->
+
+- `PaypalAPI::Refunds.show`
+
+### Webhooks
+
+- `PaypalAPI::Webhooks.create`
+- `PaypalAPI::Webhooks.list`
+- `PaypalAPI::Webhooks.show`
+- `PaypalAPI::Webhooks.update`
+- `PaypalAPI::Webhooks.delete`
+- `PaypalAPI::Webhooks.event_types`
+- `PaypalAPI::Webhooks.verify`
+
+<!-- -->
+
+- `PaypalAPI::WebhookEvents.available`
+- `PaypalAPI::WebhookEvents.list`
+- `PaypalAPI::WebhookEvents.show`
+- `PaypalAPI::WebhookEvents.resend`
+- `PaypalAPI::WebhookEvents.simulate`
+
+<!-- -->
+
+- `PaypalAPI::WebhookLookups.create`
+- `PaypalAPI::WebhookLookups.list`
+- `PaypalAPI::WebhookLookups.show`
+- `PaypalAPI::WebhookLookups.delete`
+
+### Subscriptions
+
+- `PaypalAPI::Subscriptions.create`
+- `PaypalAPI::Subscriptions.show`
+- `PaypalAPI::Subscriptions.update`
+- `PaypalAPI::Subscriptions.revise`
+- `PaypalAPI::Subscriptions.suspend`
+- `PaypalAPI::Subscriptions.cancel`
+- `PaypalAPI::Subscriptions.activate`
+- `PaypalAPI::Subscriptions.capture`
+- `PaypalAPI::Subscriptions.transactions`
+
+<!-- -->
+
+- `PaypalAPI::SubscriptionPlans.create`
+- `PaypalAPI::SubscriptionPlans.list`
+- `PaypalAPI::SubscriptionPlans.show`
+- `PaypalAPI::SubscriptionPlans.update`
+- `PaypalAPI::SubscriptionPlans.activate`
+- `PaypalAPI::SubscriptionPlans.deactivate`
+- `PaypalAPI::SubscriptionPlans.update_pricing`
+
+### Shipment Tracking
+
+- `PaypalAPI::ShipmentTracking.add`
+- `PaypalAPI::ShipmentTracking.update`
+- `PaypalAPI::ShipmentTracking.show`
+
+### Catalog Products
+
+- `PaypalAPI::CatalogProducts.create`
+- `PaypalAPI::CatalogProducts.list`
+- `PaypalAPI::CatalogProducts.show`
+- `PaypalAPI::CatalogProducts.update`
+
+### Disputes
+
+- `PaypalAPI::Disputes.appeal`
+- `PaypalAPI::Disputes.make_offer`
+- `PaypalAPI::Disputes.show`
+- `PaypalAPI::Disputes.update`
+- `PaypalAPI::Disputes.send_message`
+- `PaypalAPI::Disputes.provide_supporting_info`
+- `PaypalAPI::Disputes.update_status`
+- `PaypalAPI::Disputes.deny_offer`
+- `PaypalAPI::Disputes.provide_evidence`
+- `PaypalAPI::Disputes.settle`
+- `PaypalAPI::Disputes.acknowledge_return_item`
+- `PaypalAPI::Disputes.accept_claim`
+- `PaypalAPI::Disputes.list`
+- `PaypalAPI::Disputes.escalate`
+- `PaypalAPI::Disputes.accept_offer`
+
+### UserInfo
+
+- `PaypalAPI::UserInfo.show`
+
+### Users
+
+- `PaypalAPI::Users.create`
+- `PaypalAPI::Users.list`
+- `PaypalAPI::Users.show`
+- `PaypalAPI::Users.update`
+- `PaypalAPI::Users.delete`
+
+### Invoices
+
+- `PaypalAPI::Invoices.create`
+- `PaypalAPI::Invoices.list`
+- `PaypalAPI::Invoices.show`
+- `PaypalAPI::Invoices.update`
+- `PaypalAPI::Invoices.delete`
+- `PaypalAPI::Invoices.search`
+- `PaypalAPI::Invoices.remind`
+- `PaypalAPI::Invoices.delete_refund`
+- `PaypalAPI::Invoices.delete_payment`
+- `PaypalAPI::Invoices.record_refund`
+- `PaypalAPI::Invoices.record_payment`
+- `PaypalAPI::Invoices.send_invoice`
+- `PaypalAPI::Invoices.cancel`
+- `PaypalAPI::Invoices.generate_qr_code`
+- `PaypalAPI::Invoices.generate_invoice_number`
+
+### InvoiceTemplates
+
+- `PaypalAPI::InvoiceTemplates.create`
+- `PaypalAPI::InvoiceTemplates.list`
+- `PaypalAPI::InvoiceTemplates.show`
+- `PaypalAPI::InvoiceTemplates.update`
+- `PaypalAPI::InvoiceTemplates.delete`
+
+### Payouts
+
+- `PaypalAPI::Payouts.create`
+- `PaypalAPI::Payouts.show`
+- `PaypalAPI::PayoutItems.show`
+- `PaypalAPI::PayoutItems.cancel`
+
+### ReferencedPayouts
+
+- `PaypalAPI::ReferencedPayouts.create`
+- `PaypalAPI::ReferencedPayouts.show`
+- `PaypalAPI::ReferencedPayoutItems.create`
+- `PaypalAPI::ReferencedPayoutItems.show`
+
 ## Development
 
 ```bash
-  bundle install
   rubocop
   rspec
+  mdl README.md CHANGELOG.md RELEASE.md
 ```
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at <https://github.com/aglushkov/paypal-api>.
+Bug reports and pull requests are welcome on GitHub at <https://github.com/aglushkov/paypal-rest-api>.
 
 ## License
 

data/VERSION

@@ -1 +1 @@
-0.0.3
+0.1.0

data/lib/paypal-api/access_token.rb

@@ -4,8 +4,20 @@ module PaypalAPI
   #
   # AccessToken object stores authorization string and its expire time.
   #
+  # @api private
+  #
   class AccessToken
-    attr_reader :requested_at, :expires_at, :authorization_string
+    # Time when access token request was sent
+    # @return [Time] Time
+    attr_reader :requested_at
+
+    # Time when access token request expires
+    # @return [Time] Time
+    attr_reader :expires_at
+
+    # Authorization string
+    # @return [String] Authorization string
+    attr_reader :authorization_string
 
     #
     # Initializes AccessToken object
@@ -32,7 +44,9 @@ module PaypalAPI
     end
 
     #
-    # Instance representation string. Default was overwritten to hide original access_token
+    # Instance representation string
+    #
+    # @return [String] Inspect value
     #
     def inspect
       "#<#{self.class.name} methods: (requested_at, expires_at, expired?, authorization_string)>"

data/lib/paypal-api/api_collection.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "uri"
+
 module PaypalAPI
   #
   # Base class for all PayPal API collections classes
@@ -22,5 +24,32 @@ module PaypalAPI
     def self.client
       PaypalAPI.client
     end
+
+    # Encodes URI component
+    # @param id [String] Unencoded URI component
+    # @return [String] Encoded URI component
+    def encode(id)
+      self.class.encode(id)
+    end
+
+    # :nocov:
+    if URI.respond_to?(:encode_uri_component)
+      # Encodes URI component
+      # @param id [String] Unencoded URI component
+      # @return [String] Encoded URI component
+      def self.encode(id)
+        URI.encode_uri_component(id)
+      end
+    else
+      # Encodes URI component
+      # @param id [String] Unencoded URI component
+      # @return [String] Encoded URI component
+      def self.encode(id)
+        encoded_id = URI.encode_www_form_component(id)
+        encoded_id.gsub!("+", "%20")
+        encoded_id
+      end
+    end
+    # :nocov:
   end
 end

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

@@ -26,7 +26,7 @@ module PaypalAPI
       # @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)
+        client.get("/v2/payments/authorizations/#{encode(authorization_id)}", query: query, body: body, headers: headers)
       end
 
       #
@@ -38,7 +38,7 @@ module PaypalAPI
       # @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)
+        client.post("/v2/payments/authorizations/#{encode(authorization_id)}/capture", query: query, body: body, headers: headers)
       end
 
       # Reauthorize authorized payment
@@ -49,7 +49,7 @@ module PaypalAPI
       # @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)
+        client.post("/v2/payments/authorizations/#{encode(authorization_id)}/reauthorize", query: query, body: body, headers: headers)
       end
 
       # Void authorized payment
@@ -60,7 +60,7 @@ module PaypalAPI
       # @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)
+        client.post("/v2/payments/authorizations/#{encode(authorization_id)}/void", query: query, body: body, headers: headers)
       end
     end
 

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

@@ -26,7 +26,7 @@ module PaypalAPI
       # @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)
+        client.get("/v2/payments/captures/#{encode(capture_id)}", query: query, body: body, headers: headers)
       end
 
       #
@@ -38,7 +38,7 @@ module PaypalAPI
       # @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)
+        client.post("/v2/payments/captures/#{encode(capture_id)}/refund", query: query, body: body, headers: headers)
       end
     end
 

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

@@ -48,7 +48,7 @@ module PaypalAPI
       # @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)
+        client.get("/v1/catalogs/products/#{encode(product_id)}", query: query, body: body, headers: headers)
       end
 
       #
@@ -60,7 +60,7 @@ module PaypalAPI
       # @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)
+        client.patch("/v1/catalogs/products/#{encode(product_id)}", query: query, body: body, headers: headers)
       end
     end