start-vibing-stacks 2.1.0 → 2.2.0

package/dist/ui.js

@@ -2,7 +2,7 @@
  * Start Vibing Stacks — Terminal UI
  */
 import chalk from 'chalk';
-const VERSION = '2.1.0';
+const VERSION = '2.2.0';
 const gradient = (text) => {
     const colors = [chalk.hex('#FF6B6B'), chalk.hex('#FF8E53'), chalk.hex('#FFBD2E'), chalk.hex('#48BB78'), chalk.hex('#4299E1'), chalk.hex('#9F7AEA')];
     return text.split('').map((c, i) => colors[i % colors.length](c)).join('');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-vibing-stacks",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "AI-powered multi-stack dev workflow for Claude Code. Supports PHP, Node.js, Python and more.",
   "type": "module",
   "bin": {

package/stacks/php/skills/api-security/SKILL.md

@@ -0,0 +1,431 @@
+# API Security — NSA-Level Hardening for Laravel + Octane
+
+**ALWAYS invoke when building APIs, auth endpoints, or handling user input.**
+
+## Security Layers
+
+```
+Internet → Cloudflare WAF → Rate Limiting → CORS → Auth Middleware
+  → Input Validation → Business Logic → Output Sanitization → Response
+
+Every layer is a wall. Assume the previous one failed.
+```
+
+## 1. Authentication (Sanctum + Octane)
+
+### Token-Based (API)
+
+```php
+// config/sanctum.php
+'expiration' => 60 * 24,     // 24h token expiry (MANDATORY)
+'token_prefix' => 'flk_',    // Prefix for easy log scanning
+
+// Issue token with abilities (least privilege)
+$token = $user->createToken('api-client', [
+    'read:leads',
+    'write:leads',
+    // NOT '*' — never wildcard abilities
+])->plainTextToken;
+
+// Middleware: check specific ability
+Route::middleware(['auth:sanctum', 'ability:read:leads'])->group(function () {
+    Route::get('/api/v1/leads', [LeadController::class, 'index']);
+});
+```
+
+### Token Rotation
+
+```php
+// Rotate on every sensitive action
+public function changePassword(Request $request): JsonResponse
+{
+    // ... change password logic
+
+    // Revoke ALL tokens (force re-login everywhere)
+    $request->user()->tokens()->delete();
+
+    // Issue fresh token
+    $newToken = $request->user()->createToken('session', ['*'])->plainTextToken;
+
+    return $this->success(['token' => $newToken]);
+}
+```
+
+### Octane Session Safety
+
+```php
+// app/Providers/AppServiceProvider.php
+use Laravel\Octane\Facades\Octane;
+
+public function boot(): void
+{
+    // MANDATORY: flush auth state between requests
+    Octane::prepare(function ($sandbox) {
+        $sandbox->forgetScopedInstances();
+        $sandbox->flushDatabaseConnections();
+    });
+}
+```
+
+## 2. Input Validation (Trust NOTHING)
+
+### FormRequest (Always)
+
+```php
+// app/Http/Requests/StoreLeadRequest.php
+class StoreLeadRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return $this->user()->tokenCan('write:leads');
+    }
+
+    public function rules(): array
+    {
+        return [
+            'name' => ['required', 'string', 'min:2', 'max:255'],
+            'email' => ['required', 'email:rfc,dns', 'max:320'],  // RFC + DNS check
+            'phone' => ['nullable', 'string', 'regex:/^\+?[1-9]\d{1,14}$/'],  // E.164
+            'domain_id' => ['required', 'uuid', 'exists:domains,id'],
+            'metadata' => ['nullable', 'json', 'max:10000'],  // Size limit on JSON
+            'tags' => ['nullable', 'array', 'max:10'],
+            'tags.*' => ['string', 'max:50', 'alpha_dash'],
+        ];
+    }
+
+    // Sanitize AFTER validation
+    public function validated($key = null, $default = null): array
+    {
+        $data = parent::validated($key, $default);
+        $data['email'] = strtolower(trim($data['email']));
+        $data['name'] = strip_tags($data['name']);
+        return $data;
+    }
+}
+```
+
+### SQL Injection Prevention
+
+```php
+// ✅ ALWAYS Eloquent or parameterized
+Lead::where('email', $request->validated('email'))->first();
+
+// ✅ Raw with bindings
+DB::select('SELECT * FROM leads WHERE email = ?', [$email]);
+
+// ❌ NEVER interpolate user input
+DB::select("SELECT * FROM leads WHERE email = '{$email}'");  // ❌ SQL INJECTION
+```
+
+### Mass Assignment Protection
+
+```php
+class Lead extends Model
+{
+    // Explicit fillable (whitelist approach)
+    protected $fillable = [
+        'name', 'email', 'phone', 'domain_id', 'metadata',
+    ];
+
+    // NEVER: protected $guarded = []; ← allows EVERYTHING
+}
+```
+
+## 3. Rate Limiting (Multi-Layer)
+
+```php
+// app/Providers/AppServiceProvider.php
+use Illuminate\Cache\RateLimiting\Limit;
+use Illuminate\Support\Facades\RateLimiter;
+
+public function boot(): void
+{
+    // Global API limit
+    RateLimiter::for('api', function ($request) {
+        return Limit::perMinute(60)->by($request->user()?->id ?: $request->ip());
+    });
+
+    // Strict limit on auth endpoints
+    RateLimiter::for('auth', function ($request) {
+        return [
+            Limit::perMinute(5)->by($request->ip()),           // 5/min per IP
+            Limit::perHour(20)->by($request->ip()),            // 20/hour per IP
+            Limit::perDay(50)->by($request->ip()),             // 50/day per IP
+        ];
+    });
+
+    // Strict limit on sensitive actions
+    RateLimiter::for('sensitive', function ($request) {
+        return Limit::perMinute(3)->by($request->user()->id);  // 3/min per user
+    });
+
+    // Webhook endpoints
+    RateLimiter::for('webhooks', function ($request) {
+        return Limit::perMinute(100)->by($request->ip());
+    });
+}
+
+// Routes
+Route::middleware('throttle:auth')->group(function () {
+    Route::post('/login', [AuthController::class, 'login']);
+    Route::post('/register', [AuthController::class, 'register']);
+    Route::post('/forgot-password', [AuthController::class, 'forgotPassword']);
+});
+
+Route::middleware('throttle:sensitive')->group(function () {
+    Route::post('/change-password', [AuthController::class, 'changePassword']);
+    Route::post('/change-email', [AuthController::class, 'changeEmail']);
+    Route::delete('/account', [AuthController::class, 'deleteAccount']);
+});
+```
+
+## 4. CORS (Restrictive)
+
+```php
+// config/cors.php
+return [
+    'paths' => ['api/*'],
+    'allowed_methods' => ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'],
+    'allowed_origins' => [
+        env('APP_URL'),                           // Only your domain
+        // NOT '*' — NEVER wildcard in production
+    ],
+    'allowed_headers' => [
+        'Content-Type', 'Authorization', 'X-Requested-With',
+        'X-Timezone', 'Accept', 'X-CSRF-TOKEN',
+    ],
+    'exposed_headers' => ['X-Request-ID', 'Retry-After'],
+    'max_age' => 86400,                           // 24h preflight cache
+    'supports_credentials' => true,
+];
+```
+
+## 5. Security Headers Middleware
+
+```php
+// app/Http/Middleware/SecurityHeaders.php
+class SecurityHeaders
+{
+    public function handle($request, Closure $next)
+    {
+        $response = $next($request);
+
+        return $response
+            ->header('X-Content-Type-Options', 'nosniff')
+            ->header('X-Frame-Options', 'DENY')
+            ->header('X-XSS-Protection', '0')  // Modern browsers use CSP instead
+            ->header('Referrer-Policy', 'strict-origin-when-cross-origin')
+            ->header('Permissions-Policy', 'camera=(), microphone=(), geolocation=()')
+            ->header('Strict-Transport-Security', 'max-age=31536000; includeSubDomains; preload')
+            ->header('X-Request-ID', $request->attributes->get('request_id', (string) Str::uuid()))
+            ->header('Content-Security-Policy', implode('; ', [
+                "default-src 'self'",
+                "script-src 'self' 'unsafe-inline' https://js.stripe.com",
+                "style-src 'self' 'unsafe-inline' https://fonts.googleapis.com",
+                "img-src 'self' data: https:",
+                "font-src 'self' https://fonts.gstatic.com",
+                "connect-src 'self' https://api.stripe.com",
+                "frame-src https://js.stripe.com",
+                "object-src 'none'",
+                "base-uri 'self'",
+            ]));
+    }
+}
+```
+
+## 6. Output Sanitization
+
+```php
+// app/Http/Resources/LeadResource.php
+class LeadResource extends JsonResource
+{
+    use FormatsDatesForApi;
+
+    public function toArray(Request $request): array
+    {
+        return [
+            'id' => $this->id,
+            'name' => e($this->name),           // HTML entity encode
+            'email' => $this->email,
+            'status' => $this->status->value,
+            'created_at' => $this->formatDateTime($this->created_at, $request),
+            // NEVER expose:
+            // 'password' → NEVER
+            // 'api_token' → NEVER
+            // 'ip_address' → only if admin
+            // 'remember_token' → NEVER
+        ];
+    }
+}
+
+// Model hidden attributes (defense in depth)
+class User extends Authenticatable
+{
+    protected $hidden = [
+        'password',
+        'remember_token',
+        'two_factor_secret',
+        'two_factor_recovery_codes',
+    ];
+}
+```
+
+## 7. Encryption at Rest
+
+```php
+// Encrypt sensitive data in database
+use Illuminate\Database\Eloquent\Casts\Attribute;
+
+class ApiCredential extends Model
+{
+    // Laravel encrypted cast (AES-256-CBC)
+    protected $casts = [
+        'api_key' => 'encrypted',
+        'api_secret' => 'encrypted',
+        'webhook_secret' => 'encrypted',
+    ];
+}
+
+// For searchable encrypted fields
+use Illuminate\Support\Facades\Crypt;
+
+class Lead extends Model
+{
+    // Store hash for lookup, encrypted value for display
+    protected static function booted(): void
+    {
+        static::creating(function ($lead) {
+            $lead->email_hash = hash('sha256', strtolower($lead->email));
+            $lead->email_encrypted = Crypt::encryptString($lead->email);
+        });
+    }
+}
+```
+
+## 8. Audit Logging
+
+```php
+// app/Traits/Auditable.php
+trait Auditable
+{
+    protected static function bootAuditable(): void
+    {
+        foreach (['created', 'updated', 'deleted'] as $event) {
+            static::$event(function ($model) use ($event) {
+                AuditLog::create([
+                    'auditable_type' => $model->getMorphClass(),
+                    'auditable_id' => $model->getKey(),
+                    'event' => $event,
+                    'old_values' => $event === 'updated' ? $model->getOriginal() : null,
+                    'new_values' => $event !== 'deleted' ? $model->getAttributes() : null,
+                    'user_id' => auth()->id(),
+                    'ip_address' => request()->ip(),
+                    'user_agent' => request()->userAgent(),
+                ]);
+            });
+        }
+    }
+}
+
+// Usage on sensitive models
+class Lead extends Model
+{
+    use HasUuids, Auditable;
+}
+```
+
+## 9. Brute Force Protection
+
+```php
+// app/Http/Controllers/Auth/LoginController.php
+public function login(LoginRequest $request): JsonResponse
+{
+    $key = 'login_attempts:' . $request->ip() . ':' . Str::lower($request->email);
+
+    // Check lockout (progressive delay)
+    $attempts = (int) Cache::get($key, 0);
+    if ($attempts >= 5) {
+        $lockoutMinutes = min(pow(2, $attempts - 5), 60);  // 1, 2, 4, 8, 16, 32, 60 min
+        $ttl = Cache::get("{$key}:lockout");
+        if ($ttl && now()->lt($ttl)) {
+            return $this->error('Too many attempts. Try again later.', 429);
+        }
+    }
+
+    if (!Auth::attempt($request->validated())) {
+        // Increment with exponential TTL
+        Cache::put($key, $attempts + 1, now()->addHours(1));
+        if ($attempts + 1 >= 5) {
+            $lockoutMinutes = min(pow(2, $attempts - 4), 60);
+            Cache::put("{$key}:lockout", now()->addMinutes($lockoutMinutes), now()->addMinutes($lockoutMinutes));
+        }
+
+        // Generic message (don't reveal if user exists)
+        return $this->error('Invalid credentials', 401);
+    }
+
+    // Reset on success
+    Cache::forget($key);
+    Cache::forget("{$key}:lockout");
+
+    $token = $request->user()->createToken('session')->plainTextToken;
+    return $this->success(['token' => $token]);
+}
+```
+
+## 10. Request ID Tracking
+
+```php
+// app/Http/Middleware/RequestId.php
+class RequestId
+{
+    public function handle($request, Closure $next)
+    {
+        $requestId = $request->header('X-Request-ID', (string) Str::uuid());
+        $request->attributes->set('request_id', $requestId);
+
+        // Add to all log entries in this request
+        Log::shareContext(['request_id' => $requestId]);
+
+        $response = $next($request);
+        $response->header('X-Request-ID', $requestId);
+
+        return $response;
+    }
+}
+```
+
+## Security Checklist — Before Deploy
+
+- [ ] All endpoints have auth middleware
+- [ ] All input validated via FormRequest
+- [ ] Rate limiting on auth + sensitive endpoints
+- [ ] CORS restricted to your domain only
+- [ ] Security headers middleware active
+- [ ] Sensitive fields `$hidden` on models
+- [ ] API keys encrypted at rest
+- [ ] Audit logging on sensitive models
+- [ ] Brute force protection on login
+- [ ] Request ID tracking in all logs
+- [ ] No `env()` in code (only `config()`)
+- [ ] No `*` in token abilities
+- [ ] No `$guarded = []` on models
+- [ ] CSP headers configured
+- [ ] HSTS enabled
+- [ ] Webhook signatures verified
+- [ ] Error responses don't expose internals
+
+## FORBIDDEN
+
+| ❌ Don't | ✅ Do |
+|---|---|
+| `$guarded = []` | Explicit `$fillable` |
+| `'allowed_origins' => ['*']` | Your domain only |
+| `createToken('x', ['*'])` | Specific abilities |
+| `"WHERE email = '$email'"` | Parameterized queries |
+| `dd($user)` in production | `Log::info()` structured |
+| Generic error messages with stack traces | Clean error + request_id for debugging |
+| Store API keys in plaintext | `'encrypted'` cast |
+| Same rate limit for all endpoints | Progressive: auth(5/min) < api(60/min) |
+| Trust `X-Forwarded-For` directly | Use trusted proxies config |
+| No token expiry | 24h max, rotate on sensitive actions |

package/stacks/php/skills/external-api-patterns/SKILL.md

@@ -0,0 +1,513 @@
+# External API Patterns — HTTP Client for Laravel + Octane
+
+**ALWAYS invoke when consuming external APIs, webhooks, or third-party services.**
+
+## Architecture
+
+```
+Controller/Job
+  → ApiService (business logic)
+    → Http::withOptions() (Laravel HTTP Client)
+      → Response handling (DTO)
+        → Error handling (typed exceptions)
+          → Logging + monitoring
+
+NEVER call Http:: directly in controllers. Always through a Service.
+```
+
+## Service Pattern
+
+```php
+// app/Services/External/OpenAiService.php
+namespace App\Services\External;
+
+use App\DTOs\Api\ChatCompletionRequest;
+use App\DTOs\Api\ChatCompletionResponse;
+use App\Exceptions\Api\ApiConnectionException;
+use App\Exceptions\Api\ApiRateLimitException;
+use App\Exceptions\Api\ApiValidationException;
+use Illuminate\Http\Client\PendingRequest;
+use Illuminate\Http\Client\RequestException;
+use Illuminate\Http\Client\ConnectionException;
+use Illuminate\Support\Facades\Http;
+use Illuminate\Support\Facades\Log;
+
+class OpenAiService
+{
+    private PendingRequest $client;
+
+    public function __construct()
+    {
+        $this->client = Http::baseUrl(config('services.openai.base_url', 'https://api.openai.com/v1'))
+            ->withToken(config('services.openai.key'))
+            ->timeout(30)
+            ->connectTimeout(5)
+            ->withHeaders([
+                'Accept' => 'application/json',
+                'Content-Type' => 'application/json',
+            ])
+            ->retry(
+                times: 3,
+                sleepMilliseconds: fn (int $attempt) => $attempt * 500, // 500ms, 1s, 1.5s
+                when: fn ($exception) => $this->shouldRetry($exception),
+                throw: true,
+            );
+    }
+
+    public function chatCompletion(ChatCompletionRequest $request): ChatCompletionResponse
+    {
+        try {
+            $response = $this->client
+                ->post('/chat/completions', $request->toArray())
+                ->throw();
+
+            return ChatCompletionResponse::fromArray($response->json());
+
+        } catch (ConnectionException $e) {
+            Log::error('[OpenAI] Connection failed', [
+                'error' => $e->getMessage(),
+            ]);
+            throw new ApiConnectionException('OpenAI', $e);
+
+        } catch (RequestException $e) {
+            $this->handleRequestException($e, 'chatCompletion');
+        }
+    }
+
+    private function shouldRetry(\Exception $exception): bool
+    {
+        if ($exception instanceof ConnectionException) return true;
+
+        if ($exception instanceof RequestException) {
+            $status = $exception->response->status();
+            // Retry on: 408 timeout, 429 rate limit, 500+ server errors
+            return in_array($status, [408, 429, 500, 502, 503, 504]);
+        }
+
+        return false;
+    }
+
+    private function handleRequestException(RequestException $e, string $method): never
+    {
+        $status = $e->response->status();
+        $body = $e->response->json();
+
+        Log::error("[OpenAI] {$method} failed", [
+            'status' => $status,
+            'error' => $body['error']['message'] ?? $e->getMessage(),
+            'type' => $body['error']['type'] ?? 'unknown',
+        ]);
+
+        match (true) {
+            $status === 429 => throw new ApiRateLimitException('OpenAI', $body, $e),
+            $status === 422 => throw new ApiValidationException('OpenAI', $body, $e),
+            $status >= 500 => throw new ApiConnectionException('OpenAI', $e),
+            default => throw new ApiConnectionException('OpenAI', $e),
+        };
+    }
+}
+```
+
+## DTOs (Data Transfer Objects)
+
+```php
+// app/DTOs/Api/ChatCompletionRequest.php
+namespace App\DTOs\Api;
+
+readonly class ChatCompletionRequest
+{
+    public function __construct(
+        public string $model,
+        public array $messages,
+        public float $temperature = 0.7,
+        public int $maxTokens = 4096,
+    ) {}
+
+    public function toArray(): array
+    {
+        return [
+            'model' => $this->model,
+            'messages' => $this->messages,
+            'temperature' => $this->temperature,
+            'max_tokens' => $this->maxTokens,
+        ];
+    }
+}
+
+// app/DTOs/Api/ChatCompletionResponse.php
+namespace App\DTOs\Api;
+
+readonly class ChatCompletionResponse
+{
+    public function __construct(
+        public string $id,
+        public string $content,
+        public int $promptTokens,
+        public int $completionTokens,
+        public string $model,
+        public string $finishReason,
+    ) {}
+
+    public static function fromArray(array $data): self
+    {
+        return new self(
+            id: $data['id'],
+            content: $data['choices'][0]['message']['content'] ?? '',
+            promptTokens: $data['usage']['prompt_tokens'] ?? 0,
+            completionTokens: $data['usage']['completion_tokens'] ?? 0,
+            model: $data['model'],
+            finishReason: $data['choices'][0]['finish_reason'] ?? 'unknown',
+        );
+    }
+}
+```
+
+## Typed Exceptions
+
+```php
+// app/Exceptions/Api/ApiConnectionException.php
+namespace App\Exceptions\Api;
+
+class ApiConnectionException extends \RuntimeException
+{
+    public function __construct(
+        public readonly string $service,
+        ?\Throwable $previous = null,
+    ) {
+        parent::__construct("Connection to {$service} API failed", 503, $previous);
+    }
+}
+
+// app/Exceptions/Api/ApiRateLimitException.php
+class ApiRateLimitException extends \RuntimeException
+{
+    public function __construct(
+        public readonly string $service,
+        public readonly array $body = [],
+        ?\Throwable $previous = null,
+    ) {
+        $retryAfter = $body['error']['retry_after'] ?? 'unknown';
+        parent::__construct("{$service} rate limit exceeded. Retry after: {$retryAfter}s", 429, $previous);
+    }
+}
+
+// app/Exceptions/Api/ApiValidationException.php
+class ApiValidationException extends \RuntimeException
+{
+    public function __construct(
+        public readonly string $service,
+        public readonly array $body = [],
+        ?\Throwable $previous = null,
+    ) {
+        $message = $body['error']['message'] ?? 'Validation failed';
+        parent::__construct("{$service}: {$message}", 422, $previous);
+    }
+}
+```
+
+## API Response Standard (Your API → Frontend)
+
+```php
+// app/Traits/ApiResponse.php
+namespace App\Traits;
+
+use Illuminate\Http\JsonResponse;
+
+trait ApiResponse
+{
+    protected function success(mixed $data = null, string $message = 'OK', int $status = 200): JsonResponse
+    {
+        return response()->json([
+            'success' => true,
+            'message' => $message,
+            'data' => $data,
+        ], $status);
+    }
+
+    protected function created(mixed $data = null, string $message = 'Created'): JsonResponse
+    {
+        return $this->success($data, $message, 201);
+    }
+
+    protected function error(string $message, int $status = 400, array $errors = []): JsonResponse
+    {
+        $response = [
+            'success' => false,
+            'message' => $message,
+        ];
+
+        if (!empty($errors)) {
+            $response['errors'] = $errors;
+        }
+
+        return response()->json($response, $status);
+    }
+
+    protected function notFound(string $resource = 'Resource'): JsonResponse
+    {
+        return $this->error("{$resource} not found", 404);
+    }
+
+    protected function unauthorized(string $message = 'Unauthorized'): JsonResponse
+    {
+        return $this->error($message, 401);
+    }
+
+    protected function rateLimited(int $retryAfter = 60): JsonResponse
+    {
+        return response()->json([
+            'success' => false,
+            'message' => 'Too many requests',
+            'retry_after' => $retryAfter,
+        ], 429)->header('Retry-After', $retryAfter);
+    }
+}
+```
+
+### Controller Usage
+
+```php
+class AiModelController extends Controller
+{
+    use ApiResponse;
+
+    public function __construct(
+        private readonly OpenAiService $openAi,
+    ) {}
+
+    public function generate(GenerateRequest $request): JsonResponse
+    {
+        try {
+            $dto = new ChatCompletionRequest(
+                model: $request->validated('model'),
+                messages: $request->validated('messages'),
+                temperature: $request->validated('temperature', 0.7),
+            );
+
+            $result = $this->openAi->chatCompletion($dto);
+
+            return $this->success([
+                'content' => $result->content,
+                'tokens' => $result->promptTokens + $result->completionTokens,
+                'model' => $result->model,
+            ]);
+
+        } catch (ApiRateLimitException $e) {
+            return $this->rateLimited(60);
+        } catch (ApiValidationException $e) {
+            return $this->error($e->getMessage(), 422);
+        } catch (ApiConnectionException $e) {
+            return $this->error('Service temporarily unavailable', 503);
+        }
+    }
+}
+```
+
+## Frontend Consumption (React + Inertia)
+
+```tsx
+// resources/js/services/api.ts
+import axios, { AxiosError } from 'axios';
+
+interface ApiResponse<T> {
+    success: boolean;
+    message: string;
+    data: T;
+    errors?: Record<string, string[]>;
+}
+
+interface ApiErrorResponse {
+    success: false;
+    message: string;
+    errors?: Record<string, string[]>;
+    retry_after?: number;
+}
+
+export async function apiCall<T>(
+    method: 'get' | 'post' | 'put' | 'delete',
+    url: string,
+    data?: unknown,
+): Promise<T> {
+    try {
+        const response = await axios({ method, url, data });
+        const body = response.data as ApiResponse<T>;
+        if (!body.success) throw new ApiError(body.message, response.status);
+        return body.data;
+    } catch (error) {
+        if (error instanceof AxiosError) {
+            const body = error.response?.data as ApiErrorResponse;
+            const status = error.response?.status ?? 500;
+
+            if (status === 429) {
+                throw new RateLimitError(body?.retry_after ?? 60);
+            }
+            if (status === 422 && body?.errors) {
+                throw new ValidationError(body.message, body.errors);
+            }
+            throw new ApiError(body?.message ?? 'Connection failed', status);
+        }
+        throw error;
+    }
+}
+
+// Typed errors
+export class ApiError extends Error {
+    constructor(message: string, public status: number) { super(message); }
+}
+export class ValidationError extends ApiError {
+    constructor(message: string, public errors: Record<string, string[]>) { super(message, 422); }
+}
+export class RateLimitError extends ApiError {
+    constructor(public retryAfter: number) { super('Too many requests', 429); }
+}
+```
+
+### React Component Usage
+
+```tsx
+const LABELS = {
+    generating: __('messages.ai.generating'),
+    error: __('messages.errors.error'),
+    rateLimited: __('messages.errors.rate_limited'),
+} as const;
+
+export default function AiChat() {
+    const [loading, setLoading] = useState(false);
+
+    const generate = async () => {
+        setLoading(true);
+        try {
+            const result = await apiCall<{ content: string }>('post', route('api.v1.ai.generate'), {
+                model: 'gpt-4',
+                messages: [{ role: 'user', content: prompt }],
+            });
+            setResponse(result.content);
+        } catch (error) {
+            if (error instanceof RateLimitError) {
+                toast.error(`${LABELS.rateLimited} (${error.retryAfter}s)`);
+            } else if (error instanceof ValidationError) {
+                Object.values(error.errors).flat().forEach(msg => toast.error(msg));
+            } else {
+                toast.error(error instanceof ApiError ? error.message : LABELS.error);
+            }
+        } finally {
+            setLoading(false);
+        }
+    };
+}
+```
+
+## Octane Safety
+
+```php
+// ✅ New client instance per request (no stale state)
+public function __construct()
+{
+    // Http::baseUrl() creates a NEW PendingRequest each time
+    // Safe in Octane — no shared state between requests
+    $this->client = Http::baseUrl(config('services.openai.base_url'))
+        ->withToken(config('services.openai.key'));
+}
+
+// ❌ NEVER static client (leaks between Octane requests)
+private static PendingRequest $client; // ❌ Shared across ALL requests!
+```
+
+## Config Pattern
+
+```php
+// config/services.php
+'openai' => [
+    'key' => env('OPENAI_API_KEY'),
+    'base_url' => env('OPENAI_BASE_URL', 'https://api.openai.com/v1'),
+    'timeout' => env('OPENAI_TIMEOUT', 30),
+    'max_retries' => env('OPENAI_MAX_RETRIES', 3),
+],
+
+'stripe' => [
+    'key' => env('STRIPE_KEY'),
+    'secret' => env('STRIPE_SECRET'),
+    'webhook_secret' => env('STRIPE_WEBHOOK_SECRET'),
+],
+```
+
+**Rule:** All API keys in `.env` → `config/services.php` → `config('services.x.key')`. NEVER `env()` directly in code (cached in Octane).
+
+## Webhook Receiving
+
+```php
+// app/Http/Controllers/Webhooks/StripeWebhookController.php
+class StripeWebhookController extends Controller
+{
+    public function handle(Request $request): JsonResponse
+    {
+        // 1. Verify signature
+        $payload = $request->getContent();
+        $signature = $request->header('Stripe-Signature');
+
+        try {
+            $event = \Stripe\Webhook::constructEvent(
+                $payload,
+                $signature,
+                config('services.stripe.webhook_secret')
+            );
+        } catch (\Exception $e) {
+            Log::warning('[Stripe Webhook] Invalid signature', ['error' => $e->getMessage()]);
+            return response()->json(['error' => 'Invalid signature'], 400);
+        }
+
+        // 2. Process idempotently (check if already processed)
+        if (WebhookEvent::where('event_id', $event->id)->exists()) {
+            return response()->json(['status' => 'already_processed']);
+        }
+
+        // 3. Store event
+        WebhookEvent::create([
+            'event_id' => $event->id,
+            'type' => $event->type,
+            'payload' => $payload,
+        ]);
+
+        // 4. Dispatch job (async processing)
+        ProcessStripeEvent::dispatch($event->type, $event->data->object);
+
+        return response()->json(['status' => 'received']);
+    }
+}
+```
+
+## Logging Standard
+
+```php
+// Structured logging for all API calls
+Log::info('[ServiceName] API call', [
+    'method' => 'POST',
+    'endpoint' => '/chat/completions',
+    'status' => 200,
+    'duration_ms' => $duration,
+    'tokens' => $response->promptTokens + $response->completionTokens,
+]);
+
+Log::error('[ServiceName] API failed', [
+    'method' => 'POST',
+    'endpoint' => '/chat/completions',
+    'status' => $e->response->status(),
+    'error' => $e->response->json('error.message'),
+    'duration_ms' => $duration,
+]);
+```
+
+## FORBIDDEN
+
+| ❌ Don't | ✅ Do |
+|---|---|
+| `Http::get()` in controller | Service class with typed DTOs |
+| `env('API_KEY')` in code | `config('services.x.key')` |
+| Raw arrays for API data | `readonly class` DTOs |
+| Catch generic `Exception` | Typed exceptions per error type |
+| `static $client` in Octane | Instance `$this->client` per request |
+| No timeout on HTTP calls | `->timeout(30)->connectTimeout(5)` |
+| No retry logic | `->retry(3, backoff, when)` |
+| Webhook without signature check | ALWAYS verify signatures |
+| Webhook sync processing | Dispatch job for async |
+| `dd()` / `dump()` API responses | Structured `Log::info/error` |