Package Exports

medos-sdk
medos-sdk/core
medos-sdk/react
medos-sdk/vanilla
medos-sdk/widget

Readme

Medos SDK

A JavaScript/TypeScript SDK for integrating healthcare appointment booking into your applications. Built for clinics, hospitals, and healthcare platforms.

✨ Features

🎨 Powerful Theming System - Customize appearance with built-in themes or create your own
⚛️ React & Vanilla JS - Works with React or pure JavaScript
🔒 Secure Authentication - API key and session token support
📱 Responsive Design - Mobile-first, works on all screen sizes
🎯 TypeScript-First - Full type safety and IntelliSense support
♿ Accessible - WCAG compliant components

Installation

npm install medos-sdk

Quick Start
Getting Started
Usage
React Integration
Vanilla JavaScript
TypeScript
API Reference
Error Handling
Requirements

Quick Start

React

import { MedosThemeProvider, AppointmentCalender } from "medos-sdk/react";

function App() {
  return (
    <MedosThemeProvider theme="modern">
      <AppointmentCalender onError={(err) => console.error(err)} />
    </MedosThemeProvider>
  );
}

Vanilla JavaScript

import { initAppointmentCalendar } from "medos-sdk/vanilla";

initAppointmentCalendar({
  containerId: "appointment-widget",
  apiKey: "your-api-key",
  theme: "modern", // or 'default'
});

HTML/CSS/JS

<!DOCTYPE html>
<html>
  <head>
    <link rel="stylesheet" href="path/to/widget.css" />
  </head>
  <body>
    <div id="appointment-calendar"></div>
    <script src="path/to/widget.js"></script>
    <script>
      window.MedosAppointmentCalendar.init({
        containerId: "appointment-calendar",
        apiKey: "your-api-key",
      });
    </script>
  </body>
</html>

Getting Started

Authentication

The SDK supports two authentication methods:

Server-Side (API Key)

Use this method for backend services and server-side rendering.

import { MedosClient } from "medos-sdk";

await MedosClient.init({
  apiKey: "your-api-key",
});

Client-Side (Session Token)

Use this method for frontend applications. Obtain the session token from your backend.

import { MedosClient } from "medos-sdk";

await MedosClient.initWithSession({
  sessionToken: "user-session-token",
});

Usage

Fetch Clinic Addresses and Doctors

Retrieve all available clinic locations with their associated doctors.

const result = await MedosClient.fetchAllAddressesAndDoctors();

Response:

{
  totalAddresses: 5,
  totalDoctors: 12,
  workspaceId: "workspace-123",
  addresses: [
    {
      id: "addr-1",
      completeAddress: "123 Medical Center, New York, NY 10001",
      addressLine1: "123 Medical Center",
      city: "New York",
      state: "NY",
      country: "USA",
      zipcode: "10001",
      doctors: [
        {
          id: "doc-1",
          name: "Dr. John Smith",
          email: "john.smith@example.com",
          specialty: "Cardiology"
        }
      ]
    }
  ]
}

Fetch Available Slots

Get available appointment time slots for a specific doctor.

const slots = await MedosClient.fetchAppointments(
  "workspace-123", // workspaceId
  "addr-1", // addressId
  "doc-1", // doctorId
  "2025-11-16" // appointmentDate (YYYY-MM-DD)
);

Response:

[
  {
    start: "2025-11-16T10:00:00",
    end: "2025-11-16T10:30:00",
    id: "slot-1",
  },
  {
    start: "2025-11-16T11:00:00",
    end: "2025-11-16T11:30:00",
    id: "slot-2",
  },
];

Book an Appointment

Create a new appointment booking.

import { AppointmentService } from "medos-sdk";

const appointment = await AppointmentService.createAppointment({
  workspaceAddressId: "addr-1",
  doctorId: "doc-1",
  mode: "OFFLINE",
  appointmentDate: "2025-11-16",
  fromDateTimeTs: "10:00",
  toDateTimeTs: "10:30",
  consultationCharge: "100",
  type: "CONSULTATION",
  source: "SDK_POWERED_WEBSITE",
  patientPayload: {
    firstName: "Jane",
    lastName: "Doe",
    email: "jane.doe@example.com",
    countryCode: "+1",
    phoneNumber: "5551234567",
    age: 30,
    gender: "FEMALE",
  },
  patientAddress: {
    addressLine1: "456 Patient Street",
    city: "New York",
    state: "NY",
    country: "USA",
    zipcode: "10001",
    landmark: "Near Central Park",
  },
});

Optional Fields:

Field	Default Value	Description
`mode`	`"OFFLINE"`	Consultation mode: `"OFFLINE"` or `"ONLINE"`
`consultationCharge`	`"0"`	Consultation fee as string
`type`	`"CONSULTATION"`	Appointment type
`source`	`"SDK_POWERED_WEBSITE"`	Source identifier

Phone Verification

Implement OTP-based phone number verification for patients.

Send OTP

