@lunch-money/v2-api-spec 2.8.2

package/README.md

@@ -0,0 +1,136 @@
+# @lunch-money/v2-api-spec
+
+OpenAPI specification and version history for the Lunch Money v2 API.
+
+## Installation
+
+```bash
+npm install @lunch-money/v2-api-spec
+```
+
+## Contents
+
+After installation, the package provides:
+
+- **OpenAPI Specification**: `node_modules/@lunch-money/v2-api-spec/lunch-money-api-v2.yaml`
+- **Version History**: `node_modules/@lunch-money/v2-api-spec/version-history.md`
+
+## Usage
+
+### Accessing the OpenAPI Specification
+
+```javascript
+const fs = require('fs');
+const path = require('path');
+
+const specPath = path.join(
+  __dirname,
+  'node_modules/@lunch-money/v2-api-spec/lunch-money-api-v2.yaml'
+);
+const spec = fs.readFileSync(specPath, 'utf8');
+```
+
+### Using with OpenAPI Tools
+
+```bash
+# Generate TypeScript types
+npx @openapitools/openapi-generator-cli generate \
+  -i node_modules/@lunch-money/v2-api-spec/lunch-money-api-v2.yaml \
+  -g typescript-axios \
+  -o ./generated
+
+# Validate the spec
+npx swagger-cli validate node_modules/@lunch-money/v2-api-spec/lunch-money-api-v2.yaml
+```
+
+### Updating URLs for Local Development
+
+The package includes a script to help switch between local and production URLs in the OpenAPI specification. This is useful when developing against a local server.
+
+#### Using the Script
+
+The script is located at `node_modules/@lunch-money/v2-api-spec/update-urls.sh`.
+
+**Required flags:**
+- `--local` - Switch URLs to local development (default: `http://localhost:3000/v2`)
+- `--production` - Switch URLs to production deployment URLs
+
+**Switch to production URLs (using defaults):**
+```bash
+cd node_modules/@lunch-money/v2-api-spec
+./update-urls.sh --production
+```
+
+**Switch to production URLs (with custom URLs):**
+```bash
+cd node_modules/@lunch-money/v2-api-spec
+API_DEPLOY_URL=https://api.lunchmoney.app/v2 \
+DOCS_DEPLOY_URL=https://alpha.lunchmoney.app/v2 \
+./update-urls.sh --production
+```
+
+**Switch to local URLs:**
+```bash
+cd node_modules/@lunch-money/v2-api-spec
+./update-urls.sh --local
+```
+
+**Switch to local URLs (with custom local URL):**
+```bash
+cd node_modules/@lunch-money/v2-api-spec
+LOCAL_URL=http://localhost:4000/v2 ./update-urls.sh --local
+```
+
+**Using environment variables:**
+Create a `.env` file in the package directory:
+```bash
+LOCAL_URL=http://localhost:3000/v2
+API_DEPLOY_URL=https://api.lunchmoney.app/v2
+DOCS_DEPLOY_URL=https://alpha.lunchmoney.app/v2
+```
+
+Then run:
+```bash
+./update-urls.sh --production
+# or
+./update-urls.sh --local
+```
+
+#### How It Works
+
+The script updates the `servers` section in the OpenAPI specification:
+- **Server 1**: Typically the production API server
+- **Server 2**: Typically a mock or staging server
+
+It also updates any references to these URLs throughout the specification file.
+
+#### Important Notes
+
+- The script modifies the spec file in place
+- Changes are not persisted across `npm install` - the package will be restored to its original state
+- For persistent changes, consider copying the spec to your project directory first
+- The script works in both the npm package and the git repository
+
+## Versioning
+
+This package follows the Lunch Money API versioning scheme:
+- **Major version**: API version (currently 2)
+- **Minor version**: Number of main endpoint groups
+- **Revision**: Number of updates since last endpoint addition
+
+For example, version `2.8.2` means:
+- API version 2
+- 8 main endpoint groups
+- 2 updates since the 8th endpoint was added
+
+## Resources
+
+- [Lunch Money Website](https://lunchmoney.app)
+- [Interactive API Documentation](https://alpha.lunchmoney.dev/v2/docs)
+- [GitHub Repository](https://github.com/lunch-money/api-specs)
+- [API Status](https://status.lunchmoney.app)
+
+## License
+
+ISC
+

package/README.md.backup

@@ -0,0 +1,217 @@
+# Lunch Money API Specifications and Documentation
+
+This repository contains the official API specifications and documentation for the [Lunch Money](https://lunchmoney.app) API. Lunch Money is a delightfully simple personal finance and budgeting tool with a comprehensive developer API.
+
+## Repository Structure
+
+This repository is organized in a multi-version structure to support current and future API versions:
+
+```
+.
+├── v2/                    # Version 2 API specific content
+│   ├── spec/              # OpenAPI specification (YAML)
+│   ├── docs/              # Version-specific documentation guides
+│   └── images/            # Images used in documentation
+├── docs/                  # Version-independent documentation
+├── scripts/               # Build and publishing scripts
+└── spec/                  # Generated directory (created during npm publish)
+```
+
+### Directory Details
+
+#### `v2/spec/` - OpenAPI Specification
+The OpenAPI 3.0 specification file (`lunch-money-api-v2.yaml`) defines the complete API contract:
+- All available endpoints
+- Request/response schemas
+- Authentication requirements
+- Error responses
+- Example requests and responses
+
+**This is the source of truth for the API.** Changes to the specification automatically update the interactive API documentation.
+
+#### `v2/docs/` - Version-Specific Documentation Guides
+Markdown files containing detailed guides and reference material specific to v2:
+- `intro-to-v2.md` - Overview of the v2 API and key features
+- `migration-guide.md` - Guide for migrating from v1 to v2
+- `version-history.md` - Changelog of all API versions
+
+These guides are written in Markdown and support custom rendering features (see below).
+
+#### `v2/images/` - Documentation Assets
+Images and screenshots used in the documentation guides.
+
+#### `docs/` - Version-Independent Documentation
+Shared documentation that applies across all API versions:
+- `getting-started.md` - Quick start guide for new developers (applies to all API versions)
+- `rate-limiting.md` - Rate limiting policies and best practices (applies to all API versions)
+- Additional version-independent guides (e.g., pagination guidelines, general API concepts)
+
+## OpenAPI Specification vs Documentation Guides
+
+There are two types of content in this repository, each serving a different purpose:
+
+### OpenAPI Specification (`v2/spec/lunch-money-api-v2.yaml`)
+- **Purpose**: Machine-readable API contract
+- **Format**: YAML (OpenAPI 3.0)
+- **Used for**: 
+  - Generating interactive API documentation
+  - Code generation for SDKs and client libraries
+  - API validation and testing
+  - IDE autocomplete and type checking
+- **Editable**: Yes - changes here automatically update the docs
+
+The OpenAPI spec is the authoritative source for:
+- Endpoint definitions (paths, methods, parameters)
+- Request/response schemas
+- Authentication requirements
+- Status codes and error formats
+
+### Documentation Guides (`v2/docs/*.md`)
+- **Purpose**: Human-readable guides and tutorials
+- **Format**: Markdown with custom extensions
+- **Used for**:
+  - Developer onboarding and tutorials
+  - Best practices and patterns
+  - Migration guides and changelogs
+  - Conceptual explanations
+- **Editable**: Yes - written in Markdown with support for custom features
+
+The guides provide context, examples, and explanations that complement the technical specification.
+
+## Custom Markdown Features
+
+The documentation system supports custom rendering features that enhance Markdown files. These features are processed when the documentation is served and can be used in any Markdown file in the `v2/docs/` directory.
+
+### Callouts
+
+Callouts are styled information boxes for highlighting important information, warnings, or tips.
+
+**Syntax:**
+```markdown
+> [!TYPE]
+> Title (optional)
+> 
+> Content goes here. This can span multiple lines
+> and include **markdown formatting**.
+```
+
+**Supported Types:**
+- `[!NOTE]` - General information or notes (blue styling)
+- `[!TIP]` - Helpful tips or best practices (green styling)
+- `[!WARNING]` - Warnings or important cautions (yellow/orange styling)
+
+**Example:**
+```markdown
+> [!NOTE]
+> API Rate Limits
+> 
+> The API has a rate limit of 1000 requests per 5 minutes per IP address.
+```
+
+### Tabs
+
+Tabs organize content into multiple tabbed sections, useful for showing different code examples, API versions, or alternative approaches.
+
+**Syntax:**
+```markdown
+:::tabs
+@tab Tab Label 1
+Content for the first tab. This can include **markdown** and code blocks.
+
+@tab Tab Label 2
+Content for the second tab. You can have as many tabs as needed.
+:::
+```
+
+**Example: Code Examples in Multiple Languages**
+```markdown
+:::tabs
+@tab cURL
+```bash
+curl -X GET "https://api.lunchmoney.app/v2/transactions" \
+  -H "Authorization: Bearer YOUR_API_TOKEN"
+```
+
+@tab JavaScript
+```javascript
+const response = await fetch('https://api.lunchmoney.app/v2/transactions', {
+  headers: {
+    'Authorization': 'Bearer YOUR_API_TOKEN'
+  }
+});
+```
+:::
+```
+
+**Usage Notes:**
+- Each tab must start with `@tab` followed by the tab label
+- The first tab is active by default when the page loads
+- Tab content can include any markdown, including code blocks, lists, callouts, tables, and links
+- You can combine callouts and tabs in various ways
+
+## Versioning
+
+The Lunch Money API uses a modified version of SEMVER:
+
+- **Major version**: The API version (currently 2)
+- **Minor version**: The number of main endpoints (OpenAPI tags) the spec supports
+- **Revision number**: The number of updates since the last endpoint was added
+
+For example, version `2.8.2` means:
+- API version 2
+- 8 main endpoint groups
+- 2 updates since the 8th endpoint was added
+
+Details of each version can be found in [`v2/docs/version-history.md`](./v2/docs/version-history.md).
+
+### Branch Naming Convention
+
+Each API version is maintained on a branch named after the version number (e.g., `v2.8.2`). The `main` branch typically tracks the most recent version.
+
+## Using This Repository
+
+### As an npm Package
+
+This repository is published as `@lunchmoney/v2-api-spec` on npm for lightweight consumption:
+
+```bash
+npm install @lunchmoney/v2-api-spec
+```
+
+After installation, you can access:
+- OpenAPI spec: `node_modules/@lunchmoney/v2-api-spec/spec/lunch-money-api-v2.yaml`
+- Version history: `node_modules/@lunchmoney/v2-api-spec/spec/version-history.md`
+
+### As a Git Repository
+
+You can clone this repository directly:
+
+```bash
+git clone https://github.com/lunch-money/api-specs.git
+cd api-specs
+```
+
+Or add it as a submodule to your project:
+
+```bash
+git submodule add https://github.com/lunch-money/api-specs.git specs/v2
+```
+
+## Contributing
+
+We welcome contributions to improve the API documentation! When contributing:
+
+1. **For API reference changes**: Update the OpenAPI specification in `v2/spec/lunch-money-api-v2.yaml`
+2. **For documentation**: Update the relevant Markdown files in `v2/docs/`
+3. **Version updates**: Update `v2/docs/version-history.md` with your changes
+4. Create a pull request with a clear description of your changes
+
+Please ensure that:
+- OpenAPI spec changes are valid YAML and conform to OpenAPI 3.0
+- Documentation follows the existing style and uses the custom Markdown features appropriately
+
+## Resources
+
+- [Lunch Money Website](https://lunchmoney.app)
+- [Interactive API Documentation](https://alpha.lunchmoney.dev/v2/docs)
+- [API Status](https://status.lunchmoney.app)