arxiv-api-wrapper 1.0.1 → 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

@@ -11,8 +11,9 @@ npm install arxiv-api-wrapper
 ## Quick Start
 
 ```typescript
-import { getArxivEntries } from 'arxiv-api-wrapper';
+import { getArxivEntries, getArxivEntriesById } from 'arxiv-api-wrapper';
 
+// Search for papers
 const result = await getArxivEntries({
   search: {
     title: ['quantum computing'],
@@ -27,6 +28,9 @@ 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
@@ -40,15 +44,29 @@ result.entries.forEach(entry => {
 
 ## API Reference
 
-For complete API documentation with detailed type information and examples, see the [generated API documentation](./docs/index.html) (generate with `npm run docs:generate`).
+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.
+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 (ignored if `idList` is provided)
+- `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
@@ -113,6 +131,14 @@ const result = await getArxivEntries({
 
 ### 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'],
@@ -138,7 +164,22 @@ const result = await getArxivEntries({
 });
 ```
 
-### With rate limiting
+### 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({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arxiv-api-wrapper",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Provides functions wrapping the arXiv API",
   "keywords": [
     "arxiv"

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';
@@ -244,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

@@ -40,7 +40,7 @@
  */
 
 // Main entry point for the arXiv API wrapper package
-export { getArxivEntries } from './arxivAPIRead';
+export { getArxivEntries, getArxivEntriesById } from './arxivAPIRead';
 export type {
   ArxivQueryOptions,
   ArxivQueryResult,

package/src/types.ts

@@ -125,10 +125,10 @@ export interface ArxivSearchFilters {
  * @see {@link ArxivRateLimitConfig} for rate limiting configuration
  */
 export interface ArxivQueryOptions {
-  /** List of arXiv IDs to fetch directly (e.g., ['2101.01234', '2101.05678']). If provided, search filters are ignored. */
+  /** 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 filters to query papers. Ignored if `idList` is provided. */
-  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) */

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);
 });