@bodhiapp/bodhi-js 0.0.1

package/dist/bodhi-js-sdk/core/src/types/api.d.ts

@@ -0,0 +1,34 @@
+import { ApiResponse, OperationErrorResponse } from '../../../../bodhi-browser-ext/src/types';
+import { OpenAiApiError } from '@bodhiapp/ts-client';
+
+/**
+ * Public API result type - discriminated union without protocol fields
+ *
+ * This is the return type for sendApiRequest() and similar methods.
+ * Unlike ApiResponseMessage<T> (which includes type and requestId for internal routing),
+ * this is the clean public interface without protocol overhead.
+ *
+ * Usage:
+ *   if ('error' in result) → { error: OperationErrorResponse } (network/extension error)
+ *   if ('body' in result) → ApiResponse<T> (HTTP completed - check status for success/error)
+ */
+export type ApiResponseResult<T> = ApiResponse<T> | {
+    error: OperationErrorResponse;
+};
+/**
+ * Type guard for operation error response
+ */
+export declare function isApiResultOperationError<T>(result: ApiResponseResult<T>): result is {
+    error: OperationErrorResponse;
+};
+/**
+ * Type guard for API response (success or HTTP error)
+ */
+export declare function isApiResultSuccess<T>(result: ApiResponseResult<T>): result is ApiResponse<T> & {
+    body: T;
+    status: number;
+};
+export declare function isApiResultError<T>(result: ApiResponseResult<T>): result is ApiResponse<OpenAiApiError> & {
+    body: OpenAiApiError;
+    status: number;
+};

package/dist/bodhi-js-sdk/core/src/types/callback.d.ts

@@ -0,0 +1,23 @@
+import { ClientState } from './client-state';
+import { AuthState } from './user-info';
+
+/**
+ * Discriminated union for state changes.
+ * Allows single callback to handle both client state and auth state changes.
+ */
+export type ClientStateChange = {
+    type: 'client-state';
+    state: ClientState;
+};
+export type AuthStateChange = {
+    type: 'auth-state';
+    state: AuthState;
+};
+export type StateChange = ClientStateChange | AuthStateChange;
+/**
+ * Callback invoked when client state or auth state changes.
+ * Defaults to no-op if not provided.
+ */
+export type StateChangeCallback = (change: StateChange) => void;
+/** No-op callback for clients created without listener */
+export declare const NOOP_STATE_CALLBACK: StateChangeCallback;

package/dist/bodhi-js-sdk/core/src/types/client-state.d.ts

@@ -0,0 +1,191 @@
+import { OperationErrorResponse } from '../../../../bodhi-browser-ext/src/types';
+
+/**
+ * Serialized direct client state for persistence
+ * Stores minimal state needed to restore direct connection
+ */
+export type SerializedDirectState = {
+    url?: string;
+};
+/**
+ * Connection mode - how the client communicates with the local server
+ *
+ * - 'direct': Direct HTTP fetch to local server (requires LNA permission in web context,
+ *   but extension already has network access)
+ * - 'extension': Communication via extension (chrome.runtime or window.bodhiext)
+ */
+export type ConnectionMode = 'direct' | 'extension';
+/**
+ * Hardcoded error messages for server states
+ */
+export declare const SERVER_ERROR_CODES: {
+    readonly NOT_REACHABLE: {
+        readonly message: "server is not reachable on given url";
+        readonly type: "network_error";
+    };
+    readonly SERVER_NOT_READY: {
+        readonly message: "server is not in ready state, configure to complete setup";
+        readonly type: "extension_error";
+    };
+};
+export declare const BACKEND_SERVER_NOT_REACHABLE: BackendServerNotReachableState;
+/**
+ * Server is ready - no error field
+ */
+export interface BackendServerReadyState {
+    status: 'ready';
+    version: string;
+}
+/**
+ * Server is reachable but needs configuration - has error details
+ * error code: 'server-not-ready'
+ */
+export interface BackendServerNotReadyState {
+    status: 'setup' | 'resource-admin' | 'error';
+    version: string;
+    error: OperationErrorResponse;
+}
+/**
+ * Server is not reachable - network/connection failure
+ * error code: 'not-reachable'
+ */
+export interface BackendServerNotReachableState {
+    status: 'not-reachable';
+    error: OperationErrorResponse;
+}
+/**
+ * Backend server state from /bodhi/v1/info endpoint
+ * Discriminated union with definite fields per state
+ * Different from setup-modal's ServerState which includes UI states
+ */
+export type BackendServerState = BackendServerReadyState | BackendServerNotReadyState | BackendServerNotReachableState;
+/**
+ * State indicating extension is ready but server state is pending
+ */
+export interface PendingExtensionReadyState {
+    status: 'pending-extension-ready';
+}
+export declare const PENDING_EXTENSION_READY: PendingExtensionReadyState;
+/**
+ * State indicating direct connection not yet established
+ */
+export interface BackendServerNotConnectedState {
+    status: 'not-connected';
+}
+export declare const BACKEND_SERVER_NOT_CONNECTED: BackendServerNotConnectedState;
+/**
+ * Raw response from /bodhi/v1/info endpoint
+ */
+export interface ServerInfoResponse {
+    status: 'setup' | 'ready' | 'resource-admin' | 'error';
+    version?: string;
+    error?: OperationErrorResponse;
+}
+export declare function isServerReady(state: BackendServerState): state is BackendServerReadyState;
+export declare function backendServerNotReady(status: 'setup' | 'resource-admin' | 'error', version?: string, error?: OperationErrorResponse): BackendServerNotReadyState;
+/**
+ * ClientState - Unified state for extension or direct connectivity
+ * Discriminated union with type field: 'extension' | 'direct'
+ */
+export type ClientState = ExtensionState | DirectState;
+/**
+ * Serialized client state for localStorage persistence
+ * Nested structure storing each client's state separately
+ * Server state is transient and not persisted
+ */
+export type SerializedExtensionState = Record<string, unknown>;
+export interface SerializedClientState {
+    connectionMode: ConnectionMode | null;
+    direct: SerializedDirectState;
+    extension: SerializedExtensionState;
+}
+/**
+ * Parameters for client initialization
+ * Unified interface with priority handling:
+ * - Explicit params (serverUrl, timeoutMs) take priority over savedState
+ * - selectedConnection: true → initialize client (get handle/set url), server stays 'not-initialized'
+ * - testConnection: true → also test backend server connectivity and update server state
+ */
+export interface InitParams {
+    savedState?: Record<string, unknown>;
+    selectedConnection?: boolean;
+    testConnection?: boolean;
+    serverUrl?: string;
+    timeoutMs?: number;
+    intervalMs?: number;
+}
+export declare function isExtensionState(state: ClientState): state is ExtensionState;
+export declare function isDirectState(state: ClientState): state is DirectState;
+export interface DirectStateNotInitialized {
+    type: 'direct';
+    server: BackendServerNotConnectedState;
+}
+export interface DirectStateInitialized {
+    type: 'direct';
+    url: string;
+    server: BackendServerNotConnectedState | BackendServerState;
+}
+export interface DirectStateReady {
+    type: 'direct';
+    url: string;
+    server: BackendServerReadyState;
+}
+export interface DirectStateNotReachable {
+    type: 'direct';
+    url: string;
+    server: BackendServerNotReachableState;
+}
+export interface DirectStateNotReady {
+    type: 'direct';
+    url: string;
+    server: BackendServerNotReadyState;
+}
+export type DirectState = DirectStateNotInitialized | DirectStateInitialized | DirectStateReady | DirectStateNotReachable | DirectStateNotReady;
+export declare function isDirectServerReady(state: DirectState): state is DirectStateReady;
+export declare function isDirectClientReady(state: DirectState): state is DirectStateInitialized | DirectStateReady | DirectStateNotReachable | DirectStateNotReady;
+export declare const DIRECT_STATE_NOT_INITIALIZED: DirectStateNotInitialized;
+export declare function createDirectStateReady(url: string, version?: string): DirectStateReady;
+export declare function createDirectStateNotReachable(url: string): DirectStateNotReachable;
+export declare function createDirectStateNotReady(url: string, server: BackendServerNotReadyState): DirectStateNotReady;
+export declare const EXTENSION_STATE_NOT_INITIALIZED: ExtensionState;
+export declare const EXTENSION_STATE_NOT_FOUND: ExtensionState;
+export interface ExtensionStateNotInitialized {
+    type: 'extension';
+    extension: 'not-initialized';
+    server: PendingExtensionReadyState;
+}
+export interface ExtensionStateNotFound {
+    type: 'extension';
+    extension: 'not-found';
+    server: PendingExtensionReadyState;
+}
+export interface ExtensionStateReady {
+    type: 'extension';
+    extension: 'ready';
+    extensionId: string;
+    server: PendingExtensionReadyState | BackendServerState;
+}
+export type ExtensionState = ExtensionStateNotInitialized | ExtensionStateNotFound | ExtensionStateReady;
+export declare function isExtensionServerReady(state: ExtensionState): state is ExtensionStateReady;
+export declare function isExtensionClientReady(state: ExtensionState): state is ExtensionStateReady;
+export declare function createExtensionStateNotInitialized(): ExtensionStateNotInitialized;
+export declare function createExtensionStateNotFound(): ExtensionStateNotFound;
+/**
+ * Check if client is ready (has handle/url) - does NOT require server ready
+ * Use this for auth checks and reload state checks
+ */
+export declare function isClientReady(state: ClientState): boolean;
+/**
+ * Get backend server state from client state
+ */
+export declare function getBackendServerState(state: ClientState): BackendServerState | PendingExtensionReadyState | BackendServerNotConnectedState;
+/**
+ * Safely get extension ID from client state
+ * @returns Extension ID if state is ExtensionStateReady, undefined otherwise
+ */
+export declare function getExtensionId(state: ClientState): string | undefined;
+/**
+ * Safely get server URL from client state
+ * @returns Server URL if state is DirectState with URL, undefined otherwise
+ */
+export declare function getServerUrl(state: ClientState): string | undefined;

