pluggy-rb 0.1.0

data/lib/pluggy/services/base_service.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Pluggy
+  module Services
+    class BaseService
+      def initialize(client)
+        @client = client
+        @requestor = client.requestor
+      end
+
+      private
+
+      def list_request(path, klass:, paginated: false, **params)
+        @requestor.list(path, params: params, klass: klass, client: @client, paginated: paginated)
+      end
+
+      def object_request(method, path, klass:, body: nil, opaque: [], **params)
+        payload = @requestor.request(
+          method, path,
+          params: params.empty? ? nil : params,
+          body: body,
+          opaque_body_keys: opaque
+        )
+        klass.new(payload, client: @client)
+      end
+
+      # Several endpoints take a required query param on an operation that
+      # documents only a 200 (/accounts and /loans need itemId; /bills and
+      # /transactions need accountId). Failing here with a clear message beats
+      # a confusing empty result or a 500.
+      def require_args!(**args)
+        missing = args.select { |_, v| v.nil? || (v.respond_to?(:empty?) && v.empty?) }.keys
+        return if missing.empty?
+
+        name = self.class.name.split("::").last
+        raise ArgumentError, "#{name}: #{missing.join(", ")} #{missing.one? ? "is" : "are"} required"
+      end
+
+      def config = @client.config
+    end
+  end
+end

