lunchmoney 0.10.0

data/lib/lunchmoney/crypto/crypto/crypto_base.rb

@@ -0,0 +1,65 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LunchMoney
+  # https://lunchmoney.dev/#crypto-object
+  class CryptoBase < LunchMoney::DataObject
+    include LunchMoney::Validators
+
+    sig { returns(T.nilable(Integer)) }
+    attr_accessor :id, :zabo_account_id
+
+    sig { returns(String) }
+    attr_reader :source, :created_at
+
+    sig { returns(String) }
+    attr_accessor :name, :balance
+
+    sig { returns(T.nilable(String)) }
+    attr_accessor :display_name, :institution_name
+
+    # Valid crypto source types
+    VALID_SOURCES = T.let(
+      [
+        "synced",
+        "manual",
+      ],
+      T::Array[String],
+    )
+
+    sig do
+      params(
+        created_at: String,
+        source: String,
+        name: String,
+        balance: String,
+        institution_name: T.nilable(String),
+        id: T.nilable(Integer),
+        zabo_account_id: T.nilable(Integer),
+        display_name: T.nilable(String),
+      ).void
+    end
+    def initialize(created_at:, source:, name:, balance:, institution_name: nil, id: nil, zabo_account_id: nil,
+      display_name: nil)
+      super()
+      @created_at = T.let(validate_iso8601!(created_at), String)
+      @source = T.let(validate_one_of!(source, VALID_SOURCES), String)
+      @name = name
+      @balance = balance
+      @institution_name = institution_name
+      @id = id
+      @zabo_account_id = zabo_account_id
+      @display_name = display_name
+    end
+
+    sig { params(name: String).void }
+    def source=(name)
+      @source = validate_one_of!(name, VALID_SOURCES)
+    end
+
+    sig { params(time: String).void }
+    def created_at=(time)
+      @created_at = validate_iso8601!(time)
+    end
+  end
+end

data/lib/lunchmoney/crypto/crypto_calls.rb

@@ -0,0 +1,49 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "crypto/crypto_base"
+require_relative "crypto/crypto"
+
+module LunchMoney
+  # https://lunchmoney.dev/#crypto
+  class CryptoCalls < ApiCall
+    sig { returns(T.any(T::Array[LunchMoney::Crypto], LunchMoney::Errors)) }
+    def crypto
+      response = get("crypto")
+
+      api_errors = errors(response)
+      return api_errors if api_errors.present?
+
+      response.body[:crypto].map do |crypto|
+        LunchMoney::Crypto.new(**crypto)
+      end
+    end
+
+    sig do
+      params(
+        crypto_id: Integer,
+        name: T.nilable(String),
+        display_name: T.nilable(String),
+        institution_name: T.nilable(String),
+        balance: T.nilable(String),
+        currency: T.nilable(String),
+      ).returns(T.any(LunchMoney::CryptoBase, LunchMoney::Errors))
+    end
+    def update_crypto(crypto_id, name: nil, display_name: nil, institution_name: nil, balance: nil, currency: nil)
+      params = clean_params({
+        name:,
+        display_name:,
+        institution_name:,
+        balance:,
+        currency:,
+      })
+
+      response = put("crypto/manual/#{crypto_id}", params)
+
+      api_errors = errors(response)
+      return api_errors if api_errors.present?
+
+      LunchMoney::CryptoBase.new(**response.body)
+    end
+  end
+end

data/lib/lunchmoney/data_object.rb

@@ -0,0 +1,25 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LunchMoney
+  # Base data object for the objects returned and used when calling the LunchMoney API
+  class DataObject
+    sig { params(symbolize_keys: T::Boolean).returns(T::Hash[String, T.untyped]) }
+    def serialize(symbolize_keys: false)
+      ivars = instance_variables
+
+      output = {}
+
+      ivars.each do |ivar|
+        key = ivar.to_s.gsub("@", "")
+        key = key.to_sym if symbolize_keys
+
+        value = instance_variable_get(ivar)
+
+        output[key] = value
+      end
+
+      output
+    end
+  end
+end

data/lib/lunchmoney/errors.rb

@@ -0,0 +1,19 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LunchMoney
+  # This class is used to represent errors returned directly from the LunchMoney API
+  class Errors
+    sig { returns(T::Array[String]) }
+    attr_accessor :messages
+
+    sig { params(message: T.nilable(String)).void }
+    def initialize(message: nil)
+      @messages = T.let([], T::Array[String])
+
+      @messages << message unless message.nil?
+    end
+
+    delegate :[], :<<, :each, :to_a, :first, :last, :empty?, :present?, to: :@messages
+  end
+end

data/lib/lunchmoney/exceptions.rb

@@ -0,0 +1,19 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LunchMoney
+  # Base exception class for exceptions raised by this gem
+  class Exception < StandardError; end
+
+  # Exception raised when an API Key appears to be invalid
+  class InvalidApiKey < Exception; end
+
+  # Exception raised when an object attribute is invalid
+  class InvalidObjectAttribute < Exception; end
+
+  # Exception raised when a query parameter is invalid
+  class InvalidQueryParameter < Exception; end
+
+  # Exception raised when an essential argument is missing
+  class MissingArgument < Exception; end
+end

data/lib/lunchmoney/plaid_accounts/plaid_account.rb

@@ -0,0 +1,73 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LunchMoney
+  # https://lunchmoney.dev/#plaid-accounts-object
+  class PlaidAccount < LunchMoney::DataObject
+    sig { returns(Integer) }
+    attr_accessor :id
+
+    sig { returns(String) }
+    attr_accessor :date_linked,
+      :name,
+      :type,
+      :mask,
+      :institution_name,
+      :status,
+      :balance,
+      :currency,
+      :balance_last_update,
+      :display_name,
+      :plaid_last_successful_update
+
+    sig { returns(T.nilable(String)) }
+    attr_accessor :subtype, :import_start_date, :last_fetch, :last_import
+
+    sig { returns(T.nilable(Integer)) }
+    attr_accessor :limit
+
+    sig do
+      params(
+        date_linked: String,
+        name: String,
+        type: String,
+        mask: String,
+        institution_name: String,
+        status: String,
+        balance: String,
+        currency: String,
+        balance_last_update: String,
+        display_name: String,
+        id: Integer,
+        plaid_last_successful_update: String,
+        last_import: T.nilable(String),
+        limit: T.nilable(Integer),
+        subtype: T.nilable(String),
+        import_start_date: T.nilable(String),
+        last_fetch: T.nilable(String),
+      ).void
+    end
+    def initialize(date_linked:, name:, type:, mask:, institution_name:, status:, balance:, currency:,
+      balance_last_update:, display_name:, id:, plaid_last_successful_update:, last_import: nil, limit: nil,
+      subtype: nil, import_start_date: nil, last_fetch: nil)
+      super()
+      @id = id
+      @date_linked = date_linked
+      @name = name
+      @display_name = display_name
+      @type = type
+      @subtype = subtype
+      @mask = mask
+      @institution_name = institution_name
+      @status = status
+      @limit = limit
+      @balance = balance
+      @currency = currency
+      @balance_last_update = balance_last_update
+      @import_start_date = import_start_date
+      @last_import = last_import
+      @last_fetch = last_fetch
+      @plaid_last_successful_update = plaid_last_successful_update
+    end
+  end
+end

data/lib/lunchmoney/plaid_accounts/plaid_account_calls.rb

@@ -0,0 +1,38 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "plaid_account"
+
+module LunchMoney
+  # https://lunchmoney.dev/#plaid-accounts
+  class PlaidAccountCalls < ApiCall
+    sig { returns(T.any(T::Array[LunchMoney::PlaidAccount], LunchMoney::Errors)) }
+    def plaid_accounts
+      response = get("plaid_accounts")
+
+      api_errors = errors(response)
+      return api_errors if api_errors.present?
+
+      response.body[:plaid_accounts].map do |plaid_account|
+        LunchMoney::PlaidAccount.new(**plaid_account)
+      end
+    end
+
+    sig do
+      params(
+        start_date: T.nilable(String),
+        end_date: T.nilable(String),
+        plaid_account_id: T.nilable(Integer),
+      ).returns(T.any(T::Boolean, LunchMoney::Errors))
+    end
+    def plaid_accounts_fetch(start_date: nil, end_date: nil, plaid_account_id: nil)
+      params = clean_params({ start_date:, end_date:, plaid_account_id: })
+      response = post("plaid_accounts/fetch", params)
+
+      api_errors = errors(response)
+      return api_errors if api_errors.present?
+
+      response.body
+    end
+  end
+end

data/lib/lunchmoney/recurring_expenses/recurring_expense/recurring_expense.rb

@@ -0,0 +1,65 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LunchMoney
+  # https://lunchmoney.dev/#recurring-expenses-object
+  class RecurringExpense < RecurringExpenseBase
+    sig { returns(Integer) }
+    attr_accessor :id
+
+    sig { returns(T.nilable(String)) }
+    attr_accessor :start_date, :end_date, :description, :original_name
+
+    sig { returns(String) }
+    attr_accessor :cadence, :billing_date, :type, :source, :created_at
+
+    sig { returns(T.nilable(Integer)) }
+    attr_accessor :plaid_account_id, :asset_id, :transaction_id, :category_id
+
+    sig do
+      params(
+        cadence: String,
+        payee: String,
+        amount: String,
+        currency: String,
+        billing_date: String,
+        type: String,
+        source: String,
+        id: Integer,
+        created_at: String,
+        category_id: T.nilable(Integer),
+        start_date: T.nilable(String),
+        end_date: T.nilable(String),
+        description: T.nilable(String),
+        original_name: T.nilable(String),
+        plaid_account_id: T.nilable(Integer),
+        asset_id: T.nilable(Integer),
+        transaction_id: T.nilable(Integer),
+        to_base: T.nilable(Number),
+      ).void
+    end
+    def initialize(cadence:, payee:, amount:, currency:, billing_date:, type:, source:, id:, created_at:,
+      category_id: nil, start_date: nil, end_date: nil, description: nil, original_name: nil, plaid_account_id: nil,
+      asset_id: nil, transaction_id: nil, to_base: nil)
+      super(payee:, amount:, currency:, to_base:)
+      @cadence = cadence
+      @payee = payee
+      @amount = amount
+      @currency = currency
+      @billing_date = billing_date
+      @type = type
+      @source = source
+      @id = id
+      @category_id = category_id
+      @created_at = created_at
+      @start_date = start_date
+      @end_date = end_date
+      @description = description
+      @original_name = original_name
+      @plaid_account_id = plaid_account_id
+      @asset_id = asset_id
+      @transaction_id = transaction_id
+      @to_base = to_base
+    end
+  end
+end

data/lib/lunchmoney/recurring_expenses/recurring_expense/recurring_expense_base.rb

@@ -0,0 +1,29 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LunchMoney
+  # https://lunchmoney.dev/#recurring-expenses-object
+  class RecurringExpenseBase < LunchMoney::DataObject
+    sig { returns(String) }
+    attr_accessor :payee, :currency, :amount
+
+    sig { returns(T.nilable(Number)) }
+    attr_accessor :to_base
+
+    sig do
+      params(
+        payee: String,
+        amount: String,
+        currency: String,
+        to_base: T.nilable(Number),
+      ).void
+    end
+    def initialize(payee:, amount:, currency:, to_base:)
+      super()
+      @payee = payee
+      @amount = amount
+      @currency = currency
+      @to_base = to_base
+    end
+  end
+end

data/lib/lunchmoney/recurring_expenses/recurring_expense_calls.rb

@@ -0,0 +1,28 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "recurring_expense/recurring_expense_base"
+require_relative "recurring_expense/recurring_expense"
+
+module LunchMoney
+  # https://lunchmoney.dev/#recurring-expenses
+  class RecurringExpenseCalls < ApiCall
+    sig do
+      params(
+        start_date: T.nilable(String),
+        end_date: T.nilable(String),
+      ).returns(T.any(T::Array[LunchMoney::RecurringExpense], LunchMoney::Errors))
+    end
+    def recurring_expenses(start_date: nil, end_date: nil)
+      params = clean_params({ start_date:, end_date: })
+      response = get("recurring_expenses", query_params: params)
+
+      api_errors = errors(response)
+      return api_errors if api_errors.present?
+
+      response.body[:recurring_expenses].map do |recurring_expense|
+        LunchMoney::RecurringExpense.new(**recurring_expense)
+      end
+    end
+  end
+end

data/lib/lunchmoney/tags/tag/tag.rb

@@ -0,0 +1,20 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LunchMoney
+  # https://lunchmoney.dev/#tags-object
+  class Tag < TagBase
+    sig { returns(T.nilable(String)) }
+    attr_accessor :description
+
+    sig { returns(T::Boolean) }
+    attr_accessor :archived
+
+    sig { params(id: Integer, name: String, archived: T::Boolean, description: T.nilable(String)).void }
+    def initialize(id:, name:, archived:, description: nil)
+      super(id:, name:)
+      @archived = archived
+      @description = description
+    end
+  end
+end

data/lib/lunchmoney/tags/tag/tag_base.rb

