@nodetool-ai/agents 0.7.0-rc.23 → 0.8.2

package/dist/serpapi/catalog.js.map

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

package/dist/serpapi/client.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The SerpAPI HTTP client — the only code in this layer that holds the API key.
+ *
+ * Everything above it (the catalog, the capability module, the sandbox) works
+ * in terms of engine ids and plain parameter objects. The key is
+ * constructor-private, is attached to a request and never to a result, and is
+ * scrubbed out of every error before it is thrown, so there is no path by which
+ * it reaches guest code, a tool result, a model's context, or a log line.
+ *
+ * Endpoints, verified against serpapi.com:
+ *
+ *   GET /search.json?engine=<engine>&…   run any of the catalogued engines
+ *   GET /account.json                    plan, searches used, searches left
+ *   GET /locations.json?q=&limit=        canonical values for `location`
+ *
+ * There is one search method for all 120 engines rather than one per engine.
+ * That is the whole point of this layer: SerpAPI's own surface is a single
+ * endpoint whose `engine` parameter selects the contract, so a wrapper per
+ * engine would be a backlog that never catches up with what SerpAPI ships.
+ */
+/** The public API root. Not configurable: it is also the SSRF answer. */
+export declare const SERPAPI_BASE = "https://serpapi.com";
+/** Parameter values SerpAPI accepts on the query string. */
+export type SerpApiParamValue = string | number | boolean;
+export interface SerpApiClientOptions {
+    /** Injected for tests; defaults to the global fetch. */
+    readonly fetchImpl?: typeof fetch;
+    /** Per-request ceiling, in milliseconds. Not the run's deadline. */
+    readonly requestTimeoutMs?: number;
+    /** Attempts for a retryable failure, including the first. */
+    readonly maxAttempts?: number;
+    /** Base backoff, doubled per attempt. */
+    readonly retryBaseMs?: number;
+}
+/**
+ * Parameters the host owns, which a caller may not set.
+ *
+ * `api_key` is the credential and `output` decides whether the response is JSON
+ * at all — a guest that could set either would either exfiltrate the key or
+ * hand this layer HTML it cannot parse.
+ */
+export declare const HOST_OWNED_PARAMS: ReadonlySet<string>;
+/** One account record, as much of it as anything above this layer reads. */
+export interface SerpApiAccount {
+    readonly plan?: string;
+    readonly searchesPerMonth?: number;
+    readonly thisMonthUsage?: number;
+    readonly totalSearchesLeft?: number;
+}
+/** One location suggestion, as `location` wants it spelled. */
+export interface SerpApiLocation {
+    readonly name: string;
+    readonly canonicalName: string;
+    readonly countryCode?: string;
+    readonly targetType?: string;
+    readonly reach?: number;
+}
+export declare class SerpApiClient {
+    #private;
+    constructor(key: string, options?: SerpApiClientOptions);
+    /**
+     * Run one search on any engine.
+     *
+     * `params` is passed through as the engine's own contract spells it — this
+     * client knows nothing about what `google_scholar` wants and
+     * `walmart_product` does not. Validation against the catalogued schema
+     * happens a layer up, where the schema lives.
+     */
+    search(engine: string, params: Readonly<Record<string, SerpApiParamValue>>, signal?: AbortSignal): Promise<Record<string, unknown>>;
+    /** Plan and remaining searches, so a caller can see its own budget. */
+    account(signal?: AbortSignal): Promise<SerpApiAccount>;
+    /**
+     * Canonical values for the `location` parameter.
+     *
+     * A guessed location string is not an error on SerpAPI's side — it is an
+     * unsupported-location refusal or, worse, results for somewhere else — so
+     * every engine with a `location` parameter needs this lookup first.
+     */
+    locations(query: string, limit: number, signal?: AbortSignal): Promise<readonly SerpApiLocation[]>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/serpapi/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/serpapi/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAOH,yEAAyE;AACzE,eAAO,MAAM,YAAY,wBAAwB,CAAC;AAElD,4DAA4D;AAC5D,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE1D,MAAM,WAAW,oBAAoB;IACnC,wDAAwD;IACxD,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IAClC,oEAAoE;IACpE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,6DAA6D;IAC7D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,yCAAyC;IACzC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAMD;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAGhD,CAAC;AAgCH,4EAA4E;AAC5E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AAED,+DAA+D;AAC/D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,qBAAa,aAAa;;IAOxB,YAAY,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,oBAAyB,EAa1D;IAED;;;;;;;OAOG;IACG,MAAM,CACV,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,EACnD,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAiBlC;IAED,uEAAuE;IACjE,OAAO,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC,CAgB3D;IAED;;;;;;OAMG;IACG,SAAS,CACb,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,SAAS,eAAe,EAAE,CAAC,CAerC;CAmGF"}

package/dist/serpapi/client.js

@@ -0,0 +1,228 @@
+/**
+ * The SerpAPI HTTP client — the only code in this layer that holds the API key.
+ *
+ * Everything above it (the catalog, the capability module, the sandbox) works
+ * in terms of engine ids and plain parameter objects. The key is
+ * constructor-private, is attached to a request and never to a result, and is
+ * scrubbed out of every error before it is thrown, so there is no path by which
+ * it reaches guest code, a tool result, a model's context, or a log line.
+ *
+ * Endpoints, verified against serpapi.com:
+ *
+ *   GET /search.json?engine=<engine>&…   run any of the catalogued engines
+ *   GET /account.json                    plan, searches used, searches left
+ *   GET /locations.json?q=&limit=        canonical values for `location`
+ *
+ * There is one search method for all 120 engines rather than one per engine.
+ * That is the whole point of this layer: SerpAPI's own surface is a single
+ * endpoint whose `engine` parameter selects the contract, so a wrapper per
+ * engine would be a backlog that never catches up with what SerpAPI ships.
+ */
+import { setTimeout as delay } from "node:timers/promises";
+import { SerpApiError, asSerpApiError } from "./errors.js";
+import { isNonBlankString, isRecord, isString } from "../utils/type-guards.js";
+/** The public API root. Not configurable: it is also the SSRF answer. */
+export const SERPAPI_BASE = "https://serpapi.com";
+const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
+const DEFAULT_MAX_ATTEMPTS = 3;
+const DEFAULT_RETRY_BASE_MS = 500;
+/**
+ * Parameters the host owns, which a caller may not set.
+ *
+ * `api_key` is the credential and `output` decides whether the response is JSON
+ * at all — a guest that could set either would either exfiltrate the key or
+ * hand this layer HTML it cannot parse.
+ */
+export const HOST_OWNED_PARAMS = new Set([
+    "api_key",
+    "output"
+]);
+/** Map an HTTP status onto the distinction a caller acts on. */
+function kindForStatus(status) {
+    if (status === 401 || status === 403)
+        return "auth";
+    if (status === 429)
+        return "rate_limited";
+    if (status >= 500)
+        return "network";
+    return "invalid_input";
+}
+/**
+ * Strip anything key-shaped out of a message before it becomes an error.
+ *
+ * SerpAPI echoes the request in some error bodies, and the key rides on the
+ * query string, so redacting at the one place errors are built beats trusting
+ * every call site not to log.
+ */
+function redact(text, key) {
+    const safe = key.length >= 8 ? text.split(key).join("«redacted»") : text;
+    return safe.replace(/\bapi_key=[A-Za-z0-9]+/g, "api_key=«redacted»");
+}
+/** Whether the caller's signal has fired *now*. Mutable, so re-read it. */
+function isAborted(signal) {
+    return signal !== undefined && signal.aborted;
+}
+/** Wait, waking early if the caller's signal fires. Never rejects. */
+async function sleep(ms, signal) {
+    await delay(ms, undefined, { signal }).catch(() => undefined);
+}
+export class SerpApiClient {
+    #key;
+    #fetch;
+    #requestTimeoutMs;
+    #maxAttempts;
+    #retryBaseMs;
+    constructor(key, options = {}) {
+        if (!isNonBlankString(key)) {
+            throw new SerpApiError("auth", "No SerpAPI key is configured. Add SERPAPI_API_KEY in Settings → Secrets.");
+        }
+        this.#key = key;
+        this.#fetch = options.fetchImpl ?? fetch;
+        this.#requestTimeoutMs =
+            options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+        this.#maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+        this.#retryBaseMs = options.retryBaseMs ?? DEFAULT_RETRY_BASE_MS;
+    }
+    /**
+     * Run one search on any engine.
+     *
+     * `params` is passed through as the engine's own contract spells it — this
+     * client knows nothing about what `google_scholar` wants and
+     * `walmart_product` does not. Validation against the catalogued schema
+     * happens a layer up, where the schema lives.
+     */
+    async search(engine, params, signal) {
+        const query = new URLSearchParams({ engine, output: "json" });
+        for (const [name, value] of Object.entries(params)) {
+            if (HOST_OWNED_PARAMS.has(name))
+                continue;
+            if (value === undefined || value === null)
+                continue;
+            query.set(name, String(value));
+        }
+        const body = await this.#getJson("/search.json", query, signal, engine);
+        // SerpAPI answers 200 with an `error` string for engine-level refusals —
+        // an unsupported parameter combination, a query it will not run — so the
+        // status alone does not separate success from failure here.
+        if (isString(body.error)) {
+            throw new SerpApiError("invalid_input", redact(body.error, this.#key), {
+                engine
+            });
+        }
+        return body;
+    }
+    /** Plan and remaining searches, so a caller can see its own budget. */
+    async account(signal) {
+        const body = await this.#getJson("/account.json", new URLSearchParams(), signal);
+        const account = {};
+        if (isString(body.plan_name))
+            account.plan = body.plan_name;
+        if (typeof body.searches_per_month === "number") {
+            account.searchesPerMonth = body.searches_per_month;
+        }
+        if (typeof body.this_month_usage === "number") {
+            account.thisMonthUsage = body.this_month_usage;
+        }
+        if (typeof body.total_searches_left === "number") {
+            account.totalSearchesLeft = body.total_searches_left;
+        }
+        return account;
+    }
+    /**
+     * Canonical values for the `location` parameter.
+     *
+     * A guessed location string is not an error on SerpAPI's side — it is an
+     * unsupported-location refusal or, worse, results for somewhere else — so
+     * every engine with a `location` parameter needs this lookup first.
+     */
+    async locations(query, limit, signal) {
+        const search = new URLSearchParams({ q: query, limit: String(limit) });
+        const body = await this.#getArray("/locations.json", search, signal);
+        return body.filter(isRecord).map((row) => {
+            const location = {
+                name: isString(row.name) ? row.name : "",
+                canonicalName: isString(row.canonical_name) ? row.canonical_name : ""
+            };
+            if (isString(row.country_code))
+                location.countryCode = row.country_code;
+            if (isString(row.target_type))
+                location.targetType = row.target_type;
+            if (typeof row.reach === "number")
+                location.reach = row.reach;
+            return location;
+        });
+    }
+    async #getJson(path, query, signal, engine) {
+        const body = await this.#request(path, query, signal, engine);
+        if (!isRecord(body)) {
+            throw new SerpApiError("network", `SerpAPI returned a ${typeof body} where an object was expected.`, engine === undefined ? {} : { engine });
+        }
+        return body;
+    }
+    async #getArray(path, query, signal) {
+        const body = await this.#request(path, query, signal);
+        if (!Array.isArray(body)) {
+            throw new SerpApiError("network", `SerpAPI returned a ${typeof body} where an array was expected.`);
+        }
+        return body;
+    }
+    async #request(path, query, signal, engine) {
+        // Set last so a caller-supplied `api_key` can never win the slot.
+        query.set("api_key", this.#key);
+        const url = `${SERPAPI_BASE}${path}?${query.toString()}`;
+        let lastError;
+        for (let attempt = 1; attempt <= this.#maxAttempts; attempt += 1) {
+            if (isAborted(signal)) {
+                throw new SerpApiError("cancelled", "The run was cancelled.");
+            }
+            try {
+                return await this.#attempt(url, signal, engine);
+            }
+            catch (error) {
+                if (isAborted(signal)) {
+                    throw new SerpApiError("cancelled", "The run was cancelled.");
+                }
+                lastError = asSerpApiError(error);
+                if (!lastError.retryable || attempt === this.#maxAttempts)
+                    break;
+                await sleep(this.#retryBaseMs * 2 ** (attempt - 1), signal);
+            }
+        }
+        throw lastError ?? new SerpApiError("network", "SerpAPI request failed.");
+    }
+    async #attempt(url, signal, engine) {
+        const timeout = AbortSignal.timeout(this.#requestTimeoutMs);
+        const merged = signal === undefined ? timeout : AbortSignal.any([signal, timeout]);
+        const response = await this.#fetch(url, {
+            signal: merged,
+            headers: { accept: "application/json" }
+        });
+        const text = await response.text();
+        if (!response.ok) {
+            const detail = readErrorText(text);
+            throw new SerpApiError(kindForStatus(response.status), `SerpAPI request failed (${response.status}): ${redact(detail, this.#key)}`, engine === undefined
+                ? { status: response.status }
+                : { status: response.status, engine });
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch (error) {
+            throw new SerpApiError("network", "SerpAPI returned a body that is not JSON.", { cause: error });
+        }
+    }
+}
+/** Read SerpAPI's `{error}` envelope out of a failure body, or keep the text. */
+function readErrorText(text) {
+    try {
+        const body = JSON.parse(text);
+        if (isRecord(body) && isString(body.error))
+            return body.error;
+    }
+    catch {
+        // Not JSON — SerpAPI serves an HTML error page for some failures, and the
+        // raw text is still the most useful thing to report.
+    }
+    return text.slice(0, 500);
+}
+//# sourceMappingURL=client.js.map

package/dist/serpapi/client.js.map

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

package/dist/serpapi/errors.d.ts

@@ -0,0 +1,49 @@
+/**
+ * One error type for everything the SerpAPI layer can refuse, carrying the
+ * distinction a caller acts on.
+ *
+ * Same shape and the same reason as `apify/errors.ts`: a raw status tells a
+ * retry loop nothing (400 from a bad engine parameter and 400 from a malformed
+ * query both abort, 429 and 502 both wait), so the client classifies once at
+ * the boundary and every layer above reads {@link SerpApiError.retryable}.
+ *
+ * Nothing here ever carries the API key. The client redacts before
+ * constructing, so an error that reaches a model, a tool result, or a log line
+ * cannot leak the credential that produced it.
+ */
+/** What went wrong, in the terms a caller can act on. */
+export type SerpApiErrorKind = 
+/** No key configured, or the key was rejected. */
+"auth"
+/** The engine id does not exist in SerpAPI's catalog. */
+ | "unknown_engine"
+/** The parameters did not satisfy the engine's own contract. */
+ | "invalid_input"
+/** The engine catalog could not be read from serpapi.com. */
+ | "catalog_unavailable"
+/** SerpAPI asked us to slow down, or the plan ran out of searches. */
+ | "rate_limited"
+/** Transport-level failure before any SerpAPI response. */
+ | "network"
+/** The surrounding NodeTool run was cancelled. */
+ | "cancelled";
+export interface SerpApiErrorOptions {
+    /** HTTP status, when the failure came back as a response. */
+    readonly status?: number;
+    /** The engine this failed against, when there is one. */
+    readonly engine?: string;
+    readonly cause?: unknown;
+}
+/** A failure from the SerpAPI layer, classified. */
+export declare class SerpApiError extends Error {
+    readonly kind: SerpApiErrorKind;
+    readonly status?: number;
+    readonly engine?: string;
+    constructor(kind: SerpApiErrorKind, message: string, options?: SerpApiErrorOptions);
+    get retryable(): boolean;
+    /** The `{ok: false, …}` envelope every capability answers with. */
+    toResult(): Record<string, unknown>;
+}
+/** Wrap an unknown failure so callers always see a classified error. */
+export declare function asSerpApiError(value: unknown): SerpApiError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/serpapi/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/serpapi/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,yDAAyD;AACzD,MAAM,MAAM,gBAAgB;AAC1B,kDAAkD;AAChD,MAAM;AACR,yDAAyD;GACvD,gBAAgB;AAClB,gEAAgE;GAC9D,eAAe;AACjB,6DAA6D;GAC3D,qBAAqB;AACvB,sEAAsE;GACpE,cAAc;AAChB,2DAA2D;GACzD,SAAS;AACX,kDAAkD;GAChD,WAAW,CAAC;AAWhB,MAAM,WAAW,mBAAmB;IAClC,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,yDAAyD;IACzD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,oDAAoD;AACpD,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEzB,YACE,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,mBAAwB,EAOlC;IAED,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,mEAAmE;IACnE,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAUlC;CACF;AAED,wEAAwE;AACxE,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,CAQ3D"}

