@lunch-money/v2-api-spec 2.8.2 → 2.8.3

package/lunch-money-api-v2.yaml

@@ -3,16 +3,22 @@ info:
   title: Lunch Money API - v2
   description: |-
     ## Overview
-    Welcome to the Lunch Money v2 API. 
+    Welcome to the documentation for the "next version" of the Lunch Money v2 API. This documentation includes proposed updates to the API design that have not yet been released. <br><br>
+    This documentation is for the **v2.8.3** release of the API. <br> 
+    The latest implementation of the spec is for the **v2.8.1** release and can be found [here](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/). <br><br>
+    Feedback on any of the API design is welcome, but we are particularly interested in getting feedback on most recent changes in the [version history](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/version-history).
+
+    ------------------------------------------------------------------------------------------------
+    Welcome the Lunch Money v2 API.
 
     A working version of this API is now available through these docs, or directly at:
 
-    `https://alpha.lunchmoney.dev/v2`
+    `https://api.lunchmoney.dev/v2`
 
-    **This service has only had internal testing so users are strongly encouraged to create a test budget with example data as the first step to interacting with the v2 API.**
-    See the [Getting Started Guide](https://alpha.lunchmoney.dev/v2/getting-started) for more information.
+    **This service has only had limited external testing so users are strongly encouraged to create a test budget with example data as the first step to interacting with the v2 API.**
+    See the [Getting Started Guide](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/getting-started) for more information.
 
-    If you are new to the v2 API, you may wish to review the [v2 API Overview of Changes](https://alpha.lunchmoney.dev/v2/migration-guide).
+    If you are new to the v2 API, you may wish to review the [v2 API Overview of Changes](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/changelog).
 
     ### Static Mock Server
 
@@ -23,17 +29,17 @@ info:
 
     ### Migrating from V1
 
-    The v2 API is NOT backwards compatible with the v1 API. Developers are encouraged to review the [Migration Guide](https://alpha.lunchmoney.dev/v2/migration-guide) to understand the changes and plan their migration.
+    The v2 API is NOT backwards compatible with the v1 API. Developers are encouraged to review the [Migration Guide](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/migration-guide) to understand the changes and plan their migration.
 
     ### Acknowledgments
 
     If you have been providing feedback on the API during our iterative design process, **THANK YOU**. We are happy to provide the opportunity to finally interact with the working API that was built based on your feedback.
     
     ### Useful links:
-    - [Getting Started](https://alpha.lunchmoney.dev/v2/getting-started)
-    - [v2 API Changelog](https://alpha.lunchmoney.dev/v2/changelog)
-    - [Migration Guide](https://alpha.lunchmoney.dev/v2/migration-guide)
-    - [Rate Limits](https://alpha.lunchmoney.dev/v2/rate-limits)
+    - [Getting Started](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/getting-started)
+    - [v2 API Changelog](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/changelog)
+    - [Migration Guide](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/migration-guide)
+    - [Rate Limits](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/rate-limits)
     - [Current v1 Lunch Money API Documentation](https://lunchmoney.dev)
     - [Awesome Lunch Money Projects](https://github.com/lunch-money/awesome-lunchmoney?tab=readme-ov-file)
   termsOfService: https://lunchmoney.dev/#current-status
@@ -42,12 +48,12 @@ info:
   license:
     name: Apache 2.0
     url: http://www.apache.org/licenses/LICENSE-2.0.html
-  version: 2.8.2
+  version: 2.8.3
 
 servers:
   - url: https://api.lunchmoney.dev/v2
     description: v2 Lunch Money API Server - modifies real data!
-  - url: https://alpha.lunchmoney.dev/v2
+  - url: https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2
     description: Static Mock v2 Lunch Money API Server
 
 tags:
@@ -1144,7 +1150,7 @@ components:
             Positive values indicate a debit transaction, negative values indicate a credit transaction.
         currency:
           description: Three-letter lowercase currency code of the transaction in ISO 4217
-            format. Must match one of the [supported currencies](). If not set
+            format. Must match one of the [supported currencies](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/currencies). If not set
             defaults to the user account's primary currency.
           allOf:
             - $ref: "#/components/schemas/currencyEnum"
@@ -5191,22 +5197,22 @@ paths:
           schema:
             type: integer
             minimum: 1
-            maximum: 1000
-            default: 100
+            maximum: 2000
+            default: 1000
           description: Sets the maximum number of transactions to return. If more match
             the filter criteria, the response will include a `has_more`
-            attribute set to `true`. See [pagination](foo)
+            attribute set to `true`. See [Pagination](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/pagination)
         - name: offset
           in: query
           schema:
             type: integer
           description: Sets the offset for the records returned. This is typically set
-            automatically in the header. See [Pagination](/foo)
+            automatically in the header. See [Pagination](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/pagination)
       responses:
         "200":
           description: Returns an array of transactions. <br><br>The `has_more` property
             is set to `true` if more transactions are available. See
-            [Pagination](/foo)
+            [Pagination](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/pagination)
           content:
             application/json:
               schema:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunch-money/v2-api-spec",
-  "version": "2.8.2",
+  "version": "2.8.3",
   "description": "OpenAPI specification and version history for the Lunch Money v2 API",
   "main": "lunch-money-api-v2.yaml",
   "files": [

package/update-urls.sh

@@ -1,7 +1,8 @@
 #!/bin/bash
 
 # Script to update URLs in the OpenAPI specification file
-# This is useful for switching between local development and production URLs
+# 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:
@@ -11,25 +12,24 @@
 #   ./update-urls.sh --local|--production
 #
 # Flags:
-#   --local       Switch URLs to local development (http://localhost:3000/v2)
-#   --production  Switch URLs to production deployment URLs
+#   --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)
-#   API_DEPLOY_URL - API deployment URL (default: https://api.lunchmoney.app/v2)
-#   DOCS_DEPLOY_URL - Docs/mock deployment URL (default: https://alpha.lunchmoney.app/v2)
+#   DOCS_DEPLOY_URL - Docs/mock deployment URL (default: https://alpha.lunchmoney.dev/v2)
 #
 # Examples:
-#   # Switch to production URLs (using defaults)
+#   # Switch to production URL (using defaults)
 #   ./update-urls.sh --production
 #
-#   # Switch to production URLs (with custom URLs)
-#   API_DEPLOY_URL=https://api.lunchmoney.app/v2 DOCS_DEPLOY_URL=https://alpha.lunchmoney.app/v2 ./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 URLs
+#   # Switch to local URL
 #   ./update-urls.sh --local
 #
-#   # Switch to local URLs (with custom local URL)
+#   # Switch to local URL (with custom local URL)
 #   LOCAL_URL=http://localhost:4000/v2 ./update-urls.sh --local
 
 set -e
@@ -40,7 +40,7 @@ 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
+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"
@@ -62,91 +62,71 @@ fi
 
 # Set default values for the URLs if not provided
 LOCAL_URL=${LOCAL_URL:-"http://localhost:3000/v2"}
-API_DEPLOY_URL=${API_DEPLOY_URL:-"https://api.lunchmoney.app/v2"}
-DOCS_DEPLOY_URL=${DOCS_DEPLOY_URL:-"https://alpha.lunchmoney.app/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 URLs to local development"
-  echo "  --production  Switch URLs to production deployment"
+  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 "  API_DEPLOY_URL  API deployment URL (default: https://api.lunchmoney.app/v2)"
-  echo "  DOCS_DEPLOY_URL Docs/mock deployment URL (default: https://alpha.lunchmoney.app/v2)"
+  echo "  DOCS_DEPLOY_URL Docs/mock deployment URL (default: https://alpha.lunchmoney.dev/v2)"
   echo ""
   echo "Examples:"
-  echo "  # Switch to production URLs (using defaults)"
+  echo "  # Switch to production URL (using defaults)"
   echo "  $0 --production"
   echo ""
-  echo "  # Switch to production URLs (with custom URLs)"
-  echo "  API_DEPLOY_URL=https://api.lunchmoney.app/v2 DOCS_DEPLOY_URL=https://alpha.lunchmoney.app/v2 $0 --production"
+  echo "  # Switch to production URL (with custom URL)"
+  echo "  DOCS_DEPLOY_URL=https://alpha.lunchmoney.dev/v2 $0 --production"
   echo ""
-  echo "  # Switch to local URLs"
+  echo "  # Switch to local URL"
   echo "  $0 --local"
   echo ""
-  echo "  # Switch to local URLs (with custom local URL)"
+  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 URLs in the spec file
-replace_urls() {
+# 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_1=$2
-  local to_url_2=$3
+  local to_url=$2
 
   if [ ! -f "$SPEC_FILE" ]; then
     echo "Error: Spec file not found at $SPEC_FILE"
     exit 1
   fi
 
-  echo "Updating URLs in $SPEC_FILE..."
+  echo "Updating all references to docs/mock server URL in $SPEC_FILE..."
   echo "  From: $from_url"
-  echo "  To (server 1): $to_url_1"
-  echo "  To (server 2): $to_url_2"
+  echo "  To: $to_url"
 
-  # Special handling for lunch-money-api-v2.yaml
-  awk -v from_url="$from_url" -v to_url_1="$to_url_1" -v to_url_2="$to_url_2" '
-  BEGIN { server_count = 0 }
-  {
-    if ($0 ~ "servers:") {
-      in_servers = 1
-    }
-    if (in_servers && $0 ~ "url:") {
-      server_count++
-      if (server_count == 1) {
-        sub(from_url, to_url_1)
-      } else if (server_count == 2) {
-        sub(from_url, to_url_2)
-      } else {
-        sub(from_url, to_url_1)
-      }
-    } else {
-      sub(from_url, to_url_2)
-    }
-    print
-  }' "$SPEC_FILE" > "$SPEC_FILE.tmp" && mv "$SPEC_FILE.tmp" "$SPEC_FILE"
+  # 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 URLs to local development..."
+  echo "Switching docs/mock server URL to local development..."
   echo "  Using LOCAL_URL: $LOCAL_URL"
-  replace_urls "$API_DEPLOY_URL" "$LOCAL_URL" "$LOCAL_URL"
-  replace_urls "$DOCS_DEPLOY_URL" "$LOCAL_URL" "$LOCAL_URL"
+  replace_docs_url "$DOCS_DEPLOY_URL" "$LOCAL_URL"
 elif [ "$1" == "--production" ]; then
-  echo "Switching URLs to production..."
-  echo "  Using API_DEPLOY_URL: $API_DEPLOY_URL"
+  echo "Switching docs/mock server URL to production..."
   echo "  Using DOCS_DEPLOY_URL: $DOCS_DEPLOY_URL"
-  replace_urls "$LOCAL_URL" "$API_DEPLOY_URL" "$DOCS_DEPLOY_URL"
+  replace_docs_url "$LOCAL_URL" "$DOCS_DEPLOY_URL"
 else
   echo "Error: A flag is required (--local or --production)"
   echo ""

package/version-history.md

@@ -5,13 +5,17 @@ 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.8.2 - [Nov 26, 2025]
+## v2.8.3 - Dec 19, 2025
+- The default for the GET /transactions query parameter `limit` has been changed from 100 to 1000.  The max for this parameter is now 2000.
+- Added new guides covering pagination and supported currencies.
+
+## v2.8.2 - Nov 26, 2025
 - The category object now includes both an `order` and `collapsed` property. These properties are used by GUIs that display a list of categories.
 - The DELETE /manual_accounts endpoint now supports two optional query parameters:
   - `delete_items` (boolean, default: false): When set to true, also deletes transactions, rules, and recurring items associated with the account
   - `delete_balance_history` (boolean, default: false): When set to true, deletes balance history associated with the account
 
-## v2.8.1 - November 14, 2025
+## v2.8.1 - Nov 14, 2025
 - Removed `debits_as_negative` from the userObject
   - For api users, positive values always indicate a debit transaction, and negative values indicate a credit transaction.
 - Added `background_color` and `text_color` to the tagObject