@lunch-money/v2-api-spec 2.10.0-preview.8 → 2.11.0-preview.10

package/package.json

@@ -1,18 +1,25 @@
 {
   "name": "@lunch-money/v2-api-spec",
-  "version": "2.10.0-preview.8",
+  "version": "2.11.0-preview.10",
   "description": "OpenAPI specification and version history for the Lunch Money v2 API",
   "main": "lunch-money-api-v2.yaml",
   "files": [
     "lunch-money-api-v2.yaml",
     "version-history.md",
-    "README.md",
-    "update-urls.sh"
+    "README.md"
   ],
   "scripts": {
     "prepare": "husky install",
     "prepublishOnly": "node scripts/prep-for-publish.js",
-    "postpublish": "node scripts/restore-readme.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",
+    "publish:all": "npm run publish:docs && npm run publish:spec",
+    "publish:docs:latest": "node scripts/publish-docs.js",
+    "publish:spec:latest": "node scripts/publish-spec.js",
+    "publish:all:latest": "npm run publish:docs:latest && npm run publish:spec:latest",
+    "pack:docs": "node scripts/pack-docs.js",
+    "pack:spec": "node scripts/pack-spec.js"
   },
   "keywords": [
     "lunchmoney",
@@ -26,4 +33,3 @@
     "husky": "^8.0.3"
   }
 }
-

package/version-history.md

@@ -5,6 +5,19 @@ 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.0 - TBD
+- Add `GET /balance_history`
+- Add `GET /balance_history/{account_type}/{account_id}`
+- Add `GET /balance_history/crypto_synced/{account_id}/{symbol}`
+- Add `PUT /balance_history/{account_type}/{account_id}`
+- Add `PUT /balance_history/crypto_synced/{account_id}/{symbol}`
+- Add `DELETE /balance_history/entries/{id}`
+- Add `DELETE /balance_history/{account_type}/{account_id}`
+- Add `DELETE /balance_history/crypto_synced/{account_id}/{symbol}`
+- Add `PUT /balance_history/deleted/{account_id}/details`
+- Remove `rollover_pool` from the category object returned in the summary response. It is in the main summary response.
+- It is now possible to set an external_id on any transaction, including those that belong to a Plaid account.
+
 ## v2.10.0 - TBD
 - Add v2 crypto endpoints which support:
   - Discovering the currently supported currencies for manually managed crypto assets
@@ -12,13 +25,17 @@ The Lunch Money API spec uses a modified version of SEMVER for its versioning me
   - Viewing the balances for currencies associated with both manually managed crypto assets and those that are synced via a synced crypto account (ie: coinbase, kraken, ethereum wallet)
   - Refreshing synced crypto account balances
 
+## v2.9.4 - May 23, 2026
+- Increase allowable length for transaction `notes`.
+- Add `clf`, `eth`, and `ves` to the supported currency codes.
+
 ## v2.9.3 - Apr 27, 2026
 - Add `xag` and `xau` to the supported currency codes.
 
 ## v2.9.2 - Apr 22, 2026
-- Increase allowable length for a transaction `payee`
+- Increase allowable length for a transaction `payee`.
 
-## v2.9.1 - Apr, 2026
+## v2.9.1 - Apr 22, 2026
 - You may now set `archived_at` when modifying a category or tag via the `PUT /categories` or `PUT /tags` endpoints.
 
 ## v2.9.0 - Feb 26, 2026

package/README.md.backup

