# CLAUDE.md

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

## Project Overview

Laravel package (`lthn/php-plug-altum`) providing PHP API clients for four AltumCode self-hosted products: 66analytics, 66biolinks, 66pusher, and 66socialproof. Licensed EUPL-1.2.

## Commands

```bash
# Install dependencies
composer install

# Run all tests
./vendor/bin/pest

# Run a single test file
./vendor/bin/pest tests/AltumClientTest.php

# Run a specific test by name
./vendor/bin/pest --filter="creates user with named params"
```

## Architecture

**Namespace:** `Core\Plug\Altum\` (PSR-4 mapped to `src/`)

### Key design decisions

- **`AltumClient`** is the base class containing all HTTP transport and both Admin API (`/admin-api/`) and User API (`/api/{resource}/`) methods. Product clients extend it.
- **Product clients** (`Analytics\Client`, `Biolinks\Client`, `Pusher\Client`, `Socialproof\Client`) are thin wrappers that call inherited `listResource()`, `getResource()`, `createResource()`, `updateResource()`, `deleteResource()` methods with product-specific resource names.
- **`AltumManager`** is a factory that reads config and instantiates the correct product client. Resolved as a singleton via `AltumServiceProvider`.
- **`AltumWebhookVerifier`** implements `Core\Webhook\WebhookVerifier` (from the parent framework). Currently only checks User-Agent header since AltumCode doesn't yet sign webhooks.
- **Immutable cloning:** `withUserKey()` returns a new client instance rather than mutating state.

### AltumCode API quirks (important for new endpoints)

- POST is used for both creates and updates (never PUT/PATCH).
- POST bodies are form-encoded (`asForm()`), not JSON.
- Admin endpoints: `/admin-api/...` with admin API key.
- User endpoints: `/api/{resource}/` with per-user API key.
- Errors return `['error' => true, ...]` arrays instead of throwing exceptions.

### Laravel integration

- Auto-discovered via `extra.laravel.providers` in composer.json.
- Config expected at `services.altum` with structure: `['analytics' => ['url' => '...', 'admin_key' => '...'], ...]`.
- Webhook verifiers bound as `webhook.verifier.altum-{product}` for each product.

## Testing

Uses Pest 3 with Laravel's `Http::fake()` for all HTTP mocking. Tests mirror the `src/` directory structure under `tests/`. No real API calls are made.