@oystehr/sdk 3.0.0

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

@@ -0,0 +1,158 @@
+export * from './fhir';
+export * from './Card';
+export * from './ChargeDetails';
+export * from './CardIdentifier';
+export * from './Project';
+export * from './ApplicationListItem';
+export * from './Application';
+export * from './RoleStub';
+export * from './RoleListItem';
+export * from './Role';
+export * from './ZambdaSchedule';
+export * from './ZambdaFunction';
+export * from './ZambdaExecuteResult';
+export * from './Secret';
+export * from './SecretListItem';
+export * from './UserListItem';
+export * from './User';
+export * from './DeveloperListItem';
+export * from './Developer';
+export * from './ClaimName';
+export * from './ClaimDate';
+export * from './ClaimDatePeriod';
+export * from './ClaimDateWithQualifier';
+export * from './ClaimAddress';
+export * from './ClaimId';
+export * from './ClaimCMS1500';
+export * from './M2mListItem';
+export * from './M2m';
+export * from './AccessPolicy';
+export * from './MessagingServiceInfo';
+export * from './ApplicationListResponse';
+export * from './ApplicationCreateParams';
+export * from './ApplicationCreateResponse';
+export * from './ApplicationGetParams';
+export * from './ApplicationGetResponse';
+export * from './ApplicationUpdateParams';
+export * from './ApplicationUpdateResponse';
+export * from './ApplicationDeleteParams';
+export * from './ApplicationRotateSecretParams';
+export * from './ApplicationRotateSecretResponse';
+export * from './ApplicationRevokeRefreshTokenParams';
+export * from './ApplicationRevokeRefreshTokenResponse';
+export * from './ApplicationRevokeAccessTokenParams';
+export * from './ApplicationRevokeAccessTokenResponse';
+export * from './DeveloperGetParams';
+export * from './DeveloperGetResponse';
+export * from './DeveloperUpdateParams';
+export * from './DeveloperUpdateResponse';
+export * from './DeveloperDeleteParams';
+export * from './DeveloperInviteParams';
+export * from './DeveloperInviteResponse';
+export * from './DeveloperListResponse';
+export * from './DeveloperListV2Params';
+export * from './DeveloperListV2Response';
+export * from './M2mListResponse';
+export * from './M2mCreateParams';
+export * from './M2mCreateResponse';
+export * from './M2mGetParams';
+export * from './M2mGetResponse';
+export * from './M2mUpdateParams';
+export * from './M2mUpdateResponse';
+export * from './M2mDeleteParams';
+export * from './M2mRotateSecretParams';
+export * from './M2mRotateSecretResponse';
+export * from './M2mListV2Params';
+export * from './M2mListV2Response';
+export * from './MessagingGetMessagingConfigResponse';
+export * from './ConversationCreateParams';
+export * from './ConversationCreateResponse';
+export * from './ConversationGetTokenResponse';
+export * from './ConversationAddParticipantParams';
+export * from './ConversationRemoveParticipantParams';
+export * from './ConversationMessageParams';
+export * from './TransactionalSMSSendParams';
+export * from './TransactionalSMSSendResponse';
+export * from './PaymentMethodSetUpParams';
+export * from './PaymentMethodSetUpResponse';
+export * from './PaymentMethodSetDefaultParams';
+export * from './PaymentMethodDeleteParams';
+export * from './PaymentMethodListParams';
+export * from './PaymentMethodListResponse';
+export * from './ChargeIssueParams';
+export * from './ChargeStatusParams';
+export * from './ChargeStatusResponse';
+export * from './ProjectGetResponse';
+export * from './ProjectUpdateParams';
+export * from './ProjectUpdateResponse';
+export * from './RcmEligibilityCheckParams';
+export * from './RcmEligibilityCheckResponse';
+export * from './RcmValidateProfessionalClaimParams';
+export * from './RcmValidateProfessionalClaimResponse';
+export * from './RcmSubmitProfessionalClaimParams';
+export * from './RcmSubmitProfessionalClaimResponse';
+export * from './ErxSyncPatientParams';
+export * from './ErxSyncPatientResponse';
+export * from './ErxAllergySearchParams';
+export * from './ErxAllergySearchResponse';
+export * from './ErxMedicationSearchParams';
+export * from './ErxMedicationSearchResponse';
+export * from './RoleListResponse';
+export * from './RoleCreateParams';
+export * from './RoleCreateResponse';
+export * from './RoleGetParams';
+export * from './RoleGetResponse';
+export * from './RoleUpdateParams';
+export * from './RoleUpdateResponse';
+export * from './RoleDeleteParams';
+export * from './SecretListResponse';
+export * from './SecretSetParams';
+export * from './SecretSetResponse';
+export * from './SecretGetParams';
+export * from './SecretGetResponse';
+export * from './SecretDeleteParams';
+export * from './TelemedCreateMeetingParams';
+export * from './TelemedCreateMeetingResponse';
+export * from './TelemedJoinMeetingParams';
+export * from './TelemedJoinMeetingResponse';
+export * from './UserMeResponse';
+export * from './UserGetParams';
+export * from './UserGetResponse';
+export * from './UserUpdateParams';
+export * from './UserUpdateResponse';
+export * from './UserDeleteParams';
+export * from './UserInviteParams';
+export * from './UserInviteResponse';
+export * from './UserListResponse';
+export * from './UserListV2Params';
+export * from './UserListV2Response';
+export * from './VersionGetResponse';
+export * from './Z3ListBucketsResponse';
+export * from './Z3CreateBucketParams';
+export * from './Z3CreateBucketResponse';
+export * from './Z3DeleteBucketParams';
+export * from './Z3ListObjectsParams';
+export * from './Z3ListObjectsResponse';
+export * from './Z3GetPresignedUrlParams';
+export * from './Z3GetPresignedUrlResponse';
+export * from './Z3DeleteObjectParams';
+export * from './ZambdaListResponse';
+export * from './ZambdaCreateParams';
+export * from './ZambdaCreateResponse';
+export * from './ZambdaGetParams';
+export * from './ZambdaGetResponse';
+export * from './ZambdaUpdateParams';
+export * from './ZambdaUpdateResponse';
+export * from './ZambdaDeleteParams';
+export * from './ZambdaExecuteParams';
+export * from './ZambdaExecuteResponse';
+export * from './ZambdaExecutePublicParams';
+export * from './ZambdaExecutePublicResponse';
+export * from './ZambdaLogStreamListParams';
+export * from './ZambdaLogStreamListResponse';
+export * from './ZambdaS3UploadParams';
+export * from './ZambdaS3UploadResponse';
+export * from './ZambdaLogStreamSearchParams';
+export * from './ZambdaLogStreamSearchResponse';
+export * from './ZambdaLogStreamGetParams';
+export * from './ZambdaLogStreamGetResponse';

