✨ get_recurring_items

#125

docs/interacting.md

@@ -20,7 +20,7 @@ lunch = LunchMoney(access_token="xxxxxxxxxxx")
 | GET       | [get_category](#lunchable.LunchMoney.get_category)                             | Get single category                                                      |
 | GET       | [get_crypto](#lunchable.LunchMoney.get_crypto)                                 | Get Crypto Assets                                                        |
 | GET       | [get_plaid_accounts](#lunchable.LunchMoney.get_plaid_accounts)                 | Get Plaid Synced Assets                                                  |
-| GET       | [get_recurring_expenses](#lunchable.LunchMoney.get_recurring_expenses)         | Get Recurring Expenses                                                   |
+| GET       | [get_recurring_items](#lunchable.LunchMoney.get_recurring_items)               | Get Recurring Items                                                      |
 | GET       | [get_tags](#lunchable.LunchMoney.get_tags)                                     | Get Spending Tags                                                        |
 | GET       | [get_transaction](#lunchable.LunchMoney.get_transaction)                       | Get a Transaction by ID                                                  |
 | GET       | [get_transactions](#lunchable.LunchMoney.get_transactions)                     | Get Transactions Using Criteria                                          |

lunchable/_config/api_config.py

@@ -26,6 +26,7 @@ class APIConfig:
     LUNCHMONEY_TRANSACTION_GROUPS: str = "group"
     LUNCHMONEY_PLAID_ACCOUNTS: str = "plaid_accounts"
     LUNCH_MONEY_RECURRING_EXPENSES: str = "recurring_expenses"
+    LUNCH_MONEY_RECURRING_ITEMS: str = "recurring_items"
     LUNCHMONEY_BUDGET: str = "budgets"
     LUNCHMONEY_ASSETS: str = "assets"
     LUNCHMONEY_CATEGORIES: str = "categories"

lunchable/models/_descriptions.py

@@ -273,6 +273,150 @@ class _RecurringExpensesDescriptions:
     """
 
 
+class _SummarizedTransactionDescriptions:
+    """
+    Descriptions for Summarized Transaction
+    """
+
+    id = """
+    Unique identifier for the transaction that matched this recurring item
+    """
+    date = """
+    Date of transaction in ISO 8601 format
+    """
+    amount = """
+    Amount of the transaction in numeric format to 4 decimal places
+    """
+    currency = """
+    Three-letter lowercase currency code of the transaction in ISO 4217 format
+    """
+    payee = """
+    Payee or payer of the recurring item
+    """
+    category_id = """
+    Unique identifier of associated category
+    """
+    recurring_id = """
+    Unique identifier of associated recurring item
+    """
+    to_base = """
+    The amount converted to the user's primary currency. If the multicurrency
+    feature is not being used, to_base and amount will be the same.
+    """
+
+
+class _RecurringItemsDescriptions:
+    """
+    Descriptions for Recurring Items
+    """
+
+    id = """
+    Unique identifier for recurring item
+    """
+    start_date = """
+    Denotes when recurring item starts occurring in ISO 8601 format.
+    If null, then this recurring item will show up for all time before end_date
+    """
+    end_date = """
+    Denotes when recurring item stops occurring in ISO 8601 format.
+    If null, then this recurring item has no set end date and will
+    show up for all months after start_date
+    """
+    payee = """
+    Payee or payer of the recurring item
+    """
+    currency = """
+    Three-letter lowercase currency code for the recurring item in ISO 4217 format
+    """
+    created_by = """
+    The id of the user who created this recurring item.
+    """
+    created_at = """
+    The date and time of when the recurring item was created (in the ISO 8601
+    extended format).
+    """
+    updated_at = """
+    The date and time of when the recurring item was updated (in the ISO 8601 extended format).
+    """
+    billing_date = """
+    Initial date that a transaction associated with this recurring item occured.
+    This date is used in conjunction with values of quantity and granularity to
+    determine the expected dates of recurring transactions in the period.
+    """
+    original_name = """
+    If any, represents the original name of the recurring item as denoted by
+    the transaction that triggered its creation
+    """
+    description = """
+    If any, represents the user-entered description of the recurring item
+    """
+    plaid_account_id = """
+    If any, denotes the plaid account associated with the creation of this
+    recurring item (see Plaid Accounts)
+    """
+    asset_id = """
+    If any, denotes the manually-managed account (i.e. asset) associated
+    with the creation of this recurring item (see Assets)
+    """
+    source = """
+    This can be one of four values:
+    - manual: User created this recurring item manually from the Recurring Items page
+    - transaction: User created this by converting a transaction from the Transactions page
+    - system: Recurring item was created by the system on transaction import
+    - null: Some older recurring items may not have a source.
+    """
+    notes = """
+    If any, the user-entered notes for the recurring item
+    """
+    amount = """
+    Amount of the recurring item in numeric format to 4 decimal places.
+    For recurring items with flexible amounts, this is the average of the
+    specified min and max amounts.
+    """
+    category_id = """
+    If any, denotes the unique identifier for the associated category to this recurring item
+    """
+    category_group_id = """
+    If any, denotes the unique identifier of associated category group
+    """
+    is_income = """
+    Based on the associated category's property, denotes if the recurring transaction
+    is treated as income
+    """
+    exclude_from_totals = """
+    Based on the associated category's property, denotes if the recurring transaction is excluded from totals
+    """
+    granularity = """
+    The unit of time used to define the cadence of the recurring item.
+    One of `weeks`, `months`, `years`
+    """
+    quantity = """
+    The number of granular units between each occurrence
+    """
+    occurrences = """
+    An object which contains dates as keys and lists as values. The dates will
+    include all the dates in the month that a recurring item is expected, as well
+    as the last date in the previous period and the first date in the next period.
+    The value for each key is a list of Summarized Transaction Objects that matched
+    the recurring item for that date (if any)
+    """
+    transactions_within_range = """
+    A list of all the Summarized Transaction Objects for transactions that that
+    have occurred in the query month for the recurring item (if any)
+    """
+    missing_dates_within_range = """
+    A list of date strings when a recurring transaction is expected but has not (yet) occurred.
+    """
+    date = """
+    Denotes the value of the start_date query parameter, or if none was provided, the date when
+    the request was made. This indicates the month used by the system when populating the response.
+    """
+    to_base = """
+    The amount converted to the user's primary currency. If the multicurrency feature is not being
+    used, to_base and amount will be the same.
+    """
+
+
 class _TransactionInsertDescriptions:
     """
     Descriptions for TransactionInsertObject

lunchable/models/_lunchmoney.py

@@ -18,6 +18,7 @@
 from .crypto import CryptoClient
 from .plaid_accounts import PlaidAccountsClient
 from .recurring_expenses import RecurringExpensesClient
+from .recurring_items import RecurringItemsClient
 from .tags import TagsClient
 from .transactions import TransactionsClient
 from .user import UserClient
@@ -33,6 +34,7 @@ class LunchMoney(
     TagsClient,
     TransactionsClient,
     UserClient,
+    RecurringItemsClient,
 ):
     """
     Lunch Money Python Client.

lunchable/models/recurring_expenses.py

@@ -6,6 +6,7 @@
 
 import datetime
 import logging
+import warnings
 from typing import List, Optional
 
 from pydantic import Field
@@ -55,9 +56,6 @@ class RecurringExpensesObject(LunchableModel):
     asset_id: Optional[int] = Field(
         None, description=_RecurringExpensesDescriptions.asset_id
     )
-    transaction_id: Optional[int] = Field(
-        None, description=_RecurringExpensesDescriptions.transaction_id
-    )
     category_id: Optional[int] = Field(
         None, description=_RecurringExpensesDescriptions.category_id
     )
@@ -85,6 +83,9 @@ def get_recurring_expenses(
         """
         Get Recurring Expenses
 
+        **DEPRECATED** - Use [LunchMoney.get_recurring_items()][lunchable.LunchMoney.get_recurring_items]
+        instead.
+
         Retrieve a list of recurring expenses to expect for a specified period.
 
         Every month, a different set of recurring expenses is expected. This is because recurring
@@ -111,6 +112,14 @@ def get_recurring_expenses(
         -------
         List[RecurringExpensesObject]
         """
+        warnings.warn(
+            message=(
+                "`LunchMoney.get_recurring_expenses` is deprecated, "
+                "use `LunchMoney.get_recurring_items` instead"
+            ),
+            category=DeprecationWarning,
+            stacklevel=2,
+        )
         if start_date is None:
             start_date = datetime.datetime.now().date().replace(day=1)
         params = RecurringExpenseParamsGet(