@browserbasehq/orca 3.0.9-alpha-4 → 3.1.0-patch.1

package/dist/esm/lib/v3/handlers/extractHandler.js

@@ -0,0 +1,139 @@
+// lib/v3/handlers/extractHandler.ts
+import { extract as runExtract } from "../../inference.js";
+import { getZFactory, getZodType, injectUrls, transformSchema, } from "../../utils.js";
+import { v3Logger } from "../logger.js";
+import { V3FunctionName } from "../types/public/methods.js";
+import { captureHybridSnapshot } from "../understudy/a11y/snapshot/index.js";
+import { defaultExtractSchema, pageTextSchema, } from "../types/public/methods.js";
+import { StagehandInvalidArgumentError, ExtractTimeoutError, } from "../types/public/sdkErrors.js";
+import { createTimeoutGuard } from "./handlerUtils/timeoutGuard.js";
+/**
+ * Scans the provided Zod schema for any `z.string().url()` fields and
+ * replaces them with `z.number()`.
+ *
+ * @param schema - The Zod object schema to transform.
+ * @returns A tuple containing:
+ *   1. The transformed schema (or the original schema if no changes were needed).
+ *   2. An array of {@link ZodPathSegments} objects representing all the replaced URL fields,
+ *      with each path segment showing where in the schema the replacement occurred.
+ */
+export function transformUrlStringsToNumericIds(schema) {
+    const [finalSchema, urlPaths] = transformSchema(schema, []);
+    return [finalSchema, urlPaths];
+}
+export class ExtractHandler {
+    llmClient;
+    defaultModelName;
+    defaultClientOptions;
+    resolveLlmClient;
+    systemPrompt;
+    logInferenceToFile;
+    experimental;
+    onMetrics;
+    constructor(llmClient, defaultModelName, defaultClientOptions, resolveLlmClient, systemPrompt, logInferenceToFile, experimental, onMetrics) {
+        this.llmClient = llmClient;
+        this.defaultModelName = defaultModelName;
+        this.defaultClientOptions = defaultClientOptions;
+        this.resolveLlmClient = resolveLlmClient;
+        this.systemPrompt = systemPrompt ?? "";
+        this.logInferenceToFile = logInferenceToFile ?? false;
+        this.experimental = experimental ?? false;
+        this.onMetrics = onMetrics;
+    }
+    async extract(params) {
+        const { instruction, schema, page, selector, timeout, model } = params;
+        const llmClient = this.resolveLlmClient(model);
+        const effectiveTimeoutMs = typeof timeout === "number" && timeout > 0 ? timeout : undefined;
+        const ensureTimeRemaining = createTimeoutGuard(effectiveTimeoutMs, (ms) => new ExtractTimeoutError(ms));
+        // No-args → page text (parity with v2)
+        const noArgs = !instruction && !schema;
+        if (noArgs) {
+            const focusSelector = selector?.replace(/^xpath=/i, "") ?? "";
+            ensureTimeRemaining();
+            const snap = await captureHybridSnapshot(page, {
+                experimental: this.experimental,
+                focusSelector: focusSelector || undefined,
+            });
+            const result = { pageText: snap.combinedTree };
+            // Validate via the same schema used in v2
+            return pageTextSchema.parse(result);
+        }
+        if (!instruction && schema) {
+            throw new StagehandInvalidArgumentError("extract() requires an instruction when a schema is provided.");
+        }
+        const focusSelector = selector?.replace(/^xpath=/, "") ?? "";
+        // Build the hybrid snapshot (includes combinedTree; combinedUrlMap optional)
+        ensureTimeRemaining();
+        const { combinedTree, combinedUrlMap } = await captureHybridSnapshot(page, {
+            experimental: this.experimental,
+            focusSelector: focusSelector,
+        });
+        v3Logger({
+            category: "extraction",
+            message: "Starting extraction using a11y snapshot",
+            level: 1,
+            auxiliary: instruction
+                ? { instruction: { value: instruction, type: "string" } }
+                : undefined,
+        });
+        // Normalize schema: if instruction provided without schema, use defaultExtractSchema
+        const baseSchema = (schema ??
+            defaultExtractSchema);
+        // Ensure we pass an object schema into inference; wrap non-object schemas
+        const isObjectSchema = getZodType(baseSchema) === "object";
+        const WRAP_KEY = "value";
+        const factory = getZFactory(baseSchema);
+        const objectSchema = isObjectSchema
+            ? baseSchema
+            : factory.object({
+                [WRAP_KEY]: baseSchema,
+            });
+        const [transformedSchema, urlFieldPaths] = transformUrlStringsToNumericIds(objectSchema);
+        ensureTimeRemaining();
+        const extractionResponse = await runExtract({
+            instruction,
+            domElements: combinedTree,
+            schema: transformedSchema,
+            llmClient,
+            userProvidedInstructions: this.systemPrompt,
+            logger: v3Logger,
+            logInferenceToFile: this.logInferenceToFile,
+        });
+        const { metadata: { completed }, prompt_tokens, completion_tokens, reasoning_tokens = 0, cached_input_tokens = 0, inference_time_ms, ...rest } = extractionResponse;
+        let output = rest;
+        // Update EXTRACT metrics from the LLM calls
+        this.onMetrics?.(V3FunctionName.EXTRACT, prompt_tokens, completion_tokens, reasoning_tokens, cached_input_tokens, inference_time_ms);
+        // Re-inject URLs for any url() fields we temporarily converted to number()
+        const idToUrl = (combinedUrlMap ?? {});
+        for (const { segments } of urlFieldPaths) {
+            injectUrls(output, segments, idToUrl);
+        }
+        // If we wrapped a non-object schema, unwrap the value
+        if (!isObjectSchema && output && typeof output === "object") {
+            output = output[WRAP_KEY];
+        }
+        const resultPreviewLength = 200;
+        const resultString = JSON.stringify(output) ?? "undefined";
+        const resultPreview = resultString.length > resultPreviewLength
+            ? resultString.slice(0, resultPreviewLength) + "..."
+            : resultString;
+        v3Logger({
+            category: "extraction",
+            message: completed
+                ? "Extraction completed successfully"
+                : "Extraction incomplete after processing all data",
+            level: 1,
+            auxiliary: {
+                prompt_tokens: { value: String(prompt_tokens), type: "string" },
+                completion_tokens: { value: String(completion_tokens), type: "string" },
+                inference_time_ms: {
+                    value: String(inference_time_ms),
+                    type: "string",
+                },
+                result: { value: resultPreview, type: "string" },
+            },
+        });
+        return output;
+    }
+}
+//# sourceMappingURL=extractHandler.js.map

package/dist/esm/lib/v3/handlers/extractHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractHandler.js","sourceRoot":"","sources":["../../../../../lib/v3/handlers/extractHandler.ts"],"names":[],"mappings":"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","sourcesContent":["// lib/v3/handlers/extractHandler.ts\nimport { extract as runExtract } from \"../../inference.js\";\nimport {\n  getZFactory,\n  getZodType,\n  injectUrls,\n  transformSchema,\n} from \"../../utils.js\";\nimport { v3Logger } from \"../logger.js\";\nimport { V3FunctionName } from \"../types/public/methods.js\";\nimport { captureHybridSnapshot } from \"../understudy/a11y/snapshot/index.js\";\nimport type { ZodTypeAny } from \"zod\";\nimport { LLMClient } from \"../llm/LLMClient.js\";\nimport { ExtractHandlerParams } from \"../types/private/handlers.js\";\nimport { EncodedId, ZodPathSegments } from \"../types/private/internal.js\";\nimport {\n  defaultExtractSchema,\n  pageTextSchema,\n} from \"../types/public/methods.js\";\nimport {\n  AvailableModel,\n  ClientOptions,\n  ModelConfiguration,\n} from \"../types/public/model.js\";\nimport {\n  StagehandInvalidArgumentError,\n  ExtractTimeoutError,\n} from \"../types/public/sdkErrors.js\";\nimport { createTimeoutGuard } from \"./handlerUtils/timeoutGuard.js\";\nimport type {\n  InferStagehandSchema,\n  StagehandZodObject,\n  StagehandZodSchema,\n} from \"../zodCompat.js\";\n\n/**\n * Scans the provided Zod schema for any `z.string().url()` fields and\n * replaces them with `z.number()`.\n *\n * @param schema - The Zod object schema to transform.\n * @returns A tuple containing:\n *   1. The transformed schema (or the original schema if no changes were needed).\n *   2. An array of {@link ZodPathSegments} objects representing all the replaced URL fields,\n *      with each path segment showing where in the schema the replacement occurred.\n */\nexport function transformUrlStringsToNumericIds<T extends StagehandZodSchema>(\n  schema: T,\n): [StagehandZodSchema, ZodPathSegments[]] {\n  const [finalSchema, urlPaths] = transformSchema(schema, []);\n  return [finalSchema, urlPaths];\n}\n\ninterface ExtractionResponseBase {\n  metadata: { completed: boolean };\n  prompt_tokens: number;\n  completion_tokens: number;\n  reasoning_tokens: number;\n  cached_input_tokens?: number;\n  inference_time_ms: number;\n}\n\ntype ExtractionResponse<T extends StagehandZodObject> = ExtractionResponseBase &\n  InferStagehandSchema<T>;\n\nexport class ExtractHandler {\n  private readonly llmClient: LLMClient;\n  private readonly defaultModelName: AvailableModel;\n  private readonly defaultClientOptions: ClientOptions;\n  private readonly resolveLlmClient: (model?: ModelConfiguration) => LLMClient;\n  private readonly systemPrompt: string;\n  private readonly logInferenceToFile: boolean;\n  private readonly experimental: boolean;\n  private readonly onMetrics?: (\n    functionName: V3FunctionName,\n    promptTokens: number,\n    completionTokens: number,\n    reasoningTokens: number,\n    cachedInputTokens: number,\n    inferenceTimeMs: number,\n  ) => void;\n\n  constructor(\n    llmClient: LLMClient,\n    defaultModelName: AvailableModel,\n    defaultClientOptions: ClientOptions,\n    resolveLlmClient: (model?: ModelConfiguration) => LLMClient,\n    systemPrompt?: string,\n    logInferenceToFile?: boolean,\n    experimental?: boolean,\n    onMetrics?: (\n      functionName: V3FunctionName,\n      promptTokens: number,\n      completionTokens: number,\n      reasoningTokens: number,\n      cachedInputTokens: number,\n      inferenceTimeMs: number,\n    ) => void,\n  ) {\n    this.llmClient = llmClient;\n    this.defaultModelName = defaultModelName;\n    this.defaultClientOptions = defaultClientOptions;\n    this.resolveLlmClient = resolveLlmClient;\n    this.systemPrompt = systemPrompt ?? \"\";\n    this.logInferenceToFile = logInferenceToFile ?? false;\n    this.experimental = experimental ?? false;\n    this.onMetrics = onMetrics;\n  }\n\n  async extract<T extends StagehandZodSchema>(\n    params: ExtractHandlerParams<T>,\n  ): Promise<InferStagehandSchema<T> | { pageText: string }> {\n    const { instruction, schema, page, selector, timeout, model } = params;\n\n    const llmClient = this.resolveLlmClient(model);\n\n    const effectiveTimeoutMs =\n      typeof timeout === \"number\" && timeout > 0 ? timeout : undefined;\n    const ensureTimeRemaining = createTimeoutGuard(\n      effectiveTimeoutMs,\n      (ms) => new ExtractTimeoutError(ms),\n    );\n\n    // No-args → page text (parity with v2)\n    const noArgs = !instruction && !schema;\n    if (noArgs) {\n      const focusSelector = selector?.replace(/^xpath=/i, \"\") ?? \"\";\n      ensureTimeRemaining();\n      const snap = await captureHybridSnapshot(page, {\n        experimental: this.experimental,\n        focusSelector: focusSelector || undefined,\n      });\n\n      const result = { pageText: snap.combinedTree };\n      // Validate via the same schema used in v2\n      return pageTextSchema.parse(result);\n    }\n\n    if (!instruction && schema) {\n      throw new StagehandInvalidArgumentError(\n        \"extract() requires an instruction when a schema is provided.\",\n      );\n    }\n\n    const focusSelector = selector?.replace(/^xpath=/, \"\") ?? \"\";\n\n    // Build the hybrid snapshot (includes combinedTree; combinedUrlMap optional)\n    ensureTimeRemaining();\n    const { combinedTree, combinedUrlMap } = await captureHybridSnapshot(page, {\n      experimental: this.experimental,\n      focusSelector: focusSelector,\n    });\n\n    v3Logger({\n      category: \"extraction\",\n      message: \"Starting extraction using a11y snapshot\",\n      level: 1,\n      auxiliary: instruction\n        ? { instruction: { value: instruction, type: \"string\" } }\n        : undefined,\n    });\n\n    // Normalize schema: if instruction provided without schema, use defaultExtractSchema\n    const baseSchema: StagehandZodSchema = (schema ??\n      defaultExtractSchema) as StagehandZodSchema;\n    // Ensure we pass an object schema into inference; wrap non-object schemas\n    const isObjectSchema = getZodType(baseSchema) === \"object\";\n    const WRAP_KEY = \"value\" as const;\n    const factory = getZFactory(baseSchema);\n    const objectSchema: StagehandZodObject = isObjectSchema\n      ? (baseSchema as StagehandZodObject)\n      : (factory.object({\n          [WRAP_KEY]: baseSchema as ZodTypeAny,\n        }) as StagehandZodObject);\n\n    const [transformedSchema, urlFieldPaths] =\n      transformUrlStringsToNumericIds(objectSchema);\n\n    ensureTimeRemaining();\n    const extractionResponse: ExtractionResponse<StagehandZodObject> =\n      await runExtract<StagehandZodObject>({\n        instruction,\n        domElements: combinedTree,\n        schema: transformedSchema as StagehandZodObject,\n        llmClient,\n        userProvidedInstructions: this.systemPrompt,\n        logger: v3Logger,\n        logInferenceToFile: this.logInferenceToFile,\n      });\n\n    const {\n      metadata: { completed },\n      prompt_tokens,\n      completion_tokens,\n      reasoning_tokens = 0,\n      cached_input_tokens = 0,\n      inference_time_ms,\n      ...rest\n    } = extractionResponse;\n    let output = rest as InferStagehandSchema<StagehandZodObject>;\n\n    // Update EXTRACT metrics from the LLM calls\n    this.onMetrics?.(\n      V3FunctionName.EXTRACT,\n      prompt_tokens,\n      completion_tokens,\n      reasoning_tokens,\n      cached_input_tokens,\n      inference_time_ms,\n    );\n\n    // Re-inject URLs for any url() fields we temporarily converted to number()\n    const idToUrl: Record<EncodedId, string> = (combinedUrlMap ?? {}) as Record<\n      EncodedId,\n      string\n    >;\n    for (const { segments } of urlFieldPaths) {\n      injectUrls(\n        output as Record<string, unknown>,\n        segments,\n        idToUrl as unknown as Record<string, string>,\n      );\n    }\n    // If we wrapped a non-object schema, unwrap the value\n    if (!isObjectSchema && output && typeof output === \"object\") {\n      output = (output as Record<string, unknown>)[WRAP_KEY];\n    }\n\n    const resultPreviewLength = 200;\n    const resultString = JSON.stringify(output) ?? \"undefined\";\n    const resultPreview =\n      resultString.length > resultPreviewLength\n        ? resultString.slice(0, resultPreviewLength) + \"...\"\n        : resultString;\n\n    v3Logger({\n      category: \"extraction\",\n      message: completed\n        ? \"Extraction completed successfully\"\n        : \"Extraction incomplete after processing all data\",\n      level: 1,\n      auxiliary: {\n        prompt_tokens: { value: String(prompt_tokens), type: \"string\" },\n        completion_tokens: { value: String(completion_tokens), type: \"string\" },\n        inference_time_ms: {\n          value: String(inference_time_ms),\n          type: \"string\",\n        },\n        result: { value: resultPreview, type: \"string\" },\n      },\n    });\n\n    return output as InferStagehandSchema<T>;\n  }\n}\n"]}

