arxiv-api-wrapper 1.0.0 → 1.1.0

package/.github/workflows/static.yml

@@ -0,0 +1,66 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: Deploy static content to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Single deploy job since we're just deploying
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - name: Install dependencies
+        run: npm ci
+      - name: Generate documentation
+        run: npm run docs:generate
+      - name: Configure git
+        run: |
+          git config --local user.email "action@github.com"
+          git config --local user.name "GitHub Action"
+      - name: Commit generated docs
+        run: |
+          git add docs/
+          if git diff --staged --quiet; then
+            echo "No changes to commit"
+          else
+            git commit -m "docs: regenerate documentation [skip ci]"
+            git push
+          fi
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          # Upload docs path
+          path: './docs'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

package/README.md

@@ -0,0 +1,250 @@
+# arxiv-api-wrapper
+
+A TypeScript package that provides a convenient wrapper around the arXiv API, enabling easy querying and parsing of arXiv papers.
+
+## Installation
+
+```bash
+npm install arxiv-api-wrapper
+```
+
+## Quick Start
+
+```typescript
+import { getArxivEntries, getArxivEntriesById } from 'arxiv-api-wrapper';
+
+// Search for papers
+const result = await getArxivEntries({
+  search: {
+    title: ['quantum computing'],
+    author: ['John Doe'],
+  },
+  maxResults: 10,
+  sortBy: 'submittedDate',
+  sortOrder: 'descending',
+});
+
+console.log(`Found ${result.feed.totalResults} papers`);
+result.entries.forEach(entry => {
+  console.log(`${entry.arxivId}: ${entry.title}`);
+});
+
+// Or fetch specific papers by ID
+const papers = await getArxivEntriesById(['2101.01234', '2101.05678']);
+```
+
+## Features
+
+- **Type-safe**: Full TypeScript support with comprehensive type definitions
+- **Flexible Search**: Support for complex queries with multiple filters, OR groups, and negation
+- **Rate Limiting**: Built-in token bucket rate limiter to respect arXiv API guidelines
+- **Retry Logic**: Automatic retries with exponential backoff for transient failures
+- **Pagination**: Support for paginated results with configurable page size
+- **Sorting**: Multiple sort options (relevance, submission date, last updated)
+
+## API Reference
+
+For complete API documentation with detailed type information and examples, see the [generated API documentation](https://vagdur.github.io/arxiv-api-wrapper/).
+
+### `getArxivEntriesById(ids: string[], options?): Promise<ArxivQueryResult>`
+
+Simpler function to fetch arXiv papers by their IDs using the id_list API mode.
+
+**Parameters:**
+- `ids: string[]` - Array of arXiv paper IDs (e.g., `['2101.01234', '2101.05678']`)
+- `options?: object` - Optional request configuration
+  - `rateLimit?: { tokensPerInterval: number, intervalMs: number }` - Rate limit configuration
+  - `retries?: number` - Number of retry attempts (default: 3)
+  - `timeoutMs?: number` - Request timeout in milliseconds (default: 10000)
+  - `userAgent?: string` - Custom User-Agent header
+
+**Returns:** Same as `getArxivEntries` - see return type below.
+
+### `getArxivEntries(options: ArxivQueryOptions): Promise<ArxivQueryResult>`
+
+Main function to query the arXiv API with search filters or ID lists.
+
+**Options:**
+- `idList?: string[]` - List of arXiv IDs to fetch (e.g., `['2101.01234', '2101.05678']`)
+- `search?: ArxivSearchFilters` - Search filters (when used with `idList`, filters the entries from `idList` to only return those matching the search query)
+- `start?: number` - Pagination offset (0-based)
+- `maxResults?: number` - Maximum number of results (≤ 300)
+- `sortBy?: 'relevance' | 'lastUpdatedDate' | 'submittedDate'` - Sort field
+- `sortOrder?: 'ascending' | 'descending'` - Sort direction
+- `timeoutMs?: number` - Request timeout in milliseconds (default: 10000)
+- `retries?: number` - Number of retry attempts (default: 3)
+- `rateLimit?: { tokensPerInterval: number, intervalMs: number }` - Rate limit configuration
+- `userAgent?: string` - Custom User-Agent header
+
+**Search Filters:**
+- `title?: string[]` - Search in titles
+- `author?: string[]` - Search by author names
+- `abstract?: string[]` - Search in abstracts
+- `category?: string[]` - Filter by arXiv categories
+- `submittedDateRange?: { from: string, to: string }` - Date range filter (YYYYMMDDTTTT format)
+- `or?: ArxivSearchFilters[]` - OR group of filters
+- `andNot?: ArxivSearchFilters` - Negated filter (ANDNOT)
+
+**Returns:**
+```typescript
+{
+  feed: {
+    id: string;
+    updated: string;
+    title: string;
+    link: string;
+    totalResults: number;
+    startIndex: number;
+    itemsPerPage: number;
+  };
+  entries: Array<{
+    id: string;
+    arxivId: string;
+    title: string;
+    summary: string;
+    published: string;
+    updated: string;
+    authors: Array<{ name: string; affiliation?: string }>;
+    categories: string[];
+    primaryCategory?: string;
+    links: Array<{ href: string; rel?: string; type?: string; title?: string }>;
+    doi?: string;
+    journalRef?: string;
+    comment?: string;
+  }>;
+}
+```
+
+## Examples
+
+### Search by title and author
+
+```typescript
+const result = await getArxivEntries({
+  search: {
+    title: ['machine learning'],
+    author: ['Geoffrey Hinton'],
+  },
+  maxResults: 5,
+});
+```
+
+### Fetch specific papers by ID
+
+Using the simpler `getArxivEntriesById` function:
+
+```typescript
+const result = await getArxivEntriesById(['2101.01234', '2101.05678']);
+```
+
+Or using `getArxivEntries`:
+
+```typescript
+const result = await getArxivEntries({
+  idList: ['2101.01234', '2101.05678'],
+});
+```
+
+### Complex search with OR and date range
+
+```typescript
+const result = await getArxivEntries({
+  search: {
+    or: [
+      { title: ['quantum'] },
+      { abstract: ['quantum'] },
+    ],
+    submittedDateRange: {
+      from: '202301010600',
+      to: '202401010600',
+    },
+  },
+  sortBy: 'submittedDate',
+  sortOrder: 'descending',
+});
+```
+
+### Fetch papers by ID with rate limiting
+
+```typescript
+const result = await getArxivEntriesById(
+  ['2101.01234', '2101.05678'],
+  {
+    rateLimit: {
+      tokensPerInterval: 1,
+      intervalMs: 3000, // 1 request per 3 seconds
+    },
+    timeoutMs: 15000,
+  }
+);
+```
+
+### Search with rate limiting
+
+```typescript
+const result = await getArxivEntries({
+  search: { title: ['neural networks'] },
+  rateLimit: {
+    tokensPerInterval: 1,
+    intervalMs: 3000, // 1 request per 3 seconds
+  },
+});
+```
+
+## Documentation
+
+### Generating API Documentation
+
+To generate browsable API documentation from the source code:
+
+```bash
+npm run docs:generate
+```
+
+This will create HTML documentation in the `docs/` directory. You can then view it locally:
+
+```bash
+npm run docs:serve
+```
+
+The generated documentation includes:
+- Complete API reference for all exported functions and types
+- Detailed parameter descriptions and examples
+- Type information and relationships
+- Search functionality
+
+### IDE IntelliSense
+
+All exported functions and types include JSDoc comments for enhanced IDE IntelliSense support. Hover over any exported symbol in your IDE to see inline documentation.
+
+## TypeScript Types
+
+All types are exported from the package:
+
+```typescript
+import type {
+  ArxivQueryOptions,
+  ArxivQueryResult,
+  ArxivSearchFilters,
+  ArxivEntry,
+  ArxivFeedMeta,
+  ArxivAuthor,
+  ArxivLink,
+  ArxivSortBy,
+  ArxivSortOrder,
+  ArxivRateLimitConfig,
+  ArxivDateRange,
+} from 'arxiv-api-wrapper';
+```
+
+## License
+
+ISC
+
+## Author
+
+Vilhelm Agdur
+
+## Repository
+
+https://github.com/vagdur/arxiv-api-wrapper

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arxiv-api-wrapper",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Provides functions wrapping the arXiv API",
   "keywords": [
     "arxiv"
@@ -19,12 +19,16 @@
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "scripts": {
-    "test": "vitest run --config tests/vitest.config.mts"
+    "test": "vitest run --config tests/vitest.config.mts",
+    "docs:generate": "typedoc",
+    "docs:serve": "npx serve docs"
   },
   "dependencies": {
     "fast-xml-parser": "^4.3.5"
   },
   "devDependencies": {
+    "@types/node": "^25.0.0",
+    "typedoc": "^0.26.0",
     "typescript": "^5.0.0",
     "vitest": "^1.0.0"
   }

package/src/arxivAPIRead.ts

@@ -1,4 +1,4 @@
-import { ArxivQueryOptions, ArxivQueryResult, ArxivSearchFilters } from './types';
+import { ArxivQueryOptions, ArxivQueryResult, ArxivSearchFilters, ArxivRateLimitConfig } from './types';
 import { TokenBucketLimiter } from './rateLimiter';
 import { fetchWithRetry } from './http';
 import { parseEntries, parseFeedMeta } from './atom';
@@ -45,6 +45,40 @@ function joinAnd(parts: string[]): string {
   return parts.filter(Boolean).join('+AND+');
 }
 
+/**
+ * Builds an arXiv search query string from search filters.
+ * 
+ * This function converts the structured `ArxivSearchFilters` object into
+ * a query string compatible with the arXiv API search syntax. Multiple terms
+ * in the same field are combined with AND, and multiple fields are combined
+ * with AND. OR groups and negation (ANDNOT) are also supported.
+ * 
+ * @param filters - Search filters to convert to query string
+ * @returns URL-encoded query string ready for arXiv API
+ * 
+ * @example
+ * ```typescript
+ * const query = buildSearchQuery({
+ *   title: ['machine learning'],
+ *   author: ['Geoffrey Hinton'],
+ * });
+ * // Returns: "ti:\"machine learning\"+AND+au:\"Geoffrey Hinton\""
+ * ```
+ * 
+ * @example
+ * ```typescript
+ * // Complex query with OR groups
+ * const query = buildSearchQuery({
+ *   or: [
+ *     { title: ['quantum'] },
+ *     { abstract: ['quantum'] },
+ *   ],
+ *   category: ['quant-ph'],
+ * });
+ * ```
+ * 
+ * @see {@link ArxivSearchFilters} for filter options
+ */
 export function buildSearchQuery(filters: ArxivSearchFilters): string {
   const parts: string[] = [];
   const phraseExact = filters.phraseExact;
@@ -110,6 +144,63 @@ function buildUrl(opts: ArxivQueryOptions): string {
   return `${ARXIV_BASE_URL}?${qs}`;
 }
 
+/**
+ * Queries the arXiv API and returns matching paper entries.
+ * 
+ * This is the main function for interacting with the arXiv API. It supports
+ * searching by various criteria, fetching specific papers by ID, pagination,
+ * sorting, rate limiting, and automatic retries with exponential backoff.
+ * 
+ * @param options - Query options including search filters, pagination, and request configuration
+ * @returns Promise resolving to query results with feed metadata and paper entries
+ * 
+ * @throws {Error} If the API request fails after all retries
+ * @throws {Error} If the API returns a non-2xx status code
+ * @throws {Error} If the API returns an empty response
+ * 
+ * @example
+ * ```typescript
+ * // Simple search
+ * const result = await getArxivEntries({
+ *   search: {
+ *     title: ['quantum computing'],
+ *     author: ['John Doe'],
+ *   },
+ *   maxResults: 10,
+ * });
+ * 
+ * console.log(`Found ${result.feed.totalResults} papers`);
+ * result.entries.forEach(entry => {
+ *   console.log(`${entry.arxivId}: ${entry.title}`);
+ * });
+ * ```
+ * 
+ * @example
+ * ```typescript
+ * // Fetch specific papers by ID
+ * const result = await getArxivEntries({
+ *   idList: ['2101.01234', '2101.05678'],
+ * });
+ * ```
+ * 
+ * @example
+ * ```typescript
+ * // With rate limiting and custom timeout
+ * const result = await getArxivEntries({
+ *   search: { title: ['neural networks'] },
+ *   rateLimit: {
+ *     tokensPerInterval: 1,
+ *     intervalMs: 3000, // 1 request per 3 seconds
+ *   },
+ *   timeoutMs: 15000,
+ *   retries: 5,
+ * });
+ * ```
+ * 
+ * @see {@link ArxivQueryOptions} for all available options
+ * @see {@link ArxivQueryResult} for the return type structure
+ * @see {@link ArxivSearchFilters} for search filter options
+ */
 export async function getArxivEntries(options: ArxivQueryOptions): Promise<ArxivQueryResult> {
   const timeoutMs = options.timeoutMs ?? 10000;
   const retries = options.retries ?? 3;
@@ -153,3 +244,73 @@ export async function getArxivEntries(options: ArxivQueryOptions): Promise<Arxiv
   return { feed, entries };
 }
 
+/**
+ * Fetches arXiv papers by their IDs using the simpler id_list API mode.
+ * 
+ * This is a convenience function for the simpler arXiv API mode where you provide
+ * a comma-delimited list of paper IDs and get back the data for those papers.
+ * It's simpler than using search queries when you already know the paper IDs.
+ * 
+ * @param ids - Array of arXiv paper IDs (e.g., ['2101.01234', '2101.05678']). Maximum 100 IDs allowed.
+ * @param options - Optional request configuration
+ * @param options.rateLimit - Rate limiting configuration to respect arXiv API guidelines
+ * @param options.retries - Number of retry attempts for failed requests (default: 3)
+ * @param options.timeoutMs - Request timeout in milliseconds (default: 10000)
+ * @param options.userAgent - Custom User-Agent header for requests
+ * @returns Promise resolving to query results with feed metadata and paper entries
+ * 
+ * @throws {Error} If more than 100 IDs are provided
+ * @throws {Error} If the API request fails after all retries
+ * @throws {Error} If the API returns a non-2xx status code
+ * @throws {Error} If the API returns an empty response
+ * 
+ * @example
+ * ```typescript
+ * // Fetch papers by ID
+ * const result = await getArxivEntriesById(['2101.01234', '2101.05678']);
+ * 
+ * result.entries.forEach(entry => {
+ *   console.log(`${entry.arxivId}: ${entry.title}`);
+ * });
+ * ```
+ * 
+ * @example
+ * ```typescript
+ * // With rate limiting
+ * const result = await getArxivEntriesById(
+ *   ['2101.01234'],
+ *   {
+ *     rateLimit: {
+ *       tokensPerInterval: 1,
+ *       intervalMs: 3000, // 1 request per 3 seconds
+ *     },
+ *     timeoutMs: 15000,
+ *   }
+ * );
+ * ```
+ * 
+ * @see {@link getArxivEntries} for more advanced querying with search filters
+ * @see {@link ArxivQueryResult} for the return type structure
+ */
+export async function getArxivEntriesById(
+  ids: string[],
+  options?: {
+    rateLimit?: ArxivRateLimitConfig;
+    retries?: number;
+    timeoutMs?: number;
+    userAgent?: string;
+  }
+): Promise<ArxivQueryResult> {
+  if (ids.length > 100) {
+    throw new Error(`Maximum of 100 IDs allowed, but ${ids.length} IDs were provided`);
+  }
+  
+  return getArxivEntries({
+    idList: ids,
+    rateLimit: options?.rateLimit,
+    retries: options?.retries,
+    timeoutMs: options?.timeoutMs,
+    userAgent: options?.userAgent,
+  });
+}
+

package/src/index.ts

@@ -1,5 +1,46 @@
+/**
+ * @packageDocumentation
+ * 
+ * # arxiv-api-wrapper
+ * 
+ * A TypeScript package that provides a convenient wrapper around the arXiv API,
+ * enabling easy querying and parsing of arXiv papers.
+ * 
+ * ## Features
+ * 
+ * - **Type-safe**: Full TypeScript support with comprehensive type definitions
+ * - **Flexible Search**: Support for complex queries with multiple filters, OR groups, and negation
+ * - **Rate Limiting**: Built-in token bucket rate limiter to respect arXiv API guidelines
+ * - **Retry Logic**: Automatic retries with exponential backoff for transient failures
+ * - **Pagination**: Support for paginated results with configurable page size
+ * - **Sorting**: Multiple sort options (relevance, submission date, last updated)
+ * 
+ * ## Quick Start
+ * 
+ * ```typescript
+ * import { getArxivEntries } from 'arxiv-api-wrapper';
+ * 
+ * const result = await getArxivEntries({
+ *   search: {
+ *     title: ['quantum computing'],
+ *     author: ['John Doe'],
+ *   },
+ *   maxResults: 10,
+ *   sortBy: 'submittedDate',
+ *   sortOrder: 'descending',
+ * });
+ * 
+ * console.log(`Found ${result.feed.totalResults} papers`);
+ * result.entries.forEach(entry => {
+ *   console.log(`${entry.arxivId}: ${entry.title}`);
+ * });
+ * ```
+ * 
+ * @module arxiv-api-wrapper
+ */
+
 // Main entry point for the arXiv API wrapper package
-export { getArxivEntries, buildSearchQuery } from './arxivAPIRead';
+export { getArxivEntries, getArxivEntriesById } from './arxivAPIRead';
 export type {
   ArxivQueryOptions,
   ArxivQueryResult,

package/src/types.ts

@@ -1,87 +1,265 @@
+/**
+ * Sort field options for arXiv query results.
+ */
 export type ArxivSortBy = 'relevance' | 'lastUpdatedDate' | 'submittedDate';
+
+/**
+ * Sort order direction for arXiv query results.
+ */
 export type ArxivSortOrder = 'ascending' | 'descending';
 
+/**
+ * Configuration for token bucket rate limiting.
+ * 
+ * @example
+ * ```typescript
+ * const rateLimit: ArxivRateLimitConfig = {
+ *   tokensPerInterval: 1,
+ *   intervalMs: 3000, // 1 request per 3 seconds
+ * };
+ * ```
+ */
 export interface ArxivRateLimitConfig {
+  /** Number of tokens (requests) allowed per interval */
   tokensPerInterval: number;
+  /** Interval duration in milliseconds */
   intervalMs: number;
 }
 
+/**
+ * Date range filter for arXiv queries.
+ * Dates must be in YYYYMMDDTTTT format (GMT timezone).
+ * 
+ * @example
+ * ```typescript
+ * const dateRange: ArxivDateRange = {
+ *   from: '202301010600',
+ *   to: '202401010600',
+ * };
+ * ```
+ */
 export interface ArxivDateRange {
+  /** Start date in YYYYMMDDTTTT format (GMT) */
   from: string; // YYYYMMDDTTTT (GMT)
+  /** End date in YYYYMMDDTTTT format (GMT) */
   to: string;   // YYYYMMDDTTTT (GMT)
 }
 
+/**
+ * Search filters for querying arXiv papers.
+ * Multiple terms in the same field are combined with AND.
+ * Multiple fields are combined with AND.
+ * 
+ * @example
+ * ```typescript
+ * const filters: ArxivSearchFilters = {
+ *   title: ['machine learning'],
+ *   author: ['Geoffrey Hinton'],
+ *   category: ['cs.LG'],
+ * };
+ * ```
+ * 
+ * @example
+ * ```typescript
+ * // Complex query with OR groups
+ * const filters: ArxivSearchFilters = {
+ *   or: [
+ *     { title: ['quantum'] },
+ *     { abstract: ['quantum'] },
+ *   ],
+ *   submittedDateRange: {
+ *     from: '202301010600',
+ *     to: '202401010600',
+ *   },
+ * };
+ * ```
+ * 
+ * @see {@link ArxivDateRange} for date range format
+ */
 export interface ArxivSearchFilters {
+  /** Search terms to match in all fields */
   all?: string[];
+  /** Search terms to match in paper titles (arXiv field: ti:) */
   title?: string[]; // ti:
+  /** Search terms to match author names (arXiv field: au:) */
   author?: string[]; // au:
+  /** Search terms to match in abstracts (arXiv field: abs:) */
   abstract?: string[]; // abs:
+  /** Search terms to match in comments (arXiv field: co:) */
   comment?: string[]; // co:
+  /** Search terms to match in journal references (arXiv field: jr:) */
   journalRef?: string[]; // jr:
+  /** arXiv category codes to filter by (arXiv field: cat:) */
   category?: string[]; // cat:
+  /** Date range filter for submission dates (arXiv field: submittedDate:[from TO to]) */
   submittedDateRange?: ArxivDateRange; // submittedDate:[from TO to]
 
   // Composition
+  /** OR group: at least one of the subfilters must match */
   or?: ArxivSearchFilters[]; // grouped OR of subfilters
+  /** Negated filter: exclude papers matching this filter */
   andNot?: ArxivSearchFilters; // negated subfilter
 
   // Encoding behavior
+  /** If true, wrap each search term in quotes for exact phrase matching */
   phraseExact?: boolean; // wrap each term in quotes
 }
 
+/**
+ * Options for querying the arXiv API.
+ * 
+ * @example
+ * ```typescript
+ * const options: ArxivQueryOptions = {
+ *   search: {
+ *     title: ['quantum computing'],
+ *     author: ['John Doe'],
+ *   },
+ *   maxResults: 10,
+ *   sortBy: 'submittedDate',
+ *   sortOrder: 'descending',
+ * };
+ * ```
+ * 
+ * @see {@link ArxivSearchFilters} for search filter details
+ * @see {@link ArxivRateLimitConfig} for rate limiting configuration
+ */
 export interface ArxivQueryOptions {
+  /** List of arXiv IDs to fetch directly (e.g., ['2101.01234', '2101.05678']). Can be used together with `search` to filter the results. */
   idList?: string[];
-  search?: ArxivSearchFilters; // ignored if idList present
+  /** Search filters to query papers. When used with `idList`, filters the entries from `idList` to only return those matching the search query. */
+  search?: ArxivSearchFilters;
+  /** Pagination offset (0-based index) */
   start?: number; // 0-based
+  /** Maximum number of results to return (≤ 300 per arXiv API guidance) */
   maxResults?: number; // <= 300 per arXiv guidance
+  /** Field to sort results by */
   sortBy?: ArxivSortBy;
+  /** Sort order direction */
   sortOrder?: ArxivSortOrder;
+  /** Request timeout in milliseconds (default: 10000) */
   timeoutMs?: number; // default 10000
+  /** Number of retry attempts for failed requests (default: 3) */
   retries?: number; // default 3
+  /** Rate limiting configuration to respect arXiv API guidelines */
   rateLimit?: ArxivRateLimitConfig;
+  /** Custom User-Agent header for requests */
   userAgent?: string; // optional custom UA header
 }
 
+/**
+ * Link metadata for an arXiv paper entry.
+ * Links may point to the abstract page, PDF, source files, etc.
+ */
 export interface ArxivLink {
+  /** URL of the link */
   href: string;
+  /** Link relation type (e.g., 'alternate', 'related') */
   rel?: string;
+  /** MIME type of the linked resource */
   type?: string;
+  /** Human-readable title for the link */
   title?: string;
 }
 
+/**
+ * Author information for an arXiv paper.
+ */
 export interface ArxivAuthor {
+  /** Author's full name */
   name: string;
+  /** Author's institutional affiliation (if provided) */
   affiliation?: string;
 }
 
+/**
+ * Represents a single arXiv paper entry.
+ * 
+ * @example
+ * ```typescript
+ * const entry: ArxivEntry = {
+ *   id: 'http://arxiv.org/abs/2101.01234v2',
+ *   arxivId: '2101.01234v2',
+ *   title: 'Example Paper Title',
+ *   summary: 'Paper abstract...',
+ *   published: '2021-01-01T12:00:00Z',
+ *   updated: '2021-01-02T12:00:00Z',
+ *   authors: [{ name: 'John Doe', affiliation: 'University' }],
+ *   categories: ['cs.LG', 'cs.AI'],
+ *   primaryCategory: 'cs.LG',
+ *   links: [...],
+ * };
+ * ```
+ */
 export interface ArxivEntry {
+  /** Full URL to the paper's abstract page */
   id: string; // abs URL
+  /** arXiv ID including version (e.g., '2101.01234v2') */
   arxivId: string; // e.g., 2101.01234v2
+  /** Paper title */
   title: string;
+  /** Paper abstract/summary */
   summary: string;
+  /** Publication date (ISO 8601 format) */
   published: string;
+  /** Last update date (ISO 8601 format) */
   updated: string;
+  /** List of paper authors */
   authors: ArxivAuthor[];
+  /** arXiv category codes assigned to the paper */
   categories: string[];
+  /** Primary arXiv category code */
   primaryCategory?: string;
+  /** Links to abstract, PDF, source files, etc. */
   links: ArxivLink[];
+  /** Digital Object Identifier (if published elsewhere) */
   doi?: string;
+  /** Journal reference (if published) */
   journalRef?: string;
+  /** Author comments about the paper */
   comment?: string;
 }
 
+/**
+ * Metadata about the arXiv query feed/response.
+ */
 export interface ArxivFeedMeta {
+  /** Feed identifier */
   id: string;
+  /** Feed last update timestamp (ISO 8601 format) */
   updated: string;
+  /** Feed title */
   title: string;
+  /** Link to the query that generated this feed */
   link: string;
+  /** Total number of results matching the query */
   totalResults: number;
+  /** Starting index of results in this page (0-based) */
   startIndex: number;
+  /** Number of items per page in this response */
   itemsPerPage: number;
 }
 
+/**
+ * Complete result from an arXiv API query.
+ * 
+ * @example
+ * ```typescript
+ * const result: ArxivQueryResult = await getArxivEntries({
+ *   search: { title: ['machine learning'] },
+ *   maxResults: 10,
+ * });
+ * 
+ * console.log(`Found ${result.feed.totalResults} papers`);
+ * result.entries.forEach(entry => {
+ *   console.log(`${entry.arxivId}: ${entry.title}`);
+ * });
+ * ```
+ */
 export interface ArxivQueryResult {
+  /** Feed metadata and pagination information */
   feed: ArxivFeedMeta;
+  /** Array of arXiv paper entries */
   entries: ArxivEntry[];
 }
 

package/tests/arxivAPI.integration.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, test, expect } from 'vitest';
-import { getArxivEntries } from '../src/arxivAPIRead';
+import { getArxivEntries, getArxivEntriesById } from '../src/arxivAPIRead';
 
 // Integration tests that make real HTTP calls to arXiv API.
 // These are intentionally conservative in request size and rate.
@@ -94,5 +94,51 @@ describe('arXiv API integration', () => {
     expect(second.entries[0].title.length).toBeGreaterThan(0);
     expect(second.entries[0].links.length).toBeGreaterThanOrEqual(1);
   }, 120000); // Increased to 120 seconds to account for rate limiting, retries, and backoff delays
+
+  test('fetches papers by ID using getArxivEntriesById', async () => {
+    // Use a well-known arXiv paper ID for testing
+    const testIds = ['2101.01234', '2101.05678'];
+    
+    console.log(`Starting API call with getArxivEntriesById for IDs: ${testIds.join(', ')}`);
+    let result;
+    try {
+      result = await getArxivEntriesById(testIds, {
+        timeoutMs: 15000,
+        retries: 2,
+        rateLimit: { tokensPerInterval: 1, intervalMs: 1000 },
+        userAgent: 'arxiv-api-wrapper-tests/1.0',
+      });
+      console.log('API call completed successfully');
+    } catch (error) {
+      console.error('API call failed:', error);
+      throw new Error(`Failed to fetch entries by ID: ${error instanceof Error ? error.message : String(error)}`);
+    }
+
+    expect(result.feed).toBeTruthy();
+    expect(typeof result.feed.totalResults).toBe('number');
+    expect(Array.isArray(result.entries)).toBe(true);
+    expect(result.entries.length).toBeGreaterThanOrEqual(0);
+
+    // Verify that we got results for at least some of the requested IDs
+    if (result.entries.length > 0) {
+      const returnedIds = result.entries.map(e => e.arxivId.split('v')[0]); // Remove version suffix for comparison
+      const requestedIds = testIds.map(id => id.split('v')[0]);
+      
+      // At least one requested ID should be in the results
+      const hasMatchingId = requestedIds.some(reqId => 
+        returnedIds.some(retId => retId === reqId || retId.startsWith(reqId))
+      );
+      expect(hasMatchingId).toBe(true);
+
+      // Verify entry structure
+      const firstEntry = result.entries[0];
+      expect(firstEntry.arxivId).toBeTruthy();
+      expect(firstEntry.title).toBeTruthy();
+      expect(firstEntry.title.length).toBeGreaterThan(0);
+      expect(Array.isArray(firstEntry.authors)).toBe(true);
+      expect(Array.isArray(firstEntry.links)).toBe(true);
+      expect(firstEntry.links.length).toBeGreaterThanOrEqual(1);
+    }
+  }, 120000);
 });
 

package/typedoc.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "entryPoints": ["./src/index.ts"],
+  "out": "docs",
+  "name": "arxiv-api-wrapper",
+  "readme": "./README.md",
+  "includeVersion": true,
+  "excludePrivate": true,
+  "excludeProtected": true,
+  "excludeInternal": true,
+  "theme": "default",
+  "sort": ["source-order"],
+  "categorizeByGroup": true,
+  "categoryOrder": [
+    "Functions",
+    "Interfaces",
+    "Types"
+  ],
+  "gitRevision": "main",
+  "gitRemote": "origin",
+  "validation": {
+    "invalidLink": true,
+    "notDocumented": false
+  }
+}
+