pluggy-rb 0.1.0

data/lib/pluggy/resources/account.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Pluggy
+  module Resources
+    class ReservedBalance < APIResource
+      fields :name, :identification, :availableAmounts
+    end
+
+    # Populated when type == "BANK". Every field is nullable.
+    class BankData < APIResource
+      fields :transferNumber, :closingBalance, :automaticallyInvestedBalance,
+        :overdraftContractedLimit, :overdraftUsedLimit,
+        :unarrangedOverdraftAmount, :hasReservedBalance
+      nested reservedBalances: ReservedBalance
+
+      # "Cheque especial" -- how much of the arranged overdraft is in use.
+      def overdraft_in_use? = self["overdraftUsedLimit"].to_f.positive?
+    end
+
+    class AdditionalCard < APIResource
+      fields :number
+    end
+
+    class DisaggregatedCreditLimit < APIResource
+      fields :creditLineLimitType, :consolidationType, :identificationNumber,
+        :isLimitFlexible, :lineName, :lineNameAdditionalInfo, :limitAmount,
+        :limitAmountCurrencyCode, :limitAmountReason, :customizedLimitAmount,
+        :customizedLimitAmountCurrencyCode, :usedAmount,
+        :usedAmountCurrencyCode, :availableAmount, :availableAmountCurrencyCode
+    end
+
+    # Populated when type == "CREDIT".
+    class CreditData < APIResource
+      fields :level, :brand, :brandAdditionalInfo, :balanceCloseDate,
+        :balanceDueDate, :availableCreditLimit, :balanceForeignCurrency,
+        :minimumPayment, :creditLimit, :isLimitFlexible, :status, :holderType
+      nested disaggregatedCreditLimits: DisaggregatedCreditLimit,
+        additionalCards: AdditionalCard
+
+      def active? = self["status"] == "ACTIVE"
+      def blocked? = self["status"] == "BLOCKED"
+      def cancelled? = self["status"] == "CANCELLED"
+      def main_holder? = self["holderType"] == "MAIN"
+    end
+
+    class Account < APIResource
+      fields :id, :type, :subtype, :number, :name, :marketingName, :balance,
+        :itemId, :taxNumber, :owner, :currencyCode, :createdAt, :updatedAt
+      nested bankData: BankData, creditData: CreditData
+
+      def bank? = self["type"] == "BANK"
+      def credit? = self["type"] == "CREDIT"
+      def credit_card? = self["subtype"] == "CREDIT_CARD"
+      def checking? = self["subtype"] == "CHECKING_ACCOUNT"
+      def savings? = self["subtype"] == "SAVINGS_ACCOUNT"
+
+      def transactions(**filters)
+        ensure_client!.transactions.list(account_id: self["id"], **filters)
+      end
+
+      # Credit-card statements. Only CREDIT accounts have them, so say so
+      # clearly rather than returning a confusing empty list.
+      def bills(**filters)
+        unless credit?
+          raise Error,
+            "account #{self["id"]} has type #{self["type"].inspect}, not \"CREDIT\"; " \
+            "bills exist only for credit-card accounts"
+        end
+
+        ensure_client!.bills.list(account_id: self["id"], **filters)
+      end
+
+      # GET /accounts/{id}/balance -- fetched live from the institution rather
+      # than from the last sync, so it is slower and can 429 or 502.
+      def live_balance = ensure_client!.accounts.balance(self["id"])
+
+      def statements = ensure_client!.accounts.statements(self["id"])
+
+      def item = ensure_client!.items.retrieve(self["itemId"])
+
+      def refresh = ensure_client!.accounts.retrieve(self["id"])
+    end
+  end
+end

