@computesdk/provider 1.0.33 → 1.2.0

package/dist/index.d.mts

@@ -405,6 +405,323 @@ interface StorageProvider {
     list(bucket: string, options?: ListOptions): Promise<ListResult>;
 }
 
+/**
+ * Browser Provider Types
+ *
+ * Types for browser providers (Browserbase, Kernel, etc.)
+ * Browser providers manage cloud browser sessions, distinct from sandbox providers
+ * which manage code execution environments.
+ */
+/**
+ * Browser session info returned from provider APIs
+ */
+interface BrowserSession {
+    /** Unique session identifier */
+    sessionId: string;
+    /** CDP or WebSocket connection URL */
+    connectUrl: string;
+    /** Current session status */
+    status: 'created' | 'running' | 'completed' | 'failed' | 'timed_out';
+    /** Session creation timestamp */
+    createdAt?: Date;
+    /** Provider-specific metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Options for creating a browser session
+ */
+interface CreateBrowserSessionOptions {
+    /** Proxy configuration — true for provider default, or detailed config */
+    proxies?: boolean | ProxyConfig[];
+    /** Browser viewport dimensions */
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    /** Session timeout in seconds */
+    timeout?: number;
+    /** Keep session alive after script disconnects */
+    keepAlive?: boolean;
+    /** Enable session recording (default: true) */
+    recording?: boolean;
+    /** Enable session logging (default: true) */
+    logging?: boolean;
+    /** Enable stealth/anti-detection mode */
+    stealth?: boolean;
+    /** Browser profile/context ID for session persistence */
+    profileId?: string;
+    /** Extension IDs to load */
+    extensionIds?: string[];
+    /** Region/datacenter preference */
+    region?: string;
+    /** Custom user metadata */
+    userMetadata?: Record<string, string>;
+}
+/**
+ * Proxy configuration for browser sessions
+ */
+interface ProxyConfig {
+    /** Proxy type */
+    type: 'residential' | 'isp' | 'datacenter' | 'custom';
+    /** Proxy server URL (for custom type) */
+    server?: string;
+    /** Proxy username */
+    username?: string;
+    /** Proxy password */
+    password?: string;
+    /** Geolocation targeting */
+    geolocation?: {
+        country?: string;
+        state?: string;
+        city?: string;
+    };
+    /** Domain pattern to route through this proxy */
+    domainPattern?: string;
+}
+/**
+ * Browser profile (persistent context — cookies, storage, etc.)
+ */
+interface BrowserProfile {
+    /** Unique profile identifier */
+    profileId: string;
+    /** Human-readable name */
+    name?: string;
+    /** Creation timestamp */
+    createdAt?: Date;
+    /** Provider-specific metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Options for creating a browser profile
+ */
+interface CreateBrowserProfileOptions {
+    /** Human-readable name */
+    name?: string;
+    /** Custom metadata */
+    metadata?: Record<string, string>;
+}
+/**
+ * Browser extension
+ */
+interface BrowserExtension {
+    /** Unique extension identifier */
+    extensionId: string;
+    /** Extension name */
+    name?: string;
+}
+/**
+ * Options for uploading/creating a browser extension
+ */
+interface CreateBrowserExtensionOptions {
+    /** Extension file data */
+    file: Uint8Array | string;
+    /** Extension name */
+    name?: string;
+}
+/**
+ * Browser pool — pre-warmed browser instances for instant acquisition
+ */
+interface BrowserPool {
+    /** Unique pool identifier */
+    poolId: string;
+    /** Pool name */
+    name?: string;
+    /** Number of idle instances ready */
+    idleCount?: number;
+    /** Number of active instances in use */
+    activeCount?: number;
+}
+/**
+ * Options for creating a browser pool
+ */
+interface CreateBrowserPoolOptions {
+    /** Pool name */
+    name: string;
+    /** Desired number of pre-warmed instances */
+    size: number;
+    /** Default session options for pool instances */
+    sessionDefaults?: CreateBrowserSessionOptions;
+}
+/**
+ * Browser session log entry
+ */
+interface BrowserLog {
+    /** Timestamp */
+    timestamp: Date;
+    /** Log level */
+    level: 'info' | 'warn' | 'error' | 'debug';
+    /** Log message */
+    message: string;
+    /** Additional structured data */
+    data?: Record<string, unknown>;
+}
+/**
+ * Browser session recording
+ */
+interface BrowserRecording {
+    /** Recording identifier */
+    recordingId: string;
+    /** Session this recording belongs to */
+    sessionId: string;
+    /** Recording format */
+    format: 'rrweb' | 'mp4' | string;
+    /** URL to access the recording */
+    url?: string;
+    /** Raw recording data */
+    data?: unknown;
+}
+/**
+ * Screenshot options
+ */
+interface ScreenshotOptions {
+    /** Image format */
+    format?: 'png' | 'jpeg' | 'webp';
+    /** Quality (0-100, for jpeg/webp) */
+    quality?: number;
+    /** Capture full scrollable page */
+    fullPage?: boolean;
+    /** CSS selector to capture */
+    selector?: string;
+}
+/**
+ * PDF generation options
+ */
+interface PdfOptions {
+    /** Paper format */
+    format?: 'letter' | 'legal' | 'a4' | 'a3';
+    /** Print background graphics */
+    printBackground?: boolean;
+    /** Landscape orientation */
+    landscape?: boolean;
+}
+/**
+ * Browser session manager — core lifecycle operations
+ */
+interface BrowserSessionManager<TSession = any> {
+    /** Create a new browser session */
+    create(options?: CreateBrowserSessionOptions): Promise<ProviderBrowserSession<TSession>>;
+    /** Get an existing session by ID */
+    getById(sessionId: string): Promise<ProviderBrowserSession<TSession> | null>;
+    /** List active sessions */
+    list(): Promise<ProviderBrowserSession<TSession>[]>;
+    /** Destroy/terminate a session */
+    destroy(sessionId: string): Promise<void>;
+}
+/**
+ * Browser profile manager
+ */
+interface BrowserProfileManager {
+    /** Create a new profile */
+    create(options?: CreateBrowserProfileOptions): Promise<BrowserProfile>;
+    /** Get an existing profile */
+    get(profileId: string): Promise<BrowserProfile | null>;
+    /** List profiles */
+    list(): Promise<BrowserProfile[]>;
+    /** Delete a profile */
+    delete(profileId: string): Promise<void>;
+}
+/**
+ * Browser extension manager
+ */
+interface BrowserExtensionManager {
+    /** Upload/create an extension */
+    create(options: CreateBrowserExtensionOptions): Promise<BrowserExtension>;
+    /** Get an extension by ID */
+    get(extensionId: string): Promise<BrowserExtension | null>;
+    /** Delete an extension */
+    delete(extensionId: string): Promise<void>;
+}
+/**
+ * Browser pool manager (pre-warmed instances)
+ */
+interface BrowserPoolManager<TSession = any> {
+    /** Create a new pool */
+    create(options: CreateBrowserPoolOptions): Promise<BrowserPool>;
+    /** Get pool by ID */
+    get(poolId: string): Promise<BrowserPool | null>;
+    /** List pools */
+    list(): Promise<BrowserPool[]>;
+    /** Acquire a browser from the pool */
+    acquire(poolId: string): Promise<ProviderBrowserSession<TSession>>;
+    /** Release a browser back to the pool */
+    release(poolId: string, sessionId: string): Promise<void>;
+    /** Delete a pool */
+    delete(poolId: string): Promise<void>;
+}
+/**
+ * Browser log manager
+ */
+interface BrowserLogManager {
+    /** Get logs for a session */
+    list(sessionId: string): Promise<BrowserLog[]>;
+}
+/**
+ * Browser recording manager
+ */
+interface BrowserRecordingManager {
+    /** Get recording for a session */
+    get(sessionId: string): Promise<BrowserRecording | null>;
+}
+/**
+ * Browser page operations — native browser control (optional, provider-dependent)
+ */
+interface BrowserPageOperations<TSession = any> {
+    /** Navigate to a URL */
+    navigate(session: TSession, url: string): Promise<void>;
+    /** Take a screenshot */
+    screenshot(session: TSession, options?: ScreenshotOptions): Promise<Uint8Array>;
+    /** Generate a PDF */
+    pdf?(session: TSession, options?: PdfOptions): Promise<Uint8Array>;
+    /** Evaluate JavaScript in the page context */
+    evaluate(session: TSession, script: string): Promise<unknown>;
+    /** Get the current page HTML */
+    getContent(session: TSession): Promise<string>;
+}
+/**
+ * Provider browser session — wraps raw session with provider methods
+ * Analogous to ProviderSandbox for sandbox providers.
+ */
+interface ProviderBrowserSession<TSession = any> extends BrowserSession {
+    /** Get the provider that created this session */
+    getProvider(): BrowserProvider<TSession>;
+    /** Get the native provider session instance */
+    getInstance(): TSession;
+    /** Destroy this session */
+    destroy(): Promise<void>;
+    /** Take a screenshot (delegates to provider page ops or throws) */
+    screenshot(options?: ScreenshotOptions): Promise<Uint8Array>;
+    /** Get session logs */
+    getLogs(): Promise<BrowserLog[]>;
+    /** Get session recording */
+    getRecording(): Promise<BrowserRecording | null>;
+}
+/**
+ * Browser provider interface — creates and manages browser sessions
+ *
+ * This is the top-level interface for browser providers, analogous to
+ * the Provider interface for sandbox providers.
+ */
+interface BrowserProvider<TSession = any> {
+    /** Provider name/type */
+    readonly name: string;
+    /** Session lifecycle management */
+    readonly session: BrowserSessionManager<TSession>;
+    /** Get CDP/WebSocket connection URL for a session */
+    getConnectUrl(sessionId: string): Promise<string>;
+    /** Optional profile management (Browserbase contexts, Kernel profiles) */
+    readonly profile?: BrowserProfileManager;
+    /** Optional extension management */
+    readonly extension?: BrowserExtensionManager;
+    /** Optional pool management (pre-warmed instances) */
+    readonly pool?: BrowserPoolManager<TSession>;
+    /** Optional log access */
+    readonly logs?: BrowserLogManager;
+    /** Optional recording access */
+    readonly recording?: BrowserRecordingManager;
+    /** Optional native page operations */
+    readonly page?: BrowserPageOperations<TSession>;
+}
+
 /**
  * Provider Factory - Creates providers from method definitions
  *
@@ -706,6 +1023,134 @@ interface ComputeAPI<TInstance = any> {
  */
 declare function createCompute<TInstance = any>(config: CreateComputeConfig<TInstance>): ComputeAPI<TInstance>;
 
+/**
+ * Browser Provider Factory - Creates browser providers from method definitions
+ *
+ * Eliminates boilerplate by auto-generating BrowserProvider/Session classes
+ * from simple method definitions with automatic feature detection.
+ * Mirrors the sandbox provider factory pattern.
+ */
+
+/**
+ * Session method implementations that provider authors supply
+ */
+interface BrowserSessionMethods<TSession = any, TConfig = any> {
+    create: (config: TConfig, options?: CreateBrowserSessionOptions) => Promise<{
+        session: TSession;
+        sessionId: string;
+        connectUrl: string;
+        status?: BrowserSession['status'];
+    }>;
+    getById: (config: TConfig, sessionId: string) => Promise<{
+        session: TSession;
+        sessionId: string;
+        connectUrl: string;
+        status?: BrowserSession['status'];
+    } | null>;
+    list: (config: TConfig) => Promise<Array<{
+        session: TSession;
+        sessionId: string;
+        connectUrl: string;
+        status?: BrowserSession['status'];
+    }>>;
+    destroy: (config: TConfig, sessionId: string) => Promise<void>;
+    getConnectUrl: (config: TConfig, sessionId: string) => Promise<string>;
+}
+/**
+ * Profile method implementations
+ */
+interface BrowserProfileMethods<TConfig = any> {
+    create: (config: TConfig, options?: CreateBrowserProfileOptions) => Promise<BrowserProfile>;
+    get: (config: TConfig, profileId: string) => Promise<BrowserProfile | null>;
+    list: (config: TConfig) => Promise<BrowserProfile[]>;
+    delete: (config: TConfig, profileId: string) => Promise<void>;
+}
+/**
+ * Extension method implementations
+ */
+interface BrowserExtensionMethods<TConfig = any> {
+    create: (config: TConfig, options: CreateBrowserExtensionOptions) => Promise<BrowserExtension>;
+    get: (config: TConfig, extensionId: string) => Promise<BrowserExtension | null>;
+    delete: (config: TConfig, extensionId: string) => Promise<void>;
+}
+/**
+ * Pool method implementations
+ */
+interface BrowserPoolMethods<TSession = any, TConfig = any> {
+    create: (config: TConfig, options: CreateBrowserPoolOptions) => Promise<BrowserPool>;
+    get: (config: TConfig, poolId: string) => Promise<BrowserPool | null>;
+    list: (config: TConfig) => Promise<BrowserPool[]>;
+    acquire: (config: TConfig, poolId: string) => Promise<{
+        session: TSession;
+        sessionId: string;
+        connectUrl: string;
+    }>;
+    release: (config: TConfig, poolId: string, sessionId: string) => Promise<void>;
+    delete: (config: TConfig, poolId: string) => Promise<void>;
+}
+/**
+ * Log method implementations
+ */
+interface BrowserLogMethods<TConfig = any> {
+    list: (config: TConfig, sessionId: string) => Promise<BrowserLog[]>;
+}
+/**
+ * Recording method implementations
+ */
+interface BrowserRecordingMethods<TConfig = any> {
+    get: (config: TConfig, sessionId: string) => Promise<BrowserRecording | null>;
+}
+/**
+ * Page operation method implementations
+ */
+interface BrowserPageMethods<TSession = any> {
+    navigate: (session: TSession, url: string) => Promise<void>;
+    screenshot: (session: TSession, options?: ScreenshotOptions) => Promise<Uint8Array>;
+    pdf?: (session: TSession, options?: PdfOptions) => Promise<Uint8Array>;
+    evaluate: (session: TSession, script: string) => Promise<unknown>;
+    getContent: (session: TSession) => Promise<string>;
+}
+/**
+ * Full browser provider configuration for defineBrowserProvider()
+ */
+interface BrowserProviderConfig<TSession = any, TConfig = any> {
+    name: string;
+    methods: {
+        session: BrowserSessionMethods<TSession, TConfig>;
+        profile?: BrowserProfileMethods<TConfig>;
+        extension?: BrowserExtensionMethods<TConfig>;
+        pool?: BrowserPoolMethods<TSession, TConfig>;
+        logs?: BrowserLogMethods<TConfig>;
+        recording?: BrowserRecordingMethods<TConfig>;
+        page?: BrowserPageMethods<TSession>;
+    };
+}
+/**
+ * Create a browser provider from method definitions
+ *
+ * Auto-generates all boilerplate classes and provides feature detection
+ * based on which methods are implemented.
+ *
+ * @example
+ * ```ts
+ * export const browserbase = defineBrowserProvider<BrowserbaseSession, BrowserbaseConfig>({
+ *   name: 'browserbase',
+ *   methods: {
+ *     session: { create, getById, list, destroy, getConnectUrl },
+ *     profile: { create, get, list, delete },
+ *     logs: { list: getLogs },
+ *     recording: { get: getRecording },
+ *   },
+ * });
+ *
+ * // Usage:
+ * const provider = browserbase({ apiKey: 'bb_...' });
+ * const session = await provider.session.create({ stealth: true });
+ * console.log(session.connectUrl);
+ * ```
+ */
+declare function defineBrowserProvider<TSession, TConfig = any>(providerConfig: BrowserProviderConfig<TSession, TConfig>): (config: TConfig) => BrowserProvider<TSession>;
+
 /**
  * Utility functions for ComputeSDK
  */
@@ -755,4 +1200,4 @@ declare function calculateBackoff(attempt: number, baseDelay?: number, jitterMax
  */
 declare function escapeShellArg(arg: string): string;
 
-export { type BlaxelProviderConfig, type CloudflareProviderConfig, type CodesandboxProviderConfig, type ComputeAPI, type ComputeConfig, type ComputeFactoryConfig, type CreateComputeConfig, type CreateSandboxParams, type CreateSandboxParamsWithOptionalProvider, type CreateSnapshotOptions, type CreateTemplateOptions, type DaemonConfig, type DaytonaProviderConfig, type DownloadResult, type E2BProviderConfig, type ExtendTimeoutOptions, type ExtractProviderSandboxType, type FindOrCreateSandboxOptions, type FindSandboxOptions, type InfraProvider, type InfraProviderConfig, type InfraProviderMethods, type ListOptions, type ListResult, type ListSnapshotsOptions, type ListTemplatesOptions, type ModalProviderConfig, type Provider, type ProviderConfig, type ProviderSandbox, type ProviderSandboxManager, type ProviderSnapshotManager, type ProviderTemplateManager, type RailwayProviderConfig, type RunloopProviderConfig, type SandboxMethods, type SnapshotMethods, type StorageObject, type StorageProvider, type TemplateMethods, type TypedComputeAPI, type TypedProviderSandbox, type UploadOptions, type VercelProviderConfig, calculateBackoff, createCompute, defineCompute, defineInfraProvider, defineProvider, escapeShellArg };
+export { type BlaxelProviderConfig, type BrowserExtension, type BrowserExtensionManager, type BrowserExtensionMethods, type BrowserLog, type BrowserLogManager, type BrowserLogMethods, type BrowserPageMethods, type BrowserPageOperations, type BrowserPool, type BrowserPoolManager, type BrowserPoolMethods, type BrowserProfile, type BrowserProfileManager, type BrowserProfileMethods, type BrowserProvider, type BrowserProviderConfig, type BrowserRecording, type BrowserRecordingManager, type BrowserRecordingMethods, type BrowserSession, type BrowserSessionManager, type BrowserSessionMethods, type CloudflareProviderConfig, type CodesandboxProviderConfig, type ComputeAPI, type ComputeConfig, type ComputeFactoryConfig, type CreateBrowserExtensionOptions, type CreateBrowserPoolOptions, type CreateBrowserProfileOptions, type CreateBrowserSessionOptions, type CreateComputeConfig, type CreateSandboxParams, type CreateSandboxParamsWithOptionalProvider, type CreateSnapshotOptions, type CreateTemplateOptions, type DaemonConfig, type DaytonaProviderConfig, type DownloadResult, type E2BProviderConfig, type ExtendTimeoutOptions, type ExtractProviderSandboxType, type FindOrCreateSandboxOptions, type FindSandboxOptions, type InfraProvider, type InfraProviderConfig, type InfraProviderMethods, type ListOptions, type ListResult, type ListSnapshotsOptions, type ListTemplatesOptions, type ModalProviderConfig, type PdfOptions, type Provider, type ProviderBrowserSession, type ProviderConfig, type ProviderSandbox, type ProviderSandboxManager, type ProviderSnapshotManager, type ProviderTemplateManager, type ProxyConfig, type RailwayProviderConfig, type RunloopProviderConfig, type SandboxMethods, type ScreenshotOptions, type SnapshotMethods, type StorageObject, type StorageProvider, type TemplateMethods, type TypedComputeAPI, type TypedProviderSandbox, type UploadOptions, type VercelProviderConfig, calculateBackoff, createCompute, defineBrowserProvider, defineCompute, defineInfraProvider, defineProvider, escapeShellArg };