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 v3

The latest 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 SDK Oystehr Services