@oystehr/sdk 4.3.8 → 4.3.9

package/dist/esm/resources/types/fhir.d.ts

@@ -117,4 +117,71 @@ export type BatchInputRequest<F extends FhirResource> = BatchInputGetRequest | B
 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;
+}
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oystehr/sdk",
-  "version": "4.3.8",
+  "version": "4.3.9",
   "description": "Oystehr SDK",
   "scripts": {
     "lint": "eslint .",

package/src/client/client.ts

@@ -2,7 +2,16 @@ import { v4 as uuidv4, validate as uuidValidate } from 'uuid';
 import { OystehrConfig } from '../config';
 import { OystehrFHIRError, OystehrSdkError } from '../errors';
 import { Logger } from '../logger';
-import { FhirBundle, FhirResource, OperationOutcome } from '../resources/types';
+import {
+  FhirAsyncBulkManifest,
+  FhirAsyncCompletionBundle,
+  FhirAsyncJobHandle,
+  FhirAsyncJobStatus,
+  FhirBundle,
+  FhirResource,
+  FhirResponseMode,
+  OperationOutcome,
+} from '../resources/types';
 
 type HttpMethod = 'get' | 'put' | 'post' | 'delete' | 'options' | 'head' | 'patch' | 'trace';
 export const defaultProjectApiUrl = 'https://project-api.zapehr.com/v1';
@@ -41,10 +50,19 @@ export interface OystehrClientRequest {
    * Unique identifier for this request.
    */
   requestId?: string;
+  /**
+   * Optional execution mode for FHIR requests that support async behavior.
+   * Defaults to `sync` when omitted.
+   */
+  mode?: FhirResponseMode;
 }
 
 interface InternalClientRequest extends OystehrClientRequest {
   ifMatch?: string;
+  /**
+   * Internal-only: returns raw response metadata ({ status, headers, body }) instead of throwing on non-2xx statuses.
+   */
+  rawResponse?: boolean;
 }
 
 type FhirData<T extends FhirResource> = T | T[] | FhirBundle<T>;
@@ -75,14 +93,22 @@ export class SDKResource {
     };
   }
 
-  protected fhirRequest<T extends FhirResource = any>(path: string, method: string) {
-    return async (params: any, request?: InternalClientRequest): Promise<FhirFetcherResponse<T>> => {
+  protected fhirRequest<T = FhirResource>(
+    path: string,
+    method: string
+  ): {
+    (params: any, request: InternalClientRequest & { rawResponse: true }, requestMode?: FhirResponseMode): Promise<
+      RawFetcherResponse<T>
+    >;
+    (params: any, request?: InternalClientRequest, requestMode?: FhirResponseMode): Promise<T>;
+  } {
+    return async (params: any, request?: InternalClientRequest, requestMode?: FhirResponseMode): Promise<any> => {
       try {
         const baseUrlThunk = (): string => this.config.services?.fhirApiUrl ?? defaultFhirApiUrl;
         const configThunk = (): OystehrConfig => this.config;
         const loggerThunk = (): Logger => this.logger;
         // must await here to catch
-        return await fetcher(baseUrlThunk, configThunk, loggerThunk, path, method)(params, request);
+        return await fetcher(baseUrlThunk, configThunk, loggerThunk, path, method)(params, request, requestMode);
       } catch (err: unknown) {
         // FHIR API error messages are JSON strings
         const fullError = err as { message: string | Record<string, any>; code: number; cause?: unknown };
@@ -100,13 +126,170 @@ export class SDKResource {
       }
     };
   }
+
+  protected async startAsyncJob(
+    path: string,
+    method: string,
+    params: Record<string, unknown>,
+    requestMode: FhirResponseMode,
+    request?: InternalClientRequest
+  ): Promise<FhirAsyncJobHandle> {
+    const mode = requestMode === 'async-bulk' ? 'bulk' : 'bundle';
+    const asyncPath = requestMode === 'async-bulk' ? this.appendBulkOutputFormat(path) : path;
+
+    const raw = await this.fhirRequest(asyncPath, method)(
+      params,
+      {
+        ...request,
+        rawResponse: true,
+      },
+      requestMode
+    );
+
+    if (raw.status !== 202) {
+      throw new OystehrSdkError({
+        message: `Expected start async job to return 202 Accepted, received ${raw.status}`,
+        code: raw.status,
+      });
+    }
+
+    const contentLocation = this.readHeader(raw.headers, 'content-location');
+    if (!contentLocation) {
+      throw new OystehrSdkError({
+        message: 'Start Async job response missing Content-Location header',
+        code: 500,
+      });
+    }
+
+    const jobId = this.parseAsyncJobId(contentLocation);
+    if (!jobId) {
+      throw new OystehrSdkError({
+        message: `Could not parse async job id from Content-Location: ${contentLocation}`,
+        code: 500,
+      });
+    }
+
+    return { jobId, contentLocation, mode };
+  }
+
+  protected async fetchAsyncJobStatus<T extends FhirResource>(
+    jobId: string,
+    request?: OystehrClientRequest
+  ): Promise<FhirAsyncJobStatus<T>> {
+    const raw = await this.fhirRequest(`/async-job/${jobId}`, 'GET')(
+      {},
+      {
+        ...request,
+        rawResponse: true,
+      }
+    );
+
+    if (raw.status === 202) {
+      return {
+        status: 202,
+        xProgress: this.readHeader(raw.headers, 'x-progress'),
+        retryAfter: this.readHeader(raw.headers, 'retry-after'),
+      };
+    }
+
+    if (raw.status === 410) {
+      return { status: 410 };
+    }
+
+    if (raw.status === 404) {
+      return { status: 404 };
+    }
+
+    if (raw.status === 200) {
+      if (this.isBulkManifest(raw.body)) {
+        return {
+          status: 200,
+          mode: 'bulk',
+          manifest: raw.body,
+        };
+      }
+
+      const bundle = raw.body as FhirAsyncCompletionBundle<T>;
+      if (bundle?.resourceType === 'Bundle' && bundle?.type === 'batch-response') {
+        const entry0 = bundle.entry?.[0];
+        const interactionStatus = entry0?.response?.status;
+        const resource = entry0?.resource;
+        const outcome = entry0?.response?.outcome;
+        return {
+          status: 200,
+          mode: 'bundle',
+          bundle,
+          interactionStatus,
+          resource,
+          outcome,
+        };
+      }
+
+      return {
+        status: 200,
+        body: raw.body,
+      };
+    }
+
+    return {
+      status: raw.status,
+      body: raw.body,
+    };
+  }
+
+  private readHeader(headers: Record<string, string>, name: string): string | undefined {
+    const direct = headers[name];
+    if (direct != null) {
+      return direct;
+    }
+
+    const lower = name.toLowerCase();
+    const key = Object.keys(headers).find((h) => h.toLowerCase() === lower);
+    return key ? headers[key] : undefined;
+  }
+
+  private parseAsyncJobId(contentLocation: string): string | undefined {
+    const segments = contentLocation.split('/').filter(Boolean);
+    const asyncJobIndex = segments.lastIndexOf('async-job');
+    if (asyncJobIndex < 0 || asyncJobIndex + 1 >= segments.length) {
+      return undefined;
+    }
+
+    return segments[asyncJobIndex + 1];
+  }
+
+  private appendBulkOutputFormat(path: string): string {
+    const separator = path.includes('?') ? '&' : '?';
+    return `${path}${separator}_outputFormat=${encodeURIComponent('application/fhir+ndjson')}`;
+  }
+
+  private isBulkManifest(body: unknown): body is FhirAsyncBulkManifest {
+    if (body == null || typeof body !== 'object') {
+      return false;
+    }
+
+    const maybe = body as Record<string, unknown>;
+    return (
+      typeof maybe.transactionTime === 'string' &&
+      typeof maybe.request === 'string' &&
+      typeof maybe.requiresAccessToken === 'boolean' &&
+      Array.isArray(maybe.output) &&
+      Array.isArray(maybe.error)
+    );
+  }
 }
 
 export type FetcherError = { message: string; code: number };
 export type FetcherResponse = any;
+export type RawFetcherResponse<T = unknown> = {
+  status: number;
+  headers: Record<string, string>;
+  body: T | null;
+};
 export type FetcherFunction = (
   params?: Record<string, any> | [any] | InternalClientRequest,
-  request?: InternalClientRequest
+  request?: InternalClientRequest,
+  requestMode?: FhirResponseMode
 ) => Promise<FetcherResponse>;
 
 function isInternalClientRequest(request: Record<string, any>): request is InternalClientRequest {
@@ -115,10 +298,19 @@ function isInternalClientRequest(request: Record<string, any>): request is Inter
     ('projectId' in request && uuidValidate(request.projectId)) ||
     ('contentType' in request && request.contentType?.split('/').length === 2) ||
     'requestId' in request ||
-    ('ifMatch' in request && request.ifMatch.startsWith('W/"'))
+    ('ifMatch' in request && request.ifMatch.startsWith('W/"')) ||
+    'mode' in request ||
+    'rawResponse' in request
   );
 }
 
+function getPreferHeaderFromMode(mode: FhirResponseMode | undefined): string | undefined {
+  if (mode === 'async-bundle' || mode === 'async-bulk') {
+    return 'respond-async';
+  }
+  return undefined;
+}
+
 /**
  * Parse XML response in format <response><status>...</status><output>...</output></response>
  */
@@ -151,7 +343,8 @@ function fetcher(
 ): FetcherFunction {
   return async (
     params?: Record<string, unknown> | [any] | InternalClientRequest,
-    request?: InternalClientRequest
+    request?: InternalClientRequest,
+    requestMode?: FhirResponseMode
   ): Promise<FetcherResponse> => {
     // this function supports multiple signatures. fetcher(baseUrl, path, method)(params, request) or fetcher(baseUrl, path, method)(request)
     // or fetcher(baseUrl, path, method)(params) or fetcher(baseUrl, path, method)(). the types for this are handled by Client<Path, Methods>
@@ -214,6 +407,8 @@ function fetcher(
       requestId: requestCtx?.requestId,
     });
 
+    const preferHeader = getPreferHeaderFromMode(requestMode);
+
     const headers: Record<string, string> = Object.assign(
       projectId
         ? {
@@ -224,6 +419,7 @@ function fetcher(
       {
         'content-type': requestCtx?.contentType ?? 'application/json',
       },
+      preferHeader ? { Prefer: preferHeader } : {},
       accessToken ? { Authorization: `Bearer ${accessToken}` } : {},
       requestCtx?.ifMatch ? { 'If-Match': requestCtx.ifMatch } : {},
       { 'x-oystehr-request-id': requestCtx?.requestId }
@@ -301,6 +497,17 @@ function fetcher(
         url,
         requestId: requestCtx?.requestId,
       });
+      if (requestCtx?.rawResponse) {
+        const headersRecord: Record<string, string> = {};
+        response.headers.forEach((value, key) => {
+          headersRecord[key] = value;
+        });
+        return {
+          status: response.status,
+          headers: headersRecord,
+          body: responseJson ?? responseBody,
+        } as RawFetcherResponse;
+      }
       const isError = !response.ok || response.status >= 400;
       if (isError) {
         const errObj = {