@lunch-money/developer-docs 2.11.1-preview.8 → 2.11.2-preview.1

package/docs/rate-limiting.md

@@ -1,4 +1,4 @@
-# Rate Limiting
+# Rate limiting
 
 The Lunch Money API implements rate limiting to ensure fair usage and prevent abuse of API resources. This guide explains how rate limiting works and how to monitor your rate limit status using response headers.
 
@@ -9,20 +9,20 @@ Rate limiting is applied to all requests to the `/v1/` and `/v2/` endpoints and
 
 If you exceed this limit, you will receive a `429 Too Many Requests` response.
 
-> [!NOTE] Rate Limit Scope
+> [!NOTE] Rate limit scope
 > Rate limiting is applied per IP address. Requests from the same IP address share the same rate limit quotas.
 
-## Rate Limit Response
+## Rate limit response
 
 When you exceed a rate limit, the API returns a `429 Too Many Requests` response:
 
-### HTTP Status Code
+### HTTP status code
 
 ```
 429 Too Many Requests
 ```
 
-### Response Body
+### Response body
 
 The response body follows the standard v2 error format:
 
@@ -37,11 +37,11 @@ The response body follows the standard v2 error format:
 }
 ```
 
-### Response Headers
+### Response headers
 
 The API includes rate limit information in response headers for all requests (both successful and rate-limited). You can inspect these headers to monitor your current rate limit status and determine when you can make additional requests.
 
-#### Standard Headers (RFC Draft 7)
+#### Standard headers (RFC Draft 7)
 
 The API includes standard rate limit headers in all responses:
 
@@ -56,12 +56,12 @@ RateLimit-Remaining: 3
 RateLimit-Reset: 1704067200
 ```
 
-#### Legacy Headers
+#### Legacy headers
 
 For backward compatibility, the API also includes legacy `X-RateLimit-*` headers:
 
 - **`X-RateLimit-Limit`**: The maximum number of requests allowed per window
-- **`X-RateLimit-Remaining`**: The number of requests remaining in the current window  
+- **`X-RateLimit-Remaining`**: The number of requests remaining in the current window
 - **`X-RateLimit-Reset`**: The time (in seconds since Unix epoch) when the rate limit window resets
 
 Example headers:
@@ -71,7 +71,7 @@ X-RateLimit-Remaining: 3
 X-RateLimit-Reset: 1704067200
 ```
 
-#### Retry-After Header
+#### `Retry-After` header
 
 When you receive a `429 Too Many Requests` response, the API includes a `Retry-After` header indicating how many seconds you should wait before retrying:
 
@@ -81,12 +81,12 @@ Retry-After: 45
 
 This value represents the time until the rate limit window resets (rounded up to the nearest second).
 
-> [!TIP] Using Retry-After
+> [!TIP] Using `Retry-After`
 > Always respect the `Retry-After` header value when implementing retry logic. Waiting for the specified duration ensures you don't waste requests on premature retries.
 
-## Monitoring Rate Limits
+## Monitoring rate limits
 
-### Reading Rate Limit Headers
+### Reading rate limit headers
 
 You can monitor your rate limit status by inspecting the headers in every API response, even successful ones. This allows you to proactively slow down your request rate before hitting the limit.
 
@@ -95,12 +95,12 @@ You can monitor your rate limit status by inspecting the headers in every API re
 ```javascript
 async function makeRequest(url, options) {
   const response = await fetch(url, options);
-  
+
   // Check rate limit status from headers
   const remaining = parseInt(response.headers.get('X-RateLimit-Remaining') || '0');
   const limit = parseInt(response.headers.get('X-RateLimit-Limit') || '0');
   const resetTime = parseInt(response.headers.get('X-RateLimit-Reset') || '0');
-  
+
   if (remaining < 5) {
     console.warn(`Rate limit warning: ${remaining}/${limit} requests remaining`);
     const waitTime = resetTime - Math.floor(Date.now() / 1000);
@@ -108,13 +108,13 @@ async function makeRequest(url, options) {
       console.log(`Rate limit resets in ${waitTime} seconds`);
     }
   }
-  
+
   if (response.status === 429) {
     const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
     console.error(`Rate limited! Retry after ${retryAfter} seconds`);
     throw new Error(`Rate limited: retry after ${retryAfter}s`);
   }
-  
+
   return response;
 }
 ```
@@ -126,23 +126,23 @@ import time
 
 def make_request(url, headers):
     response = requests.get(url, headers=headers)
-    
+
     # Check rate limit status
     remaining = int(response.headers.get('X-RateLimit-Remaining', 0))
     limit = int(response.headers.get('X-RateLimit-Limit', 0))
     reset_time = int(response.headers.get('X-RateLimit-Reset', 0))
-    
+
     if remaining < 5:
         print(f"Rate limit warning: {remaining}/{limit} requests remaining")
         wait_time = reset_time - int(time.time())
         if wait_time > 0:
             print(f"Rate limit resets in {wait_time} seconds")
-    
+
     if response.status_code == 429:
         retry_after = int(response.headers.get('Retry-After', 60))
         print(f"Rate limited! Retry after {retry_after} seconds")
         raise Exception(f"Rate limited: retry after {retry_after}s")
-    
+
     return response
 ```
 
@@ -150,7 +150,7 @@ def make_request(url, headers):
 ```bash
 # Make a request and capture headers
 response=$(curl -s -D /tmp/headers.txt -o /tmp/body.txt -w "%{http_code}" \
-  -H "Authorization: Bearer YOUR_TOKEN" \
+-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
   "https://api.lunchmoney.dev/v2/me")
 
 # Extract rate limit headers
@@ -170,7 +170,7 @@ fi
 ```
 :::
 
-### Implementing Exponential Backoff
+### Implementing exponential backoff
 
 When you receive a `429` response, implement exponential backoff with jitter to avoid overwhelming the API:
 
@@ -178,28 +178,28 @@ When you receive a `429` response, implement exponential backoff with jitter to
 async function makeRequestWithRetry(url, options, maxRetries = 3) {
   for (let attempt = 0; attempt < maxRetries; attempt++) {
     const response = await fetch(url, options);
-    
+
     if (response.status !== 429) {
       return response;
     }
-    
+
     // Get retry-after header or use exponential backoff
     const retryAfter = parseInt(response.headers.get('Retry-After') || '0');
-    const waitTime = retryAfter > 0 
+    const waitTime = retryAfter > 0
       ? retryAfter * 1000  // Convert seconds to milliseconds
       : Math.min(1000 * Math.pow(2, attempt) + Math.random() * 1000, 30000);
-    
+
     console.log(`Rate limited. Waiting ${waitTime}ms before retry ${attempt + 1}/${maxRetries}`);
     await new Promise(resolve => setTimeout(resolve, waitTime));
   }
-  
+
   throw new Error('Max retries exceeded due to rate limiting');
 }
 ```
 
-## Best Practices
+## Best practices
 
-### 1. Monitor Headers Proactively
+### 1. Monitor headers proactively
 
 Don't wait for a `429` response. Check rate limit headers on every request and adjust your request rate accordingly:
 
@@ -211,7 +211,7 @@ if (remaining < threshold) {
 }
 ```
 
-### 2. Implement Request Queuing
+### 2. Implement request queuing
 
 For applications that need to make many requests, implement a queue system that respects rate limits:
 
@@ -222,14 +222,14 @@ class RateLimitedQueue {
     this.remaining = 100; // Start with max
     this.resetTime = Date.now() + (15 * 60 * 1000);
   }
-  
+
   async enqueue(requestFn) {
     return new Promise((resolve, reject) => {
       this.queue.push({ requestFn, resolve, reject });
       this.processQueue();
     });
   }
-  
+
   async processQueue() {
     if (this.queue.length === 0 || this.remaining <= 0) {
       if (this.remaining <= 0 && this.resetTime > Date.now()) {
@@ -238,15 +238,15 @@ class RateLimitedQueue {
       }
       return;
     }
-    
+
     const { requestFn, resolve, reject } = this.queue.shift();
     try {
       const response = await requestFn();
-      
+
       // Update rate limit status from headers
       this.remaining = parseInt(response.headers.get('X-RateLimit-Remaining') || '0');
       this.resetTime = parseInt(response.headers.get('X-RateLimit-Reset') || '0') * 1000;
-      
+
       resolve(response);
       this.processQueue(); // Process next item
     } catch (error) {
@@ -256,7 +256,7 @@ class RateLimitedQueue {
 }
 ```
 
-### 3. Cache Responses When Possible
+### 3. Cache responses when possible
 
 Reduce the number of API calls by caching responses locally:
 
@@ -267,24 +267,24 @@ const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
 async function getCachedRequest(url, options) {
   const cacheKey = `${url}:${JSON.stringify(options)}`;
   const cached = cache.get(cacheKey);
-  
+
   if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
     return cached.data;
   }
-  
+
   const response = await fetch(url, options);
   const data = await response.json();
-  
+
   cache.set(cacheKey, {
     data,
     timestamp: Date.now()
   });
-  
+
   return data;
 }
 ```
 
-### 4. Batch Operations When Available
+### 4. Batch operations when available
 
 Use bulk endpoints when available to reduce the number of requests:
 
@@ -309,7 +309,7 @@ await fetch('/v2/categories', {
 ```
 :::
 
-### 5. Limit Crypto Refresh Polling
+### 5. Limit crypto refresh polling
 
 Crypto refresh requests can be bursty if you poll too often. For `POST /v2/crypto/synced/{id}/refresh`:
 
@@ -319,14 +319,14 @@ Crypto refresh requests can be bursty if you poll too often. For `POST /v2/crypt
 
 ## Troubleshooting
 
-### Common Issues
+### Common issues
 
 **Issue**: Rate limits resetting unexpectedly
 
 **Solution**: Rate limits are tracked per IP address. If you're behind a proxy or load balancer, multiple clients may share the same IP and exhaust the shared quota.
 
 
-## Need Help?
+## Need help?
 
 If you're experiencing rate limiting issues that can't be resolved through the techniques described above:
 

package/docs/using-with-ai.md

@@ -73,7 +73,7 @@ const token = process.env.LUNCH_MONEY_ACCESS_TOKEN;
 > [!WARNING]
 > Avoid pasting your access token directly into an AI chat window. Treat it like a password — store it in an environment variable, a `.env` file excluded from source control, or your operating system's secret store.
 
-## Best Practices
+## Best practices
 
 1. **Start with a test budget** — API changes are permanent. Use a test budget while you're learning so your real data stays safe. See the [Getting Started guide](/getting-started) for instructions.
 
@@ -97,7 +97,7 @@ If you want to experiment, here are a few low-risk starting points:
 
 Start small, and use a test budget while you're learning.
 
-## Need Help?
+## Need help?
 
 - Join the <a href="https://lunchmoney.app/discord" target="_blank" rel="noopener noreferrer">Lunch Money Discord</a> and ask in the **#developer-api** channel
 - [Email our developer advocate](mailto:jp@lunchmoney.app)

package/manifest.json

@@ -73,6 +73,94 @@
       "type": "markdown",
       "aliases": ["/v2/branding-your-app"]
     },
+    {
+      "path": "/oauth",
+      "file": "docs/oauth/index.md",
+      "title": "OAuth Overview",
+      "section": "OAUTH",
+      "type": "markdown",
+      "aliases": ["/v2/oauth", "/v2/oauth/"]
+    },
+    {
+      "path": "/oauth/concepts",
+      "file": "docs/oauth/concepts.md",
+      "title": "OAuth Concepts",
+      "section": "OAUTH",
+      "type": "markdown",
+      "aliases": ["/v2/oauth/concepts"]
+    },
+    {
+      "path": "/oauth/register-client",
+      "file": "docs/oauth/register-client.md",
+      "title": "Register an OAuth Client",
+      "section": "OAUTH",
+      "type": "markdown",
+      "aliases": ["/v2/oauth/register-client"]
+    },
+    {
+      "path": "/oauth/authorization-code",
+      "file": "docs/oauth/authorization-code.md",
+      "title": "Implement Authorization",
+      "section": "OAUTH",
+      "type": "markdown",
+      "aliases": ["/v2/oauth/authorization-code"]
+    },
+    {
+      "path": "/oauth/development",
+      "file": "docs/oauth/development.md",
+      "title": "Develop and Test",
+      "section": "OAUTH",
+      "type": "markdown",
+      "aliases": ["/v2/oauth/development"]
+    },
+    {
+      "path": "/oauth/tokens",
+      "file": "docs/oauth/tokens.md",
+      "title": "Token Lifecycle",
+      "section": "OAUTH",
+      "type": "markdown",
+      "aliases": ["/v2/oauth/tokens"]
+    },
+    {
+      "path": "/oauth/security",
+      "file": "docs/oauth/security.md",
+      "title": "OAuth Security",
+      "section": "OAUTH",
+      "type": "markdown",
+      "aliases": ["/v2/oauth/security"]
+    },
+    {
+      "path": "/oauth/troubleshooting",
+      "file": "docs/oauth/troubleshooting.md",
+      "title": "Troubleshoot OAuth",
+      "section": "OAUTH",
+      "type": "markdown",
+      "aliases": ["/v2/oauth/troubleshooting"]
+    },
+    {
+      "path": "/oauth/review-and-approval",
+      "file": "docs/oauth/review-and-approval.md",
+      "title": "OAuth Client Review and Approval",
+      "section": "OAUTH",
+      "type": "markdown",
+      "aliases": ["/v2/oauth/review-and-approval"]
+    },
+    {
+      "path": "/oauth/native-apps",
+      "file": "docs/oauth/native-apps.md",
+      "title": "Native Apps",
+      "section": "OAUTH",
+      "type": "markdown",
+      "aliases": ["/v2/oauth/native-apps"]
+    },
+    {
+      "path": "/oauth/scopes",
+      "file": "docs/oauth/scopes.md",
+      "title": "OAuth Scopes",
+      "section": "OAUTH",
+      "type": "markdown",
+      "aliases": ["/v2/oauth/scopes"]
+    },
     {
       "path": "/v2/overview",
       "file": "v2/docs/intro-to-v2.md",
@@ -211,6 +299,19 @@
         { "label": "Using the API with AI", "path": "/using-with-ai" },
         { "label": "Branding your App", "path": "/branding-your-app" }
       ]},
+      { "section": "OAUTH", "collapsed": true, "items": [
+        { "label": "OAuth Overview", "path": "/oauth" },
+        { "label": "Concepts", "path": "/oauth/concepts" },
+        { "label": "Register a Client", "path": "/oauth/register-client" },
+        { "label": "Implement Authorization", "path": "/oauth/authorization-code" },
+        { "label": "Develop and Test", "path": "/oauth/development" },
+        { "label": "Token Lifecycle", "path": "/oauth/tokens" },
+        { "label": "Security", "path": "/oauth/security" },
+        { "label": "Troubleshooting", "path": "/oauth/troubleshooting" },
+        { "label": "Review and Approval", "path": "/oauth/review-and-approval" },
+        { "label": "Native Apps", "path": "/oauth/native-apps" },
+        { "label": "Scope Catalog", "path": "/oauth/scopes" }
+      ]},
       { "section": "REFERENCE", "items": [
         { "label": "v2 API Overview", "path": "/v2/overview" },
         { "label": "v2 API Reference", "path": "/v2/docs", "external": true },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunch-money/developer-docs",
-  "version": "2.11.1-preview.8",
+  "version": "2.11.2-preview.1",
   "description": "Developer documentation content for Lunch Money APIs",
   "exports": {
     ".": "./package.json",
@@ -18,8 +18,8 @@
     "access": "public"
   },
   "scripts": {
-    "validate:manifest": "node scripts/validate-manifest.js",
-    "prepack": "node scripts/validate-manifest.js && node scripts/prepack.js",
+    "validate:manifest": "node ../../scripts/generate-oauth-scope-catalog.js --check && node scripts/validate-manifest.js",
+    "prepack": "node ../../scripts/generate-oauth-scope-catalog.js --check && node scripts/validate-manifest.js && node scripts/prepack.js",
     "postpack": "node scripts/postpack.js"
   },
   "keywords": [

package/v2/docs/intro-to-v2.md

@@ -1,4 +1,4 @@
-# v2 API Overview
+# v2 API overview
 
 Welcome to the Lunch Money v2 API. This page covers the core concepts you need to work with the API effectively — authentication, response shapes, naming conventions, error handling, and more. If you're migrating from v1, see the [Migration Guide](./migration-guide.md).
 
@@ -10,7 +10,7 @@ All API requests require a Bearer token in the `Authorization` header:
 Authorization: Bearer YOUR_ACCESS_TOKEN
 ```
 
-Get your access token from the <a href="https://my.lunchmoney.app/developers" target="_blank" rel="noopener noreferrer">Lunch Money developers page</a>. See the [Getting Started guide](/v2/getting-started) for a step-by-step walkthrough including how to create a test budget.
+Use a personal access token for API exploration or work with your own budgeting account. The [Getting started guide](/getting-started) walks through creating one on the <a href="https://my.lunchmoney.app/developers" target="_blank" rel="noopener noreferrer">Lunch Money Developers page</a> and making your first request. Applications built for other Lunch Money users should use an [OAuth access token issued after the user authorizes the application](/oauth).
 
 ## Base URL
 
@@ -18,7 +18,7 @@ Get your access token from the <a href="https://my.lunchmoney.app/developers" ta
 https://api.lunchmoney.dev/v2
 ```
 
-## Response Shapes
+## Response shapes
 
 The v2 API uses consistent HTTP status codes and response bodies across all endpoints.
 
@@ -39,7 +39,7 @@ All errors return an appropriate 4XX status code — the v2 API never returns an
 | `401` | Unauthorized — missing or invalid Bearer token |
 | `404` | Not Found — the requested object does not exist |
 | `422` | Unprocessable Content — request is valid but cannot be fulfilled (e.g., deleting a category with dependents) |
-| `429` | Too Many Requests — rate limit exceeded; response includes a `Retry-After` header. See the [Rate Limiting guide](/v2/rate-limits). |
+| `429` | Too Many Requests — rate limit exceeded; response includes a `Retry-After` header. See the [Rate limiting guide](/rate-limits). |
 
 All error responses share a consistent body format:
 
@@ -52,7 +52,7 @@ All error responses share a consistent body format:
 }
 ```
 
-> [!NOTE] Atomic Operations
+> [!NOTE] Atomic operations
 > When a request fails, no part of it is applied to your data. For example, if one transaction in a bulk insert has a validation error, none of the transactions in that request are inserted. Fix the errors and retry — you don't need to worry about partial duplicates.
 >
 > If a request has multiple validation errors, the response will attempt to list as many as possible, but it is not guaranteed to catch all errors in a single response.
@@ -61,7 +61,7 @@ All error responses share a consistent body format:
 
 The v2 API validates all requests strictly. A `400` is returned if the request includes unexpected parameters, missing required fields, fields with invalid values, or unexpected properties in the request body. This makes it easier to catch mistakes during development.
 
-## Naming Conventions
+## Naming conventions
 
 Object properties follow consistent rules across the entire API:
 
@@ -72,11 +72,11 @@ Object properties follow consistent rules across the entire API:
 - Child objects of the same type are always in a `children` property
 - All `id` fields are `integer` type (not `number`)
 
-## Amounts, Balances & Sign Convention
+## Amounts, balances & sign convention
 
-The v2 API uses a consistent set of properties — `amount`, `balance`, `currency`, and `to_base` — across all objects that deal with money. See the [Amounts & Balances guide](/v2/amounts-and-balances) for a full explanation of how these properties work, including the sign convention and multi-currency support.
+The v2 API uses a consistent set of properties — `amount`, `balance`, `currency`, and `to_base` — across all objects that deal with money. See the [Amounts & balances guide](/amounts-and-balances) for a full explanation of how these properties work, including the sign convention and multi-currency support.
 
-## Hydrated vs. Non-Hydrated Responses
+## Hydrated vs. non-hydrated responses
 
 In v1, some endpoints returned "hydrated" objects — related object details were embedded directly in the response alongside their IDs. For example, a transaction included `category_name`, `asset_name`, and an array of full tag objects.
 
@@ -93,17 +93,17 @@ In v2, responses are **non-hydrated**: related objects are returned as IDs only.
 
 This improves response times and keeps the API consistent. For apps that need related object details frequently, maintaining a local cache of categories, accounts, and tags is the recommended pattern.
 
-## Updating Objects (PUT)
+## Updating objects (PUT)
 
 Most objects in the v2 API are updatable via `PUT /endpoint/{id}`. The rules are consistent:
 
 - Request bodies may contain any mix of **user-definable** properties (will be updated) and **system-defined** properties like `id` or `created_at` (accepted but ignored).
 - Any unexpected property that is neither user-definable nor system-defined will fail validation and return `400`.
 
-> [!WARNING] Overwrite Behavior
+> [!WARNING] Overwrite behavior
 > Complex properties — objects and arrays — are **replaced entirely** by whatever is in the request body. To add a tag to a transaction without removing existing tags, first fetch the transaction, add the new tag ID to the existing `tag_ids` array, then PUT the full updated array.
 
-> [!TIP] Recommended Pattern
+> [!TIP] Recommended pattern
 > Because system-defined properties are tolerated in PUT requests, you can safely GET an object, modify the properties you want to change, and PUT the whole thing back without stripping system fields first.
 
 ## Versioning

package/v2/docs/migration-guide.md

@@ -99,7 +99,7 @@ One change worth noting: all `id` fields are now explicitly `integer` type (not
 
 #### New Properties
 
-- `debits_as_negative`: A user preference shown in the Lunch Money app. This no longer changes how transaction amounts are represented in the v2 API, but apps may use this setting to display amounts and balances in the way the user prefers. See the [Amounts & Balances guide](/v2/amounts-and-balances) for details.
+- `debits_as_negative`: A user preference shown in the Lunch Money app. This no longer changes how transaction amounts are represented in the v2 API, but apps may use this setting to display amounts and balances in the way the user prefers. See the [Amounts & balances guide](/amounts-and-balances) for details.
 
 <a href="./changelog-visual#user-object-row" target="_blank" rel="noopener noreferrer">View v1/v2 differences</a>
 
@@ -386,7 +386,7 @@ GET /v2/transactions
 > [!WARNING] Behavior Change
 > In the v1 API the optional `debit_as_negative` query parameter could change how transaction amounts were represented. In the v2 API, transaction amount signs are fixed: positive values are debits and negative values are credits. Existing applications that assume positive values are credits need to be updated.
 
-See the [Amounts & Balances guide](/v2/amounts-and-balances) for the full sign convention and how `to_base` works for multi-currency accounts.
+See the [Amounts & balances guide](/amounts-and-balances) for the full sign convention and how `to_base` works for multi-currency accounts.
 
 
 > [!TIP] Migration Tip

package/v2/docs/version-history.md

@@ -5,11 +5,15 @@ 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.2 - TBD
+- Add OAuth 2.0 bearer-token authentication to the v2 API, allowing applications to access Lunch Money on behalf of users who authorize them
+- Enforce required OAuth scopes for every v2 operation and publish the scope and scope-group catalog mapped to V2 `operationId` values
+- Document the OAuth 2.0 authorization-code flow used to obtain access tokens
+
 ## 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
 - 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

package/v2/images/oauth-authorization-flow.svg

@@ -0,0 +1,32 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1120" height="780" viewBox="0 0 1120 780" role="img" aria-labelledby="title desc">
+  <title id="title">Lunch Money OAuth authorization-code flow</title>
+  <desc id="desc">A sequence diagram with three actors: your application, the Lunch Money user, and Lunch Money. The application redirects the user's browser to Lunch Money. When necessary, Lunch Money presents its sign-in screen and the user signs in directly with Lunch Money. Lunch Money then presents the budgeting-account selector and requested permissions, the user selects an account and approves access, Lunch Money returns an authorization code, and the application exchanges it for tokens and calls the API.</desc>
+  <defs>
+    <marker id="app-arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto"><path d="M0,0 L0,6 L9,3 z" fill="#b45309"/></marker>
+    <marker id="user-arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto"><path d="M0,0 L0,6 L9,3 z" fill="#9a6700"/></marker>
+    <marker id="lm-arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto"><path d="M0,0 L0,6 L9,3 z" fill="#0f766e"/></marker>
+  </defs>
+  <style>
+    .actor{stroke-width:2}.app{fill:#ffedd5;stroke:#b45309}.user{fill:#fef3c7;stroke:#9a6700}.lm{fill:#ccfbf1;stroke:#0f766e}
+    .actor-label{font:700 19px system-ui,sans-serif;fill:#172b2a}.actor-detail{font:14px system-ui,sans-serif;fill:#334e4b}
+    .lifeline{stroke:#94a3b8;stroke-width:2;stroke-dasharray:7 7}.flow{stroke-width:2.5;fill:none}.app-flow{stroke:#b45309;marker-end:url(#app-arrow)}.user-flow{stroke:#9a6700;marker-end:url(#user-arrow)}.lm-flow{stroke:#0f766e;marker-end:url(#lm-arrow)}
+    .step-bg{fill:#fff;stroke:#cbd5e1;stroke-width:1}.step{font:600 14px system-ui,sans-serif;fill:#172b2a}
+  </style>
+  <rect class="actor app" x="40" y="25" width="260" height="72" rx="12"/>
+  <text class="actor-label" x="170" y="56" text-anchor="middle">Your application</text><text class="actor-detail" x="170" y="79" text-anchor="middle">browser route and server</text>
+  <rect class="actor user" x="430" y="25" width="260" height="72" rx="12"/>
+  <text class="actor-label" x="560" y="56" text-anchor="middle">Lunch Money user</text><text class="actor-detail" x="560" y="79" text-anchor="middle">browser, sign-in, and approval</text>
+  <rect class="actor lm" x="820" y="25" width="260" height="72" rx="12"/>
+  <text class="actor-label" x="950" y="56" text-anchor="middle">Lunch Money</text><text class="actor-detail" x="950" y="79" text-anchor="middle">authorization server and API</text>
+  <path class="lifeline" d="M170 105 V750"/><path class="lifeline" d="M560 105 V750"/><path class="lifeline" d="M950 105 V750"/>
+  <path class="flow app-flow" d="M170 140 H550"/><rect class="step-bg" x="278" y="118" width="180" height="28" rx="6"/><text class="step" x="368" y="137" text-anchor="middle">1. Redirect the user</text>
+  <path class="flow user-flow" d="M560 200 H940"/><rect class="step-bg" x="652" y="178" width="196" height="28" rx="6"/><text class="step" x="750" y="197" text-anchor="middle">2. Request authorization</text>
+  <path class="flow lm-flow" d="M950 260 H570"/><rect class="step-bg" x="640" y="238" width="240" height="28" rx="6"/><text class="step" x="760" y="257" text-anchor="middle">3. Show sign-in, when needed</text>
+  <path class="flow user-flow" d="M560 320 H940"/><rect class="step-bg" x="605" y="298" width="290" height="28" rx="6"/><text class="step" x="750" y="317" text-anchor="middle">4. Sign in directly with Lunch Money</text>
+  <path class="flow lm-flow" d="M950 380 H570"/><rect class="step-bg" x="590" y="358" width="340" height="28" rx="6"/><text class="step" x="760" y="377" text-anchor="middle">5. Present account and permission choices</text>
+  <path class="flow user-flow" d="M560 440 H940"/><rect class="step-bg" x="585" y="418" width="330" height="28" rx="6"/><text class="step" x="750" y="437" text-anchor="middle">6. Select budgeting account and approve</text>
+  <path class="flow lm-flow" d="M950 500 H180"/><rect class="step-bg" x="385" y="478" width="360" height="28" rx="6"/><text class="step" x="565" y="497" text-anchor="middle">7. Redirect to callback with authorization code</text>
+  <path class="flow app-flow" d="M170 580 H940"/><rect class="step-bg" x="335" y="558" width="460" height="28" rx="6"/><text class="step" x="565" y="577" text-anchor="middle">8. Exchange code with PKCE (+ client secret for confidential client)</text>
+  <path class="flow lm-flow" d="M950 640 H180"/><rect class="step-bg" x="385" y="618" width="360" height="28" rx="6"/><text class="step" x="565" y="637" text-anchor="middle">9. Return access token + optional refresh token</text>
+  <path class="flow app-flow" d="M170 710 H940"/><rect class="step-bg" x="466" y="688" width="198" height="28" rx="6"/><text class="step" x="565" y="707" text-anchor="middle">10. Call the V2 API</text>
+</svg>

package/v2/images/oauth-token-lifecycle.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="990" height="300" viewBox="0 0 990 300" role="img" aria-labelledby="title desc">
+  <title id="title">OAuth token lifecycle and recovery</title>
+  <desc id="desc">Authorization yields a short-lived access token and, when offline access applies, a finite refresh token. Refresh replaces tokens. Expiration, revocation, or a terminal refresh failure leads to fresh authorization.</desc>
+  <defs><marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto"><path d="M0,0 L0,6 L9,3 z" fill="#0f766e"/></marker></defs>
+  <style>.box{fill:#f0f9f8;stroke:#2a6b64;stroke-width:2}.warn{fill:#fff4dc;stroke:#9a6a16;stroke-width:2}.label{font:600 17px system-ui,sans-serif;fill:#173f3b}.small{font:14px system-ui,sans-serif;fill:#294744}.line{stroke:#0f766e;stroke-width:2.5;fill:none;marker-end:url(#arrow)}.annotation-bg{fill:#fff;stroke:#cbd5e1;stroke-width:1}.annotation{font:600 14px system-ui,sans-serif;fill:#172b2a}</style>
+  <rect class="box" x="35" y="65" width="180" height="70" rx="12"/><text class="label" x="125" y="94" text-anchor="middle">Authorization</text><text class="small" x="125" y="117" text-anchor="middle">user present</text>
+  <rect class="box" x="300" y="35" width="200" height="70" rx="12"/><text class="label" x="400" y="64" text-anchor="middle">Access token</text><text class="small" x="400" y="87" text-anchor="middle">short-lived</text>
+  <rect class="box" x="300" y="165" width="200" height="70" rx="12"/><text class="label" x="400" y="194" text-anchor="middle">Refresh token</text><text class="small" x="400" y="217" text-anchor="middle">finite; offline_access</text>
+  <rect class="box" x="590" y="100" width="170" height="70" rx="12"/><text class="label" x="675" y="129" text-anchor="middle">Refresh</text><text class="small" x="675" y="152" text-anchor="middle">store replacements</text>
+  <rect class="warn" x="790" y="100" width="140" height="70" rx="12"/><text class="label" x="860" y="129" text-anchor="middle">Terminal failure</text><text class="small" x="860" y="152" text-anchor="middle">reauthorize</text>
+  <path class="line" d="M215 88 L290 72"/><path class="line" d="M215 112 L290 185"/><path class="line" d="M500 200 L580 150"/><path class="line" d="M760 135 H780"/><path class="line" d="M675 95 C675 25 500 15 470 35"/>
+  <rect class="annotation-bg" x="530" y="10" width="170" height="28" rx="6"/><text class="annotation" x="615" y="29" text-anchor="middle">replacement token set</text>
+  <rect class="annotation-bg" x="740" y="198" width="240" height="36" rx="6"/><text class="annotation" x="860" y="221" text-anchor="middle">expired, revoked, or rejected</text>
+</svg>