Oystehr
Core Documentation
TypeScript SDK
Migration Guide

Migration Guide

This page contains instructions on how to migrate to the latest version of the Oystehr SDK. When a new major version is released, we will add a new section, leaving the guides for older versions below.

Migrating to v4

The v4 version of the SDK includes a reorganization of the eRx module to prioritize the new eRx Service v3. The eRx Service v1 and eRx Service v2 functionality has been preserved in the erxV1 and erxV2 modules.

Continuing to use eRx Service v1 and v2 functionality

eRx Service v1 and v2 are deprecated. Please migrate to the new eRx Service v3 functions. eRx Service v1 and v2 functionality will be removed in a future release.

eRx Service v1

Use the new erxV1 module to access the v1 functionality.

import Oystehr from '@oystehr/sdk';
const oystehr = new Oystehr({
  accessToken: '<your_access_token>',
});
const medications = await oystehr.erxV1.medicationSearch({ name: 'acetaminophen' })

eRx Service v2

The eRx Service v2 medication search has moved to the erxV2 module.

import Oystehr from '@oystehr/sdk';
const oystehr = new Oystehr({
  accessToken: '<your_access_token>',
});
const medications = await oystehr.erxV2.medicationSearch({ name: 'acetaminophen' })

Transitioning to the new eRx Service

The new eRx Service v3 functionality is now available in the erx module. The new service has a broader array of functionality and ties into the SureScripts ePrescribing network.

Function names have been changed to be more accurate and consistent — for example, allergySearch is now searchAllergens.

There are a number of breaking changes in the new service, including:

Migrating to v3

The v3 version of the SDK offers a number of new features — explicit parameter and return types for all functions, automatic and configurable retries, and more.

This is also the first release under the @oystehr/sdk package.

Initialization and Use

Initialization has changed in v3 to use a single class instance. Pass your configuration to the constructor function and use the resulting instance as your entrypoint to all Oystehr services.

import { Patient } from 'fhir/r4b';
 
// v1
import { AppClient, FhirClient } from '@zapehr/sdk';
const fhirClient = new FhirClient({
  accessToken: '<your_access_token>',
});
const patient = await fhirClient.createResource<Patient>({ resourceType: 'Patient '});
const appClient = new AppClient({
  accessToken: '<your_access_token>',
});
const app = await appClient.getApplication('a7e25b8e-22fb-4ba2-ba9f-d0ec47825811');
 
// v2
import zapehr from '@zapehr/sdk';
zapehr.init({
  ZAPEHR_ACCESS_TOKEN: '<your_access_token>', // can also be provided from an environment variable
});
const patient = await zapehr.fhir.createResource<Patient>({ resourceType: 'Patient '});
const app = await zapehr.project.application.get('a7e25b8e-22fb-4ba2-ba9f-d0ec47825811');
 
// v3
import Oystehr from '@oystehr/sdk';
const oystehr = new Oystehr({
  accessToken: '<your_access_token>',
});
const patient = await oystehr.fhir.create<Patient>({ resourceType: 'Patient '});
const app = await oystehr.application.get('a7e25b8e-22fb-4ba2-ba9f-d0ec47825811');

Access to non-FHIR Services

The structure of the library has been flattened to remove the project layer.

// v2
import zapehr from '@zapehr/sdk';
zapehr.init({
  ZAPEHR_ACCESS_TOKEN: '<your_access_token>', // can also be provided from an environment variable
});
const app = await zapehr.project.application.get('a7e25b8e-22fb-4ba2-ba9f-d0ec47825811');
//                       ^ all non-FHIR services under `project`
 
// v3
import Oystehr from '@oystehr/sdk';
const oystehr = new Oystehr({
  accessToken: '<your_access_token>',
});
const app = await oystehr.application.get('a7e25b8e-22fb-4ba2-ba9f-d0ec47825811');
//                       ^ all non-FHIR services at top level

FHIR Search

The default return type for FHIR search has been changed to Bundle<FhirResource> to better match the FHIR search specification. Search has also been consolidated to a single method. An unbundle() helper has been added to provide access to an array of FhirResource.

// v3
import { Patient } from 'fhir/r4b';
import Oystehr from '@oystehr/sdk';
 
const oystehr = new Oystehr({
  accessToken: '<your_access_token>',
});
const bundle/*: Bundle<Patient>*/ = await oystehr.fhir.search<Patient>({
 
  resourceType: 'Patient',
  params: [
    {
      name: 'name:exact',
      value: 'Anna,Maria,Juanita',
    },
  ],
});
const patients/*: Patient[]*/ = bundle.unbundle();
 
const morePatients/*: Patient[]*/ = (await oystehr.fhir.search<Patient>({
  resourceType: 'Patient',
  params: [
    {
      name: 'name:exact',
      value: 'Anna,Maria,Juanita',
    },
  ],
})).unbundle();
TypeScript SDKWorking with Large Data