package/dist/bodhi-js-sdk/core/src/types/config.d.ts

@@ -0,0 +1,26 @@
+import { UserScope } from './user-info';
+
+/**
+ * Log levels for client logging
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Extension discovery result
+ */
+export interface DiscoveryResult {
+    success: boolean;
+    extensionId?: string;
+    error?: string;
+}
+/**
+ * Client configuration
+ */
+export interface ClientConfig {
+    authServerUrl?: string;
+    userScope?: UserScope;
+    extensionId?: string;
+    logLevel?: LogLevel;
+    discoveryAttempts?: number;
+    discoveryAttemptWaitMs?: number;
+    discoveryAttemptTimeout?: number;
+}

package/dist/bodhi-js-sdk/core/src/types/html.d.ts

@@ -0,0 +1,9 @@
+declare module '*.html' {
+  const content: string;
+  export default content;
+}
+
+declare module '*.html?raw' {
+  const content: string;
+  export default content;
+}

package/dist/bodhi-js-sdk/core/src/types/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared types used by both ext2ext and web2ext clients
+ */
+export { isApiResultError, isApiResultOperationError, isApiResultSuccess } from './api';
+export type { ApiResponseResult } from './api';
+export { createApiError, createOperationError } from '../errors';
+export { BACKEND_SERVER_NOT_CONNECTED, BACKEND_SERVER_NOT_REACHABLE, backendServerNotReady, createDirectStateNotReachable, createDirectStateNotReady, createDirectStateReady, createExtensionStateNotFound, createExtensionStateNotInitialized, DIRECT_STATE_NOT_INITIALIZED, EXTENSION_STATE_NOT_FOUND, EXTENSION_STATE_NOT_INITIALIZED, getBackendServerState, getExtensionId, getServerUrl, isClientReady, isDirectClientReady, isDirectServerReady, isDirectState, isExtensionClientReady, isExtensionServerReady, isExtensionState, isServerReady, PENDING_EXTENSION_READY, SERVER_ERROR_CODES, } from './client-state';
+export type { BackendServerNotConnectedState, BackendServerNotReachableState, BackendServerNotReadyState, BackendServerReadyState, BackendServerState, ClientState, ConnectionMode, DirectState, DirectStateNotInitialized, DirectStateNotReachable, DirectStateNotReady, DirectStateReady, ExtensionState, ExtensionStateNotFound, ExtensionStateNotInitialized, ExtensionStateReady, InitParams, PendingExtensionReadyState, SerializedClientState, SerializedDirectState, SerializedExtensionState, ServerInfoResponse, } from './client-state';
+export { AUTH_CLIENT_NOT_INITIALIZED as AUTH_EXT_NOT_INITIALIZED, isAuthError, isAuthLoggedIn, isAuthLoggedOut, } from './user-info';
+export type { AuthLoggedIn, AuthLoggedOut, AuthState, Tokens, UserInfo, UserScope, } from './user-info';
+export type { ClientConfig, DiscoveryResult, LogLevel } from './config';
+export type { BrowserInfo, OSInfo } from './platform';
+export { NOOP_STATE_CALLBACK } from './callback';
+export type { AuthStateChange, ClientStateChange, StateChange, StateChangeCallback, } from './callback';
+export { buildError, buildEvent, buildResponse, handleRequest } from '../onboarding/protocol-utils';

package/dist/bodhi-js-sdk/core/src/types/platform.d.ts

@@ -0,0 +1,16 @@
+import { BrowserType, OSType } from '../../../../setup-modal/src/types';
+
+/**
+ * Browser detection result
+ */
+export interface BrowserInfo {
+    name: string;
+    type: BrowserType;
+}
+/**
+ * Operating system detection result
+ */
+export interface OSInfo {
+    name: string;
+    type: OSType;
+}

package/dist/bodhi-js-sdk/core/src/types/user-info.d.ts

@@ -0,0 +1,59 @@
+/**
+ * User and authentication related types
+ */
+/**
+ * User scope types for regular and power users
+ */
+export type UserScope = 'scope_user_user' | 'scope_user_power_user';
+/**
+ * User information from OAuth
+ */
+export interface UserInfo {
+    sub: string;
+    email: string;
+    name: string;
+    given_name: string;
+    family_name: string;
+    preferred_username: string;
+}
+/**
+ * OAuth tokens
+ */
+export interface Tokens {
+    accessToken: string;
+    refreshToken?: string;
+    idToken?: string;
+    expiresIn: number;
+}
+/**
+ * Authentication state when user is logged in
+ */
+export interface AuthLoggedIn {
+    isLoggedIn: true;
+    userInfo: UserInfo;
+    accessToken: string;
+}
+/**
+ * Authentication state when user is logged out
+ */
+export interface AuthLoggedOut {
+    isLoggedIn: false;
+}
+/**
+ * Authentication state when there is an error
+ */
+export interface AuthError {
+    isLoggedIn: false;
+    error: {
+        message: string;
+        code: string;
+    };
+}
+export declare const AUTH_CLIENT_NOT_INITIALIZED: AuthError;
+export declare function isAuthError(state: unknown): state is AuthError;
+export declare function isAuthLoggedOut(state: unknown): state is AuthLoggedOut;
+export declare function isAuthLoggedIn(state: unknown): state is AuthLoggedIn;
+/**
+ * Authentication state (discriminated union)
+ */
+export type AuthState = AuthLoggedIn | AuthLoggedOut | AuthError;

package/dist/bodhi-js-sdk/web/src/constants.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Constants for web2ext communication
+ */
+export declare const POLL_INTERVAL = 500;
+export declare const POLL_TIMEOUT = 5000;
+/**
+ * LocalStorage keys for OAuth tokens and PKCE flow (namespaced with 'bodhi:web' prefix)
+ */
+export declare const STORAGE_KEYS: import('../../core/src/index.ts').StorageKeys;

package/dist/bodhi-js-sdk/web/src/direct-client.d.ts

@@ -0,0 +1,24 @@
+import { DirectClientBase, AuthLoggedIn, AuthLoggedOut, DirectClientBaseConfig, StateChangeCallback } from '../../core/src/index.ts';
+
+/**
+ * Configuration for DirectWebClient
+ */
+export interface DirectWebClientConfig extends DirectClientBaseConfig {
+    redirectUri: string;
+}
+/**
+ * DirectWebClient - Web mode implementation using browser redirect OAuth
+ */
+export declare class DirectWebClient extends DirectClientBase {
+    private redirectUri;
+    constructor(config: DirectWebClientConfig, onStateChange?: StateChangeCallback);
+    login(): Promise<AuthLoggedIn>;
+    handleOAuthCallback(code: string, state: string): Promise<AuthLoggedIn>;
+    logout(): Promise<AuthLoggedOut>;
+    protected requestResourceAccess(): Promise<string>;
+    protected exchangeCodeForTokens(code: string): Promise<void>;
+    protected _storageGet(key: string): Promise<string | null>;
+    protected _storageSet(items: Record<string, string | number>): Promise<void>;
+    protected _storageRemove(keys: string[]): Promise<void>;
+    protected _getRedirectUri(): string;
+}

