pluggy-rb 0.1.0

data/lib/pluggy/errors.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Pluggy
+  # Flat, one-level hierarchy off a single base carrying the whole HTTP
+  # transcript. Unlike Stripe there is no request id: the Pluggy spec documents
+  # zero response headers, so nothing reliable exists to capture.
+  class Error < StandardError
+    attr_reader :http_status, :http_body, :http_headers, :json_body,
+      :code, :code_description, :data, :api_message
+
+    def initialize(message = nil, http_status: nil, http_body: nil, http_headers: nil, json_body: nil)
+      @http_status = http_status
+      @http_body = http_body
+      @http_headers = http_headers || {}
+      @json_body = json_body
+
+      if json_body.is_a?(Hash)
+        @code = json_body["code"]
+        @code_description = json_body["codeDescription"]
+        @data = json_body["data"]
+      end
+
+      # The API's own text, undecorated. #message and #to_s append the
+      # codeDescription because that is what you want in a log line; this is
+      # here for when you want to render just the message.
+      @api_message = message || @json_body&.fetch("message", nil) || default_message
+
+      super(@api_message)
+    end
+
+    def to_s
+      @code_description ? "#{@api_message} (#{@code_description})" : @api_message
+    end
+
+    private
+
+    def default_message
+      @http_status ? "Pluggy API returned HTTP #{@http_status}" : "Pluggy API error"
+    end
+  end
+
+  # Raised locally, before any request goes out.
+  class ConfigurationError < Error; end
+
+  # Transport-level: nothing came back, or the socket died.
+  class ConnectionError < Error; end
+  class TimeoutError < ConnectionError; end
+
+  # POST /auth rejected the client keys (CLIENT_KEYS_UNAUTHORIZED,
+  # CLIENT_DISABLED), or an apiKey was rejected and could not be renewed --
+  # either because it survived its one automatic retry, or because the client
+  # was built with a static api_key: and has no credentials to renew with.
+  class AuthenticationError < Error; end
+
+  # A 403 that carries a codeDescription: the request authenticated fine but
+  # was denied on the merits, e.g. BALANCE_CONSENT_ERROR when the institution
+  # refuses to share a balance. Distinct from AuthenticationError because these
+  # must never trigger a re-auth or a retry.
+  class PermissionError < Error; end
+
+  class InvalidRequestError < Error
+    ParameterError = Struct.new(:parameter, :code, :message)
+
+    # POST /items 400 declares `errors: ParameterValidationError[]` in the
+    # schema but every example in the spec emits `details` instead. Read both.
+    def parameter_errors
+      raw = json_body&.values_at("errors", "details")&.compact&.first || []
+      raw.filter_map do |e|
+        next unless e.is_a?(Hash)
+
+        ParameterError.new(e["parameter"], e["code"], e["message"])
+      end
+    end
+
+    # GET /v2/transactions rejects a malformed `after` cursor with a 400.
+    def invalid_cursor?
+      code_description == "invalidCursor" || message.to_s.downcase.include?("cursor")
+    end
+  end
+
+  class NotFoundError < Error; end
+
+  class ConflictError < Error
+    # The ITEM_USER_ALREADY_EXISTS response carries the ids of the items that
+    # already exist for this clientUserId (and omits `code` entirely).
+    def duplicate_item_ids
+      json_body&.fetch("items", nil) || []
+    end
+  end
+
+  class RateLimitError < Error
+    # Undocumented in the spec, so read it opportunistically and never depend
+    # on it. GET /accounts/{id}/balance is the endpoint that documents a 429,
+    # and that limit belongs to the financial institution, not to Pluggy.
+    def retry_after
+      value = http_headers["retry-after"]
+      value&.to_i
+    end
+  end
+
+  # 500
+  class APIError < Error; end
+
+  # 502 -- the financial institution is temporarily unavailable.
+  class BadGatewayError < Error; end
+
+  ERROR_CLASSES = {
+    400 => InvalidRequestError,
+    401 => AuthenticationError,
+    403 => PermissionError,
+    404 => NotFoundError,
+    409 => ConflictError,
+    429 => RateLimitError,
+    500 => APIError,
+    502 => BadGatewayError
+  }.freeze
+
+  # By the time this is consulted the requestor has already resolved the
+  # expired-apiKey case, so a surviving 403 really is a permission problem.
+  def self.error_class_for(status)
+    ERROR_CLASSES.fetch(status) do
+      status >= 500 ? APIError : Error
+    end
+  end
+end

data/lib/pluggy/lists/array_list.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Pluggy
+  module Lists
+    # A bare JSON array with no envelope at all.
+    #
+    # GET /categories declares `{type: array}` in its schema while its own
+    # `example` shows an offset envelope -- the spec contradicts itself. The
+    # shape sniffer in Pluggy::Lists.wrap resolves it at runtime, so a caller
+    # gets a working list either way and never has to care which shipped.
+    class ArrayList < BaseList
+      def initialize(payload, klass:, requestor:, path: nil, filters: {}, client: nil)
+        super
+      end
+
+      def more? = false
+      def next_page = nil
+
+      # Lets an ArrayList be splatted or passed to Array().
+      def to_ary = @results
+    end
+  end
+end

data/lib/pluggy/lists/base_list.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Pluggy
+  module Lists
+    # Shared iteration for all three of Pluggy's pagination shapes. Subclasses
+    # differ only in `more?` and `next_page`.
+    class BaseList
+      include Enumerable
+
+      attr_reader :results, :filters, :path, :raw
+
+      def initialize(payload, klass:, requestor:, path:, filters: {}, client: nil)
+        @raw = payload
+        @klass = klass
+        @requestor = requestor
+        @path = path
+        @filters = filters || {}
+        @client = client
+        @results = extract(payload).map { |item| build(item) }
+      end
+
+      def each(&) = @results.each(&)
+      def empty? = @results.empty?
+      def length = @results.length
+      alias size length
+      alias count length
+
+      def more? = false
+      def next_page = nil
+
+      # Walks every page. Returns an Enumerator when called without a block, so
+      # `.lazy`, `.first(n)` and `.to_a` all work and only fetch the pages they
+      # actually need.
+      def auto_paging_each(&block)
+        return enum_for(:auto_paging_each) unless block_given?
+
+        page = self
+        loop do
+          page.each(&block)
+          break unless page.more?
+
+          page = page.next_page
+          break if page.nil? || page.empty?
+        end
+        self
+      end
+
+      # Every page, eagerly. Convenient, but unbounded -- prefer
+      # auto_paging_each for large histories.
+      def auto_paging_to_a = auto_paging_each.to_a
+
+      def inspect
+        "#<#{self.class.name} results=#{@results.length} more=#{more?}>"
+      end
+
+      private
+
+      def extract(payload)
+        return payload if payload.is_a?(Array)
+
+        payload["results"] || []
+      end
+
+      def build(item)
+        item.is_a?(Hash) ? @klass.new(item, client: @client) : item
+      end
+    end
+  end
+end

data/lib/pluggy/lists/cursor_list.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Pluggy
+  module Lists
+    # The {results, next} envelope -- GET /v2/transactions only, the single
+    # cursor-paginated endpoint in the entire API.
+    #
+    # `next` is a ready-to-use query string including the leading "?" and every
+    # filter, e.g. "?accountId=562b...&after=MjAyMC0x...==", or null when
+    # exhausted. We append it VERBATIM and never parse it back apart:
+    #
+    #   1. The spec says to. It also says that building the request manually
+    #      requires the URL-*decoded* `after` value -- and Ruby cannot decode it
+    #      losslessly, because URI.decode_www_form and CGI.parse both turn a "+"
+    #      into a space. (In practice Pluggy's date|uuid cursors don't seem to
+    #      produce a "+", but there is no reason to stand near that.)
+    #   2. The server has already baked every filter into the string, so
+    #      appending it makes filter propagation correct by construction -- our
+    #      `filters` hash cannot drift from the server's notion of the query.
+    class CursorList < BaseList
+      # The resume token. Persist THIS -- the whole "?..." string -- not a
+      # parsed cursor. See TransactionService#resume.
+      def next_query = @raw.is_a?(Hash) ? @raw["next"] : nil
+      alias next_token next_query
+
+      def more?
+        query = next_query
+        !query.nil? && !query.empty?
+      end
+
+      def next_page
+        return nil unless more?
+
+        query = next_query
+        unless query.start_with?("?")
+          raise Error, "malformed pagination cursor from Pluggy (expected a leading '?'): #{query.inspect}"
+        end
+
+        @requestor.list_raw("#{@path}#{query}", klass: @klass, client: @client)
+      end
+
+      # The bare `after` value, for logging and debugging only. Never used to
+      # build a request -- see the class comment.
+      def next_cursor
+        return nil unless more?
+
+        encoded = next_query.delete_prefix("?")
+                            .split("&")
+                            .find { |pair| pair.start_with?("after=") }
+                            &.delete_prefix("after=")
+        encoded && URI.decode_www_form_component(encoded)
+      end
+    end
+  end
+end

