# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Critical: Do Not Edit PHP Files

All PHP files in `0.9/`, `2.0/`, `2.1/`, `3.0/`, and `2026-01/` are **auto-generated** by OpenAPI Generator. Never edit them directly. All changes must be made to the OpenAPI spec files in `swagger/` and then regenerated.

## Making Changes

1. Edit the appropriate spec file in `swagger/`:
   - `swagger/api-0.9.json` → generates `0.9/`
   - `swagger/api-2.0.json` → generates `2.0/`
   - `swagger/api-2.1.json` → generates `2.1/`
   - `swagger/api-3.0.json` → generates `3.0/`
   - `swagger/api-2026-01.yaml` → generates `2026-01/`

2. Run the build to regenerate PHP:
   ```bash
   cd /path/to/repo && bash swagger/build.sh
   ```
   Or regenerate a single version, e.g. for 2026-01:
   ```bash
   docker run --rm -v ".:/local" openapitools/openapi-generator-cli:v7.20.0 generate \
     -i /local/swagger/api-2026-01.yaml \
     -c /local/swagger/config2026-01.json \
     -g php -o /local/2026-01
   ```

   Versions `0.9`–`3.0` use `openapitools/openapi-generator-cli:v6.0.0`; `2026-01` uses `v7.20.0`.

## Running Tests

```bash
composer install
vendor/bin/phpunit
```

## Architecture

This repo is a PHP client SDK for the Lightspeed Retail (formerly Vend) API. It contains multiple API versions as separate generated PHP libraries, all sharing a single `composer.json` at the root.

| Directory | API Version | Namespace | PHP Req | Auth |
|-----------|-------------|-----------|---------|------|
| `0.9/` | Original Vend API | `Vend09` | 7.4+ | `personal_token` |
| `2.0/` | Vend API 2.0 | `Vend20` | 7.4+ | `personal_token` |
| `2.1/` | Vend API 2.1 (2 endpoints only) | `Vend21` | 7.4+ | `personal_token` |
| `3.0/` | Vend API 3.0 (beta) | `Vend30` | 7.4+ | `personal_token` |
| `2026-01/` | Lightspeed Retail X-Series | `Vend202601` | 8.1+ | Bearer token |

Each version directory has the same internal structure: `lib/Api/` (endpoint classes), `lib/Model/` (data models), `docs/`, and `test/`.

The `2026-01` API is the current active API from Lightspeed Retail. Its spec (`api-2026-01.yaml`) can be downloaded from `https://x-series-api.lightspeedhq.com/v2026.01/openapi/`.

## Notes

- The `api-2026-01.yaml` file is a single-line minified YAML — use a YAML parser to read it, not grep/read tools.
- The build script notes that `inventory_levels` must be manually added to the 2.0 API after generation (it's in the spec but not included in the generated library).
