lunchmoney 0.10.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c0eee6d8599ca3bcc3937bff5208db6a4502029ed711940ffbe90e807c4b0bd1
-  data.tar.gz: e8f7d58fbf604cf59c60111963c063273f04b7bab3e7d3ddf1e0684213cab1d2
+  metadata.gz: 6a7fc6df7ade58a32f0302f4faab00cf1f25ad4baa74960373a7d05870f55d47
+  data.tar.gz: 014e04789ba5f352ccd884f2420f0ba6fdb6fed38728977071f2c8ec43dedc24
 SHA512:
-  metadata.gz: a6a0af1c49bac3eccbaaa802dc7c4d9c59122083e69ae19efdeda3bf322e3f5c290b1f207d4805cc4b9fcff62ae317fb2249cd2340ce3186fef0b930b9132a20
-  data.tar.gz: 971503cc33d3bec22fc0e643141d85d49ba5a5295fc85f2f7e3d37f40216c57368f05e394293a86184f6052696c9aed1efc58104b177c5614194b8b3a970dcd5
+  metadata.gz: 181b9a3fe5d781b420e337c3504495374a47515b5cd50237d1eec4e9b0d3b13f7c6c8180a595cd11b09c4d02678df9f480c76f60fad933562235d6bcd022ac73
+  data.tar.gz: 7ac6dc11c6519049d4c2591bdb41e7fc0c471f7ace22ffc08f841d0c0d1ca5fc1995244baabbe8ce0b8157d7af812b37f3fe1cf581c80f84fcbccdf0710dd2cd

data/.github/workflows/publish_gem.yml

@@ -8,6 +8,7 @@ jobs:
   build:
     name: Build & Release Gem
     runs-on: ubuntu-latest
+    environment: rubygems
 
     steps:
       - uses: actions/checkout@v4

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    lunchmoney (0.10.0)
+    lunchmoney (1.1.0)
       activesupport (>= 6.1)
       faraday (>= 1.0.0)
       sorbet-runtime (>= 0.5)

data/README.md

@@ -1,10 +1,12 @@
 # lunchmoney
 
