@littlebearapps/australian-history-mcp 0.6.0

package/dist/clients/trove_client.js

@@ -0,0 +1,374 @@
+/**
+ * Trove (National Library of Australia) API Client
+ *
+ * The Trove API v3 provides access to the National Library's digitised
+ * collections including newspapers, books, images, maps, and more.
+ *
+ * API Documentation: https://trove.nla.gov.au/about/create-something/using-api/v3/api-technical-guide
+ * API Console: https://troveconsole.herokuapp.com/
+ */
+const TROVE_API_BASE = 'https://api.trove.nla.gov.au/v3';
+export class TroveClient {
+    apiKey;
+    baseUrl;
+    constructor(apiKey) {
+        this.apiKey = apiKey ?? process.env.TROVE_API_KEY ?? '';
+        this.baseUrl = TROVE_API_BASE;
+        if (!this.apiKey) {
+            console.warn('TROVE_API_KEY not set - Trove API calls will fail');
+        }
+    }
+    /**
+     * Search across Trove categories
+     */
+    async search(params) {
+        const categories = Array.isArray(params.category)
+            ? params.category
+            : [params.category ?? 'all'];
+        const urlParams = new URLSearchParams({
+            q: params.query,
+            encoding: 'json',
+            n: (params.limit ?? 20).toString(),
+        });
+        // Add categories
+        categories.forEach(cat => urlParams.append('category', cat));
+        // Pagination
+        if (params.start) {
+            urlParams.set('s', params.start);
+        }
+        // Bulk harvest mode (stable sorting by ID)
+        if (params.bulkHarvest) {
+            urlParams.set('bulkHarvest', 'true');
+        }
+        // Date range
+        if (params.dateFrom || params.dateTo) {
+            const from = params.dateFrom ?? '*';
+            const to = params.dateTo ?? '*';
+            urlParams.set('q', `${params.query} date:[${from} TO ${to}]`);
+        }
+        // State filter (for newspapers)
+        if (params.state) {
+            urlParams.set('l-state', params.state);
+        }
+        // Format filter
+        if (params.format) {
+            urlParams.set('l-format', params.format);
+        }
+        // Include full text for newspapers
+        if (params.includeFullText) {
+            urlParams.append('include', 'articletext');
+        }
+        // Request facets
+        if (params.facets) {
+            params.facets.forEach(f => urlParams.append('facet', f));
+        }
+        const url = `${this.baseUrl}/result?${urlParams.toString()}`;
+        try {
+            const response = await this.fetchWithAuth(url);
+            return this.parseSearchResponse(response, params.query);
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw new Error(`Trove search failed: ${error.message}`);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Get a newspaper article by ID
+     */
+    async getNewspaperArticle(articleId, includeText = false) {
+        const urlParams = new URLSearchParams({
+            encoding: 'json',
+            reclevel: 'full',
+        });
+        if (includeText) {
+            urlParams.append('include', 'articletext');
+        }
+        const url = `${this.baseUrl}/newspaper/${articleId}?${urlParams.toString()}`;
+        try {
+            const data = await this.fetchWithAuth(url);
+            return this.parseArticle(data);
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.includes('404')) {
+                return null;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Get a gazette article by ID
+     */
+    async getGazetteArticle(articleId, includeText = false) {
+        const urlParams = new URLSearchParams({
+            encoding: 'json',
+            reclevel: 'full',
+        });
+        if (includeText) {
+            urlParams.append('include', 'articletext');
+        }
+        const url = `${this.baseUrl}/gazette/${articleId}?${urlParams.toString()}`;
+        try {
+            const data = await this.fetchWithAuth(url);
+            return this.parseArticle(data);
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.includes('404')) {
+                return null;
+            }
+            throw error;
+        }
+    }
+    /**
+     * List newspaper titles
+     */
+    async listNewspaperTitles(state) {
+        const urlParams = new URLSearchParams({
+            encoding: 'json',
+        });
+        if (state) {
+            urlParams.set('state', state);
+        }
+        const url = `${this.baseUrl}/newspaper/titles?${urlParams.toString()}`;
+        try {
+            const data = await this.fetchWithAuth(url);
+            return this.parseNewspaperTitles(data);
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw new Error(`Trove listNewspaperTitles failed: ${error.message}`);
+            }
+            throw error;
+        }
+    }
+    /**
+     * List gazette titles
+     */
+    async listGazetteTitles(state) {
+        const urlParams = new URLSearchParams({
+            encoding: 'json',
+        });
+        if (state) {
+            urlParams.set('state', state);
+        }
+        const url = `${this.baseUrl}/gazette/titles?${urlParams.toString()}`;
+        try {
+            const data = await this.fetchWithAuth(url);
+            return this.parseNewspaperTitles(data);
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw new Error(`Trove listGazetteTitles failed: ${error.message}`);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Get details of a specific newspaper/gazette title
+     */
+    async getTitleDetails(titleId, options) {
+        const type = options?.type ?? 'newspaper';
+        const urlParams = new URLSearchParams({
+            encoding: 'json',
+        });
+        if (options?.includeYears) {
+            urlParams.append('include', 'years');
+        }
+        if (options?.dateRange) {
+            const { from, to } = options.dateRange;
+            urlParams.set('range', `${from}-${to}`);
+        }
+        const url = `${this.baseUrl}/${type}/title/${titleId}?${urlParams.toString()}`;
+        try {
+            const data = await this.fetchWithAuth(url);
+            return this.parseTitleDetail(data);
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.includes('404')) {
+                return null;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Search for images and maps
+     */
+    async searchImages(query, options) {
+        return this.search({
+            query,
+            category: 'image',
+            format: options?.format,
+            dateFrom: options?.dateFrom,
+            dateTo: options?.dateTo,
+            limit: options?.limit,
+        });
+    }
+    /**
+     * Search newspapers with Victorian focus
+     */
+    async searchVictorianNewspapers(query, options) {
+        return this.search({
+            query,
+            category: 'newspaper',
+            state: 'vic',
+            dateFrom: options?.dateFrom,
+            dateTo: options?.dateTo,
+            includeFullText: options?.includeFullText,
+            limit: options?.limit,
+        });
+    }
+    /**
+     * Check if API key is configured
+     */
+    hasApiKey() {
+        return !!this.apiKey;
+    }
+    // =========================================================================
+    // Private helpers
+    // =========================================================================
+    async fetchWithAuth(url) {
+        if (!this.apiKey) {
+            throw new Error('TROVE_API_KEY not configured');
+        }
+        const response = await fetch(url, {
+            headers: {
+                'X-API-KEY': this.apiKey,
+                'Accept': 'application/json',
+            },
+        });
+        if (!response.ok) {
+            throw new Error(`Trove API error: ${response.status} ${response.statusText}`);
+        }
+        return response.json();
+    }
+    parseSearchResponse(data, query) {
+        // Trove v3 returns results grouped by category
+        const categories = data.category ?? [];
+        // Combine results from all categories
+        let totalResults = 0;
+        let nextStart;
+        const records = [];
+        for (const cat of categories) {
+            const catRecords = cat.records ?? {};
+            totalResults += catRecords.total ?? 0;
+            nextStart = catRecords.nextStart ?? nextStart;
+            const items = catRecords.article ?? catRecords.work ?? [];
+            for (const item of items) {
+                if (cat.code === 'newspaper' || cat.code === 'gazette') {
+                    records.push(this.parseArticle(item));
+                }
+                else {
+                    records.push(this.parseWork(item));
+                }
+            }
+        }
+        return {
+            query,
+            category: categories.map((c) => c.code).join(','),
+            totalResults,
+            nextStart,
+            records,
+        };
+    }
+    parseArticle(data) {
+        return {
+            id: data.id?.toString() ?? '',
+            heading: data.heading ?? 'Untitled',
+            title: data.title ?? '',
+            titleId: data.title?.id?.toString() ?? '',
+            date: data.date ?? '',
+            page: data.page ?? '',
+            category: data.category ?? 'Article',
+            snippet: data.snippet ?? undefined,
+            fullText: data.articleText ?? undefined,
+            troveUrl: data.troveUrl ?? `https://trove.nla.gov.au/newspaper/article/${data.id}`,
+            pdfUrl: data.pdf ?? undefined,
+            wordCount: data.wordCount ?? undefined,
+            correctionCount: data.correctionCount ?? undefined,
+            illustrated: data.illustrated === 'Y',
+        };
+    }
+    parseWork(data) {
+        const types = Array.isArray(data.type) ? data.type : [data.type].filter(Boolean);
+        return {
+            id: data.id?.toString() ?? '',
+            title: data.title ?? 'Untitled',
+            contributor: data.contributor ?? undefined,
+            issued: data.issued ?? undefined,
+            type: types,
+            holdingsCount: data.holdingsCount ?? undefined,
+            versionCount: data.versionCount ?? undefined,
+            troveUrl: data.troveUrl ?? `https://trove.nla.gov.au/work/${data.id}`,
+            thumbnailUrl: this.extractThumbnail(data),
+            abstract: data.abstract ?? undefined,
+            subjects: data.subject ?? undefined,
+        };
+    }
+    parseNewspaperTitles(data) {
+        const titles = data.newspaper ?? data.gazette ?? [];
+        return titles.map((t) => ({
+            id: t.id?.toString() ?? '',
+            title: t.title ?? 'Untitled',
+            state: t.state ?? '',
+            issn: t.issn ?? undefined,
+            startDate: t.startDate ?? '',
+            endDate: t.endDate ?? '',
+            troveUrl: t.troveUrl ?? `https://trove.nla.gov.au/newspaper/title/${t.id}`,
+        }));
+    }
+    parseTitleDetail(data) {
+        const base = data.newspaper ?? data.gazette ?? data;
+        const result = {
+            id: base.id?.toString() ?? '',
+            title: base.title ?? 'Untitled',
+            state: base.state ?? '',
+            issn: base.issn ?? undefined,
+            startDate: base.startDate ?? '',
+            endDate: base.endDate ?? '',
+            troveUrl: base.troveUrl ?? '',
+        };
+        // Parse years if included
+        if (base.year) {
+            result.years = base.year.map((y) => ({
+                year: y.date ?? y.toString(),
+                issueCount: y.issuecount ?? 0,
+            }));
+            // Parse issues within years
+            const issues = [];
+            for (const year of base.year) {
+                if (year.issue) {
+                    for (const iss of year.issue) {
+                        issues.push({
+                            id: iss.id?.toString() ?? '',
+                            date: iss.date ?? '',
+                            url: iss.url ?? '',
+                        });
+                    }
+                }
+            }
+            if (issues.length > 0) {
+                result.issues = issues;
+            }
+        }
+        return result;
+    }
+    extractThumbnail(data) {
+        if (data.identifier) {
+            const identifiers = Array.isArray(data.identifier)
+                ? data.identifier
+                : [data.identifier];
+            for (const id of identifiers) {
+                if (id.linktype === 'thumbnail' && id.value) {
+                    return id.value;
+                }
+            }
+        }
+        return undefined;
+    }
+}
+// Export factory function (allows lazy initialization with API key)
+export function createTroveClient(apiKey) {
+    return new TroveClient(apiKey);
+}
+//# sourceMappingURL=trove_client.js.map

package/dist/clients/trove_client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trove_client.js","sourceRoot":"","sources":["../../src/clients/trove_client.ts"],"names":[],"mappings":"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"}

package/dist/core/base-client.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Base Client
+ *
+ * Shared HTTP client functionality for all data sources.
+ * Provides common patterns for fetch, error handling, and retries.
+ */
+/**
+ * Options for fetch requests
+ */
+export interface FetchOptions extends RequestInit {
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Number of retry attempts for transient failures */
+    retries?: number;
+    /** Custom error handler */
+    onError?: (error: Error) => void;
+}
+/**
+ * Base client with shared fetch functionality
+ */
+export declare abstract class BaseClient {
+    protected readonly baseUrl: string;
+    protected readonly userAgent: string;
+    protected readonly defaultTimeout: number;
+    constructor(baseUrl: string, options?: {
+        userAgent?: string;
+        timeout?: number;
+    });
+    /**
+     * Make a JSON fetch request with standard error handling
+     */
+    protected fetchJSON<T>(url: string, options?: FetchOptions): Promise<T>;
+    /**
+     * Make a fetch request and return raw response (for header-based pagination)
+     */
+    protected fetchWithHeaders<T>(url: string, options?: FetchOptions): Promise<{
+        data: T;
+        headers: Headers;
+    }>;
+    /**
+     * Build URL with query parameters
+     */
+    protected buildUrl(path: string, params?: Record<string, unknown>): string;
+    /**
+     * Delay helper for retries
+     */
+    protected delay(ms: number): Promise<void>;
+}
+//# sourceMappingURL=base-client.d.ts.map

package/dist/core/base-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-client.d.ts","sourceRoot":"","sources":["../../src/core/base-client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;GAEG;AACH,MAAM,WAAW,YAAa,SAAQ,WAAW;IAC/C,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2BAA2B;IAC3B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAED;;GAEG;AACH,8BAAsB,UAAU;IAC9B,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACnC,SAAS,CAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IACrC,SAAS,CAAC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;gBAE9B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE;IAM/E;;OAEG;cACa,SAAS,CAAC,CAAC,EACzB,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,CAAC,CAAC;IA0Db;;OAEG;cACa,gBAAgB,CAAC,CAAC,EAChC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC;QAAE,IAAI,EAAE,CAAC,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAiCzC;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM;IAoB1E;;OAEG;IACH,SAAS,CAAC,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAG3C"}

package/dist/core/base-client.js

@@ -0,0 +1,116 @@
+/**
+ * Base Client
+ *
+ * Shared HTTP client functionality for all data sources.
+ * Provides common patterns for fetch, error handling, and retries.
+ */
+import { APIRequestError } from './types.js';
+/**
+ * Base client with shared fetch functionality
+ */
+export class BaseClient {
+    baseUrl;
+    userAgent;
+    defaultTimeout;
+    constructor(baseUrl, options) {
+        this.baseUrl = baseUrl.replace(/\/$/, ''); // Remove trailing slash
+        this.userAgent = options?.userAgent ?? 'australian-history-mcp/0.6.0';
+        this.defaultTimeout = options?.timeout ?? 30000;
+    }
+    /**
+     * Make a JSON fetch request with standard error handling
+     */
+    async fetchJSON(url, options = {}) {
+        const { timeout = this.defaultTimeout, retries = 0, ...fetchOptions } = options;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeout);
+        try {
+            const response = await fetch(url, {
+                ...fetchOptions,
+                signal: controller.signal,
+                headers: {
+                    'Accept': 'application/json',
+                    'User-Agent': this.userAgent,
+                    ...fetchOptions.headers,
+                },
+            });
+            if (!response.ok) {
+                const _body = await response.text().catch(() => 'No response body');
+                throw new APIRequestError(`HTTP ${response.status}: ${response.statusText}`, `HTTP_${response.status}`, response.status, response.status >= 500 || response.status === 429);
+            }
+            return await response.json();
+        }
+        catch (error) {
+            if (error instanceof APIRequestError) {
+                // If retryable and retries remaining, retry after delay
+                if (error.retryable && retries > 0) {
+                    await this.delay(1000 * (4 - retries)); // Backoff: 1s, 2s, 3s
+                    return this.fetchJSON(url, { ...options, retries: retries - 1 });
+                }
+                throw error;
+            }
+            if (error instanceof Error && error.name === 'AbortError') {
+                throw new APIRequestError(`Request timeout after ${timeout}ms`, 'TIMEOUT', undefined, true);
+            }
+            throw new APIRequestError(error instanceof Error ? error.message : 'Unknown fetch error', 'FETCH_ERROR', undefined, false);
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Make a fetch request and return raw response (for header-based pagination)
+     */
+    async fetchWithHeaders(url, options = {}) {
+        const { timeout = this.defaultTimeout, ...fetchOptions } = options;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeout);
+        try {
+            const response = await fetch(url, {
+                ...fetchOptions,
+                signal: controller.signal,
+                headers: {
+                    'Accept': 'application/json',
+                    'User-Agent': this.userAgent,
+                    ...fetchOptions.headers,
+                },
+            });
+            if (!response.ok) {
+                throw new APIRequestError(`HTTP ${response.status}: ${response.statusText}`, `HTTP_${response.status}`, response.status, response.status >= 500 || response.status === 429);
+            }
+            const data = await response.json();
+            return { data, headers: response.headers };
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Build URL with query parameters
+     */
+    buildUrl(path, params) {
+        const url = new URL(path.startsWith('http') ? path : `${this.baseUrl}${path}`);
+        if (params) {
+            for (const [key, value] of Object.entries(params)) {
+                if (value !== undefined && value !== null && value !== '') {
+                    if (Array.isArray(value)) {
+                        for (const v of value) {
+                            url.searchParams.append(key, String(v));
+                        }
+                    }
+                    else {
+                        url.searchParams.set(key, String(value));
+                    }
+                }
+            }
+        }
+        return url.toString();
+    }
+    /**
+     * Delay helper for retries
+     */
+    delay(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+}
+//# sourceMappingURL=base-client.js.map

package/dist/core/base-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-client.js","sourceRoot":"","sources":["../../src/core/base-client.ts"],"names":[],"mappings":"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"}

package/dist/core/base-source.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Base Source Interface
+ *
+ * Defines the contract that all data sources must implement
+ * to integrate with the Australian History MCP server.
+ */
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { MCPToolResponse } from './types.js';
+/**
+ * A single tool provided by a source
+ */
+export interface SourceTool {
+    /** MCP tool schema (name, description, inputSchema) */
+    schema: Tool;
+    /** Function to execute the tool with validated arguments */
+    execute: (args: Record<string, unknown>) => Promise<MCPToolResponse>;
+}
+/**
+ * A data source that provides tools to the MCP server
+ */
+export interface Source {
+    /** Short identifier (e.g., 'prov', 'trove', 'museumsvic') */
+    name: string;
+    /** Human-readable name (e.g., 'Public Record Office Victoria') */
+    displayName: string;
+    /** All tools provided by this source */
+    tools: SourceTool[];
+    /** Whether this source requires authentication */
+    requiresAuth?: boolean;
+    /** Environment variable name for auth (e.g., 'TROVE_API_KEY') */
+    authEnvVar?: string;
+    /** Function to check if auth is properly configured */
+    checkAuth?: () => boolean;
+    /** Optional description of what this source provides */
+    description?: string;
+}
+/**
+ * Helper to create a SourceTool from schema and executor
+ */
+export declare function createTool(schema: Tool, execute: (args: Record<string, unknown>) => Promise<MCPToolResponse>): SourceTool;
+/**
+ * Helper to create a Source definition
+ */
+export declare function defineSource(config: Source): Source;
+//# sourceMappingURL=base-source.d.ts.map

package/dist/core/base-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-source.d.ts","sourceRoot":"","sources":["../../src/core/base-source.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,uDAAuD;IACvD,MAAM,EAAE,IAAI,CAAC;IACb,4DAA4D;IAC5D,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;CACtE;AAED;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IAEb,kEAAkE;IAClE,WAAW,EAAE,MAAM,CAAC;IAEpB,wCAAwC;IACxC,KAAK,EAAE,UAAU,EAAE,CAAC;IAEpB,kDAAkD;IAClD,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC;IAE1B,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,IAAI,EACZ,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,eAAe,CAAC,GACnE,UAAU,CAEZ;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEnD"}

package/dist/core/base-source.js

@@ -0,0 +1,19 @@
+/**
+ * Base Source Interface
+ *
+ * Defines the contract that all data sources must implement
+ * to integrate with the Australian History MCP server.
+ */
+/**
+ * Helper to create a SourceTool from schema and executor
+ */
+export function createTool(schema, execute) {
+    return { schema, execute };
+}
+/**
+ * Helper to create a Source definition
+ */
+export function defineSource(config) {
+    return config;
+}
+//# sourceMappingURL=base-source.js.map

package/dist/core/base-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-source.js","sourceRoot":"","sources":["../../src/core/base-source.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAyCH;;GAEG;AACH,MAAM,UAAU,UAAU,CACxB,MAAY,EACZ,OAAoE;IAEpE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;AAC7B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/core/harvest-runner.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Harvest Runner
+ *
+ * Shared pagination and batch harvesting logic used by all sources.
+ * Eliminates duplicate harvest implementations across sources.
+ */
+import type { HarvestConfig, HarvestResult } from './types.js';
+/**
+ * Run a harvest operation with consistent pagination handling
+ *
+ * Supports three pagination modes:
+ * - 'offset': Numeric offset (PROV, data.gov.au)
+ * - 'cursor': String-based cursor (Trove)
+ * - 'page': Page numbers (Museums Victoria)
+ */
+export declare function runHarvest<T>(source: string, query: string, config: HarvestConfig<T>): Promise<HarvestResult<T>>;
+/**
+ * Calculate pagination info for response formatting
+ */
+export declare function formatPaginationInfo(harvested: number, total: number, hasMore: boolean, nextCursor?: string | number): {
+    harvested: number;
+    totalAvailable: number;
+    hasMore: boolean;
+    nextOffset?: string;
+};
+//# sourceMappingURL=harvest-runner.d.ts.map