lunchmoney 0.10.0

data/LICENSE

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2021 halorrr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,57 @@
+# lunchmoney
+
+This gem and readme are very much a work in progress. More to come!
+
+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.
+
+You can find the yard docs for this gem [here](https://halorrr.github.io/lunchmoney/)
+
+## Usage
+
+### Installation
+
+Add this line to your application's `Gemfile`:
+
+```Ruby
+gem "lunchmoney"
+```
+
+### Set your lunchmoney token
+
+There are a few ways you can set your API token. You can set it manually using a configure block:
+
+```Ruby
+LunchMoney.configure do |config|
+  config.api_key = "your_api_key"
+end
+```
+
+The config will also _automatically_ pull in the token if set via environment variable named `LUNCHMONEY_TOKEN`
+
+You can also override the config and set your LunchMoney token for a specific API instance via kwarg:
+
+```Ruby
+LunchMoney::Api.new(api_key: "your_api_key")
+```
+
+### Using the API
+
+Create an instance of the api, then call the endpoint you need:
+
+```Ruby
+api = LunchMoney::Api.new
+api.categories
+```
+
+## Contributing to this repo
+
+Feel free to contribute and submit PRs to improve this gem
+
+## Releasing a new gem version
+
+1. Bump the `VERSION` constant in `lib/lunchmoney/version.rb`
+2. Run `bundle install`
+3. Commit and push up the change in a PR
+4. Merge the PR
+5. Create a new tag and release with the name version as v0.0.0
+6. A Github action will kick off and publish the new gem version

data/bin/console

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "dotenv/load"
+require "lunchmoney"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/rubocop

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rubocop' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?("This file was generated by Bundler")
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rubocop", "rubocop")

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/bin/spoom

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'spoom' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?("This file was generated by Bundler")
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("spoom", "spoom")

data/bin/srb

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'srb' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?("This file was generated by Bundler")
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("sorbet", "srb")

data/bin/tapioca

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'tapioca' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?("This file was generated by Bundler")
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("tapioca", "tapioca")

data/bin/toys

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'toys' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?("This file was generated by Bundler")
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("toys", "toys")

data/bin/yard

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'yard' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?("This file was generated by Bundler")
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("yard", "yard")

data/lib/lunchmoney/api.rb

@@ -0,0 +1,147 @@
+# typed: strict
+# frozen_string_literal: true
+
+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"
+
+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
+  # call the endpoint with LunchMoney::Api.new.user and it will be delegated to the correct call.
+  class Api
+    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
+
+    delegate :me, to: :user_calls
+
+    sig { returns(LunchMoney::ApiCall) }
+    def user_calls
+      with_valid_api_key do
+        @user_calls ||= T.let(LunchMoney::UserCalls.new(api_key:), T.nilable(LunchMoney::UserCalls))
+      end
+    end
+
+    delegate :categories,
+      :category,
+      :create_category,
+      :create_category_group,
+      :update_category,
+      :add_to_category_group,
+      :delete_category,
+      :force_delete_category,
+      to: :category_calls
+
+    sig { returns(LunchMoney::ApiCall) }
+    def category_calls
+      with_valid_api_key do
+        @category_calls ||= T.let(LunchMoney::CategoryCalls.new(api_key:), T.nilable(LunchMoney::CategoryCalls))
+      end
+    end
+
+    delegate :tags, to: :tag_calls
+
+    sig { returns(LunchMoney::ApiCall) }
+    def tag_calls
+      with_valid_api_key do
+        @tag_calls ||= T.let(LunchMoney::TagCalls.new(api_key:), T.nilable(LunchMoney::TagCalls))
+      end
+    end
+
+    delegate :transactions,
+      :transaction,
+      :insert_transactions,
+      :update_transaction,
+      :unsplit_transaction,
+      :transaction_group,
+      :create_transaction_group,
+      :delete_transaction_group,
+      to: :transaction_calls
+
+    sig { returns(LunchMoney::ApiCall) }
+    def transaction_calls
+      with_valid_api_key do
+        @transaction_calls ||= T.let(
+          LunchMoney::TransactionCalls.new(api_key:),
+          T.nilable(LunchMoney::TransactionCalls),
+        )
+      end
+    end
+
+    delegate :recurring_expenses, to: :recurring_expense_calls
+
+    sig { returns(LunchMoney::ApiCall) }
+    def recurring_expense_calls
+      with_valid_api_key do
+        @recurring_expense_calls ||= T.let(
+          LunchMoney::RecurringExpenseCalls.new(api_key:),
+          T.nilable(LunchMoney::RecurringExpenseCalls),
+        )
+      end
+    end
+
+    delegate :budgets, :upsert_budget, :remove_budget, to: :budget_calls
+
+    sig { returns(LunchMoney::ApiCall) }
+    def budget_calls
+      with_valid_api_key do
+        @budget_calls ||= T.let(LunchMoney::BudgetCalls.new(api_key:), T.nilable(LunchMoney::BudgetCalls))
+      end
+    end
+
+    delegate :assets, :create_asset, :update_asset, to: :asset_calls
+
+    sig { returns(LunchMoney::ApiCall) }
+    def asset_calls
+      with_valid_api_key do
+        @asset_calls ||= T.let(LunchMoney::AssetCalls.new(api_key:), T.nilable(LunchMoney::AssetCalls))
+      end
+    end
+
+    delegate :plaid_accounts, :plaid_accounts_fetch, to: :plaid_account_calls
+
+    sig { returns(LunchMoney::ApiCall) }
+    def plaid_account_calls
+      with_valid_api_key do
+        @plaid_account_calls ||= T.let(
+          LunchMoney::PlaidAccountCalls.new(api_key:),
+          T.nilable(LunchMoney::PlaidAccountCalls),
+        )
+      end
+    end
+
+    delegate :crypto, :update_crypto, to: :crypto_calls
+
+    sig { returns(LunchMoney::ApiCall) }
+    def crypto_calls
+      with_valid_api_key do
+        @crypto_calls ||= T.let(LunchMoney::CryptoCalls.new(api_key:), T.nilable(LunchMoney::CryptoCalls))
+      end
+    end
+
+    private
+
+    sig { params(block: T.proc.returns(LunchMoney::ApiCall)).returns(LunchMoney::ApiCall) }
+    def with_valid_api_key(&block)
+      raise(InvalidApiKey, "API key is missing or invalid") if api_key.blank?
+
+      yield
+    end
+  end
+end

data/lib/lunchmoney/api_call.rb

@@ -0,0 +1,109 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module LunchMoney
+  # Base class for all API call types
+  class ApiCall
+    # 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

data/lib/lunchmoney/assets/asset.rb

@@ -0,0 +1,89 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LunchMoney
+  # https://lunchmoney.dev/#assets-object
+  class Asset < LunchMoney::DataObject
+    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",
+      ],
+      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