@yangfei_93sky/biocli 0.2.0

package/dist/databases/enrichr.js

@@ -0,0 +1,131 @@
+/**
+ * Enrichr database backend for biocli.
+ *
+ * Enrichr API (https://maayanlab.cloud/Enrichr):
+ *   - No authentication required
+ *   - Rate limit: undocumented (we use 5/s conservatively)
+ *   - 2-step workflow: POST /addList → GET /enrich
+ *   - Response format: JSON
+ *
+ * Popular gene set libraries:
+ *   KEGG_2021_Human, GO_Biological_Process_2023, GO_Molecular_Function_2023,
+ *   GO_Cellular_Component_2023, WikiPathway_2023_Human, Reactome_2022,
+ *   MSigDB_Hallmark_2020, DisGeNET, OMIM_Disease, GWAS_Catalog_2023
+ */
+import { getRateLimiterForDatabase } from '../rate-limiter.js';
+import { ApiError } from '../errors.js';
+import { sleep } from '../utils.js';
+import { registerBackend } from './index.js';
+const BASE_URL = 'https://maayanlab.cloud/Enrichr';
+const MAX_RETRIES = 2;
+const BASE_RETRY_DELAY_MS = 500;
+/** Low-level Enrichr fetch. */
+async function enrichrFetch(url, opts) {
+    if (!opts?.skipRateLimit) {
+        const limiter = getRateLimiterForDatabase('enrichr', 5);
+        await limiter.acquire();
+    }
+    let lastError;
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        try {
+            const response = await fetch(url, {
+                method: opts?.method ?? 'GET',
+                headers: opts?.formData ? undefined : opts?.headers,
+                body: opts?.formData ?? opts?.body,
+            });
+            if (response.status === 429) {
+                if (attempt < MAX_RETRIES) {
+                    await sleep(BASE_RETRY_DELAY_MS * Math.pow(2, attempt));
+                    continue;
+                }
+                throw new ApiError('Enrichr API rate limit exceeded');
+            }
+            if (!response.ok) {
+                throw new ApiError(`Enrichr API returned HTTP ${response.status}: ${response.statusText}`);
+            }
+            return response;
+        }
+        catch (err) {
+            if (err instanceof ApiError)
+                throw err;
+            lastError = err instanceof Error ? err : new Error(String(err));
+            if (attempt < MAX_RETRIES) {
+                await sleep(BASE_RETRY_DELAY_MS * Math.pow(2, attempt));
+                continue;
+            }
+        }
+    }
+    throw new ApiError(`Enrichr request failed after ${MAX_RETRIES + 1} attempts: ${lastError?.message ?? 'unknown error'}`);
+}
+/**
+ * Submit a gene list to Enrichr and return the userListId.
+ * This is step 1 of the 2-step workflow.
+ *
+ * NOTE: Enrichr requires multipart/form-data (not URL-encoded).
+ */
+export async function submitGeneList(genes, description) {
+    const formData = new FormData();
+    formData.set('list', genes.join('\n'));
+    formData.set('description', description ?? 'biocli analysis');
+    // FormData sets Content-Type with boundary automatically
+    const response = await enrichrFetch(`${BASE_URL}/addList`, {
+        method: 'POST',
+        formData,
+    });
+    const data = await response.json();
+    const userListId = data.userListId;
+    if (typeof userListId !== 'number') {
+        throw new ApiError('Enrichr did not return a valid userListId');
+    }
+    return userListId;
+}
+/**
+ * Get enrichment results for a submitted gene list.
+ * This is step 2 of the 2-step workflow.
+ */
+export async function getEnrichment(userListId, library) {
+    const response = await enrichrFetch(`${BASE_URL}/enrich?userListId=${userListId}&backgroundType=${encodeURIComponent(library)}`);
+    const data = await response.json();
+    const results = data[library];
+    if (!Array.isArray(results))
+        return [];
+    // Enrichr returns arrays of arrays:
+    // [rank, term_name, p_value, z_score, combined_score, [overlapping_genes], adj_p, old_p, old_adj_p]
+    return results.map((row) => ({
+        rank: Number(row[0] ?? 0),
+        term: String(row[1] ?? ''),
+        pValue: Number(row[2] ?? 1),
+        zScore: Number(row[3] ?? 0),
+        combinedScore: Number(row[4] ?? 0),
+        genes: Array.isArray(row[5]) ? row[5].join(',') : '',
+        adjustedPValue: Number(row[6] ?? 1),
+    }));
+}
+function createContext() {
+    return {
+        databaseId: 'enrichr',
+        async fetch(url, opts) {
+            return enrichrFetch(url, opts);
+        },
+        async fetchJson(url, opts) {
+            const response = await enrichrFetch(url, opts);
+            return response.json();
+        },
+        async fetchXml(url, opts) {
+            const response = await enrichrFetch(url, opts);
+            return response.text();
+        },
+        async fetchText(url, opts) {
+            const response = await enrichrFetch(url, opts);
+            return response.text();
+        },
+    };
+}
+export const enrichrBackend = {
+    id: 'enrichr',
+    name: 'Enrichr',
+    baseUrl: BASE_URL,
+    rateLimit: 5,
+    createContext,
+};
+registerBackend(enrichrBackend);

