@lunch-money/developer-docs 2.11.0-preview.17 → 2.11.0-preview.18

package/package.json

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

package/v2/docs/AGENTS.md

@@ -0,0 +1,48 @@
+# V2 documentation instructions
+
+Follow these rules when editing files under `v2/docs` or documenting changes to `v2/spec/lunch-money-api-v2.yaml`.
+
+## Version history
+
+For every consumer-visible spec change, update `v2/docs/version-history.md` under the version being prepared.
+
+Keep entries brief and high level. The version history records what changed; the OpenAPI endpoint documentation describes how to use it.
+
+Include:
+
+- New, renamed, deprecated, or removed endpoints
+- Changes to path or query parameters
+- Changes to request-body properties
+- Changes to response-body properties or shapes
+- Changed status codes, accepted values, defaults, limits, or validation behavior
+- Breaking changes
+
+Do not include:
+
+- Product or implementation rationale
+- Internal implementation details
+- Detailed usage instructions or examples
+- Full schema descriptions
+- Testing, rollout, or cross-repository implementation details
+- Editorial changes that do not alter the documented API contract
+
+### Style
+
+- Name endpoints using the HTTP method and path, such as `GET /balance_history`.
+- Format endpoints, parameter names, property names, schema names, and literal values with backticks.
+- Start bullets with a present-tense verb such as `Add`, `Change`, `Remove`, `Rename`, or `Deprecate`.
+- Prefer one concise bullet for each logical change.
+- Use nested bullets only to list endpoints or closely related property changes.
+- Do not explain why the change was made or provide instructions for adapting to it.
+- Keep unreleased versions marked `TBD`; do not assign a release date without confirmation.
+- Clearly label breaking changes.
+
+## Other documentation
+
+- Do not routinely update `v2/docs/migration-guide.md` or `v2/docs/intro-to-v2.md` for individual spec changes.
+- Determine whether a spec change makes an existing guide factually incorrect, including guides in the shared `docs` directory.
+- Correct an existing guide when it would otherwise contradict the spec.
+- Consider broader documentation only for a reusable cross-endpoint concept that cannot be documented adequately on the affected endpoints.
+- If broader documentation might be useful but is not required for correctness, identify the candidate page and ask the user before expanding it or adding a page.
+- Prefer endpoint descriptions over general guides for endpoint-specific behavior.
+- Do not add detail to the migration guide merely because V2 differs from V1.

package/v2/docs/version-history.md

@@ -17,6 +17,8 @@ The Lunch Money API spec uses a modified version of SEMVER for its versioning me
 - 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.
+- Manual-account and manually managed crypto create requests now accept `null` for their optional display, institution, and subtype fields, treating `null` the same as omission.
+- Transaction split requests now accept `null` for `category_id` and `notes`. Omission inherits the parent value, while `null` explicitly clears it for the child.
 
 ## v2.10.0 - TBD
 - Add v2 crypto endpoints which support:

package/v2/spec/AGENTS.md

