@lunch-money/v2-api-spec 2.11.1-preview.5 → 2.11.1-preview.9

package/README.md

@@ -14,6 +14,7 @@ After installation, the package provides:
 
 - **OpenAPI Specification**: `node_modules/@lunch-money/v2-api-spec/lunch-money-api-v2.yaml`
 - **Version History**: `node_modules/@lunch-money/v2-api-spec/version-history.md`
+- **OAuth scope catalog**: `@lunch-money/v2-api-spec/oauth-scopes`
 
 ## Usage
 
@@ -26,6 +27,22 @@ const specPath = require.resolve('@lunch-money/v2-api-spec/lunch-money-api-v2.ya
 const spec = fs.readFileSync(specPath, 'utf8');
 ```
 
+### Using the OAuth scope catalog
+
+The package also provides immutable OAuth scope and scope-group definitions.
+API scopes identify the V2 operations they authorize by `operationId`.
+
+```javascript
+const {
+  getOAuthScopeDefinition,
+  matchOAuthScopeGroup,
+  oauthScopeGroups,
+  oauthScopes,
+} = require('@lunch-money/v2-api-spec/oauth-scopes');
+
+const transactionRead = getOAuthScopeDefinition('transactions:read');
+```
+
 ### Using with OpenAPI Tools
 
 ```bash

package/lunch-money-api-v2.yaml

@@ -53,9 +53,11 @@ servers:
 tags:
   - name: me
     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.
+      Use [/me/user/settings](#tag/me/GET/me/user/settings) for user-wide
+      preferences, [/me/account/settings](#tag/me/GET/me/account/settings) for
+      account-wide preferences, and
+      [/me/user/account/settings](#tag/me/GET/me/user/account/settings) for
+      preferences specific to the current user and budgeting account.
   - name: categories
     description: Work with categories
     externalDocs:
@@ -3798,6 +3800,7 @@ components:
         - budget_rollover_left_to_budget
 
     weekStartsOnEnum:
+      x-internal: true
       type: string
       title: week starts on enum
       enum:
@@ -3806,6 +3809,7 @@ components:
       description: The day on which a calendar week begins.
 
     monthYearFormatEnum:
+      x-internal: true
       type: string
       title: month and year format enum
       description: Format string for displaying month and year values
@@ -3832,6 +3836,7 @@ components:
         - "YYYY/MM"
 
     monthDayYearFormatEnum:
+      x-internal: true
       type: string
       title: month, day and year format enum
       description: Format string for displaying full dates in the
@@ -3889,6 +3894,7 @@ components:
         - "M/DD/YYYY"
 
     monthDayFormatEnum:
+      x-internal: true
       type: string
       title: month and day format enum
       description: Format string for displaying month and day values
@@ -3931,6 +3937,98 @@ components:
         - "DD.M"
         - "DD/M"
 
+    localeEnum:
+      type: string
+      title: locale enum
+      description: Locale used for formatting numbers and currency amounts in
+        the Lunch Money app.
+      example: en-US
+      enum:
+        - sq-AL # Albanian (Albania)
+        - be-BY # Belarusian (Belarus)
+        - bg-BG # Bulgarian (Bulgaria)
+        - ca-ES # Catalan (Spain)
+        - zh-CN # Chinese (Simplified) (China)
+        - zh-HK # Chinese (Traditional) (Hong Kong)
+        - zh-TW # Chinese (Traditional) (Taiwan)
+        - hr-HR # Croatian (Croatia)
+        - cs-CZ # Czech (Czech Republic)
+        - da-DK # Danish (Denmark)
+        - nl-BE # Dutch (Belgium)
+        - nl-NL # Dutch (Netherlands)
+        - en-AU # English (Australia)
+        - en-CA # English (Canada)
+        - en-IN # English (India)
+        - en-IE # English (Ireland)
+        - en-MT # English (Malta)
+        - en-NZ # English (New Zealand)
+        - en-PH # English (Philippines)
+        - en-SG # English (Singapore)
+        - en-ZA # English (South Africa)
+        - en-GB # English (United Kingdom)
+        - en-US # English (United States)
+        - et-EE # Estonian (Estonia)
+        - fi-FI # Finnish (Finland)
+        - fr-BE # French (Belgium)
+        - fr-CA # French (Canada)
+        - fr-FR # French (France)
+        - fr-LU # French (Luxembourg)
+        - fr-CH # French (Switzerland)
+        - de-AT # German (Austria)
+        - de-DE # German (Germany)
+        - de-LU # German (Luxembourg)
+        - de-CH # German (Switzerland)
+        - el-CY # Greek (Cyprus)
+        - el-GR # Greek (Greece)
+        - iw-IL # Hebrew (Israel); modern replacement: he-IL
+        - hi-IN # Hindi (India)
+        - hu-HU # Hungarian (Hungary)
+        - is-IS # Icelandic (Iceland)
+        - in-ID # Indonesian (Indonesia); modern replacement: id-ID
+        - ga-IE # Irish (Ireland)
+        - it-IT # Italian (Italy)
+        - it-CH # Italian (Switzerland)
+        - ja-JP # Japanese (Japan)
+        - ko-KR # Korean (South Korea)
+        - lv-LV # Latvian (Latvia)
+        - lt-LT # Lithuanian (Lithuania)
+        - mk-MK # Macedonian (Macedonia)
+        - ms-MY # Malay (Malaysia)
+        - mt-MT # Maltese (Malta)
+        - no-NO # Norwegian (Norway)
+        - pl-PL # Polish (Poland)
+        - pt-BR # Portuguese (Brazil)
+        - pt-PT # Portuguese (Portugal)
+        - ro-RO # Romanian (Romania)
+        - ru-RU # Russian (Russia)
+        - sk-SK # Slovak (Slovakia)
+        - sl-SI # Slovenian (Slovenia)
+        - es-AR # Spanish (Argentina)
+        - es-BO # Spanish (Bolivia)
+        - es-CL # Spanish (Chile)
+        - es-CO # Spanish (Colombia)
+        - es-CR # Spanish (Costa Rica)
+        - es-DO # Spanish (Dominican Republic)
+        - es-EC # Spanish (Ecuador)
+        - es-SV # Spanish (El Salvador)
+        - es-GT # Spanish (Guatemala)
+        - es-HN # Spanish (Honduras)
+        - es-MX # Spanish (Mexico)
+        - es-NI # Spanish (Nicaragua)
+        - es-PA # Spanish (Panama)
+        - es-PY # Spanish (Paraguay)
+        - es-PE # Spanish (Peru)
+        - es-PR # Spanish (Puerto Rico)
+        - es-ES # Spanish (Spain)
+        - es-US # Spanish (United States)
+        - es-UY # Spanish (Uruguay)
+        - es-VE # Spanish (Venezuela)
+        - sv-SE # Swedish (Sweden)
+        - th-TH # Thai (Thailand)
+        - tr-TR # Turkish (Turkey)
+        - uk-UA # Ukrainian (Ukraine)
+        - vi-VN # Vietnamese (Vietnam)
+
     accountSettingsObject:
       type: object
       title: account settings object
@@ -3954,13 +4052,19 @@ components:
           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`).
+          allOf:
+            - $ref: "#/components/schemas/localeEnum"
+          example: en-US
+          description: Locale used for formatting numbers and currency amounts
+            in the Lunch Money app (for example, `en-US`). See
+            [Supported Locales](https://lunchmoney.dev/v2/locales) for accepted
+            values. Date presentation is configured separately through
+            [GET /me/user/settings](#tag/me/GET/me/user/settings) and
+            [PUT /me/user/settings](#tag/me/PUT/me/user/settings). 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
@@ -3971,16 +4075,11 @@ components:
           default: true
           description: If `true`, suggested transaction rules are created
             automatically.
-        auto_review_transaction_on_update:
+        include_pending_in_totals:
           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.
+          description: If `true`, pending transactions are included in account
+            totals.
       required:
         - primary_currency
         - supported_currencies
@@ -3988,13 +4087,13 @@ components:
         - locale
         - auto_create_category_rules
         - auto_create_suggested_transaction_rules
-        - auto_review_transaction_on_update
-        - auto_review_transaction_on_creation
+        - include_pending_in_totals
 
     updateAccountSettingsRequestObject:
       x-internal: true
       type: object
       additionalProperties: false
+      minProperties: 1
       description: Request body for updating account settings. Include at least
         one property to update.
       properties:
@@ -4016,9 +4115,15 @@ components:
           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.
+          allOf:
+            - $ref: "#/components/schemas/localeEnum"
+          example: en-US
+          description: If set, updates the locale used for formatting numbers
+            and currency amounts in the Lunch Money app. See
+            [Supported Locales](https://lunchmoney.dev/v2/locales) for accepted
+            values. Date presentation is configured separately through
+            [GET /me/user/settings](#tag/me/GET/me/user/settings) and
+            [PUT /me/user/settings](#tag/me/PUT/me/user/settings).
           x-updatable: true
         auto_create_category_rules:
           type: boolean
@@ -4030,15 +4135,70 @@ components:
           description: If set, updates whether suggested transaction rules are
             created automatically.
           x-updatable: true
+        include_pending_in_totals:
+          type: boolean
+          description: If set, updates whether pending transactions are included
+            in account totals.
+          x-updatable: true
+
+    userAccountSettingsObject:
+      type: object
+      title: user account settings object
+      additionalProperties: false
+      description: Settings specific to the authorized user within the current
+        budgeting account.
+      properties:
+        auto_review_transaction_on_update:
+          type: boolean
+          default: true
+          description: If `true`, transactions are marked as reviewed when their
+            date, category, payee, amount, account, or notes are changed.
+        auto_review_transaction_on_creation:
+          type: boolean
+          default: true
+          description: If `true`, new manual transactions start as reviewed. If
+            `false`, they start as unreviewed.
+        default_manual_account_id:
+          type: integer
+          nullable: true
+          description: Manual account selected by default when the user creates a
+            manual transaction in the current budgeting account. Must identify a
+            manual account returned by
+            [GET /manual_accounts](#tag/manual_accounts/GET/manual_accounts) for
+            the current budgeting account. Set to `null` to clear the selection.
+      required:
+        - auto_review_transaction_on_update
+        - auto_review_transaction_on_creation
+        - default_manual_account_id
+
+    updateUserAccountSettingsRequestObject:
+      x-internal: true
+      type: object
+      additionalProperties: false
+      minProperties: 1
+      description: Request body for updating settings specific to the authorized
+        user within the current budgeting account. Include at least one property
+        to update.
+      properties:
         auto_review_transaction_on_update:
           type: boolean
           description: If set, updates whether transactions are marked as reviewed
-            when updated.
+            when their date, category, payee, amount, account, or notes are
+            changed.
           x-updatable: true
         auto_review_transaction_on_creation:
           type: boolean
-          description: If set, updates whether transactions are marked as reviewed
-            when created.
+          description: If set, updates whether new manual transactions start as
+            reviewed or unreviewed.
+          x-updatable: true
+        default_manual_account_id:
+          type: integer
+          nullable: true
+          description: If set, updates the manual account selected by default when
+            the user creates a manual transaction in the current budgeting
+            account. Must identify a manual account returned by
+            [GET /manual_accounts](#tag/manual_accounts/GET/manual_accounts) for
+            the current budgeting account. Set to `null` to clear the selection.
           x-updatable: true
 
     userSettingsObject:
@@ -4114,6 +4274,7 @@ components:
       x-internal: true
       type: object
       additionalProperties: false
+      minProperties: 1
       description: Request body for updating user settings. Include at least one
         property to update.
       properties:
@@ -4950,11 +5111,14 @@ paths:
       summary: Get current user
       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.
+        token.<p> Use [/me/user/settings](#tag/me/GET/me/user/settings) for
+        user-wide preferences,
+        [/me/account/settings](#tag/me/GET/me/account/settings) for account-wide
+        preferences, and
+        [/me/user/account/settings](#tag/me/GET/me/user/account/settings) for
+        preferences specific to the current user and budgeting account.
+        Properties such as `primary_currency` and `budget_name` remain on this
+        response for backwards compatibility.
       operationId: getMe
       parameters: []
       responses:
@@ -4983,8 +5147,9 @@ paths:
       tags:
         - me
       summary: Get account settings
-      description: |-
-        Returns account-level settings for the budgeting account associated with the authorized API token.
+      description: >-
+        Returns settings for the current budgeting account. These settings apply
+        regardless of which user is accessing the account.
       operationId: getAccountSettings
       responses:
         "200":
@@ -5003,8 +5168,7 @@ paths:
                 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
+                include_pending_in_totals: true
         "401":
           $ref: "#/components/responses/unauthorizedToken"
         "429":
@@ -5017,11 +5181,10 @@ paths:
       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.
+        associated with the authorized API token. Submit the full response from
+        `GET /me/account/settings` with one or more properties changed, or
+        provide only the properties to update. The request body must include at
+        least one property.
       operationId: updateAccountSettings
       requestBody:
         required: true
@@ -5036,7 +5199,7 @@ paths:
               Update automation preferences:
                 value:
                   auto_create_category_rules: false
-                  auto_review_transaction_on_creation: false
+                  include_pending_in_totals: false
       responses:
         "200":
           description: Account settings updated successfully
@@ -5061,8 +5224,10 @@ paths:
       tags:
         - me
       summary: Get user settings
-      description: |-
-        Returns user-level display and formatting preferences for the user associated with the authorized API token.
+      description: >-
+        Returns display and formatting preferences for the authorized user.
+        These settings apply across every budgeting account the user owns or
+        collaborates on.
       operationId: getUserSettings
       responses:
         "200":
@@ -5093,11 +5258,10 @@ paths:
       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
+        associated with the authorized API token. Submit the full response from
+        `GET /me/user/settings` with one or more properties changed, or provide
+        only the properties to update. The request body must include at least
+        one 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.
@@ -5137,6 +5301,88 @@ paths:
           $ref: "#/components/responses/rateLimited"
         "500":
           $ref: "#/components/responses/serverError"
+  /me/user/account/settings:
+    get:
+      tags:
+        - me
+      summary: Get user account settings
+      description: >-
+        Returns settings specific to the authorized user within the current
+        budgeting account. These settings do not affect other users or the
+        authorized user's settings in other budgeting accounts.
+      operationId: getUserAccountSettings
+      responses:
+        "200":
+          description: Settings for the authorized user in the current budgeting
+            account
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/userAccountSettingsObject"
+              example:
+                auto_review_transaction_on_update: true
+                auto_review_transaction_on_creation: true
+                default_manual_account_id: null
+        "401":
+          $ref: "#/components/responses/unauthorizedToken"
+        "429":
+          $ref: "#/components/responses/rateLimited"
+        "500":
+          $ref: "#/components/responses/serverError"
+    put:
+      tags:
+        - me
+      summary: Update user account settings
+      description: |-
+        Updates settings specific to the authorized user within the current
+        budgeting account. Submit the full response from
+        `GET /me/user/account/settings` with one or more properties changed, or
+        provide only the properties to update. The request body must include at
+        least one property.
+      operationId: updateUserAccountSettings
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/updateUserAccountSettingsRequestObject"
+            examples:
+              Update review preference:
+                value:
+                  auto_review_transaction_on_creation: false
+              Clear default manual account:
+                value:
+                  default_manual_account_id: null
+      responses:
+        "200":
+          description: User account settings updated successfully
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/userAccountSettingsObject"
+              examples:
+                Update review preference:
+                  value:
+                    auto_review_transaction_on_update: true
+                    auto_review_transaction_on_creation: false
+                    default_manual_account_id: null
+                Clear default manual account:
+                  value:
+                    auto_review_transaction_on_update: true
+                    auto_review_transaction_on_creation: true
+                    default_manual_account_id: null
+        "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:

package/oauth-scopes/catalog.d.ts

@@ -0,0 +1,9 @@
+import type { OAuthCatalogDefinition, OAuthCatalogValidationOptions, OAuthCatalogValidationResult, OAuthScopeDefinition, OAuthScopeGroupDefinition, OAuthScopeGroupMatch, OAuthScopeName } from './types';
+export declare const oauthScopes: readonly OAuthScopeDefinition[];
+export declare const oauthScopeGroups: readonly OAuthScopeGroupDefinition[];
+export declare const oauthCatalog: OAuthCatalogDefinition;
+export declare function getOAuthScopeDefinition(name: OAuthScopeName): OAuthScopeDefinition | undefined;
+export declare function getOAuthScopeGroup(id: string): OAuthScopeGroupDefinition | undefined;
+export declare function getOAuthScopeForOperationId(operationId: string): OAuthScopeDefinition | undefined;
+export declare function matchOAuthScopeGroup(scopeNames: readonly OAuthScopeName[]): OAuthScopeGroupMatch;
+export declare function validateOAuthCatalog(definition: OAuthCatalogDefinition, options?: OAuthCatalogValidationOptions): OAuthCatalogValidationResult;

package/oauth-scopes/catalog.js

@@ -0,0 +1,528 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.oauthCatalog = exports.oauthScopeGroups = exports.oauthScopes = void 0;
+exports.getOAuthScopeDefinition = getOAuthScopeDefinition;
+exports.getOAuthScopeGroup = getOAuthScopeGroup;
+exports.getOAuthScopeForOperationId = getOAuthScopeForOperationId;
+exports.matchOAuthScopeGroup = matchOAuthScopeGroup;
+exports.validateOAuthCatalog = validateOAuthCatalog;
+const freezeScope = (scope) => Object.freeze({ ...scope, operationIds: Object.freeze([...scope.operationIds]) });
+const freezeGroup = (group) => Object.freeze({ ...group, scopes: Object.freeze([...group.scopes]) });
+const scopeDefinitions = [
+    {
+        name: 'openid',
+        description: 'Verify your identity with Lunch Money',
+        category: 'identity',
+        operationIds: [],
+        status: 'active',
+    },
+    {
+        name: 'email',
+        description: 'View your email address and whether it has been verified',
+        category: 'identity',
+        operationIds: [],
+        status: 'active',
+    },
+    {
+        name: 'profile',
+        description: 'View your Lunch Money profile information',
+        category: 'identity',
+        operationIds: [],
+        status: 'active',
+    },
+    {
+        name: 'offline_access',
+        description: 'Continue accessing Lunch Money when you are not actively using the app',
+        category: 'offline',
+        operationIds: [],
+        status: 'active',
+    },
+    {
+        name: 'me:read',
+        description: 'View your Lunch Money identity and account, user, and budget settings',
+        category: 'api',
+        operationIds: ['getMe', 'getAccountSettings', 'getUserSettings', 'getUserAccountSettings'],
+        status: 'active',
+    },
+    {
+        name: 'me:update',
+        description: 'Update your Lunch Money account, user, and budget settings',
+        category: 'api',
+        operationIds: ['updateAccountSettings', 'updateUserSettings', 'updateUserAccountSettings'],
+        status: 'active',
+    },
+    {
+        name: 'summary:read',
+        description: 'View your budget summary',
+        category: 'api',
+        operationIds: ['getBudgetSummary'],
+        status: 'active',
+    },
+    {
+        name: 'categories:read',
+        description: 'View categories and category groups',
+        category: 'api',
+        operationIds: ['getAllCategories', 'getCategoryById'],
+        status: 'active',
+    },
+    {
+        name: 'categories:create',
+        description: 'Create categories and category groups',
+        category: 'api',
+        operationIds: ['createCategory'],
+        status: 'active',
+    },
+    {
+        name: 'categories:update',
+        description: 'Update categories and category groups',
+        category: 'api',
+        operationIds: ['updateCategory'],
+        status: 'active',
+    },
+    {
+        name: 'categories:delete',
+        description: 'Delete categories and category groups',
+        category: 'api',
+        operationIds: ['deleteCategory'],
+        status: 'active',
+    },
+    {
+        name: 'crypto_manual:read',
+        description: 'View supported cryptocurrencies and manually managed cryptocurrency balances',
+        category: 'api',
+        operationIds: ['getAllCryptocurrencies', 'getAllCryptoManual', 'getCryptoManualById'],
+        status: 'active',
+    },
+    {
+        name: 'crypto_manual:create',
+        description: 'Add supported cryptocurrencies and create manually managed cryptocurrency balances',
+        category: 'api',
+        operationIds: ['createCryptocurrency', 'createCryptoManual'],
+        status: 'active',
+    },
+    {
+        name: 'crypto_manual:update',
+        description: 'Update manually managed cryptocurrency balances',
+        category: 'api',
+        operationIds: ['updateCryptoManual'],
+        status: 'active',
+    },
+    {
+        name: 'crypto_manual:delete',
+        description: 'Delete manually managed cryptocurrency balances',
+        category: 'api',
+        operationIds: ['deleteCryptoManual'],
+        status: 'active',
+    },
+    {
+        name: 'crypto_synced:read',
+        description: 'View synced cryptocurrency accounts and balances',
+        category: 'api',
+        operationIds: ['getAllCryptoSynced', 'getCryptoSyncedById', 'getCryptoSyncedBalanceBySymbol'],
+        status: 'active',
+    },
+    {
+        name: 'crypto_synced:update',
+        description: 'Refresh balances for synced cryptocurrency accounts',
+        category: 'api',
+        operationIds: ['refreshCryptoSynced'],
+        status: 'active',
+    },
+    {
+        name: 'balance_history:read',
+        description: 'View balance history for accounts and synced cryptocurrency balances',
+        category: 'api',
+        operationIds: ['getBalanceHistory', 'getBalanceHistoryForAccount', 'getBalanceHistoryForCryptoSynced'],
+        status: 'active',
+    },
+    {
+        name: 'balance_history:update',
+        description: 'Create or update balance history and details for deleted accounts',
+        category: 'api',
+        operationIds: ['upsertBalanceHistoryForAccount', 'upsertBalanceHistoryForCryptoSynced', 'updateBalanceHistoryDetails'],
+        status: 'active',
+    },
+    {
+        name: 'balance_history:delete',
+        description: 'Delete balance history for accounts and synced cryptocurrency balances',
+        category: 'api',
+        operationIds: ['deleteBalanceHistoryForAccount', 'deleteBalanceHistoryForCryptoSynced', 'deleteBalanceHistoryEntry'],
+        status: 'active',
+    },
+    {
+        name: 'manual_accounts:read',
+        description: 'View manually managed accounts',
+        category: 'api',
+        operationIds: ['getAllManualAccounts', 'getManualAccountById'],
+        status: 'active',
+    },
+    {
+        name: 'manual_accounts:create',
+        description: 'Create manually managed accounts',
+        category: 'api',
+        operationIds: ['createManualAccount'],
+        status: 'active',
+    },
+    {
+        name: 'manual_accounts:update',
+        description: 'Update manually managed accounts',
+        category: 'api',
+        operationIds: ['updateManualAccount'],
+        status: 'active',
+    },
+    {
+        name: 'manual_accounts:delete',
+        description: 'Delete manually managed accounts',
+        category: 'api',
+        operationIds: ['deleteManualAccount'],
+        status: 'active',
+    },
+    {
+        name: 'plaid_accounts:read',
+        description: 'View accounts connected through Plaid',
+        category: 'api',
+        operationIds: ['getAllPlaidAccounts', 'getPlaidAccountById'],
+        status: 'active',
+    },
+    {
+        name: 'plaid_accounts:update',
+        description: 'Request a Plaid account refresh, which may import new transactions',
+        category: 'api',
+        operationIds: ['triggerPlaidAccountFetch'],
+        status: 'active',
+    },
+    {
+        name: 'transactions:read',
+        description: 'View transactions, including split and group information and attachment metadata',
+        category: 'api',
+        operationIds: ['getAllTransactions', 'getTransactionById'],
+        status: 'active',
+    },
+    {
+        name: 'transactions:create',
+        description: 'Create transactions',
+        category: 'api',
+        operationIds: ['createNewTransactions'],
+        status: 'active',
+    },
+    {
+        name: 'transactions:update',
+        description: 'Update, split, unsplit, group, and ungroup transactions',
+        category: 'api',
+        operationIds: ['updateTransactions', 'updateTransaction', 'groupTransactions', 'ungroupTransactions', 'splitTransaction', 'unsplitTransaction'],
+        status: 'active',
+    },
+    {
+        name: 'transactions:delete',
+        description: 'Delete transactions',
+        category: 'api',
+        operationIds: ['deleteTransactions', 'deleteTransactionById'],
+        status: 'active',
+    },
+    {
+        name: 'transaction_attachments:read',
+        description: 'Get download access to transaction attachments',
+        category: 'api',
+        operationIds: ['getTransactionAttachmentUrl'],
+        status: 'active',
+    },
+    {
+        name: 'transaction_attachments:create',
+        description: 'Attach files to transactions',
+        category: 'api',
+        operationIds: ['attachFileToTransaction'],
+        status: 'active',
+    },
+    {
+        name: 'transaction_attachments:delete',
+        description: 'Delete transaction attachments',
+        category: 'api',
+        operationIds: ['deleteTransactionAttachment'],
+        status: 'active',
+    },
+    {
+        name: 'tags:read',
+        description: 'View tags',
+        category: 'api',
+        operationIds: ['getAllTags', 'getTagById'],
+        status: 'active',
+    },
+    {
+        name: 'tags:create',
+        description: 'Create tags',
+        category: 'api',
+        operationIds: ['createTag'],
+        status: 'active',
+    },
+    {
+        name: 'tags:update',
+        description: 'Update tags',
+        category: 'api',
+        operationIds: ['updateTag'],
+        status: 'active',
+    },
+    {
+        name: 'tags:delete',
+        description: 'Delete tags',
+        category: 'api',
+        operationIds: ['deleteTag'],
+        status: 'active',
+    },
+    {
+        name: 'recurring_items:read',
+        description: 'View recurring items',
+        category: 'api',
+        operationIds: ['getAllRecurring', 'getRecurringById'],
+        status: 'active',
+    },
+    {
+        name: 'budgets:read',
+        description: 'View budget period settings',
+        category: 'api',
+        operationIds: ['getBudgetSettings'],
+        status: 'active',
+    },
+    {
+        name: 'budgets:update',
+        description: 'Create or update budget amounts',
+        category: 'api',
+        operationIds: ['upsertBudget'],
+        status: 'active',
+    },
+    {
+        name: 'budgets:delete',
+        description: 'Delete budget amounts',
+        category: 'api',
+        operationIds: ['deleteBudget'],
+        status: 'active',
+    },
+];
+exports.oauthScopes = Object.freeze(scopeDefinitions.map(freezeScope));
+const allApiReadScopes = exports.oauthScopes
+    .filter((scope) => scope.category === 'api' && scope.name.endsWith(':read'))
+    .map((scope) => scope.name);
+const allApiScopes = exports.oauthScopes
+    .filter((scope) => scope.category === 'api')
+    .map((scope) => scope.name);
+const groupDefinitions = [
+    {
+        id: 'read_only',
+        name: 'Read only',
+        description: 'View all supported Lunch Money data without changing it',
+        scopes: allApiReadScopes,
+    },
+    {
+        id: 'transactions',
+        name: 'Transactions',
+        description: 'Import, export, organize, and manage transactions and their attachments',
+        scopes: [
+            'transactions:read',
+            'transactions:create',
+            'transactions:update',
+            'transactions:delete',
+            'transaction_attachments:read',
+            'transaction_attachments:create',
+            'transaction_attachments:delete',
+            'categories:read',
+            'tags:read',
+            'manual_accounts:read',
+            'plaid_accounts:read',
+            'recurring_items:read',
+        ],
+    },
+    {
+        id: 'budgeting',
+        name: 'Budgeting',
+        description: 'Analyze and manage budgets, categories, and tags',
+        scopes: [
+            'summary:read',
+            'budgets:read',
+            'budgets:update',
+            'budgets:delete',
+            'categories:read',
+            'categories:create',
+            'categories:update',
+            'categories:delete',
+            'tags:read',
+            'tags:create',
+            'tags:update',
+            'tags:delete',
+            'recurring_items:read',
+        ],
+    },
+    {
+        id: 'accounts',
+        name: 'Accounts',
+        description: 'Manage accounts, balances, and balance history',
+        scopes: [
+            'manual_accounts:read',
+            'manual_accounts:create',
+            'manual_accounts:update',
+            'manual_accounts:delete',
+            'plaid_accounts:read',
+            'plaid_accounts:update',
+            'crypto_manual:read',
+            'crypto_manual:create',
+            'crypto_manual:update',
+            'crypto_manual:delete',
+            'crypto_synced:read',
+            'crypto_synced:update',
+            'balance_history:read',
+            'balance_history:update',
+            'balance_history:delete',
+        ],
+    },
+    {
+        id: 'organize',
+        name: 'Organize',
+        description: 'Manage categories and tags used to organize transactions',
+        scopes: [
+            'categories:read',
+            'categories:create',
+            'categories:update',
+            'categories:delete',
+            'tags:read',
+            'tags:create',
+            'tags:update',
+            'tags:delete',
+            'recurring_items:read',
+        ],
+    },
+    {
+        id: 'full_access',
+        name: 'Full access',
+        description: 'View and manage all supported Lunch Money data',
+        scopes: allApiScopes,
+    },
+];
+exports.oauthScopeGroups = Object.freeze(groupDefinitions.map(freezeGroup));
+const scopeByName = new Map(exports.oauthScopes.map((scope) => [scope.name, scope]));
+const groupById = new Map(exports.oauthScopeGroups.map((group) => [group.id, group]));
+const scopeByOperationId = new Map(exports.oauthScopes.flatMap((scope) => scope.operationIds.map((operationId) => [operationId, scope])));
+exports.oauthCatalog = Object.freeze({
+    scopes: exports.oauthScopes,
+    groups: exports.oauthScopeGroups,
+});
+function getOAuthScopeDefinition(name) {
+    return scopeByName.get(name);
+}
+function getOAuthScopeGroup(id) {
+    return groupById.get(id);
+}
+function getOAuthScopeForOperationId(operationId) {
+    return scopeByOperationId.get(operationId);
+}
+const canonicalSet = (values) => [...values].sort().join('\u0000');
+const SCOPE_NAME_PATTERN = /^(?:openid|email|profile|offline_access|[a-z][a-z0-9_]*:(?:read|create|update|delete))$/;
+const GROUP_ID_PATTERN = /^[a-z][a-z0-9_]*$/;
+function matchOAuthScopeGroup(scopeNames) {
+    const names = new Set(scopeNames);
+    if (names.size !== scopeNames.length)
+        return { status: 'no_match', reason: 'duplicate_scope' };
+    if (scopeNames.some((name) => !getOAuthScopeDefinition(name))) {
+        return { status: 'no_match', reason: 'unknown_scope' };
+    }
+    const candidate = canonicalSet(scopeNames);
+    const group = exports.oauthScopeGroups.find((definition) => canonicalSet(definition.scopes) === candidate);
+    return group ? { status: 'matched', group } : { status: 'no_match', reason: 'no_exact_match' };
+}
+function validateOAuthCatalog(definition, options = {}) {
+    const issues = [];
+    const scopeNames = new Set();
+    const groupIds = new Set();
+    const groupSets = new Map();
+    const operationOwners = new Map();
+    definition.scopes.forEach((scope, index) => {
+        const path = `scopes[${index}]`;
+        if (!SCOPE_NAME_PATTERN.test(scope.name)) {
+            issues.push({ code: 'invalid_scope_name', path: `${path}.name`, message: `Invalid scope name: ${scope.name}` });
+        }
+        if (!scope.description.trim()) {
+            issues.push({ code: 'missing_description', path: `${path}.description`, message: `Scope ${scope.name} requires a description` });
+        }
+        if (scopeNames.has(scope.name)) {
+            issues.push({ code: 'duplicate_scope_name', path: `${path}.name`, message: `Duplicate scope name: ${scope.name}` });
+        }
+        scopeNames.add(scope.name);
+        if (!['identity', 'offline', 'api'].includes(scope.category)) {
+            issues.push({ code: 'invalid_category', path: `${path}.category`, message: `Invalid category: ${scope.category}` });
+        }
+        if (!['active', 'deprecated', 'retired'].includes(scope.status)) {
+            issues.push({ code: 'invalid_lifecycle', path: `${path}.status`, message: `Invalid lifecycle: ${scope.status}` });
+        }
+        if (scope.category === 'api' && scope.status !== 'retired' && scope.operationIds.length === 0) {
+            issues.push({ code: 'missing_operation_ids', path: `${path}.operationIds`, message: `API scope ${scope.name} has no operationIds` });
+        }
+        if (scope.category !== 'api' && scope.operationIds.length > 0) {
+            issues.push({ code: 'unexpected_operation_ids', path: `${path}.operationIds`, message: `Protocol scope ${scope.name} cannot own V2 operationIds` });
+        }
+        const localIds = new Set();
+        scope.operationIds.forEach((operationId, operationIndex) => {
+            const operationPath = `${path}.operationIds[${operationIndex}]`;
+            if (localIds.has(operationId)) {
+                issues.push({ code: 'duplicate_operation_id', path: operationPath, message: `Duplicate operationId: ${operationId}` });
+            }
+            localIds.add(operationId);
+            const owner = operationOwners.get(operationId);
+            if (owner && owner !== scope.name) {
+                issues.push({ code: 'conflicting_operation_id', path: operationPath, message: `${operationId} is assigned to both ${owner} and ${scope.name}` });
+            }
+            else {
+                operationOwners.set(operationId, scope.name);
+            }
+            if (options.knownOperationIds && !options.knownOperationIds.has(operationId)) {
+                issues.push({ code: 'unknown_operation_id', path: operationPath, message: `Unknown V2 operationId: ${operationId}` });
+            }
+        });
+    });
+    definition.groups.forEach((group, index) => {
+        const path = `groups[${index}]`;
+        if (!GROUP_ID_PATTERN.test(group.id)) {
+            issues.push({ code: 'invalid_group_id', path: `${path}.id`, message: `Invalid group ID: ${group.id}` });
+        }
+        if (!group.description.trim()) {
+            issues.push({ code: 'missing_description', path: `${path}.description`, message: `Group ${group.id} requires a description` });
+        }
+        if (groupIds.has(group.id)) {
+            issues.push({ code: 'duplicate_group_id', path: `${path}.id`, message: `Duplicate group ID: ${group.id}` });
+        }
+        groupIds.add(group.id);
+        if (group.scopes.length === 0) {
+            issues.push({ code: 'empty_group', path: `${path}.scopes`, message: `Group ${group.id} cannot be empty` });
+        }
+        const members = new Set();
+        group.scopes.forEach((scopeName, scopeIndex) => {
+            const memberPath = `${path}.scopes[${scopeIndex}]`;
+            if (members.has(scopeName)) {
+                issues.push({ code: 'duplicate_group_scope', path: memberPath, message: `Duplicate group scope: ${scopeName}` });
+            }
+            members.add(scopeName);
+            const scope = definition.scopes.find((candidate) => candidate.name === scopeName);
+            if (!scope) {
+                issues.push({ code: 'unknown_group_scope', path: memberPath, message: `Unknown group scope: ${scopeName}` });
+            }
+            else if (scope.status === 'retired') {
+                issues.push({ code: 'retired_group_scope', path: memberPath, message: `Retired scope cannot be grouped: ${scopeName}` });
+            }
+            else if (scope.category === 'offline') {
+                issues.push({ code: 'offline_scope_in_group', path: memberPath, message: `Offline scope cannot be grouped: ${scopeName}` });
+            }
+        });
+        const setKey = canonicalSet(group.scopes);
+        const existingGroup = groupSets.get(setKey);
+        if (existingGroup) {
+            issues.push({ code: 'duplicate_group_members', path: `${path}.scopes`, message: `${group.id} has the same members as ${existingGroup}` });
+        }
+        else {
+            groupSets.set(setKey, group.id);
+        }
+    });
+    if (options.operationIdCoverage === 'require-all-mapped' && options.knownOperationIds) {
+        for (const operationId of options.knownOperationIds) {
+            if (!operationOwners.has(operationId)) {
+                issues.push({ code: 'unmapped_operation_id', path: 'scopes', message: `Unmapped V2 operationId: ${operationId}` });
+            }
+        }
+    }
+    return Object.freeze({ valid: issues.length === 0, issues: Object.freeze(issues) });
+}

package/oauth-scopes/index.d.ts

@@ -0,0 +1,2 @@
+export { getOAuthScopeDefinition, getOAuthScopeForOperationId, getOAuthScopeGroup, matchOAuthScopeGroup, oauthCatalog, oauthScopeGroups, oauthScopes, validateOAuthCatalog, } from './catalog';
+export type { KnownOAuthScopeName, OAuthApiScopeAction, OAuthCatalogDefinition, OAuthCatalogIssue, OAuthCatalogIssueCode, OAuthCatalogValidationOptions, OAuthCatalogValidationResult, OAuthScopeCategory, OAuthScopeDefinition, OAuthScopeGroupDefinition, OAuthScopeGroupMatch, OAuthScopeLifecycle, OAuthScopeName, OAuthScopeResource, } from './types';

package/oauth-scopes/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateOAuthCatalog = exports.oauthScopes = exports.oauthScopeGroups = exports.oauthCatalog = exports.matchOAuthScopeGroup = exports.getOAuthScopeGroup = exports.getOAuthScopeForOperationId = exports.getOAuthScopeDefinition = void 0;
+var catalog_1 = require("./catalog");
+Object.defineProperty(exports, "getOAuthScopeDefinition", { enumerable: true, get: function () { return catalog_1.getOAuthScopeDefinition; } });
+Object.defineProperty(exports, "getOAuthScopeForOperationId", { enumerable: true, get: function () { return catalog_1.getOAuthScopeForOperationId; } });
+Object.defineProperty(exports, "getOAuthScopeGroup", { enumerable: true, get: function () { return catalog_1.getOAuthScopeGroup; } });
+Object.defineProperty(exports, "matchOAuthScopeGroup", { enumerable: true, get: function () { return catalog_1.matchOAuthScopeGroup; } });
+Object.defineProperty(exports, "oauthCatalog", { enumerable: true, get: function () { return catalog_1.oauthCatalog; } });
+Object.defineProperty(exports, "oauthScopeGroups", { enumerable: true, get: function () { return catalog_1.oauthScopeGroups; } });
+Object.defineProperty(exports, "oauthScopes", { enumerable: true, get: function () { return catalog_1.oauthScopes; } });
+Object.defineProperty(exports, "validateOAuthCatalog", { enumerable: true, get: function () { return catalog_1.validateOAuthCatalog; } });

package/oauth-scopes/types.d.ts

@@ -0,0 +1,50 @@
+export type OAuthScopeCategory = 'identity' | 'offline' | 'api';
+export type OAuthScopeLifecycle = 'active' | 'deprecated' | 'retired';
+export type OAuthApiScopeAction = 'read' | 'create' | 'update' | 'delete';
+export type OAuthScopeResource = 'me' | 'summary' | 'categories' | 'crypto_manual' | 'crypto_synced' | 'balance_history' | 'manual_accounts' | 'plaid_accounts' | 'transactions' | 'transaction_attachments' | 'tags' | 'recurring_items' | 'budgets';
+/**
+ * Durable scope names currently recognized by this catalog version.
+ * Persisted and API-facing scope values remain strings so newer names can be
+ * preserved and reported as unknown by consumers with an older catalog.
+ */
+export type KnownOAuthScopeName = 'openid' | 'email' | 'profile' | 'offline_access' | 'me:read' | 'me:update' | 'summary:read' | 'categories:read' | 'categories:create' | 'categories:update' | 'categories:delete' | 'crypto_manual:read' | 'crypto_manual:create' | 'crypto_manual:update' | 'crypto_manual:delete' | 'crypto_synced:read' | 'crypto_synced:update' | 'balance_history:read' | 'balance_history:update' | 'balance_history:delete' | 'manual_accounts:read' | 'manual_accounts:create' | 'manual_accounts:update' | 'manual_accounts:delete' | 'plaid_accounts:read' | 'plaid_accounts:update' | 'transactions:read' | 'transactions:create' | 'transactions:update' | 'transactions:delete' | 'transaction_attachments:read' | 'transaction_attachments:create' | 'transaction_attachments:delete' | 'tags:read' | 'tags:create' | 'tags:update' | 'tags:delete' | 'recurring_items:read' | 'budgets:read' | 'budgets:update' | 'budgets:delete';
+export type OAuthScopeName = string;
+export interface OAuthScopeDefinition {
+    readonly name: KnownOAuthScopeName;
+    readonly description: string;
+    readonly category: OAuthScopeCategory;
+    readonly operationIds: readonly string[];
+    readonly status: OAuthScopeLifecycle;
+    readonly lifecycleNotice?: string;
+}
+export interface OAuthScopeGroupDefinition {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+    readonly scopes: readonly KnownOAuthScopeName[];
+}
+export interface OAuthCatalogDefinition {
+    readonly scopes: readonly OAuthScopeDefinition[];
+    readonly groups: readonly OAuthScopeGroupDefinition[];
+}
+export type OAuthCatalogIssueCode = 'invalid_scope_name' | 'invalid_group_id' | 'missing_description' | 'duplicate_scope_name' | 'duplicate_group_id' | 'duplicate_group_members' | 'duplicate_group_scope' | 'empty_group' | 'invalid_category' | 'invalid_lifecycle' | 'missing_operation_ids' | 'unexpected_operation_ids' | 'duplicate_operation_id' | 'conflicting_operation_id' | 'unknown_group_scope' | 'retired_group_scope' | 'offline_scope_in_group' | 'unknown_operation_id' | 'unmapped_operation_id';
+export interface OAuthCatalogIssue {
+    readonly code: OAuthCatalogIssueCode;
+    readonly path: string;
+    readonly message: string;
+}
+export interface OAuthCatalogValidationOptions {
+    readonly knownOperationIds?: ReadonlySet<string>;
+    readonly operationIdCoverage?: 'allow-unmapped' | 'require-all-mapped';
+}
+export interface OAuthCatalogValidationResult {
+    readonly valid: boolean;
+    readonly issues: readonly OAuthCatalogIssue[];
+}
+export type OAuthScopeGroupMatch = {
+    readonly status: 'matched';
+    readonly group: OAuthScopeGroupDefinition;
+} | {
+    readonly status: 'no_match';
+    readonly reason: 'duplicate_scope' | 'unknown_scope' | 'no_exact_match';
+};

package/oauth-scopes/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,16 +1,31 @@
 {
   "name": "@lunch-money/v2-api-spec",
-  "version": "2.11.1-preview.5",
+  "version": "2.11.1-preview.9",
   "description": "OpenAPI specification and version history for the Lunch Money v2 API",
   "main": "lunch-money-api-v2.yaml",
+  "exports": {
+    ".": "./lunch-money-api-v2.yaml",
+    "./lunch-money-api-v2.yaml": "./lunch-money-api-v2.yaml",
+    "./version-history.md": "./version-history.md",
+    "./oauth-scopes": {
+      "types": "./oauth-scopes/index.d.ts",
+      "require": "./oauth-scopes/index.js",
+      "default": "./oauth-scopes/index.js"
+    },
+    "./package.json": "./package.json",
+    "./*": "./*"
+  },
   "files": [
     "lunch-money-api-v2.yaml",
     "version-history.md",
+    "oauth-scopes",
     "README.md"
   ],
   "scripts": {
     "prepare": "husky install",
-    "prepublishOnly": "node scripts/prep-for-publish.js",
+    "build:oauth-scopes": "tsc -p tsconfig.oauth-scopes.json",
+    "test:oauth-scopes": "npm run build:oauth-scopes && node --test test/oauth-scopes/*.test.js",
+    "prepublishOnly": "npm run build:oauth-scopes && node scripts/prep-for-publish.js",
     "postpublish": "node scripts/restore-readme.js",
     "publish:docs": "node scripts/publish-docs.js --tag preview",
     "publish:spec": "node scripts/publish-spec.js --tag preview",
@@ -30,6 +45,8 @@
   "author": "",
   "license": "ISC",
   "devDependencies": {
-    "husky": "^8.0.3"
+    "husky": "^8.0.3",
+    "typescript": "^5.9.0",
+    "yaml": "^2.8.0"
   }
 }

package/version-history.md

@@ -6,8 +6,13 @@ The Lunch Money API spec uses a modified version of SEMVER for its versioning me
 - 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 the OAuth scope and scope-group catalog mapped to V2 `operationId` values
 - 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
+- Add `GET /me/user/account/settings` and `PUT /me/user/account/settings` for settings specific to a user and budgeting account
+from `GET /me/account/settings` and `PUT /me/account/settings` to `GET /me/user/account/settings` and `PUT /me/user/account/settings`
+- Add `include_pending_in_totals` to `GET /me/account/settings` and `PUT /me/account/settings`
+- Add `default_manual_account_id` to `GET /me/user/account/settings` and `PUT /me/user/account/settings`
 - Document `GET /budgets/settings` response schema publicly; change `budget_period_quantity` to integer
 
 ## v2.11.0 - Jul 31, 2026