@oystehr/sdk 4.3.9 → 4.3.11

package/dist/esm/resources/classes/fhir-ext.d.ts

@@ -1,6 +1,6 @@
 import { Address as AddressR4B, HumanName as HumanNameR4B } from 'fhir/r4b';
 import { Address as AddressR5, HumanName as HumanNameR5 } from 'fhir/r5';
-import { BatchBundle, BatchInput, Bundle, FhirAsyncJobHandle, FhirAsyncJobStatus, FhirAsyncWaitOptions, FhirCreateParams, FhirDeleteParams, FhirGetParams, FhirHistoryGetParams, FhirHistorySearchParams, FhirPatchParams, FhirResource, FhirResourceReturnValue, FhirResponseMode, FhirSearchParams, FhirUpdateParams, GenerateFriendlyPatientIdParams, TransactionBundle } from '../..';
+import { BatchBundle, BatchInput, Bundle, FhirAsyncBulkOutputResult, FhirAsyncJobHandle, FhirAsyncJobStatus, FhirAsyncWaitOptions, FhirCreateParams, FhirDeleteParams, FhirGetParams, FhirHistoryGetParams, FhirHistorySearchParams, FhirPatchParams, FhirResource, FhirResourceReturnValue, FhirResponseMode, FhirSearchParams, FhirUpdateParams, GenerateFriendlyPatientIdParams, SearchParam, TransactionBundle } from '../..';
 import { FhirFetcherResponse, OystehrClientRequest, SDKResource } from '../../client/client';
 /**
  * Optional parameter that can be passed to the client methods. It allows
@@ -16,6 +16,26 @@ export interface OystehrFHIRUpdateClientRequest extends OystehrClientRequest {
      */
     optimisticLockingVersionId?: string;
 }
+/**
+ * Optional parameter that can be passed to the FHIR create method. In addition
+ * to the standard request options, it supports FHIR conditional create via the
+ * 'If-None-Exist' header.
+ */
+export interface OystehrFHIRCreateClientRequest extends OystehrClientRequest {
+    /**
+     * Perform a FHIR conditional create using the 'If-None-Exist' header. The value is a
+     * FHIR search query that identifies whether a matching resource already exists:
+     *   - if no resource matches, the resource is created as normal;
+     *   - if exactly one resource matches, no resource is created and the existing one is returned;
+     *   - if more than one resource matches, the request fails with a 412 Precondition Failed error.
+     *
+     * Accepts either a raw search query string (e.g. `'identifier=http://acme.org|1234'`) or an
+     * array of SearchParam objects (e.g. `[{ name: 'identifier', value: 'http://acme.org|1234' }]`).
+     *
+     * @see https://www.hl7.org/fhir/http.html#cond-update for the conditional create specification.
+     */
+    ifNoneExist?: string | SearchParam[];
+}
 /**
  * Performs a FHIR search and returns the results as a Bundle resource
  *
@@ -29,10 +49,24 @@ export declare function search<T extends FhirResource>(this: SDKResource, params
 export declare function search<T extends FhirResource>(this: SDKResource, params: FhirSearchParams<T>, request?: OystehrClientRequest & {
     mode?: 'sync' | undefined;
 }): Promise<FhirFetcherResponse<Bundle<T>>>;
-export declare function create<T extends FhirResource>(this: SDKResource, params: FhirCreateParams<T>, request: OystehrClientRequest & {
+/**
+ * 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 declare function searchAndGetAllPages<T extends FhirResource>(this: SDKResource, params: FhirSearchParams<T> & {
+    pageSize?: number;
+}, request?: OystehrClientRequest & {
+    mode?: 'sync' | undefined;
+}): Promise<Bundle<T>>;
+export declare function create<T extends FhirResource>(this: SDKResource, params: FhirCreateParams<T>, request: OystehrFHIRCreateClientRequest & {
     mode: Exclude<FhirResponseMode, 'sync'>;
 }): Promise<FhirAsyncJobHandle>;
-export declare function create<T extends FhirResource>(this: SDKResource, params: FhirCreateParams<T>, request?: OystehrClientRequest & {
+export declare function create<T extends FhirResource>(this: SDKResource, params: FhirCreateParams<T>, request?: OystehrFHIRCreateClientRequest & {
     mode?: 'sync' | undefined;
 }): Promise<FhirFetcherResponse<FhirResourceReturnValue<T>>>;
 export declare function get<T extends FhirResource>(this: SDKResource, { resourceType, id }: FhirGetParams<T>, request: OystehrClientRequest & {
@@ -60,8 +94,41 @@ declare function del<T extends FhirResource>(this: SDKResource, params: FhirDele
     mode?: 'sync' | undefined;
 }): Promise<FhirFetcherResponse<FhirResourceReturnValue<T>>>;
 export { del as delete };
+/**
+ *  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 declare function getAsyncJob<T extends FhirResource>(this: SDKResource, jobId: string, request?: OystehrClientRequest): Promise<FhirAsyncJobStatus<T>>;
+/**
+ *  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 declare function waitForAsyncJob<T extends FhirResource>(this: SDKResource, jobId: string, options?: FhirAsyncWaitOptions, request?: OystehrClientRequest): Promise<FhirAsyncJobStatus<T>>;
+/**
+ *  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 declare function waitForAsyncBulkOutput<T extends FhirResource>(this: SDKResource, jobId: string, options?: FhirAsyncWaitOptions, request?: OystehrClientRequest): Promise<FhirAsyncBulkOutputResult<T>>;
+/**
+ * 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 declare function waitForAsyncBulkBundle<T extends FhirResource>(this: SDKResource, jobId: string, options?: FhirAsyncWaitOptions, request?: OystehrClientRequest): Promise<Bundle<T>>;
 export declare function cancelAsyncJob(this: SDKResource, jobId: string, request?: OystehrClientRequest): Promise<void>;
 export declare function history<T extends FhirResource>(this: SDKResource, { resourceType, id }: FhirHistorySearchParams<T>, request: OystehrClientRequest & {
     mode: Exclude<FhirResponseMode, 'sync'>;

package/dist/esm/resources/classes/fhir-ext.js

@@ -193,6 +193,21 @@ function assertRetrievedResource(config, resource) {
         }
     }
 }
+/**
+ * Serializes an If-None-Exist value into a FHIR search query string. A raw string is
+ * returned unchanged; an array of SearchParam objects is encoded as a query string
+ * (e.g. "identifier=sys|123&active=true").
+ */
+function ifNoneExistToString(value) {
+    if (typeof value === 'string') {
+        return value;
+    }
+    const search = new URLSearchParams();
+    for (const param of value) {
+        search.append(param.name, String(param.value));
+    }
+    return search.toString();
+}
 function isAsyncRequestMode(mode) {
     return mode === 'async-bundle' || mode === 'async-bulk';
 }
