BioSDKClient

public final class BioSDKClient

public static let sdkVersion: String

public struct Configuration: Equatable {
    public let environment: Environment
    public let organizationKey: String?
    public let projectKey: String

    public init(
        environment: Environment = .auto,
        organizationKey: String? = nil,
        projectKey: String
    )

    public static func auto(
        organizationKey: String? = nil,
        projectKey: String
    ) -> Configuration
}

public enum Environment: Equatable {
    case auto
    case production
}

// Synchronous convenience initializer
public convenience init(configuration: Configuration)

// Async initializer — performs bootstrap (loads supported devices, org config)
public static func initialize(configuration: Configuration) async throws -> BioSDKClient

// Restore a previously persisted session (e.g., after background wake or app relaunch)
public static func restoreIfNeeded(isBackground: Bool = true) throws -> BioSDKClient?

let sdk = try await BioSDKClient.initialize(
    configuration: .auto(projectKey: "my-project")
)

// Start scanning for BLE devices
public func startScan()

// Stop scanning
public func stopScan()

// Connect to a discovered device
public func connect(_ device: BioDevice)

// Disconnect a specific device
public func disconnect(_ device: BioDevice)

// Disconnect all connected devices
public func disconnectAll()

// Start streaming for a specific device (by BLE UUID)
public func startStreaming(deviceId: UUID)

// Stop streaming for a specific device
public func stopStreaming(deviceId: UUID)

// Enable/disable auto-streaming on connect for a device
public func setAutoStream(deviceId: UUID, enabled: Bool)

// Query current connection + stream state for a device
public func deviceSessionState(deviceId: UUID) -> (BioConnectionState, BioStreamState)?

// Check if auto-stream is enabled for a device
public func autoStreamEnabled(deviceId: UUID) -> Bool?

// Enable or disable session mode
public func setSessionMode(enabled: Bool)

// Start a backend session for a user (with completion handler)
public func startStreaming(
    for xUser: String,
    completion: @escaping (Result<String, SessionStartDisposition>) -> Void
)

// Start a backend session (fire-and-forget)
public func startStreaming(for xUser: String)

// Start only the backend session (without triggering BLE streaming)
public func startBackendSession(
    for xUser: String,
    completion: @escaping (Result<String, SessionStartDisposition>) -> Void
)

// Stop all streaming and end the backend session
public func stopStreaming()

// End the active session without stopping BLE connections
public func endActiveSession()

// Check if the backend has an active session for the current user
public func checkForActiveSession() async throws -> Bool

// Detect an orphaned session from a previous app launch
public func detectOrphanedSession() async throws -> OrphanedSessionInfo?

// Resume an orphaned session
public func resumeOrphanedSession() async throws -> Bool

// End an orphaned session
public func endOrphanedSession()

// Resume the existing conflicting session
public func resumeConflictingSession()

// End the conflicting session and start a new one
public func endConflictingAndStartNew()

// Cancel the pending conflict without action
public func cancelPendingConflict()

public enum SessionStartDisposition: Error, Equatable {
    case new                                           // New session created
    case resumed                                       // Existing session resumed
    case conflict(activeId: String, startedAt: Date?)  // 409 conflict
}

// Activate a named streaming profile on a device
public func activateStreamingProfile(deviceId: UUID, profileName: String) async throws

// Deactivate the current streaming profile
public func deactivateStreamingProfile(deviceId: UUID, executeStop: Bool = true)

// List available streaming profiles for a device
public func getStreamingProfiles(deviceId: UUID) -> [StreamingProfileUI]

// Get the currently active profile name
public func activeStreamingProfile(deviceId: UUID) -> String?

// Get available operations for a device
public func getDeviceOperations(deviceId: UUID) -> [DeviceOperationUI]

// Execute a named operation (e.g., "start_ecg", "calibrate")
public func executeOperation(deviceId: UUID, operationName: String) async throws

// Upload a UIImage for a user
public func uploadImage(_ image: UIImage, userId: UUID) async throws

// Upload raw image data with a MIME type
public func uploadImageData(
    _ data: Data,
    mimeType: String,
    userId: UUID,
    deviceId: String? = nil
) async throws

// Create a new external user
public func createXUser(
    identifier: String,
    name: String
) async throws -> XUserHTTPClient.XUserResponse

// Get or create an external user (idempotent)
public func getOrCreateXUser(
    identifier: String,
    name: String
) async throws -> XUserHTTPClient.XUserResponse

// Look up an existing external user
public func getXUser(identifier: String) async throws -> XUserHTTPClient.XUserResponse

// Configure OAuth with a callback URL scheme
public func configureOAuth(
    callbackURLScheme: String,
    userTokenProvider: (() async -> String?)? = nil
)

// Connect an OAuth provider (opens ASWebAuthenticationSession)
public func connectOAuthProvider(
    _ provider: String,
    xuserId: String,
    presentationContextProvider: ASWebAuthenticationPresentationContextProviding
) async throws

// Check if a provider is connected
public func isOAuthProviderConnected(_ provider: String) -> Bool

// Disconnect a provider
public func disconnectOAuthProvider(_ provider: String)