package/dist/esm/tests/common.d.ts

@@ -0,0 +1,2 @@
+import { Pool } from 'pg';
+export declare function query<T>(queryFunc: (pool: Pool) => Promise<T>): Promise<T>;

package/dist/esm/tests/setup/constants.d.ts

@@ -0,0 +1,12 @@
+export declare const accessToken = "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IllhcGtmeERqb3FvVnR1YUtlcHllZyJ9.eyJpc3MiOiJodHRwczovL2Rldi1hdXRoLnphcGVoci5jb20vIiwic3ViIjoiYXV0aDB8NjQ4MjRmYTYxODY2YmVmY2NiNTU5NTY4IiwiYXVkIjpbImh0dHBzOi8vZGV2LmFwaS56YXBlaHIuY29tIiwiaHR0cHM6Ly96YXBlaHItZGV2LnVzLmF1dGgwLmNvbS91c2VyaW5mbyJdLCJpYXQiOjE2ODYyNjE2NzIsImV4cCI6MTY4NjM0ODA3MiwiYXpwIjoiZzNPV0xIb1dhUEhHWkRyd1lTYW5QdDBCcUp6ZXgzTnYiLCJzY29wZSI6Im9wZW5pZCBwcm9maWxlIGVtYWlsIn0.EBSaOYp5NMJ94GZyd9cg57QWnozlN-ua4XAO3iIrPal16yWOW-_TeVgj-1j-PwAhHaxW8QoTuojMXwhWVkNUwUw1AomxFubrvL98jm871VMZTXayQRGGlZHUsREmUDWpojGKAf0wAegEPC-kSw5KAc79V5SOrcVzhTmk5AMnR1aDzck9ZbXpTCPWWmyjyf4BiCb4N3zw3Zt3iQ0c5YDKvdMa_aAKiUZ9jaOw1TnQZ4tivKsn2uVfRGPZ5WFmj7B2MQTpzw4rokHtnSYtbKb-1h5wMxsdmzy_gKMYYaiPGqkJVt1twtjH9O1nZZMSDjGQI5B96TnrVjBFm6ow8jpBKg";
+export declare const projectId = "eb1306aa-fba5-416a-a2a4-6b69eca58d87";
+export declare const FHIR_API_URL = "http://localhost:3030/dev";
+export declare const PLATFORM_API_URL = "http://localhost:3031/dev";
+export declare const PROJECT_API_URL = "http://localhost:3032/dev";
+export declare const FHIR_VERSION: import("@zapehr/core").FhirVersion;
+export declare const config: {
+    accessToken: string;
+    projectId: string;
+    fhirApiUrl: string;
+    projectApiUrl: string;
+};