package/dist/bodhi-js-sdk/web/src/ext-client.d.ts

@@ -0,0 +1,151 @@
+import { ApiResponseResult, AuthLoggedIn, AuthLoggedOut, AuthState, BackendServerState, ClientState, ExtensionState, IExtensionClient, InitParams, StateChangeCallback } from '../../core/src/index.ts';
+import { CreateChatCompletionStreamResponse } from '@bodhiapp/ts-client';
+import { WebClientConfig } from './facade-client';
+
+export type SerializedWebExtensionState = {
+    extensionId?: string;
+};
+/**
+ * WindowBodhiextClient - web mode extension client using window.bodhiext
+ *
+ * Communicates with bodhi-browser-ext via window.bodhiext API
+ *
+ * Implements IExtensionClient interface with state callback for state changes
+ * Additionally provides handleOAuthCallback for web-specific OAuth flow
+ *
+ */
+export declare class WindowBodhiextClient implements IExtensionClient {
+    private state;
+    private logger;
+    private bodhiext;
+    private authClientId;
+    private config;
+    private authEndpoints;
+    private onStateChange;
+    private refreshPromise;
+    constructor(authClientId: string, config: WebClientConfig, onStateChange?: StateChangeCallback);
+    /**
+     * Set client state and notify callback
+     */
+    private setState;
+    /**
+     * Set auth state and notify callback
+     */
+    private setAuthState;
+    /**
+     * Set or update the state change callback
+     */
+    setStateCallback(callback: StateChangeCallback): void;
+    /**
+     * Ensure bodhiext is available, attempting to acquire it if not already set
+     * @throws Error if client not initialized
+     */
+    private ensureBodhiext;
+    /**
+     * Send extension request via window.bodhiext.sendExtRequest
+     */
+    sendExtRequest<TParams = void, TRes = unknown>(action: string, params?: TParams): Promise<TRes>;
+    /**
+     * Send API message via window.bodhiext.sendApiRequest
+     * Converts ApiResponse to ApiResponseResult
+     */
+    sendApiRequest<TReq = void, TRes = unknown>(method: string, endpoint: string, body?: TReq, headers?: Record<string, string>, authenticated?: boolean): Promise<ApiResponseResult<TRes>>;
+    /**
+     * Get current client state
+     */
+    getState(): ClientState;
+    isClientInitialized(): boolean;
+    isServerReady(): boolean;
+    /**
+     * Initialize extension discovery with optional timeout
+     * Returns ExtensionState with extension and server status
+     *
+     * Note: Web mode uses stateless discovery (always polls for window.bodhiext)
+     * No extensionId storage/restoration needed - window.bodhiext handle is ephemeral
+     */
+    init(params?: InitParams): Promise<ExtensionState>;
+    /**
+     * Request resource access scope from backend
+     * Required for authenticated API access
+     */
+    private requestResourceAccess;
+    /**
+     * Login via browser redirect OAuth2 + PKCE flow
+     * @returns AuthLoggedIn (though in practice, this redirects and never returns)
+     */
+    login(): Promise<AuthLoggedIn>;
+    /**
+     * Handle OAuth callback with authorization code
+     * Should be called from callback page with extracted URL params
+     * @returns AuthLoggedIn with login state and user info
+     */
+    handleOAuthCallback(code: string, state: string): Promise<AuthLoggedIn>;
+    /**
+     * Exchange authorization code for tokens
+     */
+    private exchangeCodeForTokens;
+    /**
+     * Logout user and revoke tokens
+     * @returns AuthLoggedOut with logged out state
+     */
+    logout(): Promise<AuthLoggedOut>;
+    /**
+     * Get current authentication state
+     */
+    getAuthState(): Promise<AuthState>;
+    /**
+     * Get current access token
+     * Returns null if not logged in or token expired
+     */
+    protected _getAccessTokenRaw(): Promise<string | null>;
+    /**
+     * Try to refresh access token using refresh token
+     * Race condition prevention: Returns existing promise if refresh already in progress
+     */
+    private _tryRefreshToken;
+    /**
+     * Perform the actual token refresh
+     */
+    private _doRefreshToken;
+    /**
+     * Store refreshed tokens
+     */
+    private _storeRefreshedTokens;
+    /**
+     * Ping API
+     */
+    pingApi(): Promise<ApiResponseResult<{
+        message: string;
+    }>>;
+    /**
+     * Fetch models
+     */
+    fetchModels(): Promise<ApiResponseResult<{
+        data: Array<{
+            id: string;
+            object: string;
+        }>;
+    }>>;
+    /**
+     * Get backend server state
+     * Calls /bodhi/v1/info and returns structured server state
+     */
+    getServerState(): Promise<BackendServerState>;
+    /**
+     * Generic streaming via window.bodhiext.sendStreamRequest
+     * Wraps ReadableStream as AsyncGenerator
+     */
+    stream<TReq = unknown, TRes = unknown>(method: string, endpoint: string, body?: TReq, headers?: Record<string, string>, authenticated?: boolean): AsyncGenerator<TRes>;
+    /**
+     * Chat streaming
+     */
+    streamChat(model: string, prompt: string, authenticated?: boolean): AsyncGenerator<CreateChatCompletionStreamResponse>;
+    /**
+     * Serialize web extension client state (all transient, nothing to persist)
+     */
+    serialize(): SerializedWebExtensionState;
+    /**
+     * Debug dump of WindowBodhiextClient internal state
+     */
+    debug(): Promise<Record<string, unknown>>;
+}

