@elerahealth/booking-sdk

v1.2.0

Published

15 days ago

Official SDK for integrating Elera Health booking into provider websites with centralized flow control and theming

0High
0Medium
0Low

elerahealth

elera healthcare booking scheduling appointments widget sdk

@elera/booking-sdk

Official SDK for integrating Elera Health scheduling into provider websites.

What's New in v1.2.0

Centralized Flow Control: Elera now controls the booking steps, days shown, and flow behavior
Theming Support: Provider websites control colors, fonts, and visual design via CSS variables
React Integration: useEleraBooking hook for React/Next.js apps
Drop-in Widget: Pre-built widget that works with any website

Installation

npm install @elera/booking-sdk
# or
yarn add @elera/booking-sdk
# or
pnpm add @elera/booking-sdk

Quick Start

Option 1: Drop-in Widget (Easiest - 5 minutes)

Just add the widget to your page and customize with CSS variables:

<!DOCTYPE html>
<html>
<head>
  <style>
    /* Customize to match your brand */
    :root {
      --elera-primary: #FF6B35;           /* Your brand color */
      --elera-font-family: 'Poppins', sans-serif;
      --elera-border-radius: 16px;
    }
  </style>
</head>
<body>
  <div id="booking"></div>
  
  <script src="https://cdn.elera.com/elera-booking-widget.min.js"></script>
  <script>
    EleraBookingWidget.mount('#booking', {
      apiKey: 'elera_your_api_key',
      onComplete: (booking) => {
        console.log('Booked!', booking.booking.confirmationId);
      }
    });
  </script>
</body>
</html>

Option 2: React Integration

import { EleraBookingProvider, useEleraBooking } from '@elera/booking-sdk/react';

function App() {
  return (
    <EleraBookingProvider 
      apiKey="elera_your_api_key"
      onComplete={(booking) => console.log('Booked!', booking)}
    >
      <BookingFlow />
    </EleraBookingProvider>
  );
}

function BookingFlow() {
  const { 
    steps,           // Steps controlled by Elera
    currentStep,     // Current step in the flow
    config,          // Flow configuration
    theme,           // Theme values for styling
    nextStep,
    prevStep,
    selectDate,
    selectTime,
    bookAppointment,
    getCopyText,     // Get customizable text
  } = useEleraBooking();

  return (
    <div style={{ fontFamily: theme.fontFamily }}>
      {/* Your custom UI using Elera's flow */}
      <StepIndicator steps={steps} current={currentStep} />
      
      {currentStep?.id === 'date' && (
        <YourDatePicker 
          daysToShow={config?.days_to_show} 
          onSelect={selectDate}
        />
      )}
      
      {/* ... other steps */}
      
      <button onClick={nextStep}>
        {getCopyText('nextButtonText', 'Continue')}
      </button>
    </div>
  );
}

Option 3: Headless SDK (Full Control)

import { EleraBooking } from '@elera/booking-sdk';

const booking = new EleraBooking('elera_your_api_key', {
  theme: {
    primaryColor: '#FF6B35',
    fontFamily: 'Poppins, sans-serif'
  }
});

// Initialize and get configuration
await booking.initialize();

// Get centrally-controlled flow configuration
const config = booking.getBookingFlowConfig();
console.log('Steps:', config.steps);
console.log('Days to show:', config.days_to_show);
console.log('Insurance enabled:', config.insurance_step_enabled);

// Get enabled steps in order
const steps = booking.getEnabledSteps();
// Returns: [{id: 'date', ...}, {id: 'time', ...}, ...]

// Get customizable copy text
const ctaText = booking.getCopyText('ctaText', 'Book Now');

// Check feature flags
if (booking.isFeatureEnabled('showPricing')) {
  // Show pricing
}

// Get availability
const availability = await booking.getAvailability({
  startDate: '2026-01-15',
  endDate: '2026-01-30'
});

// Book appointment
const result = await booking.bookAppointment({
  date: '2026-01-20',
  time: '10:00',
  patient: {
    firstName: 'John',
    lastName: 'Doe',
    email: '[email protected]',
    phone: '555-123-4567'
  }
});

How It Works

Who Controls What

| Aspect | Controlled By | How | |--------|---------------|-----| | Steps in flow | Elera (central) | config.steps | | Days to show | Elera (central) | config.days_to_show | | Insurance step | Elera (central) | config.insurance_step_enabled | | Button text | Elera (central) | config.copy.ctaText | | Colors | Provider (local) | CSS variables or theme config | | Fonts | Provider (local) | CSS variables or theme config | | Visual design | Provider (local) | Your own CSS/components |

Benefits

Elera updates flow → All provider sites get new behavior automatically
Add insurance step → Flip a switch, appears on all sites
Change copy/text → Updates everywhere instantly
Provider keeps brand → Their colors, fonts, design stay intact

CSS Variables Reference

Override these to match your brand:

:root {
  /* Colors */
  --elera-primary: #10b981;           /* Main brand color */
  --elera-primary-hover: #059669;     /* Hover state */
  --elera-text: #1f2937;              /* Text color */
  --elera-text-muted: #6b7280;        /* Secondary text */
  --elera-background: #ffffff;         /* Background */
  --elera-surface: #f9fafb;           /* Card/surface background */
  --elera-border: #e5e7eb;            /* Borders */
  --elera-error: #ef4444;             /* Error states */
  --elera-success: #22c55e;           /* Success states */
  
  /* Typography */
  --elera-font-family: system-ui, sans-serif;
  
  /* Shapes */
  --elera-border-radius: 12px;        /* Cards, containers */
  --elera-button-radius: 8px;         /* Buttons */
  --elera-input-radius: 8px;          /* Inputs */
}

