49 lines
2.4 KiB
Markdown
49 lines
2.4 KiB
Markdown
|
# 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
|