paypal-rest-api 0.0.1 → 0.0.3

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

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+module PaypalAPI
+  #
+  # Manages subscriptions for recurring PayPal payments
+  #
+  # @see https://developer.paypal.com/docs/api/subscriptions/v1/
+  #
+  class Subscriptions < 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
+
+      #
+      # Creates a plan that defines pricing and billing cycle details for subscriptions.
+      #
+      # @see https://developer.paypal.com/docs/api/subscriptions/v1/#plans_create
+      #
+      # @macro request
+      #
+      def create_plan(query: nil, body: nil, headers: nil)
+        client.post("/v1/billing/plans", query: query, body: body, headers: headers)
+      end
+
+      #
+      # List plans
+      #
+      # @see https://developer.paypal.com/docs/api/subscriptions/v1/#plans_list
+      #
+      # @macro request
+      #
+      def list_plans(query: nil, body: nil, headers: nil)
+        client.get("/v1/billing/plans", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Show plan details
+      #
+      # @see https://developer.paypal.com/docs/api/subscriptions/v1/#plans_get
+      #
+      # @param plan_id [String] Plan ID
+      # @macro request
+      #
+      def show_plan(plan_id, query: nil, body: nil, headers: nil)
+        client.get("/v1/billing/plans/#{plan_id}", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Update plan
+      #
+      # @see https://developer.paypal.com/docs/api/subscriptions/v1/#plans_patch
+      #
+      # @param plan_id [String] Plan ID
+      # @macro request
+      #
+      def update_plan(plan_id, query: nil, body: nil, headers: nil)
+        client.patch("/v1/billing/plans/#{plan_id}", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Activate plan
+      #
+      # @see https://developer.paypal.com/docs/api/subscriptions/v1/#plans_activate
+      #
+      # @param plan_id [String] Plan ID
+      # @macro request
+      #
+      def activate_plan(plan_id, query: nil, body: nil, headers: nil)
+        client.post("/v1/billing/plans/#{plan_id}/activate", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Deactivate plan
+      #
+      # @see https://developer.paypal.com/docs/api/subscriptions/v1/#plans_deactivate
+      #
+      # @param plan_id [String] Plan ID
+      # @macro request
+      #
+      def deactivate_plan(plan_id, query: nil, body: nil, headers: nil)
+        client.post("/v1/billing/plans/#{plan_id}/deactivate", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Update pricing
+      #
+      # @see https://developer.paypal.com/docs/api/subscriptions/v1/#plans_deactivate
+      #
+      # @param plan_id [String] Plan ID
+      # @macro request
+      #
+      def update_plan_pricing(plan_id, query: nil, body: nil, headers: nil)
+        client.post("/v1/billing/plans/#{plan_id}/update-pricing-schemes", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Create subscription
+      #
+      # @see https://developer.paypal.com/docs/api/subscriptions/v1/#subscriptions_create
+      #
+      # @macro request
+      #
+      def create_subscription(query: nil, body: nil, headers: nil)
+        client.post("/v1/billing/subscriptions", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Show subscription details
+      #
+      # @see https://developer.paypal.com/docs/api/subscriptions/v1/#subscriptions_get
+      #
+      # @param subscription_id [String] Subscripton ID
+      # @macro request
+      #
+      def show_subscription(subscription_id, query: nil, body: nil, headers: nil)
+        client.get("/v1/billing/subscriptions/#{subscription_id}", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Update subscription
+      #
+      # @see https://developer.paypal.com/docs/api/subscriptions/v1/#subscriptions_patch
+      #
+      # @param subscription_id [String] Subscripton ID
+      # @macro request
+      #
+      def update_subscription(subscription_id, query: nil, body: nil, headers: nil)
+        client.patch("/v1/billing/subscriptions/#{subscription_id}", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Revise plan or quantity of subscription
+      #
+      # @see https://developer.paypal.com/docs/api/subscriptions/v1/#subscriptions_revise
+      #
+      # @param subscription_id [String] Subscripton ID
+      # @macro request
+      #
+      def revise_subscription(subscription_id, query: nil, body: nil, headers: nil)
+        client.post("/v1/billing/subscriptions/#{subscription_id}/revise", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Suspend subscription
+      #
+      # @see https://developer.paypal.com/docs/api/subscriptions/v1/#subscriptions_suspend
+      #
+      # @param subscription_id [String] Subscripton ID
+      # @macro request
+      #
+      def suspend_subscription(subscription_id, query: nil, body: nil, headers: nil)
+        client.post("/v1/billing/subscriptions/#{subscription_id}/suspend", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Cancel subscription
+      #
+      # @see https://developer.paypal.com/docs/api/subscriptions/v1/#subscriptions_cancel
+      #
+      # @param subscription_id [String] Subscripton ID
+      # @macro request
+      #
+      def cancel_subscription(subscription_id, query: nil, body: nil, headers: nil)
+        client.post("/v1/billing/subscriptions/#{subscription_id}/cancel", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Activate subscription
+      #
+      # @see https://developer.paypal.com/docs/api/subscriptions/v1/#subscriptions_activate
+      #
+      # @param subscription_id [String] Subscripton ID
+      # @macro request
+      #
+      def activate_subscription(subscription_id, query: nil, body: nil, headers: nil)
+        client.post("/v1/billing/subscriptions/#{subscription_id}/activate", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Capture authorized payment on subscription
+      #
+      # @see https://developer.paypal.com/docs/api/subscriptions/v1/#subscriptions_capture
+      #
+      # @param subscription_id [String] Subscripton ID
+      # @macro request
+      #
+      def capture_subscription(subscription_id, query: nil, body: nil, headers: nil)
+        client.post("/v1/billing/subscriptions/#{subscription_id}/capture", query: query, body: body, headers: headers)
+      end
+
+      #
+      # List transactions for subscription
+      #
+      # @see https://developer.paypal.com/docs/api/subscriptions/v1/#subscriptions_transactions
+      #
+      # @param subscription_id [String] Subscripton ID
+      # @macro request
+      #
+      def transactions(subscription_id, query: nil, body: nil, headers: nil)
+        client.get("/v1/billing/subscriptions/#{subscription_id}/transactions", query: query, body: body, headers: headers)
+      end
+    end
+
+    include APIs
+    extend APIs
+  end
+end

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

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+module PaypalAPI
+  #
+  # https://developer.paypal.com/docs/api/webhooks/v1/
+  #
+  class Webhooks < 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 webhook
+      #
+      # @see https://developer.paypal.com/docs/api/webhooks/v1/#webhooks_post
+      #
+      # @macro request
+      #
+      def create(query: nil, body: nil, headers: nil)
+        client.post("/v1/notifications/webhooks", query: query, body: body, headers: headers)
+      end
+
+      #
+      # List webhooks
+      #
+      # @see https://developer.paypal.com/docs/api/webhooks/v1/#webhooks_list
+      #
+      # @macro request
+      #
+      def list(query: nil, body: nil, headers: nil)
+        client.get("/v1/notifications/webhooks", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Show webhook details
+      #
+      # @see https://developer.paypal.com/docs/api/webhooks/v1/#webhooks_get
+      #
+      # @param webhook_id [String] Webhook ID
+      # @macro request
+      #
+      def show(webhook_id, query: nil, body: nil, headers: nil)
+        client.get("/v1/notifications/webhooks/#{webhook_id}", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Update webhook
+      #
+      # @see https://developer.paypal.com/docs/api/webhooks/v1/#webhooks_update
+      #
+      # @param webhook_id [String] Webhook ID
+      # @macro request
+      #
+      def update(webhook_id, query: nil, body: nil, headers: nil)
+        client.patch("/v1/notifications/webhooks/#{webhook_id}", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Delete webhook
+      #
+      # @see https://developer.paypal.com/docs/api/webhooks/v1/#webhooks_delete
+      #
+      # @param webhook_id [String] Webhook ID
+      # @macro request
+      #
+      def delete(webhook_id, query: nil, body: nil, headers: nil)
+        client.delete("/v1/notifications/webhooks/#{webhook_id}", query: query, body: body, headers: headers)
+      end
+
+      #
+      # List event subscriptions for webhook
+      #
+      # @see https://developer.paypal.com/docs/api/webhooks/v1/#event-types_list
+      #
+      # @param webhook_id [String] Webhook ID
+      # @macro request
+      #
+      def list_event_types(webhook_id, query: nil, body: nil, headers: nil)
+        client.get("/v1/notifications/webhooks/#{webhook_id}/event-types", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Create webhook lookup
+      #
+      # @see https://developer.paypal.com/docs/api/webhooks/v1/#webhooks-lookup_post
+      #
+      # @macro request
+      #
+      def create_lookup(query: nil, body: nil, headers: nil)
+        client.post("/v1/notifications/webhooks-lookup", query: query, body: body, headers: headers)
+      end
+
+      #
+      # List webhook lookups
+      #
+      # @see https://developer.paypal.com/docs/api/webhooks/v1/#webhooks-lookup_list
+      #
+      # @macro request
+      #
+      def list_lookups(query: nil, body: nil, headers: nil)
+        client.get("/v1/notifications/webhooks-lookup", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Show webhook lookup details
+      #
+      # @see https://developer.paypal.com/docs/api/webhooks/v1/#webhooks-lookup_get
+      #
+      # @param webhook_lookup_id [String] Webhook lookup ID
+      # @macro request
+      #
+      def show_lookup(webhook_lookup_id, query: nil, body: nil, headers: nil)
+        client.get("/v1/notifications/webhooks-lookup/#{webhook_lookup_id}", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Delete webhook lookup
+      #
+      # @see https://developer.paypal.com/docs/api/webhooks/v1/#webhooks-lookup_delete
+      #
+      # @param webhook_lookup_id [String] Webhook lookup ID
+      # @macro request
+      #
+      def delete_lookup(webhook_lookup_id, query: nil, body: nil, headers: nil)
+        client.delete("/v1/notifications/webhooks-lookup/#{webhook_lookup_id}", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Verify webhook signature
+      #
+      # @see https://developer.paypal.com/docs/api/webhooks/v1/#verify-webhook-signature_post
+      #
+      # @macro request
+      #
+      def verify(query: nil, body: nil, headers: nil)
+        client.post("/v1/notifications/verify-webhook-signature", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Lists available events to which any webhook can subscribe
+      #
+      # @see https://developer.paypal.com/docs/api/webhooks/v1/#webhooks-event-types_list
+      #
+      # @macro request
+      #
+      def list_available_events(query: nil, body: nil, headers: nil)
+        client.get("/v1/notifications/webhooks-event-types", query: query, body: body, headers: headers)
+      end
+
+      #
+      # List event notifications
+      #
+      # @see https://developer.paypal.com/docs/api/webhooks/v1/#webhooks-events_list
+      #
+      # @macro request
+      #
+      def list_events(query: nil, body: nil, headers: nil)
+        client.get("/v1/notifications/webhooks-events", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Show event notification details
+      #
+      # @see https://developer.paypal.com/docs/api/webhooks/v1/#webhooks-events_get
+      #
+      # @param event_id [String] Event ID
+      # @macro request
+      #
+      def show_event(event_id, query: nil, body: nil, headers: nil)
+        client.get("/v1/notifications/webhooks-events/#{event_id}", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Resend event notification
+      #
+      # @see https://developer.paypal.com/docs/api/webhooks/v1/#webhooks-events_resend
+      #
+      # @param event_id [String] Event ID
+      # @macro request
+      #
+      def resend_event(event_id, query: nil, body: nil, headers: nil)
+        client.post("/v1/notifications/webhooks-events/#{event_id}/resend", query: query, body: body, headers: headers)
+      end
+
+      #
+      # Simulate webhook event
+      #
+      # @see https://developer.paypal.com/docs/api/webhooks/v1/#simulate-event_post
+      #
+      # @macro request
+      #
+      def simulate_event(query: nil, body: nil, headers: nil)
+        client.post("/v1/notifications/simulate-event", query: query, body: body, headers: headers)
+      end
+    end
+
+    include APIs
+    extend APIs
+  end
+end

data/lib/paypal-api/client.rb

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

data/lib/paypal-api/config.rb

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