data/lib/pluggy/resources/bill.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Pluggy
+  module Resources
+    class BillFinanceCharge < APIResource
+      fields :id, :type, :amount, :currencyCode, :additionalInfo
+      # `creditCardBillId` is in the schema's `required` list but absent from
+      # its `properties` (spec bug); it is present at runtime.
+      fields :creditCardBillId
+    end
+
+    class BillPayment < APIResource
+      fields :id, :valueType, :paymentDate, :paymentMode, :amount, :currencyCode
+
+      def full? = self["valueType"] == "FULL_PAYMENT"
+      def installment? = self["valueType"] == "INSTALLMENT_PAYMENT"
+    end
+
+    # A credit-card statement.
+    #
+    # Bills carry no line items of their own -- see #transactions.
+    class Bill < APIResource
+      fields :id, :dueDate, :billClosingDate, :totalAmount,
+        :totalAmountCurrencyCode, :minimumPaymentAmount, :allowsInstallments
+      # Same spec bug as BillFinanceCharge#creditCardBillId: `accountId` is
+      # required-but-undeclared, and present at runtime.
+      fields :accountId
+      nested financeCharges: BillFinanceCharge, payments: BillPayment
+
+      # How far back to look when the previous cycle is unknown. Two months plus
+      # slack, so a 31-day cycle plus a late closing date still fits.
+      FALLBACK_WINDOW_DAYS = 62
+
+      # Stamped by BillService#list, which sees the whole cycle sequence and can
+      # therefore give #transactions an exact one-cycle window. Nil for a bill
+      # fetched on its own via bills.retrieve.
+      attr_accessor :previous_closing_date
+
+      def paid?
+        list = payments
+        return false if list.nil? || list.empty?
+
+        list.sum { |p| p["amount"] || 0 } >= (self["totalAmount"] || 0)
+      end
+
+      def finance_charges_total
+        (finance_charges || []).sum { |c| c["amount"] || 0 }
+      end
+
+      def account = ensure_client!.accounts.retrieve(self["accountId"])
+
+      # The bill's line items.
+      #
+      # GET /v2/transactions has no billId filter (v1 had one, but v1 is
+      # deprecated with a 2026-12-31 sunset), so this lists the account's
+      # transactions over the statement cycle and filters on
+      # creditCardMetadata.billId.
+      #
+      # The billId check is authoritative and always runs, so the date window
+      # only affects how many requests are made, never which transactions come
+      # back -- a wrong window yields a slower answer, never a wrong one.
+      #
+      # Pass `strategy: :legacy` for a single server-side-filtered request
+      # against the deprecated v1 endpoint.
+      #
+      # Returns an Enumerator rather than a list object, because the count is
+      # only knowable after filtering. Nothing is requested until you iterate,
+      # and `.map`/`.select` behave normally (returning Arrays) -- unlike a
+      # lazy enumerator, which would surprise callers. Chain `.lazy` yourself
+      # if you want lazy semantics downstream.
+      #
+      # With strategy: :legacy it returns a real list object instead, since the
+      # server did the filtering.
+      def transactions(strategy: :v2, date_from: nil, date_to: nil, **filters)
+        # Validated up front rather than on first iteration: a missing client or
+        # accountId is a programming error, and deferring it to somewhere deep in
+        # an enumerator makes it much harder to place.
+        ensure_client!
+        require_account_id!
+
+        if strategy == :legacy
+          return @client.transactions.list(
+            account_id: require_account_id!, bill_id: self["id"], **filters
+          )
+        end
+
+        unless block_given?
+          return enum_for(:transactions, strategy: strategy, date_from: date_from,
+            date_to: date_to, **filters)
+        end
+
+        bill_id = self["id"]
+        @client.transactions
+               .list(account_id: require_account_id!,
+                 date_from: date_from || window_start,
+                 date_to: date_to || window_end,
+                     **filters)
+               .auto_paging_each { |t| yield t if t.bill_id == bill_id }
+      end
+
+      private
+
+      def require_account_id!
+        self["accountId"] || raise(
+          Error,
+          "bill #{self["id"]} has no accountId, so its transactions cannot be located; " \
+          "fetch it via client.bills.list(account_id:)"
+        )
+      end
+
+      # Exact when BillService#list supplied the previous cycle; otherwise a
+      # deliberately generous fallback.
+      def window_start
+        if previous_closing_date
+          date = to_date(previous_closing_date)
+          return date + 1 if date
+        end
+
+        anchor = to_date(self["billClosingDate"] || self["dueDate"])
+        return nil unless anchor
+
+        @client&.config&.log(
+          :info,
+          "bill #{self["id"]}: previous cycle unknown, widening the transaction window",
+          days: FALLBACK_WINDOW_DAYS
+        )
+        anchor - FALLBACK_WINDOW_DAYS
+      end
+
+      # Through the due date rather than the closing date: instalments and
+      # late-posted items can land after the cycle closes.
+      def window_end
+        to_date(self["dueDate"] || self["billClosingDate"])
+      end
+
+      def to_date(value)
+        case value
+        when Date then value
+        when Time then value.to_date
+        when String then Date.parse(value)
+        end
+      rescue ArgumentError, TypeError
+        nil
+      end
+    end
+  end
+end

