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

package/README.md

@@ -1,17 +1,65 @@
 # @lunch-money/developer-docs
 
-Developer documentation content for Lunch Money APIs.
+Documentation content for the [Lunch Money](https://lunchmoney.app) developer APIs —
+the guides, v1/v2 reference docs, images, and doc-routing manifest that power the
+[Lunch Money developer portal](https://lunchmoney.dev).
 
-This package ships the public `developer-docs` repository content directories at the package root:
+Most API consumers want the OpenAPI spec instead: **[`@lunch-money/v2-api-spec`](https://www.npmjs.com/package/@lunch-money/v2-api-spec)**
+is the canonical machine-readable API contract. This package is the human-facing docs
+content, primarily for the docs server that renders the portal.
 
-- `docs/`
-- `v1/`
-- `v2/`
+## What's in the package
 
-The package version tracks the newest API version documented by this content. Server consumers should pin this package explicitly and resolve the package root with:
+Shipped verbatim at the package root:
+
+- `docs/` — version-independent guides (getting started, pagination, rate limiting, …)
+- `v1/` — v1 API reference markdown
+- `v2/` — v2 guides, images, and a **convenience copy** of the OpenAPI YAML under
+  `v2/spec/` (non-canonical; the canonical spec is `@lunch-money/v2-api-spec`)
+- `manifest.json` — doc routes, redirects, and sidebar structure
+
+## Consuming the content
+
+Resolve the package root, then read content files relative to it:
 
 ```js
+const path = require('path');
+const fs = require('fs');
+
 const docsRoot = path.dirname(require.resolve('@lunch-money/developer-docs/package.json'));
+const intro = fs.readFileSync(path.join(docsRoot, 'docs/getting-started.md'), 'utf8');
 ```
 
-The OpenAPI YAML under `v2/spec/` is included as a convenience copy because the docs tree is shipped verbatim. The canonical v2 API specification package is `@lunch-money/v2-api-spec`.
+`manifest.json` describes every page the docs server renders:
+
+```jsonc
+{
+  "pages": [
+    {
+      "path": "/amounts-and-balances",        // canonical URL
+      "file": "docs/amounts-and-balances.md",  // path within this package
+      "title": "Amounts & Balances",
+      "section": "GUIDES",                     // sidebar grouping
+      "type": "markdown",                      // "markdown" | "html" | "v1-slate"
+      "aliases": ["/v2/amounts-and-balances"]  // legacy URLs → 301 to path
+    }
+  ],
+  "redirects": [ /* { from, to, status } */ ],
+  "sidebar": { "docs": [ /* … */ ], "v1": [ /* … */ ] }
+}
+```
+
+## Versioning
+
+The package version tracks the newest API version this content documents (e.g. `2.11.x`
+documents the v2.11 API). Pin an exact version in server deployments so docs are
+deterministic.
+
+## Contributing
+
+Guides, spec, and the routing manifest are edited in the public
+[`developer-docs` repository](https://github.com/lunch-money/developer-docs) — see its
+README for how to add or move a page. This npm package is a published build of that
+content.
+
+_ISC licensed._

package/docs/introduction.md

@@ -2,10 +2,6 @@
 
 Welcome to the Lunch Money developer documentation. This site covers the **v2 API** — the current generation of the Lunch Money API — along with guides, a reference for the legacy v1 API, and tools for exploring the API without touching real data.
 
-> [!WARNING]
-> Alpha Release
-> The v2 API is in open alpha. It is subject to change during this review period and bugs may exist. We strongly encourage using the [mock service](#trying-the-api-without-real-data) or a test budget with sample data as your first step.
-
 ## Getting Started
 
 The v2 API is available at:

package/manifest.json

@@ -0,0 +1,225 @@
+{
+  "$comment": "Doc routing manifest (plans/remove_submodule.md, Phase 2). Pages, redirects, and sidebar for all documentation routes. 'file' paths are relative to the @lunch-money/developer-docs package root. Page 'aliases' are 301 redirects to the page path; 'redirects' entries carry their own status.",
+  "pages": [
+    {
+      "path": "/introduction",
+      "file": "docs/introduction.md",
+      "title": "Introduction",
+      "section": "INTRODUCTION",
+      "type": "markdown",
+      "aliases": ["/v2/introduction"]
+    },
+    {
+      "path": "/getting-started",
+      "file": "docs/getting-started.md",
+      "title": "Getting Started",
+      "section": "GUIDES",
+      "type": "markdown",
+      "aliases": ["/v2/getting-started"]
+    },
+    {
+      "path": "/pagination",
+      "file": "docs/pagination.md",
+      "title": "Pagination",
+      "section": "GUIDES",
+      "type": "markdown",
+      "aliases": ["/v2/pagination"]
+    },
+    {
+      "path": "/rate-limits",
+      "file": "docs/rate-limiting.md",
+      "title": "Rate Limiting",
+      "section": "GUIDES",
+      "type": "markdown",
+      "aliases": ["/v2/rate-limits"]
+    },
+    {
+      "path": "/currencies",
+      "file": "docs/currencies.md",
+      "title": "Supported Currencies",
+      "section": "GUIDES",
+      "type": "markdown",
+      "aliases": ["/v2/currencies"]
+    },
+    {
+      "path": "/amounts-and-balances",
+      "file": "docs/amounts-and-balances.md",
+      "title": "Amounts & Balances",
+      "section": "GUIDES",
+      "type": "markdown",
+      "aliases": ["/v2/amounts-and-balances"]
+    },
+    {
+      "path": "/using-with-ai",
+      "file": "docs/using-with-ai.md",
+      "title": "Using the API with AI",
+      "section": "GUIDES",
+      "type": "markdown",
+      "aliases": ["/v2/using-with-ai"]
+    },
+    {
+      "path": "/v2/overview",
+      "file": "v2/docs/intro-to-v2.md",
+      "title": "v2 API Overview",
+      "section": "REFERENCE",
+      "type": "markdown"
+    },
+    {
+      "path": "/v2/changelog",
+      "file": "v2/docs/version-history.md",
+      "title": "v2 API Changelog",
+      "section": "REFERENCE",
+      "type": "markdown",
+      "aliases": ["/v2/version-history"]
+    },
+    {
+      "path": "/v2/migration-guide",
+      "file": "v2/docs/migration-guide.md",
+      "title": "Migrating v1 to v2",
+      "section": "LEGACY APIs",
+      "type": "markdown"
+    },
+    {
+      "path": "/v2/changelog-visual",
+      "file": "v2/docs/changelog-visual.html",
+      "title": "v2 API Visual Changelog",
+      "section": "REFERENCE",
+      "type": "html"
+    },
+    {
+      "path": "/v1/changelog",
+      "file": "v1/_changelog.md",
+      "title": "v1 Changelog",
+      "section": "V1 API REFERENCE",
+      "type": "v1-slate",
+      "aliases": ["/v1/reference/changelog"]
+    },
+    {
+      "path": "/v1/user",
+      "file": "v1/_user.md",
+      "title": "v1 User",
+      "section": "V1 API REFERENCE",
+      "type": "v1-slate",
+      "aliases": ["/v1/reference/user"]
+    },
+    {
+      "path": "/v1/categories",
+      "file": "v1/_categories.md",
+      "title": "v1 Categories",
+      "section": "V1 API REFERENCE",
+      "type": "v1-slate",
+      "aliases": ["/v1/reference/categories"]
+    },
+    {
+      "path": "/v1/tags",
+      "file": "v1/_tags.md",
+      "title": "v1 Tags",
+      "section": "V1 API REFERENCE",
+      "type": "v1-slate",
+      "aliases": ["/v1/reference/tags"]
+    },
+    {
+      "path": "/v1/transactions",
+      "file": "v1/_transactions.md",
+      "title": "v1 Transactions",
+      "section": "V1 API REFERENCE",
+      "type": "v1-slate",
+      "aliases": ["/v1/reference/transactions"]
+    },
+    {
+      "path": "/v1/recurring-expenses",
+      "file": "v1/_recurring_expenses.md",
+      "title": "v1 Recurring Expenses",
+      "section": "V1 API REFERENCE",
+      "type": "v1-slate",
+      "aliases": ["/v1/reference/recurring-expenses"]
+    },
+    {
+      "path": "/v1/recurring-items",
+      "file": "v1/_recurring_items.md",
+      "title": "v1 Recurring Items",
+      "section": "V1 API REFERENCE",
+      "type": "v1-slate",
+      "aliases": ["/v1/reference/recurring-items"]
+    },
+    {
+      "path": "/v1/budget",
+      "file": "v1/_budget.md",
+      "title": "v1 Budget",
+      "section": "V1 API REFERENCE",
+      "type": "v1-slate",
+      "aliases": ["/v1/reference/budget"]
+    },
+    {
+      "path": "/v1/assets",
+      "file": "v1/_assets.md",
+      "title": "v1 Assets",
+      "section": "V1 API REFERENCE",
+      "type": "v1-slate",
+      "aliases": ["/v1/reference/assets"]
+    },
+    {
+      "path": "/v1/plaid-accounts",
+      "file": "v1/_plaid_accounts.md",
+      "title": "v1 Plaid Accounts",
+      "section": "V1 API REFERENCE",
+      "type": "v1-slate",
+      "aliases": ["/v1/reference/plaid-accounts"]
+    },
+    {
+      "path": "/v1/crypto",
+      "file": "v1/_crypto.md",
+      "title": "v1 Crypto",
+      "section": "V1 API REFERENCE",
+      "type": "v1-slate",
+      "aliases": ["/v1/reference/crypto"]
+    }
+  ],
+  "redirects": [
+    { "from": "/", "to": "/introduction", "status": 302 },
+    { "from": "/v2", "to": "/introduction", "status": 302 },
+    { "from": "/v2/", "to": "/introduction", "status": 302 },
+    { "from": "/v1", "to": "/v1/user", "status": 302 },
+    { "from": "/v1/docs", "to": "/v1/user", "status": 301 }
+  ],
+  "sidebar": {
+    "docs": [
+      { "label": "Introduction", "path": "/introduction" },
+      { "section": "GUIDES", "items": [
+        { "label": "Getting Started", "path": "/getting-started" },
+        { "label": "Amounts & Balances", "path": "/amounts-and-balances" },
+        { "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" }
+      ]},
+      { "section": "REFERENCE", "items": [
+        { "label": "v2 API Overview", "path": "/v2/overview" },
+        { "label": "v2 API Reference", "path": "/v2/docs", "external": true },
+        { "label": "v2 API Changelog", "path": "/v2/changelog" }
+      ]},
+      { "section": "LEGACY APIs", "items": [
+        { "label": "Migrating v1 → v2", "path": "/v2/migration-guide" },
+        { "label": "v1 API Reference", "path": "/v1/user", "external": true },
+        { "label": "v1 API Changelog", "path": "/v1/changelog" },
+        { "label": "Legacy v1 docs", "path": "https://v1.lunchmoney.dev/", "external": true }
+      ]}
+    ],
+    "v1": [
+      { "section": "V1 API REFERENCE", "items": [
+        { "label": "User", "path": "/v1/user" },
+        { "label": "Categories", "path": "/v1/categories" },
+        { "label": "Tags", "path": "/v1/tags" },
+        { "label": "Transactions", "path": "/v1/transactions" },
+        { "label": "Recurring Expenses", "path": "/v1/recurring-expenses" },
+        { "label": "Recurring Items", "path": "/v1/recurring-items" },
+        { "label": "Budget", "path": "/v1/budget" },
+        { "label": "Assets", "path": "/v1/assets" },
+        { "label": "Plaid Accounts", "path": "/v1/plaid-accounts" },
+        { "label": "Crypto", "path": "/v1/crypto" }
+      ]},
+      { "label": "v1 API Changelog", "path": "/v1/changelog" },
+      { "label": "Legacy v1 docs", "path": "https://v1.lunchmoney.dev/", "external": true }
+    ]
+  }
+}

package/package.json

@@ -1,22 +1,25 @@
 {
   "name": "@lunch-money/developer-docs",
-  "version": "2.11.1-preview.1",
+  "version": "2.11.1-preview.3",
   "description": "Developer documentation content for Lunch Money APIs",
   "exports": {
     ".": "./package.json",
+    "./manifest.json": "./manifest.json",
     "./package.json": "./package.json"
   },
   "files": [
     "docs",
     "v1",
     "v2",
+    "manifest.json",
     "README.md"
   ],
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "prepack": "node scripts/prepack.js",
+    "validate:manifest": "node scripts/validate-manifest.js",
+    "prepack": "node scripts/validate-manifest.js && node scripts/prepack.js",
     "postpack": "node scripts/postpack.js"
   },
   "keywords": [

package/v2/spec/lunch-money-api-v2.yaml

@@ -2,17 +2,13 @@ openapi: 3.0.2
 info:
   title: Lunch Money API - v2
   description: |-
-    Welcome to the Lunch Money v2 API reference. This is the **v2.11.1** spec. It includes previews of the proposed `/crypto` and `/balance_history` endpoints. Only the mock service works with these endpoints.<br><br>
-    The most recent stable version of the API is v2.9.4 and is available at:
-    `https://api.lunchmoney.dev/v2`
-
-    ------------------------------------------------------------------------------------------------
+    Welcome to the Lunch Money v2 API reference. This is the **v2.11.1** spec.
 
     ### Introduction
 
-    The API is available at `https://api.lunchmoney.dev/v2`. Get your access token from the [Lunch Money developers page](https://my.lunchmoney.app/developers).
+    The API is available at `https://lunchmoney.dev/v2`. Get your access token from the [Lunch Money developers page](https://my.lunchmoney.app/developers).
 
-    <span class="red-text"><strong>The v2 API is in open alpha and is still subject to change. Use the mock server or a test budget when getting started.</strong></span>
+    API calls can <span class="red-text"><strong>change or delete</strong></span> your data. Any changes you make are <span class="red-text"><strong>permanent</strong></span>, just like they would be if you made changes using the web or mobile app.   Please refer to the [Getting Started Guide](https://lunchmoney.dev/v2/getting-started) before using the API.
 
     **Static Mock Server**
 
@@ -20,19 +16,19 @@ info:
 
     **Client Libraries & SDKs**
 
-    An official TypeScript SDK is available on [NPM](https://www.npmjs.com/package/@lunch-money/v2-api-spec) and [GitHub](https://github.com/lunch-money/lunch-money-js-v2). For Python or other languages, see [lunchmoney-clients](https://github.com/juftin/lunchmoney-clients) or generate a client from this OpenAPI spec.
+    An official TypeScript SDK is available on [NPM](https://www.npmjs.com/package/@lunch-money/v2-api-spec) and [GitHub](https://github.com/lunch-money/lunch-money-js-v2). For Python or other languages, see [lunchmoney-clients](https://github.com/juftin/lunchmoney-clients) or generate a client from [this OpenAPI spec](/v2/openapi).
 
     **Migrating from v1**
 
-    The v2 API is not backwards compatible with v1. See the [Migration Guide](https://alpha.lunchmoney.dev/v2/migration-guide) for details.
+    The v2 API is not backwards compatible with v1. See the [Migration Guide](https://lunchmoney.dev/v2/migration-guide) for details.
 
     **Useful links**
-    - [Developer Portal](https://alpha.lunchmoney.dev/v2/introduction)
-    - [Getting Started Guide](https://alpha.lunchmoney.dev/v2/getting-started)
-    - [v2 API Overview](https://alpha.lunchmoney.dev/v2/overview)
-    - [Version History](https://alpha.lunchmoney.dev/v2/version-history)
-    - [Migration Guide](https://alpha.lunchmoney.dev/v2/migration-guide)
-    - [Rate Limits](https://alpha.lunchmoney.dev/v2/rate-limits)
+    - [Developer Portal](https://lunchmoney.dev/v2/introduction)
+    - [Getting Started Guide](https://lunchmoney.dev/v2/getting-started)
+    - [v2 API Overview](https://lunchmoney.dev/v2/overview)
+    - [Version History](https://lunchmoney.dev/v2/version-history)
+    - [Migration Guide](https://lunchmoney.dev/v2/migration-guide)
+    - [Rate Limits](https://lunchmoney.dev/v2/rate-limits)
   termsOfService: https://lunchmoney.dev/#current-status
   contact:
     email: devsupport@lunchmoney.app
@@ -44,8 +40,8 @@ info:
 servers:
   - url: https://api.lunchmoney.dev/v2
     description: v2 Lunch Money API Server - changes will affect real data!
-#  - url: https://mock.lunchmoney.dev/v2
-  - url: https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/
+#  - url: https://lunchmoney.dev/v2
+  - url: https://lunchmoney.dev/v2
     description: Static mock version of the v2 Lunch Money API Server
 
 tags:
@@ -2946,7 +2942,7 @@ components:
         currency:
           description: Three-letter lowercase currency code of the transaction
             in ISO 4217 format. Must match one of the [supported
-            currencies](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/currencies). If not set
+            currencies](https://lunchmoney.dev/v2/currencies). If not set
             defaults to the user account's primary currency.
           allOf:
             - $ref: "#/components/schemas/currencyEnum"
@@ -9103,19 +9099,19 @@ paths:
           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](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/pagination)
+            [Pagination](https://lunchmoney.dev/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](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/pagination)
+            [Pagination](https://lunchmoney.dev/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](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/pagination)
+            [Pagination](https://lunchmoney.dev/v2/pagination)
           content:
             application/json:
               schema: