lunchmoney 1.0.0 → 1.1.1

data/lib/lunchmoney/calls/transactions.rb

@@ -0,0 +1,220 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../objects/child_transaction"
+require_relative "../objects/transaction"
+require_relative "../objects/split"
+require_relative "../objects/update_transaction"
+
+module LunchMoney
+  module Calls
+    # https://lunchmoney.dev/#transactions
+    class Transactions < LunchMoney::Calls::Base
+      sig do
+        params(
+          tag_id: T.nilable(Integer),
+          recurring_id: T.nilable(Integer),
+          plaid_account_id: T.nilable(Integer),
+          category_id: T.nilable(Integer),
+          asset_id: T.nilable(Integer),
+          is_group: T.nilable(T::Boolean),
+          status: T.nilable(String),
+          start_date: T.nilable(String),
+          end_date: T.nilable(String),
+          debit_as_negative: T.nilable(T::Boolean),
+          pending: T.nilable(T::Boolean),
+          offset: T.nilable(Integer),
+          limit: T.nilable(Integer),
+        ).returns(T.any(T::Array[LunchMoney::Objects::Transaction], LunchMoney::Errors))
+      end
+      def transactions(
+        tag_id: nil,
+        recurring_id: nil,
+        plaid_account_id: nil,
+        category_id: nil,
+        asset_id: nil,
+        is_group: nil,
+        status: nil,
+        start_date: nil,
+        end_date: nil,
+        debit_as_negative: nil,
+        pending: nil,
+        offset: nil,
+        limit: nil
+      )
+
+        params = clean_params({
+          tag_id:,
+          recurring_id:,
+          plaid_account_id:,
+          category_id:,
+          asset_id:,
+          is_group:,
+          status:,
+          start_date:,
+          end_date:,
+          debit_as_negative:,
+          pending:,
+          offset:,
+          limit:,
+        })
+        response = get("transactions", query_params: params)
+
+        api_errors = errors(response)
+        return api_errors if api_errors.present?
+
+        response.body[:transactions].map do |transaction|
+          transaction[:tags].map! { |tag| LunchMoney::Objects::TagBase.new(**tag) }
+
+          transaction[:children]&.map! do |child_transaction|
+            LunchMoney::Objects::ChildTransaction.new(**child_transaction)
+          end
+
+          LunchMoney::Objects::Transaction.new(**transaction)
+        end
+      end
+
+      sig do
+        params(
+          transaction_id: Integer,
+          debit_as_negative: T.nilable(T::Boolean),
+        ).returns(T.any(LunchMoney::Objects::Transaction, LunchMoney::Errors))
+      end
+      def transaction(transaction_id, debit_as_negative: nil)
+        params = clean_params({ debit_as_negative: })
+        response = get("transactions/#{transaction_id}", query_params: params)
+
+        api_errors = errors(response)
+        return api_errors if api_errors.present?
+
+        LunchMoney::Objects::Transaction.new(**response.body)
+      end
+
+      sig do
+        params(
+          transactions: T::Array[LunchMoney::Objects::UpdateTransaction],
+          apply_rules: T.nilable(T::Boolean),
+          skip_duplicates: T.nilable(T::Boolean),
+          check_for_recurring: T.nilable(T::Boolean),
+          debit_as_negative: T.nilable(T::Boolean),
+          skip_balance_update: T.nilable(T::Boolean),
+        ).returns(T.any(T::Hash[Symbol, T::Array[Integer]], LunchMoney::Errors))
+      end
+      def insert_transactions(transactions, apply_rules: nil, skip_duplicates: nil,
+        check_for_recurring: nil, debit_as_negative: nil, skip_balance_update: nil)
+        params = clean_params({
+          transactions: transactions.map(&:serialize),
+          apply_rules:,
+          skip_duplicates:,
+          check_for_recurring:,
+          debit_as_negative:,
+          skip_balance_update:,
+        })
+        response = post("transactions", params)
+
+        api_errors = errors(response)
+        return api_errors if api_errors.present?
+
+        response.body
+      end
+
+      sig do
+        params(
+          transaction_id: Integer,
+          transaction: T.nilable(LunchMoney::Objects::UpdateTransaction),
+          split: T.nilable(T::Array[LunchMoney::Objects::Split]),
+          debit_as_negative: T.nilable(T::Boolean),
+          skip_balance_update: T.nilable(T::Boolean),
+        ).returns(T.any({ updated: T::Boolean, split: T.nilable(T::Array[Integer]) }, LunchMoney::Errors))
+      end
+      def update_transaction(transaction_id, transaction: nil, split: nil,
+        debit_as_negative: nil, skip_balance_update: nil)
+        raise(
+          LunchMoney::MissingArgument,
+          "Either a transaction or split must be provided",
+        ) if transaction.nil? && split.nil?
+
+        params = clean_params({
+          transaction: transaction&.serialize,
+          split: split&.map!(&:serialize),
+          debit_as_negative:,
+          skip_balance_update:,
+        })
+        response = put("transactions/#{transaction_id}", params)
+
+        api_errors = errors(response)
+        return api_errors if api_errors.present?
+
+        response.body
+      end
+
+      sig do
+        params(
+          parent_ids: T::Array[Integer],
+          remove_parents: T.nilable(T::Boolean),
+        ).returns(T.any(T::Array[Integer], LunchMoney::Errors))
+      end
+      def unsplit_transaction(parent_ids, remove_parents: false)
+        params = { parent_ids:, remove_parents: }
+        response = post("transactions/unsplit", params)
+
+        api_errors = errors(response)
+        return api_errors if api_errors.present?
+
+        response.body
+      end
+
+      sig { params(transaction_id: Integer).returns(T.any(LunchMoney::Objects::Transaction, LunchMoney::Errors)) }
+      def transaction_group(transaction_id)
+        response = get("transactions/group", query_params: { transaction_id: })
+
+        api_errors = errors(response)
+        return api_errors if api_errors.present?
+
+        LunchMoney::Objects::Transaction.new(**response.body)
+      end
+
+      sig do
+        params(
+          date: String,
+          payee: String,
+          transactions: T::Array[T.any(Integer, String)],
+          category_id: T.nilable(Integer),
+          notes: T.nilable(String),
+          tags: T.nilable(T::Array[T.any(Integer, String)]),
+        ).returns(T.any(Integer, LunchMoney::Errors))
+      end
+      def create_transaction_group(date:, payee:, transactions:, category_id: nil, notes: nil, tags: nil)
+        params = clean_params({
+          date:,
+          payee:,
+          transactions:,
+          category_id:,
+          notes:,
+          tags:,
+        })
+        response = post("transactions/group", params)
+
+        api_errors = errors(response)
+        return api_errors if api_errors.present?
+
+        response.body
+      end
+
+      sig do
+        params(transaction_id: T.any(
+          String,
+          Integer,
+        )).returns(T.any(T::Hash[Symbol, T::Array[Integer]], LunchMoney::Errors))
+      end
+      def delete_transaction_group(transaction_id)
+        response = delete("transactions/group/#{transaction_id}")
+
+        api_errors = errors(response)
+        return api_errors if api_errors.present?
+
+        response.body
+      end
+    end
+  end
+end

