@bctrl/sdk/scripts

import { ... } from '@bctrl/sdk/scripts';

defineScript<TParams extends ZodTypeAny, TResult, TScriptPage extends BaseScriptPage = BaseScriptPage>(input: DefineScriptInput<TParams, TResult, TScriptPage>): ScriptDefinition<TParams, TResult, TScriptPage>

isScriptDefinition(value: unknown): value is ScriptDefinition<ZodTypeAny, unknown, BaseScriptPage>

export interface BaseScriptPage {
  [method: string]: (...args: any[]) => Promise<any>;
}

export interface DefineScriptInput<
  TParams extends ZodTypeAny,
  TResult,
  TScriptPage extends BaseScriptPage = BaseScriptPage,
> {
  name: string;
  params: TParams;
  run: (ctx: ScriptContext<TScriptPage> & ZodInfer<TParams>) => Promise<TResult> | TResult;
  returns?: ZodType<TResult>;
  defaults?: ScriptDefaults;
}

export interface ExecuteLogEntry {
  level: ExecuteLogLevel;
  ts: string;
  args: unknown[];
  truncated?: boolean;
}

export interface ExecuteMeta {
  scriptId: string;
  scriptName?: string;
  durationMs: number;
  dispatchCount: number;
  timeoutMs: number;
  pageId?: string;
  logStats: {
    emitted: number;
    kept: number;
    dropped: number;
    bytesKept: number;
  };
}

export interface ExecuteResult<T> {
  data: T;
  logs: ExecuteLogEntry[];
  meta: ExecuteMeta;
}

export interface PlaywrightScriptPage extends BaseScriptPage {
  /** Navigate to a URL. */
  goto(url: string, options?: Record<string, unknown>): Promise<unknown>;
  /** Reload the page. */
  reload(options?: Record<string, unknown>): Promise<unknown>;
  /** Navigate back in history. */
  goBack(options?: Record<string, unknown>): Promise<unknown>;
  /** Navigate forward in history. */
  goForward(options?: Record<string, unknown>): Promise<unknown>;
  /** Wait for the main frame to navigate to the given URL. */
  waitForURL(url: Function | string, options?: Record<string, unknown>): Promise<void>;
  /** Wait for the required load state to be reached. */
  waitForLoadState(state?: unknown, options?: Record<string, unknown>): Promise<void>;
  /** Wait for the main frame navigation and return the main resource response. */
  waitForNavigation(options?: Record<string, unknown>): Promise<unknown>;
  /** Get the page title. */
  title(): Promise<string>;
  /** Get the current URL. */
  url(): Promise<string>;
  /** Get the full HTML content of the page. */
  content(): Promise<string>;
  /** Set the HTML content of the page. */
  setContent(html: string, options?: Record<string, unknown>): Promise<void>;
  /** Click on an element matching the selector. */
  click(selector: string, options?: Record<string, unknown>): Promise<void>;
  /** Double-click on an element matching the selector. */
  dblclick(selector: string, options?: Record<string, unknown>): Promise<void>;
  /** Fill an input element with the given value. */
  fill(selector: string, value: string, options?: Record<string, unknown>): Promise<void>;
  /** Type text into an element (sends keydown, keypress/input, keyup events for each character). */
  type(selector: string, text: string, options?: Record<string, unknown>): Promise<void>;
  /** Focus an element and press a key combination. */
  press(selector: string, key: string, options?: Record<string, unknown>): Promise<void>;
  /** Hover over an element. */
  hover(selector: string, options?: Record<string, unknown>): Promise<void>;
  /** Focus on an element. */
  focus(selector: string, options?: Record<string, unknown>): Promise<void>;
  /** Tap on an element (for touch devices). */
  tap(selector: string, options?: Record<string, unknown>): Promise<void>;
  /** Check a checkbox or radio button. */
  check(selector: string, options?: Record<string, unknown>): Promise<void>;
  /** Uncheck a checkbox. */
  uncheck(selector: string, options?: Record<string, unknown>): Promise<void>;
  /** Set the checked state of a checkbox. */
  setChecked(selector: string, checked: boolean, options?: Record<string, unknown>): Promise<void>;
  /** Select one or more options in a <select> element. */
  selectOption(selector: string, values: unknown, options?: Record<string, unknown>): Promise<string[]>;
  /** Set input files for a file input element. */
  setInputFiles(selector: string, files: unknown, options?: Record<string, unknown>): Promise<void>;
  /** Dispatch a DOM event on an element. */
  dispatchEvent(selector: string, type: string, eventInit?: Record<string, unknown>, options?: Record<string, unknown>): Promise<void>;
  /** Drag an element to another element. */
  dragAndDrop(source: string, target: string, options?: Record<string, unknown>): Promise<void>;
  /** Wait for a selector to appear in the DOM. */
  waitForSelector(selector: string, options?: Record<string, unknown>): Promise<unknown>;
  /** Wait for the specified timeout. */
  waitForTimeout(timeout: number): Promise<void>;
  /** Wait for a function to return a truthy value. */
  waitForFunction(pageFunction: string, arg?: unknown, options?: Function | string): Promise<unknown>;
  /** Wait for a specific event to fire. */
  waitForEvent(event: unknown, optionsOrPredicate?: unknown): Promise<unknown>;
  /** Wait for a specific request. */
  waitForRequest(urlOrPredicate: Function | string, options?: Record<string, unknown>): Promise<unknown>;
  /** Wait for a specific response. */
  waitForResponse(urlOrPredicate: Function | string, options?: Record<string, unknown>): Promise<unknown>;
  /** Evaluate JavaScript in the page context. */
  evaluate(pageFunction: string, arg?: unknown): Promise<unknown>;
  /** Evaluate JavaScript and return a handle to the result. */
  evaluateHandle(pageFunction: string, arg?: unknown): Promise<unknown>;
  /** Query for a single element. Alias for page.querySelector(). */
  $(selector: string): Promise<unknown>;
  /** Query for all matching elements. Alias for page.querySelectorAll(). */
  $$(selector: string): Promise<unknown>;
  /** Query for a single element. */
  querySelector(selector: string): Promise<unknown>;
  /** Query for all matching elements. */
  querySelectorAll(selector: string): Promise<unknown>;
  /** Find an element matching the selector and evaluate a function on it. */
  $eval(selector: string, pageFunction: string, arg?: unknown): Promise<unknown>;
  /** Find all elements matching the selector and evaluate a function on the array of elements. */
  $$eval(selector: string, pageFunction: string, arg?: unknown): Promise<unknown>;
  /** Take a screenshot of the page. */
  screenshot(options?: Record<string, unknown>): Promise<string>;
  /** Generate a PDF of the page (Chromium only). */
  pdf(options?: Record<string, unknown>): Promise<string>;
  /** Set the viewport size. */
  setViewportSize(viewportSize: string): Promise<void>;
  /** Emulate media type, color scheme, etc. */
  emulateMedia(options?: Record<string, unknown>): Promise<void>;
  /** Get the main frame. */
  mainFrame(): Promise<unknown>;
  /** Get all frames attached to the page. */
  frames(): Promise<unknown>;
  /** Get a frame by name or URL. */
  frame(frameSelector: Function | string): Promise<unknown>;
  /** Route requests matching the URL pattern. */
  route(url: Function | string, handler: string, options?: Record<string, unknown>): Promise<void>;
  /** Remove a route. */
  unroute(url: Function | string, handler?: string): Promise<void>;
  /** Remove all routes. */
  unrouteAll(options?: Record<string, unknown>): Promise<void>;
  /** Set extra HTTP headers for all requests. */
  setExtraHTTPHeaders(headers: Record<string, string>): Promise<void>;
  /** Get the browser context that the page belongs to. */
  context(): Promise<unknown>;
  /** Check if the page is closed. */
  isClosed(): Promise<boolean>;
  /** Close the page. */
  close(options?: Record<string, unknown>): Promise<void>;
  /** Bring page to front (activate tab). */
  bringToFront(): Promise<void>;
  /** Set the default timeout for all methods. */
  setDefaultTimeout(timeout: number): Promise<void>;
  /** Set the default navigation timeout. */
  setDefaultNavigationTimeout(timeout: number): Promise<void>;
  /** Add a script to evaluate before page scripts run. */
  addInitScript(script: unknown, arg?: unknown): Promise<void>;
  /** Add a <script> tag to the page. */
  addScriptTag(options: Record<string, unknown>): Promise<unknown>;
  /** Add a <style> tag to the page. */
  addStyleTag(options: Record<string, unknown>): Promise<unknown>;
  /** Expose a binding to the page (with source info). */
  exposeBinding(name: string, callback: string, options?: Record<string, unknown>): Promise<void>;
  /** Check if an element is visible. */
  isVisible(selector: string, options?: Record<string, unknown>): Promise<boolean>;
  /** Check if an element is hidden. */
  isHidden(selector: string, options?: Record<string, unknown>): Promise<boolean>;
  /** Check if an element is enabled. */
  isEnabled(selector: string, options?: Record<string, unknown>): Promise<boolean>;
  /** Check if an element is disabled. */
  isDisabled(selector: string, options?: Record<string, unknown>): Promise<boolean>;
  /** Check if an element is editable. */
  isEditable(selector: string, options?: Record<string, unknown>): Promise<boolean>;
  /** Check if a checkbox is checked. */
  isChecked(selector: string, options?: Record<string, unknown>): Promise<boolean>;
  /** Get an attribute value from an element. */
  getAttribute(selector: string, name: string, options?: Record<string, unknown>): Promise<string | null>;
  /** Get the text content of an element. */
  textContent(selector: string, options?: Record<string, unknown>): Promise<string | null>;
  /** Get the inner text of an element. */
  innerText(selector: string, options?: Record<string, unknown>): Promise<string>;
  /** Get the inner HTML of an element. */
  innerHTML(selector: string, options?: Record<string, unknown>): Promise<string>;
  /** Get the input value of an element. */
  inputValue(selector: string, options?: Record<string, unknown>): Promise<string>;
  /** Pause script execution (for debugging). */
  pause(): Promise<void>;
  /** Get the page that opened this page (via window.open). */
  opener(): Promise<unknown>;
  /** Registers a handler that will be called when the specified locator becomes visible on the page. */
  addLocatorHandler(locator: Record<string, unknown>, handler: string, options?: Record<string, unknown>): Promise<void>;
  /** Removes a previously added locator handler. */
  removeLocatorHandler(locator: Record<string, unknown>): Promise<void>;
  /** Returns all console messages captured during the page lifecycle. */
  consoleMessages(): Promise<unknown>;
  /** Returns all page errors (uncaught exceptions) captured during the page lifecycle. */
  pageErrors(): Promise<unknown>;
  /** Request garbage collection in the page context. */
  requestGC(): Promise<void>;
  /** Returns all requests made by the page since the last navigation. */
  requests(): Promise<unknown>;
  /** Serves network requests from a HAR (HTTP Archive) file. */
  routeFromHAR(har: string, options?: Record<string, unknown>): Promise<void>;
  /** Route WebSocket connections matching the URL pattern. */
  routeWebSocket(url: Function | string, handler: string): Promise<void>;

  // --- mouse methods ---
  /** Shortcut for mouse.move(), mouse.down(), mouse.up(). */
  'mouse.click'(x: number, y: number, options?: Record<string, unknown>): Promise<void>;
  /** Shortcut for mouse.move(), mouse.down(), mouse.up(), mouse.down(), mouse.up(). */
  'mouse.dblclick'(x: number, y: number, options?: Record<string, unknown>): Promise<void>;
  /** Dispatches a mousedown event. */
  'mouse.down'(options?: Record<string, unknown>): Promise<void>;
  /** Dispatches a mouseup event. */
  'mouse.up'(options?: Record<string, unknown>): Promise<void>;
  /** Dispatches a mousemove event. */
  'mouse.move'(x: number, y: number, options?: Record<string, unknown>): Promise<void>;
  /** Dispatches a wheel event. */
  'mouse.wheel'(deltaX: number, deltaY: number): Promise<void>;

  // --- keyboard methods ---
  /** Dispatches a keydown event. */
  'keyboard.down'(key: string): Promise<void>;
  /** Dispatches a keyup event. */
  'keyboard.up'(key: string): Promise<void>;
  /** Shortcut for keyboard.down() and keyboard.up(). */
  'keyboard.press'(key: string, options?: Record<string, unknown>): Promise<void>;
  /** Sends a keydown, keypress/input, and keyup event for each character in the text. */
  'keyboard.type'(text: string, options?: Record<string, unknown>): Promise<void>;
  /** Dispatches only an input event, does not emit keydown, keyup, or keypress events. */
  'keyboard.insertText'(text: string): Promise<void>;

  // --- touchscreen methods ---
  /** Dispatches a touchstart and touchend event with a single touch at the position (x, y). */
  'touchscreen.tap'(x: number, y: number): Promise<void>;
}

export interface PuppeteerScriptPage extends BaseScriptPage {
  /** Navigate to a URL. */
  goto(url: string, options?: Record<string, unknown>): Promise<unknown>;
  /** Reload the page. */
  reload(options?: Record<string, unknown>): Promise<unknown>;
  /** Navigate back in history. */
  goBack(options?: Record<string, unknown>): Promise<unknown>;
  /** Navigate forward in history. */
  goForward(options?: Record<string, unknown>): Promise<unknown>;
  /** Wait for navigation to complete. */
  waitForNavigation(options?: Record<string, unknown>): Promise<unknown>;
  /** Get the page title. */
  title(): Promise<string>;
  /** Get the current URL. */
  url(): Promise<string>;
  /** Get the full HTML content. */
  content(): Promise<string>;
  /** Set the page content. */
  setContent(html: string, options?: Record<string, unknown>): Promise<void>;
  /** Click on an element matching the selector. */
  click(selector: string, options?: Record<string, unknown>): Promise<void>;
  /** Type text into an element. */
  type(selector: string, text: string, options?: Record<string, unknown>): Promise<void>;
  /** Focus on an element. */
  focus(selector: string): Promise<void>;
  /** Hover over an element. */
  hover(selector: string): Promise<void>;
  /** Select options in a <select> element. */
  select(selector: string, ...values: string[]): Promise<string[]>;
  /** Tap on an element (for touch devices). */
  tap(selector: string): Promise<void>;
  /** Get the text content of an element matching the selector. */
  textContent(selector: string): Promise<string | null>;
  /** Get the inner HTML of an element matching the selector. */
  innerHTML(selector: string): Promise<string>;
  /** Wait for a selector to appear in the DOM. */
  waitForSelector(selector: string, options?: Record<string, unknown>): Promise<unknown>;
  /** Wait for a timeout. */
  waitForTimeout(milliseconds: number): Promise<void>;
  /** Wait for a function to return true. */
  waitForFunction(pageFunction: string, options?: Record<string, unknown>, ...args: unknown[]): Promise<void>;
  /** Wait for network to be idle. */
  waitForNetworkIdle(options?: Record<string, unknown>): Promise<void>;
  /** Evaluate JavaScript in the page context. */
  evaluate(pageFunction: string, ...args: unknown[]): Promise<unknown>;
  /** Evaluate JavaScript on a selected element. */
  $eval(selector: string, pageFunction: string, ...args: unknown[]): Promise<unknown>;
  /** Evaluate JavaScript on all matching elements. */
  $$eval(selector: string, pageFunction: string, ...args: unknown[]): Promise<unknown>;
  /** Evaluate handle (returns a JSHandle). */
  evaluateHandle(pageFunction: string, ...args: unknown[]): Promise<unknown>;
  /** Query for a single element. */
  $(selector: string): Promise<unknown>;
  /** Query for all matching elements. */
  $$(selector: string): Promise<unknown>;
  /** Evaluate XPath expression. */
  $x(expression: string): Promise<unknown>;
  /** Take a screenshot (returns base64 string or Buffer). */
  screenshot(options?: Record<string, unknown>): Promise<string>;
  /** Generate a PDF (returns base64 string or Buffer). */
  pdf(options?: Record<string, unknown>): Promise<string>;
  /** Set the viewport size. Pass null to reset to default. */
  setViewport(viewport: string): Promise<void>;
  /** Get the current viewport. */
  viewport(): Promise<unknown>;
  /** Emulate media type. */
  emulateMediaType(type?: unknown): Promise<void>;
  /** Emulate media features. */
  emulateMediaFeatures(features?: unknown): Promise<void>;
  /** Emulate timezone. */
  emulateTimezone(timezoneId?: string): Promise<void>;
  /** Emulate vision deficiency. */
  emulateVisionDeficiency(type?: unknown): Promise<void>;
  /** Set geolocation. */
  setGeolocation(geolocation: Record<string, unknown>): Promise<void>;
  /** Set user agent. */
  setUserAgent(userAgent: string): Promise<void>;
  /** Set extra HTTP headers. */
  setExtraHTTPHeaders(headers: Record<string, string>): Promise<void>;
  /** Get all cookies. */
  cookies(...urls: string[]): Promise<unknown>;
  /** Set cookies. */
  setCookie(...cookies: Record<string, unknown>[]): Promise<void>;
  /** Delete cookies. */
  deleteCookie(...cookies: Record<string, unknown>[]): Promise<void>;
  /** Bring page to front. */
  bringToFront(): Promise<void>;
  /** Close the page. */
  close(): Promise<void>;
  /** Create a CDP session. */
  createCDPSession(): Promise<unknown>;
  /** Send a CDP command directly. */
  sendCDP(method: string, params?: Record<string, unknown>): Promise<unknown>;
  /** Get metrics. */
  metrics(): Promise<unknown>;
  /** Set JavaScript enabled/disabled. */
  setJavaScriptEnabled(enabled: boolean): Promise<void>;
  /** Set cache enabled/disabled. */
  setCacheEnabled(enabled: boolean): Promise<void>;
  /** Set offline mode. */
  setOfflineMode(enabled: boolean): Promise<void>;
  /** Emulate network conditions. */
  emulateNetworkConditions(conditions: Record<string, unknown> | null): Promise<void>;
  /** Add script tag. */
  addScriptTag(options: Record<string, unknown>): Promise<unknown>;
  /** Add style tag. */
  addStyleTag(options: Record<string, unknown>): Promise<unknown>;
  /** Set request interception enabled/disabled. */
  setRequestInterception(enabled: boolean): Promise<void>;
  /** Authenticate with HTTP auth. */
  authenticate(credentials: Record<string, unknown> | null): Promise<void>;
  /** Get all frames. */
  frames(): Promise<unknown>;
  /** Wait for a frame to appear. */
  waitForFrame(urlOrPredicate: string, options?: Record<string, unknown>): Promise<unknown>;
  /** Set the default navigation timeout. */
  setDefaultNavigationTimeout(timeout: number): Promise<void>;
  /** Set the default timeout. */
  setDefaultTimeout(timeout: number): Promise<void>;
  /** Get the default navigation timeout. */
  getDefaultNavigationTimeout(): Promise<number>;
  /** Get the default timeout. */
  getDefaultTimeout(): Promise<number>;
  /** Wait for a file chooser to appear. */
  waitForFileChooser(options?: Record<string, unknown>): Promise<unknown>;
  /** Wait for a specific request. */
  waitForRequest(urlOrPredicate: string, options?: Record<string, unknown>): Promise<unknown>;
  /** Wait for a specific response. */
  waitForResponse(urlOrPredicate: string, options?: Record<string, unknown>): Promise<unknown>;
  /** Toggle bypassing Content-Security-Policy. */
  setBypassCSP(enabled: boolean): Promise<void>;
  /** Add a script to evaluate when a new document is created. */
  evaluateOnNewDocument(pageFunction: string, ...args: unknown[]): Promise<unknown>;
  /** Remove an injected script. */
  removeScriptToEvaluateOnNewDocument(identifier: string): Promise<void>;
  /** Remove an exposed function. */
  removeExposedFunction(name: string): Promise<void>;
  /** Emulate a device (viewport + user agent). */
  emulate(device: Record<string, unknown>): Promise<void>;
  /** Emulate CPU throttling. */
  emulateCPUThrottling(factor: number | null): Promise<void>;
  /** Emulate idle state. */
  emulateIdleState(overrides?: Record<string, unknown>): Promise<void>;
  /** Check if JavaScript is enabled. */
  isJavaScriptEnabled(): Promise<boolean>;
  /** Check if drag interception is enabled. */
  isDragInterceptionEnabled(): Promise<boolean>;
  /** Check if service worker bypass is enabled. */
  isServiceWorkerBypassed(): Promise<boolean>;
  /** Set service worker bypass. */
  setBypassServiceWorker(bypass: boolean): Promise<void>;
  /** Set drag interception. */
  setDragInterception(enabled: boolean): Promise<void>;
  /** Get the target for this page. */
  target(): Promise<unknown>;
  /** Get all web workers for this page. */
  workers(): Promise<unknown>;
  /** Get the window ID. */
  windowId(): Promise<number>;
  /** Resize the page. */
  resize(options: Record<string, unknown>): Promise<void>;
  /** Wait for a device prompt (e.g., Bluetooth, USB). */
  waitForDevicePrompt(options?: Record<string, unknown>): Promise<unknown>;
  /** Query all objects of a given prototype. */
  queryObjects(): Promise<unknown>;
  /** Open DevTools. Only works in headful mode. */
  openDevTools(options?: Record<string, unknown>): Promise<void>;

  // --- mouse methods ---
  /** Click at specific coordinates. */
  'mouse.click'(x: number, y: number, options?: Record<string, unknown>): Promise<void>;
  /** Move mouse to specific coordinates. */
  'mouse.move'(x: number, y: number, options?: Record<string, unknown>): Promise<void>;
  /** Press mouse button down. */
  'mouse.down'(options?: Record<string, unknown>): Promise<void>;
  /** Release mouse button. */
  'mouse.up'(options?: Record<string, unknown>): Promise<void>;
  /** Scroll mouse wheel. */
  'mouse.wheel'(options?: Record<string, unknown>): Promise<void>;
  /** Dispatches a drag event. */
  'mouse.drag'(start: string, target: string): Promise<unknown>;
  /** Perform a drag and drop operation. */
  'mouse.dragAndDrop'(start: string, target: string, options?: Record<string, unknown>): Promise<void>;
  /** Dispatches a dragenter event. */
  'mouse.dragEnter'(target: string, data: Record<string, unknown>): Promise<void>;
  /** Dispatches a dragover event. */
  'mouse.dragOver'(target: string, data: Record<string, unknown>): Promise<void>;
  /** Performs a dragenter, dragover, and drop in sequence. */
  'mouse.drop'(target: string, data: Record<string, unknown>): Promise<void>;
  /** Resets the mouse to the default state. */
  'mouse.reset'(): Promise<void>;

  // --- keyboard methods ---
  /** Dispatches a `keydown` event. */
  'keyboard.down'(key: string, options?: Record<string, unknown>): Promise<void>;
  /** Dispatches a `keyup` event. */
  'keyboard.up'(key: string): Promise<void>;
  /** Shortcut for `Keyboard.down` and `Keyboard.up`. */
  'keyboard.press'(key: string, options?: Record<string, unknown>): Promise<void>;
  /** Dispatches a `keypress` and `input` event. This does not send a `keydown` or `keyup` event. */
  'keyboard.sendCharacter'(char: string): Promise<void>;
  /** Sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text. */
  'keyboard.type'(text: string, options?: Record<string, unknown>): Promise<void>;

  // --- touchscreen methods ---
  /** Dispatches a `touchstart` and `touchend` event (simulates a tap). */
  'touchscreen.tap'(x: number, y: number): Promise<void>;
  /** Dispatches a `touchstart` event. */
  'touchscreen.touchStart'(x: number, y: number): Promise<unknown>;
  /** Dispatches a `touchmove` event on the active touch. */
  'touchscreen.touchMove'(x: number, y: number): Promise<void>;
  /** Dispatches a `touchend` event. */
  'touchscreen.touchEnd'(): Promise<void>;
}

export interface ScriptCaptcha {
  detect(): Promise<unknown>;
  solve(opts?: Record<string, unknown>): Promise<unknown>;
}

export interface ScriptContext<TScriptPage extends BaseScriptPage = ScriptPage> {
  page: TScriptPage;
  stagehand: ScriptStagehand;
  storage: ScriptStorage;
  captcha: ScriptCaptcha;
  params: Record<string, any>;
  log: ScriptLogger;
  [key: string]: unknown;
}

export interface ScriptDefaults {
  timeoutMs?: number;
  driver?: DriverType;
  pageId?: string;
  logs?: ExecuteLogsMode;
}

export interface ScriptDefinition<
  TParams extends ZodTypeAny,
  TResult,
  TScriptPage extends BaseScriptPage = BaseScriptPage,
> {
  kind: 'bctrl.script';
  name: string;
  params: TParams;
  run: (ctx: ScriptContext<TScriptPage> & ZodInfer<TParams>) => Promise<TResult> | TResult;
  returns?: ZodType<TResult>;
  defaults?: ScriptDefaults;
}

export interface ScriptExecutionOptions {
  timeoutMs?: number;
  pageId?: string;
  logs?: ExecuteLogsMode;
  onLog?: (entry: ExecuteLogEntry) => void;
}

export interface ScriptLogger {
  log(...args: unknown[]): void;
  info(...args: unknown[]): void;
  warn(...args: unknown[]): void;
  error(...args: unknown[]): void;
}

export interface ScriptPage extends BaseScriptPage {}

export interface ScriptStagehand {
  act(instruction: string): Promise<unknown>;
  extract(instruction: string): Promise<unknown>;
  observe(instruction?: string | null): Promise<unknown>;
}

export interface ScriptStorage {
  upload(filePath: string, data: string, contentType?: string): Promise<string>;
  browse(prefix?: string, cursor?: string, limit?: number): Promise<ScriptStorageBrowseResult>;
  read(filePath: string, maxBytes?: number): Promise<ScriptStorageReadResult>;
  get(filePath: string): Promise<ScriptStorageGetResult>;
  exists(filePath: string): Promise<boolean>;
}

export interface StagehandScriptPage extends BaseScriptPage {
  /** Navigate the page to a URL. */
  goto(url: string, options?: Record<string, unknown>): Promise<unknown>;
  /** Reload the current page. */
  reload(options?: Record<string, unknown>): Promise<unknown>;
  /** Navigate to the previous page in history. */
  goBack(options?: Record<string, unknown>): Promise<unknown>;
  /** Navigate to the next page in history. */
  goForward(options?: Record<string, unknown>): Promise<unknown>;
  /** Get the current URL of the page. */
  url(): Promise<string>;
  /** Get the title of the page. */
  title(): Promise<string>;
  /** Click at the specified coordinates. */
  click(x: number, y: number, options?: Record<string, unknown>): Promise<unknown>;
  /** Hover at the specified coordinates. */
  hover(x: number, y: number, options?: Record<string, unknown>): Promise<unknown>;
  /** Scroll at the specified position by the given delta. */
  scroll(x: number, y: number, deltaX: number, deltaY: number): Promise<void>;
  /** Drag from one point to another. */
  dragAndDrop(fromX: number, fromY: number, toX: number, toY: number, options?: Record<string, unknown>): Promise<unknown>;
  /** Type text into the currently focused element. */
  type(text: string, options?: Record<string, unknown>): Promise<void>;
  /** Execute JavaScript code within the page context. */
  evaluate(pageFunction: Function | string, arg?: unknown): Promise<unknown>;
  /** Add an initialization script that runs before page scripts. */
  addInitScript(script: Function | string, arg?: unknown): Promise<void>;
  /** Capture a screenshot of the page. */
  screenshot(options?: Record<string, unknown>): Promise<string>;
  /** Get a snapshot of the page DOM. */
  snapshot(options?: Record<string, unknown>): Promise<unknown>;
  /** Set the viewport size of the page. */
  setViewportSize(width: number, height: number, options?: Record<string, unknown>): Promise<void>;
  /** Wait for the page to reach a specific load state. */
  waitForLoadState(state?: string, options?: Record<string, unknown>): Promise<void>;
  /** Wait for an element matching the selector to appear. */
  waitForSelector(selector: string, options?: Record<string, unknown>): Promise<void>;
}

export type ExecuteLogLevel = 'log' | 'warn' | 'error';

export type ExecuteLogsMode = 'off' | 'capture';

export type ScriptFn<T = unknown, TScriptPage extends BaseScriptPage = ScriptPage> = (
  ctx: ScriptContext<TScriptPage>
) => Promise<T> | T;

export type ScriptParamsInput<TScript extends ScriptDefinition<ZodTypeAny, unknown, BaseScriptPage>> =
  ZodInput<TScript['params']>;

export type ScriptParamsOutput<TScript extends ScriptDefinition<ZodTypeAny, unknown, BaseScriptPage>> =
  ZodOutput<TScript['params']>;

export type ScriptResult<TScript extends ScriptDefinition<ZodTypeAny, unknown, BaseScriptPage>> =
  TScript extends ScriptDefinition<ZodTypeAny, infer TResult, BaseScriptPage> ? TResult : never;