@oystehr/sdk 4.3.8 → 4.3.10

package/src/resources/classes/fhir-ext.ts

@@ -9,6 +9,10 @@ import {
   Bundle,
   BundleEntry,
   Coding,
+  FhirAsyncBulkOutputResult,
+  FhirAsyncJobHandle,
+  FhirAsyncJobStatus,
+  FhirAsyncWaitOptions,
   FhirBundle,
   FhirCreateParams,
   FhirDeleteParams,
@@ -18,6 +22,7 @@ import {
   FhirPatchParams,
   FhirResource,
   FhirResourceReturnValue,
+  FhirResponseMode,
   FhirSearchParams,
   FhirUpdateParams,
   GenerateFriendlyPatientIdParams,
@@ -262,6 +267,10 @@ export interface OystehrFHIRUpdateClientRequest extends OystehrClientRequest {
   optimisticLockingVersionId?: string;
 }
 
+function isAsyncRequestMode(mode: FhirResponseMode | undefined): mode is Exclude<FhirResponseMode, 'sync'> {
+  return mode === 'async-bundle' || mode === 'async-bulk';
+}
+
 /**
  * Performs a FHIR search and returns the results as a Bundle resource
  *
@@ -269,11 +278,21 @@ export interface OystehrFHIRUpdateClientRequest extends OystehrClientRequest {
  * @param request optional OystehrClientRequest object
  * @returns FHIR Bundle resource
  */
+export async function search<T extends FhirResource>(
+  this: SDKResource,
+  params: FhirSearchParams<T>,
+  request: OystehrClientRequest & { mode: Exclude<FhirResponseMode, 'sync'> }
+): Promise<FhirAsyncJobHandle>;
+export async function search<T extends FhirResource>(
+  this: SDKResource,
+  params: FhirSearchParams<T>,
+  request?: OystehrClientRequest & { mode?: 'sync' | undefined }
+): Promise<FhirFetcherResponse<Bundle<T>>>;
 export async function search<T extends FhirResource>(
   this: SDKResource,
   params: FhirSearchParams<T>,
   request?: OystehrClientRequest
-): Promise<FhirFetcherResponse<Bundle<T>>> {
+): Promise<FhirFetcherResponse<Bundle<T>> | FhirAsyncJobHandle> {
   const { resourceType } = params;
   const taggedParams = applyTagSearchParams(this.config, params.params);
   let paramMap: Record<string, (string | number)[]> | undefined;
@@ -286,6 +305,15 @@ export async function search<T extends FhirResource>(
       return acc;
     }, {} as Record<string, (string | number)[]>);
   }
+
+  const requestMode = request?.mode;
+  if (isAsyncRequestMode(requestMode)) {
+    return await this.startAsyncJob(`/${resourceType}/_search`, 'POST', paramMap ?? {}, requestMode, {
+      ...request,
+      contentType: 'application/x-www-form-urlencoded',
+    });
+  }
+
   const requestBundle = await this.fhirRequest<FhirBundle<T>>(`/${resourceType}/_search`, 'POST')(paramMap, {
     ...request,
     contentType: 'application/x-www-form-urlencoded',
@@ -302,76 +330,459 @@ export async function search<T extends FhirResource>(
   return bundle;
 }
 
+/**
+ * Performs an iterative FHIR search over initial request and following "next" urls,
+ * collecting all pages into a single Bundle.
+ *
+ * @param params FHIR search parameters plus optional pageSize that will overwrite _count in params
+ * @param request optional OystehrClientRequest object
+ * @returns FHIR Bundle resource that contains all entries across all pages. Bundle-level metadata
+ * (id, meta, total, etc.) is taken from the first page.
+ */
+export async function searchAndGetAllPages<T extends FhirResource>(
+  this: SDKResource,
+  params: FhirSearchParams<T> & { pageSize?: number },
+  request?: OystehrClientRequest & { mode?: 'sync' | undefined }
+): Promise<Bundle<T>> {
+  const { pageSize, ...searchParams } = params;
+
+  let firstPageParams: FhirSearchParams<T> = searchParams;
+  if (pageSize) {
+    const baseParams = (searchParams.params ?? []).filter((p) => p.name !== '_count') ?? [];
+    firstPageParams = { ...searchParams, params: [...baseParams, { name: '_count', value: pageSize }] };
+  }
+
+  const allEntries: Array<BundleEntry<T>> = [];
+
+  const typedSearch = search<T>;
+  // search returns Bundle, and fhirRequest in the while block returns FhirBundle
+  let currentBundle: Bundle<T> | FhirBundle<T> = await typedSearch.call(this, firstPageParams, request);
+  const firstBundle = { ...currentBundle, link: currentBundle.link?.filter((link) => link.relation !== 'next') };
+
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    const entries = currentBundle.entry as Array<BundleEntry<T>> | undefined;
+    if (entries) {
+      allEntries.push(...entries);
+    }
+
+    const nextLink: string | undefined = currentBundle.link?.find((link) => link.relation === 'next')?.url;
+    if (!nextLink) {
+      break;
+    }
+    currentBundle = await this.fhirRequest<FhirBundle<T>>(nextLink, 'GET')({}, request);
+  }
+
+  return {
+    ...firstBundle,
+    entry: allEntries.length ? allEntries : undefined,
+    unbundle: function (this: { entry?: Array<BundleEntry<T>> }) {
+      return this.entry?.map((e) => e.resource).filter((r): r is T => r !== undefined) ?? [];
+    },
+  };
+}
+
+export async function create<T extends FhirResource>(
+  this: SDKResource,
+  params: FhirCreateParams<T>,
+  request: OystehrClientRequest & { mode: Exclude<FhirResponseMode, 'sync'> }
+): Promise<FhirAsyncJobHandle>;
+export async function create<T extends FhirResource>(
+  this: SDKResource,
+  params: FhirCreateParams<T>,
+  request?: OystehrClientRequest & { mode?: 'sync' | undefined }
+): Promise<FhirFetcherResponse<FhirResourceReturnValue<T>>>;
 export async function create<T extends FhirResource>(
   this: SDKResource,
   params: FhirCreateParams<T>,
   request?: OystehrClientRequest
-): Promise<FhirFetcherResponse<FhirResourceReturnValue<T>>> {
+): Promise<FhirFetcherResponse<FhirResourceReturnValue<T>> | FhirAsyncJobHandle> {
   const tagged = applyTagToResource(this.config, params);
   const { resourceType } = tagged;
-  return this.fhirRequest(`/${resourceType}`, 'POST')(tagged as unknown as Record<string, unknown>, request);
+  const requestMode = request?.mode;
+  if (isAsyncRequestMode(requestMode)) {
+    return await this.startAsyncJob(
+      `/${resourceType}`,
+      'POST',
+      tagged as unknown as Record<string, unknown>,
+      requestMode,
+      request
+    );
+  }
+
+  return await this.fhirRequest<FhirResourceReturnValue<T>>(`/${resourceType}`, 'POST')(
+    tagged as unknown as Record<string, unknown>,
+    request
+  );
 }
 
+export async function get<T extends FhirResource>(
+  this: SDKResource,
+  { resourceType, id }: FhirGetParams<T>,
+  request: OystehrClientRequest & { mode: Exclude<FhirResponseMode, 'sync'> }
+): Promise<FhirAsyncJobHandle>;
+export async function get<T extends FhirResource>(
+  this: SDKResource,
+  { resourceType, id }: FhirGetParams<T>,
+  request?: OystehrClientRequest & { mode?: 'sync' | undefined }
+): Promise<FhirFetcherResponse<FhirResourceReturnValue<T>>>;
 export async function get<T extends FhirResource>(
   this: SDKResource,
   { resourceType, id }: FhirGetParams<T>,
   request?: OystehrClientRequest
-): Promise<FhirFetcherResponse<FhirResourceReturnValue<T>>> {
+): Promise<FhirFetcherResponse<FhirResourceReturnValue<T>> | FhirAsyncJobHandle> {
+  const requestMode = request?.mode;
+  if (isAsyncRequestMode(requestMode)) {
+    return await this.startAsyncJob(`/${resourceType}/${id}`, 'GET', {}, requestMode, request);
+  }
+
   const result = await this.fhirRequest<FhirResourceReturnValue<T>>(`/${resourceType}/${id}`, 'GET')({}, request);
   assertRetrievedResource(this.config, result);
   return result;
 }
 
+export async function update<T extends FhirResource>(
+  this: SDKResource,
+  params: FhirUpdateParams<T>,
+  request: OystehrFHIRUpdateClientRequest & { mode: Exclude<FhirResponseMode, 'sync'> }
+): Promise<FhirAsyncJobHandle>;
+export async function update<T extends FhirResource>(
+  this: SDKResource,
+  params: FhirUpdateParams<T>,
+  request?: OystehrFHIRUpdateClientRequest & { mode?: 'sync' | undefined }
+): Promise<FhirFetcherResponse<FhirResourceReturnValue<T>>>;
 export async function update<T extends FhirResource>(
   this: SDKResource,
   params: FhirUpdateParams<T>,
   request?: OystehrFHIRUpdateClientRequest
-): Promise<FhirFetcherResponse<FhirResourceReturnValue<T>>> {
+): Promise<FhirFetcherResponse<FhirResourceReturnValue<T>> | FhirAsyncJobHandle> {
   const tagged = applyTagToResource(this.config, params);
   const { id, resourceType } = tagged;
-  return this.fhirRequest(`/${resourceType}/${id}`, 'PUT')(tagged as unknown as Record<string, unknown>, {
+  const requestMode = request?.mode;
+  const ifMatchRequest = {
     ...request,
     ifMatch: request?.optimisticLockingVersionId ? `W/"${request.optimisticLockingVersionId}"` : undefined,
-  });
+  };
+
+  if (isAsyncRequestMode(requestMode)) {
+    return await this.startAsyncJob(
+      `/${resourceType}/${id}`,
+      'PUT',
+      tagged as unknown as Record<string, unknown>,
+      requestMode,
+      ifMatchRequest
+    );
+  }
+
+  return await this.fhirRequest<FhirResourceReturnValue<T>>(`/${resourceType}/${id}`, 'PUT')(
+    tagged as unknown as Record<string, unknown>,
+    ifMatchRequest
+  );
 }
 
+export async function patch<T extends FhirResource>(
+  this: SDKResource,
+  params: FhirPatchParams<T>,
+  request: OystehrFHIRUpdateClientRequest & { mode: Exclude<FhirResponseMode, 'sync'> }
+): Promise<FhirAsyncJobHandle>;
+export async function patch<T extends FhirResource>(
+  this: SDKResource,
+  params: FhirPatchParams<T>,
+  request?: OystehrFHIRUpdateClientRequest & { mode?: 'sync' | undefined }
+): Promise<FhirFetcherResponse<FhirResourceReturnValue<T>>>;
 export async function patch<T extends FhirResource>(
   this: SDKResource,
   { resourceType, id, operations }: FhirPatchParams<T>,
   request?: OystehrFHIRUpdateClientRequest
-): Promise<FhirFetcherResponse<FhirResourceReturnValue<T>>> {
+): Promise<FhirFetcherResponse<FhirResourceReturnValue<T>> | FhirAsyncJobHandle> {
   const taggedOperations = applyTagToPatchOperations(this.config, operations);
-  return this.fhirRequest(`/${resourceType}/${id}`, 'PATCH')(taggedOperations, {
+  const requestMode = request?.mode;
+  const ifMatchRequest = {
     ...request,
-    contentType: 'application/json-patch+json',
     ifMatch: request?.optimisticLockingVersionId ? `W/"${request.optimisticLockingVersionId}"` : undefined,
+  };
+
+  if (isAsyncRequestMode(requestMode)) {
+    return await this.startAsyncJob(
+      `/${resourceType}/${id}`,
+      'PATCH',
+      taggedOperations as unknown as Record<string, unknown>,
+      requestMode,
+      {
+        ...ifMatchRequest,
+        contentType: 'application/json-patch+json',
+      }
+    );
+  }
+
+  return this.fhirRequest<FhirResourceReturnValue<T>>(`/${resourceType}/${id}`, 'PATCH')(taggedOperations, {
+    ...ifMatchRequest,
+    contentType: 'application/json-patch+json',
   });
 }
 
+async function del<T extends FhirResource>(
+  this: SDKResource,
+  params: FhirDeleteParams<T>,
+  request: OystehrClientRequest & { mode: Exclude<FhirResponseMode, 'sync'> }
+): Promise<FhirAsyncJobHandle>;
+async function del<T extends FhirResource>(
+  this: SDKResource,
+  params: FhirDeleteParams<T>,
+  request?: OystehrClientRequest & { mode?: 'sync' | undefined }
+): Promise<FhirFetcherResponse<FhirResourceReturnValue<T>>>;
 async function del<T extends FhirResource>(
   this: SDKResource,
   { resourceType, id }: FhirDeleteParams<T>,
   request?: OystehrClientRequest
-): Promise<FhirFetcherResponse<FhirResourceReturnValue<T>>> {
-  return this.fhirRequest(`/${resourceType}/${id}`, 'DELETE')({}, request);
+): Promise<FhirFetcherResponse<FhirResourceReturnValue<T>> | FhirAsyncJobHandle> {
+  const requestMode = request?.mode;
+  if (isAsyncRequestMode(requestMode)) {
+    return await this.startAsyncJob(`/${resourceType}/${id}`, 'DELETE', {}, requestMode, request);
+  }
+
+  return await this.fhirRequest<FhirResourceReturnValue<T>>(`/${resourceType}/${id}`, 'DELETE')({}, request);
 }
 export { del as delete };
 
+function getRetryDelayMs(retryAfter: string | undefined, fallbackMs: number): number {
+  if (!retryAfter) {
+    return fallbackMs;
+  }
+
+  const asSeconds = Number(retryAfter);
+  if (Number.isFinite(asSeconds) && asSeconds >= 0) {
+    return Math.max(0, Math.floor(asSeconds * 1000));
+  }
+
+  const asTimestamp = Date.parse(retryAfter);
+  if (Number.isFinite(asTimestamp)) {
+    return Math.max(0, asTimestamp - Date.now());
+  }
+
+  return fallbackMs;
+}
+
+/**
+ *  Fetches the status of an async job. If the job is still in progress, returns an object with status 202. If the job is completed, returns the job result with status 200. If the job has failed, returns an object with status 500 and an OperationOutcome resource describing the failure. If the job has expired, returns an object with status 410.
+ * @param this The SDKResource context (this is an extension method and should be called with the SDKResource instance as the context, e.g. `sdkResource.getAsyncJob(jobId)`)
+ * @param jobId The ID of the async job to fetch
+ * @param request  Optional OystehrClientRequest for authentication and headers
+ * @returns  A Promise that resolves to the FhirAsyncJobStatus
+ */
+export async function getAsyncJob<T extends FhirResource>(
+  this: SDKResource,
+  jobId: string,
+  request?: OystehrClientRequest
+): Promise<FhirAsyncJobStatus<T>> {
+  return await this.fetchAsyncJobStatus<T>(jobId, request);
+}
+
+/**
+ *  Waits for an async job to complete by polling its status until it reaches a terminal state (success, failure, or expiration) or the specified timeout is reached. Returns the final job status. Throws if the job fails, expires, or does not complete within the timeout.
+ * @param this  The SDKResource context (this is an extension method and should be called with the SDKResource instance as the context, e.g. `sdkResource.waitForAsyncJob(jobId)`)
+ * @param jobId  The ID of the async job to wait for
+ * @param options  Optional FhirAsyncWaitOptions to configure polling behavior
+ * @param request  Optional OystehrClientRequest for authentication and headers
+ * @returns  A Promise that resolves to the final FhirAsyncJobStatus
+ */
+export async function waitForAsyncJob<T extends FhirResource>(
+  this: SDKResource,
+  jobId: string,
+  options?: FhirAsyncWaitOptions,
+  request?: OystehrClientRequest
+): Promise<FhirAsyncJobStatus<T>> {
+  // 5 seconds poll interval by default
+  const pollIntervalMs = options?.pollIntervalMs ?? 5000;
+  // 15 minutes timout by default
+  const timeoutMs = options?.timeoutMs ?? 900000;
+  const attempts = Math.max(1, Math.ceil(timeoutMs / pollIntervalMs));
+
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    const status = await this.fetchAsyncJobStatus<T>(jobId, request);
+    if (status.status !== 202) {
+      return status;
+    }
+
+    if (attempt < attempts - 1) {
+      const retryAfter = 'retryAfter' in status ? status.retryAfter : undefined;
+      await new Promise((resolve) => setTimeout(resolve, getRetryDelayMs(retryAfter, pollIntervalMs)));
+    }
+  }
+
+  throw new OystehrSdkError({
+    message: `Async job ${jobId} did not complete within ${timeoutMs} ms`,
+    code: 408,
+  });
+}
+
+function parseNdjsonResources<T extends FhirResource>(ndjson: string, sourceUrl: string): T[] {
+  const resources: T[] = [];
+  const lines = ndjson.split('\n');
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index].trim();
+    if (line.length === 0) {
+      continue;
+    }
+    try {
+      resources.push(JSON.parse(line) as T);
+    } catch (error) {
+      throw new OystehrSdkError({
+        message: `Failed to parse NDJSON line ${index + 1} from ${sourceUrl}`,
+        code: 500,
+        cause: error,
+      });
+    }
+  }
+  return resources;
+}
+
+/**
+ *  Waits for an async job to complete and retrieves the bulk output manifest and files. Throws if the job fails, expires, or does not complete within the specified timeout.
+ * @param this  The SDKResource context (this is an extension method and should be called with the SDKResource instance as the context, e.g. `sdkResource.waitForAsyncBulkOutput(jobId)`)
+ * @param jobId  The ID of the async job to wait for
+ * @param options  Optional FhirAsyncWaitOptions to configure polling behavior
+ * @param request  Optional OystehrClientRequest for authentication and headers
+ * @returns  A Promise that resolves to a FhirAsyncBulkOutputResult containing the bulk output manifest and files
+ */
+export async function waitForAsyncBulkOutput<T extends FhirResource>(
+  this: SDKResource,
+  jobId: string,
+  options?: FhirAsyncWaitOptions,
+  request?: OystehrClientRequest
+): Promise<FhirAsyncBulkOutputResult<T>> {
+  const status = await waitForAsyncJob.call(this, jobId, options, request);
+
+  if (status.status === 404) {
+    throw new OystehrSdkError({
+      message: `Async job ${jobId} not found`,
+      code: 404,
+    });
+  }
+
+  if (status.status === 410) {
+    throw new OystehrSdkError({
+      message: `Async job ${jobId} expired`,
+      code: 410,
+    });
+  }
+
+  if (status.status !== 200 || !('mode' in status) || status.mode !== 'bulk') {
+    throw new OystehrSdkError({
+      message: `Async job ${jobId} did not complete in bulk mode`,
+      code: status.status,
+    });
+  }
+
+  const accessToken = request?.accessToken ?? this.config.accessToken;
+  const projectId = request?.projectId ?? this.config.projectId;
+  if (status.manifest.requiresAccessToken && !accessToken) {
+    throw new OystehrSdkError({
+      message: `Bulk output for async job ${jobId} requires an access token`,
+      code: 401,
+    });
+  }
+
+  const fetchImpl = this.config.fetch ?? fetch;
+  const headers: Record<string, string> = {};
+  if (projectId) {
+    headers['x-zapehr-project-id'] = projectId;
+    headers['x-oystehr-project-id'] = projectId;
+  }
+  if (status.manifest.requiresAccessToken && accessToken) {
+    headers.Authorization = `Bearer ${accessToken}`;
+  }
+  const requestHeaders = Object.keys(headers).length > 0 ? headers : undefined;
+
+  const output = await Promise.all(
+    status.manifest.output.map(async (file) => {
+      const response = await fetchImpl(
+        new Request(file.url, {
+          method: 'GET',
+          headers: requestHeaders,
+        })
+      );
+
+      if (!response.ok) {
+        throw new OystehrSdkError({
+          message: `Failed to download bulk output (${file.type}): HTTP ${response.status}`,
+          code: response.status,
+        });
+      }
+
+      const ndjson = await response.text();
+      return {
+        ...file,
+        resources: parseNdjsonResources<T>(ndjson, file.url),
+      };
+    })
+  );
+
+  return {
+    manifest: status.manifest,
+    output,
+  };
+}
+
+/**
+ * Wrapper around waitForAsyncBulkOutput that transforms the retrieved bulk output files into a single Bundle resource containing all the output resources as entries. This is a convenience method for use cases where you want to work with the bulk output as a Bundle, but it may not be efficient for large outputs due to the overhead of downloading and parsing all files and constructing the Bundle in memory.
+ * Can be slow due to downloading and parsing potentially large NDJSON files, so use only if you need the full output as a Bundle resource. For more efficient processing of large bulk outputs, use waitForAsyncBulkOutput directly.
+ * @param jobId the ID of the async job to wait for
+ * @param options optional FhirAsyncWaitOptions to configure polling behavior
+ * @param request optional OystehrClientRequest for authentication and headers
+ * @returns a Promise that resolves to a Bundle containing all resources from the bulk output
+ */
+export async function waitForAsyncBulkBundle<T extends FhirResource>(
+  this: SDKResource,
+  jobId: string,
+  options?: FhirAsyncWaitOptions,
+  request?: OystehrClientRequest
+): Promise<Bundle<T>> {
+  const bulkOutput = await waitForAsyncBulkOutput.call(this, jobId, options, request);
+  const resources = bulkOutput.output.flatMap((file) => file.resources);
+
+  const bundle = {
+    resourceType: 'Bundle',
+    type: 'collection',
+    entry: resources.map((resource) => ({ resource } as BundleEntry<T>)),
+    unbundle: function (this: { entry?: Array<BundleEntry<T>> | undefined }) {
+      return this.entry?.map((entry) => entry.resource).filter((value): value is T => value !== undefined) ?? [];
+    },
+  } as unknown as Bundle<T>;
+
+  return bundle;
+}
+
+export async function cancelAsyncJob(this: SDKResource, jobId: string, request?: OystehrClientRequest): Promise<void> {
+  await this.fhirRequest(`/async-job/${jobId}`, 'DELETE')({}, request);
+}
+
 export async function history<T extends FhirResource>(
   this: SDKResource,
   { resourceType, id }: FhirHistorySearchParams<T>,
-  request?: OystehrClientRequest
-): Promise<FhirFetcherResponse<Bundle<T>>>;
+  request: OystehrClientRequest & { mode: Exclude<FhirResponseMode, 'sync'> }
+): Promise<FhirAsyncJobHandle>;
 export async function history<T extends FhirResource>(
   this: SDKResource,
   { resourceType, id, versionId }: FhirHistoryGetParams<T>,
-  request?: OystehrClientRequest
+  request: OystehrClientRequest & { mode: Exclude<FhirResponseMode, 'sync'> }
+): Promise<FhirAsyncJobHandle>;
+export async function history<T extends FhirResource>(
+  this: SDKResource,
+  { resourceType, id, versionId }: FhirHistoryGetParams<T>,
+  request?: OystehrClientRequest & { mode?: 'sync' | undefined }
 ): Promise<FhirFetcherResponse<T>>;
