lunchmoney 0.10.0

data/lib/lunchmoney/assets/asset_calls.rb

@@ -0,0 +1,96 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "asset"
+
+module LunchMoney
+  # https://lunchmoney.dev/#assets
+  class AssetCalls < ApiCall
+    sig { returns(T.any(T::Array[LunchMoney::Asset], LunchMoney::Errors)) }
+    def assets
+      response = get("assets")
+
+      api_errors = errors(response)
+      return api_errors if api_errors.present?
+
+      response.body[:assets].map do |asset|
+        LunchMoney::Asset.new(**asset)
+      end
+    end
+
+    sig do
+      params(
+        type_name: String,
+        name: String,
+        balance: String,
+        subtype_name: T.nilable(String),
+        display_name: T.nilable(String),
+        balance_as_of: T.nilable(String),
+        currency: T.nilable(String),
+        institution_name: T.nilable(String),
+        closed_on: T.nilable(String),
+        exclude_transactions: T.nilable(T::Boolean),
+      ).returns(T.any(LunchMoney::Asset, LunchMoney::Errors))
+    end
+    def create_asset(type_name:, name:, balance:, subtype_name: nil, display_name: nil, balance_as_of: nil,
+      currency: nil, institution_name: nil, closed_on: nil, exclude_transactions: nil)
+      params = {
+        type_name:,
+        name:,
+        balance:,
+        subtype_name:,
+        display_name:,
+        balance_as_of:,
+        currency:,
+        institution_name:,
+        closed_on:,
+        exclude_transactions:,
+      }
+
+      response = post("assets", params)
+
+      api_errors = errors(response)
+      return api_errors if api_errors.present?
+
+      LunchMoney::Asset.new(**response.body)
+    end
+
+    sig do
+      params(
+        asset_id: Integer,
+        type_name: T.nilable(String),
+        name: T.nilable(String),
+        balance: T.nilable(String),
+        subtype_name: T.nilable(String),
+        display_name: T.nilable(String),
+        balance_as_of: T.nilable(String),
+        currency: T.nilable(String),
+        institution_name: T.nilable(String),
+        closed_on: T.nilable(String),
+        exclude_transactions: T.nilable(T::Boolean),
+      ).returns(T.any(LunchMoney::Asset, LunchMoney::Errors))
+    end
+    def update_asset(asset_id, type_name: nil, name: nil, balance: nil, subtype_name: nil, display_name: nil,
+      balance_as_of: nil, currency: nil, institution_name: nil, closed_on: nil, exclude_transactions: nil)
+      params = {
+        type_name:,
+        name:,
+        balance:,
+        subtype_name:,
+        display_name:,
+        balance_as_of:,
+        currency:,
+        institution_name:,
+        closed_on:,
+        exclude_transactions:,
+      }
+
+      response = put("assets/#{asset_id}", params)
+
+      api_errors = errors(response)
+      return api_errors if api_errors.present?
+
+      LunchMoney::Asset.new(**response.body)
+    end
+  end
+end

data/lib/lunchmoney/budget/budget.rb

