# CLAUDE.md

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

## Project Overview

Auto-generated PHP SDK client library for the Faire External API v2, generated from an OpenAPI specification using OpenAPI Generator v7.19.0. Provides access to Faire's e-commerce platform for brands/partners to manage products, orders, inventory, and more.

- **Language:** PHP 8.1+
- **Package:** `talisman/faire`
- **HTTP Client:** Guzzle 7.3+
- **API Base URL:** `https://www.faire.com/external-api/v2`

## Common Commands

```bash
# Install dependencies
composer install

# Regenerate SDK from OpenAPI spec (runs via Docker)
cd openapi && ./build.sh

# Run all tests
vendor/bin/phpunit

# Run a single test file
vendor/bin/phpunit test/Api/ProductsApiTest.php

# Run a single test method
vendor/bin/phpunit --filter testProductsGet test/Api/ProductsApiTest.php

# Fix code style (PSR-12)
vendor/bin/php-cs-fixer fix
```

## Architecture

### Code Generation

All code in `lib/`, `test/`, and `docs/` is **auto-generated** — do not manually edit these files. To make changes:

1. Modify `openapi/openapi.json` (the OpenAPI 3.0 spec, ~4000 lines) or `openapi/config.json`
2. Run `openapi/build.sh` which uses Docker-based OpenAPI Generator to regenerate everything

### Key Directories

- **`lib/Api/`** — 7 API client classes (BrandsApi, InventoryApi, OrdersApi, PrepacksApi, ProductsApi, ProductVariantsApi, RetailersApi) with 44 total endpoints
- **`lib/Model/`** — 82 model classes for request/response serialization, all implementing `ModelInterface`, `ArrayAccess`, `JsonSerializable`
- **`lib/Configuration.php`** — API auth & config (API keys, OAuth tokens, host settings); singleton via `getDefaultConfiguration()`
- **`lib/ObjectSerializer.php`** — JSON serialization/deserialization with nested object support
- **`test/Api/` and `test/Model/`** — Auto-generated PHPUnit test stubs

### Authentication

Two mechanisms configured in `Configuration`:
- **OAuth 2.0** (recommended): `X-FAIRE-APP-CREDENTIALS` + `X-FAIRE-OAUTH-ACCESS-TOKEN` headers
- **Direct API Key**: `X-FAIRE-APP-CREDENTIALS` header only

### Faire Domain Model

- **Product** → has Options (color, size) → has Variants (specific option combos with pricing, SKU, inventory)
- **Order** → tracks retailer orders with items, shipments, cancellations
- **Prepack** → pre-packaged product bundles, supports batch creation

## Notes

- Travis CI config (`.travis.yml`) specifies PHP 7.4 but `composer.json` requires PHP 8.1+ — this is a known mismatch
- Code style: PSR-12 with strict comparisons enabled (`.php-cs-fixer.dist.php`)
- Tests use PHPUnit 8.0 or 9.0; coverage configured for `lib/Api/` and `lib/Model/`
