@oystehr/sdk 4.3.2 → 4.3.4

package/src/client/client.ts

@@ -1,6 +1,7 @@
-import { v4 as uuidv4 } from 'uuid';
+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';
 
 type HttpMethod = 'get' | 'put' | 'post' | 'delete' | 'options' | 'head' | 'patch' | 'trace';
@@ -51,17 +52,24 @@ export type FhirFetcherResponse<T extends FhirData<FhirResource> = any> = T;
 
 export class SDKResource {
   protected readonly config: OystehrConfig;
+  protected readonly logger: Logger;
   constructor(config: OystehrConfig) {
     this.config = config;
+    this.logger = new Logger({
+      level: this.config.logLevel,
+    });
   }
 
   protected request(path: string, method: string, baseUrlThunk: () => string): FetcherFunction {
     return async (params: any, request?: InternalClientRequest): Promise<FetcherResponse> => {
       const configThunk = (): OystehrConfig => this.config;
+      const loggerThunk = (): Logger => this.logger;
       try {
-        return await fetcher(baseUrlThunk, configThunk, path, method)(params, request);
+        // must await here to catch
+        return await fetcher(baseUrlThunk, configThunk, loggerThunk, path, method)(params, request);
       } catch (err: any) {
         const error = err as { message: string; code: number; cause?: unknown };
+        this.logger.error(error.message, { code: error.code, cause: error.cause });
         throw new OystehrSdkError({ message: error.message, code: error.code, cause: error.cause });
       }
     };
@@ -72,8 +80,9 @@ export class SDKResource {
       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, path, method)(params, request);
+        return await fetcher(baseUrlThunk, configThunk, loggerThunk, path, method)(params, request);
       } catch (err: unknown) {
         // FHIR API error messages are JSON strings
         const fullError = err as { message: string | Record<string, any>; code: number; cause?: unknown };
@@ -101,7 +110,13 @@ export type FetcherFunction = (
 ) => Promise<FetcherResponse>;
 
 function isInternalClientRequest(request: Record<string, any>): request is InternalClientRequest {
-  return 'accessToken' in request;
+  return (
+    'accessToken' in request ||
+    ('projectId' in request && uuidValidate(request.projectId)) ||
+    ('contentType' in request && request.contentType?.split('/').length === 2) ||
+    'requestId' in request ||
+    ('ifMatch' in request && request.ifMatch.startsWith('W/"'))
+  );
 }
 
 /**
@@ -130,6 +145,7 @@ function parseXmlResponse(xmlString: string): Record<string, unknown> | null {
 function fetcher(
   baseUrlThunk: () => string,
   configThunk: () => OystehrConfig,
+  loggerThunk: () => Logger,
   path: string,
   methodParam: string
 ): FetcherFunction {
@@ -141,19 +157,21 @@ function fetcher(
     // or fetcher(baseUrl, path, method)(params) or fetcher(baseUrl, path, method)(). the types for this are handled by Client<Path, Methods>
     // and this is the backend implementation behind it. the heuristic we're using is that if the first param is an object with an accessToken
     // and there is no second param, assume the first one is the request object instead
-    const providedParams: Record<string, unknown> | [any] =
-      !!params && !request && !Array.isArray(params) && isInternalClientRequest(params)
-        ? {}
-        : (params as Record<string, unknown>) ?? {};
-    const requestCtx =
-      !!params && !request && !Array.isArray(params) && isInternalClientRequest(params)
-        ? (params as InternalClientRequest)
-        : request;
-    const method = methodParam.toLowerCase() as HttpMethod;
+    // eslint-disable-next-line prefer-const
+    let [providedParams, requestCtx] = extractParamsAndRequest(params, request);
+    requestCtx ??= {};
+    requestCtx.requestId ??= uuidv4();
     const config = configThunk();
+    const logger = loggerThunk();
+    const method = methodParam.toLowerCase() as HttpMethod;
+    logger.debug('Beginning fetch', {
+      method,
+      path,
+      requestId: requestCtx?.requestId,
+    });
     const fetchImpl = config.fetch ?? fetch;
     const accessToken = requestCtx?.accessToken ?? config.accessToken;
-    const projectId = requestCtx?.projectId ?? configThunk().projectId;
+    const projectId = requestCtx?.projectId ?? config.projectId;
     let finalPath = path;
     let finalParams = providedParams;
     if (!Array.isArray(providedParams)) {
@@ -161,6 +179,11 @@ function fetcher(
       finalPath = subbedPath;
       finalParams = addlParams;
     }
+    logger.debug('Substituted parameters in path', {
+      method,
+      path,
+      requestId: requestCtx?.requestId,
+    });
     finalPath = finalPath.replace(/^\//, ''); // remove leading slash
     const baseUrlEvaluated = baseUrlThunk();
     const fullBaseUrl = baseUrlEvaluated.endsWith('/') ? baseUrlEvaluated : baseUrlEvaluated + '/';
@@ -185,6 +208,11 @@ function fetcher(
         body = '{}';
       }
     }
+    logger.debug('Prepared request body', {
+      method,
+      path,
+      requestId: requestCtx?.requestId,
+    });
 
     const headers: Record<string, string> = Object.assign(
       projectId
@@ -198,7 +226,7 @@ function fetcher(
       },
       accessToken ? { Authorization: `Bearer ${accessToken}` } : {},
       requestCtx?.ifMatch ? { 'If-Match': requestCtx.ifMatch } : {},
-      { 'x-oystehr-request-id': requestCtx?.requestId ?? uuidv4() }
+      { 'x-oystehr-request-id': requestCtx?.requestId }
     );
     const retryConfig: ConstructedRetryConfig = {
       retries: config.retry?.retries ?? 3,
@@ -210,6 +238,12 @@ function fetcher(
     };
     retryConfig.retryOn.push(...STATUS_CODES_TO_RETRY);
     return retry(async () => {
+      logger.info('Request start', {
+        method,
+        url,
+        requestId: requestCtx?.requestId,
+      });
+      const now = Date.now();
       const response = await fetchImpl(
         new Request(url, {
           method: method.toUpperCase(),
@@ -217,6 +251,12 @@ function fetcher(
           headers,
         })
       );
+      logger.info('Request end', {
+        method,
+        url,
+        duration: Date.now() - now,
+        requestId: requestCtx?.requestId,
+      });
       const responseBody = response.body ? await response.text() : null;
       let responseJson: Record<string, unknown> | null;
       const contentType = response.headers.get('content-type');
@@ -225,10 +265,30 @@ function fetcher(
           responseBody &&
           (contentType?.includes('application/json') || contentType?.includes('application/fhir+json'))
         ) {
+          logger.time('Deserialized JSON response', {
+            method,
+            url,
+            requestId: requestCtx?.requestId,
+          });
           responseJson = JSON.parse(responseBody);
+          logger.timeEnd('Deserialized JSON response', {
+            method,
+            url,
+            requestId: requestCtx?.requestId,
+          });
         } else if (responseBody && (contentType?.includes('application/xml') || contentType?.includes('text/xml'))) {
           // Parse XML response into { status, output } structure
+          logger.time('Deserialized XML response', {
+            method,
+            url,
+            requestId: requestCtx?.requestId,
+          });
           responseJson = parseXmlResponse(responseBody);
+          logger.timeEnd('Deserialized XML response', {
+            method,
+            url,
+            requestId: requestCtx?.requestId,
+          });
         } else {
           responseJson = null;
         }
@@ -236,6 +296,11 @@ function fetcher(
         // ignore JSON.parse errors
         responseJson = null;
       }
+      logger.debug('Deserialized response', {
+        method,
+        url,
+        requestId: requestCtx?.requestId,
+      });
       const isError = !response.ok || response.status >= 400;
       if (isError) {
         const errObj = {
@@ -349,3 +414,18 @@ export function addParamsToSearch(params: Record<string, unknown>, search: URLSe
     search.append(key, value as string);
   }
 }
+
+export function extractParamsAndRequest(
+  params?: Record<string, unknown> | [any] | InternalClientRequest,
+  request?: InternalClientRequest
+): [Record<string, unknown>, InternalClientRequest | undefined] {
+  const providedParams: Record<string, unknown> | [any] =
+    !!params && !request && !Array.isArray(params) && isInternalClientRequest(params)
+      ? {}
+      : (params as Record<string, unknown>) ?? {};
+  const requestCtx =
+    !!params && !request && !Array.isArray(params) && isInternalClientRequest(params)
+      ? (params as InternalClientRequest)
+      : request;
+  return [providedParams, requestCtx];
+}

package/src/config.ts

@@ -1,3 +1,5 @@
+import type { Coding } from './resources/types/fhir';
+
 /**
  * Configuration for the Oystehr SDK client
  */
@@ -10,6 +12,10 @@ export interface OystehrConfig {
    * Optional Oystehr Project ID. Required for developer accessTokens.
    */
   projectId?: string;
+  /**
+   * Optional log level for the SDK logger. Possible values are 'error', 'info', and 'debug'.
+   */
+  logLevel?: 'error' | 'info' | 'debug';
   fhirApiUrl?: string;
   projectApiUrl?: string;
   services?: {
@@ -58,6 +64,20 @@ export interface OystehrConfig {
      */
     retryOn?: number[];
   };
+  /**
+   * Optional workspace tag configuration. When set, all FHIR searches will be
+   * filtered to only return resources with this tag, and all FHIR mutations
+   * (create, update, patch) will have this tag injected automatically.
+   * Mutually exclusive with `ignoreTags`.
+   */
+  workspaceTag?: Coding;
+  /**
+   * Optional list of tags to ignore. When set, all FHIR searches will be
+   * filtered to exclude resources matching any of these tags, and mutations
+   * will throw an error if the resource carries any of these tags.
+   * Mutually exclusive with `workspaceTag`.
+   */
+  ignoreTags?: Coding[];
 }
 
 let globalConfig: OystehrConfig;

package/src/logger.ts

@@ -0,0 +1,36 @@
+export class Logger {
+  _level?: 'error' | 'info' | 'debug';
+  constructor({ level }: { level?: 'error' | 'info' | 'debug' }) {
+    this._level = level;
+  }
+
+  error(message: string, extra: Record<string, any> = {}): void {
+    if (this._level && ['error', 'info', 'debug'].includes(this._level)) {
+      console.error(JSON.stringify({ message, ...extra }));
+    }
+  }
+
+  info(message: string, extra: Record<string, any> = {}): void {
+    if (this._level && ['info', 'debug'].includes(this._level)) {
+      console.info(JSON.stringify({ message, ...extra }));
+    }
+  }
+
+  debug(message: string, extra: Record<string, any> = {}): void {
+    if (this._level && ['debug'].includes(this._level)) {
+      console.debug(JSON.stringify({ message, ...extra }));
+    }
+  }
+
+  time(message: string, extra: Record<string, any> = {}): void {
+    if (this._level && ['debug'].includes(this._level)) {
+      console.time(JSON.stringify({ message, ...extra }));
+    }
+  }
+
+  timeEnd(message: string, extra: Record<string, any> = {}): void {
+    if (this._level && ['debug'].includes(this._level)) {
+      console.timeEnd(JSON.stringify({ message, ...extra }));
+    }
+  }
+}

package/src/resources/classes/erx.ts

@@ -15,6 +15,8 @@ import {
   ErxConnectPractitionerResponse,
   ErxEnrollPractitionerParams,
   ErxGetConfigurationResponse,
+  ErxGetMedicationHistoryParams,
+  ErxGetMedicationHistoryResponse,
   ErxGetMedicationParams,
   ErxGetMedicationResponse,
   ErxSearchAllergensParams,
@@ -135,6 +137,21 @@ export class Erx extends SDKResource {
       this.#baseUrlThunk.bind(this)
     )(params, request);
   }
+  /**
+   * Retrieve claims-based medication history for a patient. This endpoint requires the patient to be synced with the upstream eRx provider.
+   * Action: `eRx:GetMedicationHistory`
+   * Access Policy Resource: `eRx:Patient`
+   */
+  getMedicationHistory(
+    params: ErxGetMedicationHistoryParams,
+    request?: OystehrClientRequest
+  ): Promise<ErxGetMedicationHistoryResponse> {
+    return this.request(
+      '/patient/{patientId}/medication-history',
+      'get',
+      this.#baseUrlThunk.bind(this)
+    )(params, request);
+  }
   /**
    * Adds pharmacy for a patient with the upstream eRx provider, setting it as primary if specified.
    * Action: `eRx:AddPatientPharmacy`