carestack-staging 1.0.7

Carestack EHR SDK

A modern, asynchronous C# SDK for the CareStack EHR platform. This SDK simplifies integration with the CareStack API, providing intuitive, type-safe services for managing health records, scheduling, and leveraging powerful AI-driven features like document summarization and FHIR bundle generation.

This SDK is designed for modern .NET applications and supports asynchronous API interactions using async/await.

✨ Key Features

This SDK supports a comprehensive suite of CareStack EHR functionalities:

• Electronic Health Records (EHR): Secure and structured access to patient records.

• ABHA (Ayushman Bharat Health Account) workflows: Generate, verify, and manage ABHA numbers using official NDHM APIs.

• HPR (Healthcare Professional Registry) services: Professional identity creation and linking with ABHA.

• HealthLake Resource Management: Interact with FHIR-compliant resources such as Patient, Practitioner, Organization, and more.

• Appointment Management: Create, update, and retrieve patient appointment data.

• FHIR Bundle Generation: Generate structured clinical documents in FHIR format, ready for interoperability.

• AI-powered Document Summarization: Automatically summarize patient health documents using integrated AI services.

• Comprehensive Resource Management: Full CRUD and search support for EHR resources such as Patient, Appointment, Organization, and Practitioner.

• Workflow-Driven Services: Simplified step-by-step APIs for ABHA and HPR registration flows.

• AI-Powered Document Processing:

  • Summarization: Generate concise summaries from clinical documents.
  • Entity Extraction: Extract structured data (diagnoses, medications, etc.) from free text.
  • FHIR Bundle Generation: Convert raw documents or structured JSON into HL7 FHIR-compliant bundles.

• Asynchronous Operations: All APIs support asynchronous execution using async/await.

• Built-in Validation: Automatic validation of request DTOs before sending requests.

• Secure by Design: Includes utilities for encryption to protect sensitive health information.

🚀 Getting Started

Prerequisites

• .NET 8 or later
• An active API key for the CareStack EHR platform

Installation

Install the CareStack SDK via NuGet.

dotnet add package carestack-staging --version 1.0.3

Configuration

Initialize the SDK using your API credentials.

using Carestack.Base.Config;
using Carestack.Base.Utils;

var config = new EmbeddedSdkProperties
{
    BaseUrl = "your_api_url_here",
    ApiKey = "your_secret_api_key_here",
    AbhaCertificatePem = "your_certificate"
};

var httpClient = new HttpClient
{
    BaseAddress = new Uri(config.baseUrl),
    Timeout = TimeSpan.FromMinutes(10)
};

var encryption = new EncryptionUtilities(config, httpClient);

Quick Start

Example: Fetch a patient by ID.

using Carestack.Patient;

var patientService = new Patient(config, httpClient, encryption);

string patientId = "632df79b-67bc-415e-91d7-aa70cd99a79e";

var patientData = await patientService.FindById(patientId);

Console.WriteLine(patientData);

Services Overview

The SDK provides the following main services.

Core EHR Services

AI & Document Services

Healthcare Identity Workflows

Detailed Service Guide

Patient Resource Management

using Carestack.Patient;
var patientService = new Patient(config, httpClient, encryption);

Create a new patient record

// Input:
using Carestack.Patient.Dto;
using Carestack.Patient.Enums;
using Carestack.Base.Enums;

var newPatient = new PatientDTO
{
    IdNumber = "123456789012",                 // ID Number
    IdType = PatientIdType.AADHAAR,            // ID Type
    AbhaAddress = "ram@abha",                  // ABHA Address
    PatientType = PatientType.NEW,             // Patient Type
    FirstName = "Ram",                         // First Name
    MiddleName = "S",                          // Middle Name
    LastName = "Kumar",                        // Last Name
    BirthDate = "1990-05-15",                  // Birth Date
    Gender = Gender.MALE,                      // Gender
    EmailId = "ram.kumar@example.com",         // Email
    MobileNumber = "+919876543210",            // Mobile Number
    Address = "123 Temple Street, Ayodhya",    // Address
    Pincode = "224123",                        // Pincode
    State = StatesAndUnionTerritories.UTTAR_PRADESH, // State
    LinkWhatsapp = true,                       // Wants to link WhatsApp
    Photo = null,                              // Photo (Optional)
    ResourceType = ResourceType.Patient,       // Resource Type
    ResourceId = null                          // Resource ID (Not needed for creation)
};