package/dist/esm/tests/setup/global.d.ts

@@ -0,0 +1 @@
+export default function registerUserAndProject(): Promise<void>;

package/dist/esm/tests/setup/per-test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@oystehr/sdk",
+  "version": "3.0.0",
+  "description": "Oystehr SDK",
+  "scripts": {
+    "lint": "eslint .",
+    "check-types": "tsc --noEmit",
+    "clean": "rimraf dist",
+    "build": "npm run clean && npm run rollup",
+    "rollup": "npm run rollup-cjs && npm run rollup-mjs",
+    "rollup-cjs": "node --max-old-space-size=8192 ../../node_modules/rollup/dist/bin/rollup --config rollup.config-cjs.mjs",
+    "rollup-mjs": "node --max-old-space-size=8192 ../../node_modules/rollup/dist/bin/rollup --config rollup.config-mjs.mjs",
+    "test": "jest \".*\\.ts\" --runInBand",
+    "parser": "ts-node debug-parser.ts",
+    "publish-to-npmjs": "npm run build && npm publish",
+    "publish-to-npmjs-next": "npm run build && npm publish --tag next",
+    "generate": "ts-node scripts/generate-sdk-v3 project src/resources"
+  },
+  "engines": {
+    "npm": ">=8.0.0",
+    "node": ">=18.0.0"
+  },
+  "author": "Oystehr <info@oystehr.com>",
+  "license": "MIT",
+  "main": "dist/cjs/index.cjs",
+  "module": "dist/esm/index.js",
+  "exports": {
+    "import": {
+      "types": "./dist/esm/index.d.ts",
+      "default": "./dist/esm/index.js"
+    },
+    "require": {
+      "types": "./dist/cjs/index.d.cts",
+      "default": "./dist/cjs/index.cjs"
+    }
+  },
+  "dependencies": {
+    "@types/fhir": "0.0.41",
+    "@types/node": "20.11.25",
+    "fast-json-patch": "3.1.1",
+    "uuid": "10.0.0"
+  },
+  "keywords": [
+    "oystehr",
+    "zapehr",
+    "zap",
+    "ehr ",
+    "medical",
+    "healthcare",
+    "headless",
+    "fhir",
+    "r4b",
+    "r4",
+    "r5",
+    "dstu2",
+    "stu3",
+    "hl7"
+  ]
+}

package/rollup.config-cjs.mjs

@@ -0,0 +1,49 @@
+import json from '@rollup/plugin-json';
+import resolve from '@rollup/plugin-node-resolve';
+import typescript from '@rollup/plugin-typescript';
+import { mkdirSync, writeFileSync } from 'fs';
+import terser from '@rollup/plugin-terser';
+import commonjs from '@rollup/plugin-commonjs';
+import externals from 'rollup-plugin-node-externals';
+
+const extensions = ['.ts', '.json'];
+
+const sourcemapPathTransform = (path) => path.replaceAll('\\', '/').replaceAll('../../../src', '../../src');
+
+export default [
+  {
+    // special entrypoint for commonjs default export syntax
+    input: 'src/index.cts',
+    output: [
+      {
+        file: 'dist/cjs/index.cjs',
+        format: 'cjs',
+        name: 'osytehr.sdk',
+        sourcemap: true,
+        sourcemapPathTransform,
+      },
+      {
+        file: 'dist/cjs/index.min.cjs',
+        format: 'cjs',
+        name: 'osytehr.sdk',
+        plugins: [terser()],
+        sourcemap: true,
+        sourcemapPathTransform,
+      },
+    ],
+    plugins: [
+      json(),
+      externals(),
+      typescript({ tsconfig: 'tsconfig.cjs.json', resolveJsonModule: true }),
+      commonjs(),
+      resolve({ extensions }),
+      {
+        buildEnd: () => {
+          mkdirSync('./dist/cjs', { recursive: true });
+          writeFileSync('./dist/cjs/package.json', '{"type": "commonjs"}');
+        },
+      },
+    ],
+    strictDeprecations: true,
+  },
+];

