serpkite 0.6.0 → 0.8.0

package/README.md

@@ -94,12 +94,19 @@ vertical-specific extras and `meta` (`request_id`, `credits_used`, `cached`, `la
 | `patents(params)` | `POST /v1/patents` | `SearchParams` | `PatentsResponse` |
 | `autocomplete(params)` | `POST /v1/autocomplete` | `SearchParams` | `AutocompleteResponse` (`results[].value`) |
 | `webpage(params)` | `POST /v1/webpage` | `WebpageParams` (`url`, `include_html`) | `WebpageResponse` (`markdown`, `text`, `metadata`) |
+| `chatgpt(params)` | `POST /v1/chatgpt` | `ChatGPTParams` (`prompt`, `web_search`, `country`, `track`, `include_html`) | `AssistantResponse` |
+| `gemini` / `copilot` / `aiMode` / `braveAi(params)` | `POST /v1/gemini` / `copilot` / `ai_mode` / `brave_ai` | `AssistantParams` (`prompt`, `country`, `language`, `track`, `include_html`) | `AssistantResponse` (`text`, `markdown`, `sources`, `search_queries`, `products`, `places`, `mentions`) |
 | `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 +118,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 +199,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 +210,104 @@ 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.
+
+## AI assistants
+
+Ask ChatGPT, Gemini, Copilot (Bing Copilot Search), Google AI Mode or Brave's AI answer a `prompt` as a
+logged-out user and get the answer with the sources it cited, the searches it ran and the products
+and places it showed. `track` lists brands and domains to look for: each comes back in `mentions`.
+
+```ts
+const res = await sk.chatgpt({
+  prompt: "What are the best CRMs for a 10-person startup?",
+  country: "us", // ask from an exit in this country (prices and shops follow it)
+  track: ["hubspot.com", "Pipedrive"],
+});
+console.log(res.model, res.markdown); // citations as [n](link), matching sources[].position
+for (const s of res.sources) console.log(s.position, s.cited ? "cited" : "listed", s.domain);
+console.log(res.search_queries, res.products.map((p) => `${p.title} ${p.price}`));
+for (const m of res.mentions ?? []) {
+  // mentioned: the text names it; cited: a cited source matches it; text_position 0-1 (-1: not named)
+  console.log(m.term, m.mentioned, m.cited, m.sources, m.text_position);
+}
+
+const md = await sk.aiMode({ prompt: "how to remove a red wine stain from wool", format: "markdown" }); // string
+await sk.gemini({ prompt: "Wie funktionieren Wärmepumpen?", country: "de", language: "de" });
+
+// Google's AI Overview on a normal search, when the page shows one
+const serp = await sk.search({ q: "how do heat pumps work" });
+console.log(serp.ai_overview?.text, serp.ai_overview?.sources);
+```
+
+- Prices per answer: ChatGPT 5, Gemini 5, Copilot 3, AI Mode 3, Brave AI 2 credits (the same in
+  batches; `max_age` cache hits half). Failed, refused and empty answers are free.
+- Answers take 10-90 s: these methods wait at least `ASSISTANT_TIMEOUT_MS` (120 s) per attempt
+  unless you pass `timeoutMs`, and are retried only on `429` (a lost response is still billed).
+- `web_search` (default `true`) is ChatGPT only; `language` isn't taken by ChatGPT.
+- Run many prompts through `batches.create({ endpoint: "chatgpt", requests: [{ prompt }, …] })`, or
+  track an answer over time with a monitor (`endpoint: "gemini"`, `prompt`, `track`; see Monitors).
+
+## 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
@@ -268,6 +373,21 @@ per check) and reports it as a `MonitorPageChange` (`url`, `title`, `change: "ne
 stored on any monitor and echoed in its `monitor.results` webhooks; on `update`, an object replaces it
 and `null` clears it.
 
+An AI assistant monitor (`endpoint`: `chatgpt`, `gemini`, `copilot`, `ai_mode` or `brave_ai`) asks
+`prompt` every run and reports every answer as one `MonitorAnswer` (`text`, `markdown`, `model`,
+`sources`, `new_sources` (links not seen in earlier runs), `search_queries`, `products` and, with
+`track`, `mentions`); its `monitor.results` webhook carries `prompt` instead of `q`. Each run costs
+the endpoint's price.
+
+```ts
+await sk.monitors.create({
+  endpoint: "chatgpt",
+  prompt: "What are the best CRMs for a 10-person startup?",
+  track: ["hubspot.com", "Pipedrive"],
+  interval: "daily",
+});
+```
+
 ```ts
 const watch = await sk.monitors.create({
   endpoint: "webpage",
@@ -286,7 +406,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:
@@ -310,7 +430,7 @@ import { isBatchError, SerpKite } from "serpkite";
 
 const sk = new SerpKite();
 const { batches } = await sk.batches.create({
-  endpoint: "search", // or images, news, maps, reviews, webpage, …
+  endpoint: "search", // or images, news, maps, reviews, webpage, chatgpt, gemini, …
   requests: [{ q: "a" }, { q: "b" }],
   webhook_url: "https://example.com/hooks/serpkite", // optional
 });
@@ -362,6 +482,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 +495,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`, the AI assistant
+methods, `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 +510,10 @@ 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`, `AssistantParams`, `ChatGPTParams`, `AssistantResponse`, `AISource`, `AIProduct`,
+`Mention`, `AIOverview`, `MonitorAnswer`, `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,8 +50,9 @@ function errorFromResponse(status, headers, body) {
 }
 
 // src/client.ts
-var VERSION = "0.6.0";
+var VERSION = "0.8.0";
 var DEFAULT_BASE_URL = "https://api.serpkite.com";
+var ASSISTANT_TIMEOUT_MS = 12e4;
 var TASK_DONE = /* @__PURE__ */ new Set(["completed", "failed", "canceled"]);
 var SerpKite = class {
   baseUrl;
@@ -124,6 +125,24 @@ var SerpKite = class {
   autocomplete = this.#vertical("/v1/autocomplete");
   /** Fetch any public URL as clean Markdown plus metadata. */
   webpage = this.#vertical("/v1/webpage");
+  // ── AI assistants ─────────────────────────────────────────────────────
+  // Billed even when the response is lost: retried only on 429 (failed, refused and empty
+  // answers are free), and each attempt waits at least 120 s (answers take 10-90 s).
+  /**
+   * Ask ChatGPT as a logged-out user: the answer (`text`, `markdown`), cited `sources`,
+   * `search_queries`, `products`, `places` and the guest `model`. `web_search` (default true)
+   * makes it search the web; `country` asks from an exit in that country. `track` returns
+   * `mentions` of your brands and domains. 5 credits.
+   */
+  chatgpt = this.#assistant("/v1/chatgpt");
+  /** Ask Google Gemini as a logged-out user: the answer with the sources it grounded on. 5 credits. */
+  gemini = this.#assistant("/v1/gemini");
+  /** Microsoft Copilot Search on Bing: the answer, cited sources and products. 3 credits. */
+  copilot = this.#assistant("/v1/copilot");
+  /** Google AI Mode: the answer, cited sources and products. 3 credits. */
+  aiMode = this.#assistant("/v1/ai_mode");
+  /** Brave Search's AI answer: cited sources, the searches it ran and products. 2 credits. */
+  braveAi = this.#assistant("/v1/brave_ai");
   /** Position of `domain` for keyword `q` in the top `num` results (default 100). */
   rank(params, options) {
     return this.request({ method: "POST", path: "/v1/rank", body: params, options });
@@ -132,9 +151,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",
@@ -159,6 +183,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
@@ -201,6 +266,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 = {
     /**
@@ -210,7 +327,9 @@ var SerpKite = class {
      * and reports it (`MonitorPageChange`) when its content changes. `metadata` (your JSON
      * object, at most 2 KB) is echoed on the monitor and in its webhooks. Without a
      * `webhook_url`, read new results from `monitors.runs`. `active: false`
-     * creates it paused. A monitor pauses itself after 10 failed runs in a row
+     * creates it paused. With an AI assistant `endpoint` (`chatgpt`, `gemini`, `copilot`,
+     * `ai_mode`, `brave_ai`) and a `prompt` every run reports the answer (`MonitorAnswer`:
+     * sources, `new_sources`, `mentions` with `track`). A monitor pauses itself after 10 failed runs in a row
      * (`last_status: "paused"`); `update(id, { active: true })` resumes it. Each run costs
      * what its search costs. Only retried on 429.
      */
@@ -333,6 +452,18 @@ var SerpKite = class {
   #vertical(path) {
     return ((params, options) => this.request({ method: "POST", path, body: params, options }));
   }
+  #assistant(path) {
+    return ((params, options) => this.request({
+      method: "POST",
+      path,
+      body: params,
+      options: {
+        ...options,
+        timeoutMs: options?.timeoutMs ?? (this.timeoutMs > 0 ? Math.max(this.timeoutMs, ASSISTANT_TIMEOUT_MS) : 0)
+      },
+      retry: "rate_limit"
+    }));
+  }
   async #wait(idOrEntry, o) {
     let id;
     if (typeof idOrEntry === "string") {
@@ -370,6 +501,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;
@@ -477,6 +751,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);
@@ -518,6 +822,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);
@@ -621,6 +928,7 @@ async function parseWebhook(secret, payload, headers, options = {}) {
   return { type, deliveryId: header(headers, "x-serpkite-delivery"), data };
 }
 
+exports.ASSISTANT_TIMEOUT_MS = ASSISTANT_TIMEOUT_MS;
 exports.DEFAULT_BASE_URL = DEFAULT_BASE_URL;
 exports.SerpKite = SerpKite;
 exports.SerpKiteError = SerpKiteError;