opensteer 0.3.0 → 0.4.1

package/dist/index.d.cts

@@ -33,27 +33,6 @@ interface ElementPath {
     nodes: DomPath;
 }
 
-type ActionFailureCode = 'TARGET_NOT_FOUND' | 'TARGET_UNAVAILABLE' | 'TARGET_STALE' | 'TARGET_AMBIGUOUS' | 'BLOCKED_BY_INTERCEPTOR' | 'NOT_VISIBLE' | 'NOT_ENABLED' | 'NOT_EDITABLE' | 'INVALID_TARGET' | 'INVALID_OPTIONS' | 'ACTION_TIMEOUT' | 'UNKNOWN';
-type ActionFailureClassificationSource = 'typed_error' | 'playwright_call_log' | 'dom_probe' | 'message_heuristic' | 'unknown';
-interface ActionFailureBlocker {
-    tag: string;
-    id: string | null;
-    classes: string[];
-    role: string | null;
-    text: string | null;
-}
-interface ActionFailureDetails {
-    blocker?: ActionFailureBlocker;
-    observation?: string;
-}
-interface ActionFailure {
-    code: ActionFailureCode;
-    message: string;
-    retryable: boolean;
-    classificationSource: ActionFailureClassificationSource;
-    details?: ActionFailureDetails;
-}
-
 type SnapshotMode = 'action' | 'extraction' | 'clickable' | 'scrollable' | 'full';
 interface SnapshotOptions {
     mode?: SnapshotMode;
@@ -99,55 +78,43 @@ interface LaunchOptions {
     executablePath?: string;
     slowMo?: number;
     context?: BrowserContextOptions;
-    /** Connect to a running browser. Example: "http://localhost:9222" */
-    connectUrl?: string;
-    /** Browser channel: "chrome", "chrome-beta", or "msedge" */
+    /** Connect to a running Chrome via CDP. Example: "http://localhost:9222" */
+    cdpUrl?: string;
+    /** Use an installed browser: "chrome", "chrome-beta", "msedge" */
     channel?: string;
-    /** Browser profile directory. Preserves cookies, extensions, and sessions. */
-    profileDir?: string;
-    /** Connection timeout in milliseconds. */
-    timeout?: number;
+    /** Chrome user data directory. Preserves cookies, extensions, and sessions. */
+    userDataDir?: string;
 }
 interface OpensteerBrowserConfig {
     headless?: boolean;
     executablePath?: string;
     slowMo?: number;
-    /** Connect to a running browser. Example: "http://localhost:9222" */
-    connectUrl?: string;
-    /** Browser channel: "chrome", "chrome-beta", or "msedge" */
+    /** Connect to a running Chrome via CDP. Example: "http://localhost:9222" */
+    cdpUrl?: string;
+    /** Use an installed browser: "chrome", "chrome-beta", "msedge" */
     channel?: string;
-    /** Browser profile directory. Preserves cookies, extensions, and sessions. */
-    profileDir?: string;
+    /** Chrome user data directory. Preserves cookies, extensions, and sessions. */
+    userDataDir?: string;
 }
 interface OpensteerStorageConfig {
     rootDir?: string;
 }
-type OpensteerMode = 'local' | 'remote';
-interface OpensteerRemoteOptions {
-    apiKey?: string;
-    baseUrl?: string;
+interface OpensteerCloudConfig {
+    enabled: boolean;
+    key?: string;
 }
 interface OpensteerConfig {
     name?: string;
     browser?: OpensteerBrowserConfig;
     storage?: OpensteerStorageConfig;
-    mode?: OpensteerMode;
-    remote?: OpensteerRemoteOptions;
+    cloud?: OpensteerCloudConfig;
     model?: string;
     debug?: boolean;
 }
-interface ActionWaitOptions {
-    enabled?: boolean;
-    timeout?: number;
-    settleMs?: number;
-    networkQuietMs?: number;
-    includeNetwork?: boolean;
-}
 interface BaseActionOptions {
     description?: string;
     element?: number;
     selector?: string;
-    wait?: false | ActionWaitOptions;
 }
 interface ClickOptions extends BaseActionOptions {
     button?: 'left' | 'right' | 'middle';
@@ -303,7 +270,7 @@ declare class Opensteer {
     private readonly namespace;
     private readonly storage;
     private readonly pool;
-    private readonly remote;
+    private readonly cloud;
     private browser;
     private pageRef;
     private contextRef;
@@ -312,16 +279,14 @@ declare class Opensteer {
     constructor(config?: OpensteerConfig);
     private createLazyResolveCallback;
     private createLazyExtractCallback;
-    private invokeRemoteActionAndResetCache;
-    private invokeRemoteAction;
-    private buildActionError;
+    private bindCloudActionMethods;
+    private invokeCloudAction;
     get page(): Page;
     get context(): BrowserContext;
-    getRemoteSessionId(): string | null;
     launch(options?: LaunchOptions): Promise<void>;
     static from(page: Page, config?: OpensteerConfig): Opensteer;
     close(): Promise<void>;
-    private syncLocalSelectorCacheToRemote;
+    private syncLocalSelectorCacheToCloud;
     goto(url: string, options?: GotoOptions): Promise<void>;
     snapshot(options?: SnapshotOptions): Promise<string>;
     state(): Promise<StateResult>;
@@ -361,14 +326,12 @@ declare class Opensteer {
     getConfig(): OpensteerConfig;
     getStorage(): LocalSelectorStorage;
     clearCache(): void;
-    private runWithPostActionWait;
     private executeClickVariant;
     private resolvePath;
     private resolvePathWithAi;
     private buildPathFromElement;
     private tryBuildPathFromCounter;
     private resolveCounterHandle;
-    private resolveCounterHandleForAction;
     private buildPathFromResolvedHandle;
     private withIndexedIframeContext;
     private readPathFromCounterIndex;
@@ -393,33 +356,16 @@ declare class Opensteer {
     private normalizePath;
 }
 
-interface VisualStabilityOptions {
+declare function waitForVisualStability(page: Page, options?: {
     timeout?: number;
     settleMs?: number;
-}
-declare function waitForVisualStability(page: Page, options?: VisualStabilityOptions): Promise<void>;
+}): Promise<void>;
 
 interface ActionExecutionResult {
     ok: boolean;
     path?: ElementPath;
     usedSelector?: string;
     error?: string;
-    failure?: ActionFailure;
-}
-
-interface OpensteerActionErrorOptions {
-    action: string;
-    failure: ActionFailure;
-    selectorUsed?: string | null;
-    message?: string;
-    cause?: unknown;
-}
-declare class OpensteerActionError extends Error {
-    readonly action: string;
-    readonly code: ActionFailureCode;
-    readonly failure: ActionFailure;
-    readonly selectorUsed: string | null;
-    constructor(options: OpensteerActionErrorOptions);
 }
 
 declare function performClick(page: Page, path: ElementPath, options: ClickOptions): Promise<ActionExecutionResult>;
@@ -498,11 +444,11 @@ declare class ElementPathError extends Error {
     constructor(code: ElementPathErrorCode, message: string);
 }
 
-declare const OS_NODE_ID_ATTR = "data-os-node-id";
-declare const OS_BOUNDARY_ATTR = "data-os-boundary";
-declare const OS_UNAVAILABLE_ATTR = "data-os-unavailable";
-declare const OS_IFRAME_BOUNDARY_TAG = "os-iframe-root";
-declare const OS_SHADOW_BOUNDARY_TAG = "os-shadow-root";
+declare const OV_NODE_ID_ATTR = "data-ov-node-id";
+declare const OV_BOUNDARY_ATTR = "data-ov-boundary";
+declare const OV_UNAVAILABLE_ATTR = "data-ov-unavailable";
+declare const OV_IFRAME_BOUNDARY_TAG = "ov-iframe-root";
+declare const OV_SHADOW_BOUNDARY_TAG = "ov-shadow-root";
 interface SerializeOptions {
     detectOverlays?: boolean;
 }
@@ -583,9 +529,6 @@ interface PreparedSnapshot {
 }
 declare function prepareSnapshot(page: Page, options?: SnapshotOptions): Promise<PreparedSnapshot>;
 
-declare function normalizeNamespace(input?: string): string;
-declare function resolveNamespaceDir(rootDir: string, namespace: string): string;
-
 declare function createResolveCallback(model: string, options?: {
     temperature?: number;
     maxTokens?: number | null;
@@ -604,22 +547,21 @@ interface AiModelConfig {
     maxTokens?: number | null;
 }
 
-type RemoteActionMethod = 'goto' | 'snapshot' | 'state' | 'click' | 'dblclick' | 'rightclick' | 'hover' | 'input' | 'select' | 'scroll' | 'tabs' | 'newTab' | 'switchTab' | 'closeTab' | 'getCookies' | 'setCookie' | 'clearCookies' | 'pressKey' | 'type' | 'getElementText' | 'getElementValue' | 'getElementAttributes' | 'getElementBoundingBox' | 'getHtml' | 'getTitle' | 'waitForText' | 'extract' | 'extractFromPlan' | 'clearCache' | 'uploadFile' | 'exportCookies' | 'importCookies' | 'screenshot';
-type RemoteErrorCode = 'REMOTE_AUTH_FAILED' | 'REMOTE_SESSION_NOT_FOUND' | 'REMOTE_SESSION_CLOSED' | 'REMOTE_UNSUPPORTED_METHOD' | 'REMOTE_INVALID_REQUEST' | 'REMOTE_MODEL_NOT_ALLOWED' | 'REMOTE_ACTION_FAILED' | 'REMOTE_CAPACITY_EXHAUSTED' | 'REMOTE_RUNTIME_UNAVAILABLE' | 'REMOTE_RUNTIME_MISMATCH' | 'REMOTE_SESSION_STALE' | 'REMOTE_CONTROL_PLANE_ERROR' | 'REMOTE_INTERNAL';
-interface RemoteSessionCreateRequest {
+type CloudActionMethod = 'goto' | 'snapshot' | 'state' | 'click' | 'dblclick' | 'rightclick' | 'hover' | 'input' | 'select' | 'scroll' | 'tabs' | 'newTab' | 'switchTab' | 'closeTab' | 'getCookies' | 'setCookie' | 'clearCookies' | 'pressKey' | 'type' | 'getElementText' | 'getElementValue' | 'getElementAttributes' | 'getElementBoundingBox' | 'getHtml' | 'getTitle' | 'waitForText' | 'extract' | 'extractFromPlan' | 'clearCache' | 'uploadFile' | 'exportCookies' | 'importCookies' | 'screenshot';
+type CloudErrorCode = 'CLOUD_AUTH_FAILED' | 'CLOUD_SESSION_NOT_FOUND' | 'CLOUD_SESSION_CLOSED' | 'CLOUD_UNSUPPORTED_METHOD' | 'CLOUD_INVALID_REQUEST' | 'CLOUD_MODEL_NOT_ALLOWED' | 'CLOUD_ACTION_FAILED' | 'CLOUD_INTERNAL';
+interface CloudSessionCreateRequest {
     name?: string;
     model?: string;
     launchContext?: Record<string, unknown>;
 }
-interface RemoteSessionCreateResponse {
+interface CloudSessionCreateResponse {
     sessionId: string;
     actionWsUrl: string;
     cdpWsUrl: string;
     actionToken: string;
     cdpToken: string;
-    expiresAt?: number;
 }
-interface RemoteSelectorCacheImportEntry {
+interface CloudSelectorCacheImportEntry {
     namespace: string;
     siteOrigin: string;
     method: string;
@@ -629,55 +571,50 @@ interface RemoteSelectorCacheImportEntry {
     createdAt: number;
     updatedAt: number;
 }
-interface RemoteSelectorCacheImportRequest {
-    entries: RemoteSelectorCacheImportEntry[];
+interface CloudSelectorCacheImportRequest {
+    entries: CloudSelectorCacheImportEntry[];
 }
-interface RemoteSelectorCacheImportResponse {
+interface CloudSelectorCacheImportResponse {
     imported: number;
     inserted: number;
     updated: number;
     skipped: number;
 }
-interface RemoteActionRequest {
+interface CloudActionRequest {
     id: number;
-    method: RemoteActionMethod;
+    method: CloudActionMethod;
     args: Record<string, unknown>;
     sessionId: string;
     token: string;
 }
-interface RemoteActionSuccess {
+interface CloudActionSuccess {
     id: number;
     ok: true;
     result: unknown;
 }
-interface RemoteActionFailure {
+interface CloudActionFailure {
     id: number;
     ok: false;
     error: string;
-    code: RemoteErrorCode;
-    details?: RemoteActionFailureDetails;
-}
-type RemoteActionResponse = RemoteActionSuccess | RemoteActionFailure;
-interface RemoteActionFailureDetails {
-    actionFailure?: ActionFailure;
+    code: CloudErrorCode;
 }
+type CloudActionResponse = CloudActionSuccess | CloudActionFailure;
 
-declare class OpensteerRemoteError extends Error {
-    readonly code: RemoteErrorCode | 'REMOTE_TRANSPORT_ERROR';
+declare class OpensteerCloudError extends Error {
+    readonly code: CloudErrorCode | 'CLOUD_TRANSPORT_ERROR';
     readonly status?: number;
-    readonly details?: RemoteActionFailureDetails | Record<string, unknown>;
-    constructor(code: RemoteErrorCode | 'REMOTE_TRANSPORT_ERROR', message: string, status?: number, details?: RemoteActionFailureDetails | Record<string, unknown>);
+    constructor(code: CloudErrorCode | 'CLOUD_TRANSPORT_ERROR', message: string, status?: number);
 }
-declare function remoteUnsupportedMethodError(method: string, message?: string): OpensteerRemoteError;
-declare function remoteNotLaunchedError(): OpensteerRemoteError;
+declare function cloudUnsupportedMethodError(method: string, message?: string): OpensteerCloudError;
+declare function cloudNotLaunchedError(): OpensteerCloudError;
 
-declare class RemoteSessionClient {
+declare class CloudSessionClient {
     private readonly baseUrl;
     private readonly key;
     constructor(baseUrl: string, key: string);
-    create(request: RemoteSessionCreateRequest): Promise<RemoteSessionCreateResponse>;
+    create(request: CloudSessionCreateRequest): Promise<CloudSessionCreateResponse>;
     close(sessionId: string): Promise<void>;
-    importSelectorCache(request: RemoteSelectorCacheImportRequest): Promise<RemoteSelectorCacheImportResponse>;
+    importSelectorCache(request: CloudSelectorCacheImportRequest): Promise<CloudSelectorCacheImportResponse>;
     private importSelectorCacheBatch;
 }
 
@@ -695,25 +632,25 @@ declare class ActionWsClient {
     private closed;
     private constructor();
     static connect(options: ActionWsClientOptions): Promise<ActionWsClient>;
-    request<T>(method: RemoteActionMethod, args: Record<string, unknown>): Promise<T>;
+    request<T>(method: CloudActionMethod, args: Record<string, unknown>): Promise<T>;
     close(): Promise<void>;
     private handleMessage;
     private rejectAll;
 }
 
-interface RemoteCdpConnectArgs {
+interface CloudCdpConnectArgs {
     wsUrl: string;
     token: string;
 }
-interface RemoteCdpConnection {
+interface CloudCdpConnection {
     browser: Browser;
     context: BrowserContext;
     page: Page;
 }
-declare class RemoteCdpClient {
-    connect(args: RemoteCdpConnectArgs): Promise<RemoteCdpConnection>;
+declare class CloudCdpClient {
+    connect(args: CloudCdpConnectArgs): Promise<CloudCdpConnection>;
 }
 
-declare function collectLocalSelectorCacheEntries(storage: LocalSelectorStorage): RemoteSelectorCacheImportEntry[];
+declare function collectLocalSelectorCacheEntries(storage: LocalSelectorStorage): CloudSelectorCacheImportEntry[];
 
-export { type ActionExecutionResult, type ActionFailure, type ActionFailureBlocker, type ActionFailureClassificationSource, type ActionFailureCode, type ActionFailureDetails, type ActionResult, type ActionWaitOptions, ActionWsClient, type AiExtractArgs, type AiExtractCallback, type AiExtractResult, type AiModelConfig, type AiResolveArgs, type AiResolveCallback, type AiResolveCallbackResult, type AiResolveResult, type ArrayExtractedRow, type ArrayRowMetadata, type ArraySelector, type AttributeMatchClause, type BaseActionOptions, type BoundingBox, type ClickOptions, type ContextHop, type CookieParam, type CounterBinding, type CounterRequest, CounterResolutionError, type CounterResolutionErrorCode, type CounterSnapshotLike, type DomPath, type ElementPath, ElementPathError, type ElementPathErrorCode, type ExtractFromPlanOptions, type ExtractOptions, type ExtractSchema, type ExtractSchemaField, type ExtractSchemaValue, type ExtractionFieldPlan, type ExtractionPlan, type ExtractionRunResult, type FieldSelector, type FileUploadOptions, type GotoOptions, type HoverOptions, type InputOptions, type LaunchOptions, LocalSelectorStorage, type MarkInteractivityOptions, type MatchClause, type MatchOperator, OPENSTEER_HIDDEN_ATTR, OPENSTEER_INTERACTIVE_ATTR, OPENSTEER_SCROLLABLE_ATTR, OS_BOUNDARY_ATTR, OS_IFRAME_BOUNDARY_TAG, OS_NODE_ID_ATTR, OS_SHADOW_BOUNDARY_TAG, OS_UNAVAILABLE_ATTR, Opensteer, OpensteerActionError, type OpensteerBrowserConfig, type OpensteerConfig, type OpensteerMode, OpensteerRemoteError, type OpensteerRemoteOptions, type OpensteerStorageConfig, type PathNode, type PathNodePosition, type PositionMatchClause, type PreparedSnapshot, type RegistryEntry, type RemoteActionFailure, type RemoteActionFailureDetails, type RemoteActionMethod, type RemoteActionRequest, type RemoteActionResponse, type RemoteActionSuccess, RemoteCdpClient, type RemoteCdpConnectArgs, type RemoteCdpConnection, type RemoteErrorCode, type RemoteSelectorCacheImportEntry, type RemoteSelectorCacheImportRequest, type RemoteSelectorCacheImportResponse, RemoteSessionClient, type RemoteSessionCreateRequest, type RemoteSessionCreateResponse, type ResolvedElementPath, type ScreenshotOptions, type ScrollOptions, type SelectOptions, type SelectorFile, type SelectorRegistry, type SerializeOptions, type SerializedNodeMeta, type SerializedPageHTML, type SnapshotMode, type SnapshotOptions, type StateResult, type TabInfo, buildElementPathFromHandle, buildElementPathFromSelector, buildPathSelectorHint, cleanForAction, cleanForClickable, cleanForExtraction, cleanForFull, cleanForScrollable, clearCookies, cloneElementPath, closeTab, collectLocalSelectorCacheEntries, countArrayItemsWithPath, createEmptyRegistry, createExtractCallback, createResolveCallback, createTab, ensureLiveCounters, exportCookies, extractArrayRowsWithPaths, extractArrayWithPaths, extractWithPaths, getCookies, getElementAttributes, getElementBoundingBox, getElementText, getElementValue, getModelProvider, getPageHtml, getPageTitle, importCookies, listTabs, markInteractiveElements, normalizeNamespace, performClick, performFileUpload, performHover, performInput, performScroll, performSelect, prepareSnapshot, pressKey, remoteNotLaunchedError, remoteUnsupportedMethodError, resolveCounterElement, resolveCountersBatch, resolveElementPath, resolveNamespaceDir, sanitizeElementPath, serializePageHTML, setCookie, switchTab, typeText, waitForVisualStability };
+export { type ActionExecutionResult, type ActionResult, ActionWsClient, type AiExtractArgs, type AiExtractCallback, type AiExtractResult, type AiModelConfig, type AiResolveArgs, type AiResolveCallback, type AiResolveCallbackResult, type AiResolveResult, type ArrayExtractedRow, type ArrayRowMetadata, type ArraySelector, type AttributeMatchClause, type BaseActionOptions, type BoundingBox, type ClickOptions, type CloudActionFailure, type CloudActionMethod, type CloudActionRequest, type CloudActionResponse, type CloudActionSuccess, CloudCdpClient, type CloudCdpConnectArgs, type CloudCdpConnection, type CloudErrorCode, type CloudSelectorCacheImportEntry, type CloudSelectorCacheImportRequest, type CloudSelectorCacheImportResponse, CloudSessionClient, type CloudSessionCreateRequest, type CloudSessionCreateResponse, type ContextHop, type CookieParam, type CounterBinding, type CounterRequest, CounterResolutionError, type CounterResolutionErrorCode, type CounterSnapshotLike, type DomPath, type ElementPath, ElementPathError, type ElementPathErrorCode, type ExtractFromPlanOptions, type ExtractOptions, type ExtractSchema, type ExtractSchemaField, type ExtractSchemaValue, type ExtractionFieldPlan, type ExtractionPlan, type ExtractionRunResult, type FieldSelector, type FileUploadOptions, type GotoOptions, type HoverOptions, type InputOptions, type LaunchOptions, LocalSelectorStorage, type MarkInteractivityOptions, type MatchClause, type MatchOperator, OPENSTEER_HIDDEN_ATTR, OPENSTEER_INTERACTIVE_ATTR, OPENSTEER_SCROLLABLE_ATTR, OV_BOUNDARY_ATTR, OV_IFRAME_BOUNDARY_TAG, OV_NODE_ID_ATTR, OV_SHADOW_BOUNDARY_TAG, OV_UNAVAILABLE_ATTR, Opensteer, type OpensteerBrowserConfig, type OpensteerCloudConfig, OpensteerCloudError, type OpensteerConfig, type OpensteerStorageConfig, type PathNode, type PathNodePosition, type PositionMatchClause, type PreparedSnapshot, type RegistryEntry, type ResolvedElementPath, type ScreenshotOptions, type ScrollOptions, type SelectOptions, type SelectorFile, type SelectorRegistry, type SerializeOptions, type SerializedNodeMeta, type SerializedPageHTML, type SnapshotMode, type SnapshotOptions, type StateResult, type TabInfo, buildElementPathFromHandle, buildElementPathFromSelector, buildPathSelectorHint, cleanForAction, cleanForClickable, cleanForExtraction, cleanForFull, cleanForScrollable, clearCookies, cloneElementPath, closeTab, cloudNotLaunchedError, cloudUnsupportedMethodError, collectLocalSelectorCacheEntries, countArrayItemsWithPath, createEmptyRegistry, createExtractCallback, createResolveCallback, createTab, ensureLiveCounters, exportCookies, extractArrayRowsWithPaths, extractArrayWithPaths, extractWithPaths, getCookies, getElementAttributes, getElementBoundingBox, getElementText, getElementValue, getModelProvider, getPageHtml, getPageTitle, importCookies, listTabs, markInteractiveElements, performClick, performFileUpload, performHover, performInput, performScroll, performSelect, prepareSnapshot, pressKey, resolveCounterElement, resolveCountersBatch, resolveElementPath, sanitizeElementPath, serializePageHTML, setCookie, switchTab, typeText, waitForVisualStability };