package/dist/databases/ensembl.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Ensembl database backend for biocli.
+ *
+ * Ensembl REST API (https://rest.ensembl.org):
+ *   - No authentication required
+ *   - Rate limit: 15 req/s, 55,000 req/hr (strictly enforced)
+ *   - Returns HTTP 429 with Retry-After header when exceeded
+ *   - Response format: JSON (default), XML
+ *   - GRCh37: https://grch37.rest.ensembl.org
+ */
+import { type DatabaseBackend } from './index.js';
+/** Build an Ensembl API URL. */
+export declare function buildEnsemblUrl(path: string, params?: Record<string, string>): string;
+export declare const ensemblBackend: DatabaseBackend;

package/dist/databases/ensembl.js

@@ -0,0 +1,106 @@
+/**
+ * Ensembl database backend for biocli.
+ *
+ * Ensembl REST API (https://rest.ensembl.org):
+ *   - No authentication required
+ *   - Rate limit: 15 req/s, 55,000 req/hr (strictly enforced)
+ *   - Returns HTTP 429 with Retry-After header when exceeded
+ *   - Response format: JSON (default), XML
+ *   - GRCh37: https://grch37.rest.ensembl.org
+ */
+import { getRateLimiterForDatabase } from '../rate-limiter.js';
+import { ApiError } from '../errors.js';
+import { sleep } from '../utils.js';
+import { registerBackend } from './index.js';
+const BASE_URL = 'https://rest.ensembl.org';
+const MAX_RETRIES = 3;
+const BASE_RETRY_DELAY_MS = 500;
+/** Build an Ensembl API URL. */
+export function buildEnsemblUrl(path, params) {
+    const url = new URL(`${BASE_URL}${path}`);
+    if (params) {
+        for (const [k, v] of Object.entries(params)) {
+            if (v !== undefined && v !== '')
+                url.searchParams.set(k, v);
+        }
+    }
+    return url.toString();
+}
+/** Low-level Ensembl fetch with rate limiting and retry. */
+async function ensemblFetch(url, opts) {
+    if (!opts?.skipRateLimit) {
+        const limiter = getRateLimiterForDatabase('ensembl', 15);
+        await limiter.acquire();
+    }
+    let lastError;
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        try {
+            const response = await fetch(url, {
+                method: opts?.method ?? 'GET',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Accept': 'application/json',
+                    ...opts?.headers,
+                },
+                body: opts?.body,
+            });
+            if (response.status === 429) {
+                const retryAfter = response.headers.get('Retry-After');
+                const delayMs = retryAfter
+                    ? parseFloat(retryAfter) * 1000
+                    : BASE_RETRY_DELAY_MS * Math.pow(2, attempt);
+                if (attempt < MAX_RETRIES) {
+                    await sleep(delayMs);
+                    continue;
+                }
+                throw new ApiError('Ensembl API rate limit exceeded. Try again later.');
+            }
+            if (response.status === 400) {
+                const body = await response.text();
+                throw new ApiError(`Ensembl API error: ${body}`);
+            }
+            if (!response.ok) {
+                throw new ApiError(`Ensembl API returned HTTP ${response.status}: ${response.statusText}`);
+            }
+            return response;
+        }
+        catch (err) {
+            if (err instanceof ApiError)
+                throw err;
+            lastError = err instanceof Error ? err : new Error(String(err));
+            if (attempt < MAX_RETRIES) {
+                await sleep(BASE_RETRY_DELAY_MS * Math.pow(2, attempt));
+                continue;
+            }
+        }
+    }
+    throw new ApiError(`Ensembl request failed after ${MAX_RETRIES + 1} attempts: ${lastError?.message ?? 'unknown error'}`);
+}
+function createContext() {
+    return {
+        databaseId: 'ensembl',
+        async fetch(url, opts) {
+            return ensemblFetch(url, opts);
+        },
+        async fetchJson(url, opts) {
+            const response = await ensemblFetch(url, opts);
+            return response.json();
+        },
+        async fetchXml(url, opts) {
+            const response = await ensemblFetch(url, opts);
+            return response.text();
+        },
+        async fetchText(url, opts) {
+            const response = await ensemblFetch(url, opts);
+            return response.text();
+        },
+    };
+}
+export const ensemblBackend = {
+    id: 'ensembl',
+    name: 'Ensembl',
+    baseUrl: BASE_URL,
+    rateLimit: 15,
+    createContext,
+};
+registerBackend(ensemblBackend);

