> ## Documentation Index
> Fetch the complete documentation index at: https://developer.eka.care/llms.txt
> Use this file to discover all available pages before exploring further.

# Trinity Profiles SDK (TypeScript)

> Type-safe SDK for managing patient profiles through the Trinity API.

## Installation

```bash theme={null}
npm install @eka-care/patient-ts-sdk
```

Or, if using source:

```bash theme={null}
cd trinity-profiles-sdk
npm install
```

You can find the package on [npm](https://www.npmjs.com/package/@eka-care/patient-ts-sdk).

***

## Quick Start

```ts theme={null}
import { TrinityProfilesSDK } from '@eka-care/patient-ts-sdk';

// Initialize SDK
const sdk = new TrinityProfilesSDK({
  baseUrl: 'https://your-trinity-api.com',
  accessToken: 'your-jwt-token',
  workspaceId: 'your-workspace-id',
  enableLocalSearch: true, // optional
  timeout: 30000 // optional, defaults to 30s
});

 /* 
    enableLocalSearch: true enables local storage of patient data in IndexedDB.
    Searches are performed locally for fast, offline-capable results. If local data
    is unavailable or local search fails, the SDK automatically falls back to the API.
    Using IndexedDB is recommended for optimal performance.
 */

// Initialize local search (optional)
await sdk.initializeLocalSearch();

// Start background sync
await sdk.startLocalSync({
  onProgress: (p, total) => console.log(`Synced ${p}/${total}`),
  onComplete: () => console.log('Sync complete!'),
  onError: (err) => console.error('Sync failed:', err)
});
```

***

## Patient Operations

### Create Patient

#### Required Fields

* `oid` – Unique identifier
* `wid` – Workspace ID
* `gen` – Gender (`M` | `F` | `O`)
* `dob` – Date of birth (`YYYY-MM-DD`)
* At least one name field (`fn`, `mn`, `ln`, or `fln`)

**Other available fields:**\
You can include any of the following fields while creating a patient profile:

* `s`  Salutation
* `mobile` – Mobile number (digits only)
* `ccd` – Country code (e.g., "+91")
* `email` – Email address
* `username` – Username
* `bg` – Blood group
* `abha` – ABHA address
* `is_age` - Field to indicate whether dob was derived from age
  ​

#### Example Request

```ts theme={null}
const patient = await sdk.patients.create({
  oid: 'unique-patient-id',
  gen: 'M',
  dob: '1990-01-01',
  fn: 'John',
  ln: 'Doe',
  mobile: '1234567890',
  ccd: '+1',
  email: 'john@example.com'
});
```

#### Sample Response

```json theme={null}
{
  "oid": "unique-patient-id",
  "wid": "workspace-id",
  "gen": "M",
  "dob": "1990-01-01",
  "fn": "John",
  "ln": "Doe",
  "mobile": "1234567890",
  "ccd": "+1",
  "email": "john@example.com",
  "c_ate": 1695472000,
  "u_ate": 1695472000
}
```

***

### Get Patient

#### Example Request

```ts theme={null}
const patient = await sdk.patients.get('patient-oid');
```

#### Sample Response

```json theme={null}
{
  "oid": "patient-oid",
  "wid": "workspace-id",
  "gen": "F",
  "dob": "1985-05-20",
  "fn": "Jane",
  "ln": "Doe",
  "email": "jane@example.com",
  "mobile": "9876543210",
  "ccd": "+91",
  "c_ate": 1695472000,
  "u_ate": 1695480000
}
```

***

### Update Patient

**Updatable Fields:**\
You can update any of the following fields for a patient profile:

* `fn` – First name
* `mn` – Middle name
* `ln` – Last name
* `fln` – Full name\
  *(At least one name field (`fn`, `mn`, `ln`, or `fln`) must be present if updating the name)*
* `gen` – Gender (`M` | `F` | `O`)
* `dob` – Date of birth (`YYYY-MM-DD`)
* `mobile` – Mobile number (digits only)
* `ccd` – Country code (e.g., "+91")
* `email` – Email address
* `username` – Username
* `bg` – Blood group
* `abha` – ABHA address
* `is_age` - Field to indicate whether dob was derived from age
* `s`  Salutation

#### Example Request

```ts theme={null}
const updated = await sdk.patients.update('patient-oid', {
  fn: 'Jane',
  email: 'jane@example.com'
});
```

#### Sample Response

```json theme={null}
    {"message" : "Profile updated successfully"}
```

***

### Delete Patient

#### Example Request

```ts theme={null}
await sdk.patients.delete('patient-oid');
```

#### Sample Response

```json theme={null}
{"message": "Profile archived successfully" }
```

***

### Bulk Get

#### Example Request

```ts theme={null}
const patients = await sdk.search.bulkGet(['oid1', 'oid2']);
```

#### Sample Response

```json theme={null}
[
  { "oid": "oid1", "fln": "Alice Johnson", "mobile": "1111111111" },
  { "oid": "oid2", "fln": "Bob Smith", "mobile": "2222222222" }
]
```

***

## Search Operations

### Get by Username

#### Example Request

```ts theme={null}
const patients = await sdk.patients.getByUsername('john.doe');
```

#### Sample Response

```json theme={null}
[
  {
    "oid": "patient-oid-1",
    "wid": "workspace-id",
    "username": "john.doe",
    "fln": "John Doe",
    "mobile": "1234567890"
  }
]
```

### Search by Mobile

#### Example Request

```ts theme={null}
const patients = await sdk.search.getByMobile('1234567890');
```

#### Sample Response

```json theme={null}
[
  {
    "oid": "patient-oid",
    "fln": "John Doe",
    "mobile": "1234567890"
  }
]
```

### Prefix Search

#### Example Request

```ts theme={null}
const patients = await sdk.search.searchByPrefix('jo', 15, 'oid,fln,mobile');
```

#### Sample Response

```json theme={null}
[
  { "oid": "oid1", "fln": "John Doe", "mobile": "1234567890" },
  { "oid": "oid2", "fln": "Josh Adams", "mobile": "9876543210" }
]
```

***

## Utility Operations

### Remove Fields

#### Example Request

```ts theme={null}
await sdk.utils.removeFields('patient-oid', ['email', 'mobile']);
```

#### Sample Response

```json theme={null}
{"message": "Fields removed successfully"}
```

### Validate Patient Data

#### Example Request

```ts theme={null}
const validation = sdk.utils.validatePatientData({
  gen: 'M',
  dob: '1990-01-01',
  fn: 'John'
});

if (!validation.isValid) {
  console.log(validation.errors);
}
```

#### Sample Response

```json theme={null}
{ "isValid": true, "errors": [] }
```

***

## Data Types

### Gender

```ts theme={null}
type Gender = 'M' | 'F' | 'O';
```

### Blood Groups

```ts theme={null}
type BloodGroup = 'A+' | 'A-' | 'B+' | 'B-' | 'AB+' | 'AB-' | 'O+' | 'O-';
```

### Patient Interface

```ts theme={null}
interface Patient {
  oid: string;
  wid: string;
  gen: Gender;
  dob: string;
  fn?: string;
  mn?: string;
  ln?: string;
  fln?: string;
  ccd?: string;
  mobile?: string;
  email?: string;
  username?: string;
  bg?: BloodGroup;
  abha?: string;
  arc?: boolean;
  extras?: Record<string, any>;
}
```

***

## Error Handling

#### Example Request

```ts theme={null}
import { ValidationError, AuthenticationError, NotFoundError, TrinitySDKError } from '@eka-care/patient-ts-sdk';

try {
  const patient = await sdk.patients.get('invalid-id');
} catch (err) {
  if (err instanceof ValidationError) {
    console.log('Validation failed:', err.validationErrors);
  } else if (err instanceof AuthenticationError) {
    console.log('Invalid token');
  } else if (err instanceof NotFoundError) {
    console.log('Patient not found');
  } else if (err instanceof TrinitySDKError) {
    console.log('API error:', err.message);
  }
}
```

#### Sample Error Response

```json theme={null}
{
  "error": "ValidationError",
  "message": "Missing required field: dob",
  "validationErrors": ["dob is required"]
}
```