var response = await patientService.Create(newPatient);
Console.WriteLine(response);

/*
Expected Output:
{
  "message": "Successfully created the Patient profile",
  "type": "Patient",
  "resourceId": "791708f6-de6d-439e-bece-041e5d64e463",
  "validationErrors": [],
  "fhirProfileId": "",
  "resource": {
    "firstName": "Ram",
    "lastName": "Kumar",
    "birthDate": "1990-05-15",
    "gender": "MALE",
    "mobileNumber": "+919876543210",
    ...
  }
}
*/

ABHA Registration Workflow

The SDK simplifies the multi-step ABHA registration into a guided workflow.

var abhaService = patientService.Abha();

Step 1: Register With Aadhaar

var payload = new Dictionary<string, object>
{
    { "aadhaar", "123456789012" }
};

var response = await abhaService.CreateAbha(
    AbhaSteps.REGISTER_WITH_AADHAAR,
    payload
);
Console.WriteLine(response);

// Expected Output:
/*
{
  "success": true, "message": "OTP sent successfully...",
  "response": { "txnId": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6" },
  "nextStep": "VerifyAadhaarOtp", "nextStepHint": "Please enter the OTP..."
}
*/

Practitioner Resource Management

using Carestack.Practitioner;
var practitionerService = new Practitioner(config, httpClient);

Update Practitioner

var payload = new PractitionerDTO
{
    ResourceId = "prac_67890",
    Designation = "Senior Consultant",
    FirstName = "Jane",
    LastName = "Doe"
};

var response = await practitionerService.Update(payload);
Console.WriteLine(response);

/*
Expected Output:
{
  "message": "Details Updated successfully",
  "type": "Practitioner",
  "resource": {
    "firstName": "Jane",
    "designation": "Senior Consultant",
    ...
  }
}
*/

HPR Registration

The Healthcare Professional Registry (HPR) registration is a guided workflow.

var hprService = practitionerService.Hpr();

Step 1: Register with Aadhaar

var payload = new Dictionary<string, object>
{
    { "aadhaar", "123456789012" }
};

var response = await hprService.CreateHpr(
    HprSteps.GENERATE_AADHAAR_OTP,
    payload
);

// Expected Output:
/*
{
  "success": true, "message": "OTP sent successfully...",
  "response": { "txnId": "a1b2c3d4-e5f6-4a5b-8c9d-e1f2a3b4c5d6", "mobileNumber": "******3210" },
  "nextStep": "VerifyAadhaarOtp", "nextStepHint": "Enter txnId and OTP to verify mobile number."
}
*/

Appointment Management

Handles scheduling, retrieving, and managing appointments.

using Carestack.Appointment;
var appointmentService = new Appointment(config, httpClient);

Retrieve All Appointments (Paginated)

var appointments = await appointmentService.FindAll(15);
Console.WriteLine(appointments);
/*
Expected Output:
{
  "data": [
    { "appointmentReference": "appt_1", ... },
    { "appointmentReference": "appt_2", ... }
  ],
  "nextPage": "tokenForPage2"
}
*/

Organization Management

This service has custom methods for managing organizations and related master data.

using Carestack.Organization;
var demograph = new Demographic(config, httpClient);
var organizationService = new Organization(config, httpClient, demograph);

Register an Organization

using Carestack.Organization.Dto;
using Carestack.Organization.Enums;

var newOrg = new OrganizationDTO
{
    accountId = "my-hospital-chain"
};

var basicInfo = new BasicInformation
{
    OrganizationName = "City Central Hospital",
    Address = "456 Health Ave, Metropolis",
    State = "Telangana",
    Pincode = "500081",
    Region = Region.URBAN.GetCode()
};

newOrg.BasicInformation = basicInfo;

// ... set other required DTOs like ContactInformation and OrganizationDetails

var response = await organizationService.Create(newOrg);

Console.WriteLine(response);

