lunchmoney 0.10.0

data/lib/lunchmoney/transactions/transaction/transaction_base.rb

@@ -0,0 +1,52 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LunchMoney
+  # Slimmed down version of https://lunchmoney.dev/#transaction-object used as a base for other transaction objects
+  class TransactionBase < LunchMoney::DataObject
+    sig { returns(Integer) }
+    attr_accessor :id
+
+    sig { returns(Number) }
+    attr_accessor :to_base
+
+    sig { returns(T.nilable(Integer)) }
+    attr_accessor :asset_id, :plaid_account_id
+
+    sig { returns(String) }
+    attr_accessor :date,
+      :amount,
+      :currency,
+      :payee
+
+    sig { returns(T.nilable(String)) }
+    attr_accessor :notes
+
+    sig do
+      params(
+        id: Integer,
+        date: String,
+        amount: String,
+        currency: String,
+        to_base: Number,
+        payee: 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:, notes: nil, asset_id: nil,
+      plaid_account_id: nil)
+      super()
+      @id = id
+      @date = date
+      @amount = amount
+      @currency = currency
+      @to_base = to_base
+      @payee = payee
+      @notes = notes
+      @asset_id = asset_id
+      @plaid_account_id = plaid_account_id
+    end
+  end
+end

data/lib/lunchmoney/transactions/transaction/transaction_modification_base.rb

@@ -0,0 +1,30 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LunchMoney
+  # Base object used for transaction objects that are used to update
+  # transactions https://lunchmoney.dev/#update-transaction
+  class TransactionModificationBase < LunchMoney::DataObject
+    sig { returns(T.nilable(String)) }
+    attr_accessor :payee, :date, :notes
+
+    sig { returns(T.nilable(Integer)) }
+    attr_accessor :category_id
+
+    sig do
+      params(
+        payee: T.nilable(String),
+        date: T.nilable(String),
+        category_id: T.nilable(Integer),
+        notes: T.nilable(String),
+      ).void
+    end
+    def initialize(payee: nil, date: nil, category_id: nil, notes: nil)
+      super()
+      @payee = payee
+      @date = date
+      @category_id = category_id
+      @notes = notes
+    end
+  end
+end

data/lib/lunchmoney/transactions/transaction/update_transaction.rb

@@ -0,0 +1,43 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LunchMoney
+  # object used when updating a transaction https://lunchmoney.dev/#update-transaction
+  class UpdateTransaction < TransactionModificationBase
+    sig { returns(T.nilable(String)) }
+    attr_accessor :amount, :currency, :status, :external_id
+
+    sig { returns(T.nilable(Integer)) }
+    attr_accessor :asset_id, :recurring_id
+
+    sig { returns(T.nilable(T::Array[T.any(String, Integer)])) }
+    attr_accessor :tags
+
+    sig do
+      params(
+        tags: T.nilable(T::Array[T.any(String, Integer)]),
+        category_id: T.nilable(Integer),
+        payee: T.nilable(String),
+        amount: T.nilable(String),
+        currency: T.nilable(String),
+        asset_id: T.nilable(Integer),
+        recurring_id: T.nilable(Integer),
+        notes: T.nilable(String),
+        status: T.nilable(String),
+        external_id: T.nilable(String),
+        date: T.nilable(String),
+      ).void
+    end
+    def initialize(tags: nil, category_id: nil, payee: nil, amount: nil, currency: nil, asset_id: nil,
+      recurring_id: nil, notes: nil, status: nil, external_id: nil, date: nil)
+      super(payee:, date:, category_id:, notes:)
+      @amount = amount
+      @tags = tags
+      @currency = currency
+      @asset_id = asset_id
+      @recurring_id = recurring_id
+      @status = status
+      @external_id = external_id
+    end
+  end
+end

data/lib/lunchmoney/transactions/transaction_calls.rb

@@ -0,0 +1,218 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "transaction/transaction_base"
+require_relative "transaction/child_transaction"
+require_relative "transaction/transaction"
+require_relative "transaction/transaction_modification_base"
+require_relative "transaction/split"
+require_relative "transaction/update_transaction"
+
+module LunchMoney
+  # https://lunchmoney.dev/#transactions
+  class TransactionCalls < ApiCall
+    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::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::TagBase.new(**tag) }
+
+        transaction[:children]&.map! { |child_transaction| LunchMoney::ChildTransaction.new(**child_transaction) }
+
+        LunchMoney::Transaction.new(**transaction)
+      end
+    end
+
+    sig do
+      params(
+        transaction_id: Integer,
+        debit_as_negative: T.nilable(T::Boolean),
+      ).returns(T.any(LunchMoney::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::Transaction.new(**response.body)
+    end
+
+    sig do
+      params(
+        transactions: T::Array[LunchMoney::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::UpdateTransaction),
+        split: T.nilable(T::Array[LunchMoney::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::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::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

data/lib/lunchmoney/user/user.rb

@@ -0,0 +1,36 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LunchMoney
+  # https://lunchmoney.dev/#user-object
+  class User < LunchMoney::DataObject
+    sig { returns(Integer) }
+    attr_accessor :user_id, :account_id
+
+    sig { returns(String) }
+    attr_accessor :user_name, :user_email, :budget_name
+
+    sig { returns(T.nilable(String)) }
+    attr_accessor :api_key_label
+
+    sig do
+      params(
+        user_id: Integer,
+        user_name: String,
+        user_email: String,
+        account_id: Integer,
+        budget_name: String,
+        api_key_label: T.nilable(String),
+      ).void
+    end
+    def initialize(user_id:, user_name:, user_email:, account_id:, budget_name:, api_key_label: nil)
+      super()
+      @user_id = user_id
+      @user_name = user_name
+      @user_email = user_email
+      @account_id = account_id
+      @budget_name = budget_name
+      @api_key_label = api_key_label
+    end
+  end
+end

data/lib/lunchmoney/user/user_calls.rb

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

data/lib/lunchmoney/validators.rb

@@ -0,0 +1,43 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "time"
+
+module LunchMoney
+  # module containing reusable methods for validating data objects
+  module Validators
+    include Kernel
+
+    sig { params(value: String, valid_values: T::Array[String]).returns(String) }
+    def validate_one_of!(value, valid_values)
+      return value unless LunchMoney.validate_object_attributes?
+
+      if valid_values.exclude?(value)
+        raise(InvalidObjectAttribute, "#{value} is invalid, must be one of #{valid_values.join(", ")}")
+      end
+
+      value
+    end
+
+    sig { params(value: String).returns(String) }
+    def validate_iso8601!(value)
+      return value unless LunchMoney.validate_object_attributes?
+
+      raise(InvalidObjectAttribute, "#{value} is not a valid ISO 8601 string") unless valid_iso8601_string?(value)
+
+      value
+    end
+
+    private
+
+    sig { params(time_string: String).returns(T::Boolean) }
+    def valid_iso8601_string?(time_string)
+      Time.iso8601(time_string)
+      true
+    rescue ArgumentError => error
+      raise unless error.message.match?("invalid xmlschema format")
+
+      false
+    end
+  end
+end

data/lib/lunchmoney/version.rb

@@ -0,0 +1,7 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LunchMoney
+  # Current version of the gem
+  VERSION = "0.10.0"
+end

data/lib/lunchmoney.rb

@@ -0,0 +1,54 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/core_ext/module/delegation.rb"
+require "active_support/core_ext/object/blank.rb"
+require "faraday"
+require "sorbet-runtime"
+
+# Include T::Sig directly in the module class so that it doesn't need to be extended everywhere.
+class Module
+  include T::Sig
+end
+
+# Add type alias for when Integer and Float can both be used
+Number = T.type_alias { T.any(Integer, Float) }
+
+require_relative "lunchmoney/version"
+require_relative "lunchmoney/validators"
+require_relative "lunchmoney/api"
+
+module LunchMoney
+  # Lock used to avoid config conflicts
+  LOCK = T.let(Mutex.new, Mutex)
+
+  class << self
+    # @example Set your API key
+    #   LunchMoney.configure do |config|
+    #     config.api_key = "your_api_key"
+    #   end
+    #
+    # @example Turn off object validation
+    #   LunchMoney.configure do |config|
+    #     config.validate_object_attributes = false
+    #   end
+    sig do
+      params(block: T.proc.params(arg0: LunchMoney::Configuration).void).void
+    end
+    def configure(&block)
+      yield(configuration)
+    end
+
+    sig { returns(LunchMoney::Configuration) }
+    def configuration
+      @configuration = T.let(nil, T.nilable(LunchMoney::Configuration)) unless defined?(@configuration)
+      @configuration || LOCK.synchronize { @configuration = LunchMoney::Configuration.new }
+    end
+
+    sig { returns(T::Boolean) }
+    def validate_object_attributes?
+      configuration.validate_object_attributes
+    end
+  end
+end

data/lunchmoney.gemspec

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "lib/lunchmoney/version"
+
+Gem::Specification.new do |spec|
+  spec.name                   = "lunchmoney"
+  spec.version                = LunchMoney::VERSION
+  spec.author                 = "@halorrr"
+  spec.email                  = "halorrr@gmail.com"
+
+  spec.summary                = "LunchMoney API client library."
+  spec.homepage               = "https://github.com/halorrr/lunchmoney"
+  spec.required_ruby_version  = ">= 3.1"
+  spec.license = "MIT"
+
+  spec.metadata["allowed_push_host"]  = "https://rubygems.org"
+  spec.metadata["homepage_uri"]       = spec.homepage
+  spec.metadata["source_code_uri"]    = spec.homepage
+  spec.metadata["changelog_uri"]      = "#{spec.homepage}/releases"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    %x(git ls-files -z).split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency("activesupport", ">= 6.1")
+  spec.add_dependency("faraday", ">= 1.0.0")
+  spec.add_dependency("sorbet-runtime", ">= 0.5")
+end

data/sorbet/config

@@ -0,0 +1,5 @@
+--dir
+.
+--ignore=/vendor
+--ignore=/.toys
+--enable-experimental-requires-ancestor

data/sorbet/rbi/annotations/.gitattributes

@@ -0,0 +1 @@
+**/*.rbi linguist-vendored=true