@@ -0,0 +1,75 @@
+# Repository instructions
+
+## V2 OpenAPI conventions
+
+Follow these rules whenever editing `v2/spec/lunch-money-api-v2.yaml`:
+
+### Component schemas
+
+- Define request and response object payloads as named schemas under `components.schemas`.
+- Reference those component schemas from path operations with `$ref`; do not define object payload schemas inline under `paths`.
+- Give every property in a referenced component schema a description, including wrapper properties, nested objects, array properties, and properties whose shape is supplied by `$ref`.
+- Use a property's description to explain its role in the containing object; do not assume the referenced schema's description provides that context.
+- Give every schema displayed in Scalar's Models section a top-level description.
+- A schema hidden from the Models section does not require a top-level description when its purpose is already clear at every reference site. Add one when it defines reusable semantics or constraints not explained by the referencing property, request body, or response.
+- Remove unreferenced component schemas unless they are intentionally retained for a documented reason.
+
+### Scalar model visibility
+
+`x-internal: true` hides a component schema from Scalar's Models section. It does not mean the endpoint, payload, or data is private.
+
+- Keep primary response-body schemas public by omitting `x-internal` or setting it to `false`.
+- Set `x-internal: true` on request-only schemas and supporting schemas that are not useful as independently browsable models.
+- Keep a shared schema public when it is a useful response model, even if requests or other schemas also reference it.
+- Decide visibility from how the schema is used, not from its name.
+
+### Endpoint documentation
+
+- Give every operation a concise `summary` and a `description`.
+- Give every path, query, and header parameter a description.
+- Give every response entry a meaningful description.
+- Document endpoint-specific behavior, defaults, side effects, and request or response semantics on the operation or relevant field rather than in a general guide.
+
+### Description style
+
+- Use direct, neutral, present-tense language from the API consumer's perspective.
+- Use a sentence fragment for a short label or noun phrase, without a terminal period.
+- Use complete sentences for behavior or semantics, with terminal punctuation.
+- When a description contains multiple sentences, punctuate every sentence.
+- Use backticks for property names, parameter names, enum values, and literal values such as `true`, `false`, and `null`.
+- Do not repeat type information unless it clarifies a format, unit, constraint, or semantic detail.
+- Add links when they materially help consumers discover a related endpoint or relevant guide.
+- Do not add links that merely restate obvious navigation.
+
+### Examples
+
+Examples are selective documentation aids, not a required artifact for every spec change.
+
+- Audit affected examples whenever an endpoint, schema, or behavior changes, but edit them only when they become invalid, inaccurate, or misleading.
+- Add an example when it illustrates a new endpoint, a materially different payload shape, or behavior not already clear from the schema and descriptions.
+- Do not add examples mechanically for changes that widen accepted values, such as allowing an optional property to be `null`, when existing examples remain valid and the schema and description explain the behavior.
+- Changes to a type, format, enum, requiredness, default, or representation require examining every affected example. Edit only examples that use or imply the old contract.
+- A new endpoint should normally include a minimal valid request example when it accepts a JSON body and a representative success example when it returns a JSON body. Ask the user before omitting examples when the reason is unclear.
+- When uncertain whether a change benefits from a new example, ask the user rather than adding one speculatively.
+- Put request examples under the request media type, response examples under the applicable status code and media type, and parameter examples on the parameter.
+- Use schema-property examples sparingly for unusual formats or values that are difficult to infer.
+- Use `example` for one representative scenario and `examples` for materially different scenarios.
+- Keep examples concise, fictional, internally consistent, and valid against the applicable schema.
+- Include required properties. Include optional properties only when they help explain the scenario.
+- Give named examples concise, accurate scenario keys. Add a `summary` or `description` only when it contributes information beyond the key and payload.
+- Add endpoint-specific error examples only when the error shape or behavior differs meaningfully from shared standard errors.
+
+#### Paired request and response examples
+
+Pair request and response examples when seeing the result helps explain a synchronous create or update operation.
+
+- Use the same scenario key under the request and corresponding response.
+- Carry submitted values through consistently; use the response to show generated IDs, timestamps, defaults, conversions, inherited values, or other returned fields.
+- Pair invalid request examples with the applicable error response using the same scenario key.
+- Do not pair every request scenario. Add a pair only when the response teaches something useful.
+- Treat singular request and response `example` blocks as an implicit pair and keep shared values consistent.
+- Do not pair examples when the response has no body, processing is asynchronous, or the result does not directly correspond to the submitted payload.
+
+When planning or reviewing a spec change, identify the affected schemas, verify their Scalar visibility and descriptions, and audit related request, response, parameter, and error examples. Record example changes only when existing examples become inaccurate or a new scenario materially improves the documentation. When in doubt, ask the user.
+
+Before finishing a consumer-visible spec change, follow `../docs/AGENTS.md` to add a concise version-history entry and check whether an existing guide has become factually incorrect.

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

@@ -14,11 +14,11 @@ info:
     These docs are interactive — use **Test request** on any endpoint to call the API from this page.
     Choose a LIVE or MOCK service from the Server dropdown.
     Requests sent to `https://api.lunchmoney.dev/v2` can <span class="red-text"><strong>change or delete</strong></span> your data and are <span class="red-text"><strong>permanent</strong></span>.