@@ -0,0 +1,21 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LunchMoney
+  # https://lunchmoney.dev/#tags-object without some fields. This is used within field returns of other objects like
+  # field returns of other objects like transactions
+  class TagBase < LunchMoney::DataObject
+    sig { returns(Integer) }
+    attr_accessor :id
+
+    sig { returns(String) }
+    attr_accessor :name
+
+    sig { params(id: Integer, name: String).void }
+    def initialize(id:, name:)
+      super()
+      @id = id
+      @name = name
+    end
+  end
+end

data/lib/lunchmoney/tags/tag_calls.rb

@@ -0,0 +1,20 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "tag/tag_base"
+require_relative "tag/tag"
+
+module LunchMoney
+  # https://lunchmoney.dev/#tags
+  class TagCalls < ApiCall
+    sig { returns(T.any(T::Array[LunchMoney::Tag], LunchMoney::Errors)) }
+    def tags
+      response = get("tags")
+
+      api_errors = errors(response)
+      return api_errors if api_errors.present?
+
+      response.body.map { |tag| LunchMoney::Tag.new(**tag) }
+    end
+  end
+end

data/lib/lunchmoney/transactions/transaction/child_transaction.rb

@@ -0,0 +1,31 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LunchMoney
+  # Slimmed down version of https://lunchmoney.dev/#transaction-object used in the
+  # `children` field of a transaction object with an additional `formatted_date`` field
+  class ChildTransaction < TransactionBase
+    sig { returns(String) }
+    attr_accessor :formatted_date
+
+    sig do
+      params(
+        id: Integer,
+        date: String,
+        amount: String,
+        currency: String,
+        to_base: Number,
+        payee: String,
+        formatted_date: String,
+        notes: T.nilable(String),
+        asset_id: T.nilable(Integer),
+        plaid_account_id: T.nilable(Integer),
+      ).void
+    end
+    def initialize(id:, date:, amount:, currency:, to_base:, payee:, formatted_date:, notes: nil, asset_id: nil,
+      plaid_account_id: nil)
+      super(id:, date:, amount:, currency:, to_base:, payee:, notes:, asset_id:, plaid_account_id:)
+      @formatted_date = formatted_date
+    end
+  end
+end

data/lib/lunchmoney/transactions/transaction/split.rb

@@ -0,0 +1,24 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LunchMoney
+  # Object used to split a transaction when updating https://lunchmoney.dev/#update-transaction
+  class Split < TransactionModificationBase
+    sig { returns(T.any(Number, String)) }
+    attr_accessor :amount
+
+    sig do
+      params(
+        amount: T.any(Number, String),
+        payee: T.nilable(String),
+        date: T.nilable(String),
+        category_id: T.nilable(Integer),
+        notes: T.nilable(String),
+      ).void
+    end
+    def initialize(amount:, payee: nil, date: nil, category_id: nil, notes: nil)
+      super(payee:, date:, category_id:, notes:)
+      @amount = amount
+    end
+  end
+end

data/lib/lunchmoney/transactions/transaction/transaction.rb

