Guides
Start typing to search…

b.well SDK for Web

Welcome to the b.well SDK for Web - a powerful, type-safe library for building applications that connect to the b.well Connected Health platform. This TypeScript SDK provides a comprehensive set of tools for managing health data, user profiles, appointments, and healthcare provider connections.

⚠️ Version Notice: This documentation reflects version 2.x of the b.well SDK for Web, which is currently in beta. Beta version is stable but potential breaking changes are still possible as continued feature additions/refinement occurs. GA release slated by end of year 2025.

📦 Installation

Install the SDK from NPM:

npm install @icanbwell/bwell-sdk-ts

NPM Package

🚀 Quick Links

✨ Features

The b.well SDK for Web provides everything you need to build health-focused applications:

  • 🔬 FHIR-compliant health data access - Retrieve patient health records using FHIR R4 standards
  • 🎯 Fluid API interface - Intuitive bwellSdk.manager.method() pattern for all operations
  • 📊 Comprehensive health data - Access to conditions, medications, labs, procedures, and more
  • 👤 User management - Profile management, consent handling, and identity verification
  • 🔗 Connection management - Seamless integration with external healthcare providers
  • 📅 Appointment management - Schedule, view, and manage healthcare appointments
  • 📝 Questionnaire processing - Handle dynamic questionnaire flows
  • ⚠️ Built-in error handling - Robust error handling with detailed error information
  • 🔐 Token management - Automatic token refresh and secure credential handling
  • 📈 Telemetry & logging - Comprehensive logging and optional telemetry
  • 🛠️ Full TypeScript support - Complete type safety with IntelliSense support

🏁 Getting Started

The BWellSDK is your main entry point and provides technical API reference documentation for all methods and configuration options.

💡 Tip: Check out our example repository for complete working examples and sample applications.

Quick Start

import { AppointmentsRequest, BWellSDK } from "@icanbwell/bwell-sdk-ts";

// 1. Initialize SDK
const sdk = new BWellSDK({
  clientKey: "YOUR_CLIENT_KEY",
});

// 2. Initialize and authenticate
await sdk.initialize();
await sdk.authenticate({ token: "YOUR_TOKEN" });

// 3. Use the fluid API with request objects
const conditions = await sdk.health.getConditions();
const profile = await sdk.user.getProfile();

// Methods that require parameters use request objects
const appointments = await sdk.healthSpace.getAppointments(
  new AppointmentsRequest({ status: "booked" }),
);

Error Handling

All SDK methods return BWellTransactionResult or BWellQueryResult objects that provide consistent error handling:

const result = await sdk.user.getProfile();

if (result.success()) {
  const profile = result.data();
  console.log("Profile:", profile);
} else {
  const error = result.error();
  console.error("Error:", error.message);
}

Configuration

The SDK supports various configuration options:

import { LogLevel } from "@icanbwell/bwell-sdk-ts";

const sdk = new BWellSDK({
  clientKey: "YOUR_CLIENT_KEY",
  logLevel: LogLevel.Info,
  retryPolicy: { attempts: 3, interval: 1000 },
  tokenStorage: customTokenStorage,
  language: "en", // or "es" for Spanish
});

🏗️ Key Components

  • BWellSDK - Main SDK class and entry point for all operations
  • HealthManager - Access to patient health records and clinical data
  • UserManager - User profile management, consent handling, and identity verification
  • HealthSpaceManager - Appointments, scheduling, and healthcare facility management
  • ConnectionManager - Data source connections and OAuth management for external providers
  • SearchManager - Healthcare provider and resource discovery, including provider directory search and submission
  • QuestionnaireManager - Dynamic questionnaire processing and response handling

🛠️ API Structure

The SDK uses a fluid API pattern where all functionality is accessed through manager properties:

const sdk = new BWellSDK({ clientKey: "YOUR_KEY" });
await sdk.initialize();
await sdk.authenticate({ token: "YOUR_TOKEN" });

// Access health data
const conditions = await sdk.health.getConditions();

// Manage user profile
const profile = await sdk.user.getProfile();

// Handle appointments with request objects
const appointments = await sdk.healthSpace.getAppointments(
  new AppointmentsRequest({ status: "booked" }),
);

📋 Request Objects

Many SDK methods accept request objects to provide structured parameters. These request objects:

  • ✅ Validate input - Ensure data correctness before sending to API
  • 🔒 Type safety - Provide full TypeScript support with IntelliSense
  • 📐 Standardize patterns - Consistent interface across all SDK methods

Request Object Examples

// Get appointments with specific criteria
const appointmentsRequest = new AppointmentsRequest({
  status: "booked",
  date: {
    start: "2024-01-01",
    end: "2024-12-31",
  },
  _count: 50,
});
const appointments = await sdk.healthSpace.getAppointments(appointmentsRequest);

// Cancel an appointment
const cancelRequest = new CancelAppointmentRequest({
  appointmentId: "appt-123",
  reason: "Patient requested cancellation",
});
const result = await sdk.healthSpace.cancelAppointment(cancelRequest);

// Search health data with filters
const conditionsRequest = new ConditionsRequest({
  category: "problem-list-item",
  _count: 25,
});
const conditions = await sdk.health.getConditions(conditionsRequest);

// Search for healthcare providers
const searchRequest = new SearchHealthResourcesRequest({
  searchTerm: "cardiologist",
  location: { city: "New York", state: "NY" },
  _count: 10,
});
const providers = await sdk.search.searchHealthResources(searchRequest);

Finding Request Objects

Request objects are available as named exports from the SDK and follow consistent naming patterns:

  • Method-specific requests: AppointmentsRequest, CancelAppointmentRequest
  • Data-specific requests: ConditionsRequest, LabsRequest, MedicationsRequest
  • Search-specific requests: SearchHealthResourcesRequest, SubmitProviderForReviewRequest
  • User-specific requests: UpdateProfileRequest, CreateConsentRequest
import {
  // Health Space requests
  AppointmentsRequest,
  BWellSDK,
  CancelAppointmentRequest,
  // Health Data requests
  ConditionsRequest,
  CreateConsentRequest,
  LabsRequest,
  // Search requests
  SearchHealthResourcesRequest,
  SubmitProviderForReviewRequest,
  // User Management requests
  UpdateProfileRequest,
} from "@icanbwell/bwell-sdk-ts";

Request Parameter Patterns

Most SDK methods follow these patterns:

  1. No parameters - Methods like getProfile(), getConditions() that return all available data
  2. Optional request object - Methods like getAppointments(request?) where filtering is optional
  3. Required request object - Methods like cancelAppointment(request) that require specific parameters

When a method requires a request object, TypeScript IntelliSense will show you the exact parameter type and available properties.

📚 Documentation & Resources

Ready to get started? Visit our example repository for step-by-step tutorials and sample applications, review the Method Guides or dive into the API documentation.

Updated 23 days ago

What’s Next