/*
Expected Output:
{
  "status": "success",
  "message": "Facility added successfully. Your facility ID is IN6778"
}
*/

AI-Powered Discharge Summary and OP Consultation Generation from File URLs

This service is the gateway for generating FHIR bundles from various data sources. It internally uses an AI Service for processing unstructured documents.

Generate Discharge Summary from File URLs

using Carestack.Ai;
using Carestack.Ai.Dto;
var aiService = new AiService(config, httpClient, encryption);

var dto = new ProcessDSDto
{
    Files = new List<string>
    {
        "https://example-bucket.s3.amazonaws.com/discharge1.pdf",
        "https://example-bucket.s3.amazonaws.com/discharge2.pdf"
    }
};

var summary = await aiService.GenerateDischargeSummary(dto);
Console.WriteLine(summary);

/*
Expected Output:
Discharge Summary: {
"id": "1db63a9f-ac82-41fa-b50b-69a09c2c839e",
"dischargeSummary": {
"patientDetails": {
"Name": "MR. ARUN KUMAR MITRA",
// ...other details
}
},
"extractedData": {
"Patient Details": {
"Name": "MR. ARUN KUMAR MITRA",
// ...other details
}
},
"fhirBundle": {}
}
*/

Generating OP Consultation Summary

var summary = await aiService.GenerateOpSummary(dto);
Console.WriteLine(summary);

Generating Radiology Report

var summary = await aiService.GenerateRadiologyReport(dto);
Console.WriteLine(summary);

Generating Care Plan Summary

var summary = await aiService.GenerateCarePlan(dto);
Console.WriteLine(summary);

Generating a FHIR Bundle from Health Information Data

This method supports two modes of input:

1. File-based: Processes files provided in the dto.caseSheets array.
2. JSON-based: Processes JSON payload provided in dto.payload, which must match one of the supported HI types.

• In both cases, if the enableExtraction flag is set to false, document references will be mandatory.
• patientDetails and practitionerDetails are mandatory for case-2 (JSON-based processing), irrespective of the enableExtraction flag.
• PatinetDetails and PractitionerDetails are optional for case-1 (file-based processing) if enableExtraction is set to true. If easeExtraction is false, these details are mandatory.

using Carestack.Encounter;
var encounterService = new Encounter(config, httpClient);

Create a FHIR Bundle

This is the main method that provides bundle creation. It intelligently dispatches to the correct workflow based on the input.

From Unstructured Files (AI-Powered)

This workflow takes file URLs, uses AI to extract structured data, and generates a FHIR bundle.

using Carestack.Encounter.Dto;
var request = new EncounterRequestDTO();
request.CaseType = CaseType.DISCHARGE_SUMMARY;
request.EnableExtraction = true;

var fhirBundle = await encounterService.Create(request);

Console.WriteLine(fhirBundle);

/*
Expected Output:
{
  "id": "7b3b5fef-7fd1-437b-940d-a55b64add446",
  "resourceType": "Bundle",
  "type": "document",
  "entry": [ ... fhir resources ... ]
}
*/

From Structured JSON Data

This workflow takes a pre-structured JSON payload and converts it directly into a FHIR bundle.

using Carestack.Encounter.Dto;
// 1. Define Patient and Practitioner details
    var patientDetails = new PatientDetails{
        FirstName = "Ravi"
        // ... set other patient details
    };

    var practitionerDetails = new PractitionerDetails{
        FirstName = "Anita"
        // ... set other practitioner details
    };

// 2. Create the structured payload for the specific case type
    var opConsultationPayload = new Dictionary<string, object>{
        {
            "physicalExamination", new Dictionary<string, object>{
                {
                    "bloodPressure", new Dictionary<string, object>{
                        { "value", "140/90" },
                        { "unit", "mmHg" }
                    }
                }
            }
        },
        {
            "allergies", new List<string>{
                "No known drug allergies"
            }
        }
        // ... add other sections etc.
    };

// 3. Wrap everything in the EncounterRequestDTO
    var request = new EncounterRequestDTO{
        CaseType = CaseType.OP_CONSULTATION,
        EnableExtraction = false, // Extraction is not needed for structured data
        DocumentReferences = new List<string> {
            "https://lab.com/report123.pdf"
        },
        PatientDetails = patientDetails,
        PractitionerDetails = new List<PractitionerDetails>{
            practitionerDetails
        },
        Dto = new Dictionary<string, object>{
            { "payload", opConsultationPayload }
        }
    };