data/lib/pluggy/lists/offset_list.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Pluggy
+  module Lists
+    # The {results, page, total, totalPages} envelope.
+    #
+    # Used by /accounts, /bills, /loans, /connectors, /accounts/{id}/statements
+    # and /transactions (v1) -- but only /transactions and /connectors actually
+    # accept `page`/`pageSize`. The rest return a paged envelope with no
+    # documented way to ask for page 2, so services pass `paginated: false` and
+    # `more?` stays false. auto_paging_each then yields the single page and
+    # stops, rather than issuing a request that would return the same rows.
+    class OffsetList < BaseList
+      # Prose-only default in the spec (no JSON-Schema `default` exists
+      # anywhere), so the SDK has to supply it.
+      DEFAULT_PAGE_SIZE = 500
+      MAX_PAGE_SIZE = 500
+
+      def initialize(payload, paginated: false, **kwargs)
+        @paginated = paginated
+        super(payload, **kwargs)
+      end
+
+      def page = @raw.is_a?(Hash) ? (@raw["page"]&.to_i || 1) : 1
+      def total = @raw.is_a?(Hash) ? @raw["total"]&.to_i : nil
+      def total_pages = @raw.is_a?(Hash) ? (@raw["totalPages"]&.to_i || 1) : 1
+      def paginated? = @paginated
+
+      def more?
+        @paginated && !empty? && page < total_pages
+      end
+
+      def next_page
+        return nil unless more?
+
+        @requestor.list(
+          @path,
+          params: @filters.merge(page: page + 1),
+          klass: @klass,
+          client: @client,
+          paginated: true
+        )
+      end
+    end
+  end
+end

data/lib/pluggy/lists.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "lists/base_list"
+require_relative "lists/offset_list"
+require_relative "lists/cursor_list"
+require_relative "lists/array_list"
+
+module Pluggy
+  module Lists
+    # Pick a list type by looking at the payload rather than by trusting the
+    # endpoint's declared schema.
+    #
+    # This is deliberate: GET /categories declares a bare array but its own
+    # example is an offset envelope, so any per-endpoint assumption is a coin
+    # flip against the live API. Sniffing costs one hash lookup and makes every
+    # list endpoint present the same interface.
+    def self.wrap(payload, klass:, requestor:, path:, filters: {}, client: nil, paginated: false)
+      common = { klass: klass, requestor: requestor, path: path, filters: filters, client: client }
+
+      case payload
+      when Array
+        ArrayList.new(payload, **common)
+      when Hash
+        if payload.key?("next")
+          CursorList.new(payload, **common)
+        elsif payload.key?("results")
+          OffsetList.new(payload, paginated: paginated, **common)
+        else
+          raise Error, "unrecognized list envelope from #{path} (keys: #{payload.keys.inspect})"
+        end
+      else
+        raise Error, "expected an array or object from #{path}, got #{payload.class}"
+      end
+    end
+  end
+end