@@ -229,14 +244,59 @@ async function search(params, request) {
     };
     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.
+ */
+async function searchAndGetAllPages(params, request) {
+    const { pageSize, ...searchParams } = params;
+    let firstPageParams = searchParams;
+    if (pageSize) {
+        const baseParams = (searchParams.params ?? []).filter((p) => p.name !== '_count') ?? [];
+        firstPageParams = { ...searchParams, params: [...baseParams, { name: '_count', value: pageSize }] };
+    }
+    const allEntries = [];
+    const typedSearch = (search);
+    // search returns Bundle, and fhirRequest in the while block returns FhirBundle
+    let currentBundle = 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;
+        if (entries) {
+            allEntries.push(...entries);
+        }
+        const nextLink = currentBundle.link?.find((link) => link.relation === 'next')?.url;
+        if (!nextLink) {
+            break;
+        }
+        currentBundle = await this.fhirRequest(nextLink, 'GET')({}, request);
+    }
+    return {
+        ...firstBundle,
+        entry: allEntries.length ? allEntries : undefined,
+        unbundle: function () {
+            return this.entry?.map((e) => e.resource).filter((r) => r !== undefined) ?? [];
+        },
+    };
+}
 async function create(params, request) {
     const tagged = applyTagToResource(this.config, params);
     const { resourceType } = tagged;
     const requestMode = request?.mode;
+    const ifNoneExistRequest = {
+        ...request,
+        ifNoneExist: request?.ifNoneExist !== undefined ? ifNoneExistToString(request.ifNoneExist) : undefined,
+    };
     if (isAsyncRequestMode(requestMode)) {
-        return await this.startAsyncJob(`/${resourceType}`, 'POST', tagged, requestMode, request);
+        return await this.startAsyncJob(`/${resourceType}`, 'POST', tagged, requestMode, ifNoneExistRequest);
     }
-    return await this.fhirRequest(`/${resourceType}`, 'POST')(tagged, request);
+    return await this.fhirRequest(`/${resourceType}`, 'POST')(tagged, ifNoneExistRequest);
 }
 async function get({ resourceType, id }, request) {
     const requestMode = request?.mode;
@@ -299,9 +359,24 @@ function getRetryDelayMs(retryAfter, fallbackMs) {
     }
     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
+ */
 async function getAsyncJob(jobId, request) {
     return await this.fetchAsyncJobStatus(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
+ */
 async function waitForAsyncJob(jobId, options, request) {
     // 5 seconds poll interval by default
     const pollIntervalMs = options?.pollIntervalMs ?? 5000;
@@ -323,6 +398,116 @@ async function waitForAsyncJob(jobId, options, request) {
         code: 408,
     });
 }
+function parseNdjsonResources(ndjson, sourceUrl) {
+    const resources = [];
+    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));
+        }
+        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
+ */
+async function waitForAsyncBulkOutput(jobId, options, request) {
+    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 = {};
+    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(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
+ */
+async function waitForAsyncBulkBundle(jobId, options, request) {
+    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 })),
+        unbundle: function () {
+            return this.entry?.map((entry) => entry.resource).filter((value) => value !== undefined) ?? [];
+        },
+    };
+    return bundle;
+}
 async function cancelAsyncJob(jobId, request) {
     await this.fhirRequest(`/async-job/${jobId}`, 'DELETE')({}, request);
 }
@@ -460,9 +645,13 @@ function batchInputRequestToBundleEntryItem(request, config) {
     // POST creates require a full resource
     if (method === 'POST' && 'resource' in request) {
         const resource = applyTagToResource(config, request.resource);
-        const { fullUrl } = request;
+        const { fullUrl, ifNoneExist } = request;
         return {
-            ...baseRequest,
+            request: {
+                ...baseRequest.request,
+                // Conditional create: only create the resource if no existing resource matches the query.
+                ifNoneExist: ifNoneExist !== undefined ? ifNoneExistToString(ifNoneExist) : undefined,
+            },
             resource: resource,
             fullUrl,
         };
@@ -608,5 +797,5 @@ function formatHumanName(name, options) {
     return builder.join(' ').trim();
 }
 
-export { batch, cancelAsyncJob, create, del as delete, formatAddress, formatHumanName, generateFriendlyPatientId, get, getAsyncJob, history, patch, search, transaction, update, waitForAsyncJob };
+export { batch, cancelAsyncJob, create, del as delete, formatAddress, formatHumanName, generateFriendlyPatientId, get, getAsyncJob, history, patch, search, searchAndGetAllPages, transaction, update, waitForAsyncBulkBundle, waitForAsyncBulkOutput, waitForAsyncJob };
 //# sourceMappingURL=fhir-ext.js.map