# CLAUDE.md

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

## Project Overview

PHP Composer library (`lthn/php-plug-web3`) providing decentralised/Web3 social media provider integrations for the Plug framework. Depends on `lthn/php` which supplies the base contracts, concerns, and `Response` class.

## Commands

No build step — this is a library. Install dependencies:
```bash
composer install
```

No test suite or linter is configured in this repository.

## Architecture

**Namespace:** `Core\Plug\Web3\` (PSR-4 from `src/`)

**Six providers**, each under `src/{Provider}/`:
- **Bluesky** — AT Protocol, app passwords, optional custom PDS via `withPds()`
- **Farcaster** — Neynar API, managed signers via `withSigner()` + `withApiKey()`
- **Lemmy** — REST API v3, username/password JWT auth, federated via `forInstance()`
- **Mastodon** — REST API v1, OAuth 2.0, federated via `forInstance()`
- **Nostr** — Cryptographic key pairs (secp256k1), relay-based publishing, no HTTP auth
- **Threads** — Meta Graph API, OAuth 2.0, two-step container+publish flow

**Each provider has up to 5 classes** implementing contracts from `Core\Plug\Contract\`:
- `Auth` implements `Authenticable` — authentication/token exchange
- `Post` implements `Postable` — publishing content (`publish(string $text, Collection $media, array $params)`)
- `Read` implements `Readable` — fetching content (`get()`, `me()`, `list()`)
- `Delete` implements `Deletable` — removing content
- `Media` implements `MediaUploadable` — file uploads (Mastodon, Bluesky only)
- Lemmy also has `Comment` and `Communities` (implements `Listable`)

**Shared behaviour via concerns** from `Core\Plug\Concern\`:
- `BuildsResponse` — wraps API responses into `Core\Plug\Response` (`fromHttp()`, `ok()`, `error()`)
- `UsesHttp` — provides `$this->http()` (Laravel HTTP client)
- `ManagesTokens` — `withToken()`, `accessToken()`, `getToken()`

**Key patterns:**
- All public methods return `Core\Plug\Response`
- Federated providers (Mastodon, Lemmy) require instance URL set via `forInstance()` before API calls
- `Post::publish()` has a uniform signature across all providers; provider-specific options go in `$params`
- Each provider has static `externalPostUrl()` and `externalAccountUrl()` helpers for generating web URLs
- Strict types declared in every file; PHP 8.2+ required