data/lib/pluggy/services/other_services.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+module Pluggy
+  module Services
+    class AccountService < BaseService
+      # GET /accounts. `type` filters between "BANK" and "CREDIT".
+      #
+      # paginated: false -- the endpoint returns a page envelope but documents no
+      # page/pageSize parameters, so there is no way to request page 2.
+      def list(item_id:, type: nil)
+        require_args!(item_id: item_id)
+        list_request("/accounts", klass: Resources::Account, itemId: item_id, type: type)
+      end
+
+      def retrieve(id)
+        require_args!(id: id)
+        object_request(:get, "/accounts/#{id}", klass: Resources::Account)
+      end
+
+      # Live balance, read from the institution rather than the last sync. Slower
+      # than Account#balance and the one endpoint in scope that documents a 429
+      # (institution rate limit) and a 502 (institution unavailable).
+      def balance(id)
+        require_args!(id: id)
+        object_request(:get, "/accounts/#{id}/balance", klass: Resources::Balance)
+      end
+
+      # Monthly statement documents. Each url is signed and valid 30 minutes.
+      def statements(id)
+        require_args!(id: id)
+        list_request("/accounts/#{id}/statements", klass: Resources::Statement)
+      end
+    end
+
+    class BillService < BaseService
+      # GET /bills. Scoped to one credit-card account.
+      def list(account_id:)
+        require_args!(account_id: account_id)
+        result = list_request("/bills", klass: Resources::Bill, accountId: account_id)
+        annotate_cycles!(result)
+        result
+      end
+
+      def retrieve(id)
+        require_args!(id: id)
+        object_request(:get, "/bills/#{id}", klass: Resources::Bill)
+      end
+
+      # Convenience mirroring Bill#transactions.
+      def transactions(bill, **options)
+        bill = retrieve(bill) unless bill.is_a?(Resources::Bill)
+        bill.transactions(**options)
+      end
+
+      private
+
+      # Chain each bill to its predecessor's closing date so Bill#transactions
+      # can window on exactly one statement cycle instead of guessing.
+      def annotate_cycles!(list)
+        list.results
+            .select { |b| b["billClosingDate"] }
+            .sort_by { |b| b["billClosingDate"].to_s }
+            .each_cons(2) { |prev, cur| cur.previous_closing_date = prev["billClosingDate"] }
+      end
+    end
+
+    class LoanService < BaseService
+      # GET /loans. Note loans are scoped by ITEM, not by account.
+      def list(item_id:)
+        require_args!(item_id: item_id)
+        list_request("/loans", klass: Resources::Loan, itemId: item_id)
+      end
+
+      def retrieve(id)
+        require_args!(id: id)
+        object_request(:get, "/loans/#{id}", klass: Resources::Loan)
+      end
+    end
+
+    class ItemService < BaseService
+      # There is deliberately no #list: GET /items does not exist in the API.
+      # Persist the ids you create, normally keyed by your own clientUserId.
+
+      # POST /items.
+      #
+      # `parameters` is a connector-defined {String => String} credential map
+      # (or an encrypted string). Its keys are passed through untouched -- see
+      # Util.encode_body's `opaque` handling -- because camelizing a credential
+      # named "cpf_cnpj" would break item creation.
+      #
+      # Never retried on failure: the API has no idempotency key, so a retry
+      # could open a duplicate connection.
+      def create(connector_id:, parameters:, **options)
+        require_args!(connector_id: connector_id, parameters: parameters)
+        object_request(:post, "/items",
+          klass: Resources::Item,
+          opaque: %w[parameters],
+          body: { connector_id: connector_id, parameters: parameters, **options })
+      end
+
+      def retrieve(id)
+        require_args!(id: id)
+        object_request(:get, "/items/#{id}", klass: Resources::Item)
+      end
+
+      # PATCH /items/{id} triggers a fresh sync, optionally updating credentials.
+      def update(id, **body)
+        require_args!(id: id)
+        object_request(:patch, "/items/#{id}",
+          klass: Resources::Item, opaque: %w[parameters], body: body)
+      end
+
+      def delete(id)
+        require_args!(id: id)
+        object_request(:delete, "/items/#{id}", klass: Resources::Count)
+      end
+
+      # POST /items/{id}/mfa. The body is a bare {name => value} map, not a
+      # wrapped object, e.g. send_mfa(id, token: "123456").
+      def send_mfa(id, values)
+        require_args!(id: id, values: values)
+        object_request(:post, "/items/#{id}/mfa",
+          klass: Resources::Item,
+          body: Util.stringify_keys(values.to_h))
+      end
+
+      # PATCH, and it takes no body.
+      def disable_auto_sync(id)
+        require_args!(id: id)
+        object_request(:patch, "/items/#{id}/disable-auto-sync", klass: Resources::Item)
+      end
+    end
+
+    class ConnectorService < BaseService
+      # GET /connectors. `countries` and `types` are comma-joined by the encoder.
+      def list(countries: nil, types: nil, name: nil, sandbox: nil, health_details: nil,
+        is_open_finance: nil, supports_payment_initiation: nil,
+        supports_smart_transfers: nil, supports_automatic_pix: nil,
+        page: nil, page_size: nil)
+        list_request("/connectors",
+          klass: Resources::Connector,
+          paginated: !page.nil? || !page_size.nil?,
+          countries: countries,
+          types: types,
+          name: name,
+          sandbox: sandbox,
+          healthDetails: health_details,
+          isOpenFinance: is_open_finance,
+          supportsPaymentInitiation: supports_payment_initiation,
+          supportsSmartTransfers: supports_smart_transfers,
+          supportsAutomaticPix: supports_automatic_pix,
+          page: page,
+          pageSize: page_size)
+      end
+
+      # NOTE: a connector id is a NUMBER, not a UUID.
+      def retrieve(id, health_details: nil)
+        require_args!(id: id)
+        object_request(:get, "/connectors/#{id}",
+          klass: Resources::Connector, healthDetails: health_details)
+      end
+    end
+
+    class CategoryService < BaseService
+      # GET /categories. The spec declares a bare array but its own example is a
+      # page envelope, so the shape is sniffed at runtime; either way you get a
+      # list that answers #each.
+      def list(parent_id: nil)
+        list_request("/categories", klass: Resources::Category, parentId: parent_id)
+      end
+
+      def retrieve(id)
+        require_args!(id: id)
+        object_request(:get, "/categories/#{id}", klass: Resources::Category)
+      end
+    end
+
+    class MerchantService < BaseService
+      # GET /merchants. Returns three buckets (found, not found, invalid) rather
+      # than a list, so it maps to MerchantSearch rather than a list object.
+      def search(cnpjs)
+        list = Array(cnpjs)
+        require_args!(cnpjs: list)
+        object_request(:get, "/merchants", klass: Resources::MerchantSearch, cnpjs: list)
+      end
+
+      # Resolve a single CNPJ, or nil when it is unknown or invalid.
+      def retrieve(cnpj)
+        search([cnpj]).found_merchants&.first
+      end
+    end
+
+    class ConnectTokenService < BaseService
+      # POST /connect_token.
+      #
+      # Returns a 30-minute token for the Connect Widget in your frontend. It is
+      # not an apiKey and cannot authenticate API calls.
+      #
+      # Pass item_id: to let the widget update an existing item instead of
+      # creating a new one.
+      def create(item_id: nil, options: nil)
+        body = {}
+        body[:item_id] = item_id if item_id
+        body[:options] = options if options
+
+        object_request(:post, "/connect_token",
+          klass: Resources::ConnectToken,
+          body: body.empty? ? nil : body)
+      end
+    end
+  end
+end