API Reference

EleraBooking Class

Constructor

new EleraBooking(apiKey: string, config?: EleraBookingConfig)

| Parameter | Type | Description | |-----------|------|-------------| | apiKey | string | Your provider API key (starts with elera_) | | config.baseUrl | string | Override API URL (for testing) | | config.timeout | number | Request timeout in ms (default: 30000) | | config.theme | EleraTheme \| 'inherit' \| 'none' | Theme configuration | | config.enablePixel | boolean | Enable Meta Pixel tracking (default: true) | | config.onEvent | function | Event callback for analytics |

Methods

`initialize(): Promise<ProviderContext>`

Initialize the SDK and fetch provider/flow configuration.

`getBookingFlowConfig(): BookingFlowConfig | undefined`

Get the centrally-controlled flow configuration.

`getEnabledSteps(): BookingFlowStep[]`

Get enabled steps sorted by order.

`getCopyText(key: string, defaultValue?: string): string`

Get customizable copy text with fallback.

`isFeatureEnabled(feature: string): boolean`

Check if a feature flag is enabled.

`getTheme(): EleraTheme`

Get resolved theme (merged with defaults).

`applyThemeToElement(element: HTMLElement): void`

Apply theme as CSS variables to an element.

`getThemeCSS(): string`

Generate CSS string with all theme variables.

`getAvailability(options?): Promise<AvailabilityResponse>`

Get available time slots.

`bookAppointment(options): Promise<BookingResponse>`

Book an appointment.

`trackSlotSelected(date: string, time: string): string`

Track when a slot is selected.

BookingFlowConfig

interface BookingFlowConfig {
  steps: BookingFlowStep[];           // Flow steps
  days_to_show: number;               // Days in calendar (default: 14)
  max_days_out: number;               // Max booking horizon (default: 60)
  time_slot_interval_minutes: number; // Slot interval (default: 30)
  insurance_step_enabled: boolean;    // Show insurance step
  insurance_step_required: boolean;   // Require insurance
  intake_form_enabled: boolean;       // Show intake form
  copy: BookingFlowCopy;              // Customizable text
  features: BookingFlowFeatures;      // Feature flags
}

BookingFlowStep

interface BookingFlowStep {
  id: string;           // 'date' | 'time' | 'insurance' | 'contact' | 'confirm'
  title: string;        // Display title
  description?: string; // Optional description
  enabled: boolean;     // Is step enabled
  order: number;        // Order in flow (1-based)
  required?: boolean;   // Is step required
}

EleraTheme

interface EleraTheme {
  primaryColor?: string;
  primaryHoverColor?: string;
  textColor?: string;
  textMutedColor?: string;
  backgroundColor?: string;
  surfaceColor?: string;
  borderColor?: string;
  errorColor?: string;
  successColor?: string;
  fontFamily?: string;
  borderRadius?: string;
  buttonRadius?: string;
  inputRadius?: string;
}

React Hooks

useEleraBooking

Main hook for booking state and actions:

const {
  // State
  sdk,                // SDK instance
  providerContext,    // Provider metadata
  config,             // Flow configuration
  steps,              // Enabled steps
  currentStep,        // Current step
  currentStepIndex,   // Current step index
  theme,              // Resolved theme
  isLoading,          // Loading state
  error,              // Error if any
  isInitialized,      // SDK initialized
  availability,       // Available slots
  selectedDate,       // Selected date
  selectedTime,       // Selected time
  patientInfo,        // Patient info collected
  bookingResult,      // Booking result
  isBooking,          // Booking in progress
  
  // Actions
  goToStep,           // Go to step by id
  nextStep,           // Next step
  prevStep,           // Previous step
  canProceed,         // Can proceed to next
  selectDate,         // Select date and fetch availability
  selectTime,         // Select time slot
  updatePatientInfo,  // Update patient info
  bookAppointment,    // Complete booking
  reset,              // Reset flow
  getCopyText,        // Get copy text
  isFeatureEnabled,   // Check feature flag
  fetchAvailability,  // Fetch availability
} = useEleraBooking();

Helper Hooks

// Get just the theme
const theme = useEleraTheme();

// Get booking flow config
const config = useBookingFlowConfig();

// Get step navigation
const { currentStep, nextStep, prevStep, isLastStep } = useStepNavigation();

Widget Options

interface WidgetOptions {
  apiKey: string;                                    // Required
  config?: EleraBookingConfig;                       // SDK config
  onComplete?: (booking: BookingResponse) => void;  // Success callback
  onError?: (error: Error) => void;                 // Error callback
  onStepChange?: (step: BookingFlowStep) => void;   // Step change callback
  className?: string;                               // Custom CSS class
}

Analytics & Tracking

The SDK includes built-in Meta Pixel tracking:

| Event | When Fired | Data Included | |-------|------------|---------------| | PageView | After initialize() | Provider context | | ViewContent | After initialize() | Provider, specialty, state | | Schedule | When slot selected | Date, time, provider | | Lead | When booking completes | Appointment value, confirmation |

Events are automatically deduplicated between client-side Pixel and server-side Conversions API.

Getting Your API Key

Log in to your Elera Health provider dashboard
Go to Settings → API Keys
Click "Generate New Key"
Copy the key (starts with elera_)

Support

Documentation: https://docs.elera.com/sdk
Issues: https://github.com/elerahealth/booking-sdk/issues
Email: [email protected]

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme