@spicrawl/mcp 0.0.0-stage → 0.1.1

package/dist/server.js

@@ -0,0 +1,141 @@
+import { z } from "zod";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { PACKAGE_VERSION } from "./client.js";
+import { registerScrapeTools } from "./tools/scrape.js";
+import { registerBatchTools } from "./tools/batch.js";
+import { registerSessionsTools } from "./tools/sessions.js";
+import { registerUsageTools } from "./tools/usage.js";
+import { registerRequestsTools } from "./tools/requests.js";
+import { registerBrowserTools } from "./tools/browser.js";
+import { registerDocsTools } from "./tools/docs.js";
+export const SERVER_NAME = "spicrawl-mcp-server";
+export const SERVER_VERSION = PACKAGE_VERSION;
+// ---------------------------------------------------------------------------
+// Unknown arguments are refused, never dropped.
+//
+// zod's default object strips keys it does not know, so `js_render: true` (the
+// REST name; the tool calls it `render`) used to become a silent plain fetch —
+// the customer believes rendering is on and is billed for something else. The
+// Spicrawl API refuses unknown fields for exactly this reason; the MCP layer must
+// not bypass that. Every tool's top-level arguments are therefore a strict
+// object: an unknown key fails validation with a message naming it (and the
+// closest real argument), and tools/list advertises `additionalProperties:
+// false`. Free-form maps inside a tool (headers, JSON Schemas, records) stay open.
+// ---------------------------------------------------------------------------
+/** Names an agent is likely to guess (REST / other-scraper spellings) -> the tool's name. */
+const ALIASES = {
+    js_render: "render",
+    javascript: "render",
+    response_format: "format",
+    formats: "format",
+    only_main_content: "main_content_only",
+    onlyMainContent: "main_content_only",
+    includeTags: "include_tags",
+    excludeTags: "exclude_tags",
+    waitFor: "wait_for",
+    headers: "custom_headers",
+    country: "proxy_country",
+};
+const normalise = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, "");
+function levenshtein(a, b) {
+    let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
+    for (let i = 1; i <= a.length; i++) {
+        const cur = [i];
+        for (let j = 1; j <= b.length; j++) {
+            cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        prev = cur;
+    }
+    return prev[b.length];
+}
+/** The valid argument closest to `key`, if one is close enough to be a plausible typo. */
+function closestArgument(key, valid) {
+    const alias = ALIASES[key];
+    if (alias && valid.includes(alias))
+        return alias;
+    const nk = normalise(key);
+    // Candidates: every valid name, plus every alias whose target is valid (so a
+    // typo of a REST name, e.g. `js_rendr`, still lands on `render`).
+    const candidates = valid.map((v) => [v, v]);
+    for (const [a, target] of Object.entries(ALIASES))
+        if (valid.includes(target))
+            candidates.push([a, target]);
+    let best;
+    let bestDistance = Infinity;
+    for (const [spelling, target] of candidates) {
+        const d = levenshtein(nk, normalise(spelling));
+        if (d < bestDistance)
+            [best, bestDistance] = [target, d];
+    }
+    return bestDistance <= Math.max(1, Math.floor(nk.length / 3)) ? best : undefined;
+}
+function unknownArgumentsMessage(keys, valid) {
+    let unresolved = false;
+    const parts = keys.map((k) => {
+        const s = closestArgument(k, valid);
+        if (!s)
+            unresolved = true;
+        return s ? `unknown argument \`${k}\`; did you mean \`${s}\`?` : `unknown argument \`${k}\``;
+    });
+    let msg = parts.join("; ");
+    if (unresolved) {
+        msg += valid.length
+            ? ` (valid arguments: ${valid.map((v) => `\`${v}\``).join(", ")})`
+            : " (this tool takes no arguments)";
+    }
+    return msg;
+}
+/**
+ * Wraps a raw zod shape into a strict object: unknown keys are a validation
+ * error naming them (with a did-you-mean), and the JSON Schema carries
+ * `additionalProperties: false`. Descriptions and defaults are untouched.
+ */
+export function strictArgs(shape) {
+    const valid = Object.keys(shape);
+    const errorMap = (issue, ctx) => issue.code === z.ZodIssueCode.unrecognized_keys
+        ? { message: unknownArgumentsMessage(issue.keys, valid) }
+        : { message: ctx.defaultError };
+    return z.object(shape, { errorMap }).strict();
+}
+/** Makes a registerTool inputSchema strict: raw shapes and non-strict zod objects. */
+function strictInputSchema(schema) {
+    if (schema === undefined)
+        return undefined; // no schema -> SDK passes no args at all
+    if (schema instanceof z.ZodObject) {
+        return schema._def.unknownKeys === "strip" ? strictArgs(schema.shape) : schema;
+    }
+    const isSchemaInstance = "_def" in schema || "_zod" in schema;
+    return isSchemaInstance ? schema : strictArgs(schema);
+}
+/**
+ * McpServer whose registerTool makes every tool's input schema strict. Tools
+ * keep declaring plain raw shapes; this one place guarantees none of them (or
+ * any tool added later) can silently drop an argument.
+ */
+class StrictArgsMcpServer extends McpServer {
+    registerTool(name, config, cb) {
+        // The strict object parses to exactly what the raw shape did, so the
+        // callback's argument type is unchanged; only the declared type widens.
+        return super.registerTool(name, { ...config, inputSchema: strictInputSchema(config.inputSchema) }, cb);
+    }
+}
+/**
+ * One MCP server bound to one caller's API key. The stdio entry builds one for
+ * the process; the HTTP entry builds one per session, from that session's key.
+ */
+export function buildServer(client) {
+    const server = new StrictArgsMcpServer({ name: SERVER_NAME, version: SERVER_VERSION });
+    for (const register of [
+        registerScrapeTools,
+        registerBatchTools,
+        registerSessionsTools,
+        registerUsageTools,
+        registerRequestsTools,
+        registerBrowserTools,
+        registerDocsTools,
+    ]) {
+        register(server, client);
+    }
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/tools/actions.d.ts

@@ -0,0 +1,534 @@
+import { z } from "zod";
+export declare const ActionSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    type: z.ZodLiteral<"click">;
+} & {
+    selector: z.ZodString;
+    wait_for_navigation: z.ZodOptional<z.ZodBoolean>;
+    until: z.ZodOptional<z.ZodEnum<["load", "domcontentloaded", "networkidle"]>>;
+} & {
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+    on_error: z.ZodOptional<z.ZodEnum<["fail", "skip"]>>;
+    label: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    type: "click";
+    selector: string;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    wait_for_navigation?: boolean | undefined;
+    until?: "load" | "domcontentloaded" | "networkidle" | undefined;
+}, {
+    type: "click";
+    selector: string;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    wait_for_navigation?: boolean | undefined;
+    until?: "load" | "domcontentloaded" | "networkidle" | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"fill">;
+} & {
+    selector: z.ZodString;
+    value: z.ZodString;
+    secret: z.ZodOptional<z.ZodBoolean>;
+} & {
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+    on_error: z.ZodOptional<z.ZodEnum<["fail", "skip"]>>;
+    label: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    type: "fill";
+    value: string;
+    selector: string;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    secret?: boolean | undefined;
+}, {
+    type: "fill";
+    value: string;
+    selector: string;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    secret?: boolean | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"wait_for">;
+} & {
+    selector: z.ZodOptional<z.ZodString>;
+    ms: z.ZodOptional<z.ZodNumber>;
+} & {
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+    on_error: z.ZodOptional<z.ZodEnum<["fail", "skip"]>>;
+    label: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    type: "wait_for";
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    selector?: string | undefined;
+    ms?: number | undefined;
+}, {
+    type: "wait_for";
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    selector?: string | undefined;
+    ms?: number | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"wait_for_navigation">;
+} & {
+    until: z.ZodOptional<z.ZodEnum<["load", "domcontentloaded", "networkidle"]>>;
+} & {
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+    on_error: z.ZodOptional<z.ZodEnum<["fail", "skip"]>>;
+    label: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    type: "wait_for_navigation";
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    until?: "load" | "domcontentloaded" | "networkidle" | undefined;
+}, {
+    type: "wait_for_navigation";
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    until?: "load" | "domcontentloaded" | "networkidle" | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"scroll">;
+} & {
+    y: z.ZodOptional<z.ZodNumber>;
+    to_bottom: z.ZodOptional<z.ZodBoolean>;
+    selector: z.ZodOptional<z.ZodString>;
+} & {
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+    on_error: z.ZodOptional<z.ZodEnum<["fail", "skip"]>>;
+    label: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    type: "scroll";
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    selector?: string | undefined;
+    y?: number | undefined;
+    to_bottom?: boolean | undefined;
+}, {
+    type: "scroll";
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    selector?: string | undefined;
+    y?: number | undefined;
+    to_bottom?: boolean | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"select">;
+} & {
+    selector: z.ZodString;
+    value: z.ZodOptional<z.ZodString>;
+    values: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+} & {
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+    on_error: z.ZodOptional<z.ZodEnum<["fail", "skip"]>>;
+    label: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    type: "select";
+    selector: string;
+    values?: string[] | undefined;
+    value?: string | undefined;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+}, {
+    type: "select";
+    selector: string;
+    values?: string[] | undefined;
+    value?: string | undefined;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"evaluate">;
+} & {
+    expression: z.ZodString;
+    return_value: z.ZodOptional<z.ZodBoolean>;
+    await_promise: z.ZodOptional<z.ZodBoolean>;
+} & {
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+    on_error: z.ZodOptional<z.ZodEnum<["fail", "skip"]>>;
+    label: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    type: "evaluate";
+    expression: string;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    return_value?: boolean | undefined;
+    await_promise?: boolean | undefined;
+}, {
+    type: "evaluate";
+    expression: string;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    return_value?: boolean | undefined;
+    await_promise?: boolean | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"screenshot">;
+} & {
+    full_page: z.ZodOptional<z.ZodBoolean>;
+    selector: z.ZodOptional<z.ZodString>;
+    format: z.ZodOptional<z.ZodEnum<["png", "jpeg", "webp"]>>;
+    quality: z.ZodOptional<z.ZodNumber>;
+} & {
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+    on_error: z.ZodOptional<z.ZodEnum<["fail", "skip"]>>;
+    label: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    type: "screenshot";
+    format?: "png" | "jpeg" | "webp" | undefined;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    selector?: string | undefined;
+    full_page?: boolean | undefined;
+    quality?: number | undefined;
+}, {
+    type: "screenshot";
+    format?: "png" | "jpeg" | "webp" | undefined;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    selector?: string | undefined;
+    full_page?: boolean | undefined;
+    quality?: number | undefined;
+}>]>;
+export type Action = z.infer<typeof ActionSchema>;
+export declare const ActionsSchema: z.ZodEffects<z.ZodArray<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    type: z.ZodLiteral<"click">;
+} & {
+    selector: z.ZodString;
+    wait_for_navigation: z.ZodOptional<z.ZodBoolean>;
+    until: z.ZodOptional<z.ZodEnum<["load", "domcontentloaded", "networkidle"]>>;
+} & {
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+    on_error: z.ZodOptional<z.ZodEnum<["fail", "skip"]>>;
+    label: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    type: "click";
+    selector: string;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    wait_for_navigation?: boolean | undefined;
+    until?: "load" | "domcontentloaded" | "networkidle" | undefined;
+}, {
+    type: "click";
+    selector: string;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    wait_for_navigation?: boolean | undefined;
+    until?: "load" | "domcontentloaded" | "networkidle" | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"fill">;
+} & {
+    selector: z.ZodString;
+    value: z.ZodString;
+    secret: z.ZodOptional<z.ZodBoolean>;
+} & {
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+    on_error: z.ZodOptional<z.ZodEnum<["fail", "skip"]>>;
+    label: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    type: "fill";
+    value: string;
+    selector: string;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    secret?: boolean | undefined;
+}, {
+    type: "fill";
+    value: string;
+    selector: string;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    secret?: boolean | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"wait_for">;
+} & {
+    selector: z.ZodOptional<z.ZodString>;
+    ms: z.ZodOptional<z.ZodNumber>;
+} & {
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+    on_error: z.ZodOptional<z.ZodEnum<["fail", "skip"]>>;
+    label: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    type: "wait_for";
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    selector?: string | undefined;
+    ms?: number | undefined;
+}, {
+    type: "wait_for";
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    selector?: string | undefined;
+    ms?: number | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"wait_for_navigation">;
+} & {
+    until: z.ZodOptional<z.ZodEnum<["load", "domcontentloaded", "networkidle"]>>;
+} & {
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+    on_error: z.ZodOptional<z.ZodEnum<["fail", "skip"]>>;
+    label: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    type: "wait_for_navigation";
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    until?: "load" | "domcontentloaded" | "networkidle" | undefined;
+}, {
+    type: "wait_for_navigation";
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    until?: "load" | "domcontentloaded" | "networkidle" | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"scroll">;
+} & {
+    y: z.ZodOptional<z.ZodNumber>;
+    to_bottom: z.ZodOptional<z.ZodBoolean>;
+    selector: z.ZodOptional<z.ZodString>;
+} & {
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+    on_error: z.ZodOptional<z.ZodEnum<["fail", "skip"]>>;
+    label: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    type: "scroll";
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    selector?: string | undefined;
+    y?: number | undefined;
+    to_bottom?: boolean | undefined;
+}, {
+    type: "scroll";
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    selector?: string | undefined;
+    y?: number | undefined;
+    to_bottom?: boolean | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"select">;
+} & {
+    selector: z.ZodString;
+    value: z.ZodOptional<z.ZodString>;
+    values: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+} & {
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+    on_error: z.ZodOptional<z.ZodEnum<["fail", "skip"]>>;
+    label: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    type: "select";
+    selector: string;
+    values?: string[] | undefined;
+    value?: string | undefined;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+}, {
+    type: "select";
+    selector: string;
+    values?: string[] | undefined;
+    value?: string | undefined;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"evaluate">;
+} & {
+    expression: z.ZodString;
+    return_value: z.ZodOptional<z.ZodBoolean>;
+    await_promise: z.ZodOptional<z.ZodBoolean>;
+} & {
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+    on_error: z.ZodOptional<z.ZodEnum<["fail", "skip"]>>;
+    label: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    type: "evaluate";
+    expression: string;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    return_value?: boolean | undefined;
+    await_promise?: boolean | undefined;
+}, {
+    type: "evaluate";
+    expression: string;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    return_value?: boolean | undefined;
+    await_promise?: boolean | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"screenshot">;
+} & {
+    full_page: z.ZodOptional<z.ZodBoolean>;
+    selector: z.ZodOptional<z.ZodString>;
+    format: z.ZodOptional<z.ZodEnum<["png", "jpeg", "webp"]>>;
+    quality: z.ZodOptional<z.ZodNumber>;
+} & {
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+    on_error: z.ZodOptional<z.ZodEnum<["fail", "skip"]>>;
+    label: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    type: "screenshot";
+    format?: "png" | "jpeg" | "webp" | undefined;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    selector?: string | undefined;
+    full_page?: boolean | undefined;
+    quality?: number | undefined;
+}, {
+    type: "screenshot";
+    format?: "png" | "jpeg" | "webp" | undefined;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    selector?: string | undefined;
+    full_page?: boolean | undefined;
+    quality?: number | undefined;
+}>]>, "many">, ({
+    type: "click";
+    selector: string;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    wait_for_navigation?: boolean | undefined;
+    until?: "load" | "domcontentloaded" | "networkidle" | undefined;
+} | {
+    type: "fill";
+    value: string;
+    selector: string;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    secret?: boolean | undefined;
+} | {
+    type: "wait_for";
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    selector?: string | undefined;
+    ms?: number | undefined;
+} | {
+    type: "wait_for_navigation";
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    until?: "load" | "domcontentloaded" | "networkidle" | undefined;
+} | {
+    type: "scroll";
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    selector?: string | undefined;
+    y?: number | undefined;
+    to_bottom?: boolean | undefined;
+} | {
+    type: "select";
+    selector: string;
+    values?: string[] | undefined;
+    value?: string | undefined;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+} | {
+    type: "evaluate";
+    expression: string;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    return_value?: boolean | undefined;
+    await_promise?: boolean | undefined;
+} | {
+    type: "screenshot";
+    format?: "png" | "jpeg" | "webp" | undefined;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    selector?: string | undefined;
+    full_page?: boolean | undefined;
+    quality?: number | undefined;
+})[], ({
+    type: "click";
+    selector: string;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    wait_for_navigation?: boolean | undefined;
+    until?: "load" | "domcontentloaded" | "networkidle" | undefined;
+} | {
+    type: "fill";
+    value: string;
+    selector: string;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    secret?: boolean | undefined;
+} | {
+    type: "wait_for";
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    selector?: string | undefined;
+    ms?: number | undefined;
+} | {
+    type: "wait_for_navigation";
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    until?: "load" | "domcontentloaded" | "networkidle" | undefined;
+} | {
+    type: "scroll";
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    selector?: string | undefined;
+    y?: number | undefined;
+    to_bottom?: boolean | undefined;
+} | {
+    type: "select";
+    selector: string;
+    values?: string[] | undefined;
+    value?: string | undefined;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+} | {
+    type: "evaluate";
+    expression: string;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    return_value?: boolean | undefined;
+    await_promise?: boolean | undefined;
+} | {
+    type: "screenshot";
+    format?: "png" | "jpeg" | "webp" | undefined;
+    timeout_ms?: number | undefined;
+    on_error?: "fail" | "skip" | undefined;
+    label?: string | undefined;
+    selector?: string | undefined;
+    full_page?: boolean | undefined;
+    quality?: number | undefined;
+})[]>;
+/** Map typed steps onto the API's keyed shape: {kind: {fields}, timeout_ms?, on_error?, label?}. */
+export declare function toApiActions(steps: Action[]): Record<string, unknown>[];