@lunch-money/developer-docs 2.11.0-preview.9 → 2.11.1-preview.2

package/README.md

@@ -1,65 +1,24 @@
 # @lunch-money/developer-docs
 
-Documentation content for the [Lunch Money](https://lunchmoney.app) developer APIs —
-the guides, v1/v2 reference docs, images, and doc-routing manifest that power the
-[Lunch Money developer portal](https://lunchmoney.dev).
+Developer documentation content for Lunch Money APIs.
 
-Most API consumers want the OpenAPI spec instead: **[`@lunch-money/v2-api-spec`](https://www.npmjs.com/package/@lunch-money/v2-api-spec)**
-is the canonical machine-readable API contract. This package is the human-facing docs
-content, primarily for the docs server that renders the portal.
+This package ships the public `developer-docs` repository content directories at the package root:
 
-## What's in the package
+- `docs/`
+- `v1/`
+- `v2/`
+- `manifest.json`
 
-Shipped verbatim at the package root:
-
-- `docs/` — version-independent guides (getting started, pagination, rate limiting, …)
-- `v1/` — v1 API reference markdown
-- `v2/` — v2 guides, images, and a **convenience copy** of the OpenAPI YAML under
-  `v2/spec/` (non-canonical; the canonical spec is `@lunch-money/v2-api-spec`)
-- `manifest.json` — doc routes, redirects, and sidebar structure
-
-## Consuming the content
-
-Resolve the package root, then read content files relative to it:
+The package version tracks the newest API version documented by this content. Server consumers should pin this package explicitly and resolve the package root with:
 
 ```js
-const path = require('path');
-const fs = require('fs');
-
 const docsRoot = path.dirname(require.resolve('@lunch-money/developer-docs/package.json'));
-const intro = fs.readFileSync(path.join(docsRoot, 'docs/getting-started.md'), 'utf8');
 ```
 
-`manifest.json` describes every page the docs server renders:
-
-```jsonc
-{
-  "pages": [
-    {
-      "path": "/amounts-and-balances",        // canonical URL
-      "file": "docs/amounts-and-balances.md",  // path within this package
-      "title": "Amounts & Balances",
-      "section": "GUIDES",                     // sidebar grouping
-      "type": "markdown",                      // "markdown" | "html" | "v1-slate"
-      "aliases": ["/v2/amounts-and-balances"]  // legacy URLs → 301 to path
-    }
-  ],
-  "redirects": [ /* { from, to, status } */ ],
-  "sidebar": { "docs": [ /* … */ ], "v1": [ /* … */ ] }
-}
-```
-
-## Versioning
-
-The package version tracks the newest API version this content documents (e.g. `2.11.x`
-documents the v2.11 API). Pin an exact version in server deployments so docs are
-deterministic.
+The OpenAPI YAML under `v2/spec/` is included as a convenience copy because the docs tree is shipped verbatim. The canonical v2 API specification package is `@lunch-money/v2-api-spec`.
 
-## Contributing
+## Updating Routes and Sidebar
 
-Guides, spec, and the routing manifest are edited in the public
-[`developer-docs` repository](https://github.com/lunch-money/developer-docs) — see its
-README for how to add or move a page. This npm package is a published build of that
-content.
+The docs server reads `manifest.json` from the package root. When adding or moving a documentation page, update the content file and add a matching manifest entry with `path`, `file`, `title`, `section`, and `type`.
 
-_ISC licensed._
+Run `npm run pack:docs` from the repository root before publishing. The package validates the manifest during `prepack` and fails if paths collide, aliases are duplicated, or referenced files are missing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunch-money/developer-docs",
-  "version": "2.11.0-preview.9",
+  "version": "2.11.1-preview.2",
   "description": "Developer documentation content for Lunch Money APIs",
   "exports": {
     ".": "./package.json",

package/v2/docs/version-history.md

@@ -5,6 +5,11 @@ The Lunch Money API spec uses a modified version of SEMVER for its versioning me
 - The minor version represents the number of main endpoints the current version of the spec supports.  For example, a version of the API that supports the /me, /categories, and /transactions endpoints would have a minor version of 3.
 - The revision number represents the number of updates since the last endpoint was added.  For example, each time changes are made to one of the existing three APIs as described above, the revision number will be bumped.
 
+## v2.11.1 - TBD
+- Add `GET /me/account/settings` and `PUT /me/account/settings` for account-level settings
+- Add `GET /me/user/settings` and `PUT /me/user/settings` for user-level display and formatting preferences
+- Document `GET /budgets/settings` response schema publicly; change `budget_period_quantity` to integer
+
 ## v2.11.0 - TBD
 - Add `GET /balance_history`
 - Add `GET /balance_history/{account_type}/{account_id}`

package/v2/spec/lunch-money-api-v2.yaml

@@ -33,7 +33,7 @@ info:
   license:
     name: Apache 2.0
     url: http://www.apache.org/licenses/LICENSE-2.0.html
-  version: 2.11.0
+  version: 2.11.1
 
 servers:
   - url: https://api.lunchmoney.dev/v2
@@ -44,7 +44,10 @@ servers:
 
 tags:
   - name: me
-    description: View details and settings for the current user and account
+    description: View details and settings for the current user and account.<p>
+      Use [/me/account/settings](#tag/me/GET/me/account/settings) and
+      [/me/user/settings](#tag/me/GET/me/user/settings) for account- and
+      user-level preferences.
   - name: categories
     description: Work with categories
     externalDocs:
@@ -141,9 +144,15 @@ components:
           description: Unique ID for the current budgeting account
         budget_name:
           type: string
-          description: Name of the current budgeting account
+          description: Name of the current budgeting account.<p> Also available
+            as `display_name` on
+            [/me/account/settings](#tag/me/GET/me/account/settings), which is
+            the preferred endpoint for reading and updating account settings.
         primary_currency:
-          description: Primary currency for the current budgeting account
+          description: Primary currency for the current budgeting account.<p>
+            Also available on [/me/account/settings](#tag/me/GET/me/account/settings),
+            which is the preferred endpoint for reading and updating account
+            settings.
           allOf:
             - $ref: "#/components/schemas/currencyEnum"
         api_key_label:
@@ -3667,6 +3676,371 @@ components:
         - budget_income_option
         - budget_rollover_left_to_budget
 
+    weekStartsOnEnum:
+      type: string
+      title: week starts on enum
+      enum:
+        - sunday
+        - monday
+      description: The day on which a calendar week begins.
+
+    monthYearFormatEnum:
+      type: string
+      title: month and year format enum
+      description: Format string for displaying month and year values
+        in the Lunch Money app.
+      enum:
+        - "MMMM YYYY"
+        - "MMM YYYY"
+        - "YYYY MMM"
+        - "MM YYYY"
+        - "MM-YYYY"
+        - "MM.YYYY"
+        - "MM/YYYY"
+        - "M YYYY"
+        - "M-YYYY"
+        - "M.YYYY"
+        - "M/YYYY"
+        - "YYYY M"
+        - "YYYY-M"
+        - "YYYY.M"
+        - "YYYY/M"
+        - "YYYY MM"
+        - "YYYY-MM"
+        - "YYYY.MM"
+        - "YYYY/MM"
+
+    monthDayYearFormatEnum:
+      type: string
+      title: month, day and year format enum
+      description: Format string for displaying full dates in the
+        Lunch Money app.
+      enum:
+        - "MMM D, YYYY"
+        - "D MMM YYYY"
+        - "YYYY MM DD"
+        - "YYYY-MM-DD"
+        - "YYYY.MM.DD"
+        - "YYYY/MM/DD"
+        - "YYYY M DD"
+        - "YYYY-M-DD"
+        - "YYYY.M.DD"
+        - "YYYY/M/DD"
+        - "YYYY MM D"
+        - "YYYY-MM-D"
+        - "YYYY.MM.D"
+        - "YYYY/MM/D"
+        - "YYYY M D"
+        - "YYYY-M-D"
+        - "YYYY.M.D"
+        - "YYYY/M/D"
+        - "DD MM YYYY"
+        - "DD-MM-YYYY"
+        - "DD.MM.YYYY"
+        - "DD/MM/YYYY"
+        - "DD M YYYY"
+        - "DD-M-YYYY"
+        - "DD.M.YYYY"
+        - "DD/M/YYYY"
+        - "D MM YYYY"
+        - "D-MM-YYYY"
+        - "D.MM.YYYY"
+        - "D/MM/YYYY"
+        - "D M YYYY"
+        - "D-M-YYYY"
+        - "D.M.YYYY"
+        - "D/M/YYYY"
+        - "M D YYYY"
+        - "M-D-YYYY"
+        - "M.D.YYYY"
+        - "M/D/YYYY"
+        - "MM D YYYY"
+        - "MM-D-YYYY"
+        - "MM.D.YYYY"
+        - "MM/D/YYYY"
+        - "MM DD YYYY"
+        - "MM-DD-YYYY"
+        - "MM.DD.YYYY"
+        - "MM/DD/YYYY"
+        - "M DD YYYY"
+        - "M-DD-YYYY"
+        - "M.DD.YYYY"
+        - "M/DD/YYYY"
+
+    monthDayFormatEnum:
+      type: string
+      title: month and day format enum
+      description: Format string for displaying month and day values
+        without a year.
+      enum:
+        - "MMM D"
+        - "MMM DD"
+        - "D MMM"
+        - "DD MMM"
+        - "MM D"
+        - "MM-D"
+        - "MM.D"
+        - "MM/D"
+        - "MM DD"
+        - "MM-DD"
+        - "MM.DD"
+        - "MM/DD"
+        - "M D"
+        - "M-D"
+        - "M.D"
+        - "M/D"
+        - "M DD"
+        - "M-DD"
+        - "M.DD"
+        - "M/DD"
+        - "D MM"
+        - "D-MM"
+        - "D.MM"
+        - "D/MM"
+        - "DD MM"
+        - "DD-MM"
+        - "DD.MM"
+        - "DD/MM"
+        - "D M"
+        - "D-M"
+        - "D.M"
+        - "D/M"
+        - "DD M"
+        - "DD-M"
+        - "DD.M"
+        - "DD/M"
+
+    accountSettingsObject:
+      type: object
+      title: account settings object
+      additionalProperties: false
+      description: Account-level settings for the budgeting account
+        associated with the authorized API token.
+      properties:
+        primary_currency:
+          description: Primary currency for the account.
+          allOf:
+            - $ref: "#/components/schemas/currencyEnum"
+        supported_currencies:
+          type: array
+          items:
+            $ref: "#/components/schemas/currencyEnum"
+          description: Currencies available when creating or editing transactions,
+            balances, and other amounts in the Lunch Money app.
+        display_name:
+          type: string
+          nullable: true
+          description: Display name of the budgeting account in the Lunch Money
+            app.
+        locale:
+          type: string
+          description: Locale used for formatting dates and numbers in the
+            Lunch Money app (for example, `en-US`). When no locale is explicitly
+            stored for the account, the effective locale is derived from the
+            `default_locale` associated with `primary_currency` in the
+            currencies table (for example, `usd` → `en-US`, `cad` → `en-CA`,
+            `gbp` → `en-GB`).
+        auto_create_category_rules:
+          type: boolean
+          default: true
+          description: If `true`, category rules are created automatically when
+            categorizing transactions.
+        auto_create_suggested_transaction_rules:
+          type: boolean
+          default: true
+          description: If `true`, suggested transaction rules are created
+            automatically.
+        auto_review_transaction_on_update:
+          type: boolean
+          default: true
+          description: If `true`, transactions are marked as reviewed when
+            updated.
+        auto_review_transaction_on_creation:
+          type: boolean
+          default: true
+          description: If `true`, transactions are marked as reviewed when
+            created.
+      required:
+        - primary_currency
+        - supported_currencies
+        - display_name
+        - locale
+        - auto_create_category_rules
+        - auto_create_suggested_transaction_rules
+        - auto_review_transaction_on_update
+        - auto_review_transaction_on_creation
+
+    updateAccountSettingsRequestObject:
+      x-internal: true
+      type: object
+      additionalProperties: false
+      description: Request body for updating account settings. Include at least
+        one property to update.
+      properties:
+        primary_currency:
+          allOf:
+            - $ref: "#/components/schemas/currencyEnum"
+          description: If set, updates the account's primary currency.
+          x-updatable: true
+        supported_currencies:
+          type: array
+          items:
+            $ref: "#/components/schemas/currencyEnum"
+          description: If set, replaces the list of supported currencies for the
+            account.
+          x-updatable: true
+        display_name:
+          type: string
+          nullable: true
+          description: If set, updates the display name of the budgeting account.
+          x-updatable: true
+        locale:
+          type: string
+          description: If set, updates the locale used for formatting dates and
+            numbers in the Lunch Money app.
+          x-updatable: true
+        auto_create_category_rules:
+          type: boolean
+          description: If set, updates whether category rules are created
+            automatically.
+          x-updatable: true
+        auto_create_suggested_transaction_rules:
+          type: boolean
+          description: If set, updates whether suggested transaction rules are
+            created automatically.
+          x-updatable: true
+        auto_review_transaction_on_update:
+          type: boolean
+          description: If set, updates whether transactions are marked as reviewed
+            when updated.
+          x-updatable: true
+        auto_review_transaction_on_creation:
+          type: boolean
+          description: If set, updates whether transactions are marked as reviewed
+            when created.
+          x-updatable: true
+
+    userSettingsObject:
+      type: object
+      title: user settings object
+      additionalProperties: false
+      description: User-level display and formatting preferences for the user
+        associated with the authorized API token.
+      properties:
+        show_debits_as_negative:
+          type: boolean
+          default: true
+          description: Display preference for how amounts are shown in the Lunch
+            Money app. When `true`, debits are shown as negative values and
+            credits as positive values.<p> This setting does **not** change
+            amount sign conventions in API responses. Amount fields such as
+            `amount` and `to_base` on transaction objects always use positive
+            values for debits and negative values for credits.
+        auto_suggest_payee:
+          type: boolean
+          default: true
+          description: If `true`, payee suggestions are shown when entering
+            transactions in the Lunch Money app.
+        month_year_format:
+          allOf:
+            - $ref: "#/components/schemas/monthYearFormatEnum"
+          default: "MMM YYYY"
+          description: Format string used when displaying month and year values.
+        month_day_year_format:
+          allOf:
+            - $ref: "#/components/schemas/monthDayYearFormatEnum"
+          default: "MMM D, YYYY"
+          description: Format string used when displaying full dates (month, day,
+            and year).
+        month_day_format:
+          allOf:
+            - $ref: "#/components/schemas/monthDayFormatEnum"
+          default: "MMM D"
+          description: Format string used when displaying month and day values
+            without a year.
+        show_am_pm:
+          type: boolean
+          default: true
+          description: If `true`, times are displayed using a 12-hour clock with
+            AM/PM. If `false`, times are displayed using a 24-hour clock.
+        week_starts_on:
+          allOf:
+            - $ref: "#/components/schemas/weekStartsOnEnum"
+          default: sunday
+          description: The day on which a calendar week begins.
+        always_display_year:
+          type: boolean
+          default: false
+          description: If `true`, dates always include the year and
+            `month_day_format` is not used.
+        always_display_weekday:
+          type: boolean
+          default: true
+          description: If `true`, weekday names are included when displaying
+            dates.
+      required:
+        - show_debits_as_negative
+        - auto_suggest_payee
+        - month_year_format
+        - month_day_year_format
+        - month_day_format
+        - show_am_pm
+        - week_starts_on
+        - always_display_year
+        - always_display_weekday
+
+    updateUserSettingsRequestObject:
+      x-internal: true
+      type: object
+      additionalProperties: false
+      description: Request body for updating user settings. Include at least one
+        property to update.
+      properties:
+        show_debits_as_negative:
+          type: boolean
+          description: If set, updates the display preference for amount signs in
+            the Lunch Money app. Does not affect amount sign conventions in API
+            responses.
+          x-updatable: true
+        auto_suggest_payee:
+          type: boolean
+          description: If set, updates whether payee suggestions are shown.
+          x-updatable: true
+        month_year_format:
+          allOf:
+            - $ref: "#/components/schemas/monthYearFormatEnum"
+          description: If set, updates the month and year display format.
+          x-updatable: true
+        month_day_year_format:
+          allOf:
+            - $ref: "#/components/schemas/monthDayYearFormatEnum"
+          description: If set, updates the full date display format.
+          x-updatable: true
+        month_day_format:
+          allOf:
+            - $ref: "#/components/schemas/monthDayFormatEnum"
+          description: If set, updates the month and day display format.
+          x-updatable: true
+        show_am_pm:
+          type: boolean
+          description: If set, updates whether times use a 12-hour (AM/PM) or
+            24-hour clock.
+          x-updatable: true
+        week_starts_on:
+          allOf:
+            - $ref: "#/components/schemas/weekStartsOnEnum"
+          description: If set, updates the day on which a calendar week begins.
+          x-updatable: true
+        always_display_year:
+          type: boolean
+          description: If set, updates whether dates always include the year.
+          x-updatable: true
+        always_display_weekday:
+          type: boolean
+          description: If set, updates whether weekday names are shown when
+            displaying dates.
+          x-updatable: true
+
     # Summary endpoint response schemas
     summaryResponseObject:
       type: object
@@ -4465,8 +4839,13 @@ paths:
       tags:
         - me
       summary: Get current user
-      description: Get details about the user associated with the supplied
-        authorization token.
+      description: |-
+        Get details about the user associated with the supplied authorization
+        token.<p> For account- and user-level preferences, prefer
+        [/me/account/settings](#tag/me/GET/me/account/settings) and
+        [/me/user/settings](#tag/me/GET/me/user/settings). Properties such as
+        `primary_currency` and `budget_name` remain on this response for
+        backwards compatibility.
       operationId: getMe
       parameters: []
       responses:
@@ -4490,6 +4869,165 @@ paths:
           $ref: "#/components/responses/rateLimited"
         "500":
           $ref: "#/components/responses/serverError"
+  /me/account/settings:
+    get:
+      tags:
+        - me
+      summary: Get account settings
+      description: Returns account-level settings for the budgeting
+        account associated with the authorized API token.
+      operationId: getAccountSettings
+      responses:
+        "200":
+          description: Account settings for the current budgeting account
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/accountSettingsObject"
+              example:
+                primary_currency: usd
+                supported_currencies:
+                  - usd
+                  - cad
+                  - jpy
+                display_name: "\U0001F3E0 Family budget"
+                locale: en-US
+                auto_create_category_rules: true
+                auto_create_suggested_transaction_rules: true
+                auto_review_transaction_on_update: true
+                auto_review_transaction_on_creation: true
+        "401":
+          $ref: "#/components/responses/unauthorizedToken"
+        "429":
+          $ref: "#/components/responses/rateLimited"
+        "500":
+          $ref: "#/components/responses/serverError"
+    put:
+      tags:
+        - me
+      summary: Update account settings
+      description: |-
+        Updates account-level settings for the budgeting account
+        associated with the authorized API token.<p> You may submit the response from a
+        `GET /me/account/settings` as the request body; however, only certain
+        properties can be updated.<p> It is also possible to provide only the
+        properties to be updated in the request body, as long as the request
+        includes at least one updatable property.
+      operationId: updateAccountSettings
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/updateAccountSettingsRequestObject"
+            examples:
+              Update display name:
+                value:
+                  display_name: "Travel budget"
+              Update automation preferences:
+                value:
+                  auto_create_category_rules: false
+                  auto_review_transaction_on_creation: false
+      responses:
+        "200":
+          description: Account settings updated successfully
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/accountSettingsObject"
+        "400":
+          description: Invalid request body
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/errorResponseObject"
+        "401":
+          $ref: "#/components/responses/unauthorizedToken"
+        "429":
+          $ref: "#/components/responses/rateLimited"
+        "500":
+          $ref: "#/components/responses/serverError"
+  /me/user/settings:
+    get:
+      tags:
+        - me
+      summary: Get user settings
+      description: Returns user-level display and formatting preferences for the
+        user associated with the authorized API token.
+      operationId: getUserSettings
+      responses:
+        "200":
+          description: User settings for the authorized user
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/userSettingsObject"
+              example:
+                show_debits_as_negative: true
+                auto_suggest_payee: true
+                month_year_format: "MMM YYYY"
+                month_day_year_format: "MMM D, YYYY"
+                month_day_format: "MMM D"
+                show_am_pm: true
+                week_starts_on: sunday
+                always_display_year: false
+                always_display_weekday: true
+        "401":
+          $ref: "#/components/responses/unauthorizedToken"
+        "429":
+          $ref: "#/components/responses/rateLimited"
+        "500":
+          $ref: "#/components/responses/serverError"
+    put:
+      tags:
+        - me
+      summary: Update user settings
+      description: |-
+        Updates user-level display and formatting preferences for the user
+        associated with the authorized API token.<p> You may submit the response
+        from a `GET /me/user/settings` as the request body; however, only
+        certain properties can be updated.<p> It is also possible to provide
+        only the properties to be updated in the request body, as long as the
+        request includes at least one updatable property.<p> Updating
+        `show_debits_as_negative` affects display in the Lunch Money app only.
+        Amount fields in API responses always use positive values for debits and
+        negative values for credits.
+      operationId: updateUserSettings
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/updateUserSettingsRequestObject"
+            examples:
+              Update date formats:
+                value:
+                  month_year_format: "YYYY-MM"
+                  month_day_year_format: "YYYY-MM-DD"
+                  month_day_format: "MM-DD"
+              Use 24-hour time and Monday week start:
+                value:
+                  show_am_pm: false
+                  week_starts_on: monday
+      responses:
+        "200":
+          description: User settings updated successfully
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/userSettingsObject"
+        "400":
+          description: Invalid request body
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/errorResponseObject"
+        "401":
+          $ref: "#/components/responses/unauthorizedToken"
+        "429":
+          $ref: "#/components/responses/rateLimited"
+        "500":
+          $ref: "#/components/responses/serverError"
   /summary:
     get:
       tags:
@@ -11618,7 +12156,9 @@ paths:
       description: |-
         Returns budget period and display settings for the budget
         associated with this API token.<p> These control how budget **periods** are calculated
-        (granularity, anchor date, rollover, and related options).
+        (granularity, anchor date, rollover, and related options). For general
+        budget preferences such as currency and locale, see
+        [/me/account/settings](#tag/me/GET/me/account/settings).
       operationId: getBudgetSettings
       responses:
         "200":