starkbank 2.4.0 → 2.5.0

data/lib/deposit/log.rb

@@ -52,18 +52,49 @@ module StarkBank
       #
       # ## Parameters (optional):
       # - limit [integer, default nil]: maximum number of objects to be retrieved. Unlimited if nil. ex: 35
-      # - after [Date, DateTime, Time or string, default nil] date filter for objects created only after specified date. ex: Date.new(2020, 3, 10)
-      # - before [Date, DateTime, Time or string, default nil] date filter for objects created only before specified date. ex: Date.new(2020, 3, 10)
+      # - after [Date, DateTime, Time or string, default nil]: date filter for objects created only after specified date. ex: Date.new(2020, 3, 10)
+      # - before [Date, DateTime, Time or string, default nil]: date filter for objects created only before specified date. ex: Date.new(2020, 3, 10)
       # - types [list of strings, default nil]: filter for log event types. ex: 'paid' or 'canceled'
       # - deposit_ids [list of strings, default nil]: list of Deposit ids to filter logs. ex: ['5656565656565656', '4545454545454545']
-      # - user [Organization/Project object]: Organization or Project object. Not necessary if Starkbank.user was set before function call
+      # - user [Organization/Project object]: Organization or Project object. Not necessary if StarkBank.user was set before function call
       #
       # ## Return:
       # - list of Log objects with updated attributes
       def self.query(limit: nil, after: nil, before: nil, types: nil, deposit_ids: nil, user: nil)
         after = StarkBank::Utils::Checks.check_date(after)
         before = StarkBank::Utils::Checks.check_date(before)