package/dist/serpapi/errors.js

@@ -0,0 +1,64 @@
+/**
+ * One error type for everything the SerpAPI layer can refuse, carrying the
+ * distinction a caller acts on.
+ *
+ * Same shape and the same reason as `apify/errors.ts`: a raw status tells a
+ * retry loop nothing (400 from a bad engine parameter and 400 from a malformed
+ * query both abort, 429 and 502 both wait), so the client classifies once at
+ * the boundary and every layer above reads {@link SerpApiError.retryable}.
+ *
+ * Nothing here ever carries the API key. The client redacts before
+ * constructing, so an error that reaches a model, a tool result, or a log line
+ * cannot leak the credential that produced it.
+ */
+/**
+ * Kinds worth trying again. Everything absent is deterministic: retrying a
+ * rejected key or a parameter the engine refuses spends the same failure twice.
+ */
+const RETRYABLE = new Set([
+    "rate_limited",
+    "network"
+]);
+/** A failure from the SerpAPI layer, classified. */
+export class SerpApiError extends Error {
+    kind;
+    status;
+    engine;
+    constructor(kind, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "SerpApiError";
+        this.kind = kind;
+        if (options.status !== undefined)
+            this.status = options.status;
+        if (options.engine !== undefined)
+            this.engine = options.engine;
+    }
+    get retryable() {
+        return RETRYABLE.has(this.kind);
+    }
+    /** The `{ok: false, …}` envelope every capability answers with. */
+    toResult() {
+        const result = {
+            ok: false,
+            error: this.message,
+            error_kind: this.kind,
+            retryable: this.retryable
+        };
+        if (this.status !== undefined)
+            result.status = this.status;
+        if (this.engine !== undefined)
+            result.engine = this.engine;
+        return result;
+    }
+}
+/** Wrap an unknown failure so callers always see a classified error. */
+export function asSerpApiError(value) {
+    if (value instanceof SerpApiError)
+        return value;
+    if (value instanceof Error) {
+        const kind = value.name === "AbortError" ? "cancelled" : "network";
+        return new SerpApiError(kind, value.message, { cause: value });
+    }
+    return new SerpApiError("network", String(value), { cause: value });
+}
+//# sourceMappingURL=errors.js.map

