serpkite 0.5.0 → 0.7.0

package/README.md

@@ -87,7 +87,7 @@ vertical-specific extras and `meta` (`request_id`, `credits_used`, `cached`, `la
 | `news(params)` | `POST /v1/news` | `SearchParams` | `NewsResponse` |
 | `maps(params)` | `POST /v1/maps` | `SearchParams` (+ `ll`: `"@lat,lng,14z"`) | `PlacesResponse` |
 | `places(params)` | `POST /v1/places` | `SearchParams` | `PlacesResponse` |
-| `place(params)` | `POST /v1/place` | `PlaceParams` (`place_id` \| `cid` \| `fid`, `country`, `language`) | `PlacesResponse` (one place: `weekly_hours`, `photos`, `timezone`, …; empty when the id is unknown) |
+| `place(params)` | `POST /v1/place` | `PlaceParams` (`place_id` \| `cid` \| `fid` \| `oid` (Yandex Maps), `country`, `language`) | `PlacesResponse` (one place: `weekly_hours`, `photos`, `timezone`, …; empty when the id is unknown) |
 | `reviews(params)` | `POST /v1/reviews` | `ReviewsParams` (`place_id` \| `cid` \| `fid`, `sort`, `page_token`, `num` ≤ 50) | `ReviewsResponse` (+ `next_page_token`) |
 | `shopping(params)` | `POST /v1/shopping` | `SearchParams` | `ShoppingResponse` |
 | `scholar(params)` | `POST /v1/scholar` | `SearchParams` | `ScholarResponse` |
@@ -95,11 +95,16 @@ vertical-specific extras and `meta` (`request_id`, `credits_used`, `cached`, `la
 | `autocomplete(params)` | `POST /v1/autocomplete` | `SearchParams` | `AutocompleteResponse` (`results[].value`) |
 | `webpage(params)` | `POST /v1/webpage` | `WebpageParams` (`url`, `include_html`) | `WebpageResponse` (`markdown`, `text`, `metadata`) |
 | `rank(params)` | `POST /v1/rank` | `RankParams` (`q`, `domain`, `num`: 10\|20\|30\|50\|100) | `RankResponse` (`position` or `null`, `matches`, `checked`) |
-| `extract(params)` | `POST /v1/extract` | `ExtractParams` (`urls` ≤ 20, `format`, `query`, `highlights`, …) | `ExtractResponse` (`results`, `failed`) |
+| `answer(params)` | `POST /v1/answer` | `AnswerParams` (`q`, `depth`: `fast`\|`standard`, `num_sources` 1-5, `output_schema`, search options) | `AnswerResponse` (`answer`, `citations`, `results`, `output`) |
+| `answerStream(params)` | `POST /v1/answer` (`stream: true`) | `AnswerParams` | `AsyncIterable<AnswerStreamEvent>` (`results`, `delta`…, `done`) |
+| `extract(params)` | `POST /v1/extract` | `ExtractParams` (`urls` ≤ 20, `format`, `query`, `highlights`, `summary`, `output_schema`, `prompt`, …) | `ExtractResponse` (`results`, `failed`) |
 | `map(params)` | `POST /v1/map` | `MapParams` (`url`, `search`, `limit`, `sitemap`, path filters) | `MapResponse` (`results[].url`) |
 | `crawl(params)` | `POST /v1/crawl` | `CrawlParams` (`url`, `limit` ≤ 1000, `max_depth` ≤ 10, …) | `TaskCreated` (`202`) |
 | `getCrawl(id)` / `cancelCrawl(id)` | `GET` / `DELETE /v1/crawl/{id}` | task id | `CrawlTask` / `TaskCancelResponse` |
 | `waitForCrawl(idOrTask, options?)` | polls `GET /v1/crawl/{id}` | task id or task | `CrawlTask` (`completed`, `failed` or `canceled`) |
+| `research(params)` | `POST /v1/research` | `ResearchParams` (`input`, `effort`: `lite`\|`standard`\|`deep`, `output_schema`, domains, `webhook_url`) | `TaskCreated` (`202`) |
+| `getResearch(id)` / `cancelResearch(id)` | `GET` / `DELETE /v1/research/{id}` | task id | `ResearchTask` / `TaskCancelResponse` |
+| `waitResearch(idOrTask, options?)` | polls `GET /v1/research/{id}` | task id or task | `ResearchTask` (`completed`, `failed` or `canceled`) |
 | `monitors.create/list/get/update/delete/run` | `/v1/monitors…` | `MonitorCreateParams`, `MonitorUpdateParams` | `Monitor`, `MonitorList` |
 | `monitors.runs(id, params?)` / `monitors.iterRuns(id)` | `GET /v1/monitors/{id}/runs` | `limit`, `before` | `MonitorRunList` / `AsyncIterable<MonitorRun>` |
 | `account()` | `GET /v1/account` | none | `Account` (`balance`, `plan`, `rate_limit_rps`, `month`, …) |
@@ -111,7 +116,7 @@ Common `SearchParams`: `q` (required), `country` (default `us`), `language` (def
 `location`, `uule`, `num` (10, or 100 for the depth bundle), `page` (1-10), `time`
 (`hour`|`day`|`week`|`month`|`year`), `tbs`, `device` (`desktop`|`mobile`), `safe`, `autocorrect`,
 `format` (`json`|`markdown`|`compact`), `fields`, `include_content` (0-5), `ads`, `max_age`,
-`engine`.
+`engine`, `include_answer` (`search` and `news`).
 
 ### Examples
 
@@ -192,7 +197,7 @@ await sk.news({ q: "espresso", engine: ["google", "brave"] });
 ```
 
 - `engine` is `"google"` (default), `"auto"`, `"consensus"`, one `Provider` (`"brave"`, `"bing"`,
-  `"yahoo"`, `"duckduckgo"`, `"mojeek"`, `"wikipedia"`) or a `Provider[]` list. `"auto"` and `"consensus"` can't
+  `"yahoo"`, `"duckduckgo"`, `"mojeek"`, `"wikipedia"`, `"yandex"`) or a `Provider[]` list. `"auto"` and `"consensus"` can't
   be combined with other names; unknown names, or a provider that doesn't serve the endpoint, return
   `400 invalid_request`.
 - `engine: "consensus"` (`search` only) asks several independent indexes in parallel, merges the
@@ -203,6 +208,68 @@ await sk.news({ q: "espresso", engine: ["google", "brave"] });
   and its `outcome` (absent on cache hits). `request.engine` echoes what you asked for.
 - Credits (`meta.credits_used`, `X-Credits-Used`) follow the answering provider's price.
 
+## AI answers
+
+```ts
+// A cited answer grounded on live Google results ("fast" answers from the result page;
+// "standard", the default, also reads the top num_sources pages)
+const res = await sk.answer({ q: "what is retrieval-augmented generation", depth: "fast" });
+console.log(res.answer); // Markdown with [1] markers
+for (const c of res.citations) console.log(c.index, c.title, c.link);
+console.log(res.meta.credits, res.meta.llm); // { search, answer }, { provider, model, … }
+
+// Stream it: results first, then text deltas, then done (final answer, citations, meta)
+for await (const ev of sk.answerStream({ q: "what is retrieval-augmented generation" })) {
+  if (ev.event === "delta") process.stdout.write(ev.data.text);
+  if (ev.event === "done") console.log("\n", ev.data.citations);
+}
+
+// Structured output: the answer as JSON matching your schema (not with streaming)
+const facts = await sk.answer({
+  q: "tallest building in the world",
+  output_schema: { type: "object", properties: { name: { type: "string" }, height_m: { type: "number" } } },
+});
+console.log(facts.output);
+
+// A cited answer on top of a normal search or news response
+const news = await sk.news({ q: "ECB rate decision", time: "day", include_answer: true });
+console.log(news.answer?.text, news.meta.warnings); // no answer + a warning (refunded) if the model failed
+```
+
+- A stream's `error` event (and a model failure on `answer`) is thrown as `SerpKiteError` with code
+  `ai_unavailable` (503); the model part is not charged. Breaking out of the `for await` loop
+  closes the connection and the model part is not charged either.
+- `extract` takes `summary: true` (an AI summary per page) and `output_schema` (+ optional
+  `prompt`; each page's data as JSON in `output`), each at an extra per-page price. A page whose
+  model step failed carries `summary_error` / `output_error` instead and isn't charged for it. Its
+  default `timeout` becomes 75 seconds with either.
+- AI prices (answers, `include_answer`, summaries, schema extraction, research) are listed at
+  [serpkite.com/pricing](https://serpkite.com/pricing); `meta.credits` on an answer splits the
+  search and the model part.
+
+## Research
+
+```ts
+const task = await sk.research({
+  input: "Compare managed Postgres vector search options in 2026",
+  effort: "standard", // lite | standard (default) | deep
+});
+const done = await sk.waitResearch(task); // polls until completed/failed/canceled (15 min default)
+if (done.status === "completed") {
+  console.log(done.result?.report); // Markdown report with [n] citations
+  for (const s of done.result?.sources ?? []) console.log(s.index, s.link, s.query);
+}
+```
+
+- Each `effort` has a flat price ([serpkite.com/pricing](https://serpkite.com/pricing)), reserved
+  up front and charged only when the report is written; failed research is refunded. `getResearch(id)` shows `progress` (`round`, `queries`, `sources`, `step`) while it
+  runs. `cancelResearch(id)` refunds a queued task; a running one stops at its next round and is
+  charged for the searches already run.
+- `output_schema` also returns the report as JSON in `result.output`; `include_domains` /
+  `exclude_domains`, `country` and `language` steer the searches.
+- Pass `webhook_url` to get a signed `research.completed` delivery (same envelope as
+  `crawl.completed`) instead of polling.
+
 ## Map and extract
 
 ```ts
@@ -286,7 +353,7 @@ resumes it. `webhook_url: ""` removes the webhook; a changed search reports ever
 
 ## Webhooks
 
-Every delivery (`batch.completed`, `crawl.completed`, `monitor.results`) is signed with
+Every delivery (`batch.completed`, `crawl.completed`, `research.completed`, `monitor.results`) is signed with
 `X-SerpKite-Signature`. `parseWebhook` verifies it and returns the event typed by
 `X-SerpKite-Event`, with `deliveryId` from `X-SerpKite-Delivery` (for `monitor.results`, the
 `run_id`) to deduplicate retries:
@@ -362,6 +429,7 @@ try {
 | `rate_limited` | 429 | Too many requests (retried automatically) |
 | `upstream_error`, `upstream_blocked` | 503 | Google could not be fetched (not billed, retried) |
 | `upstream_timeout` | 503 | The search took too long (not billed, retried) |
+| `ai_unavailable` | 503 | The AI model failed or AI is off (model part refunded; honours `Retry-After`) |
 | `unavailable` | 503 | Temporarily unavailable (retried) |
 | `internal` | 500 | Server error (retried) |
 | `connection_error`, `timeout` | 0 | No response received |
@@ -374,8 +442,10 @@ Failed, empty and blocked searches are refunded, so they never cost credits.
 Requests are retried up to `maxRetries` times (default 2) on `429`, `5xx`, network errors and
 timeouts, with exponential backoff (`retryDelayMs · 2^attempt`, capped at 8 s) and jitter. A
 `Retry-After` header (seconds or HTTP date, capped at 60 s) takes precedence. Other `4xx` errors
-are never retried. `batches.create`, `crawl`, `monitors.create` and `monitors.run` retry only on
-`429`, so a lost response can never queue (and bill) the same work twice.
+are never retried. `batches.create`, `crawl`, `research`, `extract`, `answer`, `monitors.create`
+and `monitors.run` retry only on `429`, so a lost response can never queue (and bill) the same
+work twice. `answerStream` retries only until the stream starts. `answer` and `answerStream` wait
+at least 100 s for the response headers (the search runs first) unless you pass `timeoutMs`.
 
 ## Types
 
@@ -387,7 +457,9 @@ Types are generated from the OpenAPI contract (`backend/api/serp-api.yaml`) with
 `RankResponse`,
 `Account`, `Batch`, `BatchCreateParams`, `Meta`, `Engine`, `Provider`, `RouteStep`,
 `CompactResponse`, `MapResponse`, `ExtractResponse`, `CrawlParams`, `CrawlTask`, `CrawlResult`,
-`TaskCreated`, `Monitor`, `MonitorRun`, `MonitorPageChange`, `TaskCompletedEvent`,
+`TaskCreated`, `AnswerParams`, `AnswerResponse`, `AnswerStreamEvent`, `Citation`, `SearchAnswer`,
+`LLMUsage`, `ResearchParams`, `ResearchTask`, `ResearchResult`, `ResearchSource`,
+`Monitor`, `MonitorRun`, `MonitorPageChange`, `TaskCompletedEvent`,
 `MonitorResultsEvent`, `WebhookEvent` and more. The raw
 `paths`, `components` and `operations` types are exported as well.
 

package/dist/index.cjs

@@ -50,7 +50,7 @@ function errorFromResponse(status, headers, body) {
 }
 
 // src/client.ts
-var VERSION = "0.5.0";
+var VERSION = "0.7.0";
 var DEFAULT_BASE_URL = "https://api.serpkite.com";
 var TASK_DONE = /* @__PURE__ */ new Set(["completed", "failed", "canceled"]);
 var SerpKite = class {
@@ -98,12 +98,16 @@ var SerpKite = class {
   videos = this.#vertical("/v1/videos");
   /** Google News. */
   news = this.#vertical("/v1/news");
-  /** Google Maps search (places with coordinates). Accepts `ll` ("@lat,lng,14z"). */
+  /**
+   * Google Maps search (places with coordinates). Accepts `ll` ("@lat,lng,14z"). With
+   * `engine: "yandex"` (where enabled) the places come from Yandex Maps and carry an `oid`.
+   */
   maps = this.#vertical("/v1/maps");
   /** Google local results. */
   places = this.#vertical("/v1/places");
   /**
-   * Details of one place by `place_id`, `cid` or `fid`: address, country, time zone, hours
+   * Details of one place by `place_id`, `cid` or `fid`, or by a Yandex Maps `oid` (implies
+   * `engine: "yandex"`): address, country, time zone, hours
    * (`opening_hours` text and structured `weekly_hours`), phones, description and photos.
    * `results` holds the place, or is empty (not charged) when no place has that id. 1 credit.
    */
@@ -128,9 +132,14 @@ var SerpKite = class {
    * Read up to 20 URLs (HTML or PDF) as Markdown, text or HTML in one call, with optional
    * query-ranked `highlights` (BM25), `include_links` and `include_images`. 1 credit per URL
    * that comes back (0.5 from cache); URLs that fail are listed in `failed` and cost nothing.
+   * `summary: true` adds an AI summary of each page and `output_schema` (a JSON Schema, guided
+   * by an optional `prompt`) returns each page's data as JSON in `output`, each at an extra
+   * per-page price (https://serpkite.com/pricing); a page whose model step failed has
+   * `summary_error` / `output_error` instead and isn't charged for it.
    */
   extract(params, options) {
-    const wait = ((params.timeout ?? 50) + 15) * 1e3;
+    const ai = params.summary === true || params.output_schema !== void 0;
+    const wait = ((params.timeout ?? (ai ? 75 : 50)) + 15) * 1e3;
     return this.request({
       method: "POST",
       path: "/v1/extract",
@@ -155,6 +164,47 @@ var SerpKite = class {
   account(options) {
     return this.request({ method: "GET", path: "/v1/account", options });
   }
+  // ── AI answers ────────────────────────────────────────────────────────
+  /**
+   * A cited answer grounded on live Google results: Markdown with `[n]` markers in `answer`,
+   * the cited sources in `citations`. `depth: "fast"` answers from the result page;
+   * `"standard"` (default) also reads the top `num_sources` pages and costs more
+   * (https://serpkite.com/pricing; `meta.credits` splits search and model). With
+   * `output_schema` the answer is a JSON value in `output`.
+   * When the model fails the call throws `ai_unavailable` (503) and the model part is refunded;
+   * a search with nothing to answer from returns `answer: null` and a `meta.warnings` entry.
+   */
+  answer(params, options) {
+    return this.request({
+      method: "POST",
+      path: "/v1/answer",
+      body: params,
+      options: { ...options, timeoutMs: this.#answerTimeout(options) },
+      retry: "rate_limit"
+    });
+  }
+  /**
+   * Streams an answer as Server-Sent Events: `results` first, then `delta` text pieces,
+   * then `done` (final answer, citations, meta). A server `error` event is thrown as a
+   * `SerpKiteError` (`ai_unavailable`). Breaking out of the loop closes the connection
+   * (the model part is then not charged). Can't be combined with `output_schema`.
+   *
+   * ```ts
+   * for await (const ev of sk.answerStream({ q: "what is retrieval-augmented generation" })) {
+   *   if (ev.event === "delta") process.stdout.write(ev.data.text);
+   * }
+   * ```
+   */
+  answerStream(params, options) {
+    return this.#stream(
+      { ...params, stream: true },
+      { ...options, timeoutMs: this.#answerTimeout(options) }
+    );
+  }
+  /** The search (pages read included) runs before the first byte: wait at least 100 s. */
+  #answerTimeout(options) {
+    return options?.timeoutMs ?? (this.timeoutMs > 0 ? Math.max(this.timeoutMs, 1e5) : 0);
+  }
   // ── Async tasks: crawl ────────────────────────────────────────────────
   /**
    * Starts an async crawl of one site and returns the queued task (`202`). 1 credit per page
@@ -197,6 +247,58 @@ var SerpKite = class {
       timeoutMs: options.timeoutMs ?? 21e5
     });
   }
+  // ── Async tasks: research ─────────────────────────────────────────────
+  /**
+   * Starts an async research task: the model plans searches, reads the sources and writes a
+   * cited Markdown report (`result.report`). `effort` (`lite`, `standard` (default), `deep`)
+   * sets how much is searched and read; its flat price (https://serpkite.com/pricing) is
+   * reserved up front and charged only when the report is written (a canceled task is charged
+   * for the searches already run). With
+   * `output_schema` the report is also returned as JSON in `result.output`. Poll with
+   * `getResearch` / `waitResearch` or receive the signed `research.completed` webhook.
+   * Only retried on 429, so a lost response never starts (and reserves) a second task.
+   */
+  research(params, options) {
+    return this.request({
+      method: "POST",
+      path: "/v1/research",
+      body: params,
+      options,
+      retry: "rate_limit"
+    });
+  }
+  /** Polls a research task (`progress` while it runs; results are kept for 24 hours). */
+  getResearch(id, options) {
+    return this.request({
+      method: "GET",
+      path: `/v1/research/${encodeURIComponent(id)}`,
+      options
+    });
+  }
+  /**
+   * Cancels a research task: refunded if still queued, else stops at its next round and is
+   * charged for the searches run.
+   */
+  cancelResearch(id, options) {
+    return this.request({
+      method: "DELETE",
+      path: `/v1/research/${encodeURIComponent(id)}`,
+      options
+    });
+  }
+  /**
+   * Polls until the research task is `completed`, `failed` or `canceled` and returns it (a
+   * failed task is returned, not thrown; check `status` and `error`). The report is in
+   * `result.report`. Accepts an id or the task returned by `research`. Default timeout
+   * 15 minutes.
+   */
+  async waitResearch(idOrTask, options = {}) {
+    return this.#waitTask(
+      taskId(idOrTask),
+      (id) => this.getResearch(id, { signal: options.signal }),
+      { ...options, timeoutMs: options.timeoutMs ?? 9e5 }
+    );
+  }
   // ── Monitors ──────────────────────────────────────────────────────────
   monitors = {
     /**
@@ -366,6 +468,149 @@ var SerpKite = class {
       interval = Math.min(interval * 1.5, maxInterval);
     }
   }
+  /** Opens `POST /v1/answer` as an event stream (retrying the connect like `request`) and parses it. */
+  async *#stream(body, options = {}) {
+    const maxRetries = Math.max(0, options.maxRetries ?? this.maxRetries);
+    const timeoutMs = options.timeoutMs ?? this.timeoutMs;
+    const headers = {
+      Accept: "text/event-stream, application/json;q=0.9",
+      Authorization: `Bearer ${this.#apiKey}`,
+      ...this.#headers,
+      ...options.headers,
+      "Content-Type": "application/json"
+    };
+    if (!isBrowser()) headers["User-Agent"] = `serpkite-typescript/${VERSION}`;
+    let res;
+    let cleanup = () => {
+    };
+    for (let attempt = 0; !res; attempt++) {
+      const canRetry = attempt < maxRetries;
+      const t = withTimeout(options.signal, timeoutMs);
+      let r;
+      try {
+        r = await this.#fetch(`${this.baseUrl}/v1/answer`, {
+          method: "POST",
+          headers,
+          body: JSON.stringify(body),
+          signal: t.signal
+        });
+      } catch (err) {
+        t.cleanup();
+        if (options.signal?.aborted) throw err;
+        if (canRetry) {
+          await sleep(this.#backoff(attempt), options.signal);
+          continue;
+        }
+        const code = t.timedOut() ? "timeout" : "connection_error";
+        const msg = t.timedOut() ? `request timed out after ${timeoutMs} ms` : `request failed: ${err instanceof Error ? err.message : String(err)}`;
+        throw new SerpKiteError(0, code, msg, void 0, void 0, { cause: err });
+      }
+      if (!r.ok) {
+        const text = await r.text().catch(() => "");
+        t.cleanup();
+        if (canRetry && (r.status === 429 || r.status >= 500)) {
+          await sleep(this.#retryDelay(attempt, r.headers), options.signal);
+          continue;
+        }
+        throw errorFromResponse(r.status, r.headers, text);
+      }
+      t.stopTimer();
+      cleanup = t.cleanup;
+      res = r;
+    }
+    options.onResponse?.(responseInfo(res));
+    const requestId = res.headers.get("x-request-id") ?? void 0;
+    if (!res.body) {
+      cleanup();
+      throw new SerpKiteError(
+        res.status,
+        "invalid_response",
+        "response has no body",
+        requestId,
+        res.headers
+      );
+    }
+    if ((res.headers.get("content-type") ?? "").includes("json")) {
+      let answer;
+      try {
+        answer = JSON.parse(await res.text());
+      } catch (err) {
+        throw new SerpKiteError(
+          res.status,
+          "invalid_response",
+          "response is not valid JSON",
+          requestId,
+          res.headers,
+          { cause: err }
+        );
+      } finally {
+        cleanup();
+      }
+      yield { event: "results", data: { request: answer.request, results: answer.results } };
+      yield {
+        event: "done",
+        data: { answer: answer.answer ?? "", citations: answer.citations, meta: answer.meta }
+      };
+      return;
+    }
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buf = "";
+    let done = false;
+    try {
+      while (!done) {
+        let chunk;
+        try {
+          chunk = await reader.read();
+        } catch (err) {
+          if (options.signal?.aborted) throw err;
+          throw new SerpKiteError(
+            0,
+            "connection_error",
+            `stream read failed: ${err instanceof Error ? err.message : String(err)}`,
+            requestId,
+            res.headers,
+            { cause: err }
+          );
+        }
+        if (chunk.done) {
+          buf += decoder.decode();
+          done = true;
+        } else {
+          buf += decoder.decode(chunk.value, { stream: true });
+        }
+        const held = !done && buf.endsWith("\r") ? "\r" : "";
+        if (held) buf = buf.slice(0, -1);
+        buf = buf.replace(/\r\n?/g, "\n");
+        let sep = buf.indexOf("\n\n");
+        while (sep >= 0 || done && buf.trim() !== "") {
+          const raw = sep >= 0 ? buf.slice(0, sep) : buf;
+          buf = sep >= 0 ? buf.slice(sep + 2) : "";
+          const ev = parseSSE(raw);
+          if (ev) {
+            if (ev.event === "error") throw sseError(ev.data, res.headers, requestId);
+            if (ev.event === "results" || ev.event === "delta" || ev.event === "done") {
+              yield { event: ev.event, data: ev.data };
+              if (ev.event === "done") return;
+            }
+          }
+          sep = buf.indexOf("\n\n");
+        }
+        buf += held;
+      }
+      throw new SerpKiteError(
+        res.status,
+        "invalid_response",
+        "the stream ended before the done event",
+        requestId,
+        res.headers
+      );
+    } finally {
+      cleanup();
+      reader.cancel().catch(() => {
+      });
+    }
+  }
   /** Low-level request: JSON body in, parsed JSON (or text for non-JSON responses) out. */
   async request(call) {
     const { method, path, body, options = {} } = call;
@@ -473,6 +718,36 @@ function taskId(idOrTask) {
   if (!id) throw new SerpKiteError(0, "invalid_request", "a task id is required");
   return id;
 }
+function parseSSE(block) {
+  let event = "message";
+  const data = [];
+  for (const line of block.split("\n")) {
+    if (line === "" || line.startsWith(":")) continue;
+    const i = line.indexOf(":");
+    const field = i < 0 ? line : line.slice(0, i);
+    let value = i < 0 ? "" : line.slice(i + 1);
+    if (value.startsWith(" ")) value = value.slice(1);
+    if (field === "event") event = value;
+    else if (field === "data") data.push(value);
+  }
+  if (data.length === 0) return void 0;
+  const text = data.join("\n");
+  try {
+    return { event, data: JSON.parse(text) };
+  } catch {
+    return { event, data: text };
+  }
+}
+function sseError(data, headers, requestId) {
+  const e = data?.error;
+  return new SerpKiteError(
+    503,
+    e?.code ?? "unavailable",
+    e?.message ?? "the answer stream failed",
+    e?.request_id ?? requestId,
+    headers
+  );
+}
 function parseRetryAfter(v) {
   if (!v) return void 0;
   const secs = Number(v);
@@ -514,6 +789,9 @@ function withTimeout(outer, ms) {
   return {
     signal: ctrl.signal,
     timedOut: () => timedOut,
+    stopTimer: () => {
+      if (timer !== void 0) clearTimeout(timer);
+    },
     cleanup: () => {
       if (timer !== void 0) clearTimeout(timer);
       outer?.removeEventListener("abort", onAbort);