b.well SDK

The b.well SDK is the main entry point for interacting with the b.well Connected Health platform.

Provides a comprehensive TypeScript/JavaScript interface with organized manager categories for:

Health data access (conditions, medications, labs, procedures)
User management (profiles, consent, identity verification)
Appointment management (scheduling, viewing, canceling)
Connection management (external healthcare providers)
Device management (push notifications, device registration)
Search operations (healthcare provider and resource discovery)
Questionnaire processing (dynamic forms and responses)

Basic Usage

import { BWellSDK } from '@bwell/sdk';

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

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

See

HealthManager for health data operations
UserManager for user management operations
HealthSpaceManager for appointment management
ConnectionManager for provider connections
DeviceManager for device management operations
SearchManager for search operations
QuestionnaireManager for questionnaire processing

BWellSDK

Constructors

Constructor

new BWellSDK(config): BWellSDK

Parameters

config

BWellConfig

Returns

BWellSDK

Managers

financial

Get Signature

get financial(): FinancialManager

Financial manager for insurance coverage and financial data access.

See

FinancialManager - Complete financial data operations and examples

Returns

FinancialManager

The financial manager instance

health

Get Signature

get health(): HealthManager

Health data manager for patient health records and clinical data access.

See

HealthManager - Complete health data operations and examples

Returns

HealthManager

The health data manager instance

healthSpace

Get Signature

get healthSpace(): HealthSpaceManager

Health space manager for appointments, scheduling, and healthcare facility management.

See

HealthSpaceManager - Complete appointment management operations and examples

Returns

HealthSpaceManager

The health space manager instance

user

Get Signature

get user(): UserManager

User manager for profile management, consent handling, and identity verification.

See

UserManager - Complete user management operations and examples

Returns

UserManager

The user manager instance

connection

Get Signature

get connection(): ConnectionManager

Connection manager for data source connections and OAuth management.

See

ConnectionManager - Complete connection management operations and examples

Returns

ConnectionManager

The connection manager instance

device

Get Signature

get device(): DeviceManager

Device manager for push notification registration and device management.

See

DeviceManager - Complete device management operations and examples

Returns

DeviceManager

The device manager instance

search

Get Signature

get search(): SearchManager

Search manager for healthcare provider and resource discovery.

See

SearchManager - Complete search operations and examples

Returns

SearchManager

The search manager instance

language

Get Signature

get language(): LanguageManager

Language manager for language and localization utilities.

See

LanguageManager - Complete language and localization operations

Returns

LanguageManager

The language manager instance

questionnaire

Get Signature

get questionnaire(): QuestionnaireManager

Experimental

Questionnaire manager for dynamic questionnaire processing and response handling.

This manager and its methods are experimental and may change in future releases.

See

QuestionnaireManager - Complete questionnaire processing operations and examples

Returns

QuestionnaireManager

The questionnaire manager instance

Other

initialize()

initialize(): Promise<BWellTransactionResult<null, InvalidClientKeyError | OperationOutcomeError>>

Initialize SDK

Initializes the SDK with the provided configuration. This method must be called before using any other SDK functionality.

Prerequisites:

Valid clientKey must be provided in the constructor
Network connectivity to b.well services

Post-initialization:

SDK configuration is validated and loaded
Base dependencies are initialized
Ready for authentication

Returns

Promise<BWellTransactionResult<null, InvalidClientKeyError | OperationOutcomeError>>

A promise that resolves to a BWellTransactionResult with:

null data on success
InvalidClientKeyError if client credentials are invalid
OperationOutcomeError if server-side initialization fails

Example

const sdk = new BWellSDK({
  clientKey: "YOUR_CLIENT_KEY",
});

const initResult = await sdk.initialize();
if (initResult.success()) {
  console.log("SDK initialized successfully");
} else {
  console.error("Failed to initialize SDK:", initResult.error().message);
}

authenticate()

authenticate(credentials): Promise<BWellTransactionResult<null, AuthenticationError | InvalidTokenError>>

Authenticate User

Authenticates the user with the provided credentials and prepares the SDK for data access operations.

Prerequisites:

SDK must be initialized via initialize()
Valid authentication credentials

Authentication Flow:

Validates credentials with authentication strategy
Bootstraps authentication tokens
Initializes token management
Prepares API providers for authenticated requests

Supported Credential Types:

Token-based authentication
OAuth credentials (depending on configuration)

Parameters

credentials

Credentials

The credentials to be used for authentication

Returns

Promise<BWellTransactionResult<null, AuthenticationError | InvalidTokenError>>

A promise that resolves to a BWellTransactionResult with:

null data on success
AuthenticationError if authentication fails
InvalidTokenError if provided tokens are invalid

Example

const sdk = new BWellSDK({
  clientKey: "YOUR_CLIENT_KEY",
});

await sdk.initialize();

const authResult = await sdk.authenticate({
  token: "YOUR_ACCESS_TOKEN",
});

