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

package/docs/pagination.md

@@ -6,10 +6,10 @@ The Lunch Money API uses offset-based pagination for the `GET /transactions` end
 
 When retrieving transactions using `GET /transactions`, the API supports pagination through the `limit` and `offset` query parameters. By default, the endpoint returns up to 1000 transactions per request. If more transactions match your filter criteria, the response includes a `has_more` property set to `true`, indicating that additional pages are available.
 
-> [!NOTE] Pagination Scope
+> [!NOTE] Pagination scope
 > Pagination works with all filter parameters including date ranges, account IDs, categories, tags, and status filters. The pagination applies to the filtered result set.
 
-## How Pagination Works
+## How pagination works
 
 ### Parameters
 
@@ -24,13 +24,13 @@ When retrieving transactions using `GET /transactions`, the API supports paginat
   - Minimum: `0`
   - Use this to fetch subsequent pages of results
 
-### Response Property
+### Response property
 
 - **`has_more`**: A boolean property in the response indicating whether more transactions are available
   - `true`: More transactions match your filter criteria and are available on subsequent pages
   - `false`: All matching transactions have been returned
 
-### Basic Pagination Flow
+### Basic pagination flow
 
 1. Make your first request (optionally with `limit` specified, defaults to 1000)
 2. Check the `has_more` property in the response
@@ -39,7 +39,7 @@ When retrieving transactions using `GET /transactions`, the API supports paginat
 
 ## Examples
 
-### Basic Pagination
+### Basic pagination
 
 Here's how to fetch transactions page by page:
 
@@ -61,10 +61,10 @@ async function getAllTransactions(accessToken, limit = 1000) {
 
     const data = await response.json();
     allTransactions.push(...data.transactions);
-    
+
     hasMore = data.has_more;
     offset += limit;
-    
+
     console.log(`Fetched ${data.transactions.length} transactions (total: ${allTransactions.length})`);
   }
 
@@ -84,22 +84,22 @@ def get_all_transactions(access_token, limit=1000):
     all_transactions = []
     offset = 0
     has_more = True
-    
+
     headers = {
         'Authorization': f'Bearer {access_token}'
     }
-    
+
     while has_more:
         url = f'https://api.lunchmoney.dev/v2/transactions?limit={limit}&offset={offset}'
         response = requests.get(url, headers=headers)
         data = response.json()
-        
+
         all_transactions.extend(data['transactions'])
         has_more = data['has_more']
         offset += limit
-        
+
         print(f"Fetched {len(data['transactions'])} transactions (total: {len(all_transactions)})")
-    
+
     return all_transactions
 
 # Usage
@@ -119,18 +119,18 @@ ALL_TRANSACTIONS="[]"
 
 while [ "$HAS_MORE" = "true" ]; do
   echo "Fetching transactions with offset=$OFFSET, limit=$LIMIT..."
-  
+
   RESPONSE=$(curl -s -X GET \
     "https://api.lunchmoney.dev/v2/transactions?limit=$LIMIT&offset=$OFFSET" \
     -H "Authorization: Bearer $ACCESS_TOKEN")
-  
+
   TRANSACTIONS=$(echo $RESPONSE | jq -r '.transactions')
   HAS_MORE=$(echo $RESPONSE | jq -r '.has_more')
-  
+
   # Merge transactions (simplified - in practice you'd want proper JSON merging)
   COUNT=$(echo $TRANSACTIONS | jq 'length')
   echo "Fetched $COUNT transactions"
-  
+
   OFFSET=$((OFFSET + LIMIT))
 done
 
@@ -138,7 +138,7 @@ echo "All transactions fetched"
 ```
 :::
 
-### Pagination with Date Filters
+### Pagination with date filters
 
 Pagination works seamlessly with date range filters:
 
@@ -166,7 +166,7 @@ async function getTransactionsByDateRange(accessToken, startDate, endDate) {
 
     const data = await response.json();
     allTransactions.push(...data.transactions);
-    
+
     hasMore = data.has_more;
     offset += limit;
   }
@@ -192,9 +192,9 @@ def get_transactions_by_date_range(access_token, start_date, end_date):
     offset = 0
     has_more = True
     limit = 1000
-    
+
     headers = {'Authorization': f'Bearer {access_token}'}
-    
+
     while has_more:
         params = {
             'start_date': start_date,
@@ -202,15 +202,15 @@ def get_transactions_by_date_range(access_token, start_date, end_date):
             'limit': limit,
             'offset': offset
         }
-        
+
         url = f"https://api.lunchmoney.dev/v2/transactions?{urlencode(params)}"
         response = requests.get(url, headers=headers)
         data = response.json()
-        
+
         all_transactions.extend(data['transactions'])
         has_more = data['has_more']
         offset += limit
-    
+
     return all_transactions
 
 # Usage: Get all transactions for January 2024
@@ -236,17 +236,17 @@ while [ "$HAS_MORE" = "true" ]; do
   RESPONSE=$(curl -s -X GET \
     "https://api.lunchmoney.dev/v2/transactions?start_date=$START_DATE&end_date=$END_DATE&limit=$LIMIT&offset=$OFFSET" \
     -H "Authorization: Bearer $ACCESS_TOKEN")
-  
+
   HAS_MORE=$(echo $RESPONSE | jq -r '.has_more')
   COUNT=$(echo $RESPONSE | jq -r '.transactions | length')
   echo "Fetched $COUNT transactions (offset=$OFFSET)"
-  
+
   OFFSET=$((OFFSET + LIMIT))
 done
 ```
 :::
 
-### Handling the `has_more` Flag
+### Handling the `has_more` flag
 
 Always check the `has_more` property to determine if you need to fetch more pages:
 
@@ -262,7 +262,7 @@ async function fetchTransactionsPage(accessToken, limit = 1000, offset = 0) {
   });
 
   const data = await response.json();
-  
+
   return {
     transactions: data.transactions,
     hasMore: data.has_more,
@@ -288,10 +288,10 @@ import requests
 def fetch_transactions_page(access_token, limit=1000, offset=0):
     url = f'https://api.lunchmoney.dev/v2/transactions?limit={limit}&offset={offset}'
     headers = {'Authorization': f'Bearer {access_token}'}
-    
+
     response = requests.get(url, headers=headers)
     data = response.json()
-    
+
     return {
         'transactions': data['transactions'],
         'has_more': data['has_more'],
@@ -335,9 +335,9 @@ fi
 ```
 :::
 
-## Best Practices
+## Best practices
 
-### 1. Use Appropriate Limit Values
+### 1. Use appropriate limit values
 
 Choose a `limit` value that balances performance and number of requests:
 
@@ -353,7 +353,7 @@ const response = await fetch('/v2/transactions?limit=1000');
 const response = await fetch('/v2/transactions?limit=500');
 ```
 
-### 2. Always Check `has_more`
+### 2. Always check `has_more`
 
 Don't assume you've received all results. Always check the `has_more` property:
 
@@ -375,7 +375,7 @@ while (hasMore) {
 }
 ```
 
-### 3. Combine with Date Ranges When Possible
+### 3. Combine with date ranges when possible
 
 If you know the date range you need, use `start_date` and `end_date` parameters to reduce the result set size:
 
@@ -387,12 +387,12 @@ const response = await fetch(
 
 // ❌ Less efficient: Fetches all transactions then filters client-side
 const allTransactions = await fetchAllTransactions();
-const janTransactions = allTransactions.filter(t => 
+const janTransactions = allTransactions.filter(t =>
   t.date >= '2024-01-01' && t.date <= '2024-01-31'
 );
 ```
 
-### 4. Handle Edge Cases
+### 4. Handle edge cases
 
 - **Empty results**: The `transactions` array will be empty, and `has_more` will be `false`
 - **Exact page boundary**: If the number of results is exactly divisible by your limit, `has_more` will be `false` on the last page
@@ -406,24 +406,24 @@ async function safeFetchTransactions(accessToken, limit = 1000, offset = 0) {
       headers: { 'Authorization': `Bearer ${accessToken}` }
     }
   );
-  
+
   if (!response.ok) {
     throw new Error(`API error: ${response.status}`);
   }
-  
+
   const data = await response.json();
-  
+
   // Handle empty results
   if (data.transactions.length === 0 && !data.has_more) {
     console.log('No transactions found');
     return [];
   }
-  
+
   return data;
 }
 ```
 
-### 5. Implement Rate Limit Awareness
+### 5. Implement rate limit awareness
 
 When paginating through many pages, be mindful of rate limits. Consider adding delays between requests:
 
@@ -439,7 +439,7 @@ async function getAllTransactionsWithRateLimit(accessToken) {
     allTransactions.push(...data.transactions);
     hasMore = data.has_more;
     offset += limit;
-    
+
     // Small delay to avoid hitting rate limits
     if (hasMore) {
       await new Promise(resolve => setTimeout(resolve, 100));
@@ -452,7 +452,7 @@ async function getAllTransactionsWithRateLimit(accessToken) {
 
 ## Troubleshooting
 
-### Common Issues
+### Common issues
 
 **Issue**: Getting duplicate transactions across pages
 
@@ -506,7 +506,7 @@ const data = await fetch('/v2/transactions?start_date=2024-01-01&end_date=2024-0
 // data.transactions.length might be 200, and has_more will be false
 ```
 
-## Need Help?
+## Need help?
 
 If you're experiencing pagination issues that can't be resolved through the techniques described above:
 
@@ -514,4 +514,3 @@ If you're experiencing pagination issues that can't be resolved through the tech
 - Verify that you're checking the `has_more` property on each response
 - Consider using date range filters to reduce the result set size
 - [Email our developer advocate](mailto:jp@lunchmoney.app) if you need assistance with pagination implementation
-

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

@@ -41,6 +41,14 @@
       "type": "markdown",
       "aliases": ["/v2/currencies"]
     },
+    {
+      "path": "/locales",
+      "file": "docs/locales.md",
+      "title": "Supported Locales",
+      "section": "GUIDES",
+      "type": "markdown",
+      "aliases": ["/v2/locales"]
+    },
     {
       "path": "/amounts-and-balances",
       "file": "docs/amounts-and-balances.md",
@@ -57,6 +65,14 @@
       "type": "markdown",
       "aliases": ["/v2/using-with-ai"]
     },
+    {
+      "path": "/branding-your-app",
+      "file": "docs/branding-your-app.md",
+      "title": "Branding your App",
+      "section": "GUIDES",
+      "type": "markdown",
+      "aliases": ["/v2/branding-your-app"]
+    },
     {
       "path": "/v2/overview",
       "file": "v2/docs/intro-to-v2.md",
@@ -191,7 +207,9 @@
         { "label": "Pagination", "path": "/pagination" },
         { "label": "Rate Limiting", "path": "/rate-limits" },
         { "label": "Supported Currencies", "path": "/currencies" },
-        { "label": "Using the API with AI", "path": "/using-with-ai" }
+        { "label": "Supported Locales", "path": "/locales" },
+        { "label": "Using the API with AI", "path": "/using-with-ai" },
+        { "label": "Branding your App", "path": "/branding-your-app" }
       ]},
       { "section": "REFERENCE", "items": [
         { "label": "v2 API Overview", "path": "/v2/overview" },

package/package.json

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

package/v1/_user.md

@@ -11,8 +11,8 @@ This API (v1) will not progress to a generally available state. For new projects
 | user_id        | number | false    | Unique identifier for user                                                              |
 | user_name      | string | false    | User's name                                                                             |
 | user_email     | string | false    | User's email                                                                            |
-| account_id     | number | false    | Unique identifier for the associated budgeting account                                  |
-| budget_name    | string | false    | Name of the associated budgeting account                                                |
+| account_id     | number | false    | Unique identifier for the associated budget account                                     |
+| budget_name    | string | false    | Name of the associated budget account                                                   |
 | primary_currency|string | false    | Primary currency from user's settings                                                   |
 | api_key_label  | string | true     | User-defined label of the developer API key used. Returns null if nothing has been set. |