bridgeapi_client 1.0.1

data/lib/bridge_api/api/client.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+require "bridge_api/api/error"
+
+module BridgeApi
+  module API
+    #
+    # Allows to request the Bridge API using Ruby native net/http library
+    #
+    class Client
+      HTTP_VERBS_MAP = {
+        get: Net::HTTP::Get,
+        post: Net::HTTP::Post,
+        put: Net::HTTP::Put,
+        delete: Net::HTTP::Delete
+      }.freeze
+
+      attr_accessor :access_token
+
+      #
+      # Handles a GET request
+      #
+      # @param [String] path the API endpoint PATH to query
+      # @param [Hash] params any params that might be required (or optional) to communicate with the API
+      #
+      # @return [Hash] the parsed API response
+      #
+      # @raise [API::Error] expectation if API responding with any error
+      #
+      def get(path, **params)
+        request :get, path, params
+      end
+
+      #
+      # Handles a POST request
+      #
+      # @param (see #get)
+      #
+      # @return (see #get)
+      #
+      # @raise (see #get)
+      #
+
+      def post(path, **params)
+        request :post, path, params
+      end
+
+      #
+      # Handles a PUT request
+      #
+      # @param (see #get)
+      #
+      # @return (see #get)
+      #
+      # @raise (see #get)
+      #
+      def put(path, **params)
+        request :put, path, params
+      end
+
+      #
+      # Handles a DELETE request
+      #
+      # @param (see #get)
+      #
+      # @return (see #get)
+      #
+      # @raise (see #get)
+      #
+      def delete(path, **params)
+        request :delete, path, params
+      end
+
+      private
+
+      def request(method, path, params = {})
+        make_http_request do
+          if !method.in?(%i(get delete))
+            HTTP_VERBS_MAP[method].new(path, headers).tap do |request|
+              request.body = params.to_json 
+            end
+          else
+            HTTP_VERBS_MAP[method].new(encode_path(path, params), headers)
+          end
+        end
+      end
+
+      def make_http_request
+        Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
+          http.set_debug_output($stdout) if debug?
+
+          request = yield
+
+          if debug?
+            puts "\n--- BRIDGE API REQUEST ---"
+            puts "#{request.method} #{uri}#{request.path}"
+            request.each_header { |k, v| puts "  #{k}: #{v}" }
+            puts "  Body: #{request.body.inspect}" if request.body
+            puts "--------------------------\n"
+          end
+
+          api_response = http.request(request)
+
+          if debug?
+            puts "--- BRIDGE API RESPONSE #{api_response.code} ---"
+            puts api_response.body
+            puts "-------------------------------\n"
+          end
+
+          case api_response.code
+          when "200", "201"
+            data = parse_response_body(api_response.body)
+
+            if data.dig(:pagination, :next_uri) && follow_pages
+              handle_paging(data)
+            else
+              data
+            end
+          when "204", "202"
+            {}
+          else
+            handle_error(api_response)
+          end
+        end
+      end
+
+      def parse_response_body(json_response_body)
+        JSON.parse(json_response_body, symbolize_names: true)
+      end
+
+      def uri
+        @uri ||= URI.parse(BridgeApi.configuration.api_base_url)
+      end
+
+      def follow_pages
+        BridgeApi.configuration.follow_pages
+      end
+
+      def debug?
+        BridgeApi.configuration.debug
+      end
+
+      def handle_paging(data)
+        page_uri = URI.parse(data[:pagination][:next_uri])
+        params = URI.decode_www_form(page_uri.query).to_h
+
+        next_page_data = get(page_uri.path, **params)
+
+        next_page_data[:resources] = data[:resources] + next_page_data[:resources]
+        next_page_data
+      end
+
+      def headers
+        headers =
+          {
+            "Bridge-Version" => BridgeApi.configuration.api_version,
+            "Client-Id" => BridgeApi.configuration.api_client_id,
+            "Client-Secret" => BridgeApi.configuration.api_client_secret,
+            "Content-Type" => "application/json",
+            "Accept" => "application/json"
+          }
+
+        return headers unless access_token
+
+        headers.merge!("Authorization" => "Bearer #{access_token}")
+      end
+
+      def encode_path(path, params = nil)
+        URI::HTTP
+          .build(path: path, query: URI.encode_www_form(params))
+          .request_uri
+      end
+
+      def handle_error(api_response)
+        response_body = parse_response_body(api_response.body)
+
+        case api_response.code
+        when "400"
+          raise API::BadRequestError.new(api_response.code, response_body)
+        when "401"
+          raise API::UnauthorizedError.new(api_response.code, response_body)
+        when "403"
+          raise API::ForbiddenError.new(api_response.code, response_body)
+        when "404"
+          raise API::NotFoundError.new(api_response.code, response_body)
+        when "409"
+          raise API::ConflictError.new(api_response.code, response_body)
+        when "415"
+          raise API::UnsupportedMediaTypeError.new(api_response.code, response_body)
+        when "422"
+          raise API::UnprocessableEntityError.new(api_response.code, response_body)
+        when "429"
+          raise API::TooManyRequestsError.new(api_response.code, response_body)
+        when "500"
+          raise API::InternalServerError.new(api_response.code, response_body)
+        else
+          raise API::Error.new(api_response.code, response_body)
+        end
+      end
+    end
+  end
+end