package/dist/databases/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Database backend abstraction layer.
+ *
+ * Each supported database (NCBI, UniProt, KEGG, STRING, Ensembl, Enrichr)
+ * implements the DatabaseBackend interface and registers itself here.
+ * The execution layer uses createHttpContextForDatabase() to get the
+ * right HTTP client for each command.
+ */
+import type { HttpContext } from '../types.js';
+export interface DatabaseBackend {
+    /** Unique identifier (e.g. 'ncbi', 'uniprot', 'kegg'). */
+    readonly id: string;
+    /** Human-readable name (e.g. 'NCBI', 'UniProt'). */
+    readonly name: string;
+    /** Base URL for the API. */
+    readonly baseUrl: string;
+    /** Default rate limit: max requests per second. */
+    readonly rateLimit: number;
+    /** Create an HttpContext bound to this database's rate limiter and auth. */
+    createContext(): HttpContext;
+}
+declare global {
+    var __biocli_backends__: Map<string, DatabaseBackend> | undefined;
+}
+/** Register a database backend. */
+export declare function registerBackend(backend: DatabaseBackend): void;
+/** Get a registered backend by ID, or undefined if not found. */
+export declare function getBackend(id: string): DatabaseBackend | undefined;
+/** Get all registered backends. */
+export declare function getAllBackends(): DatabaseBackend[];
+/**
+ * Create an HttpContext for a specific database.
+ *
+ * This is the main entry point used by execution.ts. It replaces the
+ * NCBI-hardcoded createHttpContext() with a database-aware factory.
+ *
+ * Lookup strategy:
+ *   1. Exact match on databaseId (e.g. 'ncbi', 'uniprot')
+ *   2. If not found and looks like an NCBI sub-database (pubmed, gene, etc.),
+ *      fall back to the 'ncbi' backend
+ *
+ * For 'aggregate' commands (which need multiple databases), the command's
+ * func() creates its own contexts — this function is not called.
+ */
+export declare function createHttpContextForDatabase(databaseId: string): HttpContext;

package/dist/databases/index.js

@@ -0,0 +1,49 @@
+/**
+ * Database backend abstraction layer.
+ *
+ * Each supported database (NCBI, UniProt, KEGG, STRING, Ensembl, Enrichr)
+ * implements the DatabaseBackend interface and registers itself here.
+ * The execution layer uses createHttpContextForDatabase() to get the
+ * right HTTP client for each command.
+ */
+const _backends = globalThis.__biocli_backends__ ??= new Map();
+/** Register a database backend. */
+export function registerBackend(backend) {
+    _backends.set(backend.id, backend);
+}
+/** Get a registered backend by ID, or undefined if not found. */
+export function getBackend(id) {
+    return _backends.get(id);
+}
+/** Get all registered backends. */
+export function getAllBackends() {
+    return [..._backends.values()];
+}
+/**
+ * Create an HttpContext for a specific database.
+ *
+ * This is the main entry point used by execution.ts. It replaces the
+ * NCBI-hardcoded createHttpContext() with a database-aware factory.
+ *
+ * Lookup strategy:
+ *   1. Exact match on databaseId (e.g. 'ncbi', 'uniprot')
+ *   2. If not found and looks like an NCBI sub-database (pubmed, gene, etc.),
+ *      fall back to the 'ncbi' backend
+ *
+ * For 'aggregate' commands (which need multiple databases), the command's
+ * func() creates its own contexts — this function is not called.
+ */
+export function createHttpContextForDatabase(databaseId) {
+    // Direct match
+    let backend = _backends.get(databaseId);
+    // Fallback: NCBI sub-database names (pubmed, gene, gds, sra, clinvar, snp, taxonomy)
+    // route to the 'ncbi' backend
+    if (!backend && _backends.has('ncbi')) {
+        backend = _backends.get('ncbi');
+    }
+    if (!backend) {
+        throw new Error(`Unknown database backend: "${databaseId}". ` +
+            `Available: ${[..._backends.keys()].join(', ') || '(none registered)'}`);
+    }
+    return backend.createContext();
+}

package/dist/databases/kegg.d.ts

@@ -0,0 +1,26 @@
+/**
+ * KEGG database backend for biocli.
+ *
+ * KEGG REST API (https://rest.kegg.jp):
+ *   - No authentication required
+ *   - Rate limit: undocumented (we use 10/s conservatively)
+ *   - Response format: tab-delimited text (NOT JSON) for most endpoints
+ *   - Max 10 entries per /get request
+ */
+import { type DatabaseBackend } from './index.js';
+/** Build a KEGG API URL. */
+export declare function buildKeggUrl(path: string): string;
+/**
+ * Parse KEGG tab-delimited response into key-value pairs.
+ * Most KEGG endpoints return lines like "hsa:7157\thsa05200"
+ */
+export declare function parseKeggTsv(text: string): Array<{
+    key: string;
+    value: string;
+}>;
+/**
+ * Parse KEGG flat-file /get response into structured sections.
+ * KEGG /get returns a flat-file format with labeled fields.
+ */
+export declare function parseKeggEntry(text: string): Record<string, string>;
+export declare const keggBackend: DatabaseBackend;

package/dist/databases/kegg.js

@@ -0,0 +1,136 @@
+/**
+ * KEGG database backend for biocli.
+ *
+ * KEGG REST API (https://rest.kegg.jp):
+ *   - No authentication required
+ *   - Rate limit: undocumented (we use 10/s conservatively)
+ *   - Response format: tab-delimited text (NOT JSON) for most endpoints
+ *   - Max 10 entries per /get request
+ */
+import { getRateLimiterForDatabase } from '../rate-limiter.js';
+import { ApiError } from '../errors.js';
+import { sleep } from '../utils.js';
+import { registerBackend } from './index.js';
+const BASE_URL = 'https://rest.kegg.jp';
+const MAX_RETRIES = 2;
+const BASE_RETRY_DELAY_MS = 500;
+/** Build a KEGG API URL. */
+export function buildKeggUrl(path) {
+    return `${BASE_URL}${path}`;
+}
+/**
+ * Parse KEGG tab-delimited response into key-value pairs.
+ * Most KEGG endpoints return lines like "hsa:7157\thsa05200"
+ */
+export function parseKeggTsv(text) {
+    return text.trim().split('\n').filter(Boolean).map(line => {
+        const [key, ...rest] = line.split('\t');
+        return { key: key?.trim() ?? '', value: rest.join('\t').trim() };
+    });
+}
+/**
+ * Parse KEGG flat-file /get response into structured sections.
+ * KEGG /get returns a flat-file format with labeled fields.
+ */
+export function parseKeggEntry(text) {
+    const result = {};
+    let currentKey = '';
+    let currentValue = '';
+    for (const line of text.split('\n')) {
+        if (line === '///')
+            break; // end of entry
+        const match = line.match(/^([A-Z_]+)\s+(.*)/);
+        if (match) {
+            if (currentKey)
+                result[currentKey] = currentValue.trim();
+            currentKey = match[1];
+            currentValue = match[2];
+        }
+        else if (line.startsWith('            ') || line.startsWith('  ')) {
+            // Continuation line
+            currentValue += ' ' + line.trim();
+        }
+    }
+    if (currentKey)
+        result[currentKey] = currentValue.trim();
+    return result;
+}
+/** Low-level KEGG fetch with rate limiting and retry. */
+async function keggFetch(url, opts) {
+    if (!opts?.skipRateLimit) {
+        const limiter = getRateLimiterForDatabase('kegg', 10);
+        await limiter.acquire();
+    }
+    let lastError;
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        try {
+            const response = await fetch(url, {
+                method: opts?.method ?? 'GET',
+                headers: opts?.headers,
+                body: opts?.body,
+            });
+            if (response.status === 403 || response.status === 429) {
+                if (attempt < MAX_RETRIES) {
+                    await sleep(BASE_RETRY_DELAY_MS * Math.pow(2, attempt));
+                    continue;
+                }
+                throw new ApiError('KEGG API rate limit exceeded. Try again shortly.');
+            }
+            if (response.status === 404) {
+                throw new ApiError('KEGG entry not found');
+            }
+            if (!response.ok) {
+                throw new ApiError(`KEGG API returned HTTP ${response.status}: ${response.statusText}`);
+            }
+            return response;
+        }
+        catch (err) {
+            if (err instanceof ApiError)
+                throw err;
+            lastError = err instanceof Error ? err : new Error(String(err));
+            if (attempt < MAX_RETRIES) {
+                await sleep(BASE_RETRY_DELAY_MS * Math.pow(2, attempt));
+                continue;
+            }
+        }
+    }
+    throw new ApiError(`KEGG request failed after ${MAX_RETRIES + 1} attempts: ${lastError?.message ?? 'unknown error'}`);
+}
+/** Create a KEGG HttpContext. */
+function createContext() {
+    return {
+        databaseId: 'kegg',
+        async fetch(url, opts) {
+            return keggFetch(url, opts);
+        },
+        async fetchJson(url, opts) {
+            // KEGG rarely returns JSON; parse TSV into array of objects
+            const response = await keggFetch(url, opts);
+            const text = await response.text();
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                // Not JSON — return as parsed TSV
+                return parseKeggTsv(text);
+            }
+        },
+        async fetchXml(url, opts) {
+            const response = await keggFetch(url, opts);
+            return response.text();
+        },
+        async fetchText(url, opts) {
+            const response = await keggFetch(url, opts);
+            return response.text();
+        },
+    };
+}
+// ── Backend registration ─────────────────────────────────────────────────────
+export const keggBackend = {
+    id: 'kegg',
+    name: 'KEGG',
+    baseUrl: BASE_URL,
+    rateLimit: 10,
+    createContext,
+};
+registerBackend(keggBackend);

package/dist/databases/ncbi.d.ts

@@ -0,0 +1,28 @@
+/**
+ * NCBI database backend for biocli.
+ *
+ * Provides an NCBI-aware HTTP client that automatically:
+ *   - Injects api_key and email into URL params
+ *   - Applies rate limiting (3/s anonymous, 10/s with API key)
+ *   - Retries on HTTP 429 with exponential backoff
+ *   - Parses XML and JSON responses
+ *
+ * Refactored from the original ncbi-fetch.ts into the DatabaseBackend
+ * pattern. The original ncbi-fetch.ts is kept as a re-export shim.
+ */
+import type { HttpContext, FetchOptions } from '../types.js';
+import { type DatabaseBackend } from './index.js';
+export declare const EUTILS_BASE = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils";
+/**
+ * Build a full E-utilities URL for a given tool endpoint.
+ */
+export declare function buildEutilsUrl(tool: string, params: Record<string, string>): string;
+/**
+ * Low-level NCBI fetch with rate limiting and retry.
+ */
+export declare function ncbiFetch(url: string, opts?: FetchOptions, apiKey?: string, email?: string): Promise<Response>;
+/**
+ * Create an NCBI HttpContext for command execution.
+ */
+export declare function createHttpContext(): HttpContext;
+export declare const ncbiBackend: DatabaseBackend;

package/dist/databases/ncbi.js

@@ -0,0 +1,144 @@
+/**
+ * NCBI database backend for biocli.
+ *
+ * Provides an NCBI-aware HTTP client that automatically:
+ *   - Injects api_key and email into URL params
+ *   - Applies rate limiting (3/s anonymous, 10/s with API key)
+ *   - Retries on HTTP 429 with exponential backoff
+ *   - Parses XML and JSON responses
+ *
+ * Refactored from the original ncbi-fetch.ts into the DatabaseBackend
+ * pattern. The original ncbi-fetch.ts is kept as a re-export shim.
+ */
+import { getApiKey, getEmail } from '../config.js';
+import { getRateLimiter } from '../rate-limiter.js';
+import { parseXml } from '../xml-parser.js';
+import { RateLimitError, ApiError } from '../errors.js';
+import { sleep } from '../utils.js';
+import { registerBackend } from './index.js';
+// ── Constants ────────────────────────────────────────────────────────────────
+export const EUTILS_BASE = 'https://eutils.ncbi.nlm.nih.gov/entrez/eutils';
+/** Maximum number of retries on HTTP 429 responses. */
+const MAX_RETRIES = 3;
+/** Base delay in ms for exponential backoff (doubled on each retry). */
+const BASE_RETRY_DELAY_MS = 500;
+/** Tool parameter sent to NCBI to identify this client. */
+const TOOL_NAME = 'biocli';
+// ── URL builder ──────────────────────────────────────────────────────────────
+/**
+ * Build a full E-utilities URL for a given tool endpoint.
+ */
+export function buildEutilsUrl(tool, params) {
+    const url = new URL(`${EUTILS_BASE}/${tool}`);
+    for (const [k, v] of Object.entries(params)) {
+        if (v !== undefined && v !== '')
+            url.searchParams.set(k, v);
+    }
+    return url.toString();
+}
+// ── Core fetch ───────────────────────────────────────────────────────────────
+/**
+ * Low-level NCBI fetch with rate limiting and retry.
+ */
+export async function ncbiFetch(url, opts, apiKey, email) {
+    const parsed = new URL(url);
+    if (opts?.params) {
+        for (const [k, v] of Object.entries(opts.params)) {
+            if (v !== undefined && v !== '')
+                parsed.searchParams.set(k, v);
+        }
+    }
+    if (apiKey && !parsed.searchParams.has('api_key')) {
+        parsed.searchParams.set('api_key', apiKey);
+    }
+    if (email && !parsed.searchParams.has('email')) {
+        parsed.searchParams.set('email', email);
+    }
+    if (!parsed.searchParams.has('tool')) {
+        parsed.searchParams.set('tool', TOOL_NAME);
+    }
+    const finalUrl = parsed.toString();
+    if (!opts?.skipRateLimit) {
+        const limiter = getRateLimiter(!!apiKey);
+        await limiter.acquire();
+    }
+    let lastError;
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        try {
+            const response = await fetch(finalUrl, {
+                method: opts?.method ?? 'GET',
+                headers: opts?.headers,
+                body: opts?.body,
+            });
+            if (response.status === 429) {
+                if (attempt < MAX_RETRIES) {
+                    const retryAfter = response.headers.get('Retry-After');
+                    const delayMs = retryAfter
+                        ? parseInt(retryAfter, 10) * 1000
+                        : BASE_RETRY_DELAY_MS * Math.pow(2, attempt);
+                    await sleep(delayMs);
+                    continue;
+                }
+                throw new RateLimitError(`NCBI returned 429 after ${MAX_RETRIES + 1} attempts`);
+            }
+            if (!response.ok) {
+                throw new ApiError(`NCBI API returned HTTP ${response.status}: ${response.statusText}`, `Request URL: ${finalUrl.replace(/api_key=[^&]+/, 'api_key=***')}`);
+            }
+            return response;
+        }
+        catch (err) {
+            if (err instanceof RateLimitError || err instanceof ApiError) {
+                throw err;
+            }
+            lastError = err instanceof Error ? err : new Error(String(err));
+            if (attempt < MAX_RETRIES) {
+                await sleep(BASE_RETRY_DELAY_MS * Math.pow(2, attempt));
+                continue;
+            }
+        }
+    }
+    throw new ApiError(`NCBI request failed after ${MAX_RETRIES + 1} attempts: ${lastError?.message ?? 'unknown error'}`);
+}
+// ── HttpContext factory ──────────────────────────────────────────────────────
+/**
+ * Create an NCBI HttpContext for command execution.
+ */
+export function createHttpContext() {
+    const apiKey = getApiKey();
+    const email = getEmail();
+    getRateLimiter(!!apiKey);
+    return {
+        databaseId: 'ncbi',
+        apiKey,
+        email,
+        credentials: {
+            ...(apiKey ? { api_key: apiKey } : {}),
+            ...(email ? { email } : {}),
+        },
+        async fetch(url, opts) {
+            return ncbiFetch(url, opts, apiKey, email);
+        },
+        async fetchXml(url, opts) {
+            const response = await ncbiFetch(url, opts, apiKey, email);
+            const text = await response.text();
+            return parseXml(text);
+        },
+        async fetchJson(url, opts) {
+            const response = await ncbiFetch(url, opts, apiKey, email);
+            return response.json();
+        },
+        async fetchText(url, opts) {
+            const response = await ncbiFetch(url, opts, apiKey, email);
+            return response.text();
+        },
+    };
+}
+// ── Backend registration ─────────────────────────────────────────────────────
+export const ncbiBackend = {
+    id: 'ncbi',
+    name: 'NCBI',
+    baseUrl: EUTILS_BASE,
+    rateLimit: 3,
+    createContext: createHttpContext,
+};
+registerBackend(ncbiBackend);