@eka-care/eka-care-core

v0.2.2

Published

5 months ago

Official TypeScript SDK for EKA Healthcare APIs - Appointments, Patients, Assessment & more

Downloads

0High
0Medium
0Low

Eka Care SDK

A comprehensive TypeScript SDK for integrating with Eka Care's healthcare APIs. Built for Ekathon (Eka Care Hackathon) with full TypeScript support and TS based autocomplete on payload, fns, return responses.

🚀 Features

Complete TypeScript Support - Full type safety with intelligent autocomplete
Healthcare Module Coverage - Appointments, Patients, Medications, Health Assessments, ABHA (coming soon)
Easy Integration - Simple setup for Node.js, Next.js, and React applications
Production Ready - Robust error handling and validation
Auth - you as a third party dev dont need to worry about auth or refresh token. since the SDK takes care of it. and everytime you call any of the SDK modules and fns it will automatically manage the auth token and its life-cycle and renewal

📦 Installation

npm install @eka-care/eka-care-core

⚠️ IMPORTANT NOTE BEFORE YOU START USING THE SDK ⚠️

The SDK can be used on both BE and FE — just with different configs.

If you initialize the SDK in a backend JS/TS runtime like Node, Express, Next, etc., you can use a straightforward config. We’ve also made it FE-compatible with a slightly different setup.

✅ Setup for BE runtimes

You can initialize the SDK in your backend environment by simply passing the client_id, client_secret, and api_key.

⚠️ Make sure to store these credentials securely and never expose them on the frontend.

import createEkaInstance from "@eka-care/eka-care-core";

const myEka = createEkaInstance({
  client_id: "your_client_id",
  client_secret: "your_client_secret",
  api_key: "your_api_key",
});

✅ Setup for FE runtimes (React, Next.js, etc.)

To use the SDK in a client-side web app, you'll need to use a token-based flow and set up a small backend auth proxy. Here's how:

// NOTE: This API endpoint is already written — you can deploy it with one click,
// add your env variables, and have it running on your Vercel account. More on that below.

// Client side FE code ——>
const authRes = await fetch("https://your-backend.vercel.app/api/manage-auth", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
});

const authData = await authRes.json();

const ekaInstanceResult = createEkaInstance({
  source: "FE",
  auth_token: authData.data.access_token,
  backendAuthEndpointURL:
    "https://vercel-clone-from-eka-account-next.vercel.app/api/manage-auth", // make sure this is the full URL: https + your Vercel domain + the API route
});

And you're GTG! You can initialize it once (maybe in a useEffect with empty dependencies) and take it for a spin. The SDK is now fully FE-compatible.

🔧 Get the backend up and running for FE auth

⚠️ Only needed if you're using the SDK on the frontend.

We have starter templates you can deploy instantly:

one click deployment button in the repo's readme Use these to deploy the /api/manage-auth route mentioned above. hence

deploy the repo that you wish to use (express or Next)
follow the deployment guidelines in the repo's readme
have the backend up and running and you can now initialize the SDK on FE as well
by first calling the backend api that you just deployed, and getting the auth token

const authRes = await fetch("https://your-backend.vercel.app/api/manage-auth", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
});

const authData = await authRes.json();

and initing the SDK on client side

const ekaInstanceResult = createEkaInstance({
  source: "FE",
  auth_token: authData.data.access_token, // passing the auth token that you received from the above API call
  backendAuthEndpointURL:
    "https://vercel-clone-from-eka-account-next.vercel.app/api/manage-auth", // make sure this is the full URL: https + your Vercel domain + the API route
});

Setup for BE runtimes

import createEkaInstance from "@eka-care/eka-care-core";

const myEka = createEkaInstance({
  client_id: "your_client_id",
  client_secret: "your_client_secret",
  api_key: "your_api_key",
});

Next.js API Route Example

// pages/api/healthcare.ts
import createEkaInstance from "@eka-care/eka-care-core";

const myEka = createEkaInstance({
  client_id: process.env.EKA_CLIENT_ID,
  client_secret: process.env.EKA_CLIENT_SECRET,
  api_key: process.env.EKA_API_KEY,
});