package/dist/serpapi/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/serpapi/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAmBH;;;GAGG;AACH,MAAM,SAAS,GAAkC,IAAI,GAAG,CAAmB;IACzE,cAAc;IACd,SAAS;CACV,CAAC,CAAC;AAUH,oDAAoD;AACpD,MAAM,OAAO,YAAa,SAAQ,KAAK;IAC5B,IAAI,CAAmB;IACvB,MAAM,CAAU;IAChB,MAAM,CAAU;IAEzB,YACE,IAAsB,EACtB,OAAe,EACf,OAAO,GAAwB,EAAE;QAEjC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QACnF,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS;YAAE,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC/D,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS;YAAE,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IACjE,CAAC;IAED,IAAI,SAAS;QACX,OAAO,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClC,CAAC;IAED,mEAAmE;IACnE,QAAQ;QACN,MAAM,MAAM,GAA4B;YACtC,EAAE,EAAE,KAAK;YACT,KAAK,EAAE,IAAI,CAAC,OAAO;YACnB,UAAU,EAAE,IAAI,CAAC,IAAI;YACrB,SAAS,EAAE,IAAI,CAAC,SAAS;SAC1B,CAAC;QACF,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;YAAE,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC3D,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;YAAE,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC3D,OAAO,MAAM,CAAC;IAChB,CAAC;CACF;AAED,wEAAwE;AACxE,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,IAAI,KAAK,YAAY,YAAY;QAAE,OAAO,KAAK,CAAC;IAChD,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,MAAM,IAAI,GACR,KAAK,CAAC,IAAI,KAAK,YAAY,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC;QACxD,OAAO,IAAI,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACjE,CAAC;IACD,OAAO,IAAI,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;AACtE,CAAC"}