package/rollup.config-mjs.mjs

@@ -0,0 +1,49 @@
+import json from '@rollup/plugin-json';
+import resolve from '@rollup/plugin-node-resolve';
+import typescript from '@rollup/plugin-typescript';
+import { mkdirSync, writeFileSync } from 'fs';
+import terser from '@rollup/plugin-terser';
+import commonjs from '@rollup/plugin-commonjs';
+import externals from 'rollup-plugin-node-externals';
+
+const extensions = ['.ts', '.json'];
+
+const sourcemapPathTransform = (path) => path.replaceAll('\\', '/').replaceAll('../../../src', '../../src');
+
+export default [
+  {
+    input: 'src/index.ts',
+    output: [
+      {
+        dir: 'dist/esm',
+        format: 'esm',
+        preserveModules: true,
+        preserveModulesRoot: 'src',
+        sourcemap: true,
+        sourcemapPathTransform,
+      },
+      {
+        file: 'dist/esm/index.min.js',
+        format: 'esm',
+        plugins: [terser()],
+        sourcemap: true,
+        sourcemapPathTransform,
+      },
+    ],
+    plugins: [
+      json(),
+      externals(),
+      resolve({ extensions }),
+      typescript({ tsconfig: 'tsconfig.esm.json', resolveJsonModule: true }),
+      commonjs(),
+      {
+        buildEnd: () => {
+          mkdirSync('./dist/esm/node_modules/tslib', { recursive: true });
+          writeFileSync('./dist/esm/package.json', '{"type": "module"}');
+          writeFileSync('./dist/esm/node_modules/tslib/package.json', '{"type": "module"}');
+        },
+      },
+    ],
+    strictDeprecations: true,
+  },
+];

package/src/client/client.ts

