gocardless_pro 2.15.1 → 2.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 240cc1318312d1dc21ab14f27d0c9ffe3d813dbac6e671f1b1ff25c5574010f8
-  data.tar.gz: 462678183639612f89335b0166a848047a03ca73a9134d85959740cde5f32e35
+  metadata.gz: 396dcbfc132b43e7d8d8a29bed742fe7eea6a097b143182761f68847a2ab0879
+  data.tar.gz: c3b2f53f38baf4a182eefec78be40e55ad21d9ec45b0a6a3169824859fe7a1af
 SHA512:
-  metadata.gz: 00363e5109326f5924f2407f0de5fb54557af8eabedb6a283f03dccab816f220fda68cbf77e142df1a8f66f4116eb0047ed261d38dd181759c6e4e1a3c6c9658
-  data.tar.gz: '04628b2b5996f31402d9919d0e91d0a064484d96f05d9fc97a04f8e964fad0542953b55d98778b3ec32bdf76634e33428b6a8764ae8c1ec7753f95ed515ec371'
+  metadata.gz: 8077e0c81cb8c2c2c51aca0d9d76d855be60aede0ef86bc87ea3d6be03bb13fda37002f4913621919478b07e9c2eabf491e6d551d5e59bc6cf80d7e7288955f8
+  data.tar.gz: e33ffac591f5657eb93172d866ecdda2105a452e066e7eabc0fc1b9d14dc59241f5f8b6b2a3e090d38afae4023cb3a280699307e332f4b4bd342d0f38715604c

data/README.md

@@ -120,6 +120,16 @@ When creating a resource, the library will automatically include a randomly-gene
 [idempotency key](https://developer.gocardless.com/api-reference/#making-requests-idempotency-keys)
 - this means that if a request appears to fail but is in fact successful (for example due
 to a timeout), you will not end up creating multiple duplicates of the resource.
+- By default if a request results in an Idempotency Key conflict
+  the library will make a second request and return the object that was
+  originally created with the Idempotency Key. If you wish, you can instead configure
+  the client to raise the conflict for you to handle. e.g
+  ```
+  @client = GoCardlessPro::Client.new(
+    access_token: ENV["GOCARDLESS_TOKEN"],
+    on_idempotency_conflict: :raise,
+  )
+  ```
 
 If any parameters are required they come first:
 

data/lib/gocardless_pro/client.rb

@@ -38,6 +38,11 @@ module GoCardlessPro
       @events ||= Services::EventsService.new(@api_service)
     end
 
+    # Access to the service for instalment_schedule to make API calls
+    def instalment_schedules
+      @instalment_schedules ||= Services::InstalmentSchedulesService.new(@api_service)
+    end
+
     # Access to the service for mandate to make API calls
     def mandates
       @mandates ||= Services::MandatesService.new(@api_service)
@@ -138,7 +143,7 @@ module GoCardlessPro
           'User-Agent' => user_agent.to_s,
           'Content-Type' => 'application/json',
           'GoCardless-Client-Library' => 'gocardless-pro-ruby',
-          'GoCardless-Client-Version' => '2.15.1',
+          'GoCardless-Client-Version' => '2.16.0',
         },
       }
     end

data/lib/gocardless_pro/resources/event.rb

@@ -59,6 +59,10 @@ module GoCardlessPro
           @links = links || {}
         end
 
+        def instalment_schedule
+          @links['instalment_schedule']
+        end
+
         def mandate
           @links['mandate']
         end

data/lib/gocardless_pro/resources/instalment_schedule.rb

