@everdeep/pubmed 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,432 @@
+type PubMedErrorCode = "VALIDATION_ERROR" | "HTTP_ERROR" | "RATE_LIMIT_ERROR" | "TIMEOUT_ERROR" | "NETWORK_ERROR" | "RESPONSE_TOO_LARGE" | "QUEUE_FULL" | "PARSE_ERROR" | "INVALID_RESPONSE" | "CURSOR_EXPIRED" | "CURSOR_INVALID" | "ABORTED" | "SEARCH_LIMIT";
+declare class PubMedError extends Error {
+    readonly code: PubMedErrorCode;
+    readonly retryable: boolean;
+    constructor(message: string, code: PubMedErrorCode, retryable?: boolean, options?: ErrorOptions);
+    toJSON(): Readonly<{
+        name: string;
+        message: string;
+        code: PubMedErrorCode;
+        retryable: boolean;
+    }>;
+}
+declare class ValidationError extends PubMedError {
+    constructor(message: string);
+}
+declare class HttpError extends PubMedError {
+    readonly status: number;
+    constructor(status: number, retryable: boolean);
+}
+declare class RateLimitError extends PubMedError {
+    readonly status = 429;
+    constructor();
+}
+declare class TimeoutError extends PubMedError {
+    constructor(options?: ErrorOptions);
+}
+declare class NetworkError extends PubMedError {
+    constructor(options?: ErrorOptions);
+}
+declare class ResponseTooLargeError extends PubMedError {
+    readonly limitBytes: number;
+    constructor(limitBytes: number);
+}
+declare class QueueFullError extends PubMedError {
+    constructor();
+}
+declare class ParseError extends PubMedError {
+    constructor(message?: string, options?: ErrorOptions);
+}
+declare class InvalidResponseError extends PubMedError {
+    constructor(message?: string, options?: ErrorOptions);
+}
+declare class CursorExpiredError extends PubMedError {
+    constructor();
+}
+declare class CursorInvalidError extends PubMedError {
+    constructor();
+}
+declare class AbortedError extends PubMedError {
+    constructor(options?: ErrorOptions);
+}
+declare class SearchLimitError extends PubMedError {
+    readonly limit: number;
+    constructor(limit?: number);
+}
+
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonObject | readonly JsonValue[];
+interface JsonObject {
+    readonly [key: string]: JsonValue;
+}
+interface PubMedIdentifier {
+    readonly type: string;
+    readonly value: string;
+    readonly provenance: "citation" | "article-id" | "book";
+}
+interface PubMedLink {
+    readonly url: string;
+    readonly type: "pubmed" | "doi" | "pmc" | "linkout";
+    readonly provenance: "canonical" | "ncbi-linkout";
+    readonly provider?: Readonly<{
+        name?: string;
+        abbreviation?: string;
+        id?: string;
+    }>;
+}
+interface PartialDate {
+    readonly year?: string;
+    readonly month?: string;
+    readonly day?: string;
+    readonly season?: string;
+    readonly medlineDate?: string;
+    readonly hour?: string;
+    readonly minute?: string;
+    readonly second?: string;
+}
+interface AbstractSection {
+    readonly text: string;
+    readonly label?: string;
+    readonly category?: string;
+    /** @deprecated Copyright applies to the full abstract; use BasePubMedRecord.abstractCopyright. */
+    readonly copyright?: string;
+}
+interface Affiliation {
+    readonly text: string;
+    readonly identifiers: readonly PubMedIdentifier[];
+}
+interface AuthorIdentifier {
+    readonly source?: string;
+    readonly value: string;
+}
+interface PersonalAuthor {
+    readonly type: "personal";
+    readonly lastName?: string;
+    readonly foreName?: string;
+    readonly initials?: string;
+    readonly suffix?: string;
+    readonly fullName: string;
+    readonly valid?: boolean;
+    readonly affiliations: readonly Affiliation[];
+    readonly identifiers: readonly AuthorIdentifier[];
+    readonly orcid?: string;
+}
+interface CollectiveAuthor {
+    readonly type: "collective";
+    readonly name: string;
+    readonly affiliations: readonly Affiliation[];
+    readonly identifiers: readonly AuthorIdentifier[];
+}
+type PubMedAuthor = PersonalAuthor | CollectiveAuthor;
+interface JournalCitation {
+    readonly title?: string;
+    readonly isoAbbreviation?: string;
+    readonly issn?: string;
+    readonly issnType?: string;
+    readonly volume?: string;
+    readonly issue?: string;
+    readonly pagination?: string;
+    readonly pubDate?: PartialDate;
+}
+interface PublicationHistoryEntry {
+    readonly status: string;
+    readonly date: PartialDate;
+}
+interface PublicationDates {
+    readonly completed?: PartialDate;
+    readonly revised?: PartialDate;
+    readonly electronic?: PartialDate;
+    readonly print?: PartialDate;
+    readonly history: readonly PublicationHistoryEntry[];
+}
+interface MeshHeading {
+    readonly descriptor: string;
+    readonly descriptorUi?: string;
+    readonly majorTopic?: boolean;
+    readonly qualifiers: readonly Readonly<{
+        name: string;
+        ui?: string;
+        majorTopic?: boolean;
+    }>[];
+}
+interface Keyword {
+    readonly value: string;
+    readonly owner?: string;
+    readonly majorTopic?: boolean;
+}
+interface PubMedWarning {
+    readonly code: "UNKNOWN_RECORD" | "PARSE_WARNING";
+    readonly message: string;
+    readonly recordType?: string;
+}
+interface BasePubMedRecord {
+    readonly kind: "article" | "book" | "unknown";
+    readonly recordType: string;
+    readonly rawXml: string;
+    readonly source: JsonObject;
+    readonly identifiers: readonly PubMedIdentifier[];
+    readonly links: readonly PubMedLink[];
+    readonly pmid?: string;
+    readonly doi?: string;
+    readonly pmcid?: string;
+    readonly title?: string;
+    readonly abstract: readonly AbstractSection[];
+    readonly abstractCopyright?: string;
+    readonly authors: readonly PubMedAuthor[];
+    readonly languages: readonly string[];
+    readonly publicationTypes: readonly string[];
+    readonly keywords: readonly Keyword[];
+    readonly meshHeadings: readonly MeshHeading[];
+    readonly dates: PublicationDates;
+}
+interface PubMedArticleRecord extends BasePubMedRecord {
+    readonly kind: "article";
+    readonly recordType: "PubmedArticle";
+    readonly vernacularTitle?: string;
+    readonly journal?: JournalCitation;
+    readonly citationStatus?: string;
+}
+interface PubMedBookRecord extends BasePubMedRecord {
+    readonly kind: "book";
+    readonly recordType: "PubmedBookArticle";
+    readonly book?: Readonly<{
+        title?: string;
+        collectionTitle?: string;
+        publisher?: string;
+        location?: string;
+        edition?: string;
+        isbn: readonly string[];
+    }>;
+}
+interface UnknownPubMedRecord extends BasePubMedRecord {
+    readonly kind: "unknown";
+}
+type PubMedRecord = PubMedArticleRecord | PubMedBookRecord | UnknownPubMedRecord;
+interface PubMedSummaryAuthor {
+    readonly name: string;
+    readonly type?: string;
+    readonly clusterId?: string;
+}
+interface PubMedSummaryIdentifier {
+    readonly type: string;
+    readonly value: string;
+    readonly numericType?: number;
+}
+interface PubMedSummaryHistoryEntry {
+    readonly status: string;
+    readonly date: string;
+}
+interface PubMedSummaryJournal {
+    readonly title?: string;
+    readonly abbreviation?: string;
+    readonly issn?: string;
+    readonly electronicIssn?: string;
+    readonly volume?: string;
+    readonly issue?: string;
+    readonly pages?: string;
+}
+interface PubMedSummaryBook {
+    readonly title?: string;
+    readonly name?: string;
+    readonly chapter?: string;
+    readonly edition?: string;
+    readonly publisher?: string;
+    readonly location?: string;
+}
+/** Lightweight metadata returned by the PubMed ESummary endpoint. */
+interface PubMedSummary {
+    readonly kind: "summary";
+    readonly uid: string;
+    readonly pmid: string;
+    /** The validated JSON object for this UID, retained for forward compatibility. */
+    readonly source: JsonObject;
+    readonly title?: string;
+    readonly sortTitle?: string;
+    readonly authors: readonly PubMedSummaryAuthor[];
+    readonly lastAuthor?: string;
+    readonly sortFirstAuthor?: string;
+    readonly journal?: PubMedSummaryJournal;
+    readonly book?: PubMedSummaryBook;
+    readonly publicationDate?: string;
+    readonly electronicPublicationDate?: string;
+    readonly sortPublicationDate?: string;
+    /** Electronic article locator, for example an article number instead of page range. */
+    readonly electronicLocationId?: string;
+    readonly sourceDate?: string;
+    readonly documentDate?: string;
+    readonly languages: readonly string[];
+    readonly publicationTypes: readonly string[];
+    readonly identifiers: readonly PubMedSummaryIdentifier[];
+    readonly history: readonly PubMedSummaryHistoryEntry[];
+    readonly doi?: string;
+    readonly pmcid?: string;
+    readonly recordStatus?: string;
+    readonly publicationStatus?: string;
+    readonly documentType?: string;
+    readonly medium?: string;
+    readonly edition?: string;
+    readonly publisher?: string;
+    readonly publisherLocation?: string;
+    readonly reportNumber?: string;
+    readonly availableFromUrl?: string;
+}
+interface SummaryBatchResult {
+    readonly summaries: readonly PubMedSummary[];
+    readonly missingPmids: readonly string[];
+}
+type CitationFormat = "ris" | "bibtex";
+type CitationSource = PubMedArticleRecord | PubMedBookRecord | PubMedSummary;
+interface BatchResult {
+    readonly records: readonly PubMedRecord[];
+    readonly missingPmids: readonly string[];
+    readonly warnings: readonly PubMedWarning[];
+}
+interface SearchBatch extends BatchResult {
+    readonly total: number;
+    readonly nextCursor: string | null;
+}
+interface RequestOptions {
+    readonly includeLinkOuts?: boolean;
+    readonly signal?: AbortSignal;
+}
+interface SummaryRequestOptions {
+    readonly signal?: AbortSignal;
+}
+interface SearchQueryOptions extends RequestOptions {
+    readonly query: string;
+    readonly pageSize?: number;
+    readonly sort?: string;
+    readonly cursor?: never;
+}
+interface SearchCursorOptions extends RequestOptions {
+    readonly cursor: string;
+    readonly query?: never;
+}
+type SearchOptions = SearchQueryOptions | SearchCursorOptions;
+interface SearchAllOptions extends RequestOptions {
+    readonly query: string;
+    readonly maxResults: number;
+    readonly pageSize?: number;
+    readonly sort?: string;
+}
+interface CacheAdapter {
+    get(key: string): Promise<string | undefined>;
+    set(key: string, value: string): Promise<void>;
+    /** Optional best-effort invalidation used when a cached endpoint body fails validation. */
+    delete?(key: string): Promise<void>;
+}
+interface RateLimitBucket {
+    readonly host: string;
+    readonly credentialFingerprint: string;
+    readonly requestsPerSecond: number;
+}
+interface RateLimitCoordinator {
+    acquire(bucket: RateLimitBucket, signal?: AbortSignal): Promise<void>;
+    cooldown?(bucket: RateLimitBucket, delayMs: number): Promise<void>;
+}
+type PubMedEndpoint = "esearch" | "esummary" | "efetch" | "elink";
+type PubMedEvent = Readonly<{
+    type: "correlation-id";
+    endpoint: PubMedEndpoint;
+    correlationId: string;
+}> | Readonly<{
+    type: "cache-hit" | "cache-miss";
+    endpoint: PubMedEndpoint;
+    correlationId: string;
+}> | Readonly<{
+    type: "request-coalesced";
+    endpoint: PubMedEndpoint;
+    correlationId: string;
+    sharedCorrelationId: string;
+}> | Readonly<{
+    type: "response-bytes";
+    endpoint: PubMedEndpoint;
+    correlationId: string;
+    attempt: number;
+    bytes: number;
+}> | Readonly<{
+    type: "terminal-failure";
+    endpoint: PubMedEndpoint;
+    correlationId: string;
+    errorCode: PubMedErrorCode | "UNKNOWN_ERROR";
+}> | Readonly<{
+    type: "request";
+    endpoint: PubMedEndpoint;
+    status: number;
+    durationMs: number;
+    attempt: number;
+    correlationId?: string;
+}> | Readonly<{
+    type: "retry";
+    endpoint: PubMedEndpoint;
+    attempt: number;
+    delayMs: number;
+    reason: "network" | "timeout" | "http";
+    correlationId?: string;
+}> | Readonly<{
+    type: "queue-delay";
+    delayMs: number;
+}> | Readonly<{
+    type: "rate-cooldown";
+    delayMs: number;
+}> | Readonly<{
+    type: "parse-warning";
+    code: PubMedWarning["code"];
+    recordType?: string;
+}>;
+interface PubMedClientOptions {
+    readonly email: string;
+    readonly tool: string;
+    readonly apiKey?: string;
+    readonly fetch?: typeof fetch;
+    readonly cache?: CacheAdapter;
+    readonly rateLimitCoordinator?: RateLimitCoordinator;
+    readonly onEvent?: (event: PubMedEvent) => void;
+    readonly timeoutMs?: number;
+    readonly maxAttempts?: number;
+    readonly maxResponseBytes?: number;
+    readonly maxQueuedRequests?: number;
+    readonly maxBatchSize?: number;
+}
+
+declare class PubMedClient {
+    #private;
+    constructor(options: PubMedClientOptions);
+    get(pmid: string, options?: RequestOptions): Promise<PubMedRecord | null>;
+    getMany(pmids: readonly string[], options?: RequestOptions): Promise<BatchResult>;
+    getSummary(pmid: string, options?: SummaryRequestOptions): Promise<PubMedSummary | null>;
+    getManySummaries(pmids: readonly string[], options?: SummaryRequestOptions): Promise<SummaryBatchResult>;
+    search(options: SearchOptions): Promise<SearchBatch>;
+    searchAll(options: SearchAllOptions): AsyncIterable<SearchBatch>;
+}
+
+interface MemoryCacheOptions {
+    readonly maxEntries?: number;
+    /** Maximum UTF-8 bytes retained across cache keys and values. */
+    readonly maxBytes?: number;
+    readonly ttlMs?: number;
+}
+/** Opt-in bounded, process-local cache. Byte accounting includes UTF-8 keys and values. */
+declare class MemoryCache implements CacheAdapter {
+    #private;
+    constructor(options?: MemoryCacheOptions);
+    get(key: string): Promise<string | undefined>;
+    set(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): void;
+    get size(): number;
+}
+
+/** Formats one PubMed article, book record, or summary as deterministic RIS or BibTeX. */
+declare function formatCitation(source: CitationSource, format: CitationFormat): string;
+/** Formats citations in caller order, separated by one blank line. */
+declare function formatCitations(sources: readonly CitationSource[], format: CitationFormat): string;
+
+interface ParsedPubMedXml {
+    readonly records: readonly PubMedRecord[];
+    readonly warnings: readonly PubMedWarning[];
+}
+/** Parse an entire PubmedArticleSet while retaining each direct child byte-for-byte. */
+declare function parsePubMedXml(xml: string): ParsedPubMedXml;
+
+export { AbortedError, type AbstractSection, type Affiliation, type AuthorIdentifier, type BasePubMedRecord, type BatchResult, type CacheAdapter, type CitationFormat, type CitationSource, type CollectiveAuthor, CursorExpiredError, CursorInvalidError, HttpError, InvalidResponseError, type JournalCitation, type JsonObject, type JsonPrimitive, type JsonValue, type Keyword, MemoryCache, type MemoryCacheOptions, type MeshHeading, NetworkError, ParseError, type ParsedPubMedXml, type PartialDate, type PersonalAuthor, type PubMedArticleRecord, type PubMedAuthor, type PubMedBookRecord, PubMedClient, type PubMedClientOptions, type PubMedEndpoint, PubMedError, type PubMedErrorCode, type PubMedEvent, type PubMedIdentifier, type PubMedLink, type PubMedRecord, type PubMedSummary, type PubMedSummaryAuthor, type PubMedSummaryBook, type PubMedSummaryHistoryEntry, type PubMedSummaryIdentifier, type PubMedSummaryJournal, type PubMedWarning, type PublicationDates, type PublicationHistoryEntry, QueueFullError, type RateLimitBucket, type RateLimitCoordinator, RateLimitError, type RequestOptions, ResponseTooLargeError, type SearchAllOptions, type SearchBatch, type SearchCursorOptions, SearchLimitError, type SearchOptions, type SearchQueryOptions, type SummaryBatchResult, type SummaryRequestOptions, TimeoutError, type UnknownPubMedRecord, ValidationError, formatCitation, formatCitations, parsePubMedXml };