@everdeep/pubmed 0.1.1 → 0.1.3

package/README.md

@@ -77,12 +77,14 @@ Cursors are versioned, base64url-encoded, unsigned, implementation-specific cont
 
 ### Count changes during pagination
 
-NCBI can return HTTP 200 with valid IDs but a different total on a later page. By default, the client stops with `PaginationConsistencyError` (`code: "PAGINATION_INCONSISTENT"`, `retryable: false`), not `INVALID_RESPONSE` or `SEARCH_LIMIT`. This is a consistency signal, **not provider unavailability**. Retrying may succeed, but does not establish consistent results; the client does not automatically retry or restart such searches.
+NCBI can return HTTP 200 with valid IDs but a different total on a later page. By default, `search()` and `searchAll()` **continue retrieving valid pages**, returning count-drift diagnostics and emitting a `search-total-drift` event. The default `totalDriftPolicy` is `"warn"` (version 0.1.1 defaulted to `"error"`); no explicit opt-in or event handler is required. This is best-effort pagination, not a snapshot guarantee.
 
-If best-effort pagination is acceptable, opt in explicitly at client construction:
+To stop on count changes, explicitly configure `totalDriftPolicy: "error"`. Strict mode throws `PaginationConsistencyError` (`code: "PAGINATION_INCONSISTENT"`, `retryable: false`) before fetching the changed page's records. This is a consistency signal, **not provider unavailability**. The client does not automatically retry or restart such searches.
+
+With the default policy:
 
 ```ts
-const client = new PubMedClient({ email, tool, totalDriftPolicy: "warn" });
+const client = new PubMedClient({ email, tool }); // totalDriftPolicy: "warn" by default
 const first = await client.search({ query: "cancer", pageSize: 2 });
 if (first.nextCursor) {
   const second = await client.search({ cursor: first.nextCursor });
@@ -94,7 +96,7 @@ In both modes, `SearchBatch.total` and the pagination bound remain the **initial
 
 Warn mode returns a `diagnostics` entry on each drifted page and emits a `search-total-drift` event. A consistency error exposes the same metadata through `.diagnostic` and `toJSON()`: `reason`, `originalTotal`, `observedTotal`, `offset`, `requestedIds`, and `returnedIds`. No queries, PMIDs, cursors, or history tokens are included. Record parse `warnings` remain separate.
 
-Neither mode guarantees snapshot enumeration: equal counts do not prove stable membership or ordering, and page-local uniqueness does not detect cross-page duplicates or omissions. Warn mode explicitly accepts that risk; it does not silently deduplicate or claim complete results. Consumers requiring exact enumeration should not opt in.
+Neither mode guarantees snapshot enumeration: equal counts do not prove stable membership or ordering, and page-local uniqueness does not detect cross-page duplicates or omissions. Warn mode accepts that risk; it does not silently deduplicate or claim complete results. Consumers should persist by PMID idempotently and inspect `missingPmids` and `diagnostics`. Consumers requiring a stop on count drift should select `"error"`, but that alone does not establish exact enumeration.
 
 For progressive consumption, use `searchAll()`. `maxResults` is required so a caller must make the retrieval bound explicit:
 
@@ -130,7 +132,17 @@ if (record?.kind === "article") {
 }
 ```
 
-Every record includes `rawXml`, which is the exact direct-child XML fragment received from PubMed, without serialization or normalization. `source` retains parsed source data for fields not represented in the normalized surface.
+`rawXml` is omitted by default, including on unknown records. Enable it for a client or individual full-record request to retain the exact direct-child XML fragment received from PubMed, without serialization or normalization:
+
+```ts
+const client = new PubMedClient({ email, tool, includeRawXml: true });
+const record = await client.get("123"); // includes rawXml
+const compact = await client.get("123", { includeRawXml: false }); // omits rawXml
+```
+
+The per-request option also applies to `getMany`, `search` (including cursor requests), and every page of `searchAll`. Each cursor request uses its own option or the client's default, not the previous page's option. The standalone parser similarly supports `parsePubMedXml(xml, { includeRawXml: true })` and omits XML by default.
+
+**Compatibility change:** `rawXml` is now optional (`string | undefined`); consumers that previously relied on its presence must explicitly opt in. This controls returned fields only: XML is still fetched and parsed, and any configured response cache still stores XML bodies. `source` continues to retain parsed source data for fields not represented in the normalized surface. Summary methods are unchanged and do not support this option.
 
 ## Citation export
 

package/dist/index.cjs

@@ -715,8 +715,19 @@ function parseFragment(fragment) {
 }
 
 // src/parser.ts
-function parsePubMedXml(xml) {
-  const records = extractFragments(xml).map(parseFragment);
+function parsePubMedXml(xml, options = {}) {
+  if (typeof options !== "object" || options === null || Array.isArray(options)) {
+    throw new ValidationError("parser options must be an object");
+  }
+  if (options.includeRawXml !== void 0 && typeof options.includeRawXml !== "boolean") {
+    throw new ValidationError("includeRawXml must be a boolean");
+  }
+  const records = extractFragments(xml).map((fragment) => {
+    const record = parseFragment(fragment);
+    if (options.includeRawXml === true) return record;
+    const { rawXml, ...withoutRawXml } = record;
+    return withoutRawXml;
+  });
   const warnings = records.flatMap((record) => record.kind === "unknown" ? [{ code: "UNKNOWN_RECORD", message: `Unknown PubMed record type: ${record.recordType}`, recordType: record.recordType }] : []);
   return { records, warnings };
 }
@@ -1567,7 +1578,9 @@ var Transport = class {
     const correlationId = (0, import_node_crypto.randomUUID)();
     safeEvent(this.#onEvent, { type: "correlation-id", endpoint, correlationId });
     try {
-      return await this.#coordinate(endpoint, parameters, decode, options, correlationId);
+      const value = await this.#coordinate(endpoint, parameters, decode, options, correlationId);
+      if (options.signal?.aborted) throw new AbortedError();
+      return value;
     } catch (error) {
       safeEvent(this.#onEvent, {
         type: "terminal-failure",
@@ -1591,6 +1604,7 @@ ${semantic.toString()}`);
       const cached = await this.#cache.read(key, signal);
       if (cached.status === "hit") {
         safeEvent(this.#onEvent, { type: "cache-hit", endpoint, correlationId });
+        if (signal?.aborted) throw new AbortedError();
         if (encoder.encode(cached.value).byteLength > this.#maxResponseBytes) {
           await this.#cache.invalidate(key);
         } else {
@@ -1671,6 +1685,9 @@ function isAbortSignal(value) {
 function validateRequestOptions(options, name) {
   const candidate = object3(options);
   if (candidate === void 0) throw new ValidationError(`${name} must be an object`);
+  if (candidate.includeRawXml !== void 0 && typeof candidate.includeRawXml !== "boolean") {
+    throw new ValidationError("includeRawXml must be a boolean");
+  }
   if (candidate.includeLinkOuts !== void 0 && typeof candidate.includeLinkOuts !== "boolean") {
     throw new ValidationError("includeLinkOuts must be a boolean");
   }
@@ -1681,6 +1698,9 @@ function validateRequestOptions(options, name) {
 function validateSummaryRequestOptions(options) {
   const candidate = object3(options);
   if (candidate === void 0) throw new ValidationError("summary request options must be an object");
+  if (candidate.includeRawXml !== void 0) {
+    throw new ValidationError("includeRawXml is not supported for summary requests");
+  }
   if (candidate.includeLinkOuts !== void 0) {
     throw new ValidationError("includeLinkOuts is not supported for summary requests");
   }
@@ -1813,7 +1833,7 @@ function validateSearchState(state, expectedIds, offset = 0) {
   }
 }
 function parseExpectedFetch(body, expectedPmids) {
-  const parsed = parsePubMedXml(body);
+  const parsed = parsePubMedXml(body, { includeRawXml: true });
   const expected = new Set(expectedPmids);
   const seen = /* @__PURE__ */ new Set();
   for (const record of parsed.records) {
@@ -1894,15 +1914,20 @@ function withLinks(record, extra) {
 var PubMedClient = class {
   #transport;
   #maxBatchSize;
+  #includeRawXml;
   #totalDriftPolicy;
   #onEvent;
   constructor(options) {
     if (typeof options !== "object" || options === null) throw new ValidationError("PubMedClient options are required");
     validateAdapterShapes(options);
+    if (options.includeRawXml !== void 0 && typeof options.includeRawXml !== "boolean") {
+      throw new ValidationError("includeRawXml must be a boolean");
+    }
+    this.#includeRawXml = options.includeRawXml ?? false;
     if (options.totalDriftPolicy !== void 0 && options.totalDriftPolicy !== "error" && options.totalDriftPolicy !== "warn") {
       throw new ValidationError('totalDriftPolicy must be "error" or "warn"');
     }
-    this.#totalDriftPolicy = options.totalDriftPolicy ?? "error";
+    this.#totalDriftPolicy = options.totalDriftPolicy ?? "warn";
     if (typeof options.email !== "string" || options.email.trim() === "") throw new ValidationError("email is required");
     if (typeof options.tool !== "string" || options.tool.trim() === "") throw new ValidationError("tool is required");
     if (options.apiKey !== void 0 && (typeof options.apiKey !== "string" || options.apiKey.trim() === "")) {
@@ -1965,7 +1990,11 @@ var PubMedClient = class {
     }
     let ordered = input.flatMap((pmid) => byPmid.get(pmid) ?? []);
     if (unknown.length > 0) ordered = [...ordered, ...unknown];
+    if (!(options.includeRawXml ?? this.#includeRawXml)) {
+      ordered = ordered.map(({ rawXml, ...record }) => record);
+    }
     if (options.includeLinkOuts === true && ordered.length > 0) ordered = await this.#enrich(ordered, options.signal);
+    if (options.signal?.aborted) throw new AbortedError();
     return {
       records: ordered,
       missingPmids: input.filter((pmid) => !byPmid.has(pmid)),
@@ -1994,6 +2023,7 @@ var PubMedClient = class {
       );
       received.push(...summaries);
     }
+    if (options.signal?.aborted) throw new AbortedError();
     const byPmid = new Map(received.map((summary) => [summary.pmid, summary]));
     return {
       summaries: input.flatMap((pmid) => byPmid.get(pmid) ?? []),
@@ -2004,7 +2034,7 @@ var PubMedClient = class {
     validateRequestOptions(options, "search options");
     if ("cursor" in options) {
       if (typeof options.cursor !== "string" || options.cursor === "") throw new ValidationError("cursor must be a non-empty string");
-      return (await this.#searchCursorPage(options.cursor, options.includeLinkOuts === true, options.signal)).batch;
+      return (await this.#searchCursorPage(options.cursor, options)).batch;
     }
     validateQueryOptions(options);
     return (await this.#searchQueryPage(options)).batch;
@@ -2020,6 +2050,7 @@ var PubMedClient = class {
       query: options.query,
       pageSize,
       ...options.sort === void 0 ? {} : { sort: options.sort },
+      ...options.includeRawXml === void 0 ? {} : { includeRawXml: options.includeRawXml },
       ...options.includeLinkOuts === void 0 ? {} : { includeLinkOuts: options.includeLinkOuts },
       ...options.signal === void 0 ? {} : { signal: options.signal }
     };
@@ -2036,8 +2067,7 @@ var PubMedClient = class {
       if (page.batch.nextCursor === null) throw new InvalidResponseError("PubMed search ended before the requested result count");
       page = await this.#searchCursorPage(
         page.batch.nextCursor,
-        options.includeLinkOuts === true,
-        options.signal,
+        options,
         target - processed
       );
     }
@@ -2077,10 +2107,7 @@ var PubMedClient = class {
         expectedPmids: []
       };
     }
-    const batch = await this.getMany(state.ids, {
-      ...options.includeLinkOuts === void 0 ? {} : { includeLinkOuts: options.includeLinkOuts },
-      ...options.signal === void 0 ? {} : { signal: options.signal }
-    });
+    const batch = await this.getMany(state.ids, options);
     const offset = state.ids.length;
     return {
       batch: {
@@ -2091,7 +2118,8 @@ var PubMedClient = class {
       expectedPmids: state.ids
     };
   }
-  async #searchCursorPage(cursorValue, includeLinkOuts, signal, maxExpected) {
+  async #searchCursorPage(cursorValue, options, maxExpected) {
+    const { signal } = options;
     const cursor = decodeCursor(cursorValue);
     if (cursor.offset >= SEARCH_WINDOW) throw new SearchLimitError();
     const remainingWindow = SEARCH_WINDOW - cursor.offset;
@@ -2130,7 +2158,7 @@ var PubMedClient = class {
       { cache: false, ...signal === void 0 ? {} : { signal } }
     );
     if (diagnostic !== void 0) safeEvent(this.#onEvent, { type: "search-total-drift", ...diagnostic });
-    const batch = await this.getMany(state.ids, { includeLinkOuts, ...signal === void 0 ? {} : { signal } });
+    const batch = await this.getMany(state.ids, options);
     const offset = cursor.offset + state.ids.length;
     return {
       batch: {

package/dist/index.d.cts

@@ -169,7 +169,8 @@ interface PubMedWarning {
 interface BasePubMedRecord {
     readonly kind: "article" | "book" | "unknown";
     readonly recordType: string;
-    readonly rawXml: string;
+    /** Exact source fragment, present only when includeRawXml is enabled. */
+    readonly rawXml?: string;
     readonly source: JsonObject;
     readonly identifiers: readonly PubMedIdentifier[];
     readonly links: readonly PubMedLink[];
@@ -305,6 +306,8 @@ interface SearchBatch extends BatchResult {
     readonly diagnostics?: readonly SearchTotalDriftDiagnostic[];
 }
 interface RequestOptions {
+    /** Override the client's raw XML inclusion default for this request. */
+    readonly includeRawXml?: boolean;
     readonly includeLinkOuts?: boolean;
     readonly signal?: AbortSignal;
 }
@@ -396,6 +399,8 @@ type PubMedEvent = Readonly<{
     recordType?: string;
 }>;
 interface PubMedClientOptions {
+    /** Include exact source XML fragments in full records. Default false. */
+    readonly includeRawXml?: boolean;
     readonly email: string;
     readonly tool: string;
     readonly apiKey?: string;
@@ -408,7 +413,7 @@ interface PubMedClientOptions {
     readonly maxResponseBytes?: number;
     readonly maxQueuedRequests?: number;
     readonly maxBatchSize?: number;
-    /** Default "error". "warn" explicitly permits best-effort, non-snapshot pagination. */
+    /** Default "warn": continue valid pages with drift diagnostics. "error" opts into stopping on count changes. Neither guarantees a snapshot. */
     readonly totalDriftPolicy?: "error" | "warn";
 }
 
@@ -449,7 +454,11 @@ interface ParsedPubMedXml {
     readonly records: readonly PubMedRecord[];
     readonly warnings: readonly PubMedWarning[];
 }
-/** Parse an entire PubmedArticleSet while retaining each direct child byte-for-byte. */
-declare function parsePubMedXml(xml: string): ParsedPubMedXml;
+interface ParsePubMedXmlOptions {
+    /** Include each direct child's exact source XML fragment. Default false. */
+    readonly includeRawXml?: boolean;
+}
+/** Parse an entire PubmedArticleSet, optionally retaining exact source fragments. */
+declare function parsePubMedXml(xml: string, options?: ParsePubMedXmlOptions): ParsedPubMedXml;
 
-export { AbortedError, type AbstractSection, type Affiliation, type AuthorIdentifier, type BasePubMedRecord, type BatchResult, type CacheAdapter, type CitationFormat, type CitationSource, type CollectiveAuthor, CursorExpiredError, CursorInvalidError, HttpError, InvalidResponseError, type JournalCitation, type JsonObject, type JsonPrimitive, type JsonValue, type Keyword, MemoryCache, type MemoryCacheOptions, type MeshHeading, NetworkError, PaginationConsistencyError, ParseError, type ParsedPubMedXml, type PartialDate, type PersonalAuthor, type PubMedArticleRecord, type PubMedAuthor, type PubMedBookRecord, PubMedClient, type PubMedClientOptions, type PubMedEndpoint, PubMedError, type PubMedErrorCode, type PubMedEvent, type PubMedIdentifier, type PubMedLink, type PubMedRecord, type PubMedSummary, type PubMedSummaryAuthor, type PubMedSummaryBook, type PubMedSummaryHistoryEntry, type PubMedSummaryIdentifier, type PubMedSummaryJournal, type PubMedWarning, type PublicationDates, type PublicationHistoryEntry, QueueFullError, type RateLimitBucket, type RateLimitCoordinator, RateLimitError, type RequestOptions, ResponseTooLargeError, type SearchAllOptions, type SearchBatch, type SearchCursorOptions, SearchLimitError, type SearchOptions, type SearchQueryOptions, type SearchTotalDriftDiagnostic, type SummaryBatchResult, type SummaryRequestOptions, TimeoutError, type UnknownPubMedRecord, ValidationError, formatCitation, formatCitations, parsePubMedXml };
+export { AbortedError, type AbstractSection, type Affiliation, type AuthorIdentifier, type BasePubMedRecord, type BatchResult, type CacheAdapter, type CitationFormat, type CitationSource, type CollectiveAuthor, CursorExpiredError, CursorInvalidError, HttpError, InvalidResponseError, type JournalCitation, type JsonObject, type JsonPrimitive, type JsonValue, type Keyword, MemoryCache, type MemoryCacheOptions, type MeshHeading, NetworkError, PaginationConsistencyError, ParseError, type ParsePubMedXmlOptions, type ParsedPubMedXml, type PartialDate, type PersonalAuthor, type PubMedArticleRecord, type PubMedAuthor, type PubMedBookRecord, PubMedClient, type PubMedClientOptions, type PubMedEndpoint, PubMedError, type PubMedErrorCode, type PubMedEvent, type PubMedIdentifier, type PubMedLink, type PubMedRecord, type PubMedSummary, type PubMedSummaryAuthor, type PubMedSummaryBook, type PubMedSummaryHistoryEntry, type PubMedSummaryIdentifier, type PubMedSummaryJournal, type PubMedWarning, type PublicationDates, type PublicationHistoryEntry, QueueFullError, type RateLimitBucket, type RateLimitCoordinator, RateLimitError, type RequestOptions, ResponseTooLargeError, type SearchAllOptions, type SearchBatch, type SearchCursorOptions, SearchLimitError, type SearchOptions, type SearchQueryOptions, type SearchTotalDriftDiagnostic, type SummaryBatchResult, type SummaryRequestOptions, TimeoutError, type UnknownPubMedRecord, ValidationError, formatCitation, formatCitations, parsePubMedXml };

package/dist/index.d.ts

@@ -169,7 +169,8 @@ interface PubMedWarning {
 interface BasePubMedRecord {
     readonly kind: "article" | "book" | "unknown";
     readonly recordType: string;
-    readonly rawXml: string;
+    /** Exact source fragment, present only when includeRawXml is enabled. */
+    readonly rawXml?: string;
     readonly source: JsonObject;
     readonly identifiers: readonly PubMedIdentifier[];
     readonly links: readonly PubMedLink[];
@@ -305,6 +306,8 @@ interface SearchBatch extends BatchResult {
     readonly diagnostics?: readonly SearchTotalDriftDiagnostic[];
 }
 interface RequestOptions {
+    /** Override the client's raw XML inclusion default for this request. */
+    readonly includeRawXml?: boolean;
     readonly includeLinkOuts?: boolean;
     readonly signal?: AbortSignal;
 }
@@ -396,6 +399,8 @@ type PubMedEvent = Readonly<{
     recordType?: string;
 }>;
 interface PubMedClientOptions {
+    /** Include exact source XML fragments in full records. Default false. */
+    readonly includeRawXml?: boolean;
     readonly email: string;
     readonly tool: string;
     readonly apiKey?: string;
@@ -408,7 +413,7 @@ interface PubMedClientOptions {
     readonly maxResponseBytes?: number;
     readonly maxQueuedRequests?: number;
     readonly maxBatchSize?: number;
-    /** Default "error". "warn" explicitly permits best-effort, non-snapshot pagination. */
+    /** Default "warn": continue valid pages with drift diagnostics. "error" opts into stopping on count changes. Neither guarantees a snapshot. */
     readonly totalDriftPolicy?: "error" | "warn";
 }
 
@@ -449,7 +454,11 @@ interface ParsedPubMedXml {
     readonly records: readonly PubMedRecord[];
     readonly warnings: readonly PubMedWarning[];
 }
-/** Parse an entire PubmedArticleSet while retaining each direct child byte-for-byte. */
-declare function parsePubMedXml(xml: string): ParsedPubMedXml;
+interface ParsePubMedXmlOptions {
+    /** Include each direct child's exact source XML fragment. Default false. */
+    readonly includeRawXml?: boolean;
+}
+/** Parse an entire PubmedArticleSet, optionally retaining exact source fragments. */
+declare function parsePubMedXml(xml: string, options?: ParsePubMedXmlOptions): ParsedPubMedXml;
 
-export { AbortedError, type AbstractSection, type Affiliation, type AuthorIdentifier, type BasePubMedRecord, type BatchResult, type CacheAdapter, type CitationFormat, type CitationSource, type CollectiveAuthor, CursorExpiredError, CursorInvalidError, HttpError, InvalidResponseError, type JournalCitation, type JsonObject, type JsonPrimitive, type JsonValue, type Keyword, MemoryCache, type MemoryCacheOptions, type MeshHeading, NetworkError, PaginationConsistencyError, ParseError, type ParsedPubMedXml, type PartialDate, type PersonalAuthor, type PubMedArticleRecord, type PubMedAuthor, type PubMedBookRecord, PubMedClient, type PubMedClientOptions, type PubMedEndpoint, PubMedError, type PubMedErrorCode, type PubMedEvent, type PubMedIdentifier, type PubMedLink, type PubMedRecord, type PubMedSummary, type PubMedSummaryAuthor, type PubMedSummaryBook, type PubMedSummaryHistoryEntry, type PubMedSummaryIdentifier, type PubMedSummaryJournal, type PubMedWarning, type PublicationDates, type PublicationHistoryEntry, QueueFullError, type RateLimitBucket, type RateLimitCoordinator, RateLimitError, type RequestOptions, ResponseTooLargeError, type SearchAllOptions, type SearchBatch, type SearchCursorOptions, SearchLimitError, type SearchOptions, type SearchQueryOptions, type SearchTotalDriftDiagnostic, type SummaryBatchResult, type SummaryRequestOptions, TimeoutError, type UnknownPubMedRecord, ValidationError, formatCitation, formatCitations, parsePubMedXml };
+export { AbortedError, type AbstractSection, type Affiliation, type AuthorIdentifier, type BasePubMedRecord, type BatchResult, type CacheAdapter, type CitationFormat, type CitationSource, type CollectiveAuthor, CursorExpiredError, CursorInvalidError, HttpError, InvalidResponseError, type JournalCitation, type JsonObject, type JsonPrimitive, type JsonValue, type Keyword, MemoryCache, type MemoryCacheOptions, type MeshHeading, NetworkError, PaginationConsistencyError, ParseError, type ParsePubMedXmlOptions, type ParsedPubMedXml, type PartialDate, type PersonalAuthor, type PubMedArticleRecord, type PubMedAuthor, type PubMedBookRecord, PubMedClient, type PubMedClientOptions, type PubMedEndpoint, PubMedError, type PubMedErrorCode, type PubMedEvent, type PubMedIdentifier, type PubMedLink, type PubMedRecord, type PubMedSummary, type PubMedSummaryAuthor, type PubMedSummaryBook, type PubMedSummaryHistoryEntry, type PubMedSummaryIdentifier, type PubMedSummaryJournal, type PubMedWarning, type PublicationDates, type PublicationHistoryEntry, QueueFullError, type RateLimitBucket, type RateLimitCoordinator, RateLimitError, type RequestOptions, ResponseTooLargeError, type SearchAllOptions, type SearchBatch, type SearchCursorOptions, SearchLimitError, type SearchOptions, type SearchQueryOptions, type SearchTotalDriftDiagnostic, type SummaryBatchResult, type SummaryRequestOptions, TimeoutError, type UnknownPubMedRecord, ValidationError, formatCitation, formatCitations, parsePubMedXml };

package/dist/index.js

@@ -670,8 +670,19 @@ function parseFragment(fragment) {
 }
 
 // src/parser.ts
-function parsePubMedXml(xml) {
-  const records = extractFragments(xml).map(parseFragment);
+function parsePubMedXml(xml, options = {}) {
+  if (typeof options !== "object" || options === null || Array.isArray(options)) {
+    throw new ValidationError("parser options must be an object");
+  }
+  if (options.includeRawXml !== void 0 && typeof options.includeRawXml !== "boolean") {
+    throw new ValidationError("includeRawXml must be a boolean");
+  }
+  const records = extractFragments(xml).map((fragment) => {
+    const record = parseFragment(fragment);
+    if (options.includeRawXml === true) return record;
+    const { rawXml, ...withoutRawXml } = record;
+    return withoutRawXml;
+  });
   const warnings = records.flatMap((record) => record.kind === "unknown" ? [{ code: "UNKNOWN_RECORD", message: `Unknown PubMed record type: ${record.recordType}`, recordType: record.recordType }] : []);
   return { records, warnings };
 }
@@ -1522,7 +1533,9 @@ var Transport = class {
     const correlationId = randomUUID();
     safeEvent(this.#onEvent, { type: "correlation-id", endpoint, correlationId });
     try {
-      return await this.#coordinate(endpoint, parameters, decode, options, correlationId);
+      const value = await this.#coordinate(endpoint, parameters, decode, options, correlationId);
+      if (options.signal?.aborted) throw new AbortedError();
+      return value;
     } catch (error) {
       safeEvent(this.#onEvent, {
         type: "terminal-failure",
@@ -1546,6 +1559,7 @@ ${semantic.toString()}`);
       const cached = await this.#cache.read(key, signal);
       if (cached.status === "hit") {
         safeEvent(this.#onEvent, { type: "cache-hit", endpoint, correlationId });
+        if (signal?.aborted) throw new AbortedError();
         if (encoder.encode(cached.value).byteLength > this.#maxResponseBytes) {
           await this.#cache.invalidate(key);
         } else {
@@ -1626,6 +1640,9 @@ function isAbortSignal(value) {
 function validateRequestOptions(options, name) {
   const candidate = object3(options);
   if (candidate === void 0) throw new ValidationError(`${name} must be an object`);
+  if (candidate.includeRawXml !== void 0 && typeof candidate.includeRawXml !== "boolean") {
+    throw new ValidationError("includeRawXml must be a boolean");
+  }
   if (candidate.includeLinkOuts !== void 0 && typeof candidate.includeLinkOuts !== "boolean") {
     throw new ValidationError("includeLinkOuts must be a boolean");
   }
@@ -1636,6 +1653,9 @@ function validateRequestOptions(options, name) {
 function validateSummaryRequestOptions(options) {
   const candidate = object3(options);
   if (candidate === void 0) throw new ValidationError("summary request options must be an object");
+  if (candidate.includeRawXml !== void 0) {
+    throw new ValidationError("includeRawXml is not supported for summary requests");
+  }
   if (candidate.includeLinkOuts !== void 0) {
     throw new ValidationError("includeLinkOuts is not supported for summary requests");
   }
@@ -1768,7 +1788,7 @@ function validateSearchState(state, expectedIds, offset = 0) {
   }
 }
 function parseExpectedFetch(body, expectedPmids) {
-  const parsed = parsePubMedXml(body);
+  const parsed = parsePubMedXml(body, { includeRawXml: true });
   const expected = new Set(expectedPmids);
   const seen = /* @__PURE__ */ new Set();
   for (const record of parsed.records) {
@@ -1849,15 +1869,20 @@ function withLinks(record, extra) {
 var PubMedClient = class {
   #transport;
   #maxBatchSize;
+  #includeRawXml;
   #totalDriftPolicy;
   #onEvent;
   constructor(options) {
     if (typeof options !== "object" || options === null) throw new ValidationError("PubMedClient options are required");
     validateAdapterShapes(options);
+    if (options.includeRawXml !== void 0 && typeof options.includeRawXml !== "boolean") {
+      throw new ValidationError("includeRawXml must be a boolean");
+    }
+    this.#includeRawXml = options.includeRawXml ?? false;
     if (options.totalDriftPolicy !== void 0 && options.totalDriftPolicy !== "error" && options.totalDriftPolicy !== "warn") {
       throw new ValidationError('totalDriftPolicy must be "error" or "warn"');
     }
-    this.#totalDriftPolicy = options.totalDriftPolicy ?? "error";
+    this.#totalDriftPolicy = options.totalDriftPolicy ?? "warn";
     if (typeof options.email !== "string" || options.email.trim() === "") throw new ValidationError("email is required");
     if (typeof options.tool !== "string" || options.tool.trim() === "") throw new ValidationError("tool is required");
     if (options.apiKey !== void 0 && (typeof options.apiKey !== "string" || options.apiKey.trim() === "")) {
@@ -1920,7 +1945,11 @@ var PubMedClient = class {
     }
     let ordered = input.flatMap((pmid) => byPmid.get(pmid) ?? []);
     if (unknown.length > 0) ordered = [...ordered, ...unknown];
+    if (!(options.includeRawXml ?? this.#includeRawXml)) {
+      ordered = ordered.map(({ rawXml, ...record }) => record);
+    }
     if (options.includeLinkOuts === true && ordered.length > 0) ordered = await this.#enrich(ordered, options.signal);
+    if (options.signal?.aborted) throw new AbortedError();
     return {
       records: ordered,
       missingPmids: input.filter((pmid) => !byPmid.has(pmid)),
@@ -1949,6 +1978,7 @@ var PubMedClient = class {
       );
       received.push(...summaries);
     }
+    if (options.signal?.aborted) throw new AbortedError();
     const byPmid = new Map(received.map((summary) => [summary.pmid, summary]));
     return {
       summaries: input.flatMap((pmid) => byPmid.get(pmid) ?? []),
@@ -1959,7 +1989,7 @@ var PubMedClient = class {
     validateRequestOptions(options, "search options");
     if ("cursor" in options) {
       if (typeof options.cursor !== "string" || options.cursor === "") throw new ValidationError("cursor must be a non-empty string");
-      return (await this.#searchCursorPage(options.cursor, options.includeLinkOuts === true, options.signal)).batch;
+      return (await this.#searchCursorPage(options.cursor, options)).batch;
     }
     validateQueryOptions(options);
     return (await this.#searchQueryPage(options)).batch;
@@ -1975,6 +2005,7 @@ var PubMedClient = class {
       query: options.query,
       pageSize,
       ...options.sort === void 0 ? {} : { sort: options.sort },
+      ...options.includeRawXml === void 0 ? {} : { includeRawXml: options.includeRawXml },
       ...options.includeLinkOuts === void 0 ? {} : { includeLinkOuts: options.includeLinkOuts },
       ...options.signal === void 0 ? {} : { signal: options.signal }
     };
@@ -1991,8 +2022,7 @@ var PubMedClient = class {
       if (page.batch.nextCursor === null) throw new InvalidResponseError("PubMed search ended before the requested result count");
       page = await this.#searchCursorPage(
         page.batch.nextCursor,
-        options.includeLinkOuts === true,
-        options.signal,
+        options,
         target - processed
       );
     }
@@ -2032,10 +2062,7 @@ var PubMedClient = class {
         expectedPmids: []
       };
     }
-    const batch = await this.getMany(state.ids, {
-      ...options.includeLinkOuts === void 0 ? {} : { includeLinkOuts: options.includeLinkOuts },
-      ...options.signal === void 0 ? {} : { signal: options.signal }
-    });
+    const batch = await this.getMany(state.ids, options);
     const offset = state.ids.length;
     return {
       batch: {
@@ -2046,7 +2073,8 @@ var PubMedClient = class {
       expectedPmids: state.ids
     };
   }
-  async #searchCursorPage(cursorValue, includeLinkOuts, signal, maxExpected) {
+  async #searchCursorPage(cursorValue, options, maxExpected) {
+    const { signal } = options;
     const cursor = decodeCursor(cursorValue);
     if (cursor.offset >= SEARCH_WINDOW) throw new SearchLimitError();
     const remainingWindow = SEARCH_WINDOW - cursor.offset;
@@ -2085,7 +2113,7 @@ var PubMedClient = class {
       { cache: false, ...signal === void 0 ? {} : { signal } }
     );
     if (diagnostic !== void 0) safeEvent(this.#onEvent, { type: "search-total-drift", ...diagnostic });
-    const batch = await this.getMany(state.ids, { includeLinkOuts, ...signal === void 0 ? {} : { signal } });
+    const batch = await this.getMany(state.ids, options);
     const offset = cursor.offset + state.ids.length;
     return {
       batch: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everdeep/pubmed",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Safe, typed TypeScript client for the NCBI PubMed E-utilities API",
   "type": "module",
   "main": "./dist/index.cjs",