# CLAUDE.md

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

## Development Commands

```bash
# Format code (Laravel Pint)
composer lint

# Check formatting without modifying
composer lint:check

# Static analysis (PHPStan level 8)
composer analyse

# Run tests (Pest)
composer test

# Run tests with coverage (minimum 80%)
composer test:coverage

# Check type coverage (minimum 90%)
composer test:type-coverage

# Run all checks (lint + analyse + tests)
composer quality

# Run a specific test file
./vendor/bin/pest tests/Unit/Services/ShortUrlApiServiceTest.php

# Run a test by name
./vendor/bin/pest --filter="returns a list of short URLs"
```

## Architecture

This Laravel SDK provides HTTP clients to interact with Wellpack APIs (ShortUrl and Trigger).

### Module Structure

Each API follows the same pattern:

```
src/{ApiName}/
├── Facades/          # Laravel facades (static access)
└── Services/         # Services with business logic
```

### Authentication Flow

`HttpClient` automatically handles OAuth2 authentication (client credentials):
1. Obtains a token via `/oauth/token`
2. Stores the token in `Storage::disk('local')`
3. Automatic retry with refresh on 401

### HTTP Macros

`ApiSdkServiceProvider` registers two macros on `Http`:
- `Http::shortUrlApi()` - Client for ShortUrl API
- `Http::triggerUrlApi()` - Client for Trigger API

These macros return a `PendingRequest` preconfigured with authentication.

### Tests

Tests use Pest with Orchestra Testbench. Helpers available in `tests/Pest.php`:
- `fakeShortUrlApiResponse($endpoint, $response, $status)` - Mock OAuth + ShortUrl response
- `fakeTriggerApiResponse($endpoint, $response, $status)` - Mock OAuth + Trigger response

Always use `Storage::fake('local')` in `beforeEach` to isolate token storage.

## Required Configuration

Environment variables:
```
SHORT_URL_API_DOMAIN, SHORT_URL_CLIENT_ID, SHORT_URL_CLIENT_SECRET
TRIGGER_API_DOMAIN, TRIGGER_CLIENT_ID, TRIGGER_CLIENT_SECRET
```

## Code Standards

- PHP 8.4+, Laravel 12+
- `declare(strict_types=1)` required
- PHPStan level 8
- Laravel Pint (laravel preset) with alphabetically ordered imports
- All code, tests, commit messages, comments, and documentation must be in English

## Git Workflow

- **NEVER commit directly to `main`** - always create a feature branch first
- Branch naming: `feature/<description>` or `fix/<description>`
- Create a PR for code review before merging to main