Add export and discovery utilities

src/Discovery/DiscoveryResult.php

···
+<?php
+
+namespace SocialDept\AtpParity\Discovery;
+
+/**
+ * Immutable value object representing the result of a discovery operation.
+ */
+readonly class DiscoveryResult
+{
+    public function __construct(
+        public bool $success,
+        public array $dids = [],
+        public int $total = 0,
+        public ?string $error = null,
+        public bool $incomplete = false,
+    ) {}
+
+    /**
+     * Check if the discovery operation succeeded.
+     */
+    public function isSuccess(): bool
+    {
+        return $this->success;
+    }
+
+    /**
+     * Check if the discovery operation failed.
+     */
+    public function isFailed(): bool
+    {
+        return ! $this->success;
+    }
+
+    /**
+     * Check if the discovery was stopped before completion (e.g., limit reached).
+     */
+    public function isIncomplete(): bool
+    {
+        return $this->incomplete;
+    }
+
+    /**
+     * Create a successful result.
+     */
+    public static function success(array $dids, bool $incomplete = false): self
+    {
+        return new self(
+            success: true,
+            dids: $dids,
+            total: count($dids),
+            incomplete: $incomplete,
+        );
+    }
+
+    /**
+     * Create a failed result.
+     */
+    public static function failed(string $error): self
+    {
+        return new self(
+            success: false,
+            error: $error,
+        );
+    }
+}

src/Discovery/DiscoveryService.php

···
+<?php
+
+namespace SocialDept\AtpParity\Discovery;
+
+use BackedEnum;
+use Generator;
+use SocialDept\AtpClient\Facades\Atp;
+use SocialDept\AtpParity\Import\ImportService;
+use Throwable;
+
+/**
+ * Service for discovering DIDs with records in specific collections.
+ */
+class DiscoveryService
+{
+    public function __construct(
+        protected ImportService $importService
+    ) {}
+
+    /**
+     * Discover all DIDs with records in a collection.
+     *
+     * @return Generator<string> Yields DIDs
+     */
+    public function discoverDids(string|BackedEnum $collection, ?int $limit = null): Generator
+    {
+        $collection = $collection instanceof BackedEnum ? $collection->value : $collection;
+        $cursor = null;
+        $count = 0;
+
+        do {
+            $response = Atp::atproto->sync->listReposByCollection(
+                collection: $collection,
+                limit: min(500, $limit ? $limit - $count : 500),
+                cursor: $cursor,
+            );
+
+            foreach ($response->repos as $repo) {
+                $did = $repo['did'] ?? null;
+
+                if ($did) {
+                    yield $did;
+                    $count++;
+
+                    if ($limit !== null && $count >= $limit) {
+                        return;
+                    }
+                }
+            }
+
+            $cursor = $response->cursor;
+        } while ($cursor !== null);
+    }
+
+    /**
+     * Discover DIDs and return as an array.
+     */
+    public function discover(string|BackedEnum $collection, ?int $limit = null): DiscoveryResult
+    {
+        try {
+            $dids = iterator_to_array($this->discoverDids($collection, $limit));
+            $incomplete = $limit !== null && count($dids) >= $limit;
+
+            return DiscoveryResult::success($dids, $incomplete);
+        } catch (Throwable $e) {
+            return DiscoveryResult::failed($e->getMessage());
+        }
+    }
+
+    /**
+     * Discover and import all users for a collection.
+     */
+    public function discoverAndImport(
+        string|BackedEnum $collection,
+        ?int $limit = null,
+        ?callable $onProgress = null
+    ): DiscoveryResult {
+        $collection = $collection instanceof BackedEnum ? $collection->value : $collection;
+
+        try {
+            $dids = [];
+            $count = 0;
+
+            foreach ($this->discoverDids($collection, $limit) as $did) {
+                $dids[] = $did;
+                $count++;
+
+                // Start import for this DID
+                $this->importService->import($did, [$collection]);
+
+                if ($onProgress) {
+                    $onProgress($did, $count);
+                }
+            }
+
+            $incomplete = $limit !== null && count($dids) >= $limit;
+
+            return DiscoveryResult::success($dids, $incomplete);
+        } catch (Throwable $e) {
+            return DiscoveryResult::failed($e->getMessage());
+        }
+    }
+
+    /**
+     * Count total DIDs with records in a collection.
+     *
+     * Note: This iterates through all results, which can be slow.
+     */
+    public function count(string|BackedEnum $collection): int
+    {
+        $count = 0;
+
+        foreach ($this->discoverDids($collection) as $_) {
+            $count++;
+        }
+
+        return $count;
+    }
+}

src/Export/ExportResult.php

