@univ-lehavre/atlas-citation-fetch

Client OpenAlex centralisé pour les applications et CLI Atlas.

Ce package fournit des fonctions typées pour rechercher des institutions, auteurs et travaux, compter les publications, calculer des statistiques par institution et suivre les informations de rate limit. Il s'appuie sur une file de requêtes et un store Effect pour paginer les réponses OpenAlex avec User-Agent et clé API optionnelle.

Installation

pnpm add @univ-lehavre/atlas-citation-fetch

Configuration

import type { CitationConfig } from '@univ-lehavre/atlas-citation-fetch';

const config: CitationConfig = {
  userAgent: 'my-app/1.0 (mailto:[email protected])',
  apiKey: process.env.OPENALEX_API_KEY,   // optional
  apiURL: 'https://api.openalex.org',     // optional, default
};

API

Institutions

searchInstitutions(query, config)

Searches institutions via the OpenAlex autocomplete endpoint.

import { searchInstitutions } from '@univ-lehavre/atlas-citation-fetch';
import { Effect } from 'effect';

const result = await Effect.runPromise(searchInstitutions('Le Havre', config));
// result.institutions: Institution[]
// result.rateLimit?: RateLimitInfo

Works

getWorksCount(institutionIds, config)

Returns the count of articles from selected institutions over the last 5 years.

const result = await Effect.runPromise(
  getWorksCount(['https://openalex.org/I123'], config)
);
// result.count, result.fromDate, result.rateLimit?

getInstitutionStats(institutionIds, config)

Fetches works count, articles by year, and authors count in 3 parallel requests.

const stats = await Effect.runPromise(
  getInstitutionStats(['https://openalex.org/I123'], config)
);
// stats.worksCount, stats.articlesCount, stats.articlesByYear, stats.authorsCount

Authors

| Function | Description | |----------|-------------| | searchAuthorsByName(names, config) | Search authors by display name | | searchAuthorsByORCID(orcids, config) | Search authors by ORCID | | searchWorksByAuthorIDs(ids, config) | Fetch works by author OpenAlex IDs | | searchWorksByORCID(orcid, config) | Fetch works by author ORCID | | searchWorksByDOI(dois, config) | Fetch works by DOI |

Pagination (advanced)

For cursor-paginated requests across multiple pages:

| Export | Description | |--------|-------------| | fetchAPIResults<T>(opts) | Fetches all pages and returns results array | | fetchAPIQueue<T>(opts) | Fetches into a queue for streaming | | FetchAPIMinimalConfig | Configuration type for paginated requests |