data/lib/pluggy/pluggy_object.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+require "set"
+require "json"
+require "time"
+require "date"
+
+module Pluggy
+  # Base value object wrapping an API JSON payload.
+  #
+  # The access contract, which is the one thing worth memorising:
+  #
+  #   txn.date      / txn[:date]     => Time      (coerced Ruby view)
+  #   txn["date"]   / txn["createdAt"] => String  (verbatim wire value)
+  #   txn.to_h                        => wire values, nested objects flattened
+  #
+  # Symbol keys and readers give you the coerced Ruby value; String keys read
+  # the original payload and accept the original camelCase spelling.
+  #
+  # Fields are declared once per class with the `fields` DSL rather than
+  # defined per instance (Stripe's approach), because a 500-transaction page
+  # would otherwise mean ~11,500 define_method calls per response. Undeclared
+  # keys are still kept and still reachable -- via method_missing and via []
+  # -- so fields Pluggy adds after this gem ships are not lost.
+  #
+  # Deliberately does NOT include Enumerable: iterating a Transaction and
+  # getting its own field values is a confusing API, and it would collide with
+  # ICountResponse#count. Only the list objects are Enumerable.
+  class PluggyObject
+    # Overriding any of these would break the object itself.
+    RESERVED = Set.new(%w[
+                         class send __send__ public_send object_id __id__ method methods
+                         respond_to? respond_to_missing? instance_variable_get instance_variable_set
+                         instance_variables singleton_class is_a? kind_of? instance_of? nil? tap
+                         then itself extend display equal? to_h to_hash to_s to_json as_json inspect
+                         keys values each_pair [] == eql? hash dup clone freeze frozen? initialize
+                         method_missing client read key?
+                       ]).freeze
+
+    # Time coercion is keyed on the wire field name, guarded by the value's
+    # shape. A blanket ISO-8601 sniff would be dangerous -- a descriptionRaw
+    # reading "2020-10-15" would silently become a Time.
+    TEMPORAL_KEYS = Set.new(%w[
+                              date createdAt updatedAt lastUpdatedAt nextAutoSyncAt consentExpiresAt
+                              expiresAt dueDate billClosingDate contractDate settlementDate
+                              firstInstallmentDueDate paymentDate purchaseDate balanceCloseDate
+                              balanceDueDate updateDateTime issueDate expirationDate paidDate
+                            ]).freeze
+
+    # Anchored, and requires a full date. This is what keeps `monthYear` and
+    # `billForecastDate` ("2024-03") as Strings, and `installmentPeriodicity`
+    # ("MES") untouched.
+    ISO8601 = /\A\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:?\d{2})?)?\z/
+
+    class << self
+      # Wire field name => nested class, inherited by subclasses.
+      def nested_types
+        @nested_types ||= superclass.respond_to?(:nested_types) ? superclass.nested_types.dup : {}
+      end
+
+      def declared_fields
+        @declared_fields ||=
+          superclass.respond_to?(:declared_fields) ? superclass.declared_fields.dup : Set.new
+      end
+
+      # fields :id, :descriptionRaw, "CET"
+      #
+      # Pass wire names (camelCase or otherwise); readers are generated in
+      # snake_case, with a camelCase alias so code transliterated from Pluggy's
+      # own docs also works.
+      def fields(*names)
+        names.flatten.each { |n| define_field(n.to_s) }
+      end
+
+      # nested connector: Connector, financeCharges: BillFinanceCharge
+      def nested(map)
+        map.each do |wire, klass|
+          nested_types[Util.wire_key(wire)] = klass
+          define_field(Util.wire_key(wire))
+        end
+      end
+
+      def define_field(wire)
+        declared_fields << wire
+        ruby = Util.snake_case(wire)
+
+        # Genuinely unusable names ("2fa", "foo-bar") stay reachable via [].
+        return unless ruby.match?(/\A[a-z_][a-zA-Z0-9_]*\z/)
+        return if RESERVED.include?(ruby)
+
+        define_method(ruby) { read(wire) }
+
+        # camelCase alias, e.g. loan.CET alongside loan.cet
+        define_method(wire) { read(wire) } unless wire == ruby || RESERVED.include?(wire)
+      end
+    end
+
+    attr_reader :client
+
+    # Accepts the payload either braced or as a bare trailing hash. Ruby routes
+    # an unbraced hash into **extra (String keys included), so
+    # `Transaction.new("id" => "x")` and `Transaction.new({"id" => "x"})` and
+    # `Transaction.new(payload, client: c)` all work.
+    #
+    # Keys are wire names -- "createdAt", not :created_at.
+    def initialize(values = {}, client: nil, **extra)
+      @client = client
+      @values = {}
+      @coerced = {}
+
+      source = values.nil? || values.empty? ? extra : values.merge(extra)
+
+      source.each do |key, value|
+        k = key.to_s
+        @values[k] = convert(k, value)
+      end
+    end
+
+    # Coerced read, memoised. Used by every generated accessor.
+    def read(wire)
+      return @coerced[wire] if @coerced.key?(wire)
+
+      raw = @values[wire]
+      @coerced[wire] = TEMPORAL_KEYS.include?(wire) ? coerce_time(raw) : raw
+    end
+
+    # String key => verbatim wire value (accepts the camelCase spelling).
+    # Symbol key => coerced value, same as the reader.
+    def [](key)
+      if key.is_a?(Symbol)
+        wire = @values.key?(key.to_s) ? key.to_s : Util.camel_case(key)
+        read(wire)
+      else
+        k = key.to_s
+        @values.key?(k) ? @values[k] : @values[Util.camel_case(k)]
+      end
+    end
+
+    def key?(key)
+      k = key.to_s
+      @values.key?(k) || @values.key?(Util.camel_case(k))
+    end
+
+    def keys = @values.keys
+    def values = @values.values
+    def each_pair(&) = @values.each_pair(&)
+
+    # Wire-shaped hash: nested objects flattened back to plain hashes. Values
+    # are the parsed ones (so amounts are BigDecimal), which is what `as_json`
+    # then renders correctly.
+    def to_h
+      @values.transform_values { |v| unwrap(v) }
+    end
+    alias to_hash to_h
+
+    # JSON.generate serialises a BigDecimal as a *quoted string*
+    # ('{"amount":"-0.21245e3"}'), which would break round-tripping. Wrap them
+    # so they render as unquoted numbers matching the original wire literal.
+    def as_json(*)
+      deep_render(to_h)
+    end
+
+    def to_json(*args)
+      as_json.to_json(*args)
+    end
+
+    def ==(other)
+      other.is_a?(self.class) && other.to_h == to_h
+    end
+    alias eql? ==
+
+    def hash = to_h.hash
+
+    def inspect
+      id = @values["id"]
+      "#<#{self.class.name}#{":#{id}" if id} #{@values.keys.join(" ")}>"
+    end
+
+    # Forward-compat path for fields Pluggy adds after this gem ships, and for
+    # the undeclared-but-real ones (Bill#accountId, Item#clientUserId,
+    # Connector#isSandbox).
+    def method_missing(name, *args)
+      n = name.to_s
+      return super if n.end_with?("=", "!") || !args.empty?
+
+      if n.end_with?("?")
+        base = n.delete_suffix("?")
+        wire = resolve_wire(base)
+        return !read(wire).nil? && read(wire) != false if wire
+      end
+
+      wire = resolve_wire(n)
+      return read(wire) if wire
+
+      super
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      n = name.to_s.sub(/[?]\z/, "")
+      !resolve_wire(n).nil? || super
+    end
+
+    private
+
+    # Map a Ruby method name back onto a present wire key.
+    def resolve_wire(name)
+      return name if @values.key?(name)
+
+      camel = Util.camel_case(name)
+      return camel if @values.key?(camel)
+
+      # Last resort: an acronym-bearing key our camelizer cannot reproduce
+      # ("issuerCNPJ" from :issuer_cnpj).
+      @values.keys.find { |k| Util.snake_case(k) == name }
+    end
+
+    def convert(wire, value)
+      case value
+      when Hash
+        (self.class.nested_types[wire] || PluggyObject).new(value, client: @client)
+      when Array
+        item_class = self.class.nested_types[wire]
+        value.map do |e|
+          e.is_a?(Hash) ? (item_class || PluggyObject).new(e, client: @client) : e
+        end
+      else
+        value
+      end
+    end
+
+    def unwrap(value)
+      case value
+      when PluggyObject then value.to_h
+      when Array then value.map { |e| unwrap(e) }
+      else value
+      end
+    end
+
+    def coerce_time(raw)
+      return raw unless raw.is_a?(String)
+      return raw unless Pluggy.config.coerce_times
+      return raw unless raw.match?(ISO8601)
+
+      # A bare "2024-03-15" is a Date; anything with a time part is a Time.
+      raw.length == 10 ? Date.iso8601(raw) : Time.iso8601(raw)
+    rescue ArgumentError, TypeError
+      # Never raise on a malformed date -- too much of this spec disagrees
+      # with the live API to be strict here.
+      raw
+    end
+
+    def deep_render(value)
+      case value
+      when BigDecimal then RawNumber.new(value)
+      when Hash then value.transform_values { |v| deep_render(v) }
+      when Array then value.map { |v| deep_render(v) }
+      else value
+      end
+    end
+
+    # Renders a BigDecimal as an unquoted JSON number.
+    class RawNumber
+      def initialize(decimal)
+        # "F" gives "-212.45" rather than "-0.21245e3".
+        @literal = decimal.to_s("F")
+        # Trim the trailing ".0" BigDecimal adds to integral values.
+        @literal = @literal.sub(/\.0\z/, "")
+      end
+
+      def to_json(*) = @literal
+      def to_s = @literal
+    end
+  end
+end