scoutline 0.22.0 → 0.24.0

package/dist/providers/searchapi/adapter.js

@@ -0,0 +1,310 @@
+/**
+ * SearchApi Provider Adapter.
+ *
+ * T2 wires the Search Capability; T3 adds the Quota and Diagnostics
+ * Capabilities (both backed by the non-destructive `GET /api/v1/me`
+ * probe). The descriptor advertises `"search"`, `"diagnostics"`, and
+ * `"quota"`, and `create()` returns an Adapter whose slots own
+ * credentials, transport, Provider field mapping, and failure
+ * normalization.
+ *
+ * Engine routing (SPEC, locked): `topic:"news"` → `engine=google_news`;
+ * every other topic (and no topic) → `engine=google`. Unlike the Z.AI/
+ * MiniMax/Parallel/Jina adapters there is NO topic keyword appendage —
+ * SearchApi routing is engine-only.
+ *
+ * Boundary rules (ARCHITECTURE.md §2):
+ *   - May import capability types, normalized errors, Provider identity
+ *     types, and the Adapter-local credential and transport Modules.
+ *   - Must NOT import command presentation, output mode, or another
+ *     Provider's Adapter.
+ */
+import { ApiError, AuthError, ConfigurationError, NetworkError, QuotaError, TimeoutError, UnsupportedOptionError, ValidationError, } from "../../lib/errors.js";
+import { hashSearchApiKey, isSearchApiConfigured, requireSearchApiKey } from "./credentials.js";
+import { fetchSearchApiSearch, } from "./client.js";
+import { createSearchApiQuotaCapability } from "./quota.js";
+import { createSearchApiDiagnosticsCapability } from "./diagnostics.js";
+const TIMEOUT_HELP_TEXT = "Try again or increase timeout with SEARCHAPI_TIMEOUT env var";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// ---------------------------------------------------------------------------
+// Validation (FR-012): reject unsupported controls before any API access
+// ---------------------------------------------------------------------------
+/**
+ * Controls the SearchApi Search Adapter does NOT accept. `contentSize`
+ * (SearchApi returns organic results, not sized extracts) and `type`
+ * (`video` is Brave-only) are rejected individually before any
+ * transport call. `domain`, `recency`, `location`, and `topic` are
+ * honored.
+ */
+function assertNoUnsupportedControls(request) {
+    const controls = request.controls;
+    if (!controls)
+        return;
+    if (controls.contentSize !== undefined) {
+        throw new UnsupportedOptionError("searchapi", "search", "contentSize");
+    }
+    if (controls.type !== undefined) {
+        throw new UnsupportedOptionError("searchapi", "search", "type");
+    }
+}
+// ---------------------------------------------------------------------------
+// Control mapping (SearchControls → SearchApi-native API params)
+// ---------------------------------------------------------------------------
+function mapRecencyToTimePeriod(recency) {
+    switch (recency) {
+        case "oneDay":
+            return "last_day";
+        case "oneWeek":
+            return "last_week";
+        case "oneMonth":
+            return "last_month";
+        case "oneYear":
+            return "last_year";
+        case "noLimit":
+            return undefined;
+        default:
+            return undefined;
+    }
+}
+/**
+ * Map the param-bearing controls into SearchApi-native API fields.
+ * Engine routing is topic-only: `news` → `google_news`, everything else
+ * (general/finance/absent) → `google`. Query-mutating `domain` is
+ * handled separately in `invoke`.
+ */
+function mapSearchControls(controls) {
+    const params = {
+        engine: controls?.topic === "news" ? "google_news" : "google",
+    };
+    if (controls?.recency) {
+        const timePeriod = mapRecencyToTimePeriod(controls.recency);
+        if (timePeriod)
+            params.time_period = timePeriod;
+    }
+    if (controls?.location) {
+        params.gl = controls.location.toLowerCase();
+    }
+    return params;
+}
+// ---------------------------------------------------------------------------
+// Response normalization
+// ---------------------------------------------------------------------------
+/**
+ * Normalize a raw SearchApi.io search response into `SearchSource[]`.
+ * Reads `raw.organic_results[]`:
+ *
+ *   title   -> title
+ *   link    -> url
+ *   snippet -> summary ("" when absent)
+ *   date    -> date (only when present and string)
+ *
+ * A malformed shape (non-object root, `organic_results` not an array,
+ * non-string title/link) is a retryable `ApiError` 500.
+ */
+export function normalizeSearchApiResults(raw) {
+    if (!isPlainObject(raw)) {
+        throw new ApiError("SearchApi.io returned a malformed response", 500);
+    }
+    const results = raw.organic_results;
+    // The `google_news` engine (topic:"news") legitimately returns only a
+    // `top_stories` block with `organic_results` ABSENT — a valid engine
+    // response, not a malformed payload. An absent array normalizes to an
+    // empty list; only a present-but-non-array value is malformed.
+    if (results === undefined)
+        return [];
+    if (!Array.isArray(results)) {
+        throw new ApiError("SearchApi.io returned a malformed response", 500);
+    }
+    const out = [];
+    for (const entry of results) {
+        if (!isPlainObject(entry)) {
+            throw new ApiError("SearchApi.io returned a malformed response", 500);
+        }
+        const title = entry.title;
+        const link = entry.link;
+        if (typeof title !== "string" || typeof link !== "string") {
+            throw new ApiError("SearchApi.io returned a malformed response", 500);
+        }
+        const source = {
+            title,
+            url: link,
+            summary: typeof entry.snippet === "string" ? entry.snippet : "",
+        };
+        // Publisher attribution (e.g. "Forbes" on google_news) — carried
+        // only when the wire supplies a string, mirroring Brave's
+        // meta_url.netloc discipline. Absent on the plain google engine.
+        if (typeof entry.source === "string") {
+            source.source = entry.source;
+        }
+        if (typeof entry.date === "string") {
+            source.date = entry.date;
+        }
+        out.push(source);
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Failure normalization: stable public codes, no raw payloads (NFR-006)
+// ---------------------------------------------------------------------------
+/**
+ * Status-keyed outward message for rewrapped SearchApi ApiErrors. The
+ * rewrap does not echo upstream `error.message` — a future change
+ * embedding a raw Provider body in an ApiError message would leak
+ * through normalization, the cache, and stdout. Curated constants only.
+ */
+function searchApiErrorMessage(statusCode) {
+    if (statusCode === 429)
+        return "SearchApi.io rate limit exceeded";
+    return "SearchApi.io request failed";
+}
+/**
+ * Normalize a Provider failure with sanitized messages. Raw response
+ * bodies never cross the adapter boundary. Same pattern as
+ * `normalizeBraveError`.
+ */
+function normalizeSearchApiError(error) {
+    // QuotaError pass-through — terminal retry guarantee preserved.
+    if (error instanceof QuotaError)
+        return error;
+    // Configuration/option/validation errors carry clean, human-authored
+    // messages and are safe to surface verbatim.
+    if (error instanceof ValidationError ||
+        error instanceof UnsupportedOptionError ||
+        error instanceof ConfigurationError) {
+        return error;
+    }
+    // Re-wrap typed transport errors with sanitized messages so a raw
+    // Provider response body embedded upstream never survives.
+    if (error instanceof AuthError) {
+        return new AuthError("SearchApi.io authentication failed", "SEARCHAPI_API_KEY");
+    }
+    if (error instanceof NetworkError) {
+        return new NetworkError("SearchApi.io network error");
+    }
+    if (error instanceof TimeoutError) {
+        return new TimeoutError(error.durationMs, TIMEOUT_HELP_TEXT);
+    }
+    if (error instanceof ApiError) {
+        const statusCode = typeof error.statusCode === "number" && Number.isFinite(error.statusCode)
+            ? error.statusCode
+            : 500;
+        return new ApiError(searchApiErrorMessage(statusCode), statusCode);
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    const lower = message.toLowerCase();
+    if (lower.includes("401") ||
+        lower.includes("403") ||
+        lower.includes("unauthorized") ||
+        lower.includes("forbidden")) {
+        return new AuthError("SearchApi.io authentication failed", "SEARCHAPI_API_KEY");
+    }
+    if (lower.includes("timeout") || lower.includes("timed out") || lower.includes("etimedout")) {
+        // Fallback branch: the transport wraps real timeouts into a typed
+        // TimeoutError (which carries the configured duration) before they
+        // reach this point. This untyped-message heuristic is rarely hit, so
+        // a constant default is fine and keeps process.env out of the
+        // normalization path (test isolation).
+        return new TimeoutError(30000, TIMEOUT_HELP_TEXT);
+    }
+    if (lower.includes("econnrefused") ||
+        lower.includes("econnreset") ||
+        lower.includes("network") ||
+        lower.includes("enotfound") ||
+        lower.includes("fetch failed")) {
+        return new NetworkError("SearchApi.io network error");
+    }
+    if (lower.includes("429") || lower.includes("rate limit")) {
+        return new ApiError("SearchApi.io rate limit exceeded", 429);
+    }
+    return new ApiError("SearchApi.io request failed", 500);
+}
+function createSearchApiSearchCapability(options) {
+    const { env, transport } = options;
+    const capability = {
+        validate(request) {
+            if (!request || typeof request.query !== "string" || request.query.trim() === "") {
+                throw new ValidationError("Search query must contain at least one non-whitespace character");
+            }
+            // SearchApi supports domain, recency, location, and topic.
+            // contentSize and type are rejected before any transport call.
+            assertNoUnsupportedControls(request);
+        },
+        cacheIdentity(request) {
+            const apiKey = requireSearchApiKey(env);
+            const identityRequest = {
+                query: request.query,
+            };
+            if (request.controls) {
+                identityRequest.controls = request.controls;
+            }
+            return {
+                provider: "searchapi",
+                capability: "search",
+                credentialFingerprint: hashSearchApiKey(apiKey),
+                request: identityRequest,
+            };
+        },
+        async invoke(request) {
+            // Validate before any credential access or transport call.
+            capability.validate(request);
+            const apiKey = requireSearchApiKey(env);
+            try {
+                const controls = request.controls;
+                // `domain` appends a `site:<domain>` operator to the query
+                // (SearchApi has no dedicated domain param). Topic routing is
+                // engine-only — no keyword appendage.
+                const q = controls?.domain !== undefined
+                    ? `${request.query} site:${controls.domain}`
+                    : request.query;
+                const params = mapSearchControls(controls);
+                const raw = await fetchSearchApiSearch(apiKey, { engine: params.engine, q, gl: params.gl, time_period: params.time_period }, transport);
+                return normalizeSearchApiResults(raw);
+            }
+            catch (error) {
+                throw normalizeSearchApiError(error);
+            }
+        },
+    };
+    return capability;
+}
+// ---------------------------------------------------------------------------
+// Descriptor factory
+// ---------------------------------------------------------------------------
+/**
+ * Build the SearchApi Provider Descriptor. The descriptor advertises
+ * Search, Diagnostics, and Quota; `create()` returns an Adapter whose
+ * slots own credentials, transport, Provider field mapping, and failure
+ * normalization. Construction is side-effect-free; the transport is
+ * invoked per Capability call. Tests pass `transport` (typically a
+ * fake-fetch wrapper); production uses the no-argument factory which
+ * resolves to the global `fetch` and timers inside the transport
+ * Module.
+ */
+export function createSearchApiDescriptor(dependencies) {
+    const transport = dependencies?.transport;
+    return {
+        id: "searchapi",
+        isConfigured(env) {
+            return isSearchApiConfigured(env);
+        },
+        capabilities() {
+            return new Set(["search", "diagnostics", "quota"]);
+        },
+        create(context) {
+            const search = createSearchApiSearchCapability({ env: context.env, transport });
+            const quota = createSearchApiQuotaCapability({ env: context.env, transport });
+            const diagnostics = createSearchApiDiagnosticsCapability({
+                env: context.env,
+                transport,
+            });
+            return { id: "searchapi", search, diagnostics, quota };
+        },
+        credentialEnvVars: ["SEARCHAPI_API_KEY", "SERPAPI_API_KEY"],
+    };
+}
+//# sourceMappingURL=adapter.js.map

package/dist/providers/searchapi/adapter.js.map

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

package/dist/providers/searchapi/client.d.ts

@@ -0,0 +1,73 @@
+/**
+ * SearchApi.io direct HTTP transport.
+ *
+ * Performs direct GETs against the SearchApi.io REST API
+ * (`https://www.searchapi.io/api/v1`) with an
+ * `Authorization: Bearer <apiKey>` header — the key NEVER travels as a
+ * query parameter. There is NO internal retry — shared execution owns
+ * retry policy. Fetch and timers are injectable for tests.
+ *
+ * Structurally cloned from `providers/brave/client.ts`, simplified to
+ * the Linkup shape (no retry-hint header parsing; SearchApi exposes no
+ * rate-limit response headers to read).
+ *
+ * Failure taxonomy (SearchApi ERROR_HANDLING, locked):
+ *   401 / 403 -> AuthError (never retry)
+ *   402       -> QuotaError (never retry)
+ *   408 / 504 -> TimeoutError (retryable by shared execution)
+ *   422       -> ApiError 422 (never retry)
+ *   429       -> ApiError 429 (retried by shared execution)
+ *   >= 500 / default -> ApiError status (retried by shared execution)
+ *
+ * Raw response bodies NEVER cross this module's error boundary — every
+ * thrown message is a curated constant (NFR-006).
+ *
+ * Boundary rules (ARCHITECTURE.md §2):
+ *   - May import Adapter-local config and normalized errors.
+ *   - May import `ProviderQuotaFetch` from `providers/types.js`.
+ *   - Must NOT import command presentation, capability contracts, or
+ *     another Provider's Adapter.
+ *   - Must NOT perform response field normalization — the Adapter owns
+ *     that. This module declares Provider-native request params only.
+ */
+import type { ProviderQuotaFetch } from "../types.js";
+/** Injectable transport dependencies (fetch, timers, env). */
+export interface SearchApiTransportDeps {
+    readonly fetch?: ProviderQuotaFetch;
+    readonly setTimeout?: typeof setTimeout;
+    readonly clearTimeout?: typeof clearTimeout;
+    readonly env?: NodeJS.ProcessEnv;
+}
+/**
+ * Provider-native search request query params (SearchApi API field
+ * names). The Adapter maps the Provider-neutral `SearchControls` into
+ * these before calling {@link fetchSearchApiSearch}; the transport
+ * never imports a capability contract. Result-count projection is a
+ * client-side concern owned by shared execution, so no count field
+ * exists here.
+ */
+export interface SearchApiSearchParams {
+    readonly engine?: string;
+    readonly q?: string;
+    readonly gl?: string;
+    readonly time_period?: string;
+}
+export declare function resolveTimeoutMs(env: NodeJS.ProcessEnv): number;
+/**
+ * Perform ONE GET against the SearchApi.io `/api/v1/search` endpoint.
+ * No retry; no response body in public errors. Returns the parsed JSON
+ * body (raw; the Adapter post-processes into normalized search
+ * sources).
+ *
+ * `params` carries SearchApi-native API fields already mapped from
+ * `SearchControls` by the Adapter (`engine`/`q`/`gl`/`time_period`).
+ */
+export declare function fetchSearchApiSearch(apiKey: string, params?: SearchApiSearchParams, deps?: SearchApiTransportDeps): Promise<unknown>;
+/**
+ * Perform ONE GET against the SearchApi.io `/api/v1/me` endpoint — the
+ * account/subscription metadata probe used by the Quota and Diagnostics
+ * Capabilities. Non-destructive: `/me` is not a search, so it consumes
+ * no search credits. No retry; no response body in public errors.
+ */
+export declare function fetchSearchApiMe(apiKey: string, deps?: SearchApiTransportDeps): Promise<unknown>;
+//# sourceMappingURL=client.d.ts.map

package/dist/providers/searchapi/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/providers/searchapi/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAKH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AActD,8DAA8D;AAC9D,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,KAAK,CAAC,EAAE,kBAAkB,CAAC;IACpC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,UAAU,CAAC;IACxC,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,YAAY,CAAC;IAC5C,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CAClC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAG/D;AA0ID;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,qBAA0B,EAClC,IAAI,GAAE,sBAA2B,GAChC,OAAO,CAAC,OAAO,CAAC,CAElB;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,sBAA2B,GAChC,OAAO,CAAC,OAAO,CAAC,CAElB"}

package/dist/providers/searchapi/client.js

@@ -0,0 +1,196 @@
+/**
+ * SearchApi.io direct HTTP transport.
+ *
+ * Performs direct GETs against the SearchApi.io REST API
+ * (`https://www.searchapi.io/api/v1`) with an
+ * `Authorization: Bearer <apiKey>` header — the key NEVER travels as a
+ * query parameter. There is NO internal retry — shared execution owns
+ * retry policy. Fetch and timers are injectable for tests.
+ *
+ * Structurally cloned from `providers/brave/client.ts`, simplified to
+ * the Linkup shape (no retry-hint header parsing; SearchApi exposes no
+ * rate-limit response headers to read).
+ *
+ * Failure taxonomy (SearchApi ERROR_HANDLING, locked):
+ *   401 / 403 -> AuthError (never retry)
+ *   402       -> QuotaError (never retry)
+ *   408 / 504 -> TimeoutError (retryable by shared execution)
+ *   422       -> ApiError 422 (never retry)
+ *   429       -> ApiError 429 (retried by shared execution)
+ *   >= 500 / default -> ApiError status (retried by shared execution)
+ *
+ * Raw response bodies NEVER cross this module's error boundary — every
+ * thrown message is a curated constant (NFR-006).
+ *
+ * Boundary rules (ARCHITECTURE.md §2):
+ *   - May import Adapter-local config and normalized errors.
+ *   - May import `ProviderQuotaFetch` from `providers/types.js`.
+ *   - Must NOT import command presentation, capability contracts, or
+ *     another Provider's Adapter.
+ *   - Must NOT perform response field normalization — the Adapter owns
+ *     that. This module declares Provider-native request params only.
+ */
+import pkg from "../../../package.json" with { type: "json" };
+import { ApiError, AuthError, NetworkError, QuotaError, TimeoutError } from "../../lib/errors.js";
+import { getGlobalFetch } from "../types.js";
+import { clampTimeoutMs } from "../../lib/timeout.js";
+const { version: VERSION } = pkg;
+const BASE_URL = "https://www.searchapi.io";
+const SEARCH_PATH = "/api/v1/search";
+const ME_PATH = "/api/v1/me";
+const DEFAULT_TIMEOUT_MS = 30000;
+const USER_AGENT = `scoutline/${VERSION}`;
+const TIMEOUT_HELP_TEXT = "Try again or increase timeout with SEARCHAPI_TIMEOUT env var";
+export function resolveTimeoutMs(env) {
+    const raw = parseInt(env.SEARCHAPI_TIMEOUT || String(DEFAULT_TIMEOUT_MS), 10);
+    return clampTimeoutMs(raw, DEFAULT_TIMEOUT_MS);
+}
+/**
+ * Layer 1 — HTTP-status mapping. Runs BEFORE the body is parsed; on a
+ * non-2xx response we discard the body and throw a typed error with a
+ * curated message (no raw Provider body in any public error).
+ */
+function mapStatusError(status, timeoutMs) {
+    if (status === 401 || status === 403) {
+        return new AuthError("SearchApi.io authentication failed", "SEARCHAPI_API_KEY");
+    }
+    if (status === 402) {
+        return new QuotaError("SearchApi.io credits exhausted");
+    }
+    if (status === 408 || status === 504) {
+        return new TimeoutError(timeoutMs, TIMEOUT_HELP_TEXT);
+    }
+    if (status === 422) {
+        return new ApiError("SearchApi.io request failed", 422);
+    }
+    if (status === 429) {
+        return new ApiError("SearchApi.io rate limit exceeded", 429);
+    }
+    return new ApiError("SearchApi.io request failed", status);
+}
+function normalizeTransportError(err, timeoutMs) {
+    if (err instanceof AuthError ||
+        err instanceof ApiError ||
+        err instanceof NetworkError ||
+        err instanceof QuotaError ||
+        err instanceof TimeoutError) {
+        return err;
+    }
+    if (err instanceof Error) {
+        if (err.name === "AbortError") {
+            return new TimeoutError(timeoutMs, TIMEOUT_HELP_TEXT);
+        }
+        const lower = err.message.toLowerCase();
+        if (lower.includes("fetch") ||
+            lower.includes("econnrefused") ||
+            lower.includes("econnreset") ||
+            lower.includes("enotfound") ||
+            lower.includes("network")) {
+            return new NetworkError("SearchApi.io network error");
+        }
+    }
+    return new ApiError("SearchApi.io request failed", 500);
+}
+/**
+ * Build the query string for a GET. Skips `undefined`/`null` values.
+ * Uses `encodeURIComponent` so callers can pass raw strings without
+ * pre-encoding. The API key is NEVER a query parameter — it travels
+ * only in the `Authorization: Bearer` header.
+ */
+function buildQueryString(params) {
+    if (!params)
+        return "";
+    const parts = [];
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined || value === null)
+            continue;
+        parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
+    }
+    return parts.length === 0 ? "" : `?${parts.join("&")}`;
+}
+/**
+ * Shared GET plumbing for every SearchApi.io JSON endpoint. Performs
+ * ONE GET against `path` with the canonical Bearer/Accept/User-Agent
+ * headers, the injected timeout, the status map, and JSON parsing. No
+ * retry; no response body in public errors. Returns the parsed JSON
+ * body (raw; the Adapter post-processes into normalized shapes).
+ *
+ * `params` carries SearchApi-native API fields already mapped by the
+ * Adapter (`engine`/`q`/`gl`/`time_period` for search). The API key is
+ * NEVER a query parameter — it travels only in the `Authorization:
+ * Bearer` header.
+ */
+async function getSearchApiJson(apiKey, path, params, deps) {
+    const f = deps.fetch ?? getGlobalFetch();
+    const setT = deps.setTimeout ?? setTimeout;
+    const clearT = deps.clearTimeout ?? clearTimeout;
+    const env = deps.env ?? process.env;
+    const timeoutMs = resolveTimeoutMs(env);
+    const url = `${BASE_URL}${path}${buildQueryString(params)}`;
+    const controller = new AbortController();
+    const timeoutId = setT(() => controller.abort(), timeoutMs);
+    try {
+        const res = await f(url, {
+            method: "GET",
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+                Accept: "application/json",
+                "User-Agent": USER_AGENT,
+            },
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            // Drain the body to free the socket, then drop it. The body must
+            // NEVER reach the error message (NFR-006).
+            await res.text().catch(() => { });
+            throw mapStatusError(res.status, timeoutMs);
+        }
+        let parsed;
+        try {
+            parsed = await res.json();
+        }
+        catch (err) {
+            // Only a genuine parse failure (non-JSON body → SyntaxError) is
+            // the malformed-response case. Anything else — notably the
+            // AbortError thrown when the transport timeout fires mid-read —
+            // must flow to the outer catch so normalizeTransportError keeps
+            // its AbortError → TimeoutError classification.
+            if (err instanceof SyntaxError) {
+                throw new ApiError("SearchApi.io returned a malformed response", 500);
+            }
+            throw err;
+        }
+        return parsed;
+    }
+    catch (err) {
+        throw normalizeTransportError(err, timeoutMs);
+    }
+    finally {
+        // Clear the timeout only after body consumption so the AbortController
+        // timeout still covers a stalled/slow response body read.
+        clearT(timeoutId);
+        controller.abort();
+    }
+}
+/**
+ * Perform ONE GET against the SearchApi.io `/api/v1/search` endpoint.
+ * No retry; no response body in public errors. Returns the parsed JSON
+ * body (raw; the Adapter post-processes into normalized search
+ * sources).
+ *
+ * `params` carries SearchApi-native API fields already mapped from
+ * `SearchControls` by the Adapter (`engine`/`q`/`gl`/`time_period`).
+ */
+export async function fetchSearchApiSearch(apiKey, params = {}, deps = {}) {
+    return getSearchApiJson(apiKey, SEARCH_PATH, { ...(params ?? {}) }, deps);
+}
+/**
+ * Perform ONE GET against the SearchApi.io `/api/v1/me` endpoint — the
+ * account/subscription metadata probe used by the Quota and Diagnostics
+ * Capabilities. Non-destructive: `/me` is not a search, so it consumes
+ * no search credits. No retry; no response body in public errors.
+ */
+export async function fetchSearchApiMe(apiKey, deps = {}) {
+    return getSearchApiJson(apiKey, ME_PATH, undefined, deps);
+}
+//# sourceMappingURL=client.js.map

package/dist/providers/searchapi/client.js.map

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

package/dist/providers/searchapi/credentials.d.ts

@@ -0,0 +1,46 @@
+/**
+ * SearchApi credential resolution.
+ *
+ * Single source of truth for the SearchApi.io API key
+ * (`SEARCHAPI_API_KEY`, with the legacy `SERPAPI_API_KEY` accepted as a
+ * lower-precedence fallback). Whitespace-only values are treated as
+ * absent, matching the descriptor's `isConfigured` contract. Resolved
+ * keys are returned trimmed so wire headers never carry stray
+ * whitespace.
+ *
+ * Boundary rules (ARCHITECTURE.md §2):
+ *   - May import the normalized-error contract only.
+ *   - Must NOT import transport, command presentation, or another
+ *     Provider's Adapter.
+ *
+ * Missing credentials are surfaced as {@link ConfigurationError}
+ * (exit 3), distinct from {@link AuthError} (exit 1) which means the
+ * Provider REJECTED a presented credential.
+ */
+/** Credential environment names read by this module (#232 derivation pin). */
+export declare const ENV_NAMES: readonly ["SEARCHAPI_API_KEY", "SERPAPI_API_KEY"];
+/**
+ * Resolve the SearchApi API key without throwing. Returns the trimmed
+ * key or `undefined` when no non-blank value is present.
+ * `SEARCHAPI_API_KEY` wins over the legacy `SERPAPI_API_KEY`.
+ */
+export declare function getSearchApiKey(env: NodeJS.ProcessEnv): string | undefined;
+/**
+ * Resolve the SearchApi API key or throw {@link ConfigurationError}
+ * (exit 3) when it is missing. Call this at every capability
+ * invocation gate.
+ */
+export declare function requireSearchApiKey(env: NodeJS.ProcessEnv): string;
+/**
+ * True when a non-blank SearchApi API key is configured. Metadata-only:
+ * performs no transport construction and reads no other Provider's
+ * credentials.
+ */
+export declare function isSearchApiConfigured(env: NodeJS.ProcessEnv): boolean;
+/**
+ * Lowercase hex SHA-256 fingerprint of the SearchApi API key. Used for
+ * partitioned cache identity; the raw key must never appear in cache
+ * filenames, errors, or logs.
+ */
+export declare function hashSearchApiKey(key: string): string;
+//# sourceMappingURL=credentials.d.ts.map

package/dist/providers/searchapi/credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../../../src/providers/searchapi/credentials.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH,8EAA8E;AAC9E,eAAO,MAAM,SAAS,YAAI,mBAAmB,EAAE,iBAAiB,CAAU,CAAC;AAc3E;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,GAAG,SAAS,CAE1E;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CASlE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,OAAO,CAErE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEpD"}