data/lib/pluggy/services/transaction_service.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Pluggy
+  module Services
+    class TransactionService < BaseService
+      V2_PATH = "/v2/transactions"
+      V1_PATH = "/transactions"
+
+      # Filters that only exist on the deprecated v1 endpoint. Passing any of
+      # them routes there automatically.
+      V1_ONLY_PARAMS = %i[bill_id page page_size].freeze
+
+      # List an account's transactions.
+      #
+      # Defaults to GET /v2/transactions (cursor-paginated, current). Routes to
+      # the deprecated GET /transactions when a v1-only filter is given, or when
+      # version: :v1 is explicit.
+      #
+      # v2 filters: date_from, date_to, created_at_from, ids, after
+      # v1 filters: from, to, created_at_from, ids, bill_id, page, page_size
+      def list(account_id:, version: nil, **filters)
+        require_args!(account_id: account_id)
+
+        resolved = version || implied_version(filters)
+        resolved == :v1 ? list_v1(account_id, **filters) : list_v2(account_id, **filters)
+      end
+
+      # Resume cursor pagination from a persisted CursorList#next_token.
+      #
+      # The token is the whole "?..." query string the API handed back, filters
+      # included -- not a bare `after` value. See Lists::CursorList.
+      def resume(next_token)
+        token = next_token.to_s
+        unless token.start_with?("?")
+          raise ArgumentError,
+            "expected a cursor token starting with '?' (use CursorList#next_token), got #{token.inspect}"
+        end
+
+        @requestor.list_raw("#{V2_PATH}#{token}", klass: Resources::Transaction, client: @client)
+      end
+
+      def retrieve(id)
+        require_args!(id: id)
+        object_request(:get, "#{V1_PATH}/#{id}", klass: Resources::Transaction)
+      end
+
+      # PATCH /transactions/{id}. Recategorizing is the only supported edit.
+      def update(id, category_id:)
+        require_args!(id: id, category_id: category_id)
+        object_request(:patch, "#{V1_PATH}/#{id}",
+          klass: Resources::Transaction,
+          body: { category_id: category_id })
+      end
+
+      private
+
+      def implied_version(filters)
+        return :v1 if V1_ONLY_PARAMS.any? { |p| filters.key?(p) }
+
+        config.transactions_api_version
+      end
+
+      def list_v2(account_id, date_from: nil, date_to: nil, created_at_from: nil,
+        ids: nil, after: nil, **rest)
+        reject_unknown!(rest, V2_PATH)
+
+        # The API returns a 400 for this combination; catching it locally saves
+        # a round-trip and gives a clearer message.
+        if date_from && created_at_from
+          raise ArgumentError,
+            "date_from cannot be combined with created_at_from on #{V2_PATH} " \
+            "(the API rejects it with a 400); use one or the other"
+        end
+
+        check_ids!(ids)
+
+        list_request(V2_PATH,
+          klass: Resources::Transaction,
+          accountId: account_id,
+          dateFrom: date_from,
+          dateTo: date_to,
+          createdAtFrom: created_at_from,
+          ids: ids,
+          after: after)
+      end
+
+      def list_v1(account_id, from: nil, to: nil, created_at_from: nil, ids: nil,
+        bill_id: nil, page: nil, page_size: nil, date_from: nil, date_to: nil, **rest)
+        reject_unknown!(rest, V1_PATH)
+        check_ids!(ids)
+
+        config.log(:info,
+          "using deprecated GET /transactions (sunset 2026-12-31)",
+          reason: bill_id ? "billId filter is v1-only" : "requested")
+
+        size = page_size || Lists::OffsetList::DEFAULT_PAGE_SIZE
+        if size > Lists::OffsetList::MAX_PAGE_SIZE
+          raise ArgumentError, "page_size cannot exceed #{Lists::OffsetList::MAX_PAGE_SIZE}"
+        end
+
+        list_request(V1_PATH,
+          klass: Resources::Transaction,
+          paginated: true,
+          accountId: account_id,
+          # v2 renamed these; accept either spelling here.
+          from: from || date_from,
+          to: to || date_to,
+          createdAtFrom: created_at_from,
+          ids: ids,
+          billId: bill_id,
+          page: page || 1,
+          pageSize: size)
+      end
+
+      def check_ids!(ids)
+        return if ids.nil? || ids.length <= 500
+
+        raise ArgumentError, "at most 500 ids per request (got #{ids.length})"
+      end
+
+      def reject_unknown!(rest, path)
+        return if rest.empty?
+
+        raise ArgumentError, "unknown filter#{"s" if rest.size > 1} for #{path}: #{rest.keys.join(", ")}"
+      end
+    end
+  end
+end

