@lunch-money/developer-docs 2.11.0-preview.10

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@lunch-money/developer-docs",
+  "version": "2.11.0-preview.10",
+  "description": "Developer documentation content for Lunch Money APIs",
+  "exports": {
+    ".": "./package.json",
+    "./manifest.json": "./manifest.json",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "docs",
+    "v1",
+    "v2",
+    "manifest.json",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "validate:manifest": "node scripts/validate-manifest.js",
+    "prepack": "node scripts/validate-manifest.js && node scripts/prepack.js",
+    "postpack": "node scripts/postpack.js"
+  },
+  "keywords": [
+    "lunchmoney",
+    "api",
+    "documentation"
+  ],
+  "author": "",
+  "license": "ISC"
+}

package/v1/_assets.md

@@ -0,0 +1,188 @@
+# Assets
+
+<aside class="notice">
+This API (v1) will not progress to a generally available state. For new projects, we recommend using the <a href="/v2/docs#tag/manual_accounts">v2 API</a>, which is in open alpha and actively maintained.
+</aside>
+
+## Assets Object
+
+Attribute Name       | Type    | Nullable | Description
+-------------------- | ------- | -------- | ----------------------------------------------------------------------------
+id                   | number  | false    | Unique identifier for asset
+type_name            | string  | false    | Primary type of the asset. Must be one of:<br><ul> <li>cash</li> <li>credit</li> <li>investment</li> <li>real estate</li> <li>loan</li> <li>vehicle</li> <li>cryptocurrency</li> <li>employee compensation</li> <li>other liability</li> <li>other asset</li> </ul> |
+subtype_name         | string  | true     | Optional asset subtype. Examples include:<br><ul> <li>retirement</li> <li>checking</li> <li>savings</li> <li>prepaid credit card</li><ul>
+name                 | string  | false    | Name of the asset
+display_name         | string  | true     | Display name of the asset (as set by user)
+balance              | string  | false    | Current balance of the asset in numeric format to 4 decimal places
+to_base              | number  | true     | The balance converted to the user's primary currency
+balance_as_of        | string  | false    | Date/time the balance was last updated in ISO 8601 extended format
+closed_on            | string  | true     | The date this asset was closed (optional)
+currency             | string  | false    | Three-letter lowercase currency code of the balance in ISO 4217 format
+institution_name     | string  | true     | Name of institution holding the asset
+exclude_transactions | boolean | false    | If true, this asset will not show up as an option for assignment when creating transactions manually.
+created_at           | string  | false    | Date/time the asset was created in ISO 8601 extended format
+
+## Get All Assets
+
+Use this endpoint to get a list of all manually-managed assets associated with the user's account.
+
+> Example 200 Response
+
+```json
+{
+  "assets": [
+    {
+      "id": 72,
+      "type_name": "cash",
+      "subtype_name": "physical cash",
+      "name": "Test Asset 1",
+      "balance": "1201.0100",
+      "to_base": 1020.85,
+      "balance_as_of": "2020-01-26T12:27:22.000Z",
+      "currency": "cad",
+      "institution_name": "Bank of Me",
+      "exclude_transactions": false,
+      "created_at": "2020-01-26T12:27:22.726Z"
+    },
+    {
+      "id": 73,
+      "type_name": "credit",
+      "subtype_name": "credit card",
+      "name": "Test Asset 2",
+      "balance": "0.0000",
+      "to_base": 0,
+      "balance_as_of": "2020-01-26T12:27:22.000Z",
+      "currency": "usd",
+      "institution_name": "Bank of You",
+      "exclude_transactions": false,
+      "created_at": "2020-01-26T12:27:22.744Z"
+    },
+    {
+      "id": 74,
+      "type_name": "vehicle",
+      "subtype_name": "automobile",
+      "name": "Test Asset 3",
+      "balance": "99999999999.0000",
+      "to_base": 657179189.99,
+      "balance_as_of": "2020-01-26T12:27:22.000Z",
+      "currency": "jpy",
+      "institution_name": "Bank of Mom",
+      "exclude_transactions": false,
+      "created_at": "2020-01-26T12:27:22.755Z"
+    },
+    {
+      "id": 75,
+      "type_name": "loan",
+      "subtype_name": null,
+      "name": "Test Asset 4",
+      "balance": "10101010101.0000",
+      "to_base": 307687460.61,
+      "balance_as_of": "2020-01-26T12:27:22.000Z",
+      "currency": "twd",
+      "institution_name": null,
+      "exclude_transactions": true,
+      "created_at": "2020-01-26T12:27:22.765Z"
+    }
+  ]
+}
+```
+
+### HTTP Request
+
+`GET https://api.lunchmoney.dev/v1/assets`
+
+## Create Asset
+
+Use this endpoint to create a single (manually-managed) asset.
+
+> Example 200 Response
+
+```json
+{
+  "id": 34061,
+  "type_name": "depository",
+  "subtype_name": null,
+  "name": "My Test Asset",
+  "display_name": null,
+  "balance": "67.2100",
+  "to_base": 47.05,
+  "balance_as_of": "2022-05-29T21:35:36.557Z",
+  "closed_on": null,
+  "created_at": "2022-05-29T21:35:36.564Z",
+  "currency": "cad",
+  "institution_name": null,
+  "exclude_transactions": false
+}
+```
+
+### HTTP Request
+
+`POST https://api.lunchmoney.dev/v1/assets`
+
+### Body Parameters
+
+Parameter            | Type    | Required | Default                 | Description
+-------------------- | ------- | -------- | ----------------------- | --------------------------------------------------
+type_name            | string  | true     | -                       | Must be one of: cash, credit, investment, other, real estate, loan, vehicle, cryptocurrency, employee compensation
+subtype_name         | string  | false    | -                       | Max 25 characters
+name                 | string  | true     | -                       | Max 45 characters
+display_name         | string  | false    | -                       | Display name of the asset (as set by user)
+balance              | string  | true     | -                       | Numeric value of the current balance of the account. Do not include any special characters aside from a decimal point!
+balance_as_of        | string  | false    | Current timestamp       | Has no effect if balance is not defined. If balance is defined, but balance_as_of is not supplied or is invalid, current timestamp will be used.
+currency             | string  | false    | User's primary currency | Three-letter lowercase currency in ISO 4217 format. The code sent must exist in our database. Defaults to user's primary currency.
+institution_name     | string  | false    | -                       | Max 50 characters
+closed_on            | string  | false    | -                       | The date this asset was closed
+exclude_transactions | boolean | false    | false                   | If true, this asset will not show up as an option for assignment when creating transactions manually
+
+## Update Asset
+
+Use this endpoint to update a single asset.
+
+> Example 200 Response
+
+```json
+{
+  "id": 12,
+  "type_name": "cash",
+  "subtype_name": "savings",
+  "name": "TD Savings Account",
+  "balance": "28658.5300",
+  "to_base": 20061.34,
+  "balance_as_of": "2020-03-10T05:17:23.856Z",
+  "currency": "cad",
+  "institution_name": "TD Bank",
+  "exclude_transactions": false,
+  "created_at": "2019-08-10T22:46:19.486Z"
+}
+```
+
+> Example Error Response (sends as 200)
+
+```json
+{
+  "errors": [
+    "type_name must be one of: cash, credit, investment, other, real estate, loan, vehicle, cryptocurrency, employee compensation"
+  ]
+}
+```
+
+### HTTP Request
+
+`PUT https://api.lunchmoney.dev/v1/assets/:id`
+
+### Body Parameters
+
+Parameter            | Type    | Required | Default                 | Description
+-------------------- | ------- | -------- | ----------------------- | --------------------------------------------------
+type_name            | string  | false    | -                       | Must be one of: cash, credit, investment, other, real estate, loan, vehicle, cryptocurrency, employee compensation
+subtype_name         | string  | false    | -                       | Max 25 characters
+name                 | string  | false    | -                       | Max 45 characters
+display_name         | string  | false    | -                       | Display name of the asset (as set by user)
+balance              | string  | false    | -                       | Numeric value of the current balance of the account. Do not include any special characters aside from a decimal point!
+balance_as_of        | string  | false    | Current timestamp       | Has no effect if balance is not defined. If balance is defined, but balance_as_of is not supplied or is invalid, current timestamp will be used.
+currency             | string  | false    | User's primary currency | Three-letter lowercase currency in ISO 4217 format. The code sent must exist in our database. Defaults to user's primary currency.
+institution_name     | string  | false    | -                       | Max 50 characters
+closed_on            | string  | false    | -                       | The date this asset was closed
+exclude_transactions | boolean | false    | false                   | If true, this asset will not show up as an option for assignment when creating transactions manually
+
+---

