emr-api-client/README.md

Api client for accessing openmrs service

# About
This client is based on [BHT-EMR-API](https://github.com/HISMalawi/BHT-EMR-API)

# Installation
```bash
npm i emr-api-client
```
# Usage

## Basic Example
```javascript
import { ApiCore } from "emr-api-client"
// Set custom host configuration. By default the system will use http://localhost:3000
ApiCore.setHost("https://hospitalwide.co")
// Condition runs a health check with provided host
if ((await ApiCore.apiOk())) {
    // Check if loggin session is present before accessing API resources
    if (!ApiCore.isLoggedIn()) {
        // Login with username and password respectively
        const authentication = await ApiCore.login("username12", "password123#")
        // Check status of the authentication before accessing api resource
        if (authentication.ok) {
            const patients = await ApiClient.getJson('patients')
            if (patients.ok) console.log(patients.data)
        }
    }
} else {
  alert("Invalid host")
}
```

## Error checking example
```javascript
import { ApiCore, ClientError } from "emr-api-client"

const sampleData = {
    first_name: "Test1",
    last_name: "Test1",
    gender: "Male"
}
// Post patient data
const request = await ApiCore.postJson("patient", sampleData)
// If the request is not ok, you can handle specific errors in your program
if (!request.ok) {
    switch(request.errorState) {
        case ClientError.AUTHENTICATION_ERROR:
            alert("You need to login")
            break;
        case ClientError.NO_CONNECTION:
            alert("Unable to reach the API")
        case ClientError.NOT_FOUND:
            alert("Invalid endpoint")
        default:
            alert("General Error")
    }
})
```

## Validating user role example
```javascript
import { ApiCore } from "emr-api-client"

// Login first using user account
const authentication = await ApiCore.login("admin", "test123")

// Validate if login was successful and check if the logged in user has 
// a super user role
if (authentication.ok && ApiCore.userHasRoles(['Superuser'])) {
    // Deletes a record in the api by some id
    ApiCore.void("encounter/1234")
        .then((res) => {
            if (res.ok) {
                alert("Encounter has been Deleted!!")
            } else {
                alert("Unable to delete because of " + res.errorState)
            }
        })
}
```

## Handling API responses globally example
```javascript
import { ApiCore, ClientError, JsonRequestResponse } from "maemr-api-client";
import ScreenLoader from "html-example";

/**
 * Intercept requests globally so that a loader is initiated before each request.
 * @param {Request} req - The request being sent.
 * @returns {Request} - The modified request.
 */
ApiCore.interceptRequest = (req) => {
    ScreenLoader.start();
    console.log(req.url, req.config) // Reading request data
    return req;
};

/**
 * Stop the screen loader once the request is complete and handle various error cases.
 * If an authentication error occurs, redirect users to the login page.
 * @param {JsonRequestResponse} res - The response received from the API.
 * @returns {JsonRequestResponse} - The modified response.
 */
ApiCore.interceptResponse = (res: JsonRequestResponse) => {
    ScreenLoader.stop();
    
    if (!res.ok) {
        if (res.errorState === ClientError.AUTHENTICATION_ERROR) {
            document.location = '/login';
        } else {
            // Handle other error cases here or log them.
        }
    }
    
    return res;
};
```

# Features
1. Authentication
2. Get, Post, Put and Delete functions provided
3. Gracefully handling http requests
4. Configurable Api host
5. DDE, User, location, Drug, lab, patient, person, user property and global property services built in