paypal-rest-api 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '08b9e0e25c50df502751486cfeceb957be78e1951aa919faec3caf9550eec304'
-  data.tar.gz: 0d3894d681057c4721cf3e50a20308ad8e7a19ffb68d73ecab31ca9f112ed2c2
+  metadata.gz: dbd16b786c08d41262b404eb893480c37dbd1b4084dcb4f26a5d7f849d187970
+  data.tar.gz: 720a713a163ca01db1e414149673f416e484616d2e86442eb75ac0d17a29620a
 SHA512:
-  metadata.gz: 49e4bbea2d23037f3af274dddf8fc9c0652b55b06247bf8513531bf41ca925bfc768f9bfa9a98022f3783cf64022906dec19932d8cf2380ef5c4464cff1ba66e
-  data.tar.gz: b8e9d53bab01f8f31da162165191bbe8ecc00b06b9a342966a3400971811d6498c71b598e2f35e7269863d82abdcfa39b92dbcf7734eb6bb79545f52a11fbb48
+  metadata.gz: d7d63364e602fe0ae3840fefcf68efbd4432243fb337ef8c4a42ec45d8e3744565456696b8f06d04c426520d25c27dd21a0447df9e6ff7017d4c6556453ca568
+  data.tar.gz: 02ebf31571711bb7a0a347b38d8c0c6c116d6ec2bb135912a6ed1da7cc499a469f2cabb3ccd0c9317dbad520e101eabdc3006422fa3498e9df7bb518cc537e8b

data/README.md

@@ -15,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
 
@@ -44,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)
 ```
 
@@ -85,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
 
@@ -173,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)
@@ -514,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
@@ -529,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.4.0
+0.5.0

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/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

data/lib/paypal-api/client/access_token_methods.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module PaypalAPI
+  class Client
+    #
+    # Client methods to get access token
+    #
+    module AccessTokenMethods
+      #
+      # 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
+        requested_at = Time.now
+        response = authentication.generate_access_token
+
+        @access_token = AccessToken.new(
+          requested_at: requested_at,
+          expires_in: response.fetch(:expires_in),
+          access_token: response.fetch(:access_token),
+          token_type: response.fetch(:token_type)
+        )
+      end
+    end
+  end
+end

data/lib/paypal-api/client/api_methods.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module PaypalAPI
+  class Client
+    #
+    # Methods to access API collections
+    #
+    module APIMethods
+      # @return [AuthorizedPayments] AuthorizedPayments APIs collection
+      def authorized_payments
+        AuthorizedPayments.new(self)
+      end
+
+      # @return [CapturedPayments] CapturedPayments APIs collection
+      def captured_payments
+        CapturedPayments.new(self)
+      end
+
+      # @return [Authentication] Authentication APIs collection
+      def authentication
+        Authentication.new(self)
+      end
+
+      # @return [CatalogProducts] Catalog Products APIs collection
+      def catalog_products
+        CatalogProducts.new(self)
+      end
+
+      # @return [Disputes] Disputes APIs collection
+      def disputes
+        Disputes.new(self)
+      end
+
+      # @return [InvoiceTemplates] InvoiceTemplates APIs collection
+      def invoice_templates
+        InvoiceTemplates.new(self)
+      end
+
+      # @return [Invoices] Invoices APIs collection
+      def invoices
+        Invoices.new(self)
+      end
+
+      # @return [Orders] Orders APIs collection
+      def orders
+        Orders.new(self)
+      end
+
+      # @return [PartnerReferrals] PartnerReferrals APIs collection
+      def partner_referrals
+        PartnerReferrals.new(self)
+      end
+
+      # @return [PaymentExperienceWebProfiles] PaymentExperienceWebProfiles APIs collection
+      def payment_experience_web_profiles
+        PaymentExperienceWebProfiles.new(self)
+      end
+
+      # @return [PaymentTokens] PaymentTokens APIs collection
+      def payment_tokens
+        PaymentTokens.new(self)
+      end
+
+      # @return [PayoutItems] PayoutItems APIs collection
+      def payout_items
+        PayoutItems.new(self)
+      end
+
+      # @return [Payouts] Payouts APIs collection
+      def payouts
+        Payouts.new(self)
+      end
+
+      # @return [Refunds] Refunds APIs collection
+      def refunds
+        Refunds.new(self)
+      end
+
+      # @return [ReferencedPayoutItems] ReferencedPayoutItems APIs collection
+      def referenced_payout_items
+        ReferencedPayoutItems.new(self)
+      end
+
+      # @return [ReferencedPayouts] ReferencedPayouts APIs collection
+      def referenced_payouts
+        ReferencedPayouts.new(self)
+      end
+
+      # @return [SetupTokens] SetupTokens APIs collection
+      def setup_tokens
+        SetupTokens.new(self)
+      end
+
+      # @return [ShipmentTracking] Shipment Tracking APIs collection
+      def shipment_tracking
+        ShipmentTracking.new(self)
+      end
+
+      # @return [Subscriptions] Subscriptions APIs collection
+      def subscriptions
+        Subscriptions.new(self)
+      end
+
+      # @return [SubscriptionPlans] Subscription Plans APIs collection
+      def subscription_plans
+        SubscriptionPlans.new(self)
+      end
+
+      # @return [TransactionSearch] TransactionSearch APIs collection
+      def transaction_search
+        TransactionSearch.new(self)
+      end
+
+      # @return [UserInfo] User Info APIs collection
+      def user_info
+        UserInfo.new(self)
+      end
+
+      # @return [Users] Users Management APIs collection
+      def users
+        Users.new(self)
+      end
+
+      # @return [Webhooks] Webhooks APIs collection
+      def webhooks
+        Webhooks.new(self)
+      end
+
+      # @return [WebhookEvents] Webhook Events APIs collection
+      def webhook_lookups
+        WebhookLookups.new(self)
+      end
+
+      # @return [WebhookEvents] Webhook Lookups APIs collection
+      def webhook_events
+        WebhookEvents.new(self)
+      end
+    end
+  end
+end

data/lib/paypal-api/client/environment_methods.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module PaypalAPI
+  class Client
+    #
+    # Client environment specific methods
+    #
+    module EnvironmentMethods
+      # Checks if PayPal LIVE environment enabled
+      # @return [Boolean] Checks if PayPal LIVE environment enabled
+      def live?
+        env.live?
+      end
+
+      # Checks if PayPal SANDBOX environment enabled
+      # @return [Boolean] Checks if PayPal SANDBOX environment enabled
+      def sandbox?
+        env.sandbox?
+      end
+
+      # Base API URL
+      # @return [String] Base API URL
+      def api_url
+        env.api_url
+      end
+
+      # Base WEB URL
+      # @return [String] Base WEB URL
+      def web_url
+        env.web_url
+      end
+    end
+  end
+end

data/lib/paypal-api/client/http_methods.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module PaypalAPI
+  class Client
+    #
+    # Client HTTP methods
+    #
+    module HTTPMethods
+      # @!macro [new] 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
+
+      #
+      # Executes POST http request
+      #
+      # @macro request
+      #
+      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
+      #
+      # @macro request
+      #
+      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
+      #
+      # @macro request
+      #
+      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
+      #
+      # @macro request
+      #
+      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
+      #
+      # @macro request
+      #
+      def delete(path, query: nil, body: nil, headers: nil)
+        execute_request(Net::HTTP::Delete, path, query: query, body: body, headers: headers)
+      end
+
+      private
+
+      def execute_request(http_method, path, query: nil, body: nil, headers: nil)
+        request = Request.new(self, http_method, path, query: query, body: body, headers: headers)
+        RequestExecutor.new(self, request).call
+      end
+    end
+  end
+end

data/lib/paypal-api/client.rb

@@ -5,6 +5,11 @@ module PaypalAPI
   # PaypalAPI Client
   #
   class Client
+    include AccessTokenMethods
+    include APIMethods
+    include EnvironmentMethods
+    include HTTPMethods
+
     # Paypal environment
     attr_reader :env
 
@@ -43,30 +48,6 @@ module PaypalAPI
       @access_token = nil
     end
 
-    # Checks if PayPal LIVE environment enabled
-    # @return [Boolean] Checks if PayPal LIVE environment enabled
-    def live?
-      env.live?
-    end
-
-    # Checks if PayPal SANDBOX environment enabled
-    # @return [Boolean] Checks if PayPal SANDBOX environment enabled
-    def sandbox?
-      env.sandbox?
-    end
-
-    # Base API URL
-    # @return [String] Base API URL
-    def api_url
-      env.api_url
-    end
-
-    # Base WEB URL
-    # @return [String] Base WEB URL
-    def web_url
-      env.web_url
-    end
-
     # Registers callback
     #
     # @param callback_name [Symbol] Callback name.
@@ -90,32 +71,6 @@ module PaypalAPI
       callbacks.fetch(callback_name) << block
     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
-      requested_at = Time.now
-      response = authentication.generate_access_token
-
-      @access_token = AccessToken.new(
-        requested_at: requested_at,
-        expires_in: response.fetch(:expires_in),
-        access_token: response.fetch(:access_token),
-        token_type: response.fetch(:token_type)
-      )
-    end
-
     #
     # Verifies Webhook
     #
@@ -147,180 +102,5 @@ module PaypalAPI
     def verify_webhook(webhook_id:, headers:, raw_body:)
       WebhookVerifier.new(self).call(webhook_id: webhook_id, headers: headers, raw_body: raw_body)
     end
-
-    # @!macro [new] 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
-
-    #
-    # Executes POST http request
-    #
-    # @macro request
-    #
-    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
-    #
-    # @macro request
-    #
-    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
-    #
-    # @macro request
-    #
-    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
-    #
-    # @macro request
-    #
-    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
-    #
-    # @macro request
-    #
-    def delete(path, query: nil, body: nil, headers: nil)
-      execute_request(Net::HTTP::Delete, path, query: query, body: body, headers: headers)
-    end
-
-    # @return [AuthorizedPayments] AuthorizedPayments APIs collection
-    def authorized_payments
-      AuthorizedPayments.new(self)
-    end
-
-    # @return [CapturedPayments] CapturedPayments APIs collection
-    def captured_payments
-      CapturedPayments.new(self)
-    end
-
-    # @return [Authentication] Authentication APIs collection
-    def authentication
-      Authentication.new(self)
-    end
-
-    # @return [CatalogProducts] Catalog Products APIs collection
-    def catalog_products
-      CatalogProducts.new(self)
-    end
-
-    # @return [Disputes] Disputes APIs collection
-    def disputes
-      Disputes.new(self)
-    end
-
-    # @return [InvoiceTemplates] InvoiceTemplates APIs collection
-    def invoice_templates
-      InvoiceTemplates.new(self)
-    end
-
-    # @return [Invoices] Invoices APIs collection
-    def invoices
-      Invoices.new(self)
-    end
-
-    # @return [Orders] Orders APIs collection
-    def orders
-      Orders.new(self)
-    end
-
-    # @return [PaymentTokens] PaymentTokens APIs collection
-    def payment_tokens
-      PaymentTokens.new(self)
-    end
-
-    # @return [PayoutItems] PayoutItems APIs collection
-    def payout_items
-      PayoutItems.new(self)
-    end
-
-    # @return [Payouts] Payouts APIs collection
-    def payouts
-      Payouts.new(self)
-    end
-
-    # @return [Refunds] Refunds APIs collection
-    def refunds
-      Refunds.new(self)
-    end
-
-    # @return [ReferencedPayoutItems] ReferencedPayoutItems APIs collection
-    def referenced_payout_items
-      ReferencedPayoutItems.new(self)
-    end
-
-    # @return [ReferencedPayouts] ReferencedPayouts APIs collection
-    def referenced_payouts
-      ReferencedPayouts.new(self)
-    end
-
-    # @return [SetupTokens] SetupTokens APIs collection
-    def setup_tokens
-      SetupTokens.new(self)
-    end
-
-    # @return [ShipmentTracking] Shipment Tracking APIs collection
-    def shipment_tracking
-      ShipmentTracking.new(self)
-    end
-
-    # @return [Subscriptions] Subscriptions APIs collection
-    def subscriptions
-      Subscriptions.new(self)
-    end
-
-    # @return [SubscriptionPlans] Subscription Plans APIs collection
-    def subscription_plans
-      SubscriptionPlans.new(self)
-    end
-
-    # @return [UserInfo] User Info APIs collection
-    def user_info
-      UserInfo.new(self)
-    end
-
-    # @return [Users] Users Management APIs collection
-    def users
-      Users.new(self)
-    end
-
-    # @return [Webhooks] Webhooks APIs collection
-    def webhooks
-      Webhooks.new(self)
-    end
-
-    # @return [WebhookEvents] Webhook Events APIs collection
-    def webhook_lookups
-      WebhookLookups.new(self)
-    end
-
-    # @return [WebhookEvents] Webhook Lookups APIs collection
-    def webhook_events
-      WebhookEvents.new(self)
-    end
-
-    private
-
-    def execute_request(http_method, path, query: nil, body: nil, headers: nil)
-      request = Request.new(self, http_method, path, query: query, body: body, headers: headers)
-      RequestExecutor.new(self, request).call
-    end
   end
 end

data/lib/paypal-api/request.rb

@@ -99,7 +99,8 @@ module PaypalAPI
 
     def build_http_uri(path, query)
       uri = URI.join(client.env.api_url, path)
-      uri.query = URI.encode_www_form(query) if query && !query.empty?
+      add_query_params(uri, query)
+
       uri
     end
 
@@ -113,6 +114,20 @@ module PaypalAPI
       end
     end
 
+    def add_query_params(uri, query)
+      return if !query || query.empty?
+
+      # We should merge query params with uri query params to not temove them
+      uri_query_string = uri.query
+
+      if uri_query_string && !uri_query_string.empty?
+        old_query = URI.decode_www_form(uri_query_string).to_h
+        query = old_query.transform_keys!(&:to_sym).merge!(query.transform_keys(&:to_sym))
+      end
+
+      uri.query = URI.encode_www_form(query)
+    end
+
     #
     # We should set json content type header to not get 415 UnsupportedMediaType
     # error in various APIs

data/lib/paypal-api/request_executor.rb

@@ -30,31 +30,40 @@ module PaypalAPI
 
     private
 
-    def execute_request(retry_number: 0)
+    def start_execution(retry_number)
       callbacks_context[:retry_number] = retry_number
-
       run_callbacks(:before)
-      response = execute_net_http_request
-    rescue => error
-      raise error if NetworkErrorBuilder::ERRORS.none? { |network_error_class| error.is_a?(network_error_class) }
+      execute_net_http_request
+    end
 
+    def handle_network_error(error, retry_number)
       will_retry = retries[:enabled] && !retries_limit_reached?(retry_number)
       callbacks_context[:will_retry] = will_retry
       run_callbacks(:after_network_error, error)
       raise NetworkErrorBuilder.call(request: request, error: error) unless will_retry
 
       retry_request(retry_number)
+    end
+
+    def handle_success_response(response)
+      callbacks_context.delete(:will_retry)
+      run_callbacks(:after_success, response)
+      response
+    end
+
+    def handle_failed_response(response, retry_number)
+      will_retry = retries[:enabled] && retryable?(response, retry_number)
+      callbacks_context[:will_retry] = will_retry
+      run_callbacks(:after_fail, response)
+      will_retry ? retry_request(retry_number) : response
+    end
+
+    def execute_request(retry_number: 0)
+      response = start_execution(retry_number)
+    rescue => error
+      unknown_network_error?(error) ? handle_unknown_error(error) : handle_network_error(error, retry_number)
     else
-      if response.success?
-        callbacks_context.delete(:will_retry)
-        run_callbacks(:after_success, response)
-        response
-      else
-        will_retry = retries[:enabled] && retryable?(response, retry_number)
-        callbacks_context[:will_retry] = will_retry
-        run_callbacks(:after_fail, response)
-        will_retry ? retry_request(retry_number) : response
-      end
+      response.success? ? handle_success_response(response) : handle_failed_response(response, retry_number)
     end
 
     def execute_net_http_request
@@ -105,6 +114,14 @@ module PaypalAPI
       true
     end
 
+    def unknown_network_error?(error)
+      NetworkErrorBuilder::ERRORS.none? { |network_error_class| error.is_a?(network_error_class) }
+    end
+
+    def handle_unknown_error(error)
+      raise error
+    end
+
     def run_callbacks(callback_name, resp = nil)
       callbacks[callback_name].each { |callback| callback.call(request, callbacks_context, resp) }
     end

data/lib/paypal-api/response.rb

@@ -108,6 +108,72 @@ module PaypalAPI
       "#<#{self.class.name} (#{http_response.code})>"
     end
 
+    #
+    # Follow up HATEOAS link
+    #
+    # @see https://developer.paypal.com/api/rest/responses/#link-hateoaslinks
+    #
+    # @param rel [String] Target link "rel" attribute
+    # @param query [Hash] Request additional query parameters
+    # @param body [Hash] Request body parameters
+    # @param headers [Hash] Request headers
+    #
+    # @return [Response, nil] Follow-up link response, if link with provided "rel" exists
+    #
+    def follow_up_link(rel, query: nil, body: nil, headers: nil)
+      links = self[:links]
+      return unless links
+
+      link = links.find { |curr_link| curr_link[:rel] == rel.to_s }
+      return unless link
+
+      http_method = link[:method]&.downcase || :get
+      request.client.public_send(http_method, link[:href], query: query, body: body, headers: headers)
+    end
+
+    #
+    # Pagination methods
+    #
+    module PaginationHelpers
+      #
+      # Iterates through all response pages by requesting HATEOAS "next" links,
+      # making additional fetches to the API as necessary.
+      #
+      # @see #follow_up_link
+      #
+      # @yield [Response] Next page response
+      #
+      # @return [void]
+      #
+      def each_page(&block)
+        return enum_for(:each_page) unless block
+
+        page = self
+        yield(page)
+        yield(page) while (page = page.follow_up_link("next"))
+      end
+
+      #
+      # Iterates through all items in response +items_field_name+ field,
+      # making additional pages requests as necessary.
+      #
+      # @see #each_page
+      #
+      # @param items_field_name [Symbol] Name of field containing items
+      #
+      # @yield [Hash] Item
+      #
+      # @return [void]
+      #
+      def each_page_item(items_field_name, &block)
+        return enum_for(:each_page_item, items_field_name) unless block
+
+        each_page do |page|
+          page.fetch(items_field_name).each(&block)
+        end
+      end
+    end
+
     private
 
     def json_response?
@@ -120,5 +186,7 @@ module PaypalAPI
     rescue JSON::ParserError, TypeError
       json
     end
+
+    include PaginationHelpers
   end
 end

data/lib/paypal-api.rb

@@ -100,10 +100,8 @@ module PaypalAPI
 
     #
     # @!macro [new] api_collection
-    #   $0 APIs collection
+    #   $3 APIs collection
     #   @api public
-    #   @example
-    #     PaypalAPI.$0
     #
 
     #
@@ -139,6 +137,14 @@ module PaypalAPI
     #   @macro api_collection
     #   @return [Orders]
     #
+    # @!method partner_referrals
+    #   @macro api_collection
+    #   @return [PartnerReferrals]
+    #
+    # @!method payment_experience_web_profiles
+    #   @macro api_collection
+    #   @return [PaymentExperienceWebProfile]
+    #
     # @!method payout_items
     #   @macro api_collection
     #   @return [PayoutItems]
@@ -171,6 +177,10 @@ module PaypalAPI
     #   @macro api_collection
     #   @return [SubscriptionPlans]
     #
+    # @!method transaction_search
+    #   @macro api_collection
+    #   @return [TransactionSearch]
+    #
     # @!method user_info
     #   @macro api_collection
     #   @return [UserInfo]
@@ -200,6 +210,8 @@ module PaypalAPI
       invoice_templates
       invoices
       orders
+      partner_referrals
+      payment_experience_web_profiles
       payment_tokens
       payout_items
       payouts
@@ -210,6 +222,7 @@ module PaypalAPI
       shipment_tracking
       subscriptions
       subscription_plans
+      transaction_search
       user_info
       users
       webhooks
@@ -237,6 +250,10 @@ end
 require_relative "paypal-api/access_token"
 require_relative "paypal-api/api_collection"
 require_relative "paypal-api/environment"
+require_relative "paypal-api/client/access_token_methods"
+require_relative "paypal-api/client/api_methods"
+require_relative "paypal-api/client/environment_methods"
+require_relative "paypal-api/client/http_methods"
 require_relative "paypal-api/client"
 require_relative "paypal-api/config"
 require_relative "paypal-api/error"
@@ -255,6 +272,8 @@ require_relative "paypal-api/api_collections/disputes"
 require_relative "paypal-api/api_collections/invoice_templates"
 require_relative "paypal-api/api_collections/invoices"
 require_relative "paypal-api/api_collections/orders"
+require_relative "paypal-api/api_collections/partner_referrals"
+require_relative "paypal-api/api_collections/payment_experience_web_profiles"
 require_relative "paypal-api/api_collections/payment_tokens"
 require_relative "paypal-api/api_collections/payout_items"
 require_relative "paypal-api/api_collections/payouts"
@@ -265,6 +284,7 @@ require_relative "paypal-api/api_collections/setup_tokens"
 require_relative "paypal-api/api_collections/shipment_tracking"
 require_relative "paypal-api/api_collections/subscriptions"
 require_relative "paypal-api/api_collections/subscription_plans"
+require_relative "paypal-api/api_collections/transaction_search"
 require_relative "paypal-api/api_collections/user_info"
 require_relative "paypal-api/api_collections/users"
 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.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Andrey Glushkov
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-09-16 00:00:00.000000000 Z
+date: 2024-09-30 00:00:00.000000000 Z
 dependencies: []
 description: PayPal REST API with no dependencies.
 email:
@@ -30,6 +30,8 @@ files:
 - lib/paypal-api/api_collections/invoice_templates.rb
 - lib/paypal-api/api_collections/invoices.rb
 - lib/paypal-api/api_collections/orders.rb
+- lib/paypal-api/api_collections/partner_referrals.rb
+- lib/paypal-api/api_collections/payment_experience_web_profiles.rb
 - lib/paypal-api/api_collections/payment_tokens.rb
 - lib/paypal-api/api_collections/payout_items.rb
 - lib/paypal-api/api_collections/payouts.rb
@@ -40,12 +42,17 @@ files:
 - lib/paypal-api/api_collections/shipment_tracking.rb
 - lib/paypal-api/api_collections/subscription_plans.rb
 - lib/paypal-api/api_collections/subscriptions.rb
+- lib/paypal-api/api_collections/transaction_search.rb
 - lib/paypal-api/api_collections/user_info.rb
 - lib/paypal-api/api_collections/users.rb
 - lib/paypal-api/api_collections/webhook_events.rb
 - lib/paypal-api/api_collections/webhook_lookups.rb
 - lib/paypal-api/api_collections/webhooks.rb
 - lib/paypal-api/client.rb
+- lib/paypal-api/client/access_token_methods.rb
+- lib/paypal-api/client/api_methods.rb
+- lib/paypal-api/client/environment_methods.rb
+- lib/paypal-api/client/http_methods.rb
 - lib/paypal-api/config.rb
 - lib/paypal-api/environment.rb
 - lib/paypal-api/error.rb
@@ -80,7 +87,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.18
+rubygems_version: 3.5.20
 signing_key:
 specification_version: 4
 summary: PayPal REST API