data/lib/lunchmoney/calls/users.rb

@@ -0,0 +1,21 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../objects/user"
+
+module LunchMoney
+  module Calls
+    # https://lunchmoney.dev/#user
+    class Users < LunchMoney::Calls::Base
+      sig { returns(T.any(LunchMoney::Objects::User, LunchMoney::Errors)) }
+      def me
+        response = get("me")
+
+        api_errors = errors(response)
+        return api_errors if api_errors.present?
+
+        LunchMoney::Objects::User.new(**response.body)
+      end
+    end
+  end
+end

data/lib/lunchmoney/errors.rb

@@ -2,7 +2,23 @@
 # frozen_string_literal: true
 
 module LunchMoney
-  # This class is used to represent errors returned directly from the LunchMoney API
+  # This class is used to represent errors returned directly from the LunchMoney API. This class has been set up to act
+  # like an array, delegating a lot of common array getter methods directly to messages for you.
+  # @example
+  #   api = LunchMoney::Api.new
+  #   response = api.categories
+  #
+  #   response.class
+  #   => LunchMoney::Errors
+  #
+  #   response.first
+  #   => "Some error returned by the API"
+  #
+  #   response.empty?
+  #   => false
+  #
+  #   response[0]
+  #   => "Some error returned by the API"
   class Errors
     sig { returns(T::Array[String]) }
     attr_accessor :messages

