@icanbwell/bwell-sdk-ts 2.0.0-alpha.0-rc.1754330797 → 2.0.0-alpha.0-rc.1754488327

package/dist/bwell-sdk/bwell-sdk.d.ts

@@ -1,86 +1,342 @@
 import { BaseManagerError } from "../api/base/errors.js";
 import { HealthManager } from "../api/base/health-data/index.js";
-import type { AuthTokens, CreateGuestAccessTokenResults } from "../api/base/identity/index.js";
 import { type Credentials } from "../auth/index.js";
 import { type BWellConfig } from "../config/index.js";
 import { BWellError, type AuthenticationError, type InvalidClientKeyError, type InvalidTokenError, type OperationOutcomeError } from "../errors/index.js";
 import { ConnectionManager, HealthSpaceManager, QuestionnaireManager, UserManager } from "../index.js";
+import { type LanguageManager } from "../language/index.js";
+import { AuthTokens, CreateGuestAccessTokenResults } from "../models/identity/index.js";
 import { BWellTransactionResult } from "../results/index.js";
-export { AuthTokens } from "../api/base/identity/index.js";
 /**
- * The BWell SDK is the main entry point for the SDK.
+ * # b.well SDK
  *
- * It is responsible for initializing the SDK, authenticating the user, and providing
- * access to all of the SDK's functionality via the manager classes (see [Interfaces](../README.md#interfaces)).
+ * 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)
+ * - Questionnaire processing (dynamic forms and responses)
+ *
+ * ## Basic Usage
  *
- * @example
- * Simple initialization with oauth authentication and only required config properties.
- * Note that the SDK must be initialized and authenticated for most data accessx
- * methods to work properly.
  * ```typescript
- * const sdk = new BWellSDK({
- *  clientKey: "YOUR_CLIENT_KEY",
- *  clientSecret: "YOUR_CLIENT_SECRET",
- * });
+ * 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 {@link HealthManager} for health data operations
+ * @see {@link UserManager} for user management operations
+ * @see {@link HealthSpaceManager} for appointment management
+ * @see {@link ConnectionManager} for provider connections
+ * @see {@link QuestionnaireManager} for questionnaire processing
+ *
+ 
+ * @class BWellSDK
+ * @category Core
+ * @title BWellSDK
+ * @excerpt Main entry point for interacting with the b.well Connected Health platform
  */
 export declare class BWellSDK {
     #private;
     constructor(config: BWellConfig);
     /**
-     * Initializes the SDK with the provided configuration.
-     * @returns A promise that resolves to a BWellTransactionResult with a null data value if the SDK was initialized successfully, or an error if it was not.
+     * ## 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
      * ```typescript
      * const sdk = new BWellSDK({
-     *  clientKey: "YOUR_CLIENT_KEY",
-     *  clientSecret: "YOUR_CLIENT_SECRET",
+     *   clientKey: "YOUR_CLIENT_KEY",
      * });
      *
-     * await sdk.initialize();
+     * const initResult = await sdk.initialize();
+     * if (initResult.success()) {
+     *   console.log("SDK initialized successfully");
+     * } else {
+     *   console.error("Failed to initialize SDK:", initResult.error().message);
+     * }
      * ```
      */
     initialize(): Promise<BWellTransactionResult<null, InvalidClientKeyError | OperationOutcomeError>>;
     /**
-     * Authenticates the user with the provided credentials.
-     * @param credentials The credentials to be used for authentication.
-     * @returns A promise that resolves to a BWellTransactionResult with a null data value if the user was authenticated successfully, or an error if they were not.
+     * ## 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)
+     *
+     * @param {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
      * ```typescript
      * const sdk = new BWellSDK({
-     *  clientKey: "YOUR_CLIENT_KEY",
-     *  clientSecret: "YOUR_CLIENT_SECRET",
+     *   clientKey: "YOUR_CLIENT_KEY",
      * });
      *
      * await sdk.initialize();
      *
-     * await sdk.authenticate({
-     *   token: "YOUR_TOKEN",
+     * 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);
+     * }
      * ```
      */
     authenticate(credentials: Credentials): Promise<BWellTransactionResult<null, AuthenticationError | InvalidTokenError>>;
     /**
-     * Sets auth tokens for a pre-authenticated user. Performs a token refresh to
-     * validate the provided tokens.
+     * ## 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
      *
-     * This can be used in place of `authenticate` for times when a user has been
-     * authenticated through means other than the SDK.
+     * **Token Validation:**
+     * - Validates token format and structure
+     * - Parses user information from ID token
+     * - Initializes token refresh mechanisms
+     *
+     * @param {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
      *
-     * @param {AuthTokens} authTokens - Auth tokens for pre-authenticated user
      * @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
+     * ```typescript
+     * 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
+     * }
+     * ```
      */
     setAuthTokens(authTokens: AuthTokens): Promise<BWellTransactionResult<null, OperationOutcomeError | 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, AuthenticationError | InvalidTokenError | BWellError>>}
+     *   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
+     * ```typescript
+     * 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" });
+     * }
+     * ```
+     */
     authenticateFromStorage(): Promise<BWellTransactionResult<null, AuthenticationError | InvalidTokenError | BWellError>>;
     /**
-     * Creates a set of guest access tokens (access, id, and refresh)
-     * @returns A promise that resolves to a BWellTransactionResult containing the guest access tokens or an error.
+     * ## 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
+     * ```typescript
+     * 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);
+     * }
+     * ```
      */
     createGuestAccessToken(): Promise<BWellTransactionResult<CreateGuestAccessTokenResults, BaseManagerError>>;
+    /**
+     * Health data manager for patient health records and clinical data access.
+     *
+     * @see {@link HealthManager} - Complete health data operations and examples
+     * @returns {HealthManager} The health data manager instance
+     * @category Managers
+     */
     get health(): HealthManager;
+    /**
+     * Health space manager for appointments, scheduling, and healthcare facility management.
+     *
+     * @see {@link HealthSpaceManager} - Complete appointment management operations and examples
+     * @returns {HealthSpaceManager} The health space manager instance
+     * @category Managers
+     */
     get healthSpace(): HealthSpaceManager;
+    /**
+     * User manager for profile management, consent handling, and identity verification.
+     *
+     * @see {@link UserManager} - Complete user management operations and examples
+     * @returns {UserManager} The user manager instance
+     * @category Managers
+     */
     get user(): UserManager;
+    /**
+     * Connection manager for data source connections and OAuth management.
+     *
+     * @see {@link ConnectionManager} - Complete connection management operations and examples
+     * @returns {ConnectionManager} The connection manager instance
+     * @category Managers
+     */
     get connection(): ConnectionManager;
-    get language(): import("../language/language-manager.js").LanguageManager;
+    /**
+     * Language manager for language and localization utilities.
+     *
+     * @see {@link LanguageManager} - Complete language and localization operations
+     * @returns {LanguageManager} The language manager instance
+     * @category Managers
+     */
+    get language(): LanguageManager;
+    /**
+     * Questionnaire manager for dynamic questionnaire processing and response handling.
+     *
+     * @experimental This manager and its methods are experimental and may change in future releases.
+     * @see {@link QuestionnaireManager} - Complete questionnaire processing operations and examples
+     * @returns {QuestionnaireManager} The questionnaire manager instance
+     * @category Managers
+     */
     get questionnaire(): QuestionnaireManager;
 }