@@ -0,0 +1,92 @@
+# encoding: utf-8
+
+#
+# This client is automatically generated from a template and JSON schema definition.
+# See https://github.com/gocardless/gocardless-pro-ruby#contributing before editing.
+#
+
+require 'uri'
+
+module GoCardlessPro
+  # A module containing classes for each of the resources in the GC Api
+  module Resources
+    # Represents an instance of a instalment_schedule resource returned from the API
+
+    # Instalment schedules are objects which represent a collection of related
+    # payments, with the
+    # intention to collect the `total_amount` specified. The API supports both
+    # schedule-based
+    # creation (similar to subscriptions) as well as explicit selection of
+    # differing payment
+    # amounts and charge dates.
+    #
+    # Unlike subscriptions, the payments are created immediately, so the
+    # instalment schedule
+    # cannot be modified once submitted and instead can only be cancelled (which
+    # will cancel
+    # any of the payments which have not yet been submitted).
+    #
+    # Customers will receive a single notification about the complete schedule
+    # of collection.
+    #
+    class InstalmentSchedule
+      attr_reader :created_at
+      attr_reader :currency
+      attr_reader :id
+      attr_reader :metadata
+      attr_reader :name
+      attr_reader :payment_errors
+      attr_reader :status
+      attr_reader :total_amount
+
+      # Initialize a instalment_schedule resource instance
+      # @param object [Hash] an object returned from the API
+      def initialize(object, response = nil)
+        @object = object
+
+        @created_at = object['created_at']
+        @currency = object['currency']
+        @id = object['id']
+        @links = object['links']
+        @metadata = object['metadata']
+        @name = object['name']
+        @payment_errors = object['payment_errors']
+        @status = object['status']
+        @total_amount = object['total_amount']
+        @response = response
+      end
+
+      def api_response
+        ApiResponse.new(@response)
+      end
+
+      # Return the links that the resource has
+      def links
+        @instalment_schedule_links ||= Links.new(@links)
+      end
+
+      # Provides the instalment_schedule resource as a hash of all its readable attributes
+      def to_h
+        @object
+      end
+
+      class Links
+        def initialize(links)
+          @links = links || {}
+        end
+
+        def customer
+          @links['customer']
+        end
+
+        def mandate
+          @links['mandate']
+        end
+
+        def payments
+          @links['payments']
+        end
+      end
+    end
+  end
+end

data/lib/gocardless_pro/resources/payment.rb

@@ -75,6 +75,10 @@ module GoCardlessPro
           @links['creditor']
         end
 
+        def instalment_schedule
+          @links['instalment_schedule']
+        end
+
         def mandate
           @links['mandate']
         end

data/lib/gocardless_pro/resources/refund.rb

@@ -27,6 +27,7 @@ module GoCardlessPro
       attr_reader :id
       attr_reader :metadata
       attr_reader :reference
+      attr_reader :status
 
       # Initialize a refund resource instance
       # @param object [Hash] an object returned from the API
@@ -41,6 +42,7 @@ module GoCardlessPro
         @links = object['links']
         @metadata = object['metadata']
         @reference = object['reference']
+        @status = object['status']
         @response = response
       end
 

data/lib/gocardless_pro/services/instalment_schedules_service.rb