@@ -0,0 +1,156 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LunchMoney
+  # https://lunchmoney.dev/#transaction-object
+  class Transaction < TransactionBase
+    sig { returns(T.nilable(Integer)) }
+    attr_accessor :category_id,
+      :category_group_id,
+      :recurring_id,
+      :parent_id,
+      :group_id,
+      :external_id
+
+    sig { returns(String) }
+    attr_accessor :created_at,
+      :updated_at,
+      :status,
+      :source,
+      :display_name,
+      :account_display_name
+
+    sig { returns(T.nilable(String)) }
+    attr_accessor :category_name,
+      :category_group_name,
+      :original_name,
+      :recurring_payee,
+      :recurring_description,
+      :recurring_cadence,
+      :recurring_type,
+      :recurring_amount,
+      :recurring_currency,
+      :asset_institution_name,
+      :asset_name,
+      :asset_display_name,
+      :asset_status,
+      :plaid_account_name,
+      :plaid_account_mask,
+      :institution_name,
+      :plaid_account_display_name,
+      :plaid_metadata,
+      :display_notes
+
+    sig { returns(T::Boolean) }
+    attr_accessor :is_income, :exclude_from_budget, :exclude_from_totals, :is_pending, :has_children, :is_group
+
+    sig { returns(T::Array[LunchMoney::TagBase]) }
+    attr_accessor :tags
+
+    sig { returns(T.nilable(T::Array[LunchMoney::ChildTransaction])) }
+    attr_accessor :children
+
+    sig do
+      params(
+        id: Integer,
+        date: String,
+        amount: String,
+        currency: String,
+        to_base: Number,
+        payee: String,
+        is_income: T::Boolean,
+        exclude_from_budget: T::Boolean,
+        exclude_from_totals: T::Boolean,
+        created_at: String,
+        updated_at: String,
+        status: String,
+        is_pending: T::Boolean,
+        has_children: T::Boolean,
+        is_group: T::Boolean,
+        source: String,
+        display_name: String,
+        account_display_name: String,
+        tags: T::Array[LunchMoney::TagBase],
+        category_id: T.nilable(Integer),
+        category_name: T.nilable(String),
+        category_group_id: T.nilable(Integer),
+        category_group_name: T.nilable(String),
+        notes: T.nilable(String),
+        original_name: T.nilable(String),
+        recurring_id: T.nilable(Integer),
+        recurring_payee: T.nilable(String),
+        recurring_description: T.nilable(String),
+        recurring_cadence: T.nilable(String),
+        recurring_type: T.nilable(String),
+        recurring_amount: T.nilable(String),
+        recurring_currency: T.nilable(String),
+        parent_id: T.nilable(Integer),
+        group_id: T.nilable(Integer),
+        asset_id: T.nilable(Integer),
+        asset_institution_name: T.nilable(String),
+        asset_name: T.nilable(String),
+        asset_display_name: T.nilable(String),
+        asset_status: T.nilable(String),
+        plaid_account_id: T.nilable(Integer),
+        plaid_account_name: T.nilable(String),
+        plaid_account_mask: T.nilable(String),
+        institution_name: T.nilable(String),
+        plaid_account_display_name: T.nilable(String),
+        plaid_metadata: T.nilable(String),
+        display_notes: T.nilable(String),
+        external_id: T.nilable(Integer),
+        children: T.nilable(T::Array[LunchMoney::ChildTransaction]),
+      ).void
+    end
+    def initialize(id:, date:, amount:, currency:, to_base:, payee:, is_income:, exclude_from_budget:,
+      exclude_from_totals:, created_at:, updated_at:, status:, is_pending:, has_children:, is_group:, source:,
+      display_name:, account_display_name:, tags:, category_id: nil, category_name: nil, category_group_id: nil,
+      category_group_name: nil, notes: nil, original_name: nil, recurring_id: nil, recurring_payee: nil,
+      recurring_description: nil, recurring_cadence: nil, recurring_type: nil, recurring_amount: nil,
+      recurring_currency: nil, parent_id: nil, group_id: nil, asset_id: nil, asset_institution_name: nil,
+      asset_name: nil, asset_display_name: nil, asset_status: nil, plaid_account_id: nil, plaid_account_name: nil,
+      plaid_account_mask: nil, institution_name: nil, plaid_account_display_name: nil, plaid_metadata: nil,
+      display_notes: nil, external_id: nil, children: nil)
+      super(id:, date:, amount:, currency:, to_base:, payee:, notes:, asset_id:, plaid_account_id:)
+      @is_income = is_income
+      @exclude_from_budget = exclude_from_budget
+      @exclude_from_totals = exclude_from_totals
+      @created_at = created_at
+      @updated_at = updated_at
+      @status = status
+      @is_pending = is_pending
+      @has_children = has_children
+      @is_group = is_group
+      @source = source
+      @display_name = display_name
+      @account_display_name = account_display_name
+      @tags = tags
+      @category_id = category_id
+      @category_name = category_name
+      @category_group_id = category_group_id
+      @category_group_name = category_group_name
+      @original_name = original_name
+      @recurring_id = recurring_id
+      @recurring_payee = recurring_payee
+      @recurring_description = recurring_description
+      @recurring_cadence = recurring_cadence
+      @recurring_type = recurring_type
+      @recurring_amount = recurring_amount
+      @recurring_currency = recurring_currency
+      @parent_id = parent_id
+      @group_id = group_id
+      @asset_institution_name = asset_institution_name
+      @asset_name = asset_name
+      @asset_display_name = asset_display_name
+      @asset_status = asset_status
+      @plaid_account_name = plaid_account_name
+      @plaid_account_mask = plaid_account_mask
+      @institution_name = institution_name
+      @plaid_account_display_name = plaid_account_display_name
+      @plaid_metadata = plaid_metadata
+      @display_notes = display_notes
+      @children = children
+      @external_id = external_id
+    end
+  end
+end