···
+<?php
+
+namespace SocialDept\AtpParity\Export;
+
+/**
+ * Value object representing the result of an export operation.
+ */
+readonly class ExportResult
+{
+    public function __construct(
+        public bool $success,
+        public ?string $path = null,
+        public ?int $size = null,
+        public ?string $error = null,
+    ) {}
+
+    /**
+     * Check if the export operation succeeded.
+     */
+    public function isSuccess(): bool
+    {
+        return $this->success;
+    }
+
+    /**
+     * Check if the export operation failed.
+     */
+    public function isFailed(): bool
+    {
+        return ! $this->success;
+    }
+
+    /**
+     * Create a successful result.
+     */
+    public static function success(string $path, int $size): self
+    {
+        return new self(
+            success: true,
+            path: $path,
+            size: $size,
+        );
+    }
+
+    /**
+     * Create a failed result.
+     */
+    public static function failed(string $error): self
+    {
+        return new self(
+            success: false,
+            error: $error,
+        );
+    }
+}

src/Export/ExportService.php

···
+<?php
+
+namespace SocialDept\AtpParity\Export;
+
+use BackedEnum;
+use Generator;
+use SocialDept\AtpClient\Facades\Atp;
+use SocialDept\AtpParity\Import\ImportService;
+use SocialDept\AtpParity\MapperRegistry;
+use Throwable;
+
+/**
+ * Service for exporting AT Protocol repositories.
+ */
+class ExportService
+{
+    public function __construct(
+        protected MapperRegistry $registry,
+        protected ImportService $importService
+    ) {}
+
+    /**
+     * Download a user's repository as CAR data.
+     */
+    public function downloadRepo(string $did, ?string $since = null): RepoExport
+    {
+        $response = Atp::atproto->sync->getRepo($did, $since);
+        $carData = $response->body();
+
+        return new RepoExport(
+            did: $did,
+            carData: $carData,
+            size: strlen($carData),
+        );
+    }
+
+    /**
+     * Export a repository to a local file.
+     */
+    public function exportToFile(string $did, string $path, ?string $since = null): ExportResult
+    {
+        try {
+            $export = $this->downloadRepo($did, $since);
+
+            if (! $export->saveTo($path)) {
+                return ExportResult::failed("Failed to write to file: {$path}");
+            }
+
+            return ExportResult::success($path, $export->size);
+        } catch (Throwable $e) {
+            return ExportResult::failed($e->getMessage());
+        }
+    }
+
+    /**
+     * Export and import records from a repository.
+     *
+     * This downloads the repository and imports records using the normal import pipeline.
+     * It's useful for bulk importing all records from a user.
+     *
+     * @param  array<string>|null  $collections  Specific collections to import (null = all registered)
+     */
+    public function exportAndImport(
+        string $did,
+        ?array $collections = null,
+        ?callable $onProgress = null
+    ): ExportResult {
+        try {
+            // Use the import service to import the user's records
+            $result = $this->importService->importUser($did, $collections, $onProgress);
+
+            if ($result->isFailed()) {
+                return ExportResult::failed($result->error ?? 'Import failed');
+            }
+
+            return ExportResult::success(
+                path: "imported:{$did}",
+                size: $result->recordsSynced
+            );
+        } catch (Throwable $e) {
+            return ExportResult::failed($e->getMessage());
+        }
+    }
+
+    /**
+     * List available blobs for a repository.
+     *
+     * @return Generator<string> Yields blob CIDs
+     */
+    public function listBlobs(string $did, ?string $since = null): Generator
+    {
+        $cursor = null;
+
+        do {
+            $response = Atp::atproto->sync->listBlobs(
+                did: $did,
+                since: $since,
+                limit: 500,
+                cursor: $cursor,
+            );
+
+            foreach ($response->cids as $cid) {
+                yield $cid;
+            }
+
+            $cursor = $response->cursor;
+        } while ($cursor !== null);
+    }
+
+    /**
+     * Download a specific blob.
+     */
+    public function downloadBlob(string $did, string $cid): string
+    {
+        $response = Atp::atproto->sync->getBlob($did, $cid);
+
+        return $response->body();
+    }
+
+    /**
+     * Get the latest commit for a repository.
+     */
+    public function getLatestCommit(string $did): array
+    {
+        $commit = Atp::atproto->sync->getLatestCommit($did);
+
+        return [
+            'cid' => $commit->cid,
+            'rev' => $commit->rev,
+        ];
+    }
+
+    /**
+     * Get the hosting status for a repository.
+     */
+    public function getRepoStatus(string $did): array
+    {
+        $status = Atp::atproto->sync->getRepoStatus($did);
+
+        return $status->toArray();
+    }
+}

src/Export/RepoExport.php

···
+<?php
+
+namespace SocialDept\AtpParity\Export;
+
+/**
+ * Value object representing an exported repository as CAR data.
+ */
+readonly class RepoExport
+{
+    public function __construct(
+        public string $did,
+        public string $carData,
+        public int $size,
+    ) {}
+
+    /**
+     * Save the CAR data to a file.
+     */
+    public function saveTo(string $path): bool
+    {
+        return file_put_contents($path, $this->carData) !== false;
+    }
+
+    /**
+     * Get the size in human-readable format.
+     */
+    public function humanSize(): string
+    {
+        $units = ['B', 'KB', 'MB', 'GB'];
+        $size = $this->size;
+        $unit = 0;
+
+        while ($size >= 1024 && $unit < count($units) - 1) {
+            $size /= 1024;
+            $unit++;
+        }
+
+        return round($size, 2).' '.$units[$unit];
+    }
+}