if (authResult.success()) {
  console.log("Authentication successful");
  // Now you can use all SDK functionality
  const profile = await sdk.user.getProfile();
} else {
  console.error("Authentication failed:", authResult.error().message);
}

setAuthTokens()

setAuthTokens(authTokens): Promise<BWellTransactionResult<null, OperationOutcomeError | InvalidTokenError>>

Set Authentication Tokens

Sets auth tokens for a pre-authenticated user. This method performs token validation and can be used in place of authenticate() when tokens are obtained through external means.

Use Cases:

Integration with existing authentication systems
Server-side token management
Custom authentication flows

Token Validation:

Validates token format and structure
Parses user information from ID token
Initializes token refresh mechanisms

Parameters

authTokens

AuthTokens

Auth tokens for pre-authenticated user containing:

accessToken - Access token for API requests
idToken - ID token containing user information
refreshToken - Refresh token for token renewal

Returns

Promise<BWellTransactionResult<null, OperationOutcomeError | InvalidTokenError>>

A promise that resolves to a BWellTransactionResult with:

null data on success
OperationOutcomeError if server-side validation fails
InvalidTokenError if provided tokens are invalid or expired

Example

const sdk = new BWellSDK({
  clientKey: "YOUR_CLIENT_KEY",
});

await sdk.initialize();

// Use tokens obtained from external authentication
const tokenResult = await sdk.setAuthTokens({
  accessToken: "your-access-token",
  idToken: "your-id-token",
  refreshToken: "your-refresh-token"
});

if (tokenResult.success()) {
  console.log("Tokens set successfully");
  // SDK is now ready for use
}

authenticateFromStorage()

authenticateFromStorage(): Promise<BWellTransactionResult<null, BWellError | AuthenticationError | InvalidTokenError>>

Authenticate From Storage

Authenticates the user using tokens previously stored in the configured token storage. This method provides a convenient way to restore user sessions without requiring manual credential input.

Prerequisites:

SDK must be initialized via initialize()
tokenStorage must be configured in the BWell config
Valid tokens must exist in the configured storage

Authentication Flow:

Loads tokens from the configured token storage
Validates and bootstraps the loaded tokens
Refreshes access token to ensure validity
Prepares API providers for authenticated requests

Storage Integration:

Supports various storage backends (localStorage, secure storage, etc.)
Handles storage errors gracefully
Automatically validates token integrity

Returns

Promise<BWellTransactionResult<null, BWellError | AuthenticationError | InvalidTokenError>>

A promise that resolves to a BWellTransactionResult with:

null data on success
AuthenticationError if authentication process fails
InvalidTokenError if stored tokens are invalid or expired
BWellError if token storage is not configured

Example

const sdk = new BWellSDK({
  clientKey: "YOUR_CLIENT_KEY",
  tokenStorage: new LocalStorageTokenStorage() // or your storage implementation
});

await sdk.initialize();

// Attempt to authenticate from stored tokens
const authResult = await sdk.authenticateFromStorage();

if (authResult.success()) {
  console.log("Authentication from storage successful");
  // SDK is ready for use with restored session
  const profile = await sdk.user.getProfile();
} else {
  console.error("Authentication from storage failed:", authResult.error().message);
  // Fall back to manual authentication
  await sdk.authenticate({ token: "USER_PROVIDED_TOKEN" });
}

createGuestAccessToken()

createGuestAccessToken(): Promise<BWellTransactionResult<CreateGuestAccessTokenResults, BaseManagerError>>

Create Guest Access Token

Creates a guest access token that allows limited, anonymous access to certain b.well platform features without requiring user authentication. Guest tokens provide restricted access to public resources and non-sensitive operations.

Prerequisites:

SDK must be initialized via initialize()
Valid client key must be configured
Client must have guest access permissions enabled

Guest Access Capabilities:

Access to public health resources
Limited questionnaire functionality
Anonymous data queries (where permitted)
Public provider directory access

Limitations:

No access to personal health records
Cannot perform user-specific operations
Limited to read-only operations on public data
Tokens have shorter expiration times

Returns

Promise<BWellTransactionResult<CreateGuestAccessTokenResults, BaseManagerError>>

A promise that resolves to a BWellTransactionResult with:

CreateGuestAccessTokenResults containing the guest access token and metadata
BaseManagerError if token creation fails due to client configuration or server issues

Example

const sdk = new BWellSDK({
  clientKey: "YOUR_CLIENT_KEY",
});

await sdk.initialize();

// Create a guest access token for anonymous access
const guestTokenResult = await sdk.createGuestAccessToken();

if (guestTokenResult.success()) {
  const guestToken = guestTokenResult.data();
  console.log("Guest token created:", guestToken.accessToken);

  // Use the guest token for limited operations
  // Note: This doesn't automatically authenticate the SDK
  // You may need to use setAuthTokens() with appropriate tokens
} else {
  console.error("Failed to create guest token:", guestTokenResult.error().message);
}