export default async function handler(req, res) {
  try {
    const slots = await myEka.appointments.getSlotsForDoctor({
      doctor_id: "doc123",
      clinic_id: "clinic456",
      start_date: "2025-06-05",
      end_date: "2025-06-06",
    });

    res.status(200).json({ success: true, data: slots });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
}

📚 Module Documentation

🏥 Appointments Module

Manage doctor appointments and schedules.

// Get available slots for a doctor
const slots = await myEka.appointments.getSlotsForDoctor({
  doctor_id: "doc123",
  clinic_id: "clinic456",
  start_date: "2025-06-01",
  end_date: "2025-06-01",
});

// Book an appointment
const appointment = await myEka.appointments.bookAppointmentSlotForDoctor({
  isBusinessOrDoctorAssosiatedWithEka: true,
  clinic_id: "clinic456",
  doctor_id: "doc123",
  patient_id: "patient789",
  appointment_details: {
    start_time: 1748607760,
    mode: "INCLINIC", // or "TELE"
  },
  patient_details: {
    dob: "2004-08-01",
    first_name: "John",
    gender: "M",
  },
});

// Get appointments by date
const appointments = await myEka.appointments.getAllAppointmentsByDate(
  "01-06-25"
);

// Get appointment details
const details = await myEka.appointments.getAppointmentDetailsById({
  appointment_id: "apt123",
});

// Manage appointment status
await myEka.appointments.parkAppointment({ appointment_id: "apt123" });
await myEka.appointments.completeAppointment({ appointment_id: "apt123" });
await myEka.appointments.cancelAppointment({ appointment_id: "apt123" });

👥 Patients Module

Patient registration and management.

// Add new patient to directory
const newPatient = await myEka.patients.addPatientToDirectory({
  first_name: "John",
  gender: "M",
  mobile: "918074106021",
  dob: "2004-08-01",
});

// Search patient by mobile number
const patient = await myEka.patients.searchPatientByMobile({
  mobile: "918074106021",
});

// Get patient details by ID
const patientDetails = await myEka.patients.getPatientDetailsById({
  patient_id: "174860072074280",
});

💊 Medication Search Module

Search and find medications.

// Search by drug name
const medications = await myEka.medicationSearch.searchMedications({
  drug_name: "paracetamol",
});

// Advanced search with multiple parameters
const advancedSearch = await myEka.medicationSearch.searchMedications({
  drug_name: "dolo",
  form: "tablet",
  volumes: "500",
});

// Search by generic names
const genericSearch = await myEka.medicationSearch.searchMedications({
  generic_names: "Glimeperide,Metformin",
  drug_name: "Glimeperide",
});

🩺 Health Assessment Module

Comprehensive health assessment and symptom checking.

// Initialize assessment
const assessment = await myEka.assessment.initAssessment({
  client_id: "your_client_id",
  user_info: {
    gender: "M",
    age: 25,
  },
  workflow_id: 814, // Symptom checker workflow
});

// Start assessment
const startResponse = await myEka.assessment.startAssessment({
  assessment_id: assessment.assessment_id,
  client_id: "your_client_id",
});

// Handle different question types with full TypeScript support
const question = startResponse.questions[0];

if (question.component_code === "I-RADG") {
  // Radio group with qualifiers (Yes/No/Don't Know)
  const choices = question.component_data.choices; // ✅ Autocomplete works!

  const userResponse = [
    {
      selected_choices: [
        {
          choice_id: choices[0].choice_id,
          choice_label: choices[0].choice_label,
          choice_qualifier: "p", // "p" = Yes, "a" = No, "u" = Don't Know
        },
      ],
    },
  ];
} else if (question.component_code === "I-MULT") {
  // Multiple choice selection
  const choices = question.component_data.choices; // ✅ Autocomplete works!

  const userResponse = [
    {
      selected_choices: choices.slice(0, 2).map((choice) => ({
        choice_id: choice.choice_id,
        choice_label: choice.choice_label,
      })),
    },
  ];
} else if (question.component_code === "I-ATSG") {
  // Autosuggest symptoms
  const staticChoices = question.component_data.autosuggest_static_choices; // ✅ Autocomplete works!

  const availableChoices = staticChoices.sections[0]?.choices || [];
  const userResponse = [
    {
      selected_choices: availableChoices.slice(0, 2).map((choice) => ({
        choice_id: choice.choice_id!,
        choice_label: choice.choice_label || choice.common_name!,
      })),
    },
  ];
}

// Continue assessment
const continueResponse = await myEka.assessment.continueAssessment({
  assessment_id: assessment.assessment_id,
  client_id: "your_client_id",
  qid: question.qid,
  user_response: userResponse,
});

// Submit final assessment
const results = await myEka.assessment.submitAssessment({
  assessment_id: assessment.assessment_id,
  client_id: "your_client_id",
});

console.log("Health Assessment Results:", results.likelihood);

🎙️ Eka Scribe Module

Ekascribe allows you to transcribe audio files into structured medical data. The TS SDK simplifies this integration, by handling auth internally and exposing 2 simple functions uploadAudioFileAndStartTranscription and getTranscribedData

Eka Care supports multiple output templates for different medical documentation needs. Choose the appropriate template ID based on your requirements:

| Template ID | Description | Use Case | | ------------------------- | ---------------------------------------------------------------- | ----------------------------------------------------- | | clinical_notes_template | Comprehensive clinical notes with structured medical information | General clinical documentation, patient consultations | | eka_emr_template | EMR-compatible format for electronic medical records | Integration with EMR systems | | transcript_template | Basic transcription with minimal structuring | Simple audio-to-text conversion |

Supported Input Languages

Eka Care supports transcription in multiple languages. Specify the appropriate language ID in the input_language parameter:

| Language ID | Language Name | | ----------- | ----------------------- | | en-IN | English (India) | | en-US | English (United States) | | hi | Hindi | | gu | Gujarati | | kn | Kannada | | ml | Malayalam | | ta | Tamil | | te | Telugu | | bn | Bengali | | mr | Marathi | | pa | Punjabi |

Step 1: Register Webhook (One-time Setup)

Before using the Ekascribe service, register a webhook to receive notifications when transcription is complete:

curl --request POST \
  --url https://api.eka.care/notification/v1/connect/webhook/subscriptions \
  --header 'Authorization: Bearer <auth_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "event_names": [
      "v2rx.completed"
    ],
    "endpoint": "your-endpoint-url",
    "signing_key": "supersecretkey",
    "protocol": "https"
  }'

