@cyanheads/pubchem-mcp-server 0.6.4 → 0.6.5

package/dist/services/pubchem/pubchem-client.js

@@ -3,9 +3,35 @@
  * Wraps both PUG REST and PUG View APIs behind a shared rate limiter.
  * @module services/pubchem/pubchem-client
  */
-import { JsonRpcErrorCode, McpError, notFound, serviceUnavailable, } from '@cyanheads/mcp-ts-core/errors';
+import { JsonRpcErrorCode, McpError, notFound, requestCancelled, serviceUnavailable, validationError, } from '@cyanheads/mcp-ts-core/errors';
 import { httpErrorFromResponse, logger, requestContextService } from '@cyanheads/mcp-ts-core/utils';
 const isNotFound = (error) => error instanceof McpError && error.code === JsonRpcErrorCode.NotFound;
+const isBadRequest = (error) => error instanceof McpError && error.data?.status === 400;
+/** The parsed upstream fault `fetchResponse` attaches to every HTTP failure. */
+const faultOf = (error) => {
+    const fault = error instanceof McpError ? error.data?.fault : undefined;
+    return typeof fault === 'string' ? fault : undefined;
+};
+/** PubChem's answer when a fast search cannot run on the query itself: a malformed SMILES or
+ * formula, a SMILES with a "*" wildcard atom, a CID with no record. Every re-send of a
+ * faulting request has faulted again, and no valid query has drawn it — a slow search gets
+ * 504 `PUGREST.Timeout`, a search with no hits 404 `PUGREST.NotFound`. So `fetchResponse`
+ * spends no retry on it, and the search methods, which know the query form, turn it into a
+ * typed `search_query_rejected`. */
+const SEARCH_REJECTED_FAULT = 'PUGREST.ServerError: Search status indicates failure';
+/** Re-throws a rejected-query fault from a fast search as `search_query_rejected`, with a
+ * hint for the query form the caller sent. Every other failure passes through unchanged. */
+function mapRejectedSearch(search, message, hint) {
+    return search.catch((error) => {
+        if (faultOf(error) !== SEARCH_REJECTED_FAULT)
+            throw error;
+        throw validationError(message, { reason: 'search_query_rejected', fault: SEARCH_REJECTED_FAULT, recovery: { hint } }, { cause: error });
+    });
+}
+/** CID 0 is PubChem's "no such structure" placeholder, never a compound: a SMILES lookup for a
+ * structure that parses but is not in the database answers 200 with `CID: [0]`. Dropped
+ * wherever a CID list is read, so no route can report it as a match. */
+const realCids = (cids) => cids.filter((cid) => cid > 0);
 /** Distinguishes the two outcomes PUG View hides behind a single HTTP 404.
  *
  * `heading=`-filtered PUG View requests answer both "this CID has no record" and "this CID's
@@ -17,12 +43,11 @@ const isNotFound = (error) => error instanceof McpError && error.code === JsonRp
  * Defaults to false when the message is missing or unrecognized: claiming a compound has no
  * data understates what is known, while wrongly claiming a CID does not exist sends the caller
  * chasing a correct identifier. */
-const isMissingRecord = (error) => {
-    if (!isNotFound(error))
-        return false;
-    const { fault } = (error.data ?? {});
-    return typeof fault === 'string' && fault.includes('No record found');
-};
+const isMissingRecord = (error) => isNotFound(error) && (faultOf(error)?.includes('No record found') ?? false);
+/** What a caller's cancellation surfaces as. `RequestCancelled` is never retried and the
+ * framework logs it at `info`; raising it here keeps a withdrawn call from reading as the 30 s
+ * timeout, and from matching the not-found checks that turn a 404 into "no data". */
+const cancellation = (reason) => requestCancelled('PubChem request cancelled by the caller.', undefined, { cause: reason });
 // ── Rate Limiter ─────────────────────────────────────────────────────
 /** Sliding-window rate limiter. Queues requests exceeding maxPerSecond. */
 class RateLimiter {
@@ -33,9 +58,23 @@ class RateLimiter {
     constructor(maxPerSecond) {
         this.max = maxPerSecond;
     }
-    acquire() {
-        return new Promise((resolve) => {
-            this.queue.push(resolve);
+    /** Waits for a slot. A caller that cancels while queued leaves the queue without taking one. */
+    acquire(signal) {
+        return new Promise((resolve, reject) => {
+            if (signal?.aborted) {
+                reject(cancellation(signal.reason));
+                return;
+            }
+            const grant = () => {
+                signal?.removeEventListener('abort', withdraw);
+                resolve();
+            };
+            const withdraw = () => {
+                this.queue.splice(this.queue.indexOf(grant), 1);
+                reject(cancellation(signal?.reason));
+            };
+            signal?.addEventListener('abort', withdraw, { once: true });
+            this.queue.push(grant);
             if (!this.draining)
                 void this.drain();
         });
@@ -61,8 +100,34 @@ class RateLimiter {
         this.draining = false;
     }
 }
-// ── Helpers ──────────────────────────────────────────────────────────
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Waits `ms`, or rejects with the cancellation as soon as `signal` aborts. */
+const sleep = (ms, signal) => new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+        reject(cancellation(signal.reason));
+        return;
+    }
+    const cancel = () => {
+        clearTimeout(timer);
+        reject(cancellation(signal?.reason));
+    };
+    const timer = setTimeout(() => {
+        signal?.removeEventListener('abort', cancel);
+        resolve();
+    }, ms);
+    signal?.addEventListener('abort', cancel, { once: true });
+});
+/** Reads a response body. The platform fetch aborts the body with the request's signal, so a
+ * caller abort mid-read surfaces as the cancellation instead of a raw abort. */
+async function readBody(read, signal) {
+    try {
+        return await read;
+    }
+    catch (error) {
+        if (signal?.aborted)
+            throw cancellation(signal.reason);
+        throw error;
+    }
+}
 /** Records a failed PubChem request, with its URL, in the server's own log. The error the
  * caller receives deliberately omits the URL, so this line is the only place an operator can
  * see which route failed. The module `logger` writes server-side only — `ctx.log` would also
@@ -412,19 +477,26 @@ export class PubChemClient {
     sdqBase = 'https://pubchem.ncbi.nlm.nih.gov/sdq/sdqagent.cgi';
     rateLimiter = new RateLimiter(5);
     // ── Core HTTP ────────────────────────────────────────────────────
-    /** Shared HTTP core: rate-limit, 30s timeout, retry once on 5xx and once on a transient
-     * network error, and surface a clean timeout message. Returns the ok Response; callers
-     * extract the body (JSON, bytes, or text). Centralizing this keeps every fetch variant on
-     * one resilience contract — the divergence that left fetchBinary without retry or a clean
-     * timeout message (#16) cannot recur. */
-    async fetchResponse(url, init) {
-        const method = init?.method ?? 'GET';
+    /** Shared HTTP core: rate-limit, 30s timeout, retry once on 5xx (except a rejected search
+     * query) and once on a transient network error, and surface a clean timeout message. Returns
+     * the ok Response; callers extract the body (JSON, bytes, or text). Centralizing this keeps
+     * every fetch variant on one resilience contract — the divergence that left fetchBinary
+     * without retry or a clean timeout message (#16) cannot recur.
+     *
+     * `init.signal` is the caller's cancellation, combined with the per-attempt timeout. Once it
+     * aborts — queued for a slot, mid-fetch, or in a retry backoff — the request ends with
+     * `RequestCancelled`: no retry, and no failed-request log, since nothing failed upstream. */
+    async fetchResponse(url, { signal, ...init }) {
+        const method = init.method ?? 'GET';
         for (let attempt = 0;; attempt++) {
-            await this.rateLimiter.acquire();
-            const controller = new AbortController();
-            const timeoutId = setTimeout(() => controller.abort(), 30_000);
+            await this.rateLimiter.acquire(signal);
+            const timeout = new AbortController();
+            const timeoutId = setTimeout(() => timeout.abort(), 30_000);
             try {
-                const response = await fetch(url, { ...init, signal: controller.signal });
+                const response = await fetch(url, {
+                    ...init,
+                    signal: signal ? AbortSignal.any([signal, timeout.signal]) : timeout.signal,
+                });
                 if (response.ok)
                     return response;
                 const text = await response.text();
@@ -439,9 +511,13 @@ export class PubChemClient {
                     service: 'PubChem',
                     data: { fault },
                 });
-                // Retry once on 5xx unless the framework marks the failure as permanent.
-                if (response.status >= 500 && error.data?.retryable !== false && attempt < 1) {
-                    await sleep(1000 * 2 ** attempt);
+                // Retry once on 5xx unless the framework marks the failure as permanent or PubChem
+                // has rejected the search query itself, which faults identically on every re-send.
+                if (response.status >= 500 &&
+                    error.data?.retryable !== false &&
+                    fault !== SEARCH_REJECTED_FAULT &&
+                    attempt < 1) {
+                    await sleep(1000 * 2 ** attempt, signal);
                     continue;
                 }
                 // A 404 is routine — most callers read it as "no data" — so it logs below warning.
@@ -452,14 +528,18 @@ export class PubChemClient {
                 throw error;
             }
             catch (error) {
+                // The caller withdrew the call: whatever this attempt rejected with, it is over.
+                if (signal?.aborted)
+                    throw cancellation(signal.reason);
                 // HTTP errors are already classified and logged — surface them, don't retry.
                 if (error instanceof McpError)
                     throw error;
                 // Retry once on network errors
                 if (attempt < 1) {
-                    await sleep(1000 * 2 ** attempt);
+                    await sleep(1000 * 2 ** attempt, signal);
                     continue;
                 }
+                // With the caller's signal ruled out, an abort can only be this attempt's timeout.
                 const failure = error instanceof Error && error.name === 'AbortError'
                     ? new Error('PubChem request timed out (30s)')
                     : error;
@@ -475,16 +555,16 @@ export class PubChemClient {
     }
     async fetchJson(url, init) {
         const response = await this.fetchResponse(url, init);
-        return (await response.json());
+        return (await readBody(response.json(), init.signal));
     }
-    async fetchBinary(url) {
-        const response = await this.fetchResponse(url);
-        return response.arrayBuffer();
+    async fetchBinary(url, signal) {
+        const response = await this.fetchResponse(url, { signal });
+        return readBody(response.arrayBuffer(), signal);
     }
     /** Fetch a text/plain body (e.g. an SDF record). Non-2xx is classified and thrown. */
-    async fetchText(url) {
-        const response = await this.fetchResponse(url);
-        return response.text();
+    async fetchText(url, signal) {
+        const response = await this.fetchResponse(url, { signal });
+        return readBody(response.text(), signal);
     }
     // ── CID Resolution ──────────────────────────────────────────────
     /** Fetch CID list, with automatic ListKey polling for async searches.
@@ -498,8 +578,8 @@ export class PubChemClient {
         try {
             const data = await this.fetchJson(url, init);
             if ('Waiting' in data)
-                return this.pollListKey(data.Waiting.ListKey, maxRecords);
-            return data.IdentifierList.CID;
+                return this.pollListKey(data.Waiting.ListKey, maxRecords, init.signal);
+            return realCids(data.IdentifierList.CID);
         }
         catch (error) {
             if (isNotFound(error))
@@ -510,17 +590,18 @@ export class PubChemClient {
     /** Poll a PubChem ListKey until results are ready.
      *
      * `listkey_count` asks PubChem to trim the page; the slice enforces the same bound
-     * locally, so the caller's saturation test holds whether or not the parameter is honored. */
-    async pollListKey(listKey, maxRecords, maxAttempts = 20) {
+     * locally, so the caller's saturation test holds whether or not the parameter is honored.
+     * A cancellation ends the wait before the next poll. */
+    async pollListKey(listKey, maxRecords, signal, maxAttempts = 20) {
         const query = maxRecords === undefined ? '' : `?listkey_count=${maxRecords}`;
         const pollUrl = `${this.pugBase}/compound/listkey/${listKey}/cids/JSON${query}`;
         for (let attempt = 0; attempt < maxAttempts; attempt++) {
-            await sleep(1500);
+            await sleep(1500, signal);
             try {
-                const data = await this.fetchJson(pollUrl);
+                const data = await this.fetchJson(pollUrl, { signal });
                 if ('Waiting' in data)
                     continue;
-                const cids = data.IdentifierList.CID;
+                const cids = realCids(data.IdentifierList.CID);
                 return maxRecords === undefined ? cids : cids.slice(0, maxRecords);
             }
             catch (error) {
@@ -531,18 +612,36 @@ export class PubChemClient {
         }
         throw new Error('PubChem async search timed out after polling');
     }
-    searchByName(name) {
-        return this.fetchCids(`${this.pugBase}/compound/name/${encodeURIComponent(name)}/cids/JSON`);
+    /** Resolve one caller-supplied identifier to its CIDs; [] when PubChem has no match.
+     *
+     * The identifier is the only variable in these requests, so an HTTP 400 is PubChem rejecting
+     * that identifier — for SMILES, a string it cannot standardize into a structure, including
+     * well-formed SMILES it cannot process such as a "*" wildcard atom. It is re-thrown as a
+     * ValidationError tagged `identifier_rejected`, so a batch caller can set that one input
+     * aside. Every other failure — 5xx, rate limit, timeout — keeps its own classification. */
+    async lookupIdentifier(url, init) {
+        try {
+            return await this.fetchCids(url, init);
+        }
+        catch (error) {
+            if (!isBadRequest(error))
+                throw error;
+            throw validationError('PubChem could not interpret the identifier.', { reason: 'identifier_rejected', fault: faultOf(error) }, { cause: error });
+        }
+    }
+    searchByName(name, signal) {
+        return this.lookupIdentifier(`${this.pugBase}/compound/name/${encodeURIComponent(name)}/cids/JSON`, { signal });
     }
-    searchBySmiles(smiles) {
-        return this.fetchCids(`${this.pugBase}/compound/smiles/cids/JSON`, {
+    searchBySmiles(smiles, signal) {
+        return this.lookupIdentifier(`${this.pugBase}/compound/smiles/cids/JSON`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
             body: new URLSearchParams({ smiles }).toString(),
+            signal,
         });
     }
-    searchByInchiKey(inchikey) {
-        return this.fetchCids(`${this.pugBase}/compound/inchikey/${encodeURIComponent(inchikey)}/cids/JSON`);
+    searchByInchiKey(inchikey, signal) {
+        return this.lookupIdentifier(`${this.pugBase}/compound/inchikey/${encodeURIComponent(inchikey)}/cids/JSON`, { signal });
     }
     /** Formula search, bounded server-side by `maxRecords`.
      *
@@ -555,15 +654,16 @@ export class PubChemClient {
      * `maxRecords` is saturated, and the true total is not recoverable — PubChem returns the
      * CID list alone, with no match count beside it. Callers that need to distinguish the two
      * compare the returned length against the cap they passed. */
-    searchByFormula(formula, allowOther, maxRecords) {
+    searchByFormula(formula, allowOther, maxRecords, signal) {
         const params = new URLSearchParams({ MaxRecords: String(maxRecords) });
         if (allowOther)
             params.set('AllowOtherElements', 'true');
-        return this.fetchCids(`${this.pugBase}/compound/fastformula/${encodeURIComponent(formula)}/cids/JSON?${params}`, undefined, maxRecords);
+        return mapRejectedSearch(this.fetchCids(`${this.pugBase}/compound/fastformula/${encodeURIComponent(formula)}/cids/JSON?${params}`, { signal }, maxRecords), 'PubChem could not run the formula search on this formula.', 'Write the formula in Hill notation with valid element symbols, for example "C6H12O6" or "CaH2O2".');
     }
     /** Substructure, superstructure, and 2D-similarity search, bounded server-side by
-     * `maxRecords`. Same cap contract as {@link searchByFormula}. */
-    searchByStructure(mode, query, queryType, threshold, maxRecords) {
+     * `maxRecords`. Same cap contract as {@link searchByFormula}; a query PubChem cannot search
+     * on throws `search_query_rejected` the same way. */
+    searchByStructure(mode, query, queryType, threshold, maxRecords, signal) {
         const endpoint = mode === 'similarity'
             ? 'fastsimilarity_2d'
             : mode === 'substructure'
@@ -573,18 +673,19 @@ export class PubChemClient {
         if (mode === 'similarity')
             params.set('Threshold', String(threshold ?? 90));
         if (queryType === 'cid') {
-            return this.fetchCids(`${this.pugBase}/compound/${endpoint}/cid/${query}/cids/JSON?${params}`, undefined, maxRecords);
+            return mapRejectedSearch(this.fetchCids(`${this.pugBase}/compound/${endpoint}/cid/${query}/cids/JSON?${params}`, { signal }, maxRecords), `PubChem could not run the ${mode} search on CID ${query}.`, `Confirm CID ${query} exists with pubchem_get_compound_details, or pass the structure as a SMILES query with queryType "smiles".`);
         }
         // POST for SMILES to avoid encoding issues
         const url = `${this.pugBase}/compound/${endpoint}/smiles/cids/JSON?${params}`;
-        return this.fetchCids(url, {
+        return mapRejectedSearch(this.fetchCids(url, {
             method: 'POST',
             headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
             body: new URLSearchParams({ smiles: query }).toString(),
-        }, maxRecords);
+            signal,
+        }, maxRecords), `PubChem could not run the ${mode} search on this SMILES.`, 'Check the SMILES syntax (balanced ring closures and parentheses, valid element symbols) and remove any "*" wildcard atoms, which PubChem structure search does not accept.');
     }
     // ── Compound Data ───────────────────────────────────────────────
-    async getProperties(cids, properties) {
+    async getProperties(cids, properties, signal) {
         if (cids.length === 0 || properties.length === 0)
             return [];
         const propsPath = properties.join(',');
@@ -595,15 +696,16 @@ export class PubChemClient {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
                 body: new URLSearchParams({ cid: cidStr }).toString(),
+                signal,
             })
-            : await this.fetchJson(`${this.pugBase}/compound/cid/${cidStr}/property/${propsPath}/JSON`);
+            : await this.fetchJson(`${this.pugBase}/compound/cid/${cidStr}/property/${propsPath}/JSON`, { signal });
         // PubChem returns different field names than the request names for some properties.
         // Normalize so consumers see the names they requested.
         return data.PropertyTable.Properties.map(normalizePropertyNames);
     }
-    async getSynonyms(cid) {
+    async getSynonyms(cid, signal) {
         try {
-            const data = await this.fetchJson(`${this.pugBase}/compound/cid/${cid}/synonyms/JSON`);
+            const data = await this.fetchJson(`${this.pugBase}/compound/cid/${cid}/synonyms/JSON`, { signal });
             return data.InformationList.Information[0]?.Synonym ?? [];
         }
         catch (error) {
@@ -612,10 +714,10 @@ export class PubChemClient {
             throw error;
         }
     }
-    async getImage(cid, size = 'large') {
+    async getImage(cid, size = 'large', signal) {
         const sizeParam = size === 'small' ? '?image_size=small' : '?image_size=large';
         try {
-            return await this.fetchBinary(`${this.pugBase}/compound/cid/${cid}/PNG${sizeParam}`);
+            return await this.fetchBinary(`${this.pugBase}/compound/cid/${cid}/PNG${sizeParam}`, signal);
         }
         catch (error) {
             // The image endpoint returns binary, so absence can't be a structured success like
@@ -630,9 +732,9 @@ export class PubChemClient {
             throw error;
         }
     }
-    async getXrefs(cid, xrefType) {
+    async getXrefs(cid, xrefType, signal) {
         try {
-            const data = await this.fetchJson(`${this.pugBase}/compound/cid/${cid}/xrefs/${xrefType}/JSON`);
+            const data = await this.fetchJson(`${this.pugBase}/compound/cid/${cid}/xrefs/${xrefType}/JSON`, { signal });
             const info = data.InformationList.Information[0];
             if (!info)
                 return [];
@@ -646,9 +748,9 @@ export class PubChemClient {
         }
     }
     // ── PUG View ────────────────────────────────────────────────────
-    async getDescription(cid) {
+    async getDescription(cid, signal) {
         try {
-            const data = await this.fetchJson(`${this.viewBase}/data/compound/${cid}/JSON?heading=Record+Description`);
+            const data = await this.fetchJson(`${this.viewBase}/data/compound/${cid}/JSON?heading=Record+Description`, { signal });
             const sections = data.Record.Section;
             if (!sections)
                 return [];
@@ -679,9 +781,9 @@ export class PubChemClient {
      * GHS classification" — a nonexistent CID and a real compound without safety data are
      * different answers that call for different follow-up, and both used to surface as an
      * absent result. */
-    async getSafetyData(cid) {
+    async getSafetyData(cid, signal) {
         try {
-            const data = await this.fetchJson(`${this.viewBase}/data/compound/${cid}/JSON?heading=Safety+and+Hazards`);
+            const data = await this.fetchJson(`${this.viewBase}/data/compound/${cid}/JSON?heading=Safety+and+Hazards`, { signal });
             const sections = data.Record.Section;
             if (!sections)
                 return { status: 'no_ghs_data' };
@@ -741,9 +843,9 @@ export class PubChemClient {
             throw error;
         }
     }
-    async getClassification(cid) {
+    async getClassification(cid, signal) {
         try {
-            const data = await this.fetchJson(`${this.viewBase}/data/compound/${cid}/JSON?heading=Pharmacology+and+Biochemistry`);
+            const data = await this.fetchJson(`${this.viewBase}/data/compound/${cid}/JSON?heading=Pharmacology+and+Biochemistry`, { signal });
             const sections = data.Record.Section;
             if (!sections)
                 return null;
@@ -812,9 +914,9 @@ export class PubChemClient {
         }
     }
     // ── Bioactivity ─────────────────────────────────────────────────
-    async getAssaySummary(cid) {
+    async getAssaySummary(cid, signal) {
         try {
-            const data = await this.fetchJson(`${this.pugBase}/compound/cid/${cid}/assaysummary/JSON`);
+            const data = await this.fetchJson(`${this.pugBase}/compound/cid/${cid}/assaysummary/JSON`, { signal });
             return this.parseAssayTable(data);
         }
         catch (error) {
@@ -891,11 +993,11 @@ export class PubChemClient {
         return [...byAid.values()];
     }
     // ── Assay Search ────────────────────────────────────────────────
-    async searchAssaysByTarget(targetType, query) {
+    async searchAssaysByTarget(targetType, query, signal) {
         // PubChem API expects "accession" not "proteinaccession"
         const apiTargetType = targetType === 'proteinaccession' ? 'accession' : targetType;
         try {
-            const data = await this.fetchJson(`${this.pugBase}/assay/target/${apiTargetType}/${encodeURIComponent(query)}/aids/JSON`);
+            const data = await this.fetchJson(`${this.pugBase}/assay/target/${apiTargetType}/${encodeURIComponent(query)}/aids/JSON`, { signal });
             return data.IdentifierList.AID;
         }
         catch (error) {
@@ -905,7 +1007,7 @@ export class PubChemClient {
         }
     }
     // ── Entity Summaries ────────────────────────────────────────────
-    async getEntitySummary(entityType, identifier) {
+    async getEntitySummary(entityType, identifier, signal) {
         const pathMap = {
             assay: `/assay/aid/${identifier}/summary/JSON`,
             gene: `/gene/geneid/${identifier}/summary/JSON`,
@@ -916,7 +1018,9 @@ export class PubChemClient {
         if (!path)
             throw new Error(`Unknown entity type: ${entityType}`);
         try {
-            const data = await this.fetchJson(`${this.pugBase}${path}`);
+            const data = await this.fetchJson(`${this.pugBase}${path}`, {
+                signal,
+            });
             // Response shape: { XxxSummaries: { XxxSummary: [{...}] } }
             const summariesKey = Object.keys(data).find((k) => k.endsWith('Summaries'));
             if (!summariesKey)
@@ -932,9 +1036,8 @@ export class PubChemClient {
             if (isNotFound(error))
                 return null;
             // PubChem returns HTTP 400 (not 404) for nonexistent entity IDs in some endpoints
-            if (error instanceof McpError && error.data?.status === 400) {
+            if (isBadRequest(error))
                 return null;
-            }
             throw error;
         }
     }
@@ -943,13 +1046,17 @@ export class PubChemClient {
      * Drug-drug and target data live in PubChem SDQ external tables (drugbankddi, bioactivity);
      * drug-food is inline PUG View text. Each kind reads a window of `maxEntries` entries
      * starting at `offset` records into that kind's own stream; absent data for a kind
-     * contributes an empty page rather than erroring. */
-    async getInteractions(cid, kinds, maxEntries, offset) {
+     * contributes an empty page rather than erroring. A cancellation fails the whole call. */
+    async getInteractions(cid, kinds, maxEntries, offset, signal) {
         // Per-kind isolation: a failure in one source (upstream parse error, timeout, network)
         // must not discard the kinds that succeeded. Failures are reported, not thrown (#21).
         // Page state is recorded per kind from that kind's own result, so a failing kind leaves
         // the others' continuation signals untouched rather than zeroing them.
-        const settled = await Promise.allSettled(kinds.map((kind) => this.getInteractionsForKind(cid, kind, maxEntries, offset)));
+        const settled = await Promise.allSettled(kinds.map((kind) => this.getInteractionsForKind(cid, kind, maxEntries, offset, signal)));
+        // A cancelled kind is not a failed source — reporting it as one would hand a withdrawn
+        // call a partial result.
+        if (signal?.aborted)
+            throw cancellation(signal.reason);
         const entries = [];
         const pages = [];
         const failedKinds = [];
@@ -970,18 +1077,18 @@ export class PubChemClient {
         });
         return { entries, pages, failedKinds };
     }
-    getInteractionsForKind(cid, kind, maxEntries, offset) {
+    getInteractionsForKind(cid, kind, maxEntries, offset, signal) {
         switch (kind) {
             case 'drug-drug':
-                return this.getDrugDrugInteractions(cid, maxEntries, offset);
+                return this.getDrugDrugInteractions(cid, maxEntries, offset, signal);
             case 'drug-food':
-                return this.getDrugFoodInteractions(cid, maxEntries, offset);
+                return this.getDrugFoodInteractions(cid, maxEntries, offset, signal);
             case 'target':
-                return this.getTargetInteractions(cid, maxEntries, offset);
+                return this.getTargetInteractions(cid, maxEntries, offset, signal);
         }
     }
-    async getDrugDrugInteractions(cid, maxEntries, offset) {
-        const { rows, totalCount } = await this.fetchSdq('drugbankddi', cid, ['cid', 'name2', 'descr'], maxEntries, offset);
+    async getDrugDrugInteractions(cid, maxEntries, offset, signal) {
+        const { rows, totalCount } = await this.fetchSdq('drugbankddi', cid, ['cid', 'name2', 'descr'], maxEntries, offset, signal);
         const entries = [];
         for (const row of rows) {
             const text = typeof row.descr === 'string' ? row.descr : '';
@@ -994,7 +1101,7 @@ export class PubChemClient {
         }
         return {
             entries,
-            totalRecords: await this.resolveSdqTotal('drugbankddi', cid, rows.length, totalCount, offset),
+            totalRecords: await this.resolveSdqTotal('drugbankddi', cid, rows.length, totalCount, offset, signal),
             recordsConsumed: rows.length,
         };
     }
@@ -1008,11 +1115,11 @@ export class PubChemClient {
      * Because most rows are dropped, the page position is an index into the activity records, not
      * into the entries returned — the walk records exactly how many rows it read so the next page
      * resumes at the first unread one. */
-    async getTargetInteractions(cid, maxEntries, offset) {
+    async getTargetInteractions(cid, maxEntries, offset, signal) {
         // `targetname` is sparse (most rows are untargeted assay outcomes), so oversample and keep
         // the target-bearing rows, most-potent-first.
         const window = Math.min(Math.max(maxEntries * 4, 20), 100);
-        const { rows, totalCount } = await this.fetchSdq('bioactivity', cid, ['cid', 'targetname', 'acname', 'acqualifier', 'acvalue', 'aidsrcname'], window, offset, ['acvalue,asc']);
+        const { rows, totalCount } = await this.fetchSdq('bioactivity', cid, ['cid', 'targetname', 'acname', 'acqualifier', 'acvalue', 'aidsrcname'], window, offset, signal, ['acvalue,asc']);
         const entries = [];
         // Collapse duplicate measurements of the same target/value reported across assays.
         const seen = new Set();
@@ -1047,14 +1154,14 @@ export class PubChemClient {
         }
         return {
             entries,
-            totalRecords: await this.resolveSdqTotal('bioactivity', cid, rows.length, totalCount, offset),
+            totalRecords: await this.resolveSdqTotal('bioactivity', cid, rows.length, totalCount, offset, signal),
             recordsConsumed,
         };
     }
-    async getDrugFoodInteractions(cid, maxEntries, offset) {
+    async getDrugFoodInteractions(cid, maxEntries, offset, signal) {
         const empty = { entries: [], totalRecords: 0, recordsConsumed: 0 };
         try {
-            const data = await this.fetchJson(`${this.viewBase}/data/compound/${cid}/JSON?heading=Drug-Food+Interactions`);
+            const data = await this.fetchJson(`${this.viewBase}/data/compound/${cid}/JSON?heading=Drug-Food+Interactions`, { signal });
             const sections = data.Record.Section;
             if (!sections)
                 return empty;
@@ -1098,7 +1205,7 @@ export class PubChemClient {
      * throws, and the `status.error` check covers the same rejection arriving inside a 2xx body.
      * An unparseable body throws with the collection and a body snippet attached, so per-kind
      * isolation can name what failed. */
-    async fetchSdq(collection, cid, columns, limit, offset = 0, order) {
+    async fetchSdq(collection, cid, columns, limit, offset, signal, order) {
         const empty = { rows: [], totalCount: 0 };
         const query = JSON.stringify({
             select: columns,
@@ -1111,7 +1218,7 @@ export class PubChemClient {
         const url = `${this.sdqBase}?infmt=json&outfmt=json&query=${encodeURIComponent(query)}`;
         let body;
         try {
-            body = await this.fetchText(url);
+            body = await this.fetchText(url, signal);
         }
         catch (error) {
             if (isNotFound(error))
@@ -1148,18 +1255,18 @@ export class PubChemClient {
      * answers `totalCount` 0 — so an offset that overshoots would otherwise report "no records"
      * for a compound that has thousands. A one-row probe from the top recovers the real bound,
      * and only runs on that case. */
-    async resolveSdqTotal(collection, cid, rowsReturned, reportedTotal, offset) {
+    async resolveSdqTotal(collection, cid, rowsReturned, reportedTotal, offset, signal) {
         if (rowsReturned > 0 || offset === 0)
             return reportedTotal;
-        const { totalCount } = await this.fetchSdq(collection, cid, ['cid'], 1);
+        const { totalCount } = await this.fetchSdq(collection, cid, ['cid'], 1, 0, signal);
         return totalCount;
     }
     // ── 3D Structure ────────────────────────────────────────────────
     /** Fetch the default 3D conformer as raw V2000 SDF text. Throws a typed not-found when
      * PubChem has no computed 3D coordinates (large molecules, mixtures, undefined salts). */
-    async getSdf3d(cid) {
+    async getSdf3d(cid, signal) {
         try {
-            return await this.fetchText(`${this.pugBase}/compound/cid/${cid}/record/SDF?record_type=3d`);
+            return await this.fetchText(`${this.pugBase}/compound/cid/${cid}/record/SDF?record_type=3d`, signal);
         }
         catch (error) {
             if (isNotFound(error)) {
@@ -1175,9 +1282,9 @@ export class PubChemClient {
         }
     }
     /** List the conformer IDs PubChem has computed for a compound. Returns [] on not-found. */
-    async getConformerIds(cid) {
+    async getConformerIds(cid, signal) {
         try {
-            const data = await this.fetchJson(`${this.pugBase}/compound/cid/${cid}/conformers/JSON`);
+            const data = await this.fetchJson(`${this.pugBase}/compound/cid/${cid}/conformers/JSON`, { signal });
             return data.InformationList.Information[0]?.ConformerID ?? [];
         }
         catch (error) {