package/dist/serpapi/normalize.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Turning one SerpAPI response into something a model can read, and one
+ * parameter bag into something SerpAPI will accept.
+ *
+ * Both directions exist for the same reason. A SerpAPI response is a whole
+ * results page — `google` alone answers with organic results, ads, knowledge
+ * graph, related questions, pagination, and inline images — and handing all of
+ * it back spends a model's context on the twelve keys it did not ask for. A
+ * parameter bag is the mirror image: a wrong key is not an error on SerpAPI's
+ * side, it is a silently ignored field and a result for a different query, so
+ * it has to be caught here against the engine's catalogued contract.
+ */
+import type { SerpApiEngine } from "./catalog.js";
+import { type SerpApiParamValue } from "./client.js";
+/** How many items of each result array are returned when nothing says. */
+export declare const DEFAULT_MAX_ITEMS = 10;
+/** The ceiling on `max_items`, whatever a caller asks for. */
+export declare const MAX_ITEMS_LIMIT = 100;
+export interface SummarizeOptions {
+    /** Only these top-level result keys. Everything else is named, not sent. */
+    readonly fields?: readonly string[];
+    readonly maxItems?: number;
+}
+export interface SearchSummary {
+    /** Engine, status, timing, and the parameters SerpAPI says it used. */
+    readonly metadata: Record<string, unknown>;
+    /** The result keys, trimmed to `maxItems` entries each. */
+    readonly results: Record<string, unknown>;
+    /** Result keys present in the response but not returned here. */
+    readonly omitted: readonly string[];
+    /** Result keys whose arrays were cut short, and by how much. */
+    readonly truncated: Readonly<Record<string, number>>;
+}
+/**
+ * Trim one response to the keys asked for and the items allowed.
+ *
+ * Nothing is dropped silently: a key that was left out is named in `omitted`
+ * and an array that was cut is counted in `truncated`, so a model can ask for
+ * the rest by name instead of guessing that there was more.
+ */
+export declare function summarizeSearch(body: Readonly<Record<string, unknown>>, options?: SummarizeOptions): SearchSummary;
+/** The result keys a response carries, for a caller choosing `fields`. */
+export declare function resultKeys(body: Readonly<Record<string, unknown>>): readonly string[];
+export interface ParamCheck {
+    /** The parameters to send, with every value coerced to a scalar. */
+    readonly params: Record<string, SerpApiParamValue>;
+    /** Why the call cannot be made as asked. Empty when it can. */
+    readonly errors: readonly string[];
+}
+/**
+ * Check a parameter bag against one engine's catalogued contract.
+ *
+ * Unknown keys are errors rather than warnings on purpose: SerpAPI ignores
+ * them, so the run succeeds, bills a search, and answers a question nobody
+ * asked. Naming the near-misses is what turns that into a fixable message.
+ */
+export declare function checkParams(engine: SerpApiEngine, raw: Readonly<Record<string, unknown>>): ParamCheck;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/serpapi/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../src/serpapi/normalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAqB,KAAK,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAYxE,0EAA0E;AAC1E,eAAO,MAAM,iBAAiB,KAAK,CAAC;AACpC,8DAA8D;AAC9D,eAAO,MAAM,eAAe,MAAM,CAAC;AAEnC,MAAM,WAAW,gBAAgB;IAC/B,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,aAAa;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,gEAAgE;IAChE,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACtD;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACvC,OAAO,GAAE,gBAAqB,GAC7B,aAAa,CA8Bf;AASD,0EAA0E;AAC1E,wBAAgB,UAAU,CACxB,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACtC,SAAS,MAAM,EAAE,CAEnB;AAED,MAAM,WAAW,UAAU;IACzB,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IACnD,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,aAAa,EACrB,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACrC,UAAU,CAoDZ"}