data/lib/pluggy/resources/connector.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Pluggy
+  module Resources
+    class CredentialOption < APIResource
+      fields :value, :label
+    end
+
+    # One input the Connect Widget (or POST /items) must supply. `name` is the
+    # key to send in the `parameters` map.
+    class ConnectorCredential < APIResource
+      fields :name, :label, :type, :assistiveText, :data, :placeholder,
+        :validation, :validationMessage, :mfa
+      nested options: CredentialOption
+
+      def mfa? = self["mfa"] == true
+      def select? = self["type"] == "select"
+      def image? = self["type"] == "image"
+      def password? = self["type"] == "password"
+
+      def valid?(value)
+        pattern = self["validation"]
+        return true if pattern.nil? || pattern.empty?
+
+        Regexp.new(pattern).match?(value.to_s)
+      rescue RegexpError
+        true
+      end
+    end
+
+    class ConnectorHealthDetails < APIResource
+      fields :connectionRateLast6Hours, :connectionsLast6Hours
+    end
+
+    # Only populated when the request passed healthDetails: true, and may itself
+    # be null. `status` is documented in prose as ONLINE/OFFLINE/UNSTABLE but
+    # declared as a free string.
+    class ConnectorHealth < APIResource
+      fields :status, :stage
+      nested details: ConnectorHealthDetails
+
+      def online? = self["status"] == "ONLINE"
+      def offline? = self["status"] == "OFFLINE"
+      def unstable? = self["status"] == "UNSTABLE"
+    end
+
+    class Connector < APIResource
+      # Note `id` is a NUMBER here, not a UUID like every other resource.
+      fields :id, :name, :institutionUrl, :imageUrl, :primaryColor, :type,
+        :country, :hasMFA, :products, :oauth, :oauthUrl, :resetPasswordUrl,
+        :isOpenFinance, :supportsPaymentInitiation, :supportsScheduledPayments,
+        :supportsSmartTransfers, :supportsBoletoManagement,
+        :supportsAutomaticPix, :createdAt, :updatedAt
+      # In the spec's examples but not its schema.
+      fields :isSandbox
+      nested credentials: ConnectorCredential, health: ConnectorHealth
+
+      def mfa? = self["hasMFA"] == true
+      def oauth? = self["oauth"] == true
+      def sandbox? = self["isSandbox"] == true
+      def open_finance? = self["isOpenFinance"] == true
+
+      def supports?(product)
+        (self["products"] || []).include?(product.to_s.upcase)
+      end
+
+      def credential_names = (credentials || []).map { |c| c["name"] }
+    end
+  end
+end