package/dist/bodhi-js-sdk/web/src/facade-client.d.ts

@@ -0,0 +1,43 @@
+import { BaseFacadeClient, Logger, AuthLoggedIn, IWebUIClient, LogLevel, StateChange, StateChangeCallback, UserScope } from '../../core/src/index.ts';
+import { DirectWebClient } from './direct-client';
+import { WindowBodhiextClient } from './ext-client';
+
+/**
+ * Configuration for WebClient OAuth
+ */
+export interface WebClientConfig {
+    authServerUrl: string;
+    redirectUri: string;
+    userScope: UserScope;
+    logLevel: LogLevel;
+    initParams?: {
+        extension?: {
+            timeoutMs?: number;
+            intervalMs?: number;
+        };
+    };
+}
+/**
+ * WebUIClient - Public facade for web mode
+ *
+ * Automatically switches between DirectClient and InternalWebUIClient
+ * based on stored user preferences.
+ */
+export declare class WebUIClient extends BaseFacadeClient<WebClientConfig, WindowBodhiextClient, DirectWebClient> implements IWebUIClient {
+    constructor(authClientId: string, config: {
+        redirectUri: string;
+        authServerUrl?: string;
+        userScope?: UserScope;
+        logLevel?: LogLevel;
+        initParams?: {
+            extension?: {
+                timeoutMs?: number;
+                intervalMs?: number;
+            };
+        };
+    }, onStateChange?: StateChangeCallback, storagePrefix?: string);
+    protected createLogger(config: WebClientConfig): Logger;
+    protected createExtClient(config: WebClientConfig, onStateChange: (change: StateChange) => void): WindowBodhiextClient;
+    protected createDirectClient(authClientId: string, config: WebClientConfig, onStateChange: (change: StateChange) => void): DirectWebClient;
+    handleOAuthCallback(code: string, state: string): Promise<AuthLoggedIn>;
+}

package/dist/bodhi-js-sdk/web/src/index.d.ts

@@ -0,0 +1,5 @@
+import { SerializedWebExtensionState } from './ext-client';
+import { IWebUIClient } from './interface';
+
+export { WebUIClient } from './facade-client';
+export type { IWebUIClient, SerializedWebExtensionState };

package/dist/bodhi-js-sdk/web/src/interface.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Re-export IWebUIClient from core (internal monorepo package)
+ */
+export type { IWebUIClient } from '../../core/src/index.ts';