TypeScript 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:

1. Validates credentials with authentication strategy
2. Bootstraps authentication tokens
3. Initializes token management
4. 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:

1. Loads tokens from the configured token storage
2. Validates and bootstraps the loaded tokens
3. Refreshes access token to ensure validity
4. 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);
}