data/lib/pluggy/resources/item.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Pluggy
+  module Resources
+    class StatusDetailWarning < APIResource
+      fields :code, :message, :providerMessage
+    end
+
+    class StatusDetailProduct < APIResource
+      fields :lastUpdatedAt, :isUpdated
+      nested warnings: StatusDetailWarning
+
+      def updated? = self["isUpdated"] == true
+    end
+
+    # Per-product sync state. Useful for answering "are the transactions ready
+    # yet?" without polling the whole item.
+    class StatusDetail < APIResource
+      PRODUCTS = %w[
+        accounts creditCards transactions investments identity
+        investmentsTransactions paymentData loans accountStatements
+      ].freeze
+
+      nested(PRODUCTS.to_h { |p| [p, StatusDetailProduct] })
+
+      def updated?(product)
+        self[Util.camel_case(product)]&.updated? || false
+      end
+
+      def warnings
+        PRODUCTS.flat_map { |p| self[p]&.warnings || [] }
+      end
+    end
+
+    class ItemError < APIResource
+      fields :code, :message, :providerMessage, :attributes
+    end
+
+    # What the user must do next: an MFA code, a device authorization, an OAuth
+    # redirect.
+    class UserAction < APIResource
+      fields :instructions, :attributes, :expiresAt
+    end
+
+    # A connection to one financial institution.
+    #
+    # There is no GET /items endpoint -- items cannot be listed. Persist the ids
+    # you create, normally keyed by your own clientUserId.
+    class Item < APIResource
+      fields :id, :status, :executionStatus, :webhookUrl, :createdAt, :updatedAt,
+        :lastUpdatedAt, :nextAutoSyncAt, :consecutiveFailedLoginAttempts,
+        :consentExpiresAt, :products
+      # In the spec's examples but not its schema.
+      fields :clientUserId, :oauthRedirectUri
+      nested connector: Connector,
+        parameter: ConnectorCredential,
+        userAction: UserAction,
+        statusDetail: StatusDetail,
+        error: ItemError
+
+      # `status` and `executionStatus` are unconstrained strings in the spec --
+      # no enum is declared anywhere and the documented values appear only in
+      # examples. These predicates compare raw strings and never assume the set
+      # is closed.
+      def updated? = self["status"] == "UPDATED"
+      def updating? = self["status"] == "UPDATING"
+      def login_error? = self["status"] == "LOGIN_ERROR"
+      def outdated? = self["status"] == "OUTDATED"
+      def waiting_user_input? = self["status"] == "WAITING_USER_INPUT" || !self["userAction"].nil?
+      alias mfa_required? waiting_user_input?
+
+      def failed? = !self["error"].nil? || self["executionStatus"].to_s.include?("ERROR")
+      def succeeded? = self["executionStatus"] == "SUCCESS"
+
+      def consent_expired?
+        expiry = self[:consentExpiresAt]
+        expiry.is_a?(Time) && expiry <= Time.now
+      end
+
+      def accounts(type: nil) = ensure_client!.accounts.list(item_id: self["id"], type: type)
+      def bank_accounts = accounts(type: "BANK")
+      def credit_accounts = accounts(type: "CREDIT")
+      def loans = ensure_client!.loans.list(item_id: self["id"])
+
+      # Every transaction on every account of this item, as one lazy stream.
+      def transactions(**filters, &block)
+        return enum_for(:transactions, **filters) unless block_given?
+
+        accounts.each do |account|
+          account.transactions(**filters).auto_paging_each(&block)
+        end
+      end
+
+      def send_mfa(values) = ensure_client!.items.send_mfa(self["id"], values)
+      def disable_auto_sync = ensure_client!.items.disable_auto_sync(self["id"])
+      def sync(**body) = ensure_client!.items.update(self["id"], **body)
+      def delete = ensure_client!.items.delete(self["id"])
+      def refresh = ensure_client!.items.retrieve(self["id"])
+    end
+  end
+end

