php-plug-altum/CLAUDE.md

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

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