@oystehr/sdk 4.3.8 → 4.3.9

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

@@ -9,6 +9,9 @@ import {
   Bundle,
   BundleEntry,
   Coding,
+  FhirAsyncJobHandle,
+  FhirAsyncJobStatus,
+  FhirAsyncWaitOptions,
   FhirBundle,
   FhirCreateParams,
   FhirDeleteParams,
@@ -18,6 +21,7 @@ import {
   FhirPatchParams,
   FhirResource,
   FhirResourceReturnValue,
+  FhirResponseMode,
   FhirSearchParams,
   FhirUpdateParams,
   GenerateFriendlyPatientIdParams,
@@ -262,6 +266,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 +277,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 +304,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 +329,255 @@ export async function search<T extends FhirResource>(
   return bundle;
 }
 
+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;
+}
+
+export async function getAsyncJob<T extends FhirResource>(
+  this: SDKResource,
+  jobId: string,
+  request?: OystehrClientRequest
+): Promise<FhirAsyncJobStatus<T>> {
+  return await this.fetchAsyncJobStatus<T>(jobId, request);
+}
+
+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,
+  });
+}
+
+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 +588,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 +760,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 +828,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

@@ -20,6 +20,9 @@ export class Fhir extends SDKResource {
   search = ext.search;
   create = ext.create;
   get = ext.get;
+  getAsyncJob = ext.getAsyncJob;
+  waitForAsyncJob = ext.waitForAsyncJob;
+  cancelAsyncJob = ext.cancelAsyncJob;
   update = ext.update;
   patch = ext.patch;
   delete = ext.delete;

package/src/resources/types/fhir.ts

@@ -166,3 +166,91 @@ export type BatchInputRequest<F extends FhirResource> =
 export interface BatchInput<F extends FhirResource> {
   requests: BatchInputRequest<F>[];
 }
+
+export interface FhirAsyncJobHandle {
+  jobId: string;
+  contentLocation: string;
+  mode: FhirAsyncResponseMode;
+}
+
+export type FhirResponseMode = 'sync' | 'async-bundle' | 'async-bulk';
+
+export type FhirAsyncResponseMode = 'bundle' | 'bulk';
+
+export interface FhirAsyncCompletionBundleEntry<T extends FhirResource> {
+  response?: {
+    status?: string;
+    outcome?: OperationOutcome;
+  };
+  resource?: T | OperationOutcome;
+}
+
+export type FhirAsyncCompletionBundle<T extends FhirResource> = EntrylessFhirBundle<T | OperationOutcome> & {
+  resourceType: 'Bundle';
+  type: 'batch-response';
+  entry?: Array<FhirAsyncCompletionBundleEntry<T>>;
+};
+
+export interface FhirAsyncJobInProgress {
+  status: 202;
+  xProgress?: string;
+  retryAfter?: string;
+}
+
+export interface FhirAsyncJobCompletedBundle<T extends FhirResource = FhirResource> {
+  status: 200;
+  mode: 'bundle';
+  bundle: FhirAsyncCompletionBundle<T>;
+  interactionStatus?: string;
+  resource?: T | OperationOutcome;
+  outcome?: OperationOutcome;
+}
+
+export interface FhirAsyncBulkOutputFile {
+  type: string;
+  url: string;
+}
+
+export interface FhirAsyncBulkManifest {
+  transactionTime: string;
+  request: string;
+  requiresAccessToken: boolean;
+  output: FhirAsyncBulkOutputFile[];
+  error: FhirAsyncBulkOutputFile[];
+  deleted?: FhirAsyncBulkOutputFile[];
+  extension?: Record<string, unknown>;
+}
+
+export interface FhirAsyncJobCompletedBulk {
+  status: 200;
+  mode: 'bulk';
+  manifest: FhirAsyncBulkManifest;
+}
+
+export interface FhirAsyncJobExpired {
+  status: 410;
+}
+
+export interface FhirAsyncJobNotFound {
+  status: 404;
+}
+
+export interface FhirAsyncJobUnexpected {
+  status: Exclude<number, 200 | 202 | 404 | 410>;
+  body: unknown;
+}
+
+export type FhirAsyncJobStatus<T extends FhirResource = FhirResource> =
+  | FhirAsyncJobInProgress
+  | FhirAsyncJobCompletedBundle<T>
+  | FhirAsyncJobCompletedBulk
+  | FhirAsyncJobExpired
+  | FhirAsyncJobNotFound
+  | FhirAsyncJobUnexpected;
+
+export interface FhirAsyncWaitOptions {
+  /** Poll interval in milliseconds. Defaults to 1000 (1 second). */
+  pollIntervalMs: number;
+  /** Maximum wait time in milliseconds before timing out. Defaults to 900000 (15 minutes). */
+  timeoutMs: number;
+}