@health-samurai/aidbox-client 0.0.0-alpha.1 → 0.0.0-alpha.3

package/README.md

@@ -1,35 +1,214 @@
 # Typescript FHIR client
 
-A typescript client for interacting with a FHIR server.
+A TypeScript client for interacting with a FHIR server.
 
 ## Usage
 
 The client is created with the `makeClient` function:
 
 ```typescript
-const client = makeClient({ baseurl: "https://fhir-server.address" });
+const baseUrl = "https://fhir-server.address";
+const client = new AidboxClient(
+  baseUrl,
+  new BrowserAuthProvider(baseUrl),
+);
 ```
 
-This constructor accepts an additional `onResponse` option, which is a side-effect-only function, that recieves a copy of the Response from the server as is:
+## Documentation
+
+Documentation is generated automatically, and can be found [here](https://healthsamurai.github.io/aidbox-ts-sdk/aidbox-client/).
+
+## Type Generator
+
+This project is designed around the type generator that provides FHIR types based on the specified package.
+However, not all types are provided in the client itself, only the necessary ones, like `Bundle`, and `OperationOutcome`.
+If your application requires more types, use [atomic-ehr/codegen](https://github.com/atomic-ehr/codegen) to generate more types.
+
+For example, using `atomic-ehr/codegen`, we can generate and import an `Observation` type, and ensure that all fields are provided when creating a resource:
 
 ```typescript
-const client = makeClient({
-  baseurl: "https://fhir-server.address"
-  onResponse: (response: Response) => {
-    /* analyze Response, use throw to interrupt request early */
-  }
+import type { Observation } from "hl7-fhir-r4-core";
+
+client.create<Observation>({
+  resourceType: "Observation",
+  status: "final",
+  code: {
+    coding: [{
+      system: "http://loinc.org",
+      code: "59408-5",
+      display: "Blood pressure systolic & diastolic"
+    }],
+    text: "Blood pressure"
+  },
+  subject: {
+    reference: "Patient/pt-1"
+  },
+  effectiveDateTime: "2025-12-05T00:00:00Z",
+  valueString: "minimal"
+})
+```
+
+The default set of types in the client is based on FHIR R4 Core.
+If your application requires a different set of types, it is possible to override that through type parameters when creating a client:
+
+```typescript
+import type * as R5 from "hl7-fhir-r5-core";
+import type { User } from "@health-samurai/aidbox-client";
+
+const baseUrl = "https://fhir-server.address";
+
+const client = new AidboxClient<R5.Bundle, R5.OperationOutcome, User> (
+  baseUrl,
+  new BrowserAuthProvider(baseUrl),
+);
+```
+
+## [FHIR Interactions](https://hl7.org/fhir/http.html)
+
+This client provides a set of methods to work with a FHIR server in a more convenient way:
+
+- Instance Level Interaction
+  - `read` - Read the current state of the resource
+  - `vread` - Read the state of a specific version of the resource
+  - `update` - Update an existing resource by its id (or create it if it is new)
+  - `conditionalUpdate` - Update an existing resource based on some identification criteria (or create it if it is new).
+  - `patch` - Update an existing resource by posting a set of changes to it.
+  - `conditionalPatch` - Update an existing resource, based on some identification criteria, by posting a set of changes to it.
+  - `delete` - Delete a resource.
+  - `deleteHistory` - Delete all historical versions of a resource.
+  - `deleteHistoryVersion` - Delete a specific version of a resource.
+  - `history` - Retrieve the change history for a particular resource.
+- Type Level Interaction
+  - `create` - Create a new resource with a server assigned id
+  - `conditionalCreate` - Create a new resource with a server assigned id if an equivalent resource does not already exist.
+  - `search` - Search the resource type based on some filter criteria.
+  - `conditionalDelete` - Conditional delete a single or multiple resources based on some identification criteria.
+  - `history` - Retrieve the change history for a particular resource type.
+- Whole System Interaction
+  - `capabilities` - Get a capability statement for the system.
+  - `batch`/`transaction` - Perform multiple interactions (e.g., create, read, update, delete, patch, and/or [extended operations]) in a single interaction.
+  - `delete` - Conditional Delete across all resource types based on some filter criteria.
+  - `history` - Retrieve the change history for all resources.
+  - `search` - Search across all resource types based on some filter criteria.
+- Compartment Interaction
+  - `search` - Search resources associated with a specific compartment instance (see [Search Contexts](https://build.fhir.org/search.html#searchcontexts) and [Compartments](https://build.fhir.org/compartmentdefinition.html))
+- Operations Framework
+  - `operation` - Perform an operation as defined by an `OperationDefinition`.
+  - `validate` - Perform the Validate Operation.
+
+### Patient CRUD Example
+
+Here's an example of
+
+```typescript
+import { AidboxClient, BrowserAuthProvider } from "@health-samurai/aidbox-client";
+import type { Patient } from "hl7-fhir-r4-core";
+import { formatOperationOutcome } from "utils";
+
+const client = new AidboxClient(
+  "http://localhost:8080",
+  new BrowserAuthProvider("http://localhost:8080"),
+);
+
+// Create a new Patient resource
+const result = await client.create<Patient>({
+  type: "Patient",
+  resource: {
+    gender: "female",
+    resourceType: "Patient",
+  },
+});
+
+// Check if interaction was successful
+if (result.isErr())
+  throw Error(formatOperationOutcome(result.value.resource), {
+    cause: result.value.resource,
+  });
+
+const patient = result.value.resource;
+
+if (!patient.id)
+  throw Error(
+    "id is optional in FHIR, so we check it to satisfy the type checker",
+  );
+
+// Updating the patient
+
+patient.name = [
+  {
+    given: ["Jane"],
+    family: "Doe",
+  },
+];
+
+const updateResult = await client.update<Patient>({
+  id: patient.id,
+  type: "Patient",
+  resource: patient,
+});
+
+if (updateResult.isErr())
+  throw Error(formatOperationOutcome(updateResult.value.resource), {
+    cause: updateResult.value.resource,
+  });
+
+// Deleting the patient
+
+const deleteResult = await client.delete<Patient>({
+  id: patient.id,
+  type: "Patient",
 });
+
+if (deleteResult.isErr())
+  throw Error(formatOperationOutcome(deleteResult.value.resource), {
+    cause: deleteResult.value.resource,
+  });
+```
+
+### Return data format
+
+As seen in the example above, most methods return a `Result<T, E>` object.
+This object represents a successful or erroneous state of the response.
+
+A general usage pattern is as follows:
+
+```typescript
+const result = await client.read<Patient>({ type: 'Patient', id: 'patient-id' });
+
+if (result.isErr())
+  throw new Error("error reading Patient", { cause: result.value.resource })
+
+const patient = result.value.resource;
+
+// work with patient.
+```
+
+It is also possible to work with resources without unwrapping the `Result` object:
+
+```typescript
+const result = await client.read<Patient>({ type: 'Patient', id: 'patient-id' });
+
+return result
+  .map(({resource}: {resource: Patient}): Patient => {
+  /* work with Patient resource */
+  })
+  .mapErr(({resource}: {resource: OperationOutcome}): OperationOutcome => {
+  /* work with OperationOutcome resource */
+  });
+  // result is still Result<Patient, OperationOutcome>
 ```
 
-## Methods
+See the [documentation](https://healthsamurai.github.io/aidbox-ts-sdk/aidbox-client/) for more info.
 
-The client provides two basic methods of interaction:
+## Low-level methods
 
-- `rawRequest` - send request to the FHIR server and recieve response in a raw format
-- `request<T>` - send request to the FHIR server and recieve response with its body parsed to the specified type `T`
+The client provides two basic methods for writing custom interactions:
 
-In successful case, the `rawRequest` returns an object with JavaScript Repsonse, and additional meta information.
-When server responds with an error code, this function throws an error:
+- `rawRequest` - send request to the FHIR server and receive response in a raw format
+- `request<T>` - send request to the FHIR server and receive response with its body parsed to the specified type `T`
+
+In a successful case, the `rawRequest` returns an object with JavaScript Response and additional meta information.
+When the server responds with an error code, this function throws an error:
 
 ```typescript
 const result = await client.rawRequest({
@@ -40,7 +219,7 @@ const result = await client.rawRequest({
 }).then((result) => {
   const patient: Patient = await result.response.json();
   // ...
-}).catch ((error) => {
+}).catch((error) => {
   if (error instanceof ErrorResponse) {
     const outcome = await error.responseWithMeta.response.json
     // ...
@@ -48,7 +227,7 @@ const result = await client.rawRequest({
 });
 ```
 
-Alternatively, a `request` method can be used.
+Alternatively, the `request` method can be used.
 It returns a `Result<T, OperationOutcome>`, which contains an already parsed result, coerced to the specified type `T`.
 
 ```typescript
@@ -65,73 +244,53 @@ if (result.isOk()) {
 }
 
 if (result.isErr()) {
-  const outcome: OperationOutcome = result.error.resource;
+  const outcome: OperationOutcome = result.value.resource;
   // process OperationOutcome
 }
 ```
 
-Both methods can throw `RequestError` class, if the error happened before the request was actually made.
-
-### [FHIR HTTP](https://hl7.org/fhir/http.html) methods:
-
-Additional set of methods is provided to work with FHIR server in a more convinient way:
-
-- [x] Instance Level Interaction
-  - [x] `read` - Read the current state of the resource
-  - [x] `vread` - Read the state of a specific version of the resource
-  - [x] `update` - Update an existing resource by its id (or create it if it is new)
-  - [x] `conditionalUpdate` - Update an existing resource based on some identification criteria (or create it if it is new)
-  - [x] `patch` - Update an existing resource by posting a set of changes to it
-  - [x] `conditionalPatch` - Update an existing resource, based on some identification criteria, by posting a set of changes to it
-  - [x] `delete` - Delete a resource
-  - [x] `deleteHistory` - Delete all historical versions of a resource
-  - [x] `deleteHistoryVersion` - Delete a specific version of a resource
-  - [x] `history` - Retrieve the change history for a particular resource
-- [x] Type Level Interaction
-  - [x] `create` - Create a new resource with a server assigned id
-  - [x] `conditionalCreate` - Create a new resource with a server assigned id if an equivalent resource does not already exist
-  - [x] `search` - Search the resource type based on some filter criteria
-  - [x] `conditionalDelete` - Conditional delete a single or multiple resources based on some identification criteria
-  - [x] `history` - Retrieve the change history for a particular resource type
-- [x] Whole System Interaction
-  - [x] `capabilities` - Get a capability statement for the system
-  - [x] `batch`/`transaction` - Perform multiple interactions (e.g., create, read, update, delete, patch, and/or [extended operations]) in a single interaction
-  - [x] `delete` - Conditional Delete across all resource types based on some filter criteria
-  - [x] `history` - Retrieve the change history for all resources
-  - [x] `search` - Search across all resource types based on some filter criteria
-- [x] Compartment Interaction
-  - [x] `search` - Search resources associated with a specific compartment instance (see [Search Contexts](https://build.fhir.org/search.html#searchcontexts) and [Compartments](https://build.fhir.org/compartmentdefinition.html))
-
-<!--
-TODO: Operations
-https://build.fhir.org/operations.html
--->
-
-## Return data format
-
-Most client methods return a `Result<T, E>` object, with methods to check if the request was successful:
+Both methods can throw the `RequestError` class if the error happened before the request was actually made.
 
-```typescript
-const result = await client.read<Patient>({type: 'Patient', id: 'patient-id'});
-if (result.isErr())
-    throw new Error("error reading Patient", { cause: result.error })
+## Authentication Providers
 
-const { resource: patient } = result.value;
+Authentication is managed via the `AuthProvider` interface.
 
-// work with patient.
-```
+Currently, the client only provides a `BrowserAuthProvider` class.
+It is suitable for usage in browsers, but other environments may require a different method.
 
-Unwrapping is not required to modify the data in the result:
+Thus, an application can describe its own Auth Provider by implementing a class that implements `AuthProvider`:
 
 ```typescript
-const result = await client.read<Patient>({type: 'Patient', id: 'patient-id'});
+import type { AuthProvider } from "@health-samurai/aidbox-client";
 
-return result
-  .map(({resource}: {resource: Patient}): Patient => {
-    /* work with Patient resource */
-  })
-  .mapErr(({resource}: {resource: OperationOutcome}): OperationOutcome => {
-    /* work with OperationOutcome resource */
-  });
-  // result is still Result<Patient, OperationOutcome>
+export class CustomAuthProvider implements AuthProvider {
+  public baseUrl: string;
+
+  constructor(baseUrl: string) {
+	this.baseUrl = baseUrl;
+  }
+
+  public async establishSession() {
+	/* code to establish a session */
+  }
+
+  public async revokeSession() {
+	/* code to revoke the session */
+  }
+
+  public async fetch(
+	input: RequestInfo | URL,
+	init?: RequestInit,
+  ): Promise<Response> {
+	/**
+     * A wrapper around the `fetch` function, that does all the
+     * necessary preparations and argument patching required for the
+     * request to go through.
+     *
+     * Optionally, security checks can be implemented, like verifying
+     * that the request indeed goes to the `baseUrl`, and not
+     * somewhere else.
+     */
+  }
+}
 ```

package/dist/src/auth-providers.d.ts

@@ -0,0 +1,23 @@
+import type { AuthProvider } from "./types";
+export declare class BrowserAuthProvider implements AuthProvider {
+    #private;
+    /** @ignore */
+    baseUrl: string;
+    constructor(baseUrl: string);
+    /**
+     * Checks if the session is already authenticated, and if not, redirects to the login page.
+     */
+    establishSession(): Promise<void>;
+    /**
+     * Sends a POST request to `baseurl/auth/logout`.
+     */
+    revokeSession(): Promise<void>;
+    /**
+     * A thin wrapper around `fetch` function.
+     * Checks if the client is authorized to perform a request, and redirects to a login page if not.
+     *
+     * Accepts the same arguments as `fetch`.
+     */
+    fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+}
+//# sourceMappingURL=auth-providers.d.ts.map

package/dist/src/auth-providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-providers.d.ts","sourceRoot":"","sources":["../../src/auth-providers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C,qBAAa,mBAAoB,YAAW,YAAY;;IACvD,cAAc;IACP,OAAO,EAAE,MAAM,CAAC;gBAEX,OAAO,EAAE,MAAM;IAgB3B;;OAEG;IACU,gBAAgB;IAQ7B;;OAEG;IACU,aAAa;IAW1B;;;;;OAKG;IACU,KAAK,CACjB,KAAK,EAAE,WAAW,GAAG,GAAG,EACxB,IAAI,CAAC,EAAE,WAAW,GAChB,OAAO,CAAC,QAAQ,CAAC;CAsBpB"}