await MedosClient.sendPhoneVerificationOtp({
  countryCode: "+1",
  phoneNumber: "5551234567",
});

Verify OTP

const result = await MedosClient.verifyPhoneVerificationOtp({
  countryCode: "+1",
  phoneNumber: "5551234567",
  otp: "123456",
});

TypeScript

The SDK is written in TypeScript and provides comprehensive type definitions.

import {
  MedosClient,
  AppointmentService,
  BookAppointmentPayload,
  AddressesResponse,
  PatientPayload,
  PatientAddressPayload,
} from "medos-sdk";

const payload: BookAppointmentPayload = {
  workspaceAddressId: "addr-1",
  doctorId: "doc-1",
  appointmentDate: "2025-11-16",
  fromDateTimeTs: "10:00",
  toDateTimeTs: "10:30",
  patientPayload: {
    firstName: "John",
    lastName: "Doe",
    countryCode: "+1",
    phoneNumber: "5551234567",
  },
  patientAddress: {
    addressLine1: "123 Main Street",
    city: "New York",
    state: "NY",
    country: "USA",
    zipcode: "10001",
  },
};

const appointment = await AppointmentService.createAppointment(payload);

Type Definitions

`BookAppointmentPayload`

{
  workspaceAddressId: string | number;
  doctorId: string | number;
  appointmentDate: string;           // Format: "YYYY-MM-DD"
  fromDateTimeTs: string;            // Format: "HH:MM"
  toDateTimeTs: string;              // Format: "HH:MM"
  mode?: "OFFLINE" | "ONLINE";       // Default: "OFFLINE"
  consultationCharge?: string;       // Default: "0"
  type?: "CONSULTATION" | string;    // Default: "CONSULTATION"
  source?: string;                   // Default: "SDK_POWERED_WEBSITE"
  patientPayload: PatientPayload;
  patientAddress: PatientAddressPayload;  // Required
}

`PatientPayload`

{
  firstName: string;
  lastName: string;
  countryCode: string;
  phoneNumber: string;
  email?: string;
  age?: number;
  gender?: "MALE" | "FEMALE" | "OTHER";
}

`PatientAddressPayload`

{
  addressLine1?: string;
  city?: string;
  state?: string;
  country?: string;
  zipcode?: string;
  landmark?: string;
}

React Integration

Pre-built appointment calendar component for React applications.

import { AppointmentCalender } from "medos-sdk";

function BookingPage() {
  return <AppointmentCalender />;
}

The component automatically uses the initialized MedosClient instance.

Using React-specific exports

For better tree-shaking and to avoid React dependency conflicts:

import { AppointmentCalender } from "medos-sdk/react";

Vanilla JavaScript / HTML Integration

For websites using plain HTML, CSS, and JavaScript (no React), use the vanilla widget.

Installation

The widget is available as a bundled UMD module. After building the package, you'll find:

dist/vanilla/widget.js - JavaScript bundle
dist/vanilla/widget.css - Stylesheet

Basic Usage

<!DOCTYPE html>
<html>
  <head>
    <link rel="stylesheet" href="path/to/widget.css" />
  </head>
  <body>
    <div id="appointment-calendar"></div>

    <script src="path/to/widget.js"></script>
    <script>
      window.MedosAppointmentCalendar.init({
        containerId: "appointment-calendar",
        apiKey: "your-api-key",
        onError: (err) => {
          console.error("Error:", err);
          alert("An error occurred. Please try again.");
        },
        onSuccess: () => {
          console.log("Appointment booked successfully!");
        },
      });
    </script>
  </body>
</html>

Using Session Token (Recommended for Production)

For better security, obtain the session token server-side:

<script>
  window.MedosAppointmentCalendar.init({
    containerId: "appointment-calendar",
    sessionToken: "your-session-token", // Obtained from your server
    baseURL: "https://api.medos.one/v1",
    onError: (err) => console.error(err),
  });
</script>

PHP Integration Example

<?php
// Get session token from your backend
$sessionToken = getSessionTokenFromBackend();
?>
<!DOCTYPE html>
<html>
<head>
    <link rel="stylesheet" href="path/to/widget.css">
</head>
<body>
    <div id="appointment-calendar"></div>
    <script src="path/to/widget.js"></script>
    <script>
        window.MedosAppointmentCalendar.init({
            containerId: 'appointment-calendar',
            sessionToken: '<?php echo htmlspecialchars($sessionToken); ?>',
            onError: (err) => {
                console.error('Error:', err);
                alert('An error occurred. Please try again.');
            }
        });
    </script>
</body>
</html>

Configuration Options