+export async function history<T extends FhirResource>(
+  this: SDKResource,
+  { resourceType, id }: FhirHistorySearchParams<T>,
+  request?: OystehrClientRequest & { mode?: 'sync' | undefined }
+): Promise<FhirFetcherResponse<Bundle<T>>>;
 export async function history<T extends FhirResource>(
   this: SDKResource,
   { resourceType, id, count, offset }: FhirHistorySearchParams<T>,
-  request?: OystehrClientRequest
+  request?: OystehrClientRequest & { mode?: 'sync' | undefined }
 ): Promise<FhirFetcherResponse<Bundle<T>>>;
+
 export async function history<T extends FhirResource>(
   this: SDKResource,
   {
@@ -382,18 +793,26 @@ export async function history<T extends FhirResource>(
     offset,
   }: { resourceType: string; id: string; versionId?: string; count?: number; offset?: number },
   request?: OystehrClientRequest
-): Promise<FhirFetcherResponse<Bundle<T>> | FhirFetcherResponse<T>> {
+): Promise<FhirFetcherResponse<Bundle<T>> | FhirFetcherResponse<T> | FhirAsyncJobHandle> {
+  const requestMode = request?.mode;
+  if (isAsyncRequestMode(requestMode)) {
+    if (versionId) {
+      return await this.startAsyncJob(`/${resourceType}/${id}/_history/${versionId}`, 'GET', {}, requestMode, request);
+    }
+    return await this.startAsyncJob(`/${resourceType}/${id}/_history`, 'GET', {}, requestMode, request);
+  }
+
   if (versionId) {
-    return this.fhirRequest(`/${resourceType}/${id}/_history/${versionId}`, 'GET')({}, request);
+    return this.fhirRequest<T>(`/${resourceType}/${id}/_history/${versionId}`, 'GET')({}, request);
   }
   if (count) {
-    return this.fhirRequest(
+    return this.fhirRequest<Bundle<T>>(
       `/${resourceType}/${id}/_history?_total=accurate&_count=${count}
       ${offset ? `&_offset=${offset}` : ''}`,
       'GET'
     )({}, request);
   }
-  return this.fhirRequest(`/${resourceType}/${id}/_history?_total=accurate`, 'GET')({}, request);
+  return this.fhirRequest<Bundle<T>>(`/${resourceType}/${id}/_history?_total=accurate`, 'GET')({}, request);
 }
 
 /**
@@ -546,19 +965,32 @@ function batchInputRequestToBundleEntryItem<T extends FhirResource>(
   throw new Error('Unrecognized method');
 }
 
+export async function batch<BundleContentType extends FhirResource>(
+  this: SDKResource,
+  input: BatchInput<BundleContentType>,
+  request: OystehrClientRequest & { mode: Exclude<FhirResponseMode, 'sync'> }
+): Promise<FhirAsyncJobHandle>;
+export async function batch<BundleContentType extends FhirResource>(
+  this: SDKResource,
+  input: BatchInput<BundleContentType>,
+  request?: OystehrClientRequest & { mode?: 'sync' | undefined }
+): Promise<FhirFetcherResponse<BatchBundle<BundleContentType>>>;
 export async function batch<BundleContentType extends FhirResource>(
   this: SDKResource,
   input: BatchInput<BundleContentType>,
   request?: OystehrClientRequest
-): Promise<FhirFetcherResponse<BatchBundle<BundleContentType>>> {
-  const resp = await this.fhirRequest('/', 'POST')(
-    {
-      resourceType: 'Bundle',
-      type: 'batch',
-      entry: input.requests.map((req) => batchInputRequestToBundleEntryItem(req, this.config)),
-    },
-    request
-  );
+): Promise<FhirFetcherResponse<BatchBundle<BundleContentType>> | FhirAsyncJobHandle> {
+  const requestPayload = {
+    resourceType: 'Bundle',
+    type: 'batch',
+    entry: input.requests.map((req) => batchInputRequestToBundleEntryItem(req, this.config)),
+  };
+  const requestMode = request?.mode;
+  if (isAsyncRequestMode(requestMode)) {
+    return await this.startAsyncJob('/', 'POST', requestPayload, requestMode, request);
+  }
+
+  const resp = await this.fhirRequest<BatchBundle<BundleContentType>>('/', 'POST')(requestPayload, request);
   // Validate each GET/HEAD retrieval entry against the tag config.
   // Violations are replaced with a synthetic 404 OperationOutcome entry; batch entries are independent.
   const rawEntries = resp.entry as Array<BundleEntry<BundleContentType>> | undefined;
@@ -601,19 +1033,32 @@ export async function batch<BundleContentType extends FhirResource>(
   return bundle;
 }
 
+export async function transaction<BundleContentType extends FhirResource>(
+  this: SDKResource,
+  input: BatchInput<BundleContentType>,
+  request: OystehrClientRequest & { mode: Exclude<FhirResponseMode, 'sync'> }
+): Promise<FhirAsyncJobHandle>;
+export async function transaction<BundleContentType extends FhirResource>(
+  this: SDKResource,
+  input: BatchInput<BundleContentType>,
+  request?: OystehrClientRequest & { mode?: 'sync' | undefined }
+): Promise<FhirFetcherResponse<TransactionBundle<BundleContentType>>>;
 export async function transaction<BundleContentType extends FhirResource>(
   this: SDKResource,
   input: BatchInput<BundleContentType>,
   request?: OystehrClientRequest
-): Promise<FhirFetcherResponse<TransactionBundle<BundleContentType>>> {
-  const resp = await this.fhirRequest('/', 'POST')(
-    {
-      resourceType: 'Bundle',
-      type: 'transaction',
-      entry: input.requests.map((req) => batchInputRequestToBundleEntryItem(req, this.config)),
-    },
-    request
-  );
+): Promise<FhirFetcherResponse<TransactionBundle<BundleContentType>> | FhirAsyncJobHandle> {
+  const requestPayload = {
+    resourceType: 'Bundle',
+    type: 'transaction',
+    entry: input.requests.map((req) => batchInputRequestToBundleEntryItem(req, this.config)),
+  };
+  const requestMode = request?.mode;
+  if (isAsyncRequestMode(requestMode)) {
+    return await this.startAsyncJob('/', 'POST', requestPayload, requestMode, request);
+  }
+
+  const resp = await this.fhirRequest<TransactionBundle<BundleContentType>>('/', 'POST')(requestPayload, request);
   // Validate each GET/HEAD retrieval entry against the tag config.
   // A violation throws OystehrFHIRError(404) — transactions are all-or-nothing.
   if (this.config.workspaceTag || this.config.ignoreTags?.length) {

package/src/resources/classes/fhir.ts

@@ -18,11 +18,25 @@ export class Fhir extends SDKResource {
    * @returns FHIR Bundle resource
    */
   search = ext.search;
+  /**
+   * Performs an iterative FHIR search over initial request and following "next" urls,
+   * collecting all pages into a single Bundle.
+   * @param params FHIR search parameters plus optional pageSize that will overwrite _count in params
+   * @param request optional OystehrClientRequest object
+   * @returns FHIR Bundle resource that contains all entries across all pages. Bundle-level metadata
+   * (id, meta, total, etc.) is taken from the first page.
+   */
+  searchAndGetAllPages = ext.searchAndGetAllPages;
   create = ext.create;
   get = ext.get;
   update = ext.update;
   patch = ext.patch;
   delete = ext.delete;
+  getAsyncJob = ext.getAsyncJob;
+  waitForAsyncJob = ext.waitForAsyncJob;
+  waitForAsyncBulkOutput = ext.waitForAsyncBulkOutput;
+  waitForAsyncBulkBundle = ext.waitForAsyncBulkBundle;
+  cancelAsyncJob = ext.cancelAsyncJob;
   history = ext.history;
   batch = ext.batch;
   transaction = ext.transaction;