@@ -0,0 +1,307 @@
+import { v4 as uuidv4 } from 'uuid';
+import { OystehrConfig } from '../config';
+import { OystehrFHIRError, OystehrSdkError } from '../errors';
+import { FhirBundle, FhirResource, OperationOutcome } from '../resources/types';
+
+type HttpMethod = 'get' | 'put' | 'post' | 'delete' | 'options' | 'head' | 'patch' | 'trace';
+const defaultProjectApiUrl = 'https://project-api.zapehr.com/v1';
+const defaultFhirApiUrl = 'https://fhir-api.zapehr.com';
+const STATUS_CODES_TO_RETRY = [408, 429, 500, 502, 503, 504];
+const ERROR_CODES_TO_RETRY = [
+  'ECONNRESET',
+  'ECONNREFUSED',
+  'EPIPE',
+  'ETIMEDOUT',
+  'UND_ERR_CONNECT_TIMEOUT',
+  'UND_ERR_HEADERS_TIMEOUT',
+  'UND_ERR_HEADERS_TIMEOUT',
+  'UND_ERR_SOCKET',
+];
+
+/**
+ * Optional parameter that can be passed to the client methods. It allows
+ * overriding the access token or project ID, and setting various headers,
+ * such as 'Content-Type'.
+ */
+export interface OystehrClientRequest {
+  /**
+   * The access token to use for the request. If not provided, the access token from `oystehr.init()` will be used.
+   */
+  accessToken?: string;
+  /**
+   * The project ID to use for the request. If not provided, the project ID from `oystehr.init()` will be used.
+   */
+  projectId?: string;
+  /**
+   * The value of the 'Content-Type' header to use for the request.
+   */
+  contentType?: string;
+  /**
+   * Unique identifier for this request.
+   */
+  requestId?: string;
+}
+
+interface InternalClientRequest extends OystehrClientRequest {
+  ifMatch?: string;
+}
+
+type FhirData<T extends FhirResource> = T | T[] | FhirBundle<T>;
+export type FhirFetcherResponse<T extends FhirData<FhirResource> = any> = T;
+
+export class SDKResource {
+  private readonly config: OystehrConfig;
+  constructor(config: OystehrConfig) {
+    this.config = config;
+  }
+
+  request(path: string, method: string): FetcherFunction {
+    return async (params: any, request?: InternalClientRequest): Promise<FetcherResponse> => {
+      const baseUrlThunk = (): string => this.config.projectApiUrl ?? defaultProjectApiUrl;
+      const configThunk = (): OystehrConfig => this.config;
+      try {
+        return await fetcher(baseUrlThunk, configThunk, path, method)(params, request);
+      } catch (err: any) {
+        const error = err as { message: string; code: number };
+        throw new OystehrSdkError({ message: error.message, code: error.code });
+      }
+    };
+  }
+
+  fhirRequest<T extends FhirResource = any>(path: string, method: string) {
+    return async (params: any, request?: InternalClientRequest): Promise<FhirFetcherResponse<T>> => {
+      try {
+        const baseUrlThunk = (): string => this.config.fhirApiUrl ?? defaultFhirApiUrl;
+        const configThunk = (): OystehrConfig => this.config;
+        // must await here to catch
+        return await fetcher(baseUrlThunk, configThunk, 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 };
+        if (typeof fullError.message === 'string') {
+          throw new OystehrSdkError({
+            message: fullError.message,
+            code: fullError.code,
+          });
+        }
+        throw new OystehrFHIRError({
+          error: fullError.message as OperationOutcome,
+          code: fullError.code,
+        });
+      }
+    };
+  }
+}
+
+export type FetcherError = { message: string; code: number };
+export type FetcherResponse = any;
+export type FetcherFunction = (
+  params?: Record<string, any> | [any] | InternalClientRequest,
+  request?: InternalClientRequest
+) => Promise<FetcherResponse>;
+
+function isInternalClientRequest(request: Record<string, any>): request is InternalClientRequest {
+  return 'accessToken' in request;
+}
+
+function fetcher(
+  baseUrlThunk: () => string,
+  configThunk: () => OystehrConfig,
+  path: string,
+  methodParam: string
+): FetcherFunction {
+  return async (
+    params?: Record<string, unknown> | [any] | InternalClientRequest,
+    request?: InternalClientRequest
+  ): 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>
+    // 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;
+    const config = configThunk();
+    const fetchImpl = config.fetch ?? fetch;
+    const accessToken = requestCtx?.accessToken ?? config.accessToken;
+    const projectId = requestCtx?.projectId ?? configThunk().projectId;
+    let finalPath = path;
+    let finalParams = providedParams;
+    if (!Array.isArray(providedParams)) {
+      const [subbedPath, addlParams] = subParamsInPath(path, providedParams);
+      finalPath = subbedPath;
+      finalParams = addlParams;
+    }
+    finalPath = finalPath.replace(/^\//, ''); // remove leading slash
+    const baseUrlEvaluated = baseUrlThunk();
+    const fullBaseUrl = baseUrlEvaluated.endsWith('/') ? baseUrlEvaluated : baseUrlEvaluated + '/';
+    const url = new URL(finalPath, fullBaseUrl);
+    let body: any;
+
+    if (Array.isArray(finalParams)) {
+      body = JSON.stringify(finalParams);
+    } else if (Object.keys(finalParams).length) {
+      if (method === 'get') {
+        addParamsToSearch(finalParams, url.searchParams);
+      } else if (requestCtx?.contentType === 'application/x-www-form-urlencoded') {
+        const search = new URLSearchParams();
+        addParamsToSearch(finalParams, search);
+        body = search.toString();
+      } else {
+        body = JSON.stringify(finalParams);
+      }
+    } else {
+      // override for rpc call
+      if (requestCtx?.contentType !== 'application/x-www-form-urlencoded' && method === 'post') {
+        body = '{}';
+      }
+    }
+
+    const headers: Record<string, string> = Object.assign(
+      projectId
+        ? {
+            'x-zapehr-project-id': projectId,
+            'x-oystehr-project-id': projectId,
+          }
+        : {},
+      {
+        'content-type': requestCtx?.contentType ?? 'application/json',
+      },
+      accessToken ? { Authorization: `Bearer ${accessToken}` } : {},
+      requestCtx?.ifMatch ? { 'If-Match': requestCtx.ifMatch } : {},
+      { 'x-oystehr-request-id': requestCtx?.requestId ?? uuidv4() }
+    );
+    const retryConfig: ConstructedRetryConfig = {
+      retries: config.retry?.retries ?? 3,
+      onRetry: config.retry?.onRetry,
+      // Using array instead of set because the length is too short for uniqueness to be important
+      retryOn: [...(config.retry?.retryOn ?? []), ...STATUS_CODES_TO_RETRY],
+    };
+    retryConfig.retryOn.push(...STATUS_CODES_TO_RETRY);
+    return retry(async (attempt) => {
+      const response = await fetchImpl(
+        new Request(url, {
+          method: method.toUpperCase(),
+          body,
+          headers,
+        })
+      );
+      const responseBody = response.body ? await response.text() : null;
+      let responseJson: Record<string, unknown> | null;
+      try {
+        responseJson =
+          responseBody &&
+          (response.headers.get('content-type')?.includes('application/json') ||
+            response.headers.get('content-type')?.includes('application/fhir+json'))
+            ? JSON.parse(responseBody)
+            : null;
+      } catch (err) {
+        // ignore JSON.parse errors
+        responseJson = null;
+      }
+      const isError = !response.ok || response.status >= 400;
+      if (isError) {
+        headers['x-oystehr-fetch-attempts'] = `${attempt}`;
+        const errObj = {
+          message: responseJson?.message ?? responseJson ?? responseBody ?? response.statusText,
+          code: responseJson?.code ?? response.status,
+          response,
+        };
+        throw errObj;
+      }
+      return responseJson;
+    }, retryConfig);
+  };
+}
+
+type ConstructedRetryConfig = Omit<NonNullable<OystehrConfig['retry']>, 'retryOn'> & {
+  retryOn: NonNullable<NonNullable<OystehrConfig['retry']>['retryOn']>;
+};
+async function retry<T>(work: (attempt: number) => Promise<T>, config: ConstructedRetryConfig): Promise<T> {
+  let lastErr;
+  for (const attempt of Array.from({ length: (config.retries ?? 0) + 1 }, (_, index) => index)) {
+    try {
+      return await work(attempt);
+    } catch (e: any) {
+      let isRetryable = false;
+      if ('response' in e) {
+        // error from API
+        const err = e as FetcherError;
+        isRetryable = config.retryOn.includes(err.code);
+        // Removes response
+        lastErr = { message: e.message, code: e.code };
+      } else {
+        lastErr = e;
+        // error from fetch
+        if ('code' in e && typeof e.code === 'string') {
+          const err = e as { code: string };
+          isRetryable = ERROR_CODES_TO_RETRY.includes(err.code);
+        }
+      }
+      if (!isRetryable) {
+        break;
+      }
+      if (config.onRetry && attempt !== (config.retries ?? 0)) {
+        config.onRetry(attempt + 1);
+      }
+    }
+  }
+  throw lastErr;
+}
+
+/**
+ * Substitutes params in a path and returns the path with params substituted and any unused params.
+ *
+ * Uses the property names in the params object to determine the param to substitute in the path.
+ *
+ * @param path JSON API resource URI
+ * @param params all params provided to the client method
+ * @returns resource URI with params substituted and any unused params
+ */
+function subParamsInPath(path: string, params: Record<string, unknown>): [string, Record<string, string>] {
+  const unusedParams = { ...params };
+  // capture everything of the form `{paramName}` and replace with the value of `params[paramName]`
+  const subbedPath = path.replace(/\{([^}]+)\}/g, (_, paramName) => {
+    delete unusedParams[paramName];
+    // override for path params that are paths, indicated by a `+` at the end
+    if (paramName.match(/^.*\+$/)) {
+      return params[paramName] + '';
+    }
+    // error if param value is empty
+    if (!params[paramName] || params[paramName] === '') {
+      throw new OystehrSdkError({ message: `Required path parameter is an empty string: ${paramName}`, code: 400 });
+    }
+    // encode search params
+    if (params[paramName]) {
+      return encodeURIComponent(params[paramName] + ''); // coerce to string
+    }
+    return '';
+  });
+
+  const unusedKeys = Object.keys(unusedParams);
+  const addlParams = unusedKeys.length
+    ? unusedKeys.reduce((acc, key) => ({ ...acc, [key]: unusedParams[key] }), {})
+    : {};
+  return [subbedPath, addlParams];
+}
+
+/**
+ * Adds params to a URLSearchParams object in such a way as to preserve array values.
+ * @param params params
+ * @param search URLSearchParams object
+ */
+export function addParamsToSearch(params: Record<string, unknown>, search: URLSearchParams): void {
+  for (const [key, value] of Object.entries(params)) {
+    if (Array.isArray(value)) {
+      value.forEach((v) => search.append(key, v as string));
+      continue;
+    }
+    search.append(key, value as string);
+  }
+}