@lunch-money/developer-docs 2.11.1-preview.4 → 2.11.1-preview.6

package/docs/README.md

@@ -5,6 +5,7 @@ This directory contains documentation that applies across all API versions.
 ## Current Documents
 
 - `pagination.md` - Pagination guidelines
+- `branding-your-app.md` - Brand assets and usage guidelines for apps built on Lunch Money
 - (To be added) Other version-independent documentation
 
 ## Version-Specific Documentation

package/docs/beta-introduction.md

@@ -0,0 +1,9 @@
+**Beta Preview Portal** — This developer portal previews planned changes including:
+- Beta versions of new [v2 API](/v2/docs) endpoints:
+  - [GET /me/account/settings](v2/docs#tag/me/GET/me/account/settings)
+  - [PUT /me/account/settings](v2/docs#tag/me/PUT/me/account/settings)
+  - [GET /me/user/settings](v2/docs#tag/me/GET/me/user/settings)
+  - [PUT /me/user/settings](v2/docs#tag/me/PUT/me/user/settings)
+
+
+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/docs/branding-your-app.md

@@ -0,0 +1,64 @@
+# Branding your App
+
+Building a tool, plugin, or integration on top of Lunch Money? Official brand assets and usage guidelines are available so you can credit Lunch Money clearly without reinventing logos or guessing at naming.
+
+Everything lives in the <a href="https://lunchmoney.app/media-kit/" target="_blank" rel="noopener noreferrer">Lunch Money Media Kit</a>. Use that page as the source of truth for downloads, colors, typography, and the latest guidelines.
+
+## What you'll find in the media kit
+
+For developers, the most useful sections are:
+
+- **Logos** — horizontal, two-row, vertical, and emblem variants (PNG)
+- **Powered by** — a lockup and an embeddable badge for crediting Lunch Money in your app or README
+- **Colors & typography** — brand palette and typefaces (primary: Avenir; monospace: Inconsolata)
+- **Usage guidelines** — clear do's and don'ts for how marks may be used
+- **Product screenshots** — optional visuals if you're writing about or promoting an integration
+
+> [!TIP]
+> Prefer the **Powered by** assets when your project connects to Lunch Money. They make the relationship clear without implying that your app *is* Lunch Money.
+
+## Naming
+
+- Refer to the product as **Lunch Money**
+- Refer to the company as **Lunchbag Labs, Inc.** when a legal or company name is needed
+- Link to <a href="https://lunchmoney.app/" target="_blank" rel="noopener noreferrer">lunchmoney.app</a> when you mention the product
+
+Avoid nicknames, abbreviations, or stylized spellings of the product name in user-facing copy.
+
+## Usage guidelines
+
+### Do
+
+- Use official logos without alteration
+- Use the provided **Powered by** lockup or badge when acknowledging Lunch Money
+- Keep enough clear space around logos so they stay readable
+- Download assets from the media kit rather than cropping screenshots of the logo
+
+### Don't
+
+- Stretch, rotate, or recolor logos
+- Add effects, shadows, or outlines to the logo
+- Modify the smiling coin mascot character
+- Imply endorsement, partnership, or official status without permission
+
+> [!NOTE]
+> The Lunch Money name, logo, and mascot character are trademarks of Lunchbag Labs, Inc. All rights reserved.
+
+## Suggested placements
+
+A few common, low-friction ways to brand an integration:
+
+1. **README or docs** — a short "Built with Lunch Money" line plus the Powered by badge linking to <a href="https://lunchmoney.app/" target="_blank" rel="noopener noreferrer">lunchmoney.app</a>
+2. **App footer or about screen** — the Powered by lockup next to your own branding
+3. **Onboarding or connect flow** — official logo when prompting users to authorize or paste an access token
+4. **Community listings** — consistent naming ("My Tool for Lunch Money") so users can find and trust your project
+
+Keep your own product name primary. Lunch Money branding should signal the connection, not compete with your identity.
+
+## Need help?
+
+If you're unsure whether a use is appropriate, or you need a format that isn't in the media kit:
+
+- Start with the <a href="https://lunchmoney.app/media-kit/" target="_blank" rel="noopener noreferrer">Media Kit</a>
+- Ask in the <a href="https://lunchmoney.app/discord" target="_blank" rel="noopener noreferrer">Lunch Money Discord</a> **#developer-api** channel
+- [Email our developer advocate](mailto:jp@lunchmoney.app)

package/manifest.json

@@ -57,6 +57,14 @@
       "type": "markdown",
       "aliases": ["/v2/using-with-ai"]
     },
+    {
+      "path": "/branding-your-app",
+      "file": "docs/branding-your-app.md",
+      "title": "Branding your App",
+      "section": "GUIDES",
+      "type": "markdown",
+      "aliases": ["/v2/branding-your-app"]
+    },
     {
       "path": "/v2/overview",
       "file": "v2/docs/intro-to-v2.md",
@@ -191,7 +199,8 @@
         { "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" }
+        { "label": "Using the API with AI", "path": "/using-with-ai" },
+        { "label": "Branding your App", "path": "/branding-your-app" }
       ]},
       { "section": "REFERENCE", "items": [
         { "label": "v2 API Overview", "path": "/v2/overview" },

package/package.json

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

@@ -10,25 +10,26 @@ The Lunch Money API spec uses a modified version of SEMVER for its versioning me
 - Add `GET /me/user/settings` and `PUT /me/user/settings` for user-level display and formatting preferences
 - Document `GET /budgets/settings` response schema publicly; change `budget_period_quantity` to integer
 
-## 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
-  - Managing the complete lifecycle of manually managed crypto assets (create, read, update, delete)
-  - 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.11.0 - Jul 31, 2026
+- Add `/balance_history` endpoints:
+  - `GET /balance_history`
+  - `GET /balance_history/{account_type}/{account_id}`
+  - `GET /balance_history/crypto_synced/{account_id}/{symbol}`
+  - `PUT /balance_history/{account_type}/{account_id}`
+  - `PUT /balance_history/crypto_synced/{account_id}/{symbol}`
+  - `DELETE /balance_history/entries/{id}`
+  - `DELETE /balance_history/{account_type}/{account_id}`
+  - `DELETE /balance_history/crypto_synced/{account_id}/{symbol}`
+  - `PUT /balance_history/deleted/{account_id}/details`
+- Remove `rollover_pool` from category objects in the `GET /summary` response
+- Allow setting `external_id` on Plaid-account transactions
+- Allow `null` for `category_id` and `notes` on split children to clear those values instead of inheriting from the parent
+
+## v2.10.0 - Jul 31, 2026
+- Add crypto endpoints:
+  - `GET /cryptocurrencies`
+  - `GET /crypto/manual`, `POST /crypto/manual`, `GET /crypto/manual/{id}`, `PUT /crypto/manual/{id}`, `DELETE /crypto/manual/{id}`
+  - `GET /crypto/synced`, `GET /crypto/synced/{id}`, `GET /crypto/synced/{id}/{symbol}`, `POST /crypto/synced/{id}/refresh`
 
 ## v2.9.4 - May 23, 2026
 - Increase allowable length for transaction `notes`.

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.