-This gem and readme are very much a work in progress. More to come!
+[![Gem Version](https://badge.fury.io/rb/lunchmoney.svg)](https://badge.fury.io/rb/lunchmoney)
+[![CI](https://github.com/halorrr/lunchmoney/actions/workflows/ci.yml/badge.svg)](https://github.com/halorrr/lunchmoney/actions/workflows/ci.yml)
+[![Yard Docs](https://github.com/halorrr/lunchmoney/actions/workflows/build_and_publish_yard_docs.yml/badge.svg)](https://github.com/halorrr/lunchmoney/actions/workflows/build_and_publish_yard_docs.yml)
 
-This gem is a library of the [LunchMoney API](https://lunchmoney.dev/) for the wonderful [LunchMoney](http://lunchmoney.app/) web app for personal finance & budgeting.
+This gem is a API client library of the [LunchMoney API](https://lunchmoney.dev/) for the wonderful [LunchMoney](http://lunchmoney.app/) web app for personal finance & budgeting.
 
-You can find the yard docs for this gem [here](https://halorrr.github.io/lunchmoney/)
+Documentation is still a work in process, but you can find the yard docs for this gem [here](https://halorrr.github.io/lunchmoney/) as well as some write ups of the basics below.
 
 ## Usage
 
@@ -36,13 +38,48 @@ LunchMoney::Api.new(api_key: "your_api_key")
 
 ### Using the API
 
-Create an instance of the api, then call the endpoint you need:
+It is intended that all calls typically go through a `LunchMoney::Api` instannce. This class delegates methods to their
+relvant classes behind the scenes. Create an instance of the api, then call the endpoint you need:
 
 ```Ruby
 api = LunchMoney::Api.new
 api.categories
 ```
 
+When the api returns an error a `LunchMoney::Errors` object will be returned. You can check the errors that occured via
+`.messages` on the instance. This will return an array of errors.
+
+```Ruby
+api = LunchMoney::Api.new
+response = api.categories
+
+response.class
+=> LunchMoney::Errors
+
+response.messages
+=> ["Some error returned by the API"]
+```
+
+The instance itself has been set up to act like an array, delegating a lot of common array getter methods directly to
+messages for you. This enables things like:
+
+```Ruby
+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"
+```
+
 ## Contributing to this repo
 
 Feel free to contribute and submit PRs to improve this gem

data/lib/lunchmoney/api.rb

@@ -4,21 +4,21 @@
 require_relative "exceptions"
 require_relative "configuration"
 
-require_relative "api_call"
-require_relative "data_object"
-require_relative "user/user_calls"
-require_relative "categories/category_calls"
-require_relative "tags/tag_calls"
-require_relative "transactions/transaction_calls"
-require_relative "recurring_expenses/recurring_expense_calls"
-require_relative "budget/budget_calls"
-require_relative "assets/asset_calls"
-require_relative "plaid_accounts/plaid_account_calls"
-require_relative "crypto/crypto_calls"
+require_relative "calls/base"
+require_relative "objects/object"
+require_relative "calls/users"
+require_relative "calls/categories"
+require_relative "calls/tags"
+require_relative "calls/transactions"
+require_relative "calls/recurring_expenses"
+require_relative "calls/budgets"
+require_relative "calls/assets"
+require_relative "calls/plaid_accounts"
+require_relative "calls/crypto"
 
 module LunchMoney
   # The main API class that a user should interface through the method of any individual call is delegated through here
-  # so that it is never necessary to go through things like `LunchMoney::UserCalls.new.user` instead you can directly
+  # so that it is never necessary to go through things like `LunchMoney::Calls::Users.new.user` instead you can directly
   # call the endpoint with LunchMoney::Api.new.user and it will be delegated to the correct call.
   class Api
     sig { returns(T.nilable(String)) }
@@ -31,10 +31,10 @@ module LunchMoney
 
     delegate :me, to: :user_calls
 
-    sig { returns(LunchMoney::ApiCall) }
+    sig { returns(LunchMoney::Calls::Base) }
     def user_calls
       with_valid_api_key do
-        @user_calls ||= T.let(LunchMoney::UserCalls.new(api_key:), T.nilable(LunchMoney::UserCalls))
+        @user_calls ||= T.let(LunchMoney::Calls::Users.new(api_key:), T.nilable(LunchMoney::Calls::Users))
       end
     end
 
@@ -48,19 +48,19 @@ module LunchMoney
       :force_delete_category,
       to: :category_calls
 
-    sig { returns(LunchMoney::ApiCall) }
+    sig { returns(LunchMoney::Calls::Base) }
     def category_calls
       with_valid_api_key do
-        @category_calls ||= T.let(LunchMoney::CategoryCalls.new(api_key:), T.nilable(LunchMoney::CategoryCalls))
+        @category_calls ||= T.let(LunchMoney::Calls::Categories.new(api_key:), T.nilable(LunchMoney::Calls::Categories))
       end
     end
 
     delegate :tags, to: :tag_calls
 
-    sig { returns(LunchMoney::ApiCall) }
+    sig { returns(LunchMoney::Calls::Base) }
     def tag_calls
       with_valid_api_key do
-        @tag_calls ||= T.let(LunchMoney::TagCalls.new(api_key:), T.nilable(LunchMoney::TagCalls))
+        @tag_calls ||= T.let(LunchMoney::Calls::Tags.new(api_key:), T.nilable(LunchMoney::Calls::Tags))
       end
     end
 
@@ -74,70 +74,70 @@ module LunchMoney
       :delete_transaction_group,
       to: :transaction_calls
 
-    sig { returns(LunchMoney::ApiCall) }
+    sig { returns(LunchMoney::Calls::Base) }
     def transaction_calls
       with_valid_api_key do
         @transaction_calls ||= T.let(
-          LunchMoney::TransactionCalls.new(api_key:),
-          T.nilable(LunchMoney::TransactionCalls),
+          LunchMoney::Calls::Transactions.new(api_key:),
+          T.nilable(LunchMoney::Calls::Transactions),
         )
       end
     end
 
     delegate :recurring_expenses, to: :recurring_expense_calls
 
-    sig { returns(LunchMoney::ApiCall) }
+    sig { returns(LunchMoney::Calls::Base) }
     def recurring_expense_calls
       with_valid_api_key do
         @recurring_expense_calls ||= T.let(
-          LunchMoney::RecurringExpenseCalls.new(api_key:),
-          T.nilable(LunchMoney::RecurringExpenseCalls),
+          LunchMoney::Calls::RecurringExpenses.new(api_key:),
+          T.nilable(LunchMoney::Calls::RecurringExpenses),
         )
       end
     end
 
     delegate :budgets, :upsert_budget, :remove_budget, to: :budget_calls
 
-    sig { returns(LunchMoney::ApiCall) }
+    sig { returns(LunchMoney::Calls::Base) }
     def budget_calls
       with_valid_api_key do
-        @budget_calls ||= T.let(LunchMoney::BudgetCalls.new(api_key:), T.nilable(LunchMoney::BudgetCalls))
+        @budget_calls ||= T.let(LunchMoney::Calls::Budgets.new(api_key:), T.nilable(LunchMoney::Calls::Budgets))
       end
     end
 
     delegate :assets, :create_asset, :update_asset, to: :asset_calls
 
-    sig { returns(LunchMoney::ApiCall) }
+    sig { returns(LunchMoney::Calls::Base) }
     def asset_calls
       with_valid_api_key do
-        @asset_calls ||= T.let(LunchMoney::AssetCalls.new(api_key:), T.nilable(LunchMoney::AssetCalls))
+        @asset_calls ||= T.let(LunchMoney::Calls::Assets.new(api_key:), T.nilable(LunchMoney::Calls::Assets))
       end
     end
 
     delegate :plaid_accounts, :plaid_accounts_fetch, to: :plaid_account_calls
 
-    sig { returns(LunchMoney::ApiCall) }
+    sig { returns(LunchMoney::Calls::Base) }
     def plaid_account_calls
       with_valid_api_key do
         @plaid_account_calls ||= T.let(
-          LunchMoney::PlaidAccountCalls.new(api_key:),
-          T.nilable(LunchMoney::PlaidAccountCalls),
+          LunchMoney::Calls::PlaidAccounts.new(api_key:),
+          T.nilable(LunchMoney::Calls::PlaidAccounts),
         )
       end
     end
 
     delegate :crypto, :update_crypto, to: :crypto_calls
 
-    sig { returns(LunchMoney::ApiCall) }
+    sig { returns(LunchMoney::Calls::Base) }
     def crypto_calls
       with_valid_api_key do
-        @crypto_calls ||= T.let(LunchMoney::CryptoCalls.new(api_key:), T.nilable(LunchMoney::CryptoCalls))
+        @crypto_calls ||= T.let(LunchMoney::Calls::Crypto.new(api_key:), T.nilable(LunchMoney::Calls::Crypto))
       end
     end
 
     private
 
-    sig { params(block: T.proc.returns(LunchMoney::ApiCall)).returns(LunchMoney::ApiCall) }
+    sig { params(block: T.proc.returns(LunchMoney::Calls::Base)).returns(LunchMoney::Calls::Base) }
     def with_valid_api_key(&block)
       raise(InvalidApiKey, "API key is missing or invalid") if api_key.blank?
 

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,112 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../errors"
+
+module LunchMoney
+  # Namespace for API call classes
+  module Calls
+    # Base class for all API call types
+    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