@@ -0,0 +1,177 @@
+require_relative './base_service'
+require 'uri'
+
+# encoding: utf-8
+#
+# This client is automatically generated from a template and JSON schema definition.
+# See https://github.com/gocardless/gocardless-pro-ruby#contributing before editing.
+#
+
+module GoCardlessPro
+  module Services
+    # Service for making requests to the InstalmentSchedule endpoints
+    class InstalmentSchedulesService < BaseService
+      # Creates a new instalment schedule object, along with the associated payments.
+      #
+      # The `instalments` property can either be an array of payment properties
+      # (`amount`
+      # and `charge_date`) or a schedule object with `interval`, `interval_unit` and
+      # `amounts`.
+      #
+      # It can take quite a while to create the associated payments, so the API will
+      # return
+      # the status as `pending` initially. When processing has completed, a subsequent
+      # GET request for the instalment schedule will either have the status `success`
+      # and link to
+      # the created payments, or the status `error` and detailed information about the
+      # failures.
+      # Example URL: /instalment_schedules
+      # @param options [Hash] parameters as a hash, under a params key.
+      def create(options = {})
+        path = '/instalment_schedules'
+
+        params = options.delete(:params) || {}
+        options[:params] = {}
+        options[:params][envelope_key] = params
+
+        options[:retry_failures] = true
+
+        begin
+          response = make_request(:post, path, options)
+
+          # Response doesn't raise any errors until #body is called
+          response.tap(&:body)
+        rescue InvalidStateError => e
+          if e.idempotent_creation_conflict?
+            case @api_service.on_idempotency_conflict
+            when :raise
+              raise IdempotencyConflict, e.error
+            when :fetch
+              return get(e.conflicting_resource_id)
+            else
+              raise ArgumentError, 'Unknown mode for :on_idempotency_conflict'
+            end
+          end
+
+          raise e
+        end
+
+        return if response.body.nil?
+
+        Resources::InstalmentSchedule.new(unenvelope_body(response.body), response)
+      end
+
+      # Returns a [cursor-paginated](#api-usage-cursor-pagination) list of your
+      # instalment schedules.
+      # Example URL: /instalment_schedules
+      # @param options [Hash] parameters as a hash, under a params key.
+      def list(options = {})
+        path = '/instalment_schedules'
+
+        options[:retry_failures] = true
+
+        response = make_request(:get, path, options)
+
+        ListResponse.new(
+          response: response,
+          unenveloped_body: unenvelope_body(response.body),
+          resource_class: Resources::InstalmentSchedule
+        )
+      end
+
+      # Get a lazily enumerated list of all the items returned. This is simmilar to the `list` method but will paginate for you automatically.
+      #
+      # @param options [Hash] parameters as a hash. If the request is a GET, these will be converted to query parameters.
+      # Otherwise they will be the body of the request.
+      def all(options = {})
+        Paginator.new(
+          service: self,
+          options: options
+        ).enumerator
+      end
+
+      # Retrieves the details of an existing instalment schedule.
+      # Example URL: /instalment_schedules/:identity
+      #
+      # @param identity       # Unique identifier, beginning with "IS".
+      # @param options [Hash] parameters as a hash, under a params key.
+      def get(identity, options = {})
+        path = sub_url('/instalment_schedules/:identity', 'identity' => identity)
+
+        options[:retry_failures] = true
+
+        response = make_request(:get, path, options)
+
+        return if response.body.nil?
+
+        Resources::InstalmentSchedule.new(unenvelope_body(response.body), response)
+      end
+
+      # Immediately cancels an instalment schedule; no further payments will be
+      # collected for it.
+      #
+      # This will fail with a `cancellation_failed` error if the instalment schedule
+      # is already cancelled or has completed.
+      # Example URL: /instalment_schedules/:identity/actions/cancel
+      #
+      # @param identity       # Unique identifier, beginning with "IS".
+      # @param options [Hash] parameters as a hash, under a params key.
+      def cancel(identity, options = {})
+        path = sub_url('/instalment_schedules/:identity/actions/cancel', 'identity' => identity)
+
+        params = options.delete(:params) || {}
+        options[:params] = {}
+        options[:params]['data'] = params
+
+        options[:retry_failures] = false
+
+        begin
+          response = make_request(:post, path, options)
+
+          # Response doesn't raise any errors until #body is called
+          response.tap(&:body)
+        rescue InvalidStateError => e
+          if e.idempotent_creation_conflict?
+            case @api_service.on_idempotency_conflict
+            when :raise
+              raise IdempotencyConflict, e.error
+            when :fetch
+              return get(e.conflicting_resource_id)
+            else
+              raise ArgumentError, 'Unknown mode for :on_idempotency_conflict'
+            end
+          end
+
+          raise e
+        end
+
+        return if response.body.nil?
+
+        Resources::InstalmentSchedule.new(unenvelope_body(response.body), response)
+      end
+
+      private
+
+      # Unenvelope the response of the body using the service's `envelope_key`
+      #
+      # @param body [Hash]
+      def unenvelope_body(body)
+        body[envelope_key] || body['data']
+      end
+
+      # return the key which API responses will envelope data under
+      def envelope_key
+        'instalment_schedules'
+      end
+
+      # take a URL with placeholder params and substitute them out for the actual value
+      # @param url [String] the URL with placeholders in
+      # @param param_map [Hash] a hash of placeholders and their actual values (which will be escaped)
+      def sub_url(url, param_map)
+        param_map.reduce(url) do |new_url, (param, value)|
+          new_url.gsub(":#{param}", URI.escape(value))
+        end
+      end
+    end
+  end
+end

data/lib/gocardless_pro/version.rb

@@ -4,5 +4,5 @@ end
 
 module GoCardlessPro
   # Current version of the GC gem
-  VERSION = '2.15.1'.freeze
+  VERSION = '2.16.0'.freeze
 end

data/lib/gocardless_pro.rb

@@ -59,6 +59,9 @@ require_relative 'gocardless_pro/services/customer_notifications_service'
 require_relative 'gocardless_pro/resources/event'
 require_relative 'gocardless_pro/services/events_service'
 
+require_relative 'gocardless_pro/resources/instalment_schedule'
+require_relative 'gocardless_pro/services/instalment_schedules_service'
+
 require_relative 'gocardless_pro/resources/mandate'
 require_relative 'gocardless_pro/services/mandates_service'