data/lib/bridge_api/api/error.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module BridgeApi
+  module API
+    #
+    # Error is the base error from which all other more specific BridgeApi errors derive.
+    #
+    class Error < StandardError
+      #
+      # Initializes Error
+      #
+      # @param [String] code the HTTP code returned by the API
+      # @param [Hash] response_body the parsed API response
+      # @option response_body [String] :type 	the machine readable error message
+      # @option response_body [String] :message the human readable error message
+      # @option response_body [String] :documentation_url the optional link to documentation
+      #
+      def initialize(code, response_body = {})
+        @payload = response_body
+        @code = code
+        @type = payload[:type]
+        @documentation_url = payload[:documentation_url]
+
+        super(payload[:message])
+      end
+
+      attr_reader :payload, :code, :type, :documentation_url
+    end
+
+    class BadRequestError < Error; end
+
+    class UnauthorizedError < Error; end
+
+    class ForbiddenError < Error; end
+
+    class NotFoundError < Error; end
+
+    class ConflictError < Error; end
+
+    class UnsupportedMediaTypeError < Error; end
+
+    class UnprocessableEntityError < Error; end
+
+    class TooManyRequestsError < Error; end
+
+    class InternalServerError < Error; end
+  end
+end

data/lib/bridge_api/api/resource.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module BridgeApi
+  module API
+    #
+    # Extend any resource class with API specific methods
+    #
+    module Resource
+      private
+
+      def protected_resource(access_token)
+        client = API::Client.new
+        client.access_token = access_token
+        Thread.current[:bridge_api_api_client] = client
+        yield
+      ensure
+        Thread.current[:bridge_api_api_client] = nil
+      end
+
+      def api_client
+        Thread.current[:bridge_api_api_client] || API::Client.new
+      end
+    end
+  end
+end

data/lib/bridge_api/authorization.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "time"
+
+module BridgeApi
+  #
+  # User authentication & authorization
+  #
+  class Authorization
+    attr_reader :access_token, :expires_at
+
+    #
+    # Initializes Authorization
+    #
+    # @param [String] access_token access token the access token provided by the API
+    # @param [Time] expires_at the expiration time for the provided access token
+    #
+    def initialize(access_token, expires_at)
+      @access_token = access_token
+      @expires_at = Time.parse(expires_at)
+    end
+
+    class << self
+      include API::Resource
+
+      #
+      # Generate an access token for a Bridge user
+      #
+      # @param [String] user_uuid the Bridge user UUID
+      # @param [String] external_user_id the external user identifier (alternative to user_uuid)
+      #
+      # @return [Authorization] the authorization informations provided by the API
+      #
+      def generate_token(user_uuid: nil, external_user_id: nil)
+        params = {}
+        params[:user_uuid] = user_uuid if user_uuid
+        params[:external_user_id] = external_user_id if external_user_id
+
+        response = api_client.post("/v3/aggregation/authorization/token", **params)
+        new(response[:access_token], response[:expires_at])
+      end
+    end
+  end
+end