containerId (string, required) - ID of the HTML element where the widget will be rendered
apiKey (string, optional) - Your Medos API key (if not using sessionToken)
sessionToken (string, optional) - Session token obtained from your server (if not using apiKey)
baseURL (string, optional) - API base URL (defaults to https://api.medos.one/v1)
onError (function, optional) - Callback function for error handling
onSuccess (function, optional) - Callback function called when appointment is successfully booked

Styling

The widget comes with default styles. You can customize them by overriding CSS classes:

.medos-appointment-btn-primary {
  background: #your-color;
}

.medos-appointment-card {
  border-radius: 8px;
}

See dist/vanilla/widget.css for all available classes.

Package Exports

The SDK provides multiple entry points for different use cases:

medos-sdk - Default export (includes React components)
medos-sdk/react - React-specific exports
medos-sdk/vanilla - Vanilla JS exports (ES modules)
medos-sdk/core - Core services only (no framework dependencies)
medos-sdk/widget - Widget bundle with CSS

API Reference

MedosClient

`init(config)`

Initialize the SDK with an API key (server-side).

Parameters:

config.apiKey (string, required) - Your Medos API key
config.baseURL (string, optional) - API base URL. Defaults to dev environment

Returns: Promise<void>

`initWithSession(config)`

Initialize the SDK with a session token (client-side).

Parameters:

config.sessionToken (string, required) - Session token
config.baseURL (string, optional) - API base URL. Defaults to dev environment

Returns: Promise<void>

`fetchAllAddressesAndDoctors()`

Fetch all clinic addresses and their associated doctors.

Returns: Promise<AddressesResponse>

Response Type:

{
  totalAddresses?: number;
  totalDoctors?: number;
  workspaceId?: number | string;
  addresses: Array<{
    id: string;
    completeAddress?: string;
    addressLine1?: string;
    city?: string;
    state?: string;
    country?: string;
    zipcode?: string;
    doctors?: Array<{
      id: string;
      name: string;
      email?: string;
      specialty?: string;
    }>;
  }>;
}

`fetchAppointments(workspaceId, addressId, doctorId, appointmentDate)`

Fetch available appointment slots for a specific doctor.

Parameters:

workspaceId (string | number) - Workspace identifier
addressId (string | number) - Address identifier
doctorId (string | number) - Doctor identifier
appointmentDate (string) - Date in YYYY-MM-DD format

Returns: Promise<Slot[]>

Response Type:

Array<{
  start: string; // ISO datetime format
  end: string; // ISO datetime format
  id?: string;
}>;

`sendPhoneVerificationOtp(payload)`

Send OTP to a phone number for verification.

Parameters:

payload.countryCode (string) - Country code with + prefix (e.g., "+1")
payload.phoneNumber (string) - Phone number without country code

Returns: Promise<any>

`verifyPhoneVerificationOtp(payload)`

Verify OTP for a phone number.

Parameters:

payload.countryCode (string) - Country code with + prefix
payload.phoneNumber (string) - Phone number without country code
payload.otp (string) - OTP code received

Returns: Promise<any>

AppointmentService

`createAppointment(payload)`

Create a new appointment booking.

Parameters:

payload (BookAppointmentPayload) - Appointment details

Returns: Promise<any>

Error Handling

All SDK methods return Promises and should be wrapped in try-catch blocks.

try {
  await MedosClient.init({ apiKey: "your-api-key" });
  const addresses = await MedosClient.fetchAllAddressesAndDoctors();
} catch (error) {
  console.error("Failed to fetch addresses:", error.message);
}

Requirements

Node.js: v14 or higher
Browsers: Modern browsers with ES6+ support
React: v19 or higher (only required for React components, not for vanilla widget)
TypeScript: v5 or higher (optional)

Support

For bug reports and feature requests, please visit our GitHub Issues.

License

UNLICENSED

Author

Pooranjoy Bhattacharya

Built for healthcare providers worldwide.

medos-sdk

Package Exports

Readme

Medos SDK

✨ Features

Installation

Table of Contents

Quick Start

React

Vanilla JavaScript

HTML/CSS/JS

Getting Started

Authentication

Server-Side (API Key)

Client-Side (Session Token)

Usage

Fetch Clinic Addresses and Doctors

Fetch Available Slots

Book an Appointment

Phone Verification

Send OTP

Verify OTP

TypeScript

Type Definitions

BookAppointmentPayload

PatientPayload

PatientAddressPayload

React Integration

Using React-specific exports

Vanilla JavaScript / HTML Integration

Installation

Basic Usage

Using Session Token (Recommended for Production)

PHP Integration Example

Configuration Options

Styling

Package Exports

API Reference

MedosClient

init(config)

initWithSession(config)

fetchAllAddressesAndDoctors()

fetchAppointments(workspaceId, addressId, doctorId, appointmentDate)

sendPhoneVerificationOtp(payload)

verifyPhoneVerificationOtp(payload)

AppointmentService

createAppointment(payload)

Error Handling

Requirements

Support

License

Author

`BookAppointmentPayload`

`PatientPayload`

`PatientAddressPayload`

`init(config)`

`initWithSession(config)`

`fetchAllAddressesAndDoctors()`

`fetchAppointments(workspaceId, addressId, doctorId, appointmentDate)`

`sendPhoneVerificationOtp(payload)`

`verifyPhoneVerificationOtp(payload)`

`createAppointment(payload)`