pluggy-rb 0.1.0

data/lib/pluggy/api_requestor.rb

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "zlib"
+require "stringio"
+require "bigdecimal"
+
+module Pluggy
+  # Builds, sends and interprets every HTTP request.
+  #
+  # Owns three things worth understanding: the apiKey lifecycle, the 403 fork,
+  # and the retry policy.
+  class APIRequestor
+    IDEMPOTENT_METHODS = %i[get head delete].freeze
+
+    # POST endpoints that are safe to retry because they create no durable
+    # resource. POST /items is NOT here on purpose: the API offers no
+    # Idempotency-Key, so retrying it risks opening a duplicate bank
+    # connection, which is user-visible and awkward to undo.
+    RETRYABLE_POST_PATHS = ["/auth", "/connect_token"].freeze
+
+    RETRY_STATUSES = [429, 500, 502, 503, 504].freeze
+
+    RETRY_ERRORS = [
+      Errno::ECONNRESET, Errno::ECONNREFUSED, Errno::EPIPE, Errno::EHOSTUNREACH,
+      Errno::ETIMEDOUT, Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout,
+      EOFError, SocketError, IOError, OpenSSL::SSL::SSLError
+    ].freeze
+
+    attr_reader :config, :credentials
+
+    def initialize(config, credentials = nil)
+      @config = config
+      @credentials = credentials || CredentialStore.new(config)
+    end
+
+    # --- surface used by services ------------------------------------------
+
+    def request(method, path, params: nil, body: nil, opaque_body_keys: [])
+      url = build_path(path, params)
+      payload = body && Util.encode_body(body, opaque: opaque_body_keys)
+      execute(method, url, payload, authenticated: true)
+    end
+
+    # For cursor pagination: `path_with_query` already carries the server's
+    # "?..." string, so no query building happens at all.
+    def request_raw(method, path_with_query)
+      execute(method, path_with_query, nil, authenticated: true)
+    end
+
+    # POST /auth is the only unauthenticated operation in the API.
+    def execute_unauthenticated(method, path, body: nil)
+      execute(method, path, body, authenticated: false)
+    end
+
+    def list(path, params:, klass:, client:, paginated: false)
+      Lists.wrap(
+        request(:get, path, params: params),
+        klass: klass, requestor: self, path: path,
+        filters: params || {}, client: client, paginated: paginated
+      )
+    end
+
+    def list_raw(path_with_query, klass:, client:)
+      Lists.wrap(
+        request_raw(:get, path_with_query),
+        klass: klass, requestor: self, path: path_with_query.split("?").first, client: client
+      )
+    end
+
+    # --- internals ---------------------------------------------------------
+
+    private
+
+    def execute(method, path, payload, authenticated:)
+      attempts = 0
+      reauthed = false
+
+      loop do
+        key = authenticated ? @credentials.fetch(self) : nil
+
+        response = attempt(method, path, payload, key) do |error|
+          attempts += 1
+          raise wrap_connection_error(error) unless retryable?(method, path, attempts)
+
+          backoff(attempts, nil)
+        end
+        next if response.nil? # transport failure, already backed off
+
+        status = response.code.to_i
+        parsed = parse_body(response)
+
+        return parsed if status < 300
+
+        if renew_and_retry?(status, response, parsed, authenticated: authenticated, reauthed: reauthed)
+          @config.log(:info, "apiKey rejected, renewing", path: path)
+          @credentials.refresh!(self, stale: key)
+          reauthed = true
+          next
+        end
+
+        attempts += 1
+        if RETRY_STATUSES.include?(status) && retryable?(method, path, attempts)
+          backoff(attempts, response["retry-after"])
+          next
+        end
+
+        raise build_error(status, response, parsed, reauthed: reauthed)
+      end
+    end
+
+    # Returns the response, or nil when the request died at the transport level
+    # and should be retried. The block decides whether a retry is allowed (it
+    # raises if not) and applies the backoff.
+    def attempt(method, path, payload, key)
+      perform_logged(method, path, payload, key)
+    rescue *RETRY_ERRORS => e
+      # A half-dead keep-alive socket would poison the retry.
+      ConnectionManager.current.clear!
+      yield e
+      nil
+    end
+
+    # The 403 fork.
+    #
+    # Only a 403 with NO codeDescription means the apiKey aged out. One that has
+    # a codeDescription (e.g. BALANCE_CONSENT_ERROR) is a domain denial: renewing
+    # would mask it and double every affected call.
+    def renew_and_retry?(status, response, parsed, authenticated:, reauthed:)
+      return false unless status == 403 && authenticated
+      return false unless expired_key?(parsed)
+
+      # Nothing to renew with: say so, rather than reporting it as a permission
+      # problem the caller cannot act on.
+      raise static_key_rejected(status, response, parsed) if @credentials.static?
+
+      !reauthed
+    end
+
+    # NotAuthenticatedResponse is {code, message}; GlobalErrorResponse adds
+    # codeDescription. That difference is the only signal the API gives us.
+    def expired_key?(parsed)
+      parsed.is_a?(Hash) && parsed["codeDescription"].nil?
+    end
+
+    def perform_logged(method, path, payload, key)
+      started = now
+      response = perform(method, path, payload, key)
+      @config.log(:debug, "#{method.to_s.upcase} #{path}",
+        status: response.code, ms: ((now - started) * 1000).round)
+      response
+    end
+
+    def perform(method, path, payload, key)
+      http = ConnectionManager.current.connection_for(@config)
+      request_class = Net::HTTP.const_get(method.to_s.capitalize)
+      req = request_class.new(path, headers(key, payload))
+      req.body = JSON.generate(payload) if payload
+      http.request(req)
+    end
+
+    def headers(key, payload)
+      h = {
+        "Accept" => "application/json",
+        "Accept-Encoding" => "gzip",
+        "User-Agent" => user_agent
+      }
+      h["X-API-KEY"] = key.to_s if key
+      h["Content-Type"] = "application/json" if payload
+      h
+    end
+
+    def user_agent
+      @user_agent ||= [
+        "pluggy-rb/#{Pluggy::VERSION}",
+        "ruby/#{RUBY_VERSION}",
+        "(#{RUBY_PLATFORM})",
+        @config.user_agent_suffix
+      ].compact.join(" ")
+    end
+
+    def build_path(path, params)
+      query = Util.encode_query(params)
+      query.empty? ? path : "#{path}?#{query}"
+    end
+
+    def parse_body(response)
+      raw = response.body.to_s
+      raw = Zlib::GzipReader.new(StringIO.new(raw)).read if response["content-encoding"] == "gzip"
+      return nil if raw.empty?
+
+      # decimal_class reads the lexical digits straight off the wire, so money
+      # never passes through a Float. Integers stay Integer.
+      options = @config.decimal_amounts ? { decimal_class: BigDecimal } : {}
+      JSON.parse(raw, **options)
+    rescue JSON::ParserError, Zlib::Error
+      # A proxy or CDN error page; hand it back for the error builder to show.
+      raw
+    end
+
+    def retryable?(method, path, attempts)
+      return false if attempts > @config.max_network_retries
+
+      idempotent?(method, path)
+    end
+
+    def idempotent?(method, path)
+      return true if IDEMPOTENT_METHODS.include?(method)
+      return RETRYABLE_POST_PATHS.any? { |p| path.start_with?(p) } if method == :post
+
+      # PATCH /items/{id} triggers a re-sync: harmless to repeat, but it queues
+      # redundant work at the institution, so leave it alone.
+      false
+    end
+
+    def backoff(attempts, retry_after)
+      base = @config.initial_network_retry_delay * (2**(attempts - 1))
+      delay = [base, @config.max_network_retry_delay].min
+      delay *= (0.5 + (rand * 0.5)) # jitter: 50-100% of the interval
+
+      # Undocumented in the spec, but honour it when a proxy or the
+      # institution sends one.
+      delay = [retry_after.to_f, delay].max if retry_after.to_s.match?(/\A\d+(\.\d+)?\z/)
+
+      @config.log(:info, "retrying", attempt: attempts, delay: delay.round(3))
+      sleep(delay)
+    end
+
+    def build_error(status, response, parsed, reauthed:)
+      json = parsed.is_a?(Hash) ? parsed : nil
+
+      klass =
+        if status == 403 && reauthed
+          # It survived a renewal, so the key is not the problem.
+          AuthenticationError
+        else
+          Pluggy.error_class_for(status)
+        end
+
+      klass.new(
+        json&.fetch("message", nil),
+        http_status: status,
+        http_body: response.body,
+        http_headers: response.each_header.to_h,
+        json_body: json
+      )
+    end
+
+    def static_key_rejected(status, response, parsed)
+      AuthenticationError.new(
+        "the supplied apiKey was rejected by Pluggy and there are no credentials to renew it " \
+        "with; construct Pluggy::Client with client_id: and client_secret: for automatic renewal",
+        http_status: status,
+        http_body: response.body,
+        http_headers: response.each_header.to_h,
+        json_body: parsed.is_a?(Hash) ? parsed : nil
+      )
+    end
+
+    def wrap_connection_error(error)
+      klass = error.is_a?(Net::OpenTimeout) || error.is_a?(Net::ReadTimeout) ? TimeoutError : ConnectionError
+      klass.new("#{error.class}: #{error.message} (#{@config.api_base})")
+    end
+
+    def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
+end

data/lib/pluggy/api_resource.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Pluggy
+  # Base for the top-level API resources. Adds the client back-reference that
+  # makes navigation (account.transactions, bill.transactions, item.accounts)
+  # possible.
+  #
+  # Objects built by a requestor always carry a client. Objects a caller
+  # constructs by hand do not, so ensure_client! explains that rather than
+  # letting a NoMethodError on nil surface.
+  class APIResource < PluggyObject
+    private
+
+    def ensure_client!
+      return @client if @client
+
+      raise Error,
+        "#{self.class.name}##{caller_locations(1, 1)[0].label} needs a client. This object was " \
+        "built without one; fetch it through Pluggy::Client (e.g. client.accounts.retrieve(id)) " \
+        "to use navigation methods."
+    end
+  end
+end

data/lib/pluggy/client.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Pluggy
+  # The entry point.
+  #
+  #   client = Pluggy::Client.new(
+  #     client_id: ENV["PLUGGY_CLIENT_ID"],
+  #     client_secret: ENV["PLUGGY_CLIENT_SECRET"]
+  #   )
+  #   client.accounts.list(item_id: item_id)
+  #
+  # Authentication is handled for you: the apiKey is fetched lazily on the first
+  # request, cached until the expiry in its own JWT, and renewed transparently
+  # if the API rejects it mid-session.
+  #
+  # One client holds one credential set and is safe to share across threads.
+  class Client
+    attr_reader :config, :requestor
+
+    def initialize(client_id: nil, client_secret: nil, api_key: nil, **options)
+      @config = Pluggy.config.merge(
+        client_id: client_id,
+        client_secret: client_secret,
+        api_key: api_key,
+        **options
+      )
+      @config.validate!
+      @requestor = APIRequestor.new(@config)
+    end
+
+    def accounts = @accounts ||= Services::AccountService.new(self)
+    def transactions = @transactions ||= Services::TransactionService.new(self)
+    def bills = @bills ||= Services::BillService.new(self)
+    def loans = @loans ||= Services::LoanService.new(self)
+    def items = @items ||= Services::ItemService.new(self)
+    def connectors = @connectors ||= Services::ConnectorService.new(self)
+    def categories = @categories ||= Services::CategoryService.new(self)
+    def merchants = @merchants ||= Services::MerchantService.new(self)
+    def connect_tokens = @connect_tokens ||= Services::ConnectTokenService.new(self)
+
+    # The first call most integrations make.
+    def create_connect_token(**kwargs) = connect_tokens.create(**kwargs)
+
+    # The current apiKey, authenticating first if needed. Rarely useful directly
+    # -- mostly for debugging and for the live smoke test.
+    def api_key = @requestor.credentials.fetch(@requestor).to_s
+
+    # Escape hatches for the endpoints this gem deliberately does not model
+    # (payments, smart transfers, boletos, consents, webhooks, investments,
+    # identity). Returns parsed JSON, not resource objects.
+    def get(path, **params) = @requestor.request(:get, path, params: params)
+    def post(path, **body) = @requestor.request(:post, path, body: body)
+    def patch(path, **body) = @requestor.request(:patch, path, body: body)
+    def delete(path, **params) = @requestor.request(:delete, path, params: params)
+
+    def inspect
+      "#<Pluggy::Client client_id=#{@config.client_id.to_s[0, 8]}... api_base=#{@config.api_base}>"
+    end
+    alias to_s inspect
+  end
+end