data/lib/pluggy/resources/loan.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Pluggy
+  module Resources
+    # Every enum below is left as a raw String on purpose.
+    #
+    # The spec declares these in English (EFFECTIVE, SIMPLE, MONTHLY, UNIQUE,
+    # MINIMUM) but the live API returns the Open Finance Brasil Portuguese
+    # values (EFETIVA, SIMPLES, AA, UNICA, MINIMO). Modelling them as closed
+    # constants would reject real data.
+    class LoanInterestRate < APIResource
+      fields :taxType, :interestRateType, :taxPeriodicity, :calculation,
+        :referentialRateIndexerType, :referentialRateIndexerSubType,
+        :referentialRateIndexerAdditionalInfo, :preFixedRate,
+        :postFixedRate, :additionalInfo
+    end
+
+    class LoanContractedFee < APIResource
+      fields :name, :code, :chargeType, :charge, :amount, :rate
+    end
+
+    class LoanContractedFinanceCharge < APIResource
+      # The schema declares `additionalInfo`/`rate`, but the spec's own examples
+      # emit `chargeAdditionalInfo`/`chargeRate`. Declare both spellings and let
+      # whichever the API omits return nil.
+      fields :type, :additionalInfo, :rate, :chargeAdditionalInfo, :chargeRate
+
+      def info = self["additionalInfo"] || self["chargeAdditionalInfo"]
+      def charge_rate = self["rate"] || self["chargeRate"]
+    end
+
+    class LoanWarranty < APIResource
+      fields :currencyCode, :type, :subtype, :amount
+    end
+
+    class LoanBalloonPayment < APIResource
+      fields :dueDate, :amount
+    end
+
+    class LoanInstallments < APIResource
+      fields :typeNumberOfInstallments, :totalNumberOfInstallments,
+        :typeContractRemaining, :contractRemainingNumber,
+        :paidInstallments, :dueInstallments, :pastDueInstallments
+      nested balloonPayments: LoanBalloonPayment
+
+      def overdue? = self["pastDueInstallments"].to_i.positive?
+    end
+
+    class LoanPaymentRelease < APIResource
+      fields :isOverParcelPayment, :installmentId, :paidDate, :currencyCode,
+        :paidAmount, :overParcel
+    end
+
+    class LoanPayments < APIResource
+      fields :contractOutstandingBalance
+      nested releases: LoanPaymentRelease
+    end
+
+    class Loan < APIResource
+      # `CET` (Custo Efetivo Total) is the only non-lowercase-first property in
+      # the whole spec. It is passed as a String literal here, and the snake_case
+      # conversion turns it into a plain `#cet` reader -- `loan.CET` and
+      # `loan["CET"]` work too.
+      fields :id, :itemId, :contractNumber, :ipocCode, :productName, :type, :kind,
+        :date, :contractDate, :disbursementDates, :settlementDate,
+        :contractAmount, :currencyCode, :dueDate, :installmentPeriodicity,
+        :installmentPeriodicityAdditionalInfo, :firstInstallmentDueDate,
+        "CET", :amortizationScheduled, :amortizationScheduledAdditionalInfo,
+        :cnpjConsignee
+      nested interestRates: LoanInterestRate,
+        contractedFees: LoanContractedFee,
+        contractedFinanceCharges: LoanContractedFinanceCharge,
+        warranties: LoanWarranty,
+        installments: LoanInstallments,
+        payments: LoanPayments
+
+      def loan? = self["kind"] == "LOAN"
+      def financing? = self["kind"] == "FINANCING"
+      def overdraft? = self["kind"] == "UNARRANGED_ACCOUNT_OVERDRAFT"
+
+      def outstanding_balance = payments&.[]("contractOutstandingBalance")
+      def overdue? = installments&.overdue? || false
+
+      # Loans hang off an item, not an account.
+      def item = ensure_client!.items.retrieve(self["itemId"])
+    end
+  end
+end

data/lib/pluggy/resources/merchant.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Pluggy
+  module Resources
+    # The counterparty of a transaction, resolved from its CNPJ.
+    class Merchant < APIResource
+      fields :name, :businessName, :cnpj, :cnae
+    end
+
+    # GET /merchants returns neither a list envelope nor a bare array, but three
+    # named buckets, so it gets its own type rather than being forced into the
+    # list interface.
+    class MerchantSearch < APIResource
+      fields :notFoundMerchants, :invalidCnpjs
+      nested foundMerchants: Merchant
+
+      alias found found_merchants
+      alias not_found not_found_merchants
+      alias invalid invalid_cnpjs
+
+      # Look up a resolved merchant by the CNPJ you asked for.
+      def [](key)
+        return super if key.is_a?(Symbol) || !key.to_s.match?(/\A\d{14}\z/)
+
+        (found_merchants || []).find { |m| m["cnpj"] == key.to_s }
+      end
+
+      def to_h_by_cnpj
+        (found_merchants || []).to_h { |m| [m["cnpj"], m] }
+      end
+    end
+  end
+end

data/lib/pluggy/resources/misc.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Pluggy
+  module Resources
+    # POST /connect_token. Valid for 30 minutes and meant for the Connect
+    # Widget in your frontend -- it is NOT an apiKey and cannot authenticate
+    # API calls.
+    class ConnectToken < APIResource
+      fields :accessToken
+    end
+
+    # GET /accounts/{id}/balance -- read live from the institution rather than
+    # from the last sync.
+    class Balance < APIResource
+      fields :balance, :currencyCode, :updateDateTime
+    end
+
+    # GET /accounts/{id}/statements. The url is a signed link valid for 30
+    # minutes. `monthYear` is "2024-03", which is why it is deliberately not
+    # coerced to a Date.
+    class Statement < APIResource
+      fields :id, :monthYear, :url
+    end
+
+    # DELETE /items/{id} returns {count}. This is why PluggyObject does not
+    # include Enumerable: #count would otherwise be shadowed.
+    class Count < APIResource
+      fields :count
+    end
+
+    # A transaction category. Two-level hierarchy: a category with no parentId
+    # is a root.
+    class Category < APIResource
+      fields :id, :description, :descriptionTranslated, :parentId, :parentDescription
+
+      def root? = self["parentId"].nil?
+
+      def children
+        ensure_client!.categories.list(parent_id: self["id"])
+      end
+
+      def parent
+        parent_id = self["parentId"]
+        parent_id && ensure_client!.categories.retrieve(parent_id)
+      end
+    end
+  end
+end

