serpkite 0.5.0 → 0.7.0

package/dist/index.js

@@ -48,7 +48,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 {
@@ -96,12 +96,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.
    */
@@ -126,9 +130,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",
@@ -153,6 +162,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
@@ -195,6 +245,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 = {
     /**
@@ -364,6 +466,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;
@@ -471,6 +716,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);
@@ -512,6 +787,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);