lunchmoney 1.0.0 → 1.1.1

data/lib/lunchmoney/calls/assets.rb

@@ -0,0 +1,98 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../objects/asset"
+
+module LunchMoney
+  module Calls
+    # https://lunchmoney.dev/#assets
+    class Assets < LunchMoney::Calls::Base
+      sig { returns(T.any(T::Array[LunchMoney::Objects::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::Objects::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::Objects::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::Objects::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::Objects::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::Objects::Asset.new(**response.body)
+      end
+    end
+  end
+end

data/lib/lunchmoney/calls/base.rb

@@ -0,0 +1,118 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../errors"
+
+module LunchMoney
+  # Namespace for all API call classes. The methods on these classes should not typically be accessed directly.
+  # Instead they should be accessed through `LunchMoney::Api` instances, which will handle delegating the methods to
+  # the appropriate Calls class.
+  # @example
+  #   api = LunchMoney::Api.new
+  #   api.categories # This will be delegated to LunchMoney::Calls::Categories#categories
+  module Calls
+    # Base class for all API call types. Containing the base methods got HTTP call types like GET / POST / PUT / DELETE
+    # as well as the general error handler
+    class Base
+      # Base URL used for API calls
+      BASE_URL = "https://dev.lunchmoney.app/v1/"
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :api_key
+
+      sig { params(api_key: T.nilable(String)).void }
+      def initialize(api_key: nil)
+        @api_key = T.let((api_key || LunchMoney.configuration.api_key), T.nilable(String))
+      end
+
+      private
+
+      sig { params(endpoint: String, query_params: T.nilable(T::Hash[Symbol, T.untyped])).returns(Faraday::Response) }
+      def get(endpoint, query_params: nil)
+        connection = request(flat_params: true)
+
+        if query_params.present?
+          connection.get(BASE_URL + endpoint, query_params)
+        else
+          connection.get(BASE_URL + endpoint)
+        end
+      end
+
+      sig { params(endpoint: String, params: T.nilable(T::Hash[Symbol, T.untyped])).returns(Faraday::Response) }
+      def post(endpoint, params)
+        request(json_request: true).post(BASE_URL + endpoint, params)
+      end
+
+      sig { params(endpoint: String, body: T::Hash[Symbol, T.untyped]).returns(Faraday::Response) }
+      def put(endpoint, body)
+        request(json_request: true).put(BASE_URL + endpoint) do |req|
+          req.body = body
+        end
+      end
+
+      sig { params(endpoint: String, query_params: T.nilable(T::Hash[Symbol, T.untyped])).returns(Faraday::Response) }
+      def delete(endpoint, query_params: nil)
+        connection = request(flat_params: true)
+
+        if query_params.present?
+          connection.delete(BASE_URL + endpoint, query_params)
+        else
+          connection.delete(BASE_URL + endpoint)
+        end
+      end
+
+      sig { params(json_request: T::Boolean, flat_params: T::Boolean).returns(Faraday::Connection) }
+      def request(json_request: false, flat_params: false)
+        Faraday.new do |conn|
+          conn.request(:authorization, "Bearer", @api_key)
+          conn.request(:json) if json_request
+          # conn.options.params_encoder = Faraday::FlatParamsEncoder if flat_params
+          conn.response(:json, content_type: /json$/, parser_options: { symbolize_names: true })
+        end
+      end
+
+      sig { params(response: Faraday::Response).returns(LunchMoney::Errors) }
+      def errors(response)
+        body = response.body
+
+        return parse_errors(body) unless error_hash(body).nil?
+
+        LunchMoney::Errors.new
+      end
+
+      sig { params(body: T::Hash[Symbol, T.any(String, T::Array[String])]).returns(LunchMoney::Errors) }
+      def parse_errors(body)
+        errors = error_hash(body)
+        api_errors = LunchMoney::Errors.new
+        return api_errors if errors.blank?
+
+        case errors
+        when String
+          api_errors << errors
+        when Array
+          errors.each { |error| api_errors << error }
+        end
+
+        api_errors
+      end
+
+      sig { params(body: T.untyped).returns(T.untyped) }
+      def error_hash(body)
+        return unless body.is_a?(Hash)
+
+        if body[:error]
+          body[:error]
+        elsif body[:errors]
+          body[:errors]
+        elsif body[:name] == "Error"
+          body[:message]
+        end
+      end
+
+      sig { params(params: T::Hash[Symbol, T.untyped]).returns(T::Hash[Symbol, T.untyped]) }
+      def clean_params(params)
+        params.reject! { |_key, value| value.nil? }
+      end
+    end
+  end
+end

data/lib/lunchmoney/calls/budgets.rb

@@ -0,0 +1,84 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../objects/budget"
+
+module LunchMoney
+  module Calls
+    # https://lunchmoney.dev/#budget
+    class Budgets < LunchMoney::Calls::Base
+      sig do
+        params(
+          start_date: String,
+          end_date: String,
+          currency: T.nilable(String),
+        ).returns(T.any(T::Array[LunchMoney::Objects::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::Objects::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::Objects::Data.new(**budget[:config][config_key])
+            end
+          end
+
+          if budget[:recurring]
+            budget[:recurring][:list]&.map! { |recurring| LunchMoney::Objects::RecurringExpenseBase.new(**recurring) }
+          end
+
+          LunchMoney::Objects::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
+end

data/lib/lunchmoney/calls/categories.rb

@@ -0,0 +1,196 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../objects/category"
+
+module LunchMoney
+  module Calls
+    # https://lunchmoney.dev/#categories
+    class Categories < LunchMoney::Calls::Base
+      # 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::Objects::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::Objects::Category.new(**child_category) }
+
+          LunchMoney::Objects::Category.new(**category)
+        end
+      end
+
+      sig { params(category_id: Integer).returns(T.any(LunchMoney::Objects::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::Objects::ChildCategory.new(**child_category) }
+
+        LunchMoney::Objects::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::Objects::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::Objects::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
+end

data/lib/lunchmoney/calls/crypto.rb

@@ -0,0 +1,50 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../objects/crypto"
+
+module LunchMoney
+  module Calls
+    # https://lunchmoney.dev/#crypto
+    class Crypto < LunchMoney::Calls::Base
+      sig { returns(T.any(T::Array[LunchMoney::Objects::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::Objects::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::Objects::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::Objects::CryptoBase.new(**response.body)
+      end
+    end
+  end
+end

data/lib/lunchmoney/calls/plaid_accounts.rb

@@ -0,0 +1,40 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../objects/plaid_account"
+
+module LunchMoney
+  module Calls
+    # https://lunchmoney.dev/#plaid-accounts
+    class PlaidAccounts < LunchMoney::Calls::Base
+      sig { returns(T.any(T::Array[LunchMoney::Objects::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::Objects::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
+end

data/lib/lunchmoney/calls/recurring_expenses.rb

@@ -0,0 +1,29 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../objects/recurring_expense"
+
+module LunchMoney
+  module Calls
+    # https://lunchmoney.dev/#recurring-expenses
+    class RecurringExpenses < LunchMoney::Calls::Base
+      sig do
+        params(
+          start_date: T.nilable(String),
+          end_date: T.nilable(String),
+        ).returns(T.any(T::Array[LunchMoney::Objects::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::Objects::RecurringExpense.new(**recurring_expense)
+        end
+      end
+    end
+  end
+end

data/lib/lunchmoney/calls/tags.rb

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