data/lib/pluggy/resources/transaction.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Pluggy
+  module Resources
+    # A CPF or CNPJ, already formatted by Pluggy ("416.799.495-00").
+    class Document < APIResource
+      fields :type, :value
+
+      def cpf? = self["type"] == "CPF"
+      def cnpj? = self["type"] == "CNPJ"
+    end
+
+    class PaymentParticipant < APIResource
+      fields :name, :accountNumber, :branchNumber, :routingNumber, :routingNumberISPB
+      nested documentNumber: Document
+    end
+
+    class BoletoMetadata < APIResource
+      fields :digitableLine, :barcode, :baseAmount, :interestAmount,
+        :penaltyAmount, :discountAmount
+    end
+
+    # Present for transfers and bill payments. `paymentMethod` is PIX, TED, DOC,
+    # TEV or BOLETO -- described in prose but declared as a free string, so it is
+    # never validated here.
+    class PaymentData < APIResource
+      fields :reason, :referenceNumber, :receiverReferenceId,
+        :authenticationCode, :paymentMethod
+      nested payer: PaymentParticipant,
+        receiver: PaymentParticipant,
+        boletoMetadata: BoletoMetadata
+    end
+
+    class CreditCardMetadata < APIResource
+      fields :installmentNumber, :totalInstallments, :totalAmount, :feeType,
+        :feeTypeAdditionalInfo, :otherCreditsType, :otherCreditsAdditionalInfo,
+        :purchaseDate, :payeeMCC, :cardNumber, :billId, :billForecastDate
+
+      def fee? = !self["feeType"].nil?
+      def installment? = self["totalInstallments"].to_i > 1
+    end
+
+    class Transaction < APIResource
+      fields :id, :description, :descriptionRaw, :currencyCode, :amount,
+        :amountInAccountCurrency, :date, :type, :balance, :providerCode,
+        :status, :category, :categoryId, :operationType,
+        :operationTypeAdditionalInfo, :providerId, :accountId, :order,
+        :createdAt, :updatedAt
+      nested paymentData: PaymentData,
+        creditCardMetadata: CreditCardMetadata,
+        merchant: Merchant
+
+      # Direction, from the account holder's point of view. Pluggy normalizes
+      # the credit-card convention, so a card purchase is always DEBIT and a
+      # payment towards the statement is always CREDIT.
+      def debit? = self["type"] == "DEBIT"
+      def credit? = self["type"] == "CREDIT"
+      alias outflow? debit?
+      alias inflow? credit?
+
+      def posted? = self["status"] == "POSTED"
+
+      # Typical of card purchases not yet on a closed bill.
+      def pending? = self["status"] == "PENDING"
+
+      def credit_card? = !self["creditCardMetadata"].nil?
+
+      def installment? = credit_card_metadata&.installment? || false
+
+      def installment_label
+        return nil unless installment?
+
+        "#{credit_card_metadata["installmentNumber"]}/#{credit_card_metadata["totalInstallments"]}"
+      end
+
+      # The bill this transaction belongs to. Since GET /v2/transactions dropped
+      # the billId filter, this is the authoritative way to group card
+      # transactions into statements.
+      def bill_id = credit_card_metadata&.[]("billId")
+
+      def bill
+        id = bill_id
+        id && ensure_client!.bills.retrieve(id)
+      end
+
+      def payment_method = payment_data&.[]("paymentMethod")
+      def pix? = payment_method == "PIX"
+      def boleto? = payment_method == "BOLETO"
+      def transfer? = %w[TED DOC TEV].include?(payment_method)
+
+      # Whoever was on the other side: the receiver of an outflow, the payer of
+      # an inflow.
+      def counterparty
+        data = payment_data
+        return nil unless data
+
+        debit? ? data.receiver : data.payer
+      end
+
+      def account = ensure_client!.accounts.retrieve(self["accountId"])
+
+      # PATCH /transactions/{id} -- the only field Pluggy lets you change.
+      def recategorize(category_id)
+        ensure_client!.transactions.update(self["id"], category_id: category_id)
+      end
+    end
+  end
+end