data/lib/pluggy/configuration.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Pluggy
+  class Configuration
+    DEFAULTS = {
+      api_base: "https://api.pluggy.ai",
+      client_id: nil,
+      client_secret: nil,
+      # A pre-existing apiKey. Disables automatic renewal: there are no
+      # credentials to renew with, so an expiry raises AuthenticationError.
+      api_key: nil,
+      open_timeout: 30,
+      # Generous because GET /accounts/{id}/balance proxies to the financial
+      # institution in real time -- it is the one endpoint in scope that
+      # documents both a 429 and a 502.
+      read_timeout: 80,
+      write_timeout: 30,
+      max_network_retries: 2,
+      initial_network_retry_delay: 0.5,
+      max_network_retry_delay: 4.0,
+      logger: nil,
+      log_level: :info,
+      # Parse JSON numbers as BigDecimal. Turning this off yields plain Floats
+      # and makes the gem dependency-free.
+      decimal_amounts: true,
+      coerce_times: true,
+      user_agent_suffix: nil,
+      verify_ssl_certs: true,
+      # :v2 (cursor, current) or :v1 (offset, deprecated, sunset 2026-12-31).
+      transactions_api_version: :v2
+    }.freeze
+
+    LOG_LEVELS = { debug: 0, info: 1, error: 2 }.freeze
+
+    SECRET_OPTIONS = %i[client_secret api_key].freeze
+
+    DEFAULTS.each_key { |key| attr_accessor key }
+
+    def self.setup
+      new.tap { |config| yield config if block_given? }
+    end
+
+    def initialize(**overrides)
+      DEFAULTS.each { |key, value| instance_variable_set(:"@#{key}", value) }
+      apply(overrides)
+    end
+
+    # Per-client options win over the globals they were merged from, but only
+    # where explicitly given -- Stripe's reverse_duplicate_merge.
+    def merge(**overrides)
+      dup.tap { |config| config.send(:apply, overrides.compact) }
+    end
+
+    def uri
+      @uri ||= URI.parse(api_base)
+    end
+
+    # Net::HTTP pool key: two configs pointing at the same endpoint share a
+    # connection.
+    def connection_key
+      [uri.host, uri.port, verify_ssl_certs]
+    end
+
+    def credentials?
+      !(client_id.nil? || client_secret.nil?)
+    end
+
+    def validate!
+      return if credentials? || api_key
+
+      raise ConfigurationError,
+        "provide client_id: and client_secret: (or api_key:) to Pluggy::Client.new, " \
+        "or set Pluggy.client_id / Pluggy.client_secret"
+    end
+
+    def log(level, message, **context)
+      return unless logger
+      return unless LOG_LEVELS.fetch(level, 1) >= LOG_LEVELS.fetch(log_level, 1)
+
+      suffix = context.map { |k, v| "#{k}=#{v}" }.join(" ")
+      logger.public_send(level, "[pluggy] #{message}#{" #{suffix}" unless suffix.empty?}")
+    end
+
+    # Never leak secrets into a log, a console session or an exception.
+    def inspect
+      shown = DEFAULTS.keys.map do |key|
+        value = public_send(key)
+        value = redact(value) if SECRET_OPTIONS.include?(key)
+        "#{key}=#{value.inspect}"
+      end
+      "#<Pluggy::Configuration #{shown.join(" ")}>"
+    end
+    alias to_s inspect
+
+    private
+
+    def apply(overrides)
+      overrides.each do |key, value|
+        raise ArgumentError, "unknown Pluggy configuration option: #{key}" unless DEFAULTS.key?(key)
+
+        public_send(:"#{key}=", value)
+      end
+      @uri = nil
+    end
+
+    def redact(value)
+      return nil if value.nil?
+
+      "***#{value.to_s[-4..]}"
+    end
+  end
+end

data/lib/pluggy/connection_manager.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+
+module Pluggy
+  # Keep-alive Net::HTTP pool, one instance per thread (Net::HTTP objects are
+  # not thread-safe), keyed by Configuration#connection_key.
+  #
+  # After a fork, sockets inherited from the parent are unusable. Call
+  # Pluggy::ConnectionManager.current.clear! in your after_fork hook
+  # (Puma, Unicorn, Sidekiq).
+  class ConnectionManager
+    def self.current
+      Thread.current[:pluggy_connection_manager] ||= new
+    end
+
+    def initialize
+      @pool = {}
+    end
+
+    def connection_for(config)
+      @pool[config.connection_key] ||= build(config)
+    end
+
+    def clear!
+      @pool.each_value do |http|
+        http.finish if http.started?
+      rescue IOError, SystemCallError
+        # Already dead; nothing to close.
+      end
+      @pool.clear
+    end
+
+    private
+
+    def build(config)
+      uri = config.uri
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.verify_mode = config.verify_ssl_certs ? OpenSSL::SSL::VERIFY_PEER : OpenSSL::SSL::VERIFY_NONE
+      http.open_timeout = config.open_timeout
+      http.read_timeout = config.read_timeout
+      http.write_timeout = config.write_timeout
+      http.keep_alive_timeout = 30
+      http
+    end
+  end
+end

data/lib/pluggy/credential_store.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Pluggy
+  # Holds the current apiKey for one client and renews it as needed.
+  #
+  # One store per Client, so a key is fetched at most once per lifetime
+  # regardless of how many services or threads use it.
+  class CredentialStore
+    def initialize(config)
+      @config = config
+      @mutex = Mutex.new
+      @key = config.api_key ? ApiKey.new(config.api_key) : nil
+      # A caller-supplied key with no credentials behind it cannot be renewed.
+      @static = !config.api_key.nil? && !config.credentials?
+    end
+
+    def static? = @static
+
+    def fetch(requestor)
+      @mutex.synchronize do
+        @key = authenticate(requestor) if @key.nil? || (!@static && @key.expired?)
+        @key
+      end
+    end
+
+    # Called after a 403 whose body carried no codeDescription -- see
+    # APIRequestor#expired_key?.
+    #
+    # `stale` is the key that just failed. If another thread has already
+    # rotated it, reuse theirs rather than authenticating again: N threads
+    # hitting expiry together produce exactly one POST /auth.
+    def refresh!(requestor, stale:)
+      if @static
+        raise AuthenticationError,
+          "the supplied apiKey was rejected and there are no credentials to renew it with; " \
+          "construct Pluggy::Client with client_id: and client_secret: for automatic renewal"
+      end
+
+      @mutex.synchronize do
+        return @key if @key && !@key.equal?(stale)
+
+        @key = authenticate(requestor)
+      end
+    end
+
+    private
+
+    def authenticate(requestor)
+      @config.validate!
+
+      body = requestor.execute_unauthenticated(
+        :post, "/auth",
+        body: { "clientId" => @config.client_id, "clientSecret" => @config.client_secret }
+      )
+
+      unless body.is_a?(Hash) && body["apiKey"]
+        raise AuthenticationError.new("POST /auth succeeded but returned no apiKey", json_body: body)
+      end
+
+      ApiKey.new(body["apiKey"]).tap do |key|
+        @config.log(:info, "authenticated", expires_at: key.expires_at.iso8601)
+      end
+    end
+  end
+end