data/lib/pluggy/util.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "set"
+require "uri"
+require "time"
+require "date"
+
+module Pluggy
+  # Naming conversion and request encoding.
+  #
+  # Pluggy speaks camelCase; Ruby speaks snake_case. Two conversions run in
+  # opposite directions: responses are read through snake_case accessors
+  # (see PluggyObject), and request params are written from snake_case kwargs
+  # into camelCase wire keys.
+  #
+  # The conversion is deliberately NOT round-tripped: camel_case(snake_case(x))
+  # is lossy for acronym-bearing keys ("issuerCNPJ" -> :issuer_cnpj ->
+  # "issuerCnpj"). That is fine because only *outgoing* params are camelized,
+  # and those are an explicit per-service allowlist rather than something we
+  # derive from a response.
+  module Util
+    # "issuerCNPJName" -> "issuerCNPJ_Name"
+    ACRONYM_BOUNDARY = /([A-Z\d]+)([A-Z][a-z])/
+    # "createdAt" -> "created_At"
+    LOWER_UPPER = /([a-z\d])([A-Z])/
+
+    # Comma-joined in the query string. `countries` and `types` are
+    # `style: form, explode: false` in the spec; `cnpjs` is typed as a bare
+    # comma-separated string. Everything else (notably `ids`) repeats the key.
+    COMMA_JOINED_PARAMS = %w[countries types cnpjs].freeze
+
+    # The spec types these as `format: date-time` but every description says
+    # "Format (yyyy-mm-dd)". The descriptions win — see plan §7.
+    DATE_ONLY_PARAMS = %w[from to dateFrom dateTo].freeze
+
+    # ...and this one really does want the full timestamp.
+    DATETIME_PARAMS = %w[createdAtFrom].freeze
+
+    DATETIME_FORMAT = "%Y-%m-%dT%H:%M:%S.%LZ"
+
+    @snake_cache = {}
+    @camel_cache = {}
+
+    class << self
+      # "createdAt" => "created_at", "CET" => "cet", "hasMFA" => "has_mfa",
+      # "issuerCNPJ" => "issuer_cnpj", "payeeMCC" => "payee_mcc"
+      def snake_case(key)
+        k = key.to_s
+        @snake_cache[k] ||= k.gsub(ACRONYM_BOUNDARY, '\1_\2')
+                             .gsub(LOWER_UPPER, '\1_\2')
+                             .tr("-", "_")
+                             .downcase
+      end
+
+      # :item_id => "itemId", :oauth_redirect_uri => "oauthRedirectUri"
+      def camel_case(key)
+        k = key.to_s
+        return k unless k.include?("_")
+
+        @camel_cache[k] ||= begin
+          head, *rest = k.split("_")
+          head + rest.map(&:capitalize).join
+        end
+      end
+
+      # Symbol keys are snake_case and get camelized. String keys pass through
+      # verbatim -- the escape hatch for any key our camelizer would mangle.
+      def wire_key(key)
+        key.is_a?(String) ? key : camel_case(key)
+      end
+
+      def encode_query(params)
+        pairs = []
+
+        (params || {}).each do |key, value|
+          next if value.nil?
+
+          wire = wire_key(key)
+
+          case value
+          when Array
+            next if value.empty?
+
+            if COMMA_JOINED_PARAMS.include?(wire)
+              pairs << [wire, value.map { |e| format_param(wire, e) }.join(",")]
+            else
+              value.each { |e| pairs << [wire, format_param(wire, e)] }
+            end
+          when Hash
+            raise ArgumentError, "nested hash is not encodable in a query string: #{wire}"
+          else
+            pairs << [wire, format_param(wire, value)]
+          end
+        end
+
+        URI.encode_www_form(pairs)
+      end
+
+      # Per-parameter date formatting (see DATE_ONLY_PARAMS / DATETIME_PARAMS).
+      def format_param(wire, value)
+        if DATE_ONLY_PARAMS.include?(wire)
+          to_date_string(value)
+        elsif DATETIME_PARAMS.include?(wire)
+          to_datetime_string(value)
+        else
+          value.to_s
+        end
+      end
+
+      def to_date_string(value)
+        case value
+        when Date then value.iso8601
+        when Time then value.to_date.iso8601
+        else
+          # Tolerate a caller passing a full timestamp for a date-only param.
+          value.to_s[0, 10]
+        end
+      end
+
+      def to_datetime_string(value)
+        case value
+        when Time then value.utc.strftime(DATETIME_FORMAT)
+        when DateTime then value.to_time.utc.strftime(DATETIME_FORMAT)
+        when Date then Time.utc(value.year, value.month, value.day).strftime(DATETIME_FORMAT)
+        else value.to_s
+        end
+      end
+
+      # Deep snake_case -> camelCase for request bodies.
+      #
+      # `opaque` names keys whose *contents* must not be touched. POST /items
+      # {parameters} and POST /items/{id}/mfa are free-form {String => String}
+      # maps whose keys are connector-defined ("user", "cpf", "cpf_cnpj"), so
+      # camelizing them would silently break item creation.
+      def encode_body(hash, opaque: [])
+        (hash || {}).each_with_object({}) do |(key, value), out|
+          next if value.nil?
+
+          wire = wire_key(key)
+          out[wire] =
+            if opaque.include?(wire)
+              stringify_keys(value)
+            else
+              encode_body_value(value, opaque)
+            end
+        end
+      end
+
+      def encode_body_value(value, opaque)
+        case value
+        when Hash then encode_body(value, opaque: opaque)
+        when Array then value.map { |e| e.is_a?(Hash) ? encode_body(e, opaque: opaque) : e }
+        else value
+        end
+      end
+
+      # Shallow String-ify of a free-form map's keys, leaving them otherwise
+      # untouched.
+      def stringify_keys(value)
+        return value unless value.is_a?(Hash)
+
+        value.each_with_object({}) { |(k, v), out| out[k.to_s] = v }
+      end
+    end
+  end
+end