data/lib/bridge_api/bank.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module BridgeApi
+  #
+  # Bank resource is deprecated, using Provider instead
+  #
+  class Bank < Provider
+    def self.list(**params)
+      warn "BridgeApi::Bank is deprecated. Use BridgeApi::Provider instead."
+      super
+    end
+
+    def self.find(id:, **params)
+      warn "BridgeApi::Bank is deprecated. Use BridgeApi::Provider instead."
+      super
+    end
+  end
+end

data/lib/bridge_api/bridge_object.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module BridgeApi
+  #
+  # BridgeObject is the base class from which all other more specific BridgeApi resources derive.
+  #
+  class BridgeObject
+    HIDDEN_ATTRIBUTES = %i[resource_type resource_uri].freeze
+
+    #
+    # Initializes BridgeObject
+    #
+    # @param [Hash] attrs any informations returned by the API as a valid response
+    #
+    def initialize(**attrs)
+      define_instance_variables(attrs)
+    end
+
+    class << self
+      #
+      # Convert any API response body with its corresponding resource object if exists
+      #
+      # @param [Hash] data parsed API response body
+      #
+      # @return [Account, Bank, Category, Item, Stock, Transaction, Transfer, User, BridgeObject] a resource object
+      #
+      def convert_to_bridge_object(data)
+        if data[:resources]
+          data[:resources].map { |resource| convert_to_bridge_object(resource) }
+        elsif data.is_a?(Array)
+          data.map { |val| convert_to_bridge_object(val) }
+        else
+          object_from_resource_type(data)
+        end
+      end
+
+      private
+
+      def object_classes
+        @object_classes ||= ObjectTypes.resource_types_to_classes
+      end
+
+      def object_from_resource_type(data)
+        object_classes.fetch(data[:resource_type], BridgeObject).new(**data)
+      end
+    end
+
+    def to_hash
+      instance_variables.each_with_object({}) do |var, hash|
+        hash[var.to_s.delete("@")] =
+          case instance_variable_get(var)
+          when BridgeObject
+            instance_variable_get(var).to_hash
+          when Array
+            instance_variable_get(var).map { |val| val.is_a?(BridgeObject) ? val.to_hash : val }
+          else
+            instance_variable_get(var)
+          end
+      end.transform_keys!(&:to_sym)
+    end
+
+    def to_json(*_args)
+      to_hash.to_json
+    end
+
+    def ==(other)
+      other.is_a?(BridgeObject) && to_hash == other.to_hash
+    end
+
+    private
+
+    def define_instance_variables(attrs)
+      attrs.each do |key, value|
+        next if HIDDEN_ATTRIBUTES.include?(key)
+
+        handle_values_types(key, value) do |parsed_value|
+          instance_variable_set(:"@#{key}", parsed_value)
+          self.class.class_eval { attr_reader key }
+        end
+      end
+    end
+
+    def handle_values_types(key, value)
+      yield(
+        case value
+        when Array
+          handle_array_values(value)
+        when Hash
+          handle_hash_values(value)
+        when String
+          handle_time_values(key, value)
+        else
+          value
+        end
+      )
+    end
+
+    def handle_array_values(array)
+      array.map do |value|
+        next value unless value.is_a?(Hash)
+
+        handle_hash_values(value)
+      end
+    end
+
+    def handle_hash_values(hash)
+      self.class.convert_to_bridge_object(hash)
+    end
+
+    def handle_time_values(key, value)
+      if key == :date
+        Date.parse(value)
+      elsif key.to_s.match?(/_at$/)
+        Time.parse(value)
+      else
+        value
+      end
+    end
+  end
+end

data/lib/bridge_api/category.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module BridgeApi
+  #
+  # Category resource
+  #
+  class Category < BridgeObject
+    RESOURCE_TYPE = "category"
+
+    class << self
+      include API::Resource
+
+      #
+      # List all categories supported by the Bridge API
+      #
+      # @param [Hash] params any params that might be required (or optional) to communicate with the API
+      #
+      # @return [Array<Category>] the supported categories list
+      #
+      def list(**params)
+        data = api_client.get("/v3/aggregation/categories", **params)
+        convert_to_bridge_object(**data)
+      end
+
+      #
+      # Retrieve a single category
+      #
+      # @param [Integer] id the id of the requested resource
+      # @param [Hash] params any params that might be required (or optional) to communicate with the API
+      #
+      # @return [Category] the requested category
+      #
+      def find(id:, **params)
+        data = api_client.get("/v3/aggregation/categories/#{id}", **params)
+        convert_to_bridge_object(**data)
+      end
+    end
+  end
+end

data/lib/bridge_api/configuration.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+#
+# BridgeApi module
+#
+module BridgeApi
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configuration=(config)
+    @configuration = config
+  end
+
+  def self.configure
+    yield configuration
+  end
+
+  #
+  # Configurations setup
+  #
+  class Configuration
+    attr_reader :api_base_url, :api_version
+    attr_accessor :api_client_id, :api_client_secret, :follow_pages, :debug
+
+    #
+    # Initializes Configuration
+    #
+    def initialize
+      @api_base_url = "https://api.bridgeapi.io"
+      @api_version = "2025-01-15"
+      @api_client_id = ""
+      @api_client_secret = ""
+      @follow_pages = false
+      @debug = false
+    end
+  end
+end

data/lib/bridge_api/connect.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module BridgeApi
+  #
+  # Connect resource
+  #
+  class Connect < BridgeObject
+    class << self
+      include API::Resource
+
+      #
+      # Create a Connect session (replaces all old connect methods)
+      #
+      # @param [String] access_token the access token provided during the user authentication
+      # @param [Hash] params any params that might be required (or optional) to communicate with the API
+      #
+      # @return [BridgeObject] Connect session with redirect_url
+      #
+      def create_session(access_token:, **params)
+        protected_resource(access_token) do
+          data = api_client.post("/v3/aggregation/connect-sessions", **params)
+          convert_to_bridge_object(**data)
+        end
+      end
+
+      # Deprecated methods - kept for backward compatibility
+      
+      def connect_item(access_token:, **params)
+        warn "BridgeApi::Connect.connect_item is deprecated. Use BridgeApi::Connect.create_session instead."
+        create_session(access_token: access_token, **params)
+      end
+
+      def connect_item_with_iban(access_token:, **params)
+        warn "BridgeApi::Connect.connect_item_with_iban is deprecated. Use BridgeApi::Connect.create_session instead."
+        create_session(access_token: access_token, **params)
+      end
+
+      def edit_item(access_token:, **params)
+        warn "BridgeApi::Connect.edit_item is deprecated. Use BridgeApi::Connect.create_session instead."
+        create_session(access_token: access_token, **params)
+      end
+
+      def item_sync(access_token:, **params)
+        warn "BridgeApi::Connect.item_sync is deprecated. Use BridgeApi::Connect.create_session instead."
+        create_session(access_token: access_token, **params)
+      end
+
+      def validate_email(access_token:, **params)
+        warn "BridgeApi::Connect.validate_email is deprecated. Use BridgeApi::Connect.create_session instead."
+        create_session(access_token: access_token, **params)
+      end
+
+      def validate_pro_items(access_token:, **params)
+        warn "BridgeApi::Connect.validate_pro_items is deprecated. Use BridgeApi::Connect.create_session instead."
+        create_session(access_token: access_token, **params)
+      end
+    end
+  end
+end

data/lib/bridge_api/insight.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module BridgeApi
+  #
+  # Insight resource
+  #
+  class Insight < BridgeObject
+    class << self
+      include API::Resource
+
+      #
+      # Categories statistics provided by Bridge
+      #
+      # @param [String] access_token the access token provided during the user authentication
+      # @param [Hash] params any params that might be required (or optional) to communicate with the API
+      #
+      # @return [Insight] the statistics generated by Bridge API
+      #
+      def categories_insights(access_token:, **params)
+        protected_resource(access_token) do
+          data = api_client.get("/v3/aggregation/insights/category", **params)
+          convert_to_bridge_object(**data)
+        end
+      end
+    end
+  end
+end