@lunch-money/developer-docs 2.11.0-preview.16-no-bh → 2.11.0-preview.18

package/docs/beta-introduction.md

@@ -3,6 +3,7 @@
 - Beta versions of new [v2 API](/v2/docs) endpoints:
   - [/crypto/manual](v2/docs#tag/crypto-manual)
   - [/crypto/synced](v2/docs#tag/crypto-synced)
+  - [/balance/history](v2/docs#tag/balance-history)
 
 
 Feedback is welcome. [Email dev-support@lunchmoney.app](mailto:dev-support@lunchmoney.app) or join us in the [developers channel](https://discord.com/channels/842337014556262411/1134594318414389258) on the [Lunch Money Discord](https://lunchmoney.app/discord).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunch-money/developer-docs",
-  "version": "2.11.0-preview.16-no-bh",
+  "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.