Extending: Build Your Own Adapter

namespace Scholarly\Adapters\YourApi;

use Scholarly\Contracts\{ScholarlyDataSource, Query, Paginator};
use Scholarly\Core\Client;

final class DataSource implements ScholarlyDataSource
{
    public function __construct(private Client $client, private array $config = []) {}

    public function searchWorks(Query $query): Paginator { /* return new YourApiPaginator(...) */ }
    public function getWorkById(string $id): ?array { /* GET /works/{id} */ }
    public function getWorkByDoi(string $doi): ?array { /* optional */ }
    public function getWorkByArxiv(string $arxivId): ?array { /* optional */ }
    public function getWorkByPubmed(string $pmid): ?array { /* optional */ }
    public function listCitations(string $id, Query $query): Paginator { /* /citations */ }
    public function listReferences(string $id, Query $query): Paginator { /* /references */ }
    public function batchWorksByIds(iterable $ids, Query $query): iterable { /* chunk + yield */ }
    public function searchAuthors(Query $query): Paginator { /* /authors */ }
    public function getAuthorById(string $id): ?array { /* /authors/{id} */ }
    public function getAuthorByOrcid(string $orcid): ?array { /* optional */ }
    public function batchAuthorsByIds(iterable $ids, Query $query): iterable { /* chunk + yield */ }
    public function health(): bool { /* lightweight GET */ }
    public function rateLimitState(): array { /* from headers or local counters */ }
}

$response = $this->client->get('https://api.yourapi.io/works', [
    'query' => $this->buildWorkSearchParams($query),
]);

// The client handles:
// - retries with jittered backoff for 429/5xx
// - Retry-After parsing
// - mapping errors to domain exceptions
// - logging

final class YourApiPaginator implements Paginator
{
    public function __construct(private Client $client, private string $url, private array $params) {}

    public function page(): array { /* call, normalize items, return nextCursor */ }
    public function getIterator(): \Traversable { /* loop until nextCursor is null */ }
}

private function mapWork(array $row): array
{
    return [
        'id' => 'yourapi:'.$row['id'],
        'title' => $row['title'] ?? '',
        'year' => (int)($row['year'] ?? 0),
        'venue' => $row['venue']['name'] ?? null,
        'authors' => array_map(fn($a) => [
            'id' => 'yourapi:'.$a['id'],
            'name' => trim(($a['given'] ?? '').' '.($a['family'] ?? '')),
            'orcid' => $a['orcid'] ?? null,
        ], $row['authors'] ?? []),
        'counts' => ['citations' => (int)($row['citationCount'] ?? 0)],
        'external_ids' => [
            'doi' => $row['doi'] ?? null,
            'arxiv' => $row['arxivId'] ?? null,
            'pmid' => $row['pmid'] ?? null,
        ],
    ];
}