data/lib/lunchmoney/objects/asset.rb

@@ -0,0 +1,92 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LunchMoney
+  module Objects
+    # https://lunchmoney.dev/#assets-object
+    class Asset < LunchMoney::Objects::Object
+      include LunchMoney::Validators
+
+      sig { returns(Integer) }
+      attr_accessor :id
+
+      sig { returns(String) }
+      attr_reader :type_name, :balance_as_of, :created_at
+
+      sig { returns(String) }
+      attr_accessor :name, :balance, :currency
+
+      sig { returns(T.nilable(String)) }
+      attr_accessor :display_name, :closed_on, :institution_name, :subtype_name
+
+      sig { returns(T::Boolean) }
+      attr_accessor :exclude_transactions
+
+      # Valid asset type names
+      VALID_TYPE_NAMES = T.let(
+        [
+          "cash",
+          "credit",
+          "investment",
+          "real estate",
+          "loan",
+          "vehicle",
+          "cryptocurrency",
+          "employee compensation",
+          "other liability",
+          "other asset",
+          "depository",
+        ],
+        T::Array[String],
+      )
+
+      sig do
+        params(
+          created_at: String,
+          type_name: String,
+          name: String,
+          balance: String,
+          balance_as_of: String,
+          currency: String,
+          exclude_transactions: T::Boolean,
+          id: Integer,
+          subtype_name: T.nilable(String),
+          display_name: T.nilable(String),
+          closed_on: T.nilable(String),
+          institution_name: T.nilable(String),
+        ).void
+      end
+      def initialize(created_at:, type_name:, name:, balance:, balance_as_of:, currency:, exclude_transactions:, id:,
+        subtype_name: nil, display_name: nil, closed_on: nil, institution_name: nil)
+        super()
+        @created_at = T.let(validate_iso8601!(created_at), String)
+        @type_name = T.let(validate_one_of!(type_name, VALID_TYPE_NAMES), String)
+        @name = name
+        @balance = balance
+        @balance_as_of = T.let(validate_iso8601!(balance_as_of), String)
+        @currency = currency
+        @exclude_transactions = exclude_transactions
+        @id = id
+        @subtype_name = subtype_name
+        @display_name = display_name
+        @closed_on = closed_on
+        @institution_name = institution_name
+      end
+
+      sig { params(name: String).void }
+      def type_name=(name)
+        @type_name = validate_one_of!(name, VALID_TYPE_NAMES)
+      end
+
+      sig { params(time: String).void }
+      def balance_as_of=(time)
+        @balance_as_of = validate_iso8601!(time)
+      end
+
+      sig { params(time: String).void }
+      def created_at=(time)
+        @created_at = validate_iso8601!(time)
+      end
+    end
+  end
+end

data/lib/lunchmoney/objects/budget.rb

@@ -0,0 +1,76 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "data"
+require_relative "config"
+
+module LunchMoney
+  module Objects
+    # https://lunchmoney.dev/#budget-object
+    class Budget < LunchMoney::Objects::Object
+      # API object reference documentation: https://lunchmoney.dev/#budget-object
+
+      sig { returns(String) }
+      attr_accessor :category_name
+
+      sig { returns(Integer) }
+      attr_accessor :order
+
+      sig { returns(T.nilable(String)) }
+      attr_accessor :category_group_name
+
+      sig { returns(T.nilable(Integer)) }
+      attr_accessor :category_id, :group_id
+
+      sig { returns(T.nilable(T::Boolean)) }
+      attr_accessor :is_group
+
+      sig { returns(T::Boolean) }
+      attr_accessor :is_income, :exclude_from_budget, :exclude_from_totals, :archived
+
+      sig { returns(T::Hash[Symbol, LunchMoney::Objects::Data]) }
+      attr_accessor :data
+
+      sig { returns(T.nilable(T::Hash[Symbol, LunchMoney::Objects::Config])) }
+      attr_accessor :config
+
+      sig { returns(T.nilable({ list: T::Array[LunchMoney::Objects::RecurringExpense] })) }
+      attr_accessor :recurring
+
+      sig do
+        params(
+          is_income: T::Boolean,
+          exclude_from_budget: T::Boolean,
+          exclude_from_totals: T::Boolean,
+          data: T::Hash[Symbol, LunchMoney::Objects::Data],
+          category_name: String,
+          order: Integer,
+          archived: T::Boolean,
+          category_id: T.nilable(Integer),
+          category_group_name: T.nilable(String),
+          group_id: T.nilable(Integer),
+          is_group: T.nilable(T::Boolean),
+          config: T.nilable(T::Hash[Symbol, LunchMoney::Objects::Config]),
+          recurring: T.nilable({ list: T::Array[LunchMoney::Objects::RecurringExpense] }),
+        ).void
+      end
+      def initialize(is_income:, exclude_from_budget:, exclude_from_totals:, data:, category_name:, order:, archived:,
+        category_id: nil, category_group_name: nil, group_id: nil, is_group: nil, config: nil, recurring: nil)
+        super()
+        @category_id = category_id
+        @is_income = is_income
+        @exclude_from_budget = exclude_from_budget
+        @exclude_from_totals = exclude_from_totals
+        @data = data
+        @category_name = category_name
+        @order = order
+        @category_group_name = category_group_name
+        @group_id = group_id
+        @is_group = is_group
+        @config = config
+        @archived = archived
+        @recurring = recurring
+      end
+    end
+  end
+end

data/lib/lunchmoney/objects/category.rb

@@ -0,0 +1,55 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "child_category"
+module LunchMoney
+  module Objects
+    # https://lunchmoney.dev/#categories-object
+    class Category < ChildCategory
+      sig { returns(T.nilable(String)) }
+      attr_accessor :group_category_name
+
+      sig { returns(T::Boolean) }
+      attr_accessor :is_income, :exclude_from_budget, :exclude_from_totals, :is_group
+
+      sig { returns(T.nilable(Integer)) }
+      attr_accessor :group_id, :order
+
+      sig { returns(T.nilable(T::Array[T.any(LunchMoney::Objects::Category, LunchMoney::Objects::ChildCategory)])) }
+      attr_accessor :children
+
+      sig do
+        params(
+          id: Integer,
+          name: String,
+          is_income: T::Boolean,
+          exclude_from_budget: T::Boolean,
+          exclude_from_totals: T::Boolean,
+          is_group: T::Boolean,
+          archived: T.nilable(T::Boolean),
+          archived_on: T.nilable(String),
+          updated_at: T.nilable(String),
+          created_at: T.nilable(String),
+          group_id: T.nilable(Integer),
+          order: T.nilable(Integer),
+          description: T.nilable(String),
+          children: T.nilable(T::Array[T.any(LunchMoney::Objects::Category, LunchMoney::Objects::ChildCategory)]),
+          group_category_name: T.nilable(String),
+        ).void
+      end
+      def initialize(id:, name:, is_income:, exclude_from_budget:, exclude_from_totals:, is_group:, archived: nil,
+        archived_on: nil, updated_at: nil, created_at: nil, group_id: nil, order: nil, description: nil, children: nil,
+        group_category_name: nil)
+        super(id:, name:, archived:, archived_on:, updated_at:, created_at:, description:)
+        @is_income = is_income
+        @exclude_from_budget = exclude_from_budget
+        @exclude_from_totals = exclude_from_totals
+        @is_group = is_group
+        @group_id = group_id
+        @order = order
+        @children = children
+        @group_category_name = group_category_name
+      end
+    end
+  end
+end

data/lib/lunchmoney/objects/child_category.rb

@@ -0,0 +1,44 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LunchMoney
+  module Objects
+    # A slimmed down version of https://lunchmoney.dev/#categories-object used in the
+    # `children` field of some category calls
+    class ChildCategory < LunchMoney::Objects::Object
+      sig { returns(Integer) }
+      attr_accessor :id
+
+      sig { returns(String) }
+      attr_accessor :name
+
+      sig { returns(T.nilable(String)) }
+      attr_accessor :description, :archived_on, :updated_at, :created_at
+
+      sig { returns(T.nilable(T::Boolean)) }
+      attr_accessor :archived
+
+      sig do
+        params(
+          id: Integer,
+          name: String,
+          archived: T.nilable(T::Boolean),
+          archived_on: T.nilable(String),
+          updated_at: T.nilable(String),
+          created_at: T.nilable(String),
+          description: T.nilable(String),
+        ).void
+      end
+      def initialize(id:, name:, archived: nil, archived_on: nil, updated_at: nil, created_at: nil, description: nil)
+        super()
+        @id = id
+        @name = name
+        @archived = archived
+        @archived_on = archived_on
+        @updated_at = updated_at
+        @created_at = created_at
+        @description = description
+      end
+    end
+  end
+end

data/lib/lunchmoney/objects/child_transaction.rb

@@ -0,0 +1,35 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "transaction_base"
+
+module LunchMoney
+  module Objects
+    # 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
+end

data/lib/lunchmoney/objects/config.rb

@@ -0,0 +1,40 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LunchMoney
+  module Objects
+    # https://lunchmoney.dev/#config-object
+    class Config < LunchMoney::Objects::Object
+      # API object reference documentation: https://lunchmoney.dev/#config-object
+
+      sig { returns(Integer) }
+      attr_accessor :config_id
+
+      sig { returns(Number) }
+      attr_accessor :amount, :to_base
+
+      sig { returns(String) }
+      attr_accessor :cadence, :currency, :auto_suggest
+
+      sig do
+        params(
+          config_id: Integer,
+          cadence: String,
+          amount: Number,
+          currency: String,
+          to_base: Number,
+          auto_suggest: String,
+        ).void
+      end
+      def initialize(config_id:, cadence:, amount:, currency:, to_base:, auto_suggest:)
+        super()
+        @config_id = config_id
+        @cadence = cadence
+        @amount = amount
+        @currency = currency
+        @to_base = to_base
+        @auto_suggest = auto_suggest
+      end
+    end
+  end
+end

data/lib/lunchmoney/objects/crypto.rb

@@ -0,0 +1,46 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "crypto_base"
+module LunchMoney
+  module Objects
+    # https://lunchmoney.dev/#crypto-object
+    class Crypto < CryptoBase
+      include LunchMoney::Validators
+
+      sig { returns(String) }
+      attr_reader :balance_as_of
+
+      sig { returns(String) }
+      attr_accessor :currency, :status
+
+      sig do
+        params(
+          created_at: String,
+          source: String,
+          name: String,
+          balance: String,
+          balance_as_of: String,
+          currency: String,
+          status: 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:, balance_as_of:, currency:,
+        status:, institution_name: nil, id: nil, zabo_account_id: nil, display_name: nil)
+        super(created_at:, source:, name:, balance:, institution_name:, id:, zabo_account_id:, display_name:)
+        @balance_as_of = T.let(validate_iso8601!(balance_as_of), String)
+        @currency = currency
+        @status = status
+      end
+
+      sig { params(time: String).void }
+      def balance_as_of=(time)
+        @balance_as_of = validate_iso8601!(time)
+      end
+    end
+  end
+end