-        StarkBank::Utils::Rest.get_list(
+        StarkBank::Utils::Rest.get_stream(
+          limit: limit,
+          after: after,
+          before: before,
+          types: types,
+          deposit_ids: deposit_ids,
+          user: user,
+          **resource
+        )
+      end
+
+      # # Retrieve paged Logs
+      #
+      # Receive a list of up to 100 Log objects previously created in the Stark Bank API and the cursor to the next page.
+      # Use this function instead of query if you want to manually page your requests.
+      #
+      # ## Parameters (optional):
+      # - cursor [string, default nil]: cursor returned on the previous page function call
+      # - limit [integer, default nil]: maximum number of objects to be retrieved. Unlimited if nil. ex: 35
+      # - after [Date, DateTime, Time or string, default nil]: date filter for objects created only after specified date. ex: Date.new(2020, 3, 10)
+      # - before [Date, DateTime, Time or string, default nil]: date filter for objects created only before specified date. ex: Date.new(2020, 3, 10)
+      # - types [list of strings, default nil]: filter for log event types. ex: 'paid' or 'canceled'
+      # - deposit_ids [list of strings, default nil]: list of Deposit ids to filter logs. ex: ['5656565656565656', '4545454545454545']
+      # - user [Organization/Project object]: Organization or Project object. Not necessary if StarkBank.user was set before function call
+      #
+      # ## Return:
+      # - list of Log objects with updated attributes and cursor to retrieve the next page of Log objects
+      def self.page(cursor: nil, limit: nil, after: nil, before: nil, types: nil, deposit_ids: nil, user: nil)
+        after = StarkBank::Utils::Checks.check_date(after)
+        before = StarkBank::Utils::Checks.check_date(before)
+        return StarkBank::Utils::Rest.get_page(
+          cursor: cursor,
           limit: limit,
           after: after,
           before: before,

data/lib/dict_key/dict_key.rb

@@ -17,25 +17,27 @@ module StarkBank
   # - name [string, default nil]: account owner full name. ex: 'Tony Stark'
   # - tax_id [string, default nil]: key owner tax ID (CNPJ or masked CPF). ex: '***.345.678-**' or '20.018.183/0001-80'
   # - owner_type [string, default nil]: DICT key owner type. ex 'naturalPerson' or 'legalPerson'
+  # - bank_name [string, default nil]: bank name associated with the DICT key. ex: 'Stark Bank'
   # - ispb [string, default nil]: bank ISPB associated with the DICT key. ex: '20018183'
   # - branch_code [string, default nil]: bank account branch code associated with the DICT key. ex: '9585'
   # - account_number [string, default nil]: bank account number associated with the DICT key. ex: '9828282578010513'
-  # - account_type [string, default nil]: bank account type associated with the DICT key. ex: 'checking', 'saving' e 'salary'
+  # - account_type [string, default nil]: bank account type associated with the DICT key. ex: 'checking', 'saving', 'salary' or 'payment'
   # - status [string, default nil]: current DICT key status. ex: 'created', 'registered', 'canceled' or 'failed'
   # - account_created [DateTime or string, default nil]: creation datetime of the bank account associated with the DICT key. ex: '2020-11-05T14:55:08.812665+00:00'
   # - owned [DateTime or string, default nil]: datetime since when the current owner hold this DICT key. ex : '2020-11-05T14:55:08.812665+00:00'
   # - created [DateTime or string, default nil]: creation datetime for the DICT key. ex: '2020-03-10 10:30:00.000'
   class DictKey < StarkBank::Utils::Resource
-    attr_reader :id, :type, :name, :tax_id, :owner_type, :ispb, :branch_code, :account_number, :account_type, :status, :account_created, :owned, :created
+    attr_reader :id, :type, :name, :tax_id, :owner_type, :bank_name, :ispb, :branch_code, :account_number, :account_type, :status, :account_created, :owned, :created
     def initialize(
-      id:, type:, name:, tax_id:, owner_type:, ispb:, branch_code:, account_number:, account_type:,
-      status:, account_created:, owned:, created:
+      id:, type:, name:, tax_id:, owner_type:, bank_name:, ispb:, branch_code:, account_number:, 
+      account_type:, status:, account_created:, owned:, created:
     )
       super(id)
       @type = type
       @name = name
       @tax_id = tax_id
       @owner_type = owner_type
+      @bank_name = bank_name
       @ispb = ispb
       @branch_code = branch_code
       @account_number = account_number
@@ -69,18 +71,51 @@ module StarkBank
     # ## Parameters (optional):
     # - limit [integer, default nil]: maximum number of objects to be retrieved. Unlimited if nil. ex: 35
     # - type [string, default nil]: DictKey type. ex: 'cpf', 'cnpj', 'phone', 'email' or 'evp'
-    # - after [Date , DateTime, Time or string, default nil] date filter for objects created only after specified date. ex: Date.new(2020, 3, 10)
-    # - before [Date, DateTime, Time or string, default nil] date filter for objects created only before specified date. ex: Date.new(2020, 3, 10)
+    # - after [Date, DateTime, Time or string, default nil]: date filter for objects created only after specified date. ex: Date.new(2020, 3, 10)
+    # - before [Date, DateTime, Time or string, default nil]: date filter for objects created only before specified date. ex: Date.new(2020, 3, 10)
     # - ids [list of strings, default nil]: list of ids to filter retrieved objects. ex: ['5656565656565656', '4545454545454545']
     # - status [string, default nil]: filter for status of retrieved objects. ex: 'canceled', 'registered'
-    # - user [Organization/Project object]: Organization or Project object. Not necessary if Starkbank.user was set before function call
+    # - user [Organization/Project object]: Organization or Project object. Not necessary if StarkBank.user was set before function call
     #
     # ## Return:
     # - generator of DitcKey objects with updated attributes
     def self.query(limit: nil, type: nil, after: nil, before: nil, ids: nil, status: nil, user: nil)
       after = StarkBank::Utils::Checks.check_date(after)
       before = StarkBank::Utils::Checks.check_date(before)
-      StarkBank::Utils::Rest.get_list(
+      StarkBank::Utils::Rest.get_stream(
+        limit: limit,
+        type: type,
+        after: after,
+        before: before,
+        ids: ids,
+        status: status,
+        user: user,
+        **resource
+      )
+    end
+
+    # # Retrieve paged DictKeys
+    #
+    # Receive a list of up to 100 DictKey objects previously created in the Stark Bank API and the cursor to the next page.
+    # Use this function instead of query if you want to manually page your requests.
+    #
+    # ## Parameters (optional):
+    # - cursor [string, default nil]: cursor returned on the previous page function call
+    # - limit [integer, default nil]: maximum number of objects to be retrieved. Unlimited if nil. ex: 35
+    # - type [string, default nil]: DictKey type. ex: 'cpf', 'cnpj', 'phone', 'email' or 'evp'
+    # - after [Date, DateTime, Time or string, default nil]: date filter for objects created only after specified date. ex: Date.new(2020, 3, 10)
+    # - before [Date, DateTime, Time or string, default nil]: date filter for objects created only before specified date. ex: Date.new(2020, 3, 10)
+    # - ids [list of strings, default nil]: list of ids to filter retrieved objects. ex: ['5656565656565656', '4545454545454545']
+    # - status [string, default nil]: filter for status of retrieved objects. ex: 'canceled', 'registered'
+    # - user [Organization/Project object]: Organization or Project object. Not necessary if StarkBank.user was set before function call
+    #
+    # ## Return:
+    # - list of DictKey objects with updated attributes and cursor to retrieve the next page of DictKey objects
+    def self.page(cursor: nil, limit: nil, type: nil, after: nil, before: nil, ids: nil, status: nil, user: nil)
+      after = StarkBank::Utils::Checks.check_date(after)
+      before = StarkBank::Utils::Checks.check_date(before)
+      return StarkBank::Utils::Rest.get_page(
+        cursor: cursor,
         limit: limit,
         type: type,
         after: after,
@@ -102,6 +137,7 @@ module StarkBank
             name: json['name'],
             tax_id: json['tax_id'],
             owner_type: json['owner_type'],
+            bank_name: json['bank_name'],
             ispb: json['ispb'],
             branch_code: json['branch_code'],
             account_number: json['account_number'],

data/lib/error.rb

@@ -4,7 +4,15 @@ require('json')
 
 module StarkBank
   module Error
-    class Error < StandardError
+    class StarkBankError < StandardError
+      attr_reader :message
+      def initialize(message)
+        @message = message
+        super(message)
+      end
+    end
+
+    class Error < StarkBankError
       attr_reader :code, :message
       def initialize(code, message)
         @code = code
@@ -13,7 +21,7 @@ module StarkBank
       end
     end
 
-    class InputErrors < StandardError
+    class InputErrors < StarkBankError
       attr_reader :errors
       def initialize(content)
         errors = []
@@ -26,19 +34,19 @@ module StarkBank
       end
     end
 
-    class InternalServerError < StandardError
+    class InternalServerError < StarkBankError
       def initialize(message = 'Houston, we have a problem.')
         super(message)
       end
     end
 
-    class UnknownError < StandardError
+    class UnknownError < StarkBankError
       def initialize(message)
         super("Unknown exception encountered: #{message}")
       end
     end
 
-    class InvalidSignatureError < StandardError
+    class InvalidSignatureError < StarkBankError
     end
   end
 end

data/lib/event/attempt.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require_relative('../utils/resource')
+require_relative('../utils/rest')
+require_relative('../utils/checks')
+require_relative('event')
+
+module StarkBank
+  class Event
+    # # Event::Attempt object
+    #
+    # When an Event delivery fails, an event attempt will be registered.
+    # It carries information meant to help you debug event reception issues.
+    #
+    # ## Attributes:
+    # - id [string]: unique id that identifies the delivery attempt. ex: "5656565656565656"
+    # - code [string]: delivery error code. ex: badHttpStatus, badConnection, timeout
+    # - message [string]: delivery error full description. ex: "HTTP POST request returned status 404"
+    # - event_id [string]: ID of the Event whose delivery failed. ex: "4848484848484848"
+    # - webhook_id [string]: ID of the Webhook that triggered this event. ex: "5656565656565656"
+    # - created [DateTime]: creation datetime for the log. ex: DateTime.new(2020, 3, 10, 10, 30, 0, 0)
+    class Attempt < StarkBank::Utils::Resource
+      attr_reader :id, :code, :message, :event_id, :webhook_id, :created
+      def initialize(id:, code:, message:, event_id:, webhook_id:, created:)
+        super(id)
+        @code = code
+        @message = message
+        @event_id = event_id
+        @webhook_id = webhook_id
+        @created = StarkBank::Utils::Checks.check_datetime(created)
+      end
+
+      # # Retrieve a specific Event::Attempt
+      #
+      # Receive a single Event::Attempt object previously created by the Stark Bank API by its id
+      #
+      # ## Parameters (required):
+      # - id [string]: object unique id. ex: '5656565656565656'
+      #
+      # ## Parameters (optional):
+      # - user [Organization/Project object]: Organization or Project object. Not necessary if StarkBank.user was set before function call
+      #
+      # ## Return:
+      # - Event::Attempt object with updated attributes
+      def self.get(id, user: nil)
+        StarkBank::Utils::Rest.get_id(id: id, user: user, **resource)
+      end
+
+      # # Retrieve Event::Attempts
+      #
+      # Receive a generator of Event::Attempt objects previously created in the Stark Bank API
+      #
+      # ## Parameters (optional):
+      # - limit [integer, default nil]: maximum number of objects to be retrieved. Unlimited if nil. ex: 35
+      # - after [Date, DateTime, Time or string, default nil]: date filter for objects created only after specified date. ex: Date.new(2020, 3, 10)
+      # - before [Date, DateTime, Time or string, default nil]: date filter for objects created only before specified date. ex: Date.new(2020, 3, 10)
+      # - event_ids [list of strings, default None]: list of Event ids to filter attempts. ex: ["5656565656565656", "4545454545454545"]
+      # - webhook_ids [list of strings, default None]: list of Webhook ids to filter attempts. ex: ["5656565656565656", "4545454545454545"]
+      # - user [Organization/Project object]: Organization or Project object. Not necessary if StarkBank.user was set before function call
+      #
+      # ## Return:
+      # - generator of Event::Attempt objects with updated attributes
+      def self.query(limit: nil, after: nil, before: nil, event_ids: nil, webhook_ids: nil, user: nil)
+        after = StarkBank::Utils::Checks.check_date(after)
+        before = StarkBank::Utils::Checks.check_date(before)
+        StarkBank::Utils::Rest.get_stream(
+          limit: limit,
+          after: after,
+          before: before,
+          event_ids: event_ids,
+          webhook_ids: webhook_ids,
+          user: user,
+          **resource
+        )
+      end
+
+      # # Retrieve paged Attempts
+      #
+      # Receive a list of up to 100 Attempt objects previously created in the Stark Bank API and the cursor to the next page.
+      # Use this function instead of query if you want to manually page your requests.
+      #
+      # ## Parameters (optional):
+      # - cursor [string, default nil]: cursor returned on the previous page function call
+      # - limit [integer, default nil]: maximum number of objects to be retrieved. Unlimited if nil. ex: 35
+      # - after [Date, DateTime, Time or string, default nil]: date filter for objects created only after specified date. ex: Date.new(2020, 3, 10)
+      # - before [Date, DateTime, Time or string, default nil]: date filter for objects created only before specified date. ex: Date.new(2020, 3, 10)
+      # - event_ids [list of strings, default None]: list of Event ids to filter attempts. ex: ["5656565656565656", "4545454545454545"]
+      # - webhook_ids [list of strings, default None]: list of Webhook ids to filter attempts. ex: ["5656565656565656", "4545454545454545"]
+      # - user [Organization/Project object]: Organization or Project object. Not necessary if StarkBank.user was set before function call
+      #
+      # ## Return:
+      # - list of Attempt objects with updated attributes and cursor to retrieve the next page of Attempt objects
+      def self.page(cursor: nil, limit: nil, after: nil, before: nil, event_ids: nil, webhook_ids: nil, user: nil)
+        after = StarkBank::Utils::Checks.check_date(after)
+        before = StarkBank::Utils::Checks.check_date(before)
+        return StarkBank::Utils::Rest.get_page(
+          cursor: cursor,
+          limit: limit,
+          after: after,
+          before: before,
+          event_ids: event_ids,
+          webhook_ids: webhook_ids,
+          user: user,
+          **resource
+        )
+      end
+
+      def self.resource
+        {
+          resource_name: 'EventAttempt',
+          resource_maker: proc { |json|
+            Attempt.new(
+              id: json['id'],
+              code: json['code'],
+              message: json['message'],
+              event_id: json['event_id'],
+              webhook_id: json['webhook_id'],
+              created: json['created']
+            )
+          }
+        }
+      end
+    end
+  end
+end

data/lib/event/event.rb

@@ -15,6 +15,8 @@ require_relative('../brcode_payment/log')
 require_relative('../transfer/log')
 require_relative('../boleto_payment/log')
 require_relative('../utility_payment/log')
+require_relative('../tax_payment/log')
+require_relative('../darf_payment/log')
 
 module StarkBank
   # # Webhook Event object
@@ -28,13 +30,15 @@ module StarkBank
   # - log [Log]: a Log object from one the subscription services (TransferLog, InvoiceLog, BoletoLog, BoletoPaymentlog or UtilityPaymentLog)
   # - created [DateTime]: creation datetime for the notification event. ex: DateTime.new(2020, 3, 10, 10, 30, 0, 0)
   # - is_delivered [bool]: true if the event has been successfully delivered to the user url. ex: False
+  # - workspace_id [string]: ID of the Workspace that generated this event. Mostly used when multiple Workspaces have Webhooks registered to the same endpoint. ex: '4545454545454545'
   # - subscription [string]: service that triggered this event. ex: 'transfer', 'utility-payment'
   class Event < StarkBank::Utils::Resource
-    attr_reader :id, :log, :created, :is_delivered, :subscription
-    def initialize(id:, log:, created:, is_delivered:, subscription:)
+    attr_reader :id, :log, :created, :is_delivered, :workspace_id, :subscription
+    def initialize(id:, log:, created:, is_delivered:, workspace_id:, subscription:)
       super(id)
       @created = StarkBank::Utils::Checks.check_datetime(created)
       @is_delivered = is_delivered
+      @workspace_id = workspace_id
       @subscription = subscription
 
       resource = {
@@ -45,6 +49,8 @@ module StarkBank
         'boleto': StarkBank::Boleto::Log.resource,
         'boleto-payment': StarkBank::BoletoPayment::Log.resource,
         'utility-payment': StarkBank::UtilityPayment::Log.resource,
+        'tax-payment': StarkBank::TaxPayment::Log.resource,
+        'darf-payment': StarkBank::DarfPayment::Log.resource,
         'boleto-holmes': StarkBank::BoletoHolmes::Log.resource
       }[subscription.to_sym]
 
@@ -77,14 +83,14 @@ module StarkBank
     # - after [Date, DateTime, Time or string, default nil]: date filter for objects created only after specified date. ex: Date.new(2020, 3, 10)
     # - before [Date, DateTime, Time or string, default nil]: date filter for objects created only before specified date. ex: Date.new(2020, 3, 10)
     # - is_delivered [bool, default nil]: bool to filter successfully delivered events. ex: True or False
-    # - user [Organization/Project object]: Organization or Project object. Not necessary if Starkbank.user was set before function call
+    # - user [Organization/Project object]: Organization or Project object. Not necessary if StarkBank.user was set before function call
     #
     # ## Return:
     # - generator of Event objects with updated attributes
     def self.query(limit: nil, after: nil, before: nil, is_delivered: nil, user: nil)
       after = StarkBank::Utils::Checks.check_date(after)
       before = StarkBank::Utils::Checks.check_date(before)
-      StarkBank::Utils::Rest.get_list(
+      StarkBank::Utils::Rest.get_stream(
         user: user,
         limit: limit,
         after: after,
@@ -94,6 +100,35 @@ module StarkBank
       )
     end
 
+    # # Retrieve paged Events
+    #
+    # Receive a list of up to 100 Event objects previously created in the Stark Bank API and the cursor to the next page.
+    # Use this function instead of query if you want to manually page your requests.
+    #
+    # ## Parameters (optional):
+    # - cursor [string, default nil]: cursor returned on the previous page function call
+    # - limit [integer, default nil]: maximum number of objects to be retrieved. Unlimited if nil. ex: 35
+    # - after [Date, DateTime, Time or string, default nil]: date filter for objects created only after specified date. ex: Date.new(2020, 3, 10)
+    # - before [Date, DateTime, Time or string, default nil]: date filter for objects created only before specified date. ex: Date.new(2020, 3, 10)
+    # - is_delivered [bool, default nil]: bool to filter successfully delivered events. ex: True or False
+    # - user [Organization/Project object]: Organization or Project object. Not necessary if StarkBank.user was set before function call
+    #
+    # ## Return:
+    # - list of Event objects with updated attributes and cursor to retrieve the next page of Event objects
+    def self.page(cursor: nil, limit: nil, after: nil, before: nil, is_delivered: nil, user: nil)
+      after = StarkBank::Utils::Checks.check_date(after)
+      before = StarkBank::Utils::Checks.check_date(before)
+      return StarkBank::Utils::Rest.get_page(
+        cursor: cursor,
+        limit: limit,
+        after: after,
+        before: before,
+        is_delivered: is_delivered,
+        user: user,
+        **resource
+      )
+    end
+
     # # Delete a notification Event
     #
     # Delete a of notification Event entity previously created in the Stark Bank API by its ID
@@ -185,6 +220,7 @@ module StarkBank
               log: json['log'],
               created: json['created'],
               is_delivered: json['is_delivered'],
+              workspace_id: json['workspace_id'],
               subscription: json['subscription']
             )
           }

data/lib/institution/institution.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative('../utils/sub_resource')
+require_relative('../utils/rest')
+require_relative('../utils/checks')
+
+module StarkBank
+  # # Institution object
+  #
+  # This resource is used to get information on the institutions that are recognized by the Brazilian Central Bank.
+  # Besides the display name and full name, they also include the STR code (used for TEDs) and the SPI Code
+  # (used for Pix) for the institutions. Either of these codes may be empty if the institution is not registered on
+  # that Central Bank service.
+  #
+  # ## Attributes (return-only):
+  # - display_name [string]: short version of the institution name that should be displayed to end users. ex: 'Stark Bank'
+  # - name [string]: full version of the institution name. ex: 'Stark Bank S.A.'
+  # - spi_code [string]: SPI code used to identify the institution on Pix transactions. ex: '20018183'
+  # - str_code [string]: STR code used to identify the institution on TED transactions. ex: '123'
+  class Institution < StarkBank::Utils::SubResource
+    attr_reader :display_name, :name, :spi_code, :str_code
+    def initialize(display_name: nil, name: nil, spi_code: nil, str_code: nil)
+      @display_name = display_name
+      @name = name
+      @spi_code = spi_code
+      @str_code = str_code
+    end
+
+    # # Retrieve Bacen Institutions
+    #
+    # Receive a list of Institution objects that are recognized by the Brazilian Central bank for Pix and TED transactions
+    #
+    # ## Parameters (optional):
+    # - limit [integer, default nil]: maximum number of objects to be retrieved. Unlimited if nil. ex: 35
+    # - search [string, default nil]: part of the institution name to be searched. ex: 'stark'
+    # - spi_codes [list of strings, default nil]: list of SPI (Pix) codes to be searched. ex: ['20018183']
+    # - str_codes [list of strings, default nil]: list of STR (TED) codes to be searched. ex: ['260']
+    # - user [Organization/Project object]: Organization or Project object. Not necessary if StarkBank.user was set before function call
+    #
+    # ## Return:
+    # - list of Institution objects with updated attributes
+    def self.query(limit: nil, search: nil, spi_codes: nil, str_codes: nil, user: nil)
+      StarkBank::Utils::Rest.get_page(
+          limit: limit,
+          search: search, 
+          spi_codes: spi_codes, 
+          str_codes: str_codes,
+          user: user,
+          **resource
+      ).first
+    end
+
+    def self.resource
+      {
+        resource_name: 'Institution',
+        resource_maker: proc { |json|
+          Institution.new(      
+            display_name: json['display_name'],
+            name: json['name'],
+            spi_code: json['spi_code'],
+            str_code: json['str_code']
+          )
+        }
+      }
+    end
+  end
+end