Class: MedplumClient
The MedplumClient class provides a client for the Medplum FHIR server.
The client can be used in the browser, in a NodeJS application, or in a Medplum Bot.
The client provides helpful methods for common operations such as: 1) Authenticating 2) Creating resources 2) Reading resources 3) Updating resources 5) Deleting resources 6) Searching 7) Making GraphQL queries
Here is a quick example of how to use the client:
import { MedplumClient } from '@medplum/core';
const medplum = new MedplumClient();
Create a Patient
:
const patient = await medplum.createResource({
resourceType: 'Patient',
name: [{
given: ['Alice'],
family: 'Smith'
}]
});
Read a Patient
by ID:
const patient = await medplum.readResource('Patient', '123');
console.log(patient.name[0].given[0]);
Search for a Patient
by name:
const bundle = await medplum.search('Patient?name=Alice');
console.log(bundle.total);
Hierarchy
EventTarget
↳
MedplumClient
Constructors
constructor
• new MedplumClient(options?
)
Parameters
Name | Type |
---|---|
options? | MedplumClientOptions |
Overrides
EventTarget.constructor
Defined in
packages/core/src/client.ts:233
Methods
addEventListener
▸ addEventListener(type
, callback
): void
Parameters
Name | Type |
---|---|
type | string |
callback | EventListener |
Returns
void
Inherited from
EventTarget.addEventListener
Defined in
packages/core/src/eventtarget.ts:19
clear
▸ clear(): void
Clears all auth state including local storage and session storage.
Returns
void
Defined in
packages/core/src/client.ts:269
clientCredentials
▸ clientCredentials(clientId
, clientSecret
): Promise
<ProfileResource
>
Parameters
Name | Type |
---|---|
clientId | string |
clientSecret | string |
Returns
Promise
<ProfileResource
>
Defined in
packages/core/src/client.ts:1380
createBinary
▸ createBinary(data
, filename
, contentType
): Promise
<Binary
>
Creates a FHIR Binary
resource with the provided data content.
The return value is the newly created resource, including the ID and meta.
The data
parameter can be a string or a File
object.
A File
object often comes from a <input type="file">
element.
Example:
const result = await medplum.createBinary(myFile, 'test.jpg', 'image/jpeg');
console.log(result.id);
See the FHIR "create" operation for full details: https://www.hl7.org/fhir/http.html#create
Parameters
Name | Type | Description |
---|---|---|
data | string | File | The binary data to upload. |
filename | undefined | string | Optional filename for the binary. |
contentType | string | Content type for the binary. |
Returns
Promise
<Binary
>
The result of the create operation.
Defined in
packages/core/src/client.ts:925
createPdf
▸ createPdf(docDefinition
, filename?
): Promise
<Binary
>
Creates a PDF as a FHIR Binary
resource based on pdfmake document definition.
The return value is the newly created resource, including the ID and meta.
The docDefinition
parameter is a pdfmake document definition.
Example:
const result = await medplum.createPdf({
content: ['Hello world']
});
console.log(result.id);
See the pdfmake document definition for full details: https://pdfmake.github.io/docs/0.1/document-definition-object/
Parameters
Name | Type | Description |
---|---|---|
docDefinition | Record <string , unknown > | The FHIR resource to create. |
filename? | string | - |
Returns
Promise
<Binary
>
The result of the create operation.
Defined in
packages/core/src/client.ts:954
createResource
▸ createResource<T
>(resource
): Promise
<T
>
Creates a new FHIR resource.
The return value is the newly created resource, including the ID and meta.
Example:
const result = await medplum.createResource({
resourceType: 'Patient',
name: [{
family: 'Smith',
given: ['John']
}]
});
console.log(result.id);
See the FHIR "create" operation for full details: https://www.hl7.org/fhir/http.html#create
Type parameters
Name | Type |
---|---|
T | extends Resource |
Parameters
Name | Type | Description |
---|---|---|
resource | T | The FHIR resource to create. |
Returns
Promise
<T
>
The result of the create operation.
Defined in
packages/core/src/client.ts:853
createResourceIfNoneExist
▸ createResourceIfNoneExist<T
>(resource
, query
): Promise
<T
>
Conditionally create a new FHIR resource only if some equivalent resource does not already exist on the server.
The return value is the existing resource or the newly created resource, including the ID and meta.
Example:
const result = await medplum.createResourceIfNoneExist(
'Patient?identifier=123',
{
resourceType: 'Patient',
identifier: [{
system: 'http://example.com/mrn',
value: '123'
}]
name: [{
family: 'Smith',
given: ['John']
}]
});
console.log(result.id);
This method is syntactic sugar for:
return searchOne(query) ?? createResource(resource);
The query parameter only contains the search parameters (what would be in the URL following the "?").
See the FHIR "conditional create" operation for full details: https://www.hl7.org/fhir/http.html#ccreate
Type parameters
Name | Type |
---|---|
T | extends Resource |
Parameters
Name | Type | Description |
---|---|---|
resource | T | The FHIR resource to create. |
query | string | The search query for an equivalent resource. |
Returns
Promise
<T
>
The result of the create operation.
Defined in
packages/core/src/client.ts:898
delete
▸ delete(url
, options?
): Promise
<any
>
Makes an HTTP DELETE request to the specified URL.
This is a lower level method for custom requests.
For common operations, we recommend using higher level methods
such as deleteResource()
.
Parameters
Name | Type | Description |
---|---|---|
url | string | The target URL. |
options | RequestInit | Optional fetch options. |
Returns
Promise
<any
>
Promise to the response content.
Defined in
packages/core/src/client.ts:380
deleteResource
▸ deleteResource(resourceType
, id
): Promise
<any
>
Deletes a FHIR resource by resource type and ID.
Example:
await medplum.deleteResource('Patient', '123');
See the FHIR "delete" operation for full details: https://www.hl7.org/fhir/http.html#delete
Parameters
Name | Type | Description |
---|---|---|
resourceType | string | The FHIR resource type. |
id | string | The resource ID. |
Returns
Promise
<any
>
The result of the delete operation.
Defined in
packages/core/src/client.ts:1038
dispatchEvent
▸ dispatchEvent(event
): boolean
Parameters
Name | Type |
---|---|
event | Event |
Returns
boolean
Inherited from
EventTarget.dispatchEvent
Defined in
packages/core/src/eventtarget.ts:39
download
▸ download(url
, options?
): Promise
<Blob
>
Downloads the URL as a blob.
Parameters
Name | Type | Description |
---|---|---|
url | string | The URL to request. |
options | RequestInit | - |
Returns
Promise
<Blob
>
Promise to the response body as a blob.
Defined in
packages/core/src/client.ts:1160
fhirUrl
▸ fhirUrl(...path
): string
Builds a FHIR URL from a collection of URL path components.
For example, buildUrl('/Patient', '123')
returns fhir/R4/Patient/123
.
Parameters
Name | Type | Description |
---|---|---|
...path | string [] | The path component of the URL. |
Returns
string
The well-formed FHIR URL.
Defined in
packages/core/src/client.ts:462
get
▸ get<T
>(url
, options?
): ReadablePromise
<T
>
Makes an HTTP GET request to the specified URL.
This is a lower level method for custom requests.
For common operations, we recommend using higher level methods
such as readResource()
, search()
, etc.
Type parameters
Name | Type |
---|---|
T | any |
Parameters
Name | Type | Description |
---|---|---|
url | string | The target URL. |
options | RequestInit | Optional fetch options. |
Returns
Promise to the response content.
Defined in
packages/core/src/client.ts:290
getActiveLogin
▸ getActiveLogin(): undefined
| LoginState
Returns
undefined
| LoginState
Defined in
packages/core/src/client.ts:1087
getCached
▸ getCached<T
>(resourceType
, id
): undefined
| T
Returns a cached resource if it is available.
Type parameters
Name | Type |
---|---|
T | extends Resource |
Parameters
Name | Type | Description |
---|---|---|
resourceType | string | The FHIR resource type. |
id | string | The FHIR resource ID. |
Returns
undefined
| T
The resource if it is available in the cache; undefined otherwise.
Defined in
packages/core/src/client.ts:604
getCachedReference
▸ getCachedReference<T
>(reference
): undefined
| T
Returns a cached resource if it is available.
Type parameters
Name | Type |
---|---|
T | extends Resource |
Parameters
Name | Type |
---|---|
reference | Reference <T > |
Returns
undefined
| T
The resource if it is available in the cache; undefined otherwise.
Defined in
packages/core/src/client.ts:615
getLogins
▸ getLogins(): LoginState
[]
Returns
Defined in
packages/core/src/client.ts:1110
getProfile
▸ getProfile(): undefined
| ProfileResource
Returns
undefined
| ProfileResource
Defined in
packages/core/src/client.ts:1140
getProfileAsync
▸ getProfileAsync(): Promise
<undefined
| ProfileResource
>
Returns
Promise
<undefined
| ProfileResource
>
Defined in
packages/core/src/client.ts:1144
getSchema
▸ getSchema(): IndexedStructureDefinition
Returns a cached schema for a resource type. If the schema is not cached, returns undefined. It is assumed that a client will call requestSchema before using this method.
Returns
The schema if immediately available, undefined otherwise.
Defined in
packages/core/src/client.ts:726
getUserConfiguration
▸ getUserConfiguration(): undefined
| UserConfiguration
Returns
undefined
| UserConfiguration
Defined in
packages/core/src/client.ts:1151
graphql
▸ graphql(query
, options?
): Promise
<any
>
Parameters
Name | Type |
---|---|
query | string |
options? | RequestInit |
Returns
Promise
<any
>
Defined in
packages/core/src/client.ts:1083
isLoading
▸ isLoading(): boolean
Returns
boolean
Defined in
packages/core/src/client.ts:1136
patch
▸ patch(url
, operations
, options?
): Promise
<any
>
Makes an HTTP PATCH request to the specified URL.
This is a lower level method for custom requests.
For common operations, we recommend using higher level methods
such as patchResource()
.
Parameters
Name | Type | Description |
---|---|---|
url | string | The target URL. |
operations | Operation [] | Array of JSONPatch operations. |
options | RequestInit | Optional fetch options. |
Returns
Promise
<any
>
Promise to the response content.
Defined in
packages/core/src/client.ts:362
patchResource
▸ patchResource<T
>(resourceType
, id
, operations
): Promise
<T
>
Updates a FHIR resource using JSONPatch operations.
The return value is the updated resource, including the ID and meta.
Example:
const result = await medplum.patchResource('Patient', '123', [
{op: 'replace', path: '/name/0/family', value: 'Smith'},
]);
console.log(result.meta.versionId);
See the FHIR "update" operation for full details: https://www.hl7.org/fhir/http.html#patch
See the JSONPatch specification for full details: https://tools.ietf.org/html/rfc6902
Type parameters
Name | Type |
---|---|
T | extends Resource |
Parameters
Name | Type | Description |
---|---|---|
resourceType | string | The FHIR resource type. |
id | string | The resource ID. |
operations | Operation [] | The JSONPatch operations. |
Returns
Promise
<T
>
The result of the patch operations.
Defined in
packages/core/src/client.ts:1019
post
▸ post(url
, body
, contentType?
, options?
): Promise
<any
>
Makes an HTTP POST request to the specified URL.
This is a lower level method for custom requests.
For common operations, we recommend using higher level methods
such as createResource()
.
Parameters
Name | Type | Description |
---|---|---|
url | string | The target URL. |
body | any | The content body. Strings and File objects are passed directly. Other objects are converted to JSON. |
contentType? | string | The content type to be included in the "Content-Type" header. |
options | RequestInit | Optional fetch options. |
Returns
Promise
<any
>
Promise to the response content.
Defined in
packages/core/src/client.ts:315
processCode
▸ processCode(code
): Promise
<ProfileResource
>
Processes an OAuth authorization code. See: https://openid.net/specs/openid-connect-core-1_0.html#TokenRequest
Parameters
Name | Type | Description |
---|---|---|
code | string | The authorization code received by URL parameter. |
Returns
Promise
<ProfileResource
>
Defined in
packages/core/src/client.ts:1330
put
▸ put(url
, body
, contentType?
, options?
): Promise
<any
>
Makes an HTTP PUT request to the specified URL.
This is a lower level method for custom requests.
For common operations, we recommend using higher level methods
such as updateResource()
.
Parameters
Name | Type | Description |
---|---|---|
url | string | The target URL. |
body | any | The content body. Strings and File objects are passed directly. Other objects are converted to JSON. |
contentType? | string | The content type to be included in the "Content-Type" header. |
options | RequestInit | Optional fetch options. |
Returns
Promise
<any
>
Promise to the response content.
Defined in
packages/core/src/client.ts:339
readCached
▸ readCached<T
>(resourceType
, id
): ReadablePromise
<T
>
Reads a resource by resource type and ID using the in-memory resource cache.
If the resource is not available in the cache, it will be read from the server.
Example:
const patient = await medplum.readCached('Patient', '123');
console.log(patient);
See the FHIR "read" operation for full details: https://www.hl7.org/fhir/http.html#read
Type parameters
Name | Type |
---|---|
T | extends Resource |
Parameters
Name | Type | Description |
---|---|---|
resourceType | string | The FHIR resource type. |
id | string | The resource ID. |
Returns
The resource if available; undefined otherwise.
Defined in
packages/core/src/client.ts:659
readCachedReference
▸ readCachedReference<T
>(reference
): ReadablePromise
<T
>
Reads a resource by Reference
using the in-memory resource cache.
This is a convenience method for readResource()
that accepts a Reference
object.
If the resource is not available in the cache, it will be read from the server.
Example:
const serviceRequest = await medplum.readResource('ServiceRequest', '123');
const patient = await medplum.readCachedReference(serviceRequest.subject);
console.log(patient);
See the FHIR "read" operation for full details: https://www.hl7.org/fhir/http.html#read
Type parameters
Name | Type |
---|---|
T | extends Resource |
Parameters
Name | Type | Description |
---|---|---|
reference | Reference <T > | The FHIR reference object. |
Returns
The resource if available; undefined otherwise.
Defined in
packages/core/src/client.ts:710
readHistory
▸ readHistory<T
>(resourceType
, id
): Promise
<Bundle
<T
>>
Reads resource history by resource type and ID.
The return value is a bundle of all versions of the resource.
Example:
const history = await medplum.readHistory('Patient', '123');
console.log(history);
See the FHIR "history" operation for full details: https://www.hl7.org/fhir/http.html#history
Type parameters
Name | Type |
---|---|
T | extends Resource |
Parameters
Name | Type | Description |
---|---|---|
resourceType | string | The FHIR resource type. |
id | string | The resource ID. |
Returns
Promise
<Bundle
<T
>>
The resource if available; undefined otherwise.
Defined in
packages/core/src/client.ts:802
readPatientEverything
▸ readPatientEverything(id
): Promise
<Bundle
<Resource
>>
Parameters
Name | Type |
---|---|
id | string |
Returns
Promise
<Bundle
<Resource
>>
Defined in
packages/core/src/client.ts:826
readReference
▸ readReference<T
>(reference
): ReadablePromise
<T
>
Reads a resource by Reference
.
This is a convenience method for readResource()
that accepts a Reference
object.
Example:
const serviceRequest = await medplum.readResource('ServiceRequest', '123');
const patient = await medplum.readReference(serviceRequest.subject);
console.log(patient);
See the FHIR "read" operation for full details: https://www.hl7.org/fhir/http.html#read
Type parameters
Name | Type |
---|---|
T | extends Resource |
Parameters
Name | Type | Description |
---|---|---|
reference | Reference <T > | The FHIR reference object. |
Returns
The resource if available; undefined otherwise.
Defined in
packages/core/src/client.ts:681
readResource
▸ readResource<T
>(resourceType
, id
): ReadablePromise
<T
>
Reads a resource by resource type and ID.
Example:
const patient = await medplum.readResource('Patient', '123');
console.log(patient);
See the FHIR "read" operation for full details: https://www.hl7.org/fhir/http.html#read
Type parameters
Name | Type |
---|---|
T | extends Resource |
Parameters
Name | Type | Description |
---|---|---|
resourceType | string | The FHIR resource type. |
id | string | The resource ID. |
Returns
The resource if available; undefined otherwise.
Defined in
packages/core/src/client.ts:637
readVersion
▸ readVersion<T
>(resourceType
, id
, vid
): Promise
<T
>
Reads a specific version of a resource by resource type, ID, and version ID.
Example:
const version = await medplum.readVersion('Patient', '123', '456');
console.log(version);
See the FHIR "vread" operation for full details: https://www.hl7.org/fhir/http.html#vread
Type parameters
Name | Type |
---|---|
T | extends Resource |
Parameters
Name | Type | Description |
---|---|---|
resourceType | string | The FHIR resource type. |
id | string | The resource ID. |
vid | string | - |
Returns
Promise
<T
>
The resource if available; undefined otherwise.
Defined in
packages/core/src/client.ts:822
register
▸ register(request
): Promise
<void
>
Tries to register a new user.
Parameters
Name | Type | Description |
---|---|---|
request | RegisterRequest | The registration request. |
Returns
Promise
<void
>
Promise to the authentication response.
Defined in
packages/core/src/client.ts:390
removeEventListeneer
▸ removeEventListeneer(type
, callback
): void
Parameters
Name | Type |
---|---|
type | string |
callback | EventListener |
Returns
void
Inherited from
EventTarget.removeEventListeneer
Defined in
packages/core/src/eventtarget.ts:26
requestSchema
▸ requestSchema(resourceType
): Promise
<IndexedStructureDefinition
>
Requests the schema for a resource type. If the schema is already cached, the promise is resolved immediately.
Parameters
Name | Type | Description |
---|---|---|
resourceType | string | The FHIR resource type. |
Returns
Promise
<IndexedStructureDefinition
>
Promise to a schema with the requested resource type.
Defined in
packages/core/src/client.ts:736
search
▸ search<T
>(query
, options?
): Promise
<Bundle
<T
>>
Sends a FHIR search request.
Example using a FHIR search string:
const bundle = await client.search('Patient?name=Alice');
console.log(bundle);
Example using a structured search:
const bundle = await client.search({
resourceType: 'Patient',
filters: [{
code: 'name',
operator: 'eq',
value: 'Alice',
}]
});
console.log(bundle);
The return value is a FHIR bundle:
{
"resourceType": "Bundle",
"type": "searchest",
"total": 1,
"entry": [
{
"resource": {
"resourceType": "Patient",
"name": [
{
"given": [
"George"
],
"family": "Washington"
}
],
}
}
]
}
See FHIR search for full details: https://www.hl7.org/fhir/search.html
Type parameters
Name | Type |
---|---|
T | extends Resource |
Parameters
Name | Type | Description |
---|---|---|
query | string | SearchRequest | The search query as either a string or a structured search object. |
options | RequestInit | - |
Returns
Promise
<Bundle
<T
>>
Promise to the search result bundle.
Defined in
packages/core/src/client.ts:522
searchOne
▸ searchOne<T
>(query
, options?
): Promise
<undefined
| T
>
Sends a FHIR search request for a single resource.
This is a convenience method for search()
that returns the first resource rather than a Bundle
.
Example using a FHIR search string:
const patient = await client.searchOne('Patient?identifier=123');
console.log(patient);
The return value is the resource, if available; otherwise, undefined.
See FHIR search for full details: https://www.hl7.org/fhir/search.html
Type parameters
Name | Type |
---|---|
T | extends Resource |
Parameters
Name | Type | Description |
---|---|---|
query | string | SearchRequest | The search query as either a string or a structured search object. |
options | RequestInit | - |
Returns
Promise
<undefined
| T
>
Promise to the search result bundle.
Defined in
packages/core/src/client.ts:548
searchResources
▸ searchResources<T
>(query
, options?
): Promise
<T
[]>
Sends a FHIR search request for an array of resources.
This is a convenience method for search()
that returns the resources as an array rather than a Bundle
.
Example using a FHIR search string:
const patients = await client.searchResources('Patient?name=Alice');
console.log(patients);
The return value is an array of resources.
See FHIR search for full details: https://www.hl7.org/fhir/search.html
Type parameters
Name | Type |
---|---|
T | extends Resource |
Parameters
Name | Type | Description |
---|---|---|
query | string | SearchRequest | The search query as either a string or a structured search object. |
options | RequestInit | - |
Returns
Promise
<T
[]>
Promise to the search result bundle.
Defined in
packages/core/src/client.ts:577
searchValueSet
▸ searchValueSet(system
, filter
, options?
): Promise
<ValueSet
>
Searches a ValueSet resource using the "expand" operation. See: https://www.hl7.org/fhir/operation-valueset-expand.html
Parameters
Name | Type | Description |
---|---|---|
system | string | The ValueSet system url. |
filter | string | The search string. |
options | RequestInit | - |
Returns
Promise
<ValueSet
>
Promise to expanded ValueSet.
Defined in
packages/core/src/client.ts:589
sendEmail
▸ sendEmail(email
): Promise
<OperationOutcome
>
Sends an email using the Medplum Email API.
Builds the email using nodemailer MailComposer.
Examples:
Send a simple text email:
await medplum.sendEmail({
to: 'alice@example.com',
cc: 'bob@example.com',
subject: 'Hello',
text: 'Hello Alice',
});
Send an email with a Binary
attachment:
await medplum.sendEmail({
to: 'alice@example.com',
subject: 'Email with attachment',
text: 'See the attached report',
attachments: [{
filename: 'report.pdf',
path: "Binary/" + binary.id
}]
});
See options here: https://nodemailer.com/extras/mailcomposer/
Parameters
Name | Type |
---|---|
email | Options |
Returns
Promise
<OperationOutcome
>
Promise to the operation outcome.
Defined in
packages/core/src/client.ts:1079
setAccessToken
▸ setAccessToken(accessToken
): void
Parameters
Name | Type |
---|---|
accessToken | string |
Returns
void
Defined in
packages/core/src/client.ts:1103
setActiveLogin
▸ setActiveLogin(login
): Promise
<void
>
Parameters
Name | Type |
---|---|
login | LoginState |
Returns
Promise
<void
>
Defined in
packages/core/src/client.ts:1091
signInWithRedirect
▸ signInWithRedirect(): undefined
| Promise
<void
| ProfileResource
>
Tries to sign in the user. Returns true if the user is signed in. This may result in navigating away to the sign in page.
Returns
undefined
| Promise
<void
| ProfileResource
>
Defined in
packages/core/src/client.ts:437
signOut
▸ signOut(): Promise
<void
>
Signs out locally. Does not invalidate tokens with the server.
Returns
Promise
<void
>
Defined in
packages/core/src/client.ts:427
signOutWithRedirect
▸ signOutWithRedirect(): void
Tries to sign out the user. See: https://docs.aws.amazon.com/cognito/latest/developerguide/logout-endpoint.html
Returns
void
Defined in
packages/core/src/client.ts:452
startGoogleLogin
▸ startGoogleLogin(googleResponse
): Promise
<LoginAuthenticationResponse
>
Tries to sign in with Google authentication. The response parameter is the result of a Google authentication. See: https://developers.google.com/identity/gsi/web/guides/handle-credential-responses-js-functions
Parameters
Name | Type | Description |
---|---|---|
googleResponse | GoogleCredentialResponse | The Google credential response. |
Returns
Promise
<LoginAuthenticationResponse
>
Promise to the authentication response.
Defined in
packages/core/src/client.ts:418
startLogin
▸ startLogin(loginRequest
): Promise
<LoginAuthenticationResponse
>
Initiates a user login flow.
Parameters
Name | Type | Description |
---|---|---|
loginRequest | LoginRequest | Login request including email and password. |
Returns
Promise
<LoginAuthenticationResponse
>
Promise to the authentication response.
Defined in
packages/core/src/client.ts:400
updateResource
▸ updateResource<T
>(resource
): Promise
<T
>
Updates a FHIR resource.
The return value is the updated resource, including the ID and meta.
Example:
const result = await medplum.updateResource({
resourceType: 'Patient',
id: '123',
name: [{
family: 'Smith',
given: ['John']
}]
});
console.log(result.meta.versionId);
See the FHIR "update" operation for full details: https://www.hl7.org/fhir/http.html#update
Type parameters
Name | Type |
---|---|
T | extends Resource |
Parameters
Name | Type | Description |
---|---|---|
resource | T | The FHIR resource to update. |
Returns
Promise
<T
>
The result of the update operation.