// 4. Call the service
    var fhirBundle = await encounterService.Create(request);
    Console.WriteLine("FHIR bundle generated: " + fhirBundle);

/*
Expected Output:
{
  "id": "8bbb67fef-7fd1-437b-940d-a55b64add446",
  "resourceType": "Bundle",
  "type": "document",
  "entry": [ ... fhir resources ... ]
}
*/

Handling Partial Upload Of Discharge Summary

using Carestack.Ai.Dto;
var dto = new ProcessDSDto
{
    Files = new List<string> { "https://bucket/hospital/notes.pdf" }
};

var result = await aiService.PartialUploadForDischargeSummary(dto);

Console.WriteLine(result);

Trigger Discharge Summary Generation

var result = await aiService.TriggerDischargeSummary("encounter-id");

Console.WriteLine(result);

Linking Health Documents

This service orchestrates the multi-step process of creating a care context and linking health documents to a patient's ABHA.

using Carestack.Encounter;
using Carestack.Encounter.DocumentLinking.Dto;
// Initialize Encounter service
var encounter = new Encounter(config, httpClient);

// 1. Create linking request
var linkingRequest = new HealthDocumentLinkingDTO{
    PatientReference = "a8654878-4202-4b47-bcc4-868060a75254",
    PractitionerReference = "3c7271bb-4212-4291-9f75-64d886d69893",
    PatientAddress = "123 Main St, Springfield, IL",
    PatientName = "John Doe",
    AppointmentStartDate = "2025-02-28T09:00:00Z",
    AppointmentEndDate = "2025-02-28T10:00:00Z"
    // ... add other fields of the dto
};

// 2. Define the health record to be linked
var healthRecord = new HealthInformationDTO{
    InformationType = DocLinkingEnums.HealthInformationTypes.OPConsultation,
    RawFhir = false
};

// 3. Create detailed DTO structure
var dto = new Dictionary<string, object>{
    { "chiefComplaints", "Severe headache and nausea for the past 1 day" },
    {
        "physicalExamination", new Dictionary<string, object>{
            {
                "bloodPressure", new Dictionary<string, object>{
                    { "value", "140/90" },
                    { "unit", "mmHg" }
                }
            }
        }
    },
    { "opConsultDocument", new List<string> { "base64-pdf-data-placeholder" } }
    // ... add other sections to the map
};

healthRecord.dto = dto;

// 4. Attach health record to linking request
linkingRequest.healthRecords = new List<HealthInformationDTO>{
    healthRecord
};

// 5. Call the service
var isLinked = await encounter.DocumentLinking().Link(linkingRequest);
Console.WriteLine("Document linked successfully: " + isLinked);

// Expected Output: true

Response Examples

Common Response Patterns

All services follow consistent response patterns for better predictability:

Success Response Format

{
  "status": "success",
  "message": "Operation completed successfully",
  "data": { /* relevant data */ },
  "timestamp": "2025-01-15T14:30:00Z",
  "request_id": "req_123456789"
}

Error Response Format

{
  "status": "error",
  "error_code": "VALIDATION_ERROR",
  "message": "Invalid input data provided",
  "details": {
    "field": "email",
    "reason": "Invalid email format"
  },
  "timestamp": "2025-01-15T14:30:00Z",
  "request_id": "req_123456789"
}

Paginated Response Format

{
  "items": [ /* array of items */ ],
  "pagination": {
    "total": 150,
    "page": 1,
    "per_page": 20,
    "total_pages": 8,
    "has_next": true,
    "has_previous": false,
    "next_page": "eyJpZCI6InBhdF8xMjM0NTY3ODkifQ==",
    "previous_page": null
  }
}

Support

Documentation and Resources

• C# SDK Documentation: [http://mydocs-sdk.s3-website.ap-south-1.amazonaws.com]

🛠️ Building from Source

To build the SDK from the source code, clone the repository and run the following command:

dotnet build

License

This SDK is licensed under the MIT License.