diff --git a/.github/workflows/build_and_public_yard_docs.yml b/.github/workflows/build_and_public_yard_docs.yml new file mode 100644 index 0000000..4d3fd34 --- /dev/null +++ b/.github/workflows/build_and_public_yard_docs.yml @@ -0,0 +1,47 @@ +name: Build and Publish Yard Docs + +on: + push: + branches: [ main ] + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: "pages" + cancel-in-progress: true + +jobs: + build: + name: Build and Publish Yard Docs + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + + - name: Set up Ruby + uses: ruby/setup-ruby@v1.165.1 + with: + ruby-version: 3.3.0 + bundler-cache: true + + - name: Install YARD + run: gem install yard + + - name: Generate docs + run: yard docs + + - name: Setup Github Pages + uses: actions/configure-pages@v4 + + - name: Upload Artifact + uses: actions/upload-pages-artifact@v3 + with: + path: "doc" + + - name: Publish to Github Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.yardopts b/.yardopts new file mode 100644 index 0000000..d12d48f --- /dev/null +++ b/.yardopts @@ -0,0 +1,2 @@ +--plugin yard-sorbet +--markup markdown diff --git a/Gemfile b/Gemfile index 982f257..034e5cd 100644 --- a/Gemfile +++ b/Gemfile @@ -18,3 +18,5 @@ gem "sorbet-static-and-runtime", require: false gem "spoom", require: false gem "tapioca", require: false gem "dotenv" +gem "yard", require: false +gem "yard-sorbet", require: false diff --git a/Gemfile.lock b/Gemfile.lock index 0e0cd81..f46b74d 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -148,6 +148,8 @@ DEPENDENCIES spoom tapioca toys + yard + yard-sorbet BUNDLED WITH 2.5.3 diff --git a/bin/yard b/bin/yard new file mode 100755 index 0000000..ea9daf5 --- /dev/null +++ b/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") diff --git a/lib/lunchmoney.rb b/lib/lunchmoney.rb index b04aa72..f1d76a7 100644 --- a/lib/lunchmoney.rb +++ b/lib/lunchmoney.rb @@ -8,16 +8,28 @@ require "sorbet-runtime" # Include T::Sig directly in the module class so that it doesn't need to be extended everywhere. -Module.include(T::Sig) +class Module + include T::Sig +end 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 diff --git a/lib/lunchmoney/api.rb b/lib/lunchmoney/api.rb index a168782..6338c8a 100644 --- a/lib/lunchmoney/api.rb +++ b/lib/lunchmoney/api.rb @@ -17,6 +17,9 @@ 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 diff --git a/lib/lunchmoney/api_call.rb b/lib/lunchmoney/api_call.rb index f00fb65..6146ed4 100644 --- a/lib/lunchmoney/api_call.rb +++ b/lib/lunchmoney/api_call.rb @@ -4,7 +4,9 @@ require_relative "error" 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)) } diff --git a/lib/lunchmoney/assets/asset.rb b/lib/lunchmoney/assets/asset.rb index 66383c6..b955725 100644 --- a/lib/lunchmoney/assets/asset.rb +++ b/lib/lunchmoney/assets/asset.rb @@ -2,6 +2,7 @@ # frozen_string_literal: true module LunchMoney + # https://lunchmoney.dev/#assets-object class Asset < LunchMoney::DataObject # API object reference documentation: https://lunchmoney.dev/#assets-object @@ -25,6 +26,7 @@ class Asset < LunchMoney::DataObject sig { returns(T::Boolean) } attr_accessor :exclude_transactions + # Valid asset type names VALID_TYPE_NAMES = T.let( [ "cash", @@ -41,6 +43,7 @@ class Asset < LunchMoney::DataObject T::Array[String], ) + # Valid asset subtype names VALID_SUBTYPE_NAMES = T.let( [ "retirement", diff --git a/lib/lunchmoney/assets/asset_calls.rb b/lib/lunchmoney/assets/asset_calls.rb index 859d721..a198bd8 100644 --- a/lib/lunchmoney/assets/asset_calls.rb +++ b/lib/lunchmoney/assets/asset_calls.rb @@ -4,6 +4,7 @@ require_relative "asset" module LunchMoney + # https://lunchmoney.dev/#assets class AssetCalls < ApiCall sig { returns(T.any(T::Array[LunchMoney::Asset], LunchMoney::Errors)) } def assets diff --git a/lib/lunchmoney/budget/budget.rb b/lib/lunchmoney/budget/budget.rb index 21e18ae..a8075c2 100644 --- a/lib/lunchmoney/budget/budget.rb +++ b/lib/lunchmoney/budget/budget.rb @@ -5,6 +5,7 @@ require_relative "config" module LunchMoney + # https://lunchmoney.dev/#budget-object class Budget < LunchMoney::DataObject # API object reference documentation: https://lunchmoney.dev/#budget-object diff --git a/lib/lunchmoney/budget/budget_calls.rb b/lib/lunchmoney/budget/budget_calls.rb index b54e329..c118b87 100644 --- a/lib/lunchmoney/budget/budget_calls.rb +++ b/lib/lunchmoney/budget/budget_calls.rb @@ -4,6 +4,7 @@ require_relative "budget" module LunchMoney + # https://lunchmoney.dev/#budget class BudgetCalls < ApiCall sig do params( diff --git a/lib/lunchmoney/budget/config.rb b/lib/lunchmoney/budget/config.rb index 396723e..3bdbd5c 100644 --- a/lib/lunchmoney/budget/config.rb +++ b/lib/lunchmoney/budget/config.rb @@ -2,6 +2,7 @@ # frozen_string_literal: true module LunchMoney + # https://lunchmoney.dev/#config-object class Config < LunchMoney::DataObject # API object reference documentation: https://lunchmoney.dev/#config-object diff --git a/lib/lunchmoney/budget/data.rb b/lib/lunchmoney/budget/data.rb index d585769..5973b71 100644 --- a/lib/lunchmoney/budget/data.rb +++ b/lib/lunchmoney/budget/data.rb @@ -2,6 +2,7 @@ # frozen_string_literal: true module LunchMoney + # https://lunchmoney.dev/#data-object class Data < LunchMoney::DataObject # API object reference documentation: https://lunchmoney.dev/#data-object diff --git a/lib/lunchmoney/categories/category.rb b/lib/lunchmoney/categories/category.rb index c67aa01..7a86ea5 100644 --- a/lib/lunchmoney/categories/category.rb +++ b/lib/lunchmoney/categories/category.rb @@ -2,6 +2,7 @@ # frozen_string_literal: true module LunchMoney + # https://lunchmoney.dev/#categories-object class Category < LunchMoney::DataObject sig { returns(Integer) } attr_accessor :id diff --git a/lib/lunchmoney/categories/category_calls.rb b/lib/lunchmoney/categories/category_calls.rb index 754ad81..4e31d9c 100644 --- a/lib/lunchmoney/categories/category_calls.rb +++ b/lib/lunchmoney/categories/category_calls.rb @@ -4,7 +4,9 @@ require_relative "category" module LunchMoney + # https://lunchmoney.dev/#categories class CategoryCalls < ApiCall + # Valid query parameter formets for categories VALID_FORMATS = T.let( [ "flattened", diff --git a/lib/lunchmoney/configuration.rb b/lib/lunchmoney/configuration.rb index 771111d..01f85f8 100644 --- a/lib/lunchmoney/configuration.rb +++ b/lib/lunchmoney/configuration.rb @@ -2,6 +2,14 @@ # 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 diff --git a/lib/lunchmoney/crypto/crypto.rb b/lib/lunchmoney/crypto/crypto.rb index 068df68..a600a6f 100644 --- a/lib/lunchmoney/crypto/crypto.rb +++ b/lib/lunchmoney/crypto/crypto.rb @@ -2,6 +2,7 @@ # frozen_string_literal: true module LunchMoney + # https://lunchmoney.dev/#crypto-object class Crypto < LunchMoney::DataObject sig { returns(T.nilable(Integer)) } attr_accessor :id, :zabo_account_id diff --git a/lib/lunchmoney/crypto/crypto_calls.rb b/lib/lunchmoney/crypto/crypto_calls.rb index 750289b..152e370 100644 --- a/lib/lunchmoney/crypto/crypto_calls.rb +++ b/lib/lunchmoney/crypto/crypto_calls.rb @@ -4,6 +4,7 @@ require_relative "crypto" module LunchMoney + # https://lunchmoney.dev/#crypto class CryptoCalls < ApiCall sig { returns(T.any(T::Array[LunchMoney::Crypto], LunchMoney::Errors)) } def crypto diff --git a/lib/lunchmoney/data_object.rb b/lib/lunchmoney/data_object.rb index fab51b5..7fc8c81 100644 --- a/lib/lunchmoney/data_object.rb +++ b/lib/lunchmoney/data_object.rb @@ -2,6 +2,7 @@ # frozen_string_literal: true module LunchMoney + # Base data object for the objects returned and used when calling the LunchMoney API class DataObject sig { params(symbolize_keys: T::Boolean).returns(T::Hash[String, T.untyped]) } def serialize(symbolize_keys: false) diff --git a/lib/lunchmoney/error.rb b/lib/lunchmoney/error.rb index 181dc99..6724624 100644 --- a/lib/lunchmoney/error.rb +++ b/lib/lunchmoney/error.rb @@ -2,6 +2,7 @@ # frozen_string_literal: true module LunchMoney + # This class is used to represent errors returned directly from the LunchMoney API class Error sig { returns(String) } attr_reader :message @@ -13,4 +14,5 @@ def initialize(message:) end end +# A type alias for an array of LunchMoney::Error LunchMoney::Errors = T.type_alias { T::Array[LunchMoney::Error] } diff --git a/lib/lunchmoney/exceptions.rb b/lib/lunchmoney/exceptions.rb index 2b9b7ec..621798d 100644 --- a/lib/lunchmoney/exceptions.rb +++ b/lib/lunchmoney/exceptions.rb @@ -2,11 +2,15 @@ # frozen_string_literal: true module LunchMoney + # Base exception class for exceptions raised by this gem class Exception < StandardError; end + # Exception raised when an API Key appears to be invalid class InvalidApiKey < Exception; end + # Exception raised when an object attribute is invalid class InvalidObjectAttribute < Exception; end + # Exception raised when a query parameter is invalid class InvalidQueryParameter < Exception; end end diff --git a/lib/lunchmoney/plaid_accounts/plaid_account.rb b/lib/lunchmoney/plaid_accounts/plaid_account.rb index b3e21b5..1eb8e3c 100644 --- a/lib/lunchmoney/plaid_accounts/plaid_account.rb +++ b/lib/lunchmoney/plaid_accounts/plaid_account.rb @@ -2,6 +2,7 @@ # frozen_string_literal: true module LunchMoney + # https://lunchmoney.dev/#plaid-accounts-object class PlaidAccount < LunchMoney::DataObject sig { returns(Integer) } attr_accessor :id diff --git a/lib/lunchmoney/plaid_accounts/plaid_account_calls.rb b/lib/lunchmoney/plaid_accounts/plaid_account_calls.rb index 4e55cad..8f845d3 100644 --- a/lib/lunchmoney/plaid_accounts/plaid_account_calls.rb +++ b/lib/lunchmoney/plaid_accounts/plaid_account_calls.rb @@ -4,6 +4,7 @@ require_relative "plaid_account" module LunchMoney + # https://lunchmoney.dev/#plaid-accounts class PlaidAccountCalls < ApiCall sig { returns(T.any(T::Array[LunchMoney::PlaidAccount], LunchMoney::Errors)) } def plaid_accounts diff --git a/lib/lunchmoney/recurring_expenses/recurring_expense.rb b/lib/lunchmoney/recurring_expenses/recurring_expense.rb index 1a2875e..aa56d4b 100644 --- a/lib/lunchmoney/recurring_expenses/recurring_expense.rb +++ b/lib/lunchmoney/recurring_expenses/recurring_expense.rb @@ -2,6 +2,7 @@ # frozen_string_literal: true module LunchMoney + # https://lunchmoney.dev/#recurring-expenses-object class RecurringExpense < LunchMoney::DataObject sig { returns(Integer) } attr_accessor :id, :amount diff --git a/lib/lunchmoney/recurring_expenses/recurring_expense_calls.rb b/lib/lunchmoney/recurring_expenses/recurring_expense_calls.rb index 45752d9..8835ecf 100644 --- a/lib/lunchmoney/recurring_expenses/recurring_expense_calls.rb +++ b/lib/lunchmoney/recurring_expenses/recurring_expense_calls.rb @@ -4,6 +4,7 @@ require_relative "recurring_expense" module LunchMoney + # https://lunchmoney.dev/#recurring-expenses class RecurringExpenseCalls < ApiCall sig do params( diff --git a/lib/lunchmoney/tags/tag.rb b/lib/lunchmoney/tags/tag.rb index 70bc969..15ef4b9 100644 --- a/lib/lunchmoney/tags/tag.rb +++ b/lib/lunchmoney/tags/tag.rb @@ -2,6 +2,7 @@ # frozen_string_literal: true module LunchMoney + # https://lunchmoney.dev/#tags-object class Tag < LunchMoney::DataObject sig { returns(Integer) } attr_accessor :id diff --git a/lib/lunchmoney/tags/tag_calls.rb b/lib/lunchmoney/tags/tag_calls.rb index df127ec..37110ac 100644 --- a/lib/lunchmoney/tags/tag_calls.rb +++ b/lib/lunchmoney/tags/tag_calls.rb @@ -4,6 +4,7 @@ require_relative "tag" module LunchMoney + # https://lunchmoney.dev/#tags class TagCalls < ApiCall sig { returns(T.any(T::Array[LunchMoney::Tag], LunchMoney::Errors)) } def all_tags diff --git a/lib/lunchmoney/transactions/split.rb b/lib/lunchmoney/transactions/split.rb index 036493b..bb7d107 100644 --- a/lib/lunchmoney/transactions/split.rb +++ b/lib/lunchmoney/transactions/split.rb @@ -2,6 +2,7 @@ # frozen_string_literal: true module LunchMoney + # Object used to split a transaction when updating https://lunchmoney.dev/#update-transaction class Split < LunchMoney::DataObject sig { returns(T.nilable(String)) } attr_accessor :payee, :date, :notes diff --git a/lib/lunchmoney/transactions/transaction.rb b/lib/lunchmoney/transactions/transaction.rb index 341be00..3d1adb6 100644 --- a/lib/lunchmoney/transactions/transaction.rb +++ b/lib/lunchmoney/transactions/transaction.rb @@ -2,6 +2,7 @@ # frozen_string_literal: true module LunchMoney + # https://lunchmoney.dev/#transaction-object class Transaction < LunchMoney::DataObject sig { returns(T.nilable(Integer)) } attr_accessor :id, :to_base, :category_id, :recurring_id, :asset_id, :plaid_account_id, :parent_id, :group_id diff --git a/lib/lunchmoney/transactions/transaction_calls.rb b/lib/lunchmoney/transactions/transaction_calls.rb index 0bf75f7..c6d8ff8 100644 --- a/lib/lunchmoney/transactions/transaction_calls.rb +++ b/lib/lunchmoney/transactions/transaction_calls.rb @@ -6,6 +6,7 @@ require_relative "split" module LunchMoney + # https://lunchmoney.dev/#transactions class TransactionCalls < ApiCall sig do params( diff --git a/lib/lunchmoney/transactions/update_transaction.rb b/lib/lunchmoney/transactions/update_transaction.rb index d8600a9..975a160 100644 --- a/lib/lunchmoney/transactions/update_transaction.rb +++ b/lib/lunchmoney/transactions/update_transaction.rb @@ -2,6 +2,7 @@ # frozen_string_literal: true module LunchMoney + # object used when updating a transaction https://lunchmoney.dev/#update-transaction class UpdateTransaction < LunchMoney::DataObject sig { returns(T.nilable(String)) } attr_accessor :date, :payee, :amount, :currency, :notes, :status, :external_id diff --git a/lib/lunchmoney/user/user.rb b/lib/lunchmoney/user/user.rb index 3605242..9e39088 100644 --- a/lib/lunchmoney/user/user.rb +++ b/lib/lunchmoney/user/user.rb @@ -2,6 +2,7 @@ # frozen_string_literal: true module LunchMoney + # https://lunchmoney.dev/#user-object class User < LunchMoney::DataObject sig { returns(Integer) } attr_accessor :user_id, :account_id diff --git a/lib/lunchmoney/user/user_calls.rb b/lib/lunchmoney/user/user_calls.rb index 688e585..eb7936b 100644 --- a/lib/lunchmoney/user/user_calls.rb +++ b/lib/lunchmoney/user/user_calls.rb @@ -4,6 +4,7 @@ require_relative "user" module LunchMoney + # https://lunchmoney.dev/#user class UserCalls < ApiCall sig { returns(T.any(LunchMoney::User, LunchMoney::Errors)) } def user diff --git a/lib/lunchmoney/validators.rb b/lib/lunchmoney/validators.rb index 046f916..19924a1 100644 --- a/lib/lunchmoney/validators.rb +++ b/lib/lunchmoney/validators.rb @@ -4,6 +4,7 @@ require "time" module LunchMoney + # module containing reusable methods for validating data objects module Validators include Kernel diff --git a/lib/lunchmoney/version.rb b/lib/lunchmoney/version.rb index b96ae09..657d039 100644 --- a/lib/lunchmoney/version.rb +++ b/lib/lunchmoney/version.rb @@ -2,5 +2,6 @@ # frozen_string_literal: true module LunchMoney + # Current version of the gem VERSION = "0.5.1" end