Trinity Profiles SDK (TypeScript)

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

Installation

npm install @eka-care/patient-ts-sdk

Or, if using source:

cd trinity-profiles-sdk
npm install

You can find the package on npm.

---

Quick Start

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

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: '[e-mail]'
});

Sample Response

{
  "oid": "unique-patient-id",
  "wid": "workspace-id",
  "gen": "M",
  "dob": "1990-01-01",
  "fn": "John",
  "ln": "Doe",
  "mobile": "1234567890",
  "ccd": "+1",
  "email": "[e-mail]",
  "c_ate": 1695472000,
  "u_ate": 1695472000
}

---

Get Patient

Example Request

const patient = await sdk.patients.get('patient-oid');

Sample Response

{
  "oid": "patient-oid",
  "wid": "workspace-id",
  "gen": "F",
  "dob": "1985-05-20",
  "fn": "Jane",
  "ln": "Doe",
  "email": "[e-mail]",
  "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

const updated = await sdk.patients.update('patient-oid', {
  fn: 'Jane',
  email: '[e-mail]'
});

Sample Response

    {"message" : "Profile updated successfully"}

---

Delete Patient

Example Request

await sdk.patients.delete('patient-oid');

Sample Response

{"message": "Profile archived successfully" }

---

Bulk Get

Example Request

const patients = await sdk.search.bulkGet(['oid1', 'oid2']);

Sample Response

[
  { "oid": "oid1", "fln": "Alice Johnson", "mobile": "1111111111" },
  { "oid": "oid2", "fln": "Bob Smith", "mobile": "2222222222" }
]

---

Search Operations

Get by Username

Example Request

const patients = await sdk.patients.getByUsername('john.doe');

Sample Response

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

Search by Mobile

Example Request

const patients = await sdk.search.getByMobile('1234567890');

Sample Response

[
  {
    "oid": "patient-oid",
    "fln": "John Doe",
    "mobile": "1234567890"
  }
]

Prefix Search

Example Request

const patients = await sdk.search.searchByPrefix('jo', 15, 'oid,fln,mobile');

Sample Response

[
  { "oid": "oid1", "fln": "John Doe", "mobile": "1234567890" },
  { "oid": "oid2", "fln": "Josh Adams", "mobile": "9876543210" }
]

---

Utility Operations

Remove Fields

Example Request

await sdk.utils.removeFields('patient-oid', ['email', 'mobile']);

Sample Response

{"message": "Fields removed successfully"}

Validate Patient Data

Example Request

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

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

Sample Response

{ "isValid": true, "errors": [] }

---

Data Types

Gender

type Gender = 'M' | 'F' | 'O';

Blood Groups

type BloodGroup = 'A+' | 'A-' | 'B+' | 'B-' | 'AB+' | 'AB-' | 'O+' | 'O-';

Patient Interface

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

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

{
  "error": "ValidationError",
  "message": "Missing required field: dob",
  "validationErrors": ["dob is required"]
}