data/lib/pluggy/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Pluggy
+  VERSION = File.read(File.join(__dir__, "..", "..", "VERSION")).strip
+end

data/lib/pluggy-rb.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Shim so `gem "pluggy-rb"` auto-requires cleanly under Bundler.
+# `require "pluggy"` is the canonical form.
+require_relative "pluggy"

data/lib/pluggy.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+require_relative "pluggy/version"
+require_relative "pluggy/errors"
+require_relative "pluggy/util"
+require_relative "pluggy/configuration"
+require_relative "pluggy/pluggy_object"
+require_relative "pluggy/api_resource"
+require_relative "pluggy/api_key"
+require_relative "pluggy/credential_store"
+require_relative "pluggy/connection_manager"
+require_relative "pluggy/lists"
+
+require_relative "pluggy/resources/merchant"
+require_relative "pluggy/resources/transaction"
+require_relative "pluggy/resources/account"
+require_relative "pluggy/resources/bill"
+require_relative "pluggy/resources/loan"
+require_relative "pluggy/resources/connector"
+require_relative "pluggy/resources/item"
+require_relative "pluggy/resources/misc"
+
+require_relative "pluggy/api_requestor"
+require_relative "pluggy/services/base_service"
+require_relative "pluggy/services/transaction_service"
+require_relative "pluggy/services/other_services"
+require_relative "pluggy/client"
+
+# Unofficial Ruby client for the Pluggy open-finance API.
+#
+#   client = Pluggy::Client.new(client_id: "...", client_secret: "...")
+#   client.accounts.list(item_id: item_id).each { |a| puts a.name }
+#
+# Configuration is per-client. The module-level accessors below set defaults
+# that new clients inherit; they are not a way to make calls without a client.
+module Pluggy
+  class << self
+    extend Forwardable
+
+    attr_accessor :config
+
+    def_delegators :config,
+      *Configuration::DEFAULTS.keys,
+      *Configuration::DEFAULTS.keys.map { |key| :"#{key}=" }
+
+    def configure
+      yield config
+      config
+    end
+  end
+
+  self.config = Configuration.new
+end