then from any FE or BE JS based runtimes prepare your payload with the voice recordings and additional data

psudo react code to execute on click of a submit button

const handleSubmit = async () => {
  const response =
    await ekaInstance.ekaScribe.uploadAudioFileAndStartTranscription({
      txn_id: "717312jkjs212313jj1",
      files: selectedFiles, // array of audio files. can be taken from the user/your app with the <input /> tag.
      input_language: ["en-US"],
      output_format_template: [
        {
          codification_needed: true,
          template_id: "clinical_notes_template",
        },
        {
          codification_needed: false,
          template_id: "eka_emr_template",
        },
      ],
      mode: "consultation",
      transfer: "non-vaded",
    });
  console.log(response, "response");
};

psudo code when uploading from a Node JS environment

(async () => {
  try {
    await ekaInstance.ekaScribe.uploadAudioFileAndStartTranscription({
      files: ["/Users/govindganeriwal/Desktop/testReco1.m4a"],
      input_language: ["en-US", "en-IN"],
      output_format_template: [
        {
          codification_needed: true,
          template_id: "clinical_notes_template",
        },
        {
          codification_needed: false,
          template_id: "eka_emr_template",
        },
      ],
      mode: "consultation",
      transfer: "non-vaded",
      txn_id: "9f14c5ba-ee0b-4642-8f38-4",
    });
  } catch (e) {
    console.log("error", e);
  }
})();

and then to get the result back, psudo code

const transcribedData = await ekaInstance.ekaScribe.getTranscribedData({
  session_id: `9f14c5ba-ee0b-4642-8f38-4` // is the same as transaction id
})
console.log(transcribedData.data.output);

// when the transcription is successful it returns this kind of a response

{
"data": {
    "output": [
        {
            "template_id": "clinical_notes_template",
            "value": "<base 64 encoded data>",
            "type": "markdown",
            "name": "Clinical Notes",
            "status": "success",
            "errors": [],
            "warnings": []
        },
        {
            "template_id": "eka_emr_template",
            "value": "<base 64 encoded data>",
            "type": "eka_emr",
            "name": "Eka EMR Format",
            "status": "success",
            "errors": [],
            "warnings": []
        }
    ],
    "additional_data": {}
}
}
// make sure to decode the data.output.value —— could be something as simple as using `atob`

🎯 TypeScript Autocomplete

The SDK provides full TypeScript support with intelligent autocomplete. Press Ctrl+Space to see available options, methods, args and responses:

// Autocomplete works throughout the entire SDK
myEka. // Shows all available modules
myEka.assessment. // Shows all assessment methods
myEka.appointments. // Shows all appointment methods

// Type safety for parameters
await myEka.appointments.getSlotsForDoctor({
  // Autocomplete shows required fields
  doctor_id: "", // ✅ Required
  clinic_id: "", // ✅ Required
  start_date: "", // ✅ Required
  end_date: "", // ✅ Required
});

🔧 Configuration

Environment Variables

Create a .env.local file:

EKA_CLIENT_ID=your_client_id
EKA_CLIENT_SECRET=your_client_secret
EKA_API_KEY=your_api_key

TypeScript Configuration

Ensure your tsconfig.json includes:

{
  "compilerOptions": {
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

📋 Response Types

All methods return properly typed responses:

// Assessment results are fully typed
interface LikelihoodItem {
  id: string;
  desc: string;
  text: string;
  likelihood: string;
  relevant_doctor_specialities: string[];
}

// Appointment data is structured
interface AppointmentDetails {
  appointment_id: string;
  status: string;
  start_time: number;
  // ... and more
}

⚡ Error Handling

The SDK would never break the app and has try/catch at every important step. but for proper UX its recommended to wrap its usage with your own try/catch or .then and .catch

try {
  const result = await myEka.appointments.getSlotsForDoctor({
    doctor_id: "invalid",
    clinic_id: "invalid",
    start_date: "2025-06-01",
    end_date: "2025-06-01",
  });
} catch (error) {
  console.error("API Error:", error.message);
  // Handle error appropriately
}

📋 Requirements

Node.js 16+
TypeScript 4.5+ (recommended)
Valid EKA Healthcare API credentials