Merge branch 'refs/heads/dev'

README.md

···
 ATP_SCOPE_REDIRECT=/login
 ```
 
+## Extending the Client
+
+Add custom functionality to AtpClient by registering your own domain clients or request clients. Extensions are lazily instantiated on first access.
+
+### Register Extensions
+
+Register extensions in your service provider's `boot()` method:
+
+```php
+use SocialDept\AtpClient\AtpClient;
+
+// Add a new domain client: $client->analytics
+AtpClient::extend('analytics', fn(AtpClient $atp) => new AnalyticsClient($atp));
+
+// Add to an existing domain: $client->bsky->metrics
+AtpClient::extendDomain('bsky', 'metrics', fn($bsky) => new MetricsClient($bsky));
+```
+
+### Usage
+
+```php
+$client = Atp::as('user.bsky.social');
+
+$client->analytics->trackEvent('post_created');
+$client->bsky->metrics->getEngagement();
+```
+
+For complete documentation including creating custom clients, testing, and advanced patterns, see [docs/extensions.md](docs/extensions.md).
+
 ## Available Commands
 
 ```bash
 # Generate OAuth private key
 php artisan atp-client:generate-key
+
+# Create a domain client extension
+php artisan make:atp-client AnalyticsClient
+
+# Create a request client extension for an existing domain
+php artisan make:atp-request MetricsClient --domain=bsky
 ```
 
 ## Requirements
···
 - [AT Protocol Documentation](https://atproto.com/)
 - [Bluesky API Docs](https://docs.bsky.app/)
 - [CRYPTO.md](CRYPTO.md) - Cryptographic implementation details
+- [docs/extensions.md](docs/extensions.md) - Client extensions guide
 
 ## Support & Contributing
 

config/client.php

···
 
         'redirect_to' => env('ATP_SCOPE_REDIRECT', '/login'),
     ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Generator Settings
+    |--------------------------------------------------------------------------
+    |
+    | Configure paths for the make:atp-client and make:atp-request commands.
+    | Paths are relative to the application base path.
+    |
+    */
+    'generators' => [
+        'client_path' => 'app/Services/Clients',
+        'request_path' => 'app/Services/Clients/Requests',
+    ],
 ];

docs/extensions.md

···
+# Client Extensions
+
+AtpClient provides an extension system that allows you to add custom functionality. You can register domain clients (like `$client->myDomain`) or request clients on existing domains (like `$client->bsky->myFeature`).
+
+## Quick Reference
+
+### Available Methods
+
+| Method | Description |
+|--------|-------------|
+| `AtpClient::extend($name, $callback)` | Register a domain client extension |
+| `AtpClient::extendDomain($domain, $name, $callback)` | Register a request client on an existing domain |
+| `AtpClient::hasExtension($name)` | Check if a domain extension is registered |
+| `AtpClient::hasDomainExtension($domain, $name)` | Check if a request client extension is registered |
+| `AtpClient::flushExtensions()` | Clear all extensions (useful for testing) |
+
+The same methods are available on `AtpPublicClient` for unauthenticated extensions.
+
+### Extension Types
+
+| Type | Access Pattern | Use Case |
+|------|----------------|----------|
+| Domain Client | `$client->myDomain` | Group related functionality under a namespace |
+| Request Client | `$client->bsky->myFeature` | Add methods to an existing domain |
+
+### Generator Commands
+
+Quickly scaffold extension classes using artisan commands:
+
+```bash
+# Create a domain client extension
+php artisan make:atp-client AnalyticsClient
+
+# Create a public domain client extension
+php artisan make:atp-client DiscoverClient --public
+
+# Create a request client extension for an existing domain
+php artisan make:atp-request MetricsClient --domain=bsky
+
+# Create a public request client extension
+php artisan make:atp-request TrendingClient --domain=bsky --public
+```
+
+The generated files are placed in `app/Services/Clients/` (domain clients) and `app/Services/Clients/Requests/` (request clients). You can customize these paths in `config/client.php`:
+
+```php
+'generators' => [
+    'client_path' => 'app/Services/Clients',
+    'request_path' => 'app/Services/Clients/Requests',
+],
+```
+
+## Understanding Extensions
+
+Extensions follow a lazy-loading pattern. When you register an extension, the callback is stored but not executed. The extension is only instantiated when first accessed:
+
+```php
+// Registration - callback stored, not executed
+AtpClient::extend('analytics', fn($atp) => new AnalyticsClient($atp));
+
+// First access - callback executed, instance cached
+$client->analytics->trackEvent('login');
+
+// Subsequent access - cached instance returned
+$client->analytics->trackEvent('post_created');
+```
+
+This ensures extensions don't add overhead unless they're actually used.
+
+## Creating a Domain Client
+
+A domain client adds a new namespace to AtpClient, accessible as a property.
+
+### Step 1: Create Your Client Class
+
+```php
+<?php
+
+namespace App\Atp;
+
+use SocialDept\AtpClient\AtpClient;
+
+class AnalyticsClient
+{
+    protected AtpClient $atp;
+
+    public function __construct(AtpClient $parent)
+    {
+        $this->atp = $parent;
+    }
+
+    public function trackEvent(string $event, array $properties = []): void
+    {
+        // Your analytics logic here
+        // You have full access to the authenticated client via $this->atp
+    }
+
+    public function getEngagementStats(string $actor): array
+    {
+        $profile = $this->atp->bsky->actor->getProfile($actor);
+
+        return [
+            'followers' => $profile->followersCount,
+            'following' => $profile->followsCount,
+            'posts' => $profile->postsCount,
+        ];
+    }
+}
+```
+
+### Step 2: Register the Extension
+
+In your `AppServiceProvider`:
+
+```php
+<?php
+
+namespace App\Providers;
+
+use App\Atp\AnalyticsClient;
+use Illuminate\Support\ServiceProvider;
+use SocialDept\AtpClient\AtpClient;
+
+class AppServiceProvider extends ServiceProvider
+{
+    public function boot(): void
+    {
+        AtpClient::extend('analytics', fn(AtpClient $atp) => new AnalyticsClient($atp));
+    }
+}
+```
+
+### Step 3: Use Your Extension
+
+```php
+use SocialDept\AtpClient\Facades\Atp;
+
+$client = Atp::as('user.bsky.social');
+
+$client->analytics->trackEvent('page_view', ['page' => '/feed']);
+
+$stats = $client->analytics->getEngagementStats('someone.bsky.social');
+```
+
+## Creating a Request Client
+
+A request client extends an existing domain (like `bsky`, `atproto`, `chat`, or `ozone`). This is useful when you want to add methods that logically belong alongside the built-in functionality.
+
+### Step 1: Create Your Request Client Class
+
+Extend the base `Request` class to get access to the parent AtpClient:
+
+```php
+<?php
+
+namespace App\Atp;
+
+use SocialDept\AtpClient\Client\Requests\Request;
+
+class BskyMetricsClient extends Request
+{
+    public function getPostEngagement(string $uri): array
+    {
+        $thread = $this->atp->bsky->feed->getPostThread($uri);
+        $post = $thread->thread['post'] ?? null;
+
+        if (! $post) {
+            return [];
+        }
+
+        return [
+            'likes' => $post['likeCount'] ?? 0,
+            'reposts' => $post['repostCount'] ?? 0,
+            'replies' => $post['replyCount'] ?? 0,
+            'quotes' => $post['quoteCount'] ?? 0,
+        ];
+    }
+
+    public function getAuthorMetrics(string $actor): array
+    {
+        $feed = $this->atp->bsky->feed->getAuthorFeed($actor, limit: 100);
+        $posts = $feed->feed;
+
+        $totalLikes = 0;
+        $totalReposts = 0;
+
+        foreach ($posts as $item) {
+            $totalLikes += $item['post']['likeCount'] ?? 0;
+            $totalReposts += $item['post']['repostCount'] ?? 0;
+        }
+
+        return [
+            'posts_analyzed' => count($posts),
+            'total_likes' => $totalLikes,
+            'total_reposts' => $totalReposts,
+            'avg_likes' => count($posts) > 0 ? $totalLikes / count($posts) : 0,
+        ];
+    }
+}
+```
+
+### Step 2: Register the Extension
+
+```php
+use App\Atp\BskyMetricsClient;
+use SocialDept\AtpClient\AtpClient;
+
+public function boot(): void
+{
+    AtpClient::extendDomain('bsky', 'metrics', fn($bsky) => new BskyMetricsClient($bsky));
+}
+```
+
+The callback receives the domain client instance (`BskyClient` in this case), which is passed to your request client's constructor.
+
+### Step 3: Use Your Extension
+
+```php
+$client = Atp::as('user.bsky.social');
+
+$engagement = $client->bsky->metrics->getPostEngagement('at://did:plc:.../app.bsky.feed.post/...');
+
+$authorMetrics = $client->bsky->metrics->getAuthorMetrics('someone.bsky.social');
+```
+
+## Public Client Extensions
+
+The `AtpPublicClient` supports the same extension system for unauthenticated API access:
+
+```php
+use SocialDept\AtpClient\Client\Public\AtpPublicClient;
+
+// Domain client extension
+AtpPublicClient::extend('discover', fn($atp) => new DiscoverClient($atp));
+
+// Request client extension on existing domain
+AtpPublicClient::extendDomain('bsky', 'trending', fn($bsky) => new TrendingClient($bsky));
+```
+
+For public request clients, extend `PublicRequest` instead of `Request`:
+
+```php
+<?php
+
+namespace App\Atp;
+
+use SocialDept\AtpClient\Client\Public\Requests\PublicRequest;
+
+class TrendingPublicClient extends PublicRequest
+{
+    public function getPopularFeeds(int $limit = 10): array
+    {
+        return $this->atp->bsky->feed->getPopularFeedGenerators($limit)->feeds;
+    }
+}
+```
+
+## Registering Multiple Extensions
+
+You can register multiple extensions in your service provider:
+
+```php
+public function boot(): void
+{
+    // Domain clients
+    AtpClient::extend('analytics', fn($atp) => new AnalyticsClient($atp));
+    AtpClient::extend('moderation', fn($atp) => new ModerationClient($atp));
+
+    // Request clients
+    AtpClient::extendDomain('bsky', 'metrics', fn($bsky) => new BskyMetricsClient($bsky));
+    AtpClient::extendDomain('bsky', 'lists', fn($bsky) => new BskyListsClient($bsky));
+    AtpClient::extendDomain('atproto', 'backup', fn($atproto) => new RepoBackupClient($atproto));
+
+    // Public client extensions
+    AtpPublicClient::extend('discover', fn($atp) => new DiscoverClient($atp));
+}
+```
+
+## Conditional Registration
+
+Register extensions conditionally based on environment or configuration:
+
+```php
+public function boot(): void
+{
+    if (config('services.analytics.enabled')) {
+        AtpClient::extend('analytics', fn($atp) => new AnalyticsClient($atp));
+    }
+
+    if (app()->environment('local')) {
+        AtpClient::extend('debug', fn($atp) => new DebugClient($atp));
+    }
+}
+```
+
+## Testing Extensions
+
+### Test Isolation
+
+Use `flushExtensions()` to clear registered extensions between tests:
+
+```php
+use SocialDept\AtpClient\AtpClient;
+use PHPUnit\Framework\TestCase;
+
+class MyExtensionTest extends TestCase
+{
+    protected function setUp(): void
+    {
+        parent::setUp();
+        AtpClient::flushExtensions();
+    }
+
+    protected function tearDown(): void
+    {
+        AtpClient::flushExtensions();
+        parent::tearDown();
+    }
+
+    public function test_extension_is_registered(): void
+    {
+        AtpClient::extend('test', fn($atp) => new TestClient($atp));
+
+        $this->assertTrue(AtpClient::hasExtension('test'));
+    }
+}
+```
+
+### Checking Registration
+
+Use the static methods to verify extensions are registered:
+
+```php
+// Check domain extension
+if (AtpClient::hasExtension('analytics')) {
+    $client->analytics->trackEvent('test');
+}
+
+// Check request client extension
+if (AtpClient::hasDomainExtension('bsky', 'metrics')) {
+    $metrics = $client->bsky->metrics->getAuthorMetrics($actor);
+}
+```
+
+## Advanced Patterns
+
+### Accessing the HTTP Client
+
+Domain client extensions can access the underlying HTTP client for custom API calls:
+
+```php
+class CustomApiClient
+{
+    protected AtpClient $atp;
+
+    public function __construct(AtpClient $parent)
+    {
+        $this->atp = $parent;
+    }
+
+    public function customEndpoint(array $params): array
+    {
+        // Access the authenticated HTTP client
+        $response = $this->atp->client->get('com.example.customEndpoint', $params);
+
+        return $response->json();
+    }
+
+    public function customProcedure(array $data): array
+    {
+        $response = $this->atp->client->post('com.example.customProcedure', $data);
+
+        return $response->json();
+    }
+}
+```
+
+### Using Typed Responses
+
+Return typed response objects for better IDE support:
+
+```php
+use SocialDept\AtpClient\Data\Responses\Response;
+
+class MetricsResponse extends Response
+{
+    public function __construct(
+        public readonly int $likes,
+        public readonly int $reposts,
+        public readonly int $replies,
+    ) {}
+
+    public static function fromArray(array $data): static
+    {
+        return new static(
+            likes: $data['likes'] ?? 0,
+            reposts: $data['reposts'] ?? 0,
+            replies: $data['replies'] ?? 0,
+        );
+    }
+}
+
+class BskyMetricsClient extends Request
+{
+    public function getPostMetrics(string $uri): MetricsResponse
+    {
+        $thread = $this->atp->bsky->feed->getPostThread($uri);
+        $post = $thread->thread['post'] ?? [];
+
+        return MetricsResponse::fromArray([
+            'likes' => $post['likeCount'] ?? 0,
+            'reposts' => $post['repostCount'] ?? 0,
+            'replies' => $post['replyCount'] ?? 0,
+        ]);
+    }
+}
+```
+
+### Composing Multiple Clients
+
+Extensions can use other extensions or built-in clients:
+
+```php
+class DashboardClient
+{
+    protected AtpClient $atp;
+
+    public function __construct(AtpClient $parent)
+    {
+        $this->atp = $parent;
+    }
+
+    public function getOverview(string $actor): array
+    {
+        // Use built-in clients
+        $profile = $this->atp->bsky->actor->getProfile($actor);
+        $feed = $this->atp->bsky->feed->getAuthorFeed($actor, limit: 10);
+
+        // Use other extensions (if registered)
+        $metrics = AtpClient::hasDomainExtension('bsky', 'metrics')
+            ? $this->atp->bsky->metrics->getAuthorMetrics($actor)
+            : null;
+
+        return [
+            'profile' => $profile,
+            'recent_posts' => $feed->feed,
+            'metrics' => $metrics,
+        ];
+    }
+}
+```
+
+## Available Domains
+
+You can extend these built-in domains with `extendDomain()`:
+
+| Domain | Description |
+|--------|-------------|
+| `bsky` | Bluesky-specific operations (app.bsky.*) |
+| `atproto` | AT Protocol core operations (com.atproto.*) |
+| `chat` | Direct messaging operations (chat.bsky.*) |
+| `ozone` | Moderation tools (tools.ozone.*) |

src/AtpClientServiceProvider.php

···
 use SocialDept\AtpClient\Enums\ScopeEnforcementLevel;
 use SocialDept\AtpClient\Http\Middleware\RequiresScopeMiddleware;
 use SocialDept\AtpClient\Console\GenerateOAuthKeyCommand;
+use SocialDept\AtpClient\Console\MakeAtpClientCommand;
+use SocialDept\AtpClient\Console\MakeAtpRequestCommand;
 use SocialDept\AtpClient\Contracts\CredentialProvider;
 use SocialDept\AtpClient\Contracts\KeyStore;
 use SocialDept\AtpClient\Http\Controllers\ClientMetadataController;
···
 
             $this->commands([
                 GenerateOAuthKeyCommand::class,
+                MakeAtpClientCommand::class,
+                MakeAtpRequestCommand::class,
             ]);
         }
 

src/Console/MakeAtpClientCommand.php

···
+<?php
+
+namespace SocialDept\AtpClient\Console;
+
+use Illuminate\Console\Command;
+use Illuminate\Filesystem\Filesystem;
+use Illuminate\Support\Str;
+
+class MakeAtpClientCommand extends Command
+{
+    protected $signature = 'make:atp-client
+                            {name : The name of the client class}
+                            {--public : Generate a public client extension instead of authenticated}
+                            {--force : Overwrite existing file}';
+
+    protected $description = 'Create a new ATP domain client extension';
+
+    public function __construct(protected Filesystem $files)
+    {
+        parent::__construct();
+    }
+
+    public function handle(): int
+    {
+        $name = $this->argument('name');
+        $isPublic = $this->option('public');
+
+        if (! Str::endsWith($name, 'Client')) {
+            $name .= 'Client';
+        }
+
+        $path = $this->getPath($name);
+
+        if ($this->files->exists($path) && ! $this->option('force')) {
+            $this->components->error("Client [{$name}] already exists!");
+
+            return self::FAILURE;
+        }
+
+        $this->makeDirectory($path);
+
+        $stub = $isPublic ? $this->getPublicStub() : $this->getStub();
+        $content = $this->populateStub($stub, $name);
+
+        $this->files->put($path, $content);
+
+        $this->components->info("Client [{$path}] created successfully.");
+
+        $this->outputRegistrationHint($name, $isPublic);
+
+        return self::SUCCESS;
+    }
+
+    protected function getPath(string $name): string
+    {
+        $basePath = config('client.generators.client_path', 'app/Services/Clients');
+
+        return base_path($basePath.'/'.$name.'.php');
+    }
+
+    protected function makeDirectory(string $path): void
+    {
+        if (! $this->files->isDirectory(dirname($path))) {
+            $this->files->makeDirectory(dirname($path), 0755, true);
+        }
+    }
+
+    protected function getNamespace(): string
+    {
+        $basePath = config('client.generators.client_path', 'app/Services/Clients');
+
+        return Str::of($basePath)
+            ->replace('/', '\\')
+            ->ucfirst()
+            ->replace('App', 'App')
+            ->toString();
+    }
+
+    protected function populateStub(string $stub, string $name): string
+    {
+        return str_replace(
+            ['{{ namespace }}', '{{ class }}'],
+            [$this->getNamespace(), $name],
+            $stub
+        );
+    }
+
+    protected function outputRegistrationHint(string $name, bool $isPublic): void
+    {
+        $this->newLine();
+        $this->components->info('Register the extension in your AppServiceProvider:');
+        $this->newLine();
+
+        $namespace = $this->getNamespace();
+        $extensionName = Str::of($name)->before('Client')->camel()->toString();
+        $clientClass = $isPublic ? 'AtpPublicClient' : 'AtpClient';
+
+        $this->line("use {$namespace}\\{$name};");
+        $this->line("use SocialDept\\AtpClient\\".($isPublic ? 'Client\\Public\\' : '').$clientClass.';');
+        $this->newLine();
+        $this->line("// In boot() method:");
+        $this->line("{$clientClass}::extend('{$extensionName}', fn(\${$clientClass} \$atp) => new {$name}(\$atp));");
+    }
+
+    protected function getStub(): string
+    {
+        return <<<'STUB'
+<?php
+
+namespace {{ namespace }};
+
+use SocialDept\AtpClient\AtpClient;
+
+class {{ class }}
+{
+    protected AtpClient $atp;
+
+    public function __construct(AtpClient $parent)
+    {
+        $this->atp = $parent;
+    }
+
+    //
+}
+STUB;
+    }
+
+    protected function getPublicStub(): string
+    {
+        return <<<'STUB'
+<?php
+
+namespace {{ namespace }};
+
+use SocialDept\AtpClient\Client\Public\AtpPublicClient;
+
+class {{ class }}
+{
+    protected AtpPublicClient $atp;
+
+    public function __construct(AtpPublicClient $parent)
+    {
+        $this->atp = $parent;
+    }
+
+    //
+}
+STUB;
+    }
+}

src/Console/MakeAtpRequestCommand.php

···
+<?php
+
+namespace SocialDept\AtpClient\Console;
+
+use Illuminate\Console\Command;
+use Illuminate\Filesystem\Filesystem;
+use Illuminate\Support\Str;
+
+class MakeAtpRequestCommand extends Command
+{
+    protected $signature = 'make:atp-request
+                            {name : The name of the request client class}
+                            {--domain=bsky : The domain to extend (bsky, atproto, chat, ozone)}
+                            {--public : Generate a public request client instead of authenticated}
+                            {--force : Overwrite existing file}';
+
+    protected $description = 'Create a new ATP request client extension for an existing domain';
+
+    protected array $validDomains = ['bsky', 'atproto', 'chat', 'ozone'];
+
+    public function __construct(protected Filesystem $files)
+    {
+        parent::__construct();
+    }
+
+    public function handle(): int
+    {
+        $name = $this->argument('name');
+        $domain = $this->option('domain');
+        $isPublic = $this->option('public');
+
+        if (! in_array($domain, $this->validDomains)) {
+            $this->components->error("Invalid domain [{$domain}]. Valid domains: ".implode(', ', $this->validDomains));
+
+            return self::FAILURE;
+        }
+
+        if (! Str::endsWith($name, 'Client')) {
+            $name .= 'Client';
+        }
+
+        $path = $this->getPath($name);
+
+        if ($this->files->exists($path) && ! $this->option('force')) {
+            $this->components->error("Request client [{$name}] already exists!");
+
+            return self::FAILURE;
+        }
+
+        $this->makeDirectory($path);
+
+        $stub = $isPublic ? $this->getPublicStub() : $this->getStub();
+        $content = $this->populateStub($stub, $name);
+
+        $this->files->put($path, $content);
+
+        $this->components->info("Request client [{$path}] created successfully.");
+
+        $this->outputRegistrationHint($name, $domain, $isPublic);
+
+        return self::SUCCESS;
+    }
+
+    protected function getPath(string $name): string
+    {
+        $basePath = config('client.generators.request_path', 'app/Services/Clients/Requests');
+
+        return base_path($basePath.'/'.$name.'.php');
+    }
+
+    protected function makeDirectory(string $path): void
+    {
+        if (! $this->files->isDirectory(dirname($path))) {
+            $this->files->makeDirectory(dirname($path), 0755, true);
+        }
+    }
+
+    protected function getNamespace(): string
+    {
+        $basePath = config('client.generators.request_path', 'app/Services/Clients/Requests');
+
+        return Str::of($basePath)
+            ->replace('/', '\\')
+            ->ucfirst()
+            ->replace('App', 'App')
+            ->toString();
+    }
+
+    protected function populateStub(string $stub, string $name): string
+    {
+        return str_replace(
+            ['{{ namespace }}', '{{ class }}'],
+            [$this->getNamespace(), $name],
+            $stub
+        );
+    }
+
+    protected function outputRegistrationHint(string $name, string $domain, bool $isPublic): void
+    {
+        $this->newLine();
+        $this->components->info('Register the extension in your AppServiceProvider:');
+        $this->newLine();
+
+        $namespace = $this->getNamespace();
+        $extensionName = Str::of($name)->before('Client')->camel()->toString();
+        $clientClass = $isPublic ? 'AtpPublicClient' : 'AtpClient';
+
+        $this->line("use {$namespace}\\{$name};");
+        $this->line("use SocialDept\\AtpClient\\".($isPublic ? 'Client\\Public\\' : '').$clientClass.';');
+        $this->newLine();
+        $this->line("// In boot() method:");
+        $this->line("{$clientClass}::extendDomain('{$domain}', '{$extensionName}', fn(\$domain) => new {$name}(\$domain));");
+    }
+
+    protected function getStub(): string
+    {
+        return <<<'STUB'
+<?php
+
+namespace {{ namespace }};
+
+use SocialDept\AtpClient\Client\Requests\Request;
+
+class {{ class }} extends Request
+{
+    //
+}
+STUB;
+    }
+
+    protected function getPublicStub(): string
+    {
+        return <<<'STUB'
+<?php
+
+namespace {{ namespace }};
+
+use SocialDept\AtpClient\Client\Public\Requests\PublicRequest;
+
+class {{ class }} extends PublicRequest
+{
+    //
+}
+STUB;
+    }
+}