paypal-rest-api 0.3.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb41159069ce06e4af428ec51fd553c176383626ac51eae019484f7bf65d22c8
-  data.tar.gz: 6c91629dd7dc266198642ae2ed4606c764cf8e376a39695fb7fbdf5ebfd22e28
+  metadata.gz: dbd16b786c08d41262b404eb893480c37dbd1b4084dcb4f26a5d7f849d187970
+  data.tar.gz: 720a713a163ca01db1e414149673f416e484616d2e86442eb75ac0d17a29620a
 SHA512:
-  metadata.gz: 4dfa83c73dbf06ac3badf8151241baa837a075f17bbe40927b8b1280bbff3867bdf8da3b4ed2e4b4126530767019aabf82899941edc0efeccdca42eba7d597e5
-  data.tar.gz: '08df1fc1d94b9c395e684a366aed64c50f94a2e357ee1d0ddb0894ba2bd5db7a2a8513799caa6138c87784fe1932f7bbcd8028f0c679e843fa9f0cfbe9b97f69'
+  metadata.gz: d7d63364e602fe0ae3840fefcf68efbd4432243fb337ef8c4a42ec45d8e3744565456696b8f06d04c426520d25c27dd21a0447df9e6ff7017d4c6556453ca568
+  data.tar.gz: 02ebf31571711bb7a0a347b38d8c0c6c116d6ec2bb135912a6ed1da7cc499a469f2cabb3ccd0c9317dbad520e101eabdc3006422fa3498e9df7bb518cc537e8b

data/README.md

@@ -1,3 +1,8 @@
+[![Gem Version](https://badge.fury.io/rb/paypal-rest-api.svg)](https://badge.fury.io/rb/paypal-rest-api)
+[![GitHub Actions](https://github.com/aglushkov/paypal-rest-api/actions/workflows/main.yml/badge.svg?event=push)](https://github.com/aglushkov/paypal-rest-api/actions/workflows/main.yml)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/11efd530f1df171dac2b/test_coverage)](https://codeclimate.com/github/aglushkov/paypal-rest-api/test_coverage)
+[![Maintainability](https://api.codeclimate.com/v1/badges/11efd530f1df171dac2b/maintainability)](https://codeclimate.com/github/aglushkov/paypal-rest-api/maintainability)
+
 # PaypalAPI
 
 ## Installation
@@ -10,12 +15,13 @@ bundle add paypal-rest-api
 
 - Supported Ruby Versions - *(2.6 .. 3.3), head, jruby-9.4, truffleruby-24*
 - No dependencies;
-- Automatic authorization & reauthorization;
+- Automatic authorization & re-authorization;
 - 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
+- Automatic pagination methods
 
 ## Usage
 
@@ -39,7 +45,7 @@ PaypalAPI.live? # => false
 PaypalAPI.api_url # => "https://api-m.sandbox.paypal.com"
 PaypalAPI.web_url # => "https://sandbox.paypal.com"
 
-response = between redeploys::Orders.show(order_id)
+response = PaypalAPI::Orders.show(order_id)
 response = PaypalAPI::Orders.create(body: body)
 ```
 
@@ -80,22 +86,42 @@ response = PaypalAPI.put(path, query: query, body: body, headers: headers)
 response = PaypalAPI.delete(path, query: query, body: body, headers: headers)
 ```
 
-### Parsing response
+### Response
 
-`response.body` is a main method that returns parsed JSON respoonse as a Hash.
+`Response` object is returned after each `API` request.
 
-There are also many others helpful methods:
+#### Original HTTP response data
 
-```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
-```
+- `response.http_status` - response HTTP status as Integer
+- `response.http_body` - response body as String
+- `response.http_headers` - response headers as Hash with String keys
+- `response.http_response` - original Net::HTTP::Response object
+- `response.request` - Request object that was used to get this response
+
+#### Parsed JSON body methods
+
+- `response.body` - parsed JSON body, keys are Symbols
+- `response[:field]` - gets `:field` attribute from parsed body,
+  returns nil if response have no such key
+- `response.fetch(:field)` - gets `:field` attribute from parsed body,
+  raises KeyError if response has no such key
+
+#### Error check methods
+
+- `response.success?` - checks HTTP status code is 2xx
+- `response.failed?` - checks HTTP status code is not 2xx
+
+#### Using HATEOAS links
+
+- `response.follow_up_link('approve', query: nil, body: nil, headers: nil)` -
+  Finds HATEOAS link is response with `rel=approve` and requests it. Returns
+  `nil` if no such link were found.
+
+#### Pagination (see [Automatic Pagination][automatic_pagination] for examples)
+
+- `response.each_page { |response| ... }` - iterates over each page in response
+- `response.each_page_item(items_field) { |item| ... }` - iterates over each
+  page item
 
 ## Configuration options
 
@@ -130,7 +156,7 @@ Retries happen on any network error, on 409, 429, 5xx response status code.
 
 ```ruby
 client = PaypalAPI::Client.new(
-  retries: {count: 2, sleep: [0, 0]}
+  retries: {enabled: !Rails.env.test?, count: 5, sleep: [0, 0.25, 0.75, 1.5, 2]}
   # ...
 )
 ```
@@ -168,6 +194,28 @@ client = PaypalAPI::Client.new(
 )
 ```
 
+## Automatic pagination
+
+PayPal provides HATEOAS links in responses. This links can contain items with
+`rel=next` attribute. We request next pages using this links.
+
+We have two specific methods:
+
+- `Response#each_page` - iterates over each page `Response` object
+- `Response#each_page_item(items_field_name)` - iterates over items on each page
+
+Example:
+
+```ruby
+  PaypalAPI::WebhookEvents.list(page_size: 25).each_page do |response|
+    # ...
+  end
+
+  PaypalAPI::WebhookEvents.list(page_size: 25).each_page_item(:events) do |hash|
+    # ...
+  end
+```
+
 ## Webhoooks verification
 
 Webhooks can be verified [offline](https://developer.paypal.com/api/rest/webhooks/rest/#link-selfverificationmethod)
@@ -351,6 +399,18 @@ All API endpoints accept this parameters:
 - `PaypalAPI::Orders.track`
 - `PaypalAPI::Orders.update_tracker`
 
+### Payment Tokens
+
+- `PaypalAPI::PaymentTokens.create`
+- `PaypalAPI::PaymentTokens.list`
+- `PaypalAPI::PaymentTokens.show`
+- `PaypalAPI::PaymentTokens.delete`
+
+<!-- -->
+
+- `PaypalAPI::SetupTokens.create`
+- `PaypalAPI::SetupTokens.show`
+
 ### Payments
 
 - `PaypalAPI::AuthorizedPayments.show`
@@ -497,6 +557,25 @@ All API endpoints accept this parameters:
 - `PaypalAPI::ReferencedPayoutItems.create`
 - `PaypalAPI::ReferencedPayoutItems.show`
 
+### PartnerReferrals
+
+- `PaypalAPI::PartnerReferrals.create`
+- `PaypalAPI::PartnerReferrals.show`
+
+### PaymentExperienceWebProfiles
+
+- `PaypalAPI::PaymentExperienceWebProfiles.create`
+- `PaypalAPI::PaymentExperienceWebProfiles.list`
+- `PaypalAPI::PaymentExperienceWebProfiles.show`
+- `PaypalAPI::PaymentExperienceWebProfiles.replace`
+- `PaypalAPI::PaymentExperienceWebProfiles.update`
+- `PaypalAPI::PaymentExperienceWebProfiles.delete`
+
+### TransactionSearch
+
+- `PaypalAPI::TransactionSearch.list_transactions`
+- `PaypalAPI::TransactionSearch.list_all_balances`
+
 ## Development
 
 ```bash
@@ -512,3 +591,5 @@ Bug reports and pull requests are welcome on GitHub at <https://github.com/aglus
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+[automatic_pagination]: #automatic-pagination

data/VERSION

@@ -1 +1 @@
-0.3.1
+0.5.0

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

@@ -13,7 +13,7 @@ module PaypalAPI
     PATH = "/v1/oauth2/token"
 
     #
-    # Common class and instance methods
+    # Common methods for PayplaAPI::Authentication class and client.authentication instance
     #
     module APIs
       #

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

@@ -8,7 +8,7 @@ module PaypalAPI
   #
   class AuthorizedPayments < APICollection
     #
-    # Common class and instance methods
+    # Common methods for PayplaAPI::AuthorizedPayments class and client.authorized_payments instance
     #
     module APIs
       # @!macro [new] request

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

@@ -8,7 +8,7 @@ module PaypalAPI
   #
   class CapturedPayments < APICollection
     #
-    # Common class and instance methods
+    # Common methods for PaypalAPI::CapturedPayments class and client.captured_payments instance
     #
     module APIs
       # @!macro [new] request

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

@@ -8,7 +8,7 @@ module PaypalAPI
   #
   class CatalogProducts < APICollection
     #
-    # Common class and instance methods
+    # Common methods for PaypalAPI::CatalogProducts class and client.catalog_products instance
     #
     module APIs
       # @!macro [new] request

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

@@ -8,7 +8,7 @@ module PaypalAPI
   #
   class Disputes < APICollection
     #
-    # Common class and instance methods
+    # Common methods for PaypalAPI::Disputes class and client.disputes instance
     #
     module APIs
       # @!macro [new] request

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

@@ -8,7 +8,7 @@ module PaypalAPI
   #
   class InvoiceTemplates < APICollection
     #
-    # Common class and instance methods
+    # Common methods for PaypalAPI::InvoiceTemplates class and client.invoice_templates instance
     #
     module APIs
       # @!macro [new] request

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

@@ -8,7 +8,7 @@ module PaypalAPI
   #
   class Invoices < APICollection
     #
-    # Common class and instance methods
+    # Common methods for PaypalAPI::Invoices class and client.invoices instance
     #
     module APIs
       # @!macro [new] request

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

@@ -8,7 +8,7 @@ module PaypalAPI
   #
   class Orders < APICollection
     #
-    # Common class and instance methods
+    # Common methods for PaypalAPI::Orders class and client.orders instance
     #
     module APIs
       # @!macro [new] request

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module PaypalAPI
+  #
+  # Use the Partner Referrals API to add PayPal seller accounts to PayPal
+  # Complete Payments Platform for Marketplaces and Platforms.
+  #
+  # @see https://developer.paypal.com/docs/api/partner-referrals/v2/
+  #
+  class PartnerReferrals < APICollection
+    #
+    # Common methods for PaypalAPI::PartnerReferrals class and client.partner_referrals instance
+    #
+    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 partner referral
+      #
+      # @see https://developer.paypal.com/docs/api/partner-referrals/v2/#partner-referrals_create
+      #
+      # @macro request
+      #
+      def create(query: nil, body: nil, headers: nil)
+        client.post("/v2/customer/partner-referrals", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Show referral data
+      #
+      # @see https://developer.paypal.com/docs/api/partner-referrals/v2/#partner-referrals_read
+      #
+      # @param id [String] The ID of the partner-referrals data for which to show details
+      # @macro request
+      #
+      def show(partner_referral_id, query: nil, body: nil, headers: nil)
+        client.get("/v2/customer/partner-referrals/#{encode(partner_referral_id)}", query: query, body: body, headers: headers)
+      end
+    end
+
+    include APIs
+    extend APIs
+  end
+end

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

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module PaypalAPI
+  #
+  # Use the Payment Experience API to create seamless payment experience profiles.
+  #
+  # @see https://developer.paypal.com/docs/api/orders/v2/
+  #
+  class PaymentExperienceWebProfiles < APICollection
+    #
+    # Common methods for PaypalAPI::PaymentExperienceWebProfiles class and client.orders instance
+    #
+    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 web experience profile
+      #
+      # @see https://developer.paypal.com/docs/api/payment-experience/v1/#web-profile_create
+      #
+      # @macro request
+      #
+      def create(query: nil, body: nil, headers: nil)
+        client.post("/v1/payment-experience/web-profiles", query: query, body: body, headers: headers)
+      end
+
+      #
+      # List web experience profiles
+      #
+      # @see https://developer.paypal.com/docs/api/payment-experience/v1/#web-profile_get-list
+      #
+      # @macro request
+      #
+      def list(query: nil, body: nil, headers: nil)
+        client.get("/v1/payment-experience/web-profiles", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Show web experience profile details by ID
+      #
+      # @see https://developer.paypal.com/docs/api/payment-experience/v1/#web-profile_get
+      #
+      # @param id [String] The ID of the profile for which to show details.
+      # @macro request
+      #
+      def show(id, query: nil, body: nil, headers: nil)
+        client.get("/v1/payment-experience/web-profiles/#{encode(id)}", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Replace web experience profile
+      #
+      # @see https://developer.paypal.com/docs/api/payment-experience/v1/#web-profile_update
+      #
+      # @param id [String] The ID of the profile to replace.
+      # @macro request
+      #
+      def replace(id, query: nil, body: nil, headers: nil)
+        client.put("/v1/payment-experience/web-profiles/#{encode(id)}", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Partially update web experience profile
+      #
+      # @see https://developer.paypal.com/docs/api/payment-experience/v1/#web-profile_partial-update
+      #
+      # @param id [String] The ID of the profile to update.
+      # @macro request
+      #
+      def update(id, query: nil, body: nil, headers: nil)
+        client.patch("/v1/payment-experience/web-profiles/#{encode(id)}", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Delete web experience profile
+      #
+      # @see https://developer.paypal.com/docs/api/payment-experience/v1/#web-profile_delete
+      #
+      # @param id [String] The ID of the profile to delete.
+      # @macro request
+      #
+      def delete(id, query: nil, body: nil, headers: nil)
+        client.delete("/v1/payment-experience/web-profiles/#{encode(id)}", query: query, body: body, headers: headers)
+      end
+    end
+
+    include APIs
+    extend APIs
+  end
+end

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

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module PaypalAPI
+  #
+  # Payment Method Tokens
+  #
+  # @see https://developer.paypal.com/docs/api/payment-tokens/v3/
+  #
+  class PaymentTokens < APICollection
+    #
+    # Common methods for PaypalAPI::PaymentTokens class and client.payment_tokens instance
+    #
+    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 payment token for a given payment source
+      #
+      # @see https://developer.paypal.com/docs/api/payment-tokens/v3/#payment-tokens_create
+      #
+      # @macro request
+      #
+      def create(query: nil, body: nil, headers: nil)
+        client.post("/v3/vault/payment-tokens", query: query, body: body, headers: headers)
+      end
+
+      #
+      # List all payment tokens
+      #
+      # @see https://developer.paypal.com/docs/api/payment-tokens/v3/#customer_payment-tokens_get
+      #
+      # @macro request
+      #
+      def list(query: nil, body: nil, headers: nil)
+        client.get("/v3/vault/payment-tokens", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Retrieve a payment token
+      #
+      # @see https://developer.paypal.com/docs/api/payment-tokens/v3/#payment-tokens_get
+      #
+      # @param id [String] ID of the payment token.
+      # @macro request
+      #
+      def show(id, query: nil, body: nil, headers: nil)
+        client.get("/v3/vault/payment-tokens/#{encode(id)}", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Delete payment token
+      #
+      # @see https://developer.paypal.com/docs/api/payment-tokens/v3/#payment-tokens_delete
+      #
+      # @param id [String] ID of the payment token
+      # @macro request
+      #
+      def delete(id, query: nil, body: nil, headers: nil)
+        client.delete("/v3/vault/payment-tokens/#{encode(id)}", query: query, body: body, headers: headers)
+      end
+    end
+
+    include APIs
+    extend APIs
+  end
+end

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

@@ -8,7 +8,7 @@ module PaypalAPI
   #
   class PayoutItems < APICollection
     #
-    # Common class and instance methods
+    # Common methods for PaypalAPI::PayoutItems class and client.payout_items instance
     #
     module APIs
       # @!macro [new] request

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

@@ -8,7 +8,7 @@ module PaypalAPI
   #
   class Payouts < APICollection
     #
-    # Common class and instance methods
+    # Common methods for PaypalAPI::Payouts class and client.payouts instance
     #
     module APIs
       # @!macro [new] request

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

@@ -4,11 +4,11 @@ module PaypalAPI
   #
   # Enables partner merchants and developers to process individual referenced payouts to recipients.
   #
-  # @seehttps://developer.paypal.com/docs/api/referenced-payouts/v1/
+  # @see https://developer.paypal.com/docs/api/referenced-payouts/v1/
   #
   class ReferencedPayoutItems < APICollection
     #
-    # Common class and instance methods
+    # Common methods for PaypalAPI::ReferencedPayoutItems class and client.referenced_payout_items instance
     #
     module APIs
       # @!macro [new] request

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

@@ -8,7 +8,7 @@ module PaypalAPI
   #
   class ReferencedPayouts < APICollection
     #
-    # Common class and instance methods
+    # Common methods for PaypalAPI::ReferencedPayouts class and client.referenced_payouts instance
     #
     module APIs
       # @!macro [new] request

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

@@ -8,7 +8,7 @@ module PaypalAPI
   #
   class Refunds < APICollection
     #
-    # Common class and instance methods
+    # Common methods for PaypalAPI::Refunds class and client.refunds instance
     #
     module APIs
       #

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module PaypalAPI
+  #
+  # Payment Setup Tokens
+  #
+  # @see https://developer.paypal.com/docs/api/payment-tokens/v3/
+  #
+  class SetupTokens < APICollection
+    #
+    # Common methods for PaypalAPI::SetupTokens class and client.setup_tokens instance
+    #
+    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 a setup token
+      #
+      # @see https://developer.paypal.com/docs/api/payment-tokens/v3/#setup-tokens_create
+      #
+      # @macro request
+      #
+      def create(query: nil, body: nil, headers: nil)
+        client.post("/v3/vault/setup-tokens", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Retrieve a setup token
+      #
+      # @see https://developer.paypal.com/docs/api/payment-tokens/v3/#setup-tokens_get
+      #
+      # @param id [String] ID of the setup token.
+      # @macro request
+      #
+      def show(id, query: nil, body: nil, headers: nil)
+        client.get("/v3/vault/setup-tokens/#{encode(id)}", query: query, body: body, headers: headers)
+      end
+    end
+
+    include APIs
+    extend APIs
+  end
+end

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

@@ -8,7 +8,7 @@ module PaypalAPI
   #
   class ShipmentTracking < APICollection
     #
-    # Common class and instance methods
+    # Common methods for PaypalAPI::ShipmentTracking class and client.shipment_tracking instance
     #
     module APIs
       # @!macro [new] request

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

@@ -8,7 +8,7 @@ module PaypalAPI
   #
   class SubscriptionPlans < APICollection
     #
-    # Common class and instance methods
+    # Common methods for PaypalAPI::SubscriptionPlans class and client.subscription_plans instance
     #
     module APIs
       # @!macro [new] request

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

@@ -8,7 +8,7 @@ module PaypalAPI
   #
   class Subscriptions < APICollection
     #
-    # Common class and instance methods
+    # Common methods for PaypalAPI::Subscriptions class and client.subscriptions instance
     #
     module APIs
       # @!macro [new] request

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module PaypalAPI
+  #
+  # Use the Transaction Search API to get the history of transactions for a PayPal account.
+  #
+  # @see https://developer.paypal.com/docs/api/transaction-search/v1/
+  #
+  class TransactionSearch < APICollection
+    #
+    # Common methods for PaypalAPI::TransactionSearch class and client.transaction_search instance
+    #
+    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
+
+      #
+      # List transactions
+      #
+      # @see https://developer.paypal.com/docs/api/transaction-search/v1/#search_get
+      #
+      # @macro request
+      #
+      def list_transactions(query: nil, body: nil, headers: nil)
+        client.get("/v1/reporting/transactions", query: query, body: body, headers: headers)
+      end
+
+      #
+      # List all balances
+      #
+      # @see https://developer.paypal.com/docs/api/transaction-search/v1/#balances_get
+      #
+      # @macro request
+      #
+      def list_all_balances(query: nil, body: nil, headers: nil)
+        client.get("/v1/reporting/balances", query: query, body: body, headers: headers)
+      end
+    end
+
+    include APIs
+    extend APIs
+  end
+end