package/v1/_budget.md

@@ -0,0 +1,256 @@
+# Budget
+
+<aside class="notice">
+This API (v1) will not progress to a generally available state. For new projects, we recommend using the <a href="/v2/docs#tag/summary">v2 API</a>, which is in open alpha and actively maintained.
+</aside>
+
+## Budget Object
+
+| Attribute Name      | Type    | Nullable | Description                                                                                                                                                              |
+| ------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| category_name       | string  | false    | Name of the category, will be "Uncategorized" if no category is assigned                                                                                                 |
+| category_id         | number  | true     | Unique identifier for category, can be null when `category_name` is "Uncategorized"                                                                                      |
+| category_group_name | string  | true     | Name of the category group, if applicable                                                                                                                                |
+| group_id            | number  | true     | Unique identifier for category group                                                                                                                                     |
+| is_group            | boolean | true     | If true, this category is a group                                                                                                                                        |
+| is_income           | boolean | false    | If true, this category is an income category (category properties are set in the app via the Categories page)                                                            |
+| exclude_from_budget | boolean | false    | If true, this category is excluded from budget (category properties are set in the app via the Categories page)                                                          |
+| exclude_from_totals | boolean | false    | If true, this category is excluded from totals (category properties are set in the app via the Categories page)                                                          |
+| data                | Data[]  | false    | For each month with budget or category spending data, there is a data object with the key set to the month in format YYYY-MM-DD. For properties, see Data object below.  |
+| config              | object  | true     | Object representing the category's budget suggestion configuration. Will be `null` if the category has no budget configuration set. See Config Object below for details. |
+| order               | number  | false    | Numerical ordering of budgets                                                                                                                                            |
+| archived            | boolean | false    | True if the category is archived and not displayed in relevant areas of the Lunch Money app.                                                                             |
+| recurring           | object  | true     | Returns a list object that contains an array of Recurring Expenses objects (just the `payee`, `amount`, `currency`, and `to_base` fields) that affect this budget        |
+
+**Note:** A category may appear in the budget response even if no budget has been set for it. This can happen when:
+- The category has transactions but no budget entries have been created
+- The category has a custom budget period configured but no budget amounts have been set
+- Budget entries were deleted but transactions still exist for that category
+- After a users existing v1 budgets were migrated to v2 budgets, if a user changed their budget period settings (quantity, granularity, or anchor date), categories without budget values may exist.
+
+In these cases, the `config` property will be `null`, and the `data` object will contain spending information (`spending_to_base`, `num_transactions`) but all `budget_*` properties will be `null`.
+
+## Data Object
+
+| Attribute Name   | Type    | Nullable | Description                                                                                                                                                                                                                         |
+| ---------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| budget_amount    | number  | true     | The budget amount, as set by the user. Will be `null` if no budget has been set for this category and time period.                                                                                                                  |
+| budget_currency  | string  | true     | The budget currency, as set by the user. Will be `null` if no budget has been set for this category and time period.                                                                                                                |
+| budget_to_base   | number  | true     | The budget converted to the user's primary currency. If the multicurrency feature is not being used, budget_to_base and budget_amount will be the same. Will be `null` if no budget has been set for this category and time period. |
+| spending_to_base | number  | false    | The total amount spent in this category for this time period in the user's primary currency. This value will always be present, even if no budget has been set.                                                                     |
+| num_transactions | number  | false    | Number of transactions that make up "spending_to_base". This value will always be present, even if no budget has been set.                                                                                                          |
+| is_automated     | boolean | true     | If true, the budget_amount is only a suggestion based on the set config. If not present, it is false (meaning this is a locked in budget). Will be `null` if no budget has been set.                                                |
+
+**Note:** When a category has transactions but no budget entries, the `data` object will still be present with spending information, but all `budget_*` properties will be `null`. This allows you to see spending activity even when budgets haven't been configured.
+
+## Config Object
+
+| Attribute Name | Type   | Nullable | Description                                                                                                                                                              |
+| -------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| config_id      | number | false    | Unique identifier for config                                                                                                                                             |
+| cadence        | string | false    | One of:<br> <ul> <li>monthly</li> <li>twice a month</li> <li>once a week</li> <li>every 3 months</li> <li>every 4 months</li> <li>twice a year</li> <li>yearly</li></ul> |
+| amount         | number | false    | Amount in numeric format                                                                                                                                                 |
+| currency       | string | false    | Three-letter lowercase currency code for the recurring expense in ISO 4217 format                                                                                        |
+| to_base        | number | false    | The amount converted to the user's primary currency.                                                                                                                     |
+| auto_suggest   | string | false    | One of:<br> <ul> <li>budgeted</li> <li>fixed</li> <li>fixed-rollover</li> <li>spent</li> </ul>                                                                           |
+
+**Note:** The `config` property in the Budget Object can be `null`. When `config` is `null`, it means the category has no budget configuration set. When `config` is present (not null), all properties listed above are required and not nullable.
+
+## Get Budget Summary
+
+Use this endpoint to get full details on the budgets for all budgetable categories between a certain time period. The budgeted and spending amounts will be broken down by month.
+
+**Note:** Categories may appear in the response even if they have no budget entries, as long as they have transactions in the specified time period. In these cases, `config` will be `null` and all `budget_*` properties in the `data` object will be `null`, but `spending_to_base` and `num_transactions` will still be populated.
+
+> Example 200 Response
+
+```json
+[
+    {
+        "category_name": "Food",
+        "category_id": 34476,
+        "category_group_name": null,
+        "group_id": null,
+        "is_group": true,
+        "is_income": false,
+        "exclude_from_budget": false,
+        "exclude_from_totals": false,
+        "data": {
+            "2020-09-01": {
+                "num_transactions": 23,
+                "spending_to_base": 373.51,
+                "budget_to_base": 376.08,
+                "budget_amount": 376.08,
+                "budget_currency": "usd",
+                "is_automated": true,
+            },
+            "2020-08-01": {
+                "num_transactions": 23,
+                "spending_to_base": 123.92,
+                "budget_to_base": 300,
+                "budget_amount": 300,
+                "budget_currency": "usd",
+            },
+            "2020-07-01": {
+                "num_transactions": 23,
+                "spending_to_base": 228.66,
+                "budget_to_base": 300,
+                "budget_amount": 300,
+                "budget_currency": "usd",
+            }
+        },
+        "config": {
+            "config_id": 9,
+            "cadence": "monthly",
+            "amount": 300,
+            "currency": "usd",
+            "to_base": 300,
+            "auto_suggest": "fixed-rollover"
+        },
+        "order": 0,
+        "archived": false,
+        "recurring": null
+    },
+    {
+        "category_name": "Alcohol & Bars",
+        "category_id": 26,
+        "category_group_name": "Food",
+        "group_id": 34476,
+        "is_group": null,
+        "is_income": false,
+        "exclude_from_budget": false,
+        "exclude_from_totals": false,
+        "data": {
+            "2020-09-01": {
+                "spending_to_base": 270.86,
+                "num_transactions": 14
+            },
+            "2020-08-01": {
+                "spending_to_base": 79.53,
+                "num_transactions": 8
+            },
+            "2020-07-01": {
+                "spending_to_base": 149.61,
+                "num_transactions": 8
+            }
+        },
+        "config": null,
+        "archived": false,
+        "order": 1,
+        "recurring": {
+            "list": [
+                {
+                    "payee": "Recurring Payee",
+                    "amount": "20.000",
+                    "currency": "cad",
+                    "to_base": 20
+                }
+            ]
+        }
+    },
+    {
+        "category_name": "Unbudgeted Category",
+        "category_id": 12345,
+        "category_group_name": null,
+        "group_id": null,
+        "is_group": false,
+        "is_income": false,
+        "exclude_from_budget": false,
+        "exclude_from_totals": false,
+        "data": {
+            "2020-09-01": {
+                "spending_to_base": 50.00,
+                "num_transactions": 1,
+                "budget_to_base": null,
+                "budget_amount": null,
+                "budget_currency": null
+            }
+        },
+        "config": null,
+        "order": 2,
+        "archived": false,
+        "recurring": null
+    }
+]
+```
+
+### HTTP Request
+
+`GET https://api.lunchmoney.dev/v1/budgets`
+
+### Query Parameters
+
+| Parameter  | Type   | Required | Default | Description                                                                                                                                         |
+| ---------- | ------ | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| start_date | string | true     | -       | Start date for the budget period. Lunch Money currently only supports monthly budgets, so your date should be the start of a month (eg. 2021-04-01) |
+| end_date   | string | true     | -       | End date for the budget period. Lunch Money currently only supports monthly budgets, so your date should be the end of a month (eg. 2021-04-30)     |
+| currency   | string | false    | -       | Currency for the budgeted amount (optional). If empty, will default to your primary currency                                                        |
+
+## Upsert Budget
+
+Use this endpoint to update an existing budget or insert a new budget for a particular category and date.
+
+Note: Lunch Money currently only supports monthly budgets, so your date must always be the start of a month (eg. 2021-04-01)
+
+> Example 200 Response
+
+If this is a sub-category, the response will include the updated category group's budget. This is because setting a sub-category may also update the category group's overall budget.
+
+```json
+{
+    "category_group": {
+        "category_id": 34476,
+        "amount": 100,
+        "currency": "usd",
+        "start_date": "2021-06-01"
+    }
+}
+```
+
+> Example Error Response (sends as 200)
+
+```json
+{ "error": "Budget must be greater than or equal to the sum of sub-category budgets ($10.01)." }
+```
+
+### HTTP Request
+
+`PUT https://api.lunchmoney.dev/v1/budgets`
+
+### Body Parameters
+
+| Parameter   | Type   | Required | Default | Description                                                                                                                                              |
+| ----------- | ------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| start_date  | string | true     | -       | Start date for the budget period. Lunch Money currently only supports monthly budgets, so your date must always be the start of a month (eg. 2021-04-01) |
+| category_id | number | true     | -       | Unique identifier for the category                                                                                                                       |
+| amount      | number | true     | -       | Amount for budget                                                                                                                                        |
+| currency    | string | false    | -       | Currency for the budgeted amount (optional). If empty, will default to your primary currency                                                             |
+
+## Remove Budget
+
+Use this endpoint to unset an existing budget for a particular category in a particular month.
+
+> Example 200 Response
+
+```json
+true
+```
+
+> Example Error Response (sends as 200)
+
+```json
+{ "error": "start_date must be a valid date in format YYYY-MM-01" }
+```
+
+### HTTP Request
+
+`DELETE https://api.lunchmoney.dev/v1/budgets`
+
+### Query Parameters
+
+| Parameter   | Type   | Required | Default | Description                                                                                                                                              |
+| ----------- | ------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| start_date  | string | true     | -       | Start date for the budget period. Lunch Money currently only supports monthly budgets, so your date must always be the start of a month (eg. 2021-04-01) |
+| category_id | number | true     | -       | Unique identifier for the category                                                                                                                       |
+
+---