@medplum/core 0.5.0 → 0.9.0

package/dist/types/client.d.ts

@@ -1,4 +1,5 @@
 import { Binary, Bundle, Project, ProjectMembership, Reference, Resource, UserConfiguration, ValueSet } from '@medplum/fhirtypes';
+import { Operation } from 'fast-json-patch';
 import { EventTarget } from './eventtarget';
 import { SearchRequest } from './search';
 import { IndexedStructureDefinition } from './types';
@@ -97,6 +98,54 @@ export interface TokenResponse {
     readonly project: Reference<Project>;
     readonly profile: Reference<ProfileResource>;
 }
+/**
+ * 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:
+ *
+ * ```typescript
+ * import { MedplumClient } from '@medplum/core';
+ * const medplum = new MedplumClient();
+ * ```
+ *
+ * Create a `Patient`:
+ *
+ * ```typescript
+ * const patient = await medplum.createResource({
+ *   resourceType: 'Patient',
+ *   name: [{
+ *     given: ['Alice'],
+ *     family: 'Smith'
+ *   }]
+ * });
+ * ```
+ *
+ * Read a `Patient` by ID:
+ *
+ * ```typescript
+ * const patient = await medplum.readResource('Patient', '123');
+ * console.log(patient.name[0].given[0]);
+ * ```
+ *
+ * Search for a `Patient` by name:
+ *
+ * ```typescript
+ * const bundle = await medplum.search('Patient?name=Alice');
+ * console.log(bundle.total);
+ * ```
+ *
+ */
 export declare class MedplumClient extends EventTarget {
     #private;
     constructor(options?: MedplumClientOptions);
@@ -104,10 +153,71 @@ export declare class MedplumClient extends EventTarget {
      * Clears all auth state including local storage and session storage.
      */
     clear(): void;
-    get(url: string): Promise<any>;
-    post(url: string, body: any, contentType?: string): Promise<any>;
-    put(url: string, body: any, contentType?: string): Promise<any>;
-    delete(url: string): Promise<any>;
+    /**
+     * 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.
+     *
+     * @param url The target URL.
+     * @param options Optional fetch options.
+     * @returns Promise to the response content.
+     */
+    get(url: string, options?: RequestInit): 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()`.
+     *
+     * @param url The target URL.
+     * @param body The content body. Strings and `File` objects are passed directly. Other objects are converted to JSON.
+     * @param contentType The content type to be included in the "Content-Type" header.
+     * @param options Optional fetch options.
+     * @returns Promise to the response content.
+     */
+    post(url: string, body: any, contentType?: string, options?: RequestInit): 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()`.
+     *
+     * @param url The target URL.
+     * @param body The content body. Strings and `File` objects are passed directly. Other objects are converted to JSON.
+     * @param contentType The content type to be included in the "Content-Type" header.
+     * @param options Optional fetch options.
+     * @returns Promise to the response content.
+     */
+    put(url: string, body: any, contentType?: string, options?: RequestInit): 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()`.
+     *
+     * @param url The target URL.
+     * @param operations Array of JSONPatch operations.
+     * @param options Optional fetch options.
+     * @returns Promise to the response content.
+     */
+    patch(url: string, operations: Operation[], options?: RequestInit): 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()`.
+     *
+     * @param url The target URL.
+     * @param options Optional fetch options.
+     * @returns Promise to the response content.
+     */
+    delete(url: string, options?: RequestInit): Promise<any>;
     /**
      * Tries to register a new user.
      * @param request The registration request.
@@ -155,10 +265,99 @@ export declare class MedplumClient extends EventTarget {
     fhirUrl(...path: string[]): string;
     /**
      * Sends a FHIR search request.
-     * @param search The search query.
+     *
+     * Example using a FHIR search string:
+     *
+     * ```typescript
+     * const bundle = await client.search('Patient?name=Alice');
+     * console.log(bundle);
+     * ```
+     *
+     * Example using a structured search:
+     *
+     * ```typescript
+     * const bundle = await client.search({
+     *   resourceType: 'Patient',
+     *   filters: [{
+     *     code: 'name',
+     *     operator: 'eq',
+     *     value: 'Alice',
+     *   }]
+     * });
+     * console.log(bundle);
+     * ```
+     *
+     * The return value is a FHIR bundle:
+     *
+     * ```json
+     * {
+     *    "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
+     *
+     * @param query The search query as either a string or a structured search object.
+     * @returns Promise to the search result bundle.
+     */
+    search<T extends Resource>(query: string | SearchRequest, options?: RequestInit): Promise<Bundle<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:
+     *
+     * ```typescript
+     * 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
+     *
+     * @param query The search query as either a string or a structured search object.
+     * @returns Promise to the search result bundle.
+     */
+    searchOne<T extends Resource>(query: string | SearchRequest, options?: RequestInit): Promise<T | undefined>;
+    /**
+     * 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:
+     *
+     * ```typescript
+     * 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
+     *
+     * @param query The search query as either a string or a structured search object.
      * @returns Promise to the search result bundle.
      */
-    search<T extends Resource>(search: SearchRequest): Promise<Bundle<T>>;
+    searchResources<T extends Resource>(query: string | SearchRequest, options?: RequestInit): Promise<T[]>;
     /**
      * Searches a ValueSet resource using the "expand" operation.
      * See: https://www.hl7.org/fhir/operation-valueset-expand.html
@@ -166,7 +365,7 @@ export declare class MedplumClient extends EventTarget {
      * @param filter The search string.
      * @returns Promise to expanded ValueSet.
      */
-    searchValueSet(system: string, filter: string): Promise<ValueSet>;
+    searchValueSet(system: string, filter: string, options?: RequestInit): Promise<ValueSet>;
     /**
      * Returns a cached resource if it is available.
      * @param resourceType The FHIR resource type.
@@ -181,9 +380,81 @@ export declare class MedplumClient extends EventTarget {
      * @returns The resource if it is available in the cache; undefined otherwise.
      */
     getCachedReference<T extends Resource>(reference: Reference<T>): T | undefined;
-    read<T extends Resource>(resourceType: string, id: string): Promise<T>;
+    /**
+     * Reads a resource by resource type and ID.
+     *
+     * Example:
+     *
+     * ```typescript
+     * 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
+     *
+     * @param resourceType The FHIR resource type.
+     * @param id The resource ID.
+     * @returns The resource if available; undefined otherwise.
+     */
+    readResource<T extends Resource>(resourceType: string, id: string): Promise<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:
+     *
+     * ```typescript
+     * 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
+     *
+     * @param resourceType The FHIR resource type.
+     * @param id The resource ID.
+     * @returns The resource if available; undefined otherwise.
+     */
     readCached<T extends Resource>(resourceType: string, id: string): Promise<T>;
+    /**
+     * Reads a resource by `Reference`.
+     *
+     * This is a convenience method for `readResource()` that accepts a `Reference` object.
+     *
+     * Example:
+     *
+     * ```typescript
+     * 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
+     *
+     * @param reference The FHIR reference object.
+     * @returns The resource if available; undefined otherwise.
+     */
     readReference<T extends Resource>(reference: Reference<T>): Promise<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:
+     *
+     * ```typescript
+     * 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
+     *
+     * @param reference The FHIR reference object.
+     * @returns The resource if available; undefined otherwise.
+     */
     readCachedReference<T extends Resource>(reference: Reference<T>): Promise<T>;
     /**
      * Returns a cached schema for a resource type.
@@ -200,16 +471,158 @@ export declare class MedplumClient extends EventTarget {
      * @returns Promise to a schema with the requested resource type.
      */
     requestSchema(resourceType: string): Promise<IndexedStructureDefinition>;
+    /**
+     * Reads resource history by resource type and ID.
+     *
+     * The return value is a bundle of all versions of the resource.
+     *
+     * Example:
+     *
+     * ```typescript
+     * 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
+     *
+     * @param resourceType The FHIR resource type.
+     * @param id The resource ID.
+     * @returns The resource if available; undefined otherwise.
+     */
     readHistory<T extends Resource>(resourceType: string, id: string): Promise<Bundle<T>>;
+    /**
+     * Reads a specific version of a resource by resource type, ID, and version ID.
+     *
+     * Example:
+     *
+     * ```typescript
+     * 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
+     *
+     * @param resourceType The FHIR resource type.
+     * @param id The resource ID.
+     * @returns The resource if available; undefined otherwise.
+     */
+    readVersion<T extends Resource>(resourceType: string, id: string, vid: string): Promise<T>;
     readPatientEverything(id: string): Promise<Bundle>;
-    create<T extends Resource>(resource: T): Promise<T>;
+    /**
+     * Creates a new FHIR resource.
+     *
+     * The return value is the newly created resource, including the ID and meta.
+     *
+     * Example:
+     *
+     * ```typescript
+     * 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
+     *
+     * @param resource The FHIR resource to create.
+     * @returns The result of the create operation.
+     */
+    createResource<T extends Resource>(resource: T): Promise<T>;
+    /**
+     * 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:
+     *
+     * ```typescript
+     * 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
+     *
+     * @param resource The FHIR resource to create.
+     * @returns The result of the create operation.
+     */
     createBinary(data: any, filename: string, contentType: string): Promise<Binary>;
-    update<T extends Resource>(resource: T): Promise<T>;
-    patch(resourceType: string, id: string, operations: any): Promise<any>;
+    /**
+     * Updates a FHIR resource.
+     *
+     * The return value is the updated resource, including the ID and meta.
+     *
+     * Example:
+     *
+     * ```typescript
+     * 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
+     *
+     * @param resource The FHIR resource to update.
+     * @returns The result of the update operation.
+     */
+    updateResource<T extends Resource>(resource: T): Promise<T>;
+    /**
+     * Updates a FHIR resource using JSONPatch operations.
+     *
+     * The return value is the updated resource, including the ID and meta.
+     *
+     * Example:
+     *
+     * ```typescript
+     * 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
+     *
+     * @param resourceType The FHIR resource type.
+     * @param id The resource ID.
+     * @param operations The JSONPatch operations.
+     * @returns The result of the patch operations.
+     */
+    patchResource<T extends Resource>(resourceType: string, id: string, operations: Operation[]): Promise<T>;
+    /**
+     * Deletes a FHIR resource by resource type and ID.
+     *
+     * Example:
+     *
+     * ```typescript
+     * await medplum.deleteResource('Patient', '123');
+     * ```
+     *
+     * See the FHIR "delete" operation for full details: https://www.hl7.org/fhir/http.html#delete
+     *
+     * @param resourceType The FHIR resource type.
+     * @param id The resource ID.
+     * @returns The result of the delete operation.
+     */
     deleteResource(resourceType: string, id: string): Promise<any>;
-    graphql(query: string): Promise<any>;
+    graphql(query: string, options?: RequestInit): Promise<any>;
     getActiveLogin(): LoginState | undefined;
     setActiveLogin(login: LoginState): Promise<void>;
+    setAccessToken(accessToken: string): void;
     getLogins(): LoginState[];
     isLoading(): boolean;
     getProfile(): ProfileResource | undefined;
@@ -220,11 +633,12 @@ export declare class MedplumClient extends EventTarget {
      * @param url The URL to request.
      * @returns Promise to the response body as a blob.
      */
-    download(url: string): Promise<Blob>;
+    download(url: string, options?: RequestInit): Promise<Blob>;
     /**
      * Processes an OAuth authorization code.
      * See: https://openid.net/specs/openid-connect-core-1_0.html#TokenRequest
      * @param code The authorization code received by URL parameter.
      */
     processCode(code: string): Promise<ProfileResource>;
+    clientCredentials(clientId: string, clientSecret: string): Promise<ProfileResource>;
 }

package/dist/types/index.d.ts

@@ -1,6 +1,7 @@
 export * from './client';
 export * from './format';
 export * from './outcomes';
+export * from './repo';
 export * from './search';
 export * from './searchparams';
 export * from './types';

package/dist/types/repo.d.ts

@@ -0,0 +1,116 @@
+import { Bundle, OperationOutcome, Reference, Resource } from '@medplum/fhirtypes';
+import { Operation } from 'fast-json-patch';
+import { MedplumClient } from './client';
+import { SearchRequest } from './search';
+/**
+ * The LegacyRepositoryResult type is a tuple of operation outcome and optional resource.
+ * @deprecated
+ */
+export declare type LegacyRepositoryResult<T extends Resource | undefined> = Promise<[OperationOutcome, T | undefined]>;
+/**
+ * The LegacyRepositoryClient is a supplementary API client that matches the legacy "Repository" API.
+ * The "Repository" API is deprecated and will be removed in a future release.
+ * This LegacyRepositoryClient is also deprecated and will be removed in a future release.
+ * @deprecated
+ */
+export declare class LegacyRepositoryClient {
+    #private;
+    constructor(client: MedplumClient);
+    /**
+     * Creates a resource.
+     *
+     * See: https://www.hl7.org/fhir/http.html#create
+     *
+     * @param resource The resource to create.
+     * @returns Operation outcome and the new resource.
+     * @deprecated
+     */
+    createResource<T extends Resource>(resource: T): LegacyRepositoryResult<T>;
+    /**
+     * Returns a resource.
+     *
+     * See: https://www.hl7.org/fhir/http.html#read
+     *
+     * @param resourceType The FHIR resource type.
+     * @param id The FHIR resource ID.
+     * @returns Operation outcome and a resource.
+     * @deprecated
+     */
+    readResource<T extends Resource>(resourceType: string, id: string): LegacyRepositoryResult<T>;
+    /**
+     * Returns a resource by FHIR reference.
+     *
+     * See: https://www.hl7.org/fhir/http.html#read
+     *
+     * @param reference The FHIR reference.
+     * @returns Operation outcome and a resource.
+     * @deprecated
+     */
+    readReference<T extends Resource>(reference: Reference<T>): LegacyRepositoryResult<T>;
+    /**
+     * Returns resource history.
+     *
+     * See: https://www.hl7.org/fhir/http.html#history
+     *
+     * @param resourceType The FHIR resource type.
+     * @param id The FHIR resource ID.
+     * @returns Operation outcome and a history bundle.
+     * @deprecated
+     */
+    readHistory<T extends Resource>(resourceType: string, id: string): LegacyRepositoryResult<Bundle<T>>;
+    /**
+     * Returns a resource version.
+     *
+     * See: https://www.hl7.org/fhir/http.html#vread
+     *
+     * @param resourceType The FHIR resource type.
+     * @param id The FHIR resource ID.
+     * @param vid The version ID.
+     * @returns Operation outcome and a resource.
+     * @deprecated
+     */
+    readVersion<T extends Resource>(resourceType: string, id: string, vid: string): LegacyRepositoryResult<T>;
+    /**
+     * Updates a resource.
+     *
+     * See: https://www.hl7.org/fhir/http.html#update
+     *
+     * @param resource The resource to update.
+     * @returns Operation outcome and the updated resource.
+     * @deprecated
+     */
+    updateResource<T extends Resource>(resource: T): LegacyRepositoryResult<T>;
+    /**
+     * Deletes a resource.
+     *
+     * See: https://www.hl7.org/fhir/http.html#delete
+     *
+     * @param resourceType The FHIR resource type.
+     * @param id The resource ID.
+     * @returns Operation outcome.
+     * @deprecated
+     */
+    deleteResource(resourceType: string, id: string): LegacyRepositoryResult<undefined>;
+    /**
+     * Patches a resource.
+     *
+     * See: https://www.hl7.org/fhir/http.html#patch
+     *
+     * @param resourceType The FHIR resource type.
+     * @param id The resource ID.
+     * @param patch Array of JSONPatch operations.
+     * @returns Operation outcome and the resource.
+     * @deprecated
+     */
+    patchResource(resourceType: string, id: string, patch: Operation[]): LegacyRepositoryResult<Resource>;
+    /**
+     * Searches for resources.
+     *
+     * See: https://www.hl7.org/fhir/http.html#search
+     *
+     * @param searchRequest The search request.
+     * @returns The search result bundle.
+     * @deprecated
+     */
+    search<T extends Resource>(query: SearchRequest | string): LegacyRepositoryResult<Bundle<T>>;
+}

package/dist/types/search.d.ts

@@ -1,12 +1,12 @@
 export interface SearchRequest {
     readonly resourceType: string;
-    readonly filters?: Filter[];
-    readonly sortRules?: SortRule[];
-    readonly page?: number;
-    readonly count?: number;
-    readonly fields?: string[];
-    readonly name?: string;
-    readonly total?: 'none' | 'estimate' | 'accurate';
+    filters?: Filter[];
+    sortRules?: SortRule[];
+    page?: number;
+    count?: number;
+    fields?: string[];
+    name?: string;
+    total?: 'none' | 'estimate' | 'accurate';
 }
 export interface Filter {
     code: string;
@@ -48,13 +48,10 @@ export declare enum Operator {
  *
  * See the FHIR search spec: http://hl7.org/fhir/r4/search.html
  *
- * @param location The URL to parse.
+ * @param url The URL to parse.
  * @returns Parsed search definition.
  */
-export declare function parseSearchDefinition(location: {
-    pathname: string;
-    search?: string;
-}): SearchRequest;
+export declare function parseSearchDefinition(url: string): SearchRequest;
 /**
  * Formats a search definition object into a query string.
  * Note: The return value does not include the resource type.

package/dist/types/utils.d.ts

@@ -44,6 +44,27 @@ export declare function getImageSrc(resource: Resource): string | undefined;
  * @returns A Date object.
  */
 export declare function getDateProperty(date: string | undefined): Date | undefined;
+/**
+ * Calculates the age in years from the birth date.
+ * @param birthDateStr The birth date or start date in ISO-8601 format YYYY-MM-DD.
+ * @param endDateStr Optional end date in ISO-8601 format YYYY-MM-DD. Default value is today.
+ * @returns The age in years, months, and days.
+ */
+export declare function calculateAge(birthDateStr: string, endDateStr?: string): {
+    years: number;
+    months: number;
+    days: number;
+};
+/**
+ * Calculates the age string for display using the age appropriate units.
+ * If the age is greater than or equal to 2 years, then the age is displayed in years.
+ * If the age is greater than or equal to 1 month, then the age is displayed in months.
+ * Otherwise, the age is displayed in days.
+ * @param birthDateStr The birth date or start date in ISO-8601 format YYYY-MM-DD.
+ * @param endDateStr Optional end date in ISO-8601 format YYYY-MM-DD. Default value is today.
+ * @returns The age string.
+ */
+export declare function calculateAgeString(birthDateStr: string, endDateStr?: string): string | undefined;
 /**
  * FHIR JSON stringify.
  * Removes properties with empty string values.