54 lines
2.3 KiB
Markdown
54 lines
2.3 KiB
Markdown
|
# 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.
|