-    See the [Getting Started Guide](https://lunchmoney.dev/v2/getting-started) before using the live API.
+    See the [Getting Started Guide](http://localhost:3000/v2/getting-started) before using the live API.
     
     **Static mock server**
 
-    Explore without risk to real data. Select `http://mock.lunchmoney.dev/v2` in the Server dropdown to work with static mock data.
+    Explore without risk to real data. Select `http://localhost:3000/v2` in the Server dropdown to work with static mock data.
     POST, PUT, and DELETE requests will return realistic responses, but do not change the mock data.
     
 
@@ -28,14 +28,14 @@ info:
 
     **Migrating from v1**
 
-    The v2 API is not backwards compatible with v1. See the [Migration Guide](https://lunchmoney.dev/v2/migration-guide) for details.
+    The v2 API is not backwards compatible with v1. See the [Migration Guide](http://localhost:3000/v2/migration-guide) for details.
 
     **Useful links**
-    - [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)
+    - [Getting Started Guide](http://localhost:3000/v2/getting-started)
+    - [v2 API Overview](http://localhost:3000/v2/overview)
+    - [Version History](http://localhost:3000/v2/version-history)
+    - [Migration Guide](http://localhost:3000/v2/migration-guide)
+    - [Rate Limits](http://localhost:3000/v2/rate-limits)
   termsOfService: https://lunchmoney.dev/#current-status
   contact:
     email: devsupport@lunchmoney.app
@@ -47,7 +47,7 @@ info:
 servers:
   - url: https://api.lunchmoney.dev/v2
     description: ⚠ LIVE — changes real Lunch Money data
-  - url: http://mock.lunchmoney.dev/v2
+  - url: http://localhost:3000/v2
     description: MOCK — static demo data, no API key required
 
 tags:
@@ -991,16 +991,19 @@ components:
           example: Cold Wallet BTC
         display_name:
           type: string
+          nullable: true
           minLength: 1
           maxLength: 45
-          description: Optional display name for the manual crypto asset. If
-            omitted, clients may derive one from `institution_name` + `name`.
+          description: Display name for the manual crypto asset. If omitted or
+            `null`, clients may derive one from `institution_name` + `name`.
           example: Cold Storage
         institution_name:
           type: string
+          nullable: true
           minLength: 1
           maxLength: 50
-          description: Optional institution or wallet provider display name
+          description: Institution or wallet provider display name. If omitted
+            or `null`, no institution name is set.
           example: Ledger
         balance:
           oneOf:
@@ -1256,15 +1259,19 @@ components:
           example: My Savings Account
         institution_name:
           type: string
+          nullable: true
           example: Bank of the West
-          description: Name of institution holding the manual account
+          description: Name of the institution holding the manual account. If
+            omitted or `null`, no institution name is set.
           minLength: 1
           maxLength: 50
         display_name:
           type: string
-          description: Display name of the manual account as set by user or
-            derived from the `institution_name` and `name` if not explicitly
-            set.<br> This must be unique for the budgeting account.
+          nullable: true
+          description: Display name of the manual account. If omitted or
+            `null`, it is derived from `institution_name` and `name`. An
+            explicitly set display name must be unique for the budgeting
+            account.
           example: Savings
         type:
           description: The type of manual account
@@ -1272,8 +1279,10 @@ components:
             - $ref: "#/components/schemas/accountTypeEnum"
         subtype:
           type: string
-          description: An optional manual account subtype. Examples include<br>
-            - retirement - checking - savings - prepaid credit card
+          nullable: true
+          description: Manual account subtype. If omitted or `null`, no subtype
+            is set. Examples include retirement, checking, savings, and prepaid
+            credit card.
           minLength: 1
           maxLength: 100
           example: prepaid credit card
@@ -3038,7 +3047,7 @@ components:
         currency:
           description: Three-letter lowercase currency code of the transaction
             in ISO 4217 format. Must match one of the [supported
-            currencies](https://lunchmoney.dev/v2/currencies). If not set
+            currencies](http://localhost:3000/v2/currencies). If not set
             defaults to the user account's primary currency.
           allOf:
             - $ref: "#/components/schemas/currencyEnum"
@@ -3394,9 +3403,10 @@ components:
         category_id:
           type: integer
           format: int32
-          description: Unique identifier for associated category_id. Category
-            must already exist for the account. Will inherit category from the
-            parent if not defined.
+          nullable: true
+          description: Category ID for the child transaction. The category must
+            already exist for the account. If omitted, the child inherits the
+            parent category. If `null`, the child has no category.
         tag_ids:
           type: array
           description: The IDs of any tags to apply to this split child
@@ -3406,7 +3416,10 @@ components:
             format: int32
         notes:
           type: string
-          description: Will inherit notes from parent if not defined.
+          nullable: true
+          description: Notes for the child transaction. If omitted, the child
+            inherits the parent notes. If `null` or an empty string, the child
+            has no notes.
       required:
         - amount
 
@@ -8662,19 +8675,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://lunchmoney.dev/v2/pagination)
+            [Pagination](http://localhost:3000/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://lunchmoney.dev/v2/pagination)
+            [Pagination](http://localhost:3000/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://lunchmoney.dev/v2/pagination)
+            [Pagination](http://localhost:3000/v2/pagination)
           content:
             application/json:
               schema: