search_paper 0.1.2

package/dist/index.d.cts

@@ -0,0 +1,210 @@
+import { GhostClient } from 'ghostfetch';
+
+type SourceType = 'google_scholar' | 'semantic_scholar' | 'arxiv';
+interface Author {
+    name: string;
+    affiliations?: string[];
+    scholarId?: string;
+    isFirstAuthor?: boolean;
+    isCorresponding?: boolean;
+}
+interface JournalInfo {
+    name?: string;
+    volume?: string;
+    issue?: string;
+}
+interface Section {
+    heading: string;
+    level: number;
+    content?: string;
+}
+interface Figure {
+    label: string;
+    caption?: string;
+    filePath?: string;
+}
+interface Table {
+    label: string;
+    caption?: string;
+    headers?: string[];
+    rows?: string[][];
+}
+interface Paper {
+    title: string;
+    authors: Author[];
+    abstract?: string;
+    year?: number;
+    publicationDate?: string;
+    venue?: string;
+    doi?: string;
+    url: string;
+    canonicalUrl?: string;
+    pdfUrl?: string;
+    citationCount?: number;
+    impactFactor?: number;
+    source: SourceType;
+    sourceId?: string;
+    keywords?: string[];
+    tags?: string[];
+    references?: string[];
+    journal?: JournalInfo;
+    sections?: Section[];
+    figures?: Figure[];
+    tables?: Table[];
+}
+interface SearchResult {
+    query: string;
+    totalResults?: number;
+    papers: Paper[];
+    nextPageToken?: string;
+    source: SourceType;
+    errors?: SourceError[];
+}
+interface SourceError {
+    source: SourceType;
+    message: string;
+    code?: 'RATE_LIMITED' | 'CAPTCHA' | 'TIMEOUT' | 'NETWORK_ERROR' | 'PARSE_ERROR' | 'UNKNOWN';
+}
+interface SearchOptions {
+    sources?: SourceType[];
+    limit?: number;
+    offset?: number;
+    year?: {
+        from?: number;
+        to?: number;
+    };
+    sort?: 'relevance' | 'date' | 'citations';
+    fields?: (keyof Paper)[];
+}
+interface ClientOptions {
+    browser?: string;
+    timeout?: number;
+    proxy?: string;
+    proxyPool?: string[];
+    semanticScholarApiKey?: string;
+}
+
+interface PaperSource {
+    readonly name: SourceType;
+    search(query: string, options?: SearchOptions): Promise<SearchResult>;
+    getPaper(id: string): Promise<Paper | null>;
+}
+interface CitationSource extends PaperSource {
+    getCitations(id: string, options?: SearchOptions): Promise<SearchResult>;
+    getReferences(id: string, options?: SearchOptions): Promise<SearchResult>;
+}
+
+declare function searchPapers(query: string, options?: SearchOptions & {
+    client?: ClientOptions;
+}): Promise<SearchResult>;
+
+declare function getPaper(doi: string, options?: {
+    client?: ClientOptions;
+}): Promise<Paper | null>;
+
+/**
+ * 논문의 전체 상세 정보를 가져옴
+ * - S2 API: 메타데이터 (DOI, 저널, 키워드, 인용수 등)
+ * - ar5iv HTML: 본문 구조 (섹션, 그림, 표, 저자 소속)
+ *
+ * @param id - arXiv ID 또는 DOI
+ */
+declare function getFullPaper(id: string, options?: {
+    client?: ClientOptions;
+}): Promise<Paper | null>;
+
+declare function createClient(options?: ClientOptions): GhostClient;
+
+declare class SemanticScholarSource implements CitationSource {
+    readonly name: "semantic_scholar";
+    private readonly client;
+    private readonly apiKey?;
+    private readonly rateLimiter;
+    constructor(client: GhostClient, options?: ClientOptions);
+    search(query: string, options?: SearchOptions): Promise<SearchResult>;
+    getPaper(id: string): Promise<Paper | null>;
+    getPapers(ids: string[]): Promise<(Paper | null)[]>;
+    getCitations(id: string, options?: SearchOptions): Promise<SearchResult>;
+    getReferences(id: string, options?: SearchOptions): Promise<SearchResult>;
+    private fetchApi;
+}
+
+declare class RateLimiter {
+    private minIntervalMs;
+    private jitterMs;
+    private lastRequest;
+    constructor(minIntervalMs: number, jitterMs?: number);
+    wait(): Promise<void>;
+}
+/**
+ * 적응형 Rate Limiter
+ * - 차단(CAPTCHA 등) 감지 시 딜레이를 지수적으로 증가
+ * - 성공 시 점진적으로 기본값으로 복귀
+ */
+declare class AdaptiveRateLimiter {
+    private readonly baseIntervalMs;
+    private readonly baseJitterMs;
+    private readonly maxIntervalMs;
+    private readonly backoffMultiplier;
+    /** 연속 성공 몇 회 후 딜레이를 줄일지 */
+    private readonly cooldownAfter;
+    /** 딜레이 감소 비율 (0.7 = 30% 감소) */
+    private readonly cooldownFactor;
+    private lastRequest;
+    private currentIntervalMs;
+    private consecutiveSuccesses;
+    constructor(baseIntervalMs: number, baseJitterMs?: number, maxIntervalMs?: number, backoffMultiplier?: number, 
+    /** 연속 성공 몇 회 후 딜레이를 줄일지 */
+    cooldownAfter?: number, 
+    /** 딜레이 감소 비율 (0.7 = 30% 감소) */
+    cooldownFactor?: number);
+    private consecutiveBlocks;
+    /** 현재 적용 중인 인터벌 (ms) */
+    get interval(): number;
+    /** 현재 차단 상태인지 (연속 차단 2회 이상이면 true) */
+    get isBlocked(): boolean;
+    wait(): Promise<void>;
+    /** 요청 성공 시 호출 → 점진적으로 딜레이 감소 */
+    success(): void;
+    /** 차단 감지 시 호출 → 딜레이를 지수적으로 증가 */
+    backoff(): void;
+}
+
+declare class GoogleScholarSource implements PaperSource {
+    readonly name: "google_scholar";
+    private readonly client;
+    private readonly rateLimiter;
+    constructor(client: GhostClient, rateLimiter?: AdaptiveRateLimiter);
+    search(query: string, options?: SearchOptions): Promise<SearchResult>;
+    getPaper(id: string): Promise<Paper | null>;
+}
+
+declare class ArxivSource implements PaperSource {
+    readonly name: "arxiv";
+    private readonly client;
+    private readonly rateLimiter;
+    constructor(client: GhostClient);
+    search(query: string, options?: SearchOptions): Promise<SearchResult>;
+    getPaper(id: string): Promise<Paper | null>;
+    /**
+     * arXiv 논문의 전체 내용을 가져옴 (메타데이터 + ar5iv HTML 파싱)
+     * - API에서 기본 메타데이터 조회
+     * - ar5iv HTML에서 저자(소속 포함), 섹션, 그림, 표 파싱
+     */
+    getFullPaper(id: string): Promise<Paper | null>;
+}
+
+declare function withRetry<T>(fn: () => Promise<T>, options?: {
+    maxRetries?: number;
+    baseDelayMs?: number;
+}): Promise<T>;
+
+declare class HttpError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    constructor(status: number, statusText: string);
+}
+
+declare function deduplicatePapers(papers: Paper[]): Paper[];
+
+export { AdaptiveRateLimiter, ArxivSource, type Author, type CitationSource, type ClientOptions, type Figure, GoogleScholarSource, HttpError, type JournalInfo, type Paper, type PaperSource, RateLimiter, type SearchOptions, type SearchResult, type Section, SemanticScholarSource, type SourceError, type SourceType, type Table, createClient, deduplicatePapers, getFullPaper, getPaper, searchPapers, withRetry };

package/dist/index.d.ts

@@ -0,0 +1,210 @@
+import { GhostClient } from 'ghostfetch';
+
+type SourceType = 'google_scholar' | 'semantic_scholar' | 'arxiv';
+interface Author {
+    name: string;
+    affiliations?: string[];
+    scholarId?: string;
+    isFirstAuthor?: boolean;
+    isCorresponding?: boolean;
+}
+interface JournalInfo {
+    name?: string;
+    volume?: string;
+    issue?: string;
+}
+interface Section {
+    heading: string;
+    level: number;
+    content?: string;
+}
+interface Figure {
+    label: string;
+    caption?: string;
+    filePath?: string;
+}
+interface Table {
+    label: string;
+    caption?: string;
+    headers?: string[];
+    rows?: string[][];
+}
+interface Paper {
+    title: string;
+    authors: Author[];
+    abstract?: string;
+    year?: number;
+    publicationDate?: string;
+    venue?: string;
+    doi?: string;
+    url: string;
+    canonicalUrl?: string;
+    pdfUrl?: string;
+    citationCount?: number;
+    impactFactor?: number;
+    source: SourceType;
+    sourceId?: string;
+    keywords?: string[];
+    tags?: string[];
+    references?: string[];
+    journal?: JournalInfo;
+    sections?: Section[];
+    figures?: Figure[];
+    tables?: Table[];
+}
+interface SearchResult {
+    query: string;
+    totalResults?: number;
+    papers: Paper[];
+    nextPageToken?: string;
+    source: SourceType;
+    errors?: SourceError[];
+}
+interface SourceError {
+    source: SourceType;
+    message: string;
+    code?: 'RATE_LIMITED' | 'CAPTCHA' | 'TIMEOUT' | 'NETWORK_ERROR' | 'PARSE_ERROR' | 'UNKNOWN';
+}
+interface SearchOptions {
+    sources?: SourceType[];
+    limit?: number;
+    offset?: number;
+    year?: {
+        from?: number;
+        to?: number;
+    };
+    sort?: 'relevance' | 'date' | 'citations';
+    fields?: (keyof Paper)[];
+}
+interface ClientOptions {
+    browser?: string;
+    timeout?: number;
+    proxy?: string;
+    proxyPool?: string[];
+    semanticScholarApiKey?: string;
+}
+
+interface PaperSource {
+    readonly name: SourceType;
+    search(query: string, options?: SearchOptions): Promise<SearchResult>;
+    getPaper(id: string): Promise<Paper | null>;
+}
+interface CitationSource extends PaperSource {
+    getCitations(id: string, options?: SearchOptions): Promise<SearchResult>;
+    getReferences(id: string, options?: SearchOptions): Promise<SearchResult>;
+}
+
+declare function searchPapers(query: string, options?: SearchOptions & {
+    client?: ClientOptions;
+}): Promise<SearchResult>;
+
+declare function getPaper(doi: string, options?: {
+    client?: ClientOptions;
+}): Promise<Paper | null>;
+
+/**
+ * 논문의 전체 상세 정보를 가져옴
+ * - S2 API: 메타데이터 (DOI, 저널, 키워드, 인용수 등)
+ * - ar5iv HTML: 본문 구조 (섹션, 그림, 표, 저자 소속)
+ *
+ * @param id - arXiv ID 또는 DOI
+ */
+declare function getFullPaper(id: string, options?: {
+    client?: ClientOptions;
+}): Promise<Paper | null>;
+
+declare function createClient(options?: ClientOptions): GhostClient;
+
+declare class SemanticScholarSource implements CitationSource {
+    readonly name: "semantic_scholar";
+    private readonly client;
+    private readonly apiKey?;
+    private readonly rateLimiter;
+    constructor(client: GhostClient, options?: ClientOptions);
+    search(query: string, options?: SearchOptions): Promise<SearchResult>;
+    getPaper(id: string): Promise<Paper | null>;
+    getPapers(ids: string[]): Promise<(Paper | null)[]>;
+    getCitations(id: string, options?: SearchOptions): Promise<SearchResult>;
+    getReferences(id: string, options?: SearchOptions): Promise<SearchResult>;
+    private fetchApi;
+}
+
+declare class RateLimiter {
+    private minIntervalMs;
+    private jitterMs;
+    private lastRequest;
+    constructor(minIntervalMs: number, jitterMs?: number);
+    wait(): Promise<void>;
+}
+/**
+ * 적응형 Rate Limiter
+ * - 차단(CAPTCHA 등) 감지 시 딜레이를 지수적으로 증가
+ * - 성공 시 점진적으로 기본값으로 복귀
+ */
+declare class AdaptiveRateLimiter {
+    private readonly baseIntervalMs;
+    private readonly baseJitterMs;
+    private readonly maxIntervalMs;
+    private readonly backoffMultiplier;
+    /** 연속 성공 몇 회 후 딜레이를 줄일지 */
+    private readonly cooldownAfter;
+    /** 딜레이 감소 비율 (0.7 = 30% 감소) */
+    private readonly cooldownFactor;
+    private lastRequest;
+    private currentIntervalMs;
+    private consecutiveSuccesses;
+    constructor(baseIntervalMs: number, baseJitterMs?: number, maxIntervalMs?: number, backoffMultiplier?: number, 
+    /** 연속 성공 몇 회 후 딜레이를 줄일지 */
+    cooldownAfter?: number, 
+    /** 딜레이 감소 비율 (0.7 = 30% 감소) */
+    cooldownFactor?: number);
+    private consecutiveBlocks;
+    /** 현재 적용 중인 인터벌 (ms) */
+    get interval(): number;
+    /** 현재 차단 상태인지 (연속 차단 2회 이상이면 true) */
+    get isBlocked(): boolean;
+    wait(): Promise<void>;
+    /** 요청 성공 시 호출 → 점진적으로 딜레이 감소 */
+    success(): void;
+    /** 차단 감지 시 호출 → 딜레이를 지수적으로 증가 */
+    backoff(): void;
+}
+
+declare class GoogleScholarSource implements PaperSource {
+    readonly name: "google_scholar";
+    private readonly client;
+    private readonly rateLimiter;
+    constructor(client: GhostClient, rateLimiter?: AdaptiveRateLimiter);
+    search(query: string, options?: SearchOptions): Promise<SearchResult>;
+    getPaper(id: string): Promise<Paper | null>;
+}
+
+declare class ArxivSource implements PaperSource {
+    readonly name: "arxiv";
+    private readonly client;
+    private readonly rateLimiter;
+    constructor(client: GhostClient);
+    search(query: string, options?: SearchOptions): Promise<SearchResult>;
+    getPaper(id: string): Promise<Paper | null>;
+    /**
+     * arXiv 논문의 전체 내용을 가져옴 (메타데이터 + ar5iv HTML 파싱)
+     * - API에서 기본 메타데이터 조회
+     * - ar5iv HTML에서 저자(소속 포함), 섹션, 그림, 표 파싱
+     */
+    getFullPaper(id: string): Promise<Paper | null>;
+}
+
+declare function withRetry<T>(fn: () => Promise<T>, options?: {
+    maxRetries?: number;
+    baseDelayMs?: number;
+}): Promise<T>;
+
+declare class HttpError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    constructor(status: number, statusText: string);
+}
+
+declare function deduplicatePapers(papers: Paper[]): Paper[];
+
+export { AdaptiveRateLimiter, ArxivSource, type Author, type CitationSource, type ClientOptions, type Figure, GoogleScholarSource, HttpError, type JournalInfo, type Paper, type PaperSource, RateLimiter, type SearchOptions, type SearchResult, type Section, SemanticScholarSource, type SourceError, type SourceType, type Table, createClient, deduplicatePapers, getFullPaper, getPaper, searchPapers, withRetry };