package/dist/esm/lib/v3/handlers/handlerUtils/actHandlerUtils.d.ts

@@ -0,0 +1,24 @@
+import { Frame } from "../../understudy/frame.js";
+import { Locator } from "../../understudy/locator.js";
+import type { Page } from "../../understudy/page.js";
+export declare class UnderstudyCommandException extends Error {
+    constructor(message: string);
+}
+export interface UnderstudyMethodHandlerContext {
+    method: string;
+    locator: Locator;
+    xpath: string;
+    args: ReadonlyArray<string>;
+    frame: Frame;
+    page: Page;
+    initialUrl: string;
+    domSettleTimeoutMs?: number;
+}
+export declare function performUnderstudyMethod(page: Page, frame: Frame, method: string, rawXPath: string, args: ReadonlyArray<unknown>, domSettleTimeoutMs?: number): Promise<void>;
+export declare function selectOption(ctx: UnderstudyMethodHandlerContext): Promise<void>;
+export declare function hover(ctx: UnderstudyMethodHandlerContext): Promise<void>;
+/**
+ * More robust DOM settle using Network + Page events to detect network quiet.
+ * Closely modeled after the provided snippet, adapted to our Frame/session + logger.
+ */
+export declare function waitForDomNetworkQuiet(frame: Frame, timeoutMs?: number): Promise<void>;