@@ -1,217 +0,0 @@
-# Lunch Money API Specifications and Documentation
-
-This repository contains the official API specifications and documentation for the [Lunch Money](https://lunchmoney.app) API. Lunch Money is a delightfully simple personal finance and budgeting tool with a comprehensive developer API.
-
-## Repository Structure
-
-This repository is organized in a multi-version structure to support current and future API versions:
-
-```
-.
-├── v2/                    # Version 2 API specific content
-│   ├── spec/              # OpenAPI specification (YAML)
-│   ├── docs/              # Version-specific documentation guides
-│   └── images/            # Images used in documentation
-├── docs/                  # Version-independent documentation
-├── scripts/               # Build and publishing scripts
-└── spec/                  # Generated directory (created during npm publish)
-```
-
-### Directory Details
-
-#### `v2/spec/` - OpenAPI Specification
-The OpenAPI 3.0 specification file (`lunch-money-api-v2.yaml`) defines the complete API contract:
-- All available endpoints
-- Request/response schemas
-- Authentication requirements
-- Error responses
-- Example requests and responses
-
-**This is the source of truth for the API.** Changes to the specification automatically update the interactive API documentation.
-
-#### `v2/docs/` - Version-Specific Documentation Guides
-Markdown files containing detailed guides and reference material specific to v2:
-- `intro-to-v2.md` - Overview of the v2 API and key features
-- `migration-guide.md` - Guide for migrating from v1 to v2
-- `version-history.md` - Changelog of all API versions
-
-These guides are written in Markdown and support custom rendering features (see below).
-
-#### `v2/images/` - Documentation Assets
-Images and screenshots used in the documentation guides.
-
-#### `docs/` - Version-Independent Documentation
-Shared documentation that applies across all API versions:
-- `getting-started.md` - Quick start guide for new developers (applies to all API versions)
-- `rate-limiting.md` - Rate limiting policies and best practices (applies to all API versions)
-- Additional version-independent guides (e.g., pagination guidelines, general API concepts)
-
-## OpenAPI Specification vs Documentation Guides
-
-There are two types of content in this repository, each serving a different purpose:
-
-### OpenAPI Specification (`v2/spec/lunch-money-api-v2.yaml`)
-- **Purpose**: Machine-readable API contract
-- **Format**: YAML (OpenAPI 3.0)
-- **Used for**: 
-  - Generating interactive API documentation
-  - Code generation for SDKs and client libraries
-  - API validation and testing
-  - IDE autocomplete and type checking
-- **Editable**: Yes - changes here automatically update the docs
-
-The OpenAPI spec is the authoritative source for:
-- Endpoint definitions (paths, methods, parameters)
-- Request/response schemas
-- Authentication requirements
-- Status codes and error formats
-
-### Documentation Guides (`v2/docs/*.md`)
-- **Purpose**: Human-readable guides and tutorials
-- **Format**: Markdown with custom extensions
-- **Used for**:
-  - Developer onboarding and tutorials
-  - Best practices and patterns
-  - Migration guides and changelogs
-  - Conceptual explanations
-- **Editable**: Yes - written in Markdown with support for custom features
-
-The guides provide context, examples, and explanations that complement the technical specification.
-
-## Custom Markdown Features
-
-The documentation system supports custom rendering features that enhance Markdown files. These features are processed when the documentation is served and can be used in any Markdown file in the `v2/docs/` directory.
-
-### Callouts
-
-Callouts are styled information boxes for highlighting important information, warnings, or tips.
-
-**Syntax:**
-```markdown
-> [!TYPE]
-> Title (optional)
-> 
-> Content goes here. This can span multiple lines
-> and include **markdown formatting**.
-```
-
-**Supported Types:**
-- `[!NOTE]` - General information or notes (blue styling)
-- `[!TIP]` - Helpful tips or best practices (green styling)
-- `[!WARNING]` - Warnings or important cautions (yellow/orange styling)
-
-**Example:**
-```markdown
-> [!NOTE]
-> API Rate Limits
-> 
-> The API has a rate limit of 1000 requests per 5 minutes per IP address.
-```
-
-### Tabs
-
-Tabs organize content into multiple tabbed sections, useful for showing different code examples, API versions, or alternative approaches.
-
-**Syntax:**
-```markdown
-:::tabs
-@tab Tab Label 1
-Content for the first tab. This can include **markdown** and code blocks.
-
-@tab Tab Label 2
-Content for the second tab. You can have as many tabs as needed.
-:::
-```
-
-**Example: Code Examples in Multiple Languages**
-```markdown
-:::tabs
-@tab cURL
-```bash
-curl -X GET "https://api.lunchmoney.app/v2/transactions" \
-  -H "Authorization: Bearer YOUR_API_TOKEN"
-```
-
-@tab JavaScript
-```javascript
-const response = await fetch('https://api.lunchmoney.app/v2/transactions', {
-  headers: {
-    'Authorization': 'Bearer YOUR_API_TOKEN'
-  }
-});
-```
-:::
-```
-
-**Usage Notes:**
-- Each tab must start with `@tab` followed by the tab label
-- The first tab is active by default when the page loads
-- Tab content can include any markdown, including code blocks, lists, callouts, tables, and links
-- You can combine callouts and tabs in various ways
-
-## Versioning
-
-The Lunch Money API uses a modified version of SEMVER:
-
-- **Major version**: The API version (currently 2)
-- **Minor version**: The number of main endpoints (OpenAPI tags) the spec supports
-- **Revision number**: The number of updates since the last endpoint was added
-
-For example, version `2.8.2` means:
-- API version 2
-- 8 main endpoint groups
-- 2 updates since the 8th endpoint was added
-
-Details of each version can be found in [`v2/docs/version-history.md`](./v2/docs/version-history.md).
-
-### Branch Naming Convention
-
-Each API version is maintained on a branch named after the version number (e.g., `v2.8.2`). The `main` branch typically tracks the most recent version.
-
-## Using This Repository
-
-### As an npm Package
-
-This repository is published as `@lunchmoney/v2-api-spec` on npm for lightweight consumption:
-
-```bash
-npm install @lunchmoney/v2-api-spec
-```
-
-After installation, you can access:
-- OpenAPI spec: `node_modules/@lunchmoney/v2-api-spec/spec/lunch-money-api-v2.yaml`
-- Version history: `node_modules/@lunchmoney/v2-api-spec/spec/version-history.md`
-
-### As a Git Repository
-
-You can clone this repository directly:
-
-```bash
-git clone https://github.com/lunch-money/api-specs.git
-cd api-specs
-```
-
-Or add it as a submodule to your project:
-
-```bash
-git submodule add https://github.com/lunch-money/api-specs.git specs/v2
-```
-
-## Contributing
-
-We welcome contributions to improve the API documentation! When contributing:
-
-1. **For API reference changes**: Update the OpenAPI specification in `v2/spec/lunch-money-api-v2.yaml`
-2. **For documentation**: Update the relevant Markdown files in `v2/docs/`
-3. **Version updates**: Update `v2/docs/version-history.md` with your changes
-4. Create a pull request with a clear description of your changes
-
-Please ensure that:
-- OpenAPI spec changes are valid YAML and conform to OpenAPI 3.0
-- Documentation follows the existing style and uses the custom Markdown features appropriately
-
-## Resources
-
-- [Lunch Money Website](https://lunchmoney.app)
-- [Interactive API Documentation](https://alpha.lunchmoney.dev/v2/docs)
-- [API Status](https://status.lunchmoney.app)

package/update-urls.sh

@@ -1,135 +0,0 @@
-#!/bin/bash
-
-# Script to update URLs in the OpenAPI specification file
-# This is useful for switching the docs/mock server URL between local development and production
-# Note: All references to DOCS_DEPLOY_URL throughout the file are toggled; the API server URL remains unchanged
-#
-# Usage:
-#   # In git repo:
-#   ./scripts/update-urls.sh --local|--production
-#   
-#   # In npm package:
-#   ./update-urls.sh --local|--production
-#
-# Flags:
-#   --local       Switch docs/mock server URL to local development (http://localhost:3000/v2)
-#   --production  Switch docs/mock server URL to production deployment URL
-#
-# Environment variables (optional, with defaults):
-#   LOCAL_URL - Local development URL (default: http://localhost:3000/v2)
-#   DOCS_DEPLOY_URL - Docs/mock deployment URL (default: https://alpha.lunchmoney.dev/v2)
-#
-# Examples:
-#   # Switch to production URL (using defaults)
-#   ./update-urls.sh --production
-#
-#   # Switch to production URL (with custom URL)
-#   DOCS_DEPLOY_URL=https://alpha.lunchmoney.dev/v2 ./update-urls.sh --production
-#
-#   # Switch to local URL
-#   ./update-urls.sh --local
-#
-#   # Switch to local URL (with custom local URL)
-#   LOCAL_URL=http://localhost:4000/v2 ./update-urls.sh --local
-
-set -e
-
-# Get the directory where the script is located
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-
-# Determine if we're in the git repo or npm package
-# In git repo: script is in scripts/ subdirectory, spec is in v2/spec/
-# In npm package: script is at root, spec is at root
-if [ -f "$SCRIPT_DIR/../v2/spec/lunch-money-api-v2.yaml" ]; then
-  # In the git repo (script is in scripts/ subdirectory)
-  REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
-  SPEC_FILE="$REPO_ROOT/v2/spec/lunch-money-api-v2.yaml"
-elif [ -f "$SCRIPT_DIR/lunch-money-api-v2.yaml" ]; then
-  # In the npm package (script is at root, spec is in same directory)
-  REPO_ROOT="$SCRIPT_DIR"
-  SPEC_FILE="$REPO_ROOT/lunch-money-api-v2.yaml"
-else
-  echo "Error: Could not find lunch-money-api-v2.yaml"
-  echo "  Looked in: $SCRIPT_DIR/v2/spec/"
-  echo "  Looked in: $SCRIPT_DIR/"
-  exit 1
-fi
-
-# Load environment variables from .env file if it exists and variables are not already set
-if [ -f "$REPO_ROOT/.env" ]; then
-  export $(grep -v '^#' "$REPO_ROOT/.env" | xargs)
-fi
-
-# Set default values for the URLs if not provided
-LOCAL_URL=${LOCAL_URL:-"http://localhost:3000/v2"}
-DOCS_DEPLOY_URL=${DOCS_DEPLOY_URL:-"https://alpha.lunchmoney.dev/v2"}
-
-# Function to show help and exit
-show_help() {
-  echo "Usage: $0 --local|--production"
-  echo ""
-  echo "Flags (required):"
-  echo "  --local       Switch docs/mock server URL to local development"
-  echo "  --production  Switch docs/mock server URL to production deployment"
-  echo ""
-  echo "Environment variables (optional, with defaults):"
-  echo "  LOCAL_URL       Local development URL (default: http://localhost:3000/v2)"
-  echo "  DOCS_DEPLOY_URL Docs/mock deployment URL (default: https://alpha.lunchmoney.dev/v2)"
-  echo ""
-  echo "Examples:"
-  echo "  # Switch to production URL (using defaults)"
-  echo "  $0 --production"
-  echo ""
-  echo "  # Switch to production URL (with custom URL)"
-  echo "  DOCS_DEPLOY_URL=https://alpha.lunchmoney.dev/v2 $0 --production"
-  echo ""
-  echo "  # Switch to local URL"
-  echo "  $0 --local"
-  echo ""
-  echo "  # Switch to local URL (with custom local URL)"
-  echo "  LOCAL_URL=http://localhost:4000/v2 $0 --local"
-  echo ""
-  echo "Note: Environment variables can also be set in a .env file in the repository root."
-  echo "Note: All references to DOCS_DEPLOY_URL throughout the file are updated; the API server URL remains unchanged."
-  exit 1
-}
-
-# Function to replace all occurrences of the docs/mock server URL in the spec file
-replace_docs_url() {
-  local from_url=$1
-  local to_url=$2
-
-  if [ ! -f "$SPEC_FILE" ]; then
-    echo "Error: Spec file not found at $SPEC_FILE"
-    exit 1
-  fi
-
-  echo "Updating all references to docs/mock server URL in $SPEC_FILE..."
-  echo "  From: $from_url"
-  echo "  To: $to_url"
-
-  # Replace all occurrences of the URL throughout the entire file
-  # Using sed with proper escaping for URLs
-  # Escape special regex characters in from_url
-  escaped_from_url=$(echo "$from_url" | sed 's/[[\.*^$()+?{|]/\\&/g')
-  # Use a temporary file for cross-platform compatibility
-  sed "s|$escaped_from_url|$to_url|g" "$SPEC_FILE" > "$SPEC_FILE.tmp" && mv "$SPEC_FILE.tmp" "$SPEC_FILE"
-
-  echo "✓ URLs updated successfully"
-}
-
-# Check for required flag
-if [ "$1" == "--local" ]; then
-  echo "Switching docs/mock server URL to local development..."
-  echo "  Using LOCAL_URL: $LOCAL_URL"
-  replace_docs_url "$DOCS_DEPLOY_URL" "$LOCAL_URL"
-elif [ "$1" == "--production" ]; then
-  echo "Switching docs/mock server URL to production..."
-  echo "  Using DOCS_DEPLOY_URL: $DOCS_DEPLOY_URL"
-  replace_docs_url "$LOCAL_URL" "$DOCS_DEPLOY_URL"
-else
-  echo "Error: A flag is required (--local or --production)"
-  echo ""
-  show_help
-fi
-