# @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