@@ -0,0 +1,74 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "data"
+require_relative "config"
+
+module LunchMoney
+  # https://lunchmoney.dev/#budget-object
+  class Budget < LunchMoney::DataObject
+    # 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::Data]) }
+    attr_accessor :data
+
+    sig { returns(T.nilable(T::Hash[Symbol, LunchMoney::Config])) }
+    attr_accessor :config
+
+    sig { returns(T.nilable({ list: T::Array[LunchMoney::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::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::Config]),
+        recurring: T.nilable({ list: T::Array[LunchMoney::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

data/lib/lunchmoney/budget/budget_calls.rb

@@ -0,0 +1,82 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "budget"
+
+module LunchMoney
+  # https://lunchmoney.dev/#budget
+  class BudgetCalls < ApiCall
+    sig do
+      params(
+        start_date: String,
+        end_date: String,
+        currency: T.nilable(String),
+      ).returns(T.any(T::Array[LunchMoney::Budget], LunchMoney::Errors))
+    end
+    def budgets(start_date:, end_date:, currency: nil)
+      params = clean_params({ start_date:, end_date:, currency: })
+      response = get("budgets", query_params: params)
+
+      api_errors = errors(response)
+      return api_errors if api_errors.present?
+
+      response.body.map do |budget|
+        if budget[:data]
+          data_keys = budget[:data].keys
+          data_keys.each do |data_key|
+            budget[:data][data_key] = LunchMoney::Data.new(**budget[:data][data_key])
+          end
+        end
+
+        if budget[:config]
+          config_keys = budget[:config].keys
+          config_keys.each do |config_key|
+            budget[:config][config_key] = LunchMoney::Data.new(**budget[:config][config_key])
+          end
+        end
+
+        if budget[:recurring]
+          budget[:recurring][:list]&.map! { |recurring| LunchMoney::RecurringExpenseBase.new(**recurring) }
+        end
+
+        LunchMoney::Budget.new(**budget)
+      end
+    end
+
+    sig do
+      params(
+        start_date: String,
+        category_id: Integer,
+        amount: Number,
+        currency: T.nilable(String),
+      ).returns(T.any(
+        T::Hash[Symbol, { category_id: Integer, amount: Number, currency: String, start_date: String }],
+        LunchMoney::Errors,
+      ))
+    end
+    def upsert_budget(start_date:, category_id:, amount:, currency: nil)
+      params = clean_params({ start_date:, category_id:, amount:, currency: })
+      response = put("budgets", params)
+
+      api_errors = errors(response)
+      return api_errors if api_errors.present?
+
+      response.body
+    end
+
+    sig { params(start_date: String, category_id: Integer).returns(T.any(T::Boolean, LunchMoney::Errors)) }
+    def remove_budget(start_date:, category_id:)
+      params = {
+        start_date:,
+        category_id:,
+      }
+
+      response = delete("budgets", query_params: params)
+
+      api_errors = errors(response)
+      return api_errors if api_errors.present?
+
+      response.body
+    end
+  end
+end

data/lib/lunchmoney/budget/config.rb

@@ -0,0 +1,38 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LunchMoney
+  # https://lunchmoney.dev/#config-object
+  class Config < LunchMoney::DataObject
+    # 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

data/lib/lunchmoney/budget/data.rb

@@ -0,0 +1,42 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LunchMoney
+  # https://lunchmoney.dev/#data-object
+  class Data < LunchMoney::DataObject
+    # API object reference documentation: https://lunchmoney.dev/#data-object
+
+    sig { returns(T.nilable(Integer)) }
+    attr_accessor :num_transactions
+
+    sig { returns(T.nilable(Number)) }
+    attr_accessor :budget_amount, :budget_to_base, :spending_to_base
+
+    sig { returns(T.nilable(String)) }
+    attr_accessor :budget_currency
+
+    sig { returns(T.nilable(T::Boolean)) }
+    attr_accessor :is_automated
+
+    sig do
+      params(
+        spending_to_base: T.nilable(Number),
+        num_transactions: T.nilable(Integer),
+        budget_amount: T.nilable(Number),
+        budget_currency: T.nilable(String),
+        budget_to_base: T.nilable(Number),
+        is_automated: T.nilable(T::Boolean),
+      ).void
+    end
+    def initialize(spending_to_base: nil, num_transactions: nil, budget_amount: nil, budget_currency: nil,
+      budget_to_base: nil, is_automated: nil)
+      super()
+      @budget_amount = budget_amount
+      @budget_currency = budget_currency
+      @budget_to_base = budget_to_base
+      @spending_to_base = spending_to_base
+      @num_transactions = num_transactions
+      @is_automated = is_automated
+    end
+  end
+end

data/lib/lunchmoney/categories/category/category.rb

@@ -0,0 +1,52 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LunchMoney
+  # 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::Category, LunchMoney::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::Category, LunchMoney::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

data/lib/lunchmoney/categories/category/child_category.rb

@@ -0,0 +1,42 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LunchMoney
+  # A slimmed down version of https://lunchmoney.dev/#categories-object used in the
+  # `children` field of some category calls
+  class ChildCategory < LunchMoney::DataObject
+    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

data/lib/lunchmoney/categories/category_calls.rb

@@ -0,0 +1,195 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "category/child_category"
+require_relative "category/category"
+
+module LunchMoney
+  # https://lunchmoney.dev/#categories
+  class CategoryCalls < ApiCall
+    # Valid query parameter formets for categories
+    VALID_FORMATS = T.let(
+      [
+        "flattened",
+        "nested",
+      ],
+      T::Array[String],
+    )
+
+    sig do
+      params(
+        format: T.nilable(T.any(String, Symbol)),
+      ).returns(T.any(T::Array[LunchMoney::Category], LunchMoney::Errors))
+    end
+    def categories(format: nil)
+      response = get("categories", query_params: categories_params(format:))
+
+      api_errors = errors(response)
+      return api_errors if api_errors.present?
+
+      response.body[:categories].map do |category|
+        category[:children]&.map! { |child_category| LunchMoney::Category.new(**child_category) }
+
+        LunchMoney::Category.new(**category)
+      end
+    end
+
+    sig { params(category_id: Integer).returns(T.any(LunchMoney::Category, LunchMoney::Errors)) }
+    def category(category_id)
+      response = get("categories/#{category_id}")
+
+      api_errors = errors(response)
+      return api_errors if api_errors.present?
+
+      response.body[:children]&.map! { |child_category| LunchMoney::ChildCategory.new(**child_category) }
+
+      LunchMoney::Category.new(**response.body)
+    end
+
+    sig do
+      params(
+        name: String,
+        description: T.nilable(String),
+        is_income: T::Boolean,
+        exclude_from_budget: T::Boolean,
+        exclude_from_totals: T::Boolean,
+        archived: T::Boolean,
+        group_id: T.nilable(Integer),
+      ).returns(T.any(T::Hash[Symbol, Integer], LunchMoney::Errors))
+    end
+    def create_category(name:, description: nil, is_income: false, exclude_from_budget: false,
+      exclude_from_totals: false, archived: false, group_id: nil)
+      params = clean_params({
+        name:,
+        description:,
+        is_income:,
+        exclude_from_budget:,
+        exclude_from_totals:,
+        archived:,
+        group_id:,
+      })
+      response = post("categories", params)
+
+      api_errors = errors(response)
+      return api_errors if api_errors.present?
+
+      response.body
+    end
+
+    sig do
+      params(
+        name: String,
+        description: T.nilable(String),
+        is_income: T::Boolean,
+        exclude_from_budget: T::Boolean,
+        exclude_from_totals: T::Boolean,
+        category_ids: T::Array[Integer],
+        new_categories: T::Array[String],
+      ).returns(T.any(T::Hash[Symbol, Integer], LunchMoney::Errors))
+    end
+    def create_category_group(name:, description: nil, is_income: false, exclude_from_budget: false,
+      exclude_from_totals: false, category_ids: [], new_categories: [])
+
+      params = {
+        name:,
+        description:,
+        is_income:,
+        exclude_from_budget:,
+        exclude_from_totals:,
+        category_ids:,
+        new_categories:,
+      }
+
+      response = post("categories/group", params)
+
+      api_errors = errors(response)
+      return api_errors if api_errors.present?
+
+      response.body
+    end
+
+    sig do
+      params(
+        category_id: Integer,
+        name: T.nilable(String),
+        description: T.nilable(String),
+        is_income: T.nilable(T::Boolean),
+        exclude_from_budget: T.nilable(T::Boolean),
+        exclude_from_totals: T.nilable(T::Boolean),
+        archived: T.nilable(T::Boolean),
+        group_id: T.nilable(Integer),
+      ).returns(T.any(T::Boolean, LunchMoney::Errors))
+    end
+    def update_category(category_id, name: nil, description: nil, is_income: nil, exclude_from_budget: nil,
+      exclude_from_totals: nil, archived: nil, group_id: nil)
+
+      params = clean_params({
+        name:,
+        description:,
+        is_income:,
+        exclude_from_budget:,
+        exclude_from_totals:,
+        archived:,
+        group_id:,
+      })
+      response = put("categories/#{category_id}", params)
+
+      api_errors = errors(response)
+      return api_errors if api_errors.present?
+
+      response.body
+    end
+
+    sig do
+      params(
+        group_id: Integer,
+        category_ids: T::Array[Integer],
+        new_categories: T::Array[String],
+      ).returns(T.any(LunchMoney::Category, LunchMoney::Errors))
+    end
+    def add_to_category_group(group_id, category_ids: [], new_categories: [])
+      params = {
+        category_ids:,
+        new_categories:,
+      }
+
+      response = post("categories/group/#{group_id}/add", params)
+
+      api_errors = errors(response)
+      return api_errors if api_errors.present?
+
+      LunchMoney::Category.new(**response.body)
+    end
+
+    sig { params(category_id: Integer).returns(T.any(T::Boolean, LunchMoney::Errors)) }
+    def delete_category(category_id)
+      response = delete("categories/#{category_id}")
+
+      api_errors = errors(response)
+      return api_errors if api_errors.present?
+
+      response.body
+    end
+
+    sig { params(category_id: Integer).returns(T.any(T::Boolean, LunchMoney::Errors)) }
+    def force_delete_category(category_id)
+      response = delete("categories/#{category_id}/force")
+
+      api_errors = errors(response)
+      return api_errors if api_errors.present?
+
+      response.body
+    end
+
+    private
+
+    sig { params(format: T.nilable(T.any(String, Symbol))).returns(T.nilable(T::Hash[Symbol, String])) }
+    def categories_params(format:)
+      return unless format
+
+      raise(InvalidQueryParameter, "format must be either flattened or nested") if VALID_FORMATS.exclude?(format.to_s)
+
+      { format: format.to_s }
+    end
+  end
+end

data/lib/lunchmoney/configuration.rb

@@ -0,0 +1,26 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LunchMoney
+  # Holds global configuration options for this gem
+  # @example api_key
+  #   LunchMoney::Configuration.api_key
+  #   => "your_api_key"
+  #
+  # @example validate_object_attributes
+  #   LunchMoney::Configuration.validate_object_attributes
+  #   => true
+  class Configuration
+    sig { returns(T.nilable(String)) }
+    attr_accessor :api_key
+
+    sig { returns(T::Boolean) }
+    attr_accessor :validate_object_attributes
+
+    sig { void }
+    def initialize
+      @api_key = ENV.fetch("LUNCHMONEY_TOKEN", nil)
+      @validate_object_attributes = T.let(true, T::Boolean)
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LunchMoney
+  # 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