arxiv-api-wrapper 1.1.0 → 2.0.0

package/tests/arxivAPI.integration.test.ts

@@ -1,144 +1,144 @@
-import { describe, it, test, expect } from 'vitest';
-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.
-
-describe('arXiv API integration', () => {
-  test('fetches results by search_query and then by id_list', async () => {
-    console.log('Starting first API call (search query)...');
-    let first;
-    try {
-      first = await getArxivEntries({
-        search: {
-          title: ['overlapping'],
-          author: ['Vilhelm Agdur'],
-        },
-        start: 0,
-        maxResults: 1,
-        sortBy: 'submittedDate',
-        sortOrder: 'descending',
-        timeoutMs: 15000,
-        retries: 2,
-        rateLimit: { tokensPerInterval: 1, intervalMs: 1000 },
-        userAgent: 'arxiv-api-wrapper-tests/1.0',
-      });
-      console.log('First API call completed successfully');
-    } catch (error) {
-      console.error('First API call failed:', error);
-      throw new Error(`Failed to fetch search results: ${error instanceof Error ? error.message : String(error)}`);
-    }
-
-    expect(first.feed).toBeTruthy();
-    expect(typeof first.feed.totalResults).toBe('number');
-    expect(Array.isArray(first.entries)).toBe(true);
-    expect(first.entries.length).toBeGreaterThanOrEqual(0);
-
-    if (first.entries.length === 0) {
-      const responseDetails = {
-        feed: first.feed,
-        totalResults: first.feed?.totalResults,
-        entriesCount: first.entries.length,
-        entries: first.entries,
-      };
-      console.error('No entries returned from search query. Response details:', JSON.stringify(responseDetails, null, 2));
-      throw new Error(
-        `Search query (title: "overlapping", author: "Vilhelm Agdur") returned no entries. ` +
-        `Feed metadata: totalResults=${first.feed?.totalResults}, ` +
-        `entries array length=${first.entries.length}. ` +
-        `This indicates the API call succeeded but returned no results, which is unexpected.`
-      );
-    }
-
-    // Verify the first result matches the search criteria
-    const firstEntry = first.entries[0];
-    
-    // Check that the title contains "overlapping" (case-insensitive)
-    const titleLower = firstEntry.title.toLowerCase();
-    expect(titleLower).toContain('overlapping');
-    
-    // Check that at least one author is "Vilhelm Agdur"
-    const authorNames = firstEntry.authors.map(a => a.name);
-    const hasVilhelmAgdur = authorNames.some(name => 
-      name.toLowerCase().includes('vilhelm') && name.toLowerCase().includes('agdur')
-    );
-    expect(hasVilhelmAgdur).toBe(true);
-    
-    // Log the actual result for debugging if needed
-    console.log(`Verified result: title="${firstEntry.title}", authors=[${authorNames.join(', ')}]`);
-
-    const arxivId = firstEntry.arxivId;
-    if (!arxivId) {
-      console.log('No arxivId found in first entry, skipping id_list test');
-      return; // Skip id_list fetch if id is unavailable
-    }
-
-    console.log(`Starting second API call (id_list) for arxivId: ${arxivId}`);
-    let second;
-    try {
-      second = await getArxivEntries({
-        idList: [arxivId],
-        timeoutMs: 15000,
-        retries: 2,
-        rateLimit: { tokensPerInterval: 1, intervalMs: 1000 },
-        userAgent: 'arxiv-api-wrapper-tests/1.0',
-      });
-      console.log('Second API call completed successfully');
-    } catch (error) {
-      console.error('Second API call failed:', error);
-      throw new Error(`Failed to fetch entry by id_list: ${error instanceof Error ? error.message : String(error)}`);
-    }
-
-    expect(second.entries.length).toBeGreaterThanOrEqual(1);
-    expect(second.entries[0].arxivId).toBe(arxivId);
-    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);
-});
-
+import { describe, it, test, expect } from 'vitest';
+import { getArxivEntries, getArxivEntriesById } from '../src/arxivAPIRead.js';
+
+// Integration tests that make real HTTP calls to arXiv API.
+// These are intentionally conservative in request size and rate.
+
+describe('arXiv API integration', () => {
+  test('fetches results by search_query and then by id_list', async () => {
+    console.log('Starting first API call (search query)...');
+    let first;
+    try {
+      first = await getArxivEntries({
+        search: {
+          title: ['overlapping'],
+          author: ['Vilhelm Agdur'],
+        },
+        start: 0,
+        maxResults: 1,
+        sortBy: 'submittedDate',
+        sortOrder: 'descending',
+        timeoutMs: 15000,
+        retries: 2,
+        rateLimit: { tokensPerInterval: 1, intervalMs: 1000 },
+        userAgent: 'arxiv-api-wrapper-tests/1.0',
+      });
+      console.log('First API call completed successfully');
+    } catch (error) {
+      console.error('First API call failed:', error);
+      throw new Error(`Failed to fetch search results: ${error instanceof Error ? error.message : String(error)}`);
+    }
+
+    expect(first.feed).toBeTruthy();
+    expect(typeof first.feed.totalResults).toBe('number');
+    expect(Array.isArray(first.entries)).toBe(true);
+    expect(first.entries.length).toBeGreaterThanOrEqual(0);
+
+    if (first.entries.length === 0) {
+      const responseDetails = {
+        feed: first.feed,
+        totalResults: first.feed?.totalResults,
+        entriesCount: first.entries.length,
+        entries: first.entries,
+      };
+      console.error('No entries returned from search query. Response details:', JSON.stringify(responseDetails, null, 2));
+      throw new Error(
+        `Search query (title: "overlapping", author: "Vilhelm Agdur") returned no entries. ` +
+        `Feed metadata: totalResults=${first.feed?.totalResults}, ` +
+        `entries array length=${first.entries.length}. ` +
+        `This indicates the API call succeeded but returned no results, which is unexpected.`
+      );
+    }
+
+    // Verify the first result matches the search criteria
+    const firstEntry = first.entries[0];
+    
+    // Check that the title contains "overlapping" (case-insensitive)
+    const titleLower = firstEntry.title.toLowerCase();
+    expect(titleLower).toContain('overlapping');
+    
+    // Check that at least one author is "Vilhelm Agdur"
+    const authorNames = firstEntry.authors.map((a: { name: string }) => a.name);
+    const hasVilhelmAgdur = authorNames.some((name: string) => 
+      name.toLowerCase().includes('vilhelm') && name.toLowerCase().includes('agdur')
+    );
+    expect(hasVilhelmAgdur).toBe(true);
+    
+    // Log the actual result for debugging if needed
+    console.log(`Verified result: title="${firstEntry.title}", authors=[${authorNames.join(', ')}]`);
+
+    const arxivId = firstEntry.arxivId;
+    if (!arxivId) {
+      console.log('No arxivId found in first entry, skipping id_list test');
+      return; // Skip id_list fetch if id is unavailable
+    }
+
+    console.log(`Starting second API call (id_list) for arxivId: ${arxivId}`);
+    let second;
+    try {
+      second = await getArxivEntries({
+        idList: [arxivId],
+        timeoutMs: 15000,
+        retries: 2,
+        rateLimit: { tokensPerInterval: 1, intervalMs: 1000 },
+        userAgent: 'arxiv-api-wrapper-tests/1.0',
+      });
+      console.log('Second API call completed successfully');
+    } catch (error) {
+      console.error('Second API call failed:', error);
+      throw new Error(`Failed to fetch entry by id_list: ${error instanceof Error ? error.message : String(error)}`);
+    }
+
+    expect(second.entries.length).toBeGreaterThanOrEqual(1);
+    expect(second.entries[0].arxivId).toBe(arxivId);
+    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: { arxivId: string }) => e.arxivId.split('v')[0]); // Remove version suffix for comparison
+      const requestedIds = testIds.map((id: string) => id.split('v')[0]);
+      
+      // At least one requested ID should be in the results
+      const hasMatchingId = requestedIds.some((reqId: string) =>
+        returnedIds.some((retId: string) => 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/tests/arxivAPIRead.test.ts

@@ -1,6 +1,6 @@
 // Basic tests for query building logic using Vitest
 import { describe, it, expect } from 'vitest';
-import { buildSearchQuery } from '../src/arxivAPIRead';
+import { buildSearchQuery } from '../src/arxivAPIRead.js';
 
 describe('buildSearchQuery', () => {
   it('ANDs top-level fields', () => {

package/tests/fixtures/parseEntries/2507.17541.json.ts

@@ -1,4 +1,4 @@
-import { ArxivEntry } from '../../../src/types';
+import { ArxivEntry } from '../../../src/types.js';
 
 export const expectedEntries: ArxivEntry[] = [
   {

package/tests/fixtures/parseEntries/search_agdur.json.ts

@@ -1,4 +1,4 @@
-import { ArxivEntry } from '../../../src/types';
+import { ArxivEntry } from '../../../src/types.js';
 
 export const expectedEntries: ArxivEntry[] = [
   {

package/tests/oai.integration.test.ts

@@ -0,0 +1,222 @@
+/**
+ * Integration tests for the arXiv OAI-PMH interface (real HTTP calls).
+ * Conservative request size and rate; same pattern as arxivAPI.integration.test.ts.
+ */
+import { describe, it, expect } from 'vitest';
+import {
+  oaiIdentify,
+  oaiListRecords,
+  oaiListRecordsAsyncIterator,
+  oaiListRecordsAll,
+  oaiListIdentifiersAsyncIterator,
+  oaiListIdentifiersAll,
+  oaiListSetsAsyncIterator,
+  oaiListSetsAll,
+} from '../src/oaiClient.js';
+
+const OAI_OPTIONS = {
+  timeoutMs: 15000,
+  retries: 2,
+  rateLimit: { tokensPerInterval: 1, intervalMs: 1000 },
+  userAgent: 'arxiv-api-wrapper-tests/1.0',
+};
+
+describe('OAI-PMH integration', () => {
+  it('oaiIdentify returns repository info and protocol version 2.0', async () => {
+    let result;
+    try {
+      result = await oaiIdentify(OAI_OPTIONS);
+    } catch (error) {
+      console.error('oaiIdentify failed:', error);
+      throw new Error(
+        `OAI Identify failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    expect(result.repositoryName).toBeTruthy();
+    expect(result.baseURL).toContain('oaipmh.arxiv.org');
+    expect(result.protocolVersion).toBe('2.0');
+    expect(Array.isArray(result.adminEmail)).toBe(true);
+    expect(result.earliestDatestamp).toBeTruthy();
+  }, 30000);
+
+  it('oaiListRecords returns one page of records with header and metadata', async () => {
+    let result;
+    try {
+      result = await oaiListRecords('oai_dc', {
+        ...OAI_OPTIONS,
+        from: '2024-01-01',
+        until: '2024-01-02',
+      });
+    } catch (error) {
+      console.error('oaiListRecords failed:', error);
+      throw new Error(
+        `OAI ListRecords failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    expect(Array.isArray(result.records)).toBe(true);
+    if (result.records.length > 0) {
+      const rec = result.records[0];
+      expect(rec.header).toBeTruthy();
+      expect(rec.header.identifier).toBeTruthy();
+      expect(rec.header.datestamp).toBeTruthy();
+      expect(rec.metadata).toBeDefined();
+      expect(typeof rec.metadata).toBe('object');
+    }
+    // May or may not have resumptionToken depending on result size
+    if (result.resumptionToken) {
+      expect(result.resumptionToken.value).toBeTruthy();
+    }
+  }, 30000);
+
+  it('oaiListRecordsAll returns records across all pages within a small date range', async () => {
+    let result;
+    try {
+      result = await oaiListRecordsAll('oai_dc', {
+        ...OAI_OPTIONS,
+        from: '2024-01-01',
+        until: '2024-01-02',
+        maxRecords: 200,
+      });
+    } catch (error) {
+      console.error('oaiListRecordsAll failed:', error);
+      throw new Error(
+        `OAI ListRecordsAll failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+
+    expect(Array.isArray(result.records)).toBe(true);
+    if (result.records.length > 0) {
+      const rec = result.records[0];
+      expect(rec.header).toBeTruthy();
+      expect(rec.header.identifier).toBeTruthy();
+      expect(rec.header.datestamp).toBeTruthy();
+      expect(rec.metadata).toBeDefined();
+      expect(typeof rec.metadata).toBe('object');
+    }
+  }, 30000);
+
+  it('oaiListRecordsAsyncIterator yields records and matches oaiListRecordsAll count for the same cap', async () => {
+    let iteratedRecords: unknown[] = [];
+    let allResult;
+    try {
+      const maxRecords = 25;
+      for await (const record of oaiListRecordsAsyncIterator('oai_dc', {
+        ...OAI_OPTIONS,
+        from: '2024-01-01',
+        until: '2024-01-02',
+        maxRecords,
+      })) {
+        iteratedRecords.push(record);
+      }
+      allResult = await oaiListRecordsAll('oai_dc', {
+        ...OAI_OPTIONS,
+        from: '2024-01-01',
+        until: '2024-01-02',
+        maxRecords,
+      });
+    } catch (error) {
+      console.error('oaiListRecordsAsyncIterator failed:', error);
+      throw new Error(
+        `OAI ListRecordsAsyncIterator failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+
+    expect(Array.isArray(iteratedRecords)).toBe(true);
+    expect(iteratedRecords.length).toBeLessThanOrEqual(25);
+    expect(iteratedRecords.length).toBe(allResult.records.length);
+  }, 30000);
+
+  it('oaiListIdentifiersAll returns headers across pages with maxHeaders cap', async () => {
+    let result;
+    try {
+      result = await oaiListIdentifiersAll('oai_dc', {
+        ...OAI_OPTIONS,
+        from: '2024-01-01',
+        until: '2024-01-02',
+        maxHeaders: 50,
+      });
+    } catch (error) {
+      console.error('oaiListIdentifiersAll failed:', error);
+      throw new Error(
+        `OAI ListIdentifiersAll failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    expect(Array.isArray(result.headers)).toBe(true);
+    expect(result.headers.length).toBeLessThanOrEqual(50);
+    if (result.headers.length > 0) {
+      expect(result.headers[0].identifier).toBeTruthy();
+      expect(result.headers[0].datestamp).toBeTruthy();
+    }
+  }, 30000);
+
+  it('oaiListIdentifiersAsyncIterator yields headers and honors maxHeaders', async () => {
+    const headers = [];
+    try {
+      for await (const header of oaiListIdentifiersAsyncIterator('oai_dc', {
+        ...OAI_OPTIONS,
+        from: '2024-01-01',
+        until: '2024-01-02',
+        maxHeaders: 20,
+      })) {
+        headers.push(header);
+      }
+    } catch (error) {
+      console.error('oaiListIdentifiersAsyncIterator failed:', error);
+      throw new Error(
+        `OAI ListIdentifiersAsyncIterator failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+
+    expect(Array.isArray(headers)).toBe(true);
+    expect(headers.length).toBeLessThanOrEqual(20);
+    if (headers.length > 0) {
+      expect(headers[0].identifier).toBeTruthy();
+      expect(headers[0].datestamp).toBeTruthy();
+    }
+  }, 30000);
+
+  it('oaiListSetsAll returns sets with maxSets cap', async () => {
+    let result;
+    try {
+      result = await oaiListSetsAll({
+        ...OAI_OPTIONS,
+        maxSets: 20,
+      });
+    } catch (error) {
+      console.error('oaiListSetsAll failed:', error);
+      throw new Error(
+        `OAI ListSetsAll failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    expect(Array.isArray(result.sets)).toBe(true);
+    expect(result.sets.length).toBeLessThanOrEqual(20);
+    if (result.sets.length > 0) {
+      expect(result.sets[0].setSpec).toBeTruthy();
+      expect(result.sets[0].setName).toBeTruthy();
+    }
+  }, 30000);
+
+  it('oaiListSetsAsyncIterator yields sets and honors maxSets', async () => {
+    const sets = [];
+    try {
+      for await (const set of oaiListSetsAsyncIterator({
+        ...OAI_OPTIONS,
+        maxSets: 10,
+      })) {
+        sets.push(set);
+      }
+    } catch (error) {
+      console.error('oaiListSetsAsyncIterator failed:', error);
+      throw new Error(
+        `OAI ListSetsAsyncIterator failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+
+    expect(Array.isArray(sets)).toBe(true);
+    expect(sets.length).toBeLessThanOrEqual(10);
+    if (sets.length > 0) {
+      expect(sets[0].setSpec).toBeTruthy();
+      expect(sets[0].setName).toBeTruthy();
+    }
+  }, 30000);
+});