surfbird 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,55 @@
-# Temporary Holding Version
+# surfbird
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Zero-dependency JS/TS client for **[Surfbird](https://github.com/terry2010/surfbird)** — the unofficial self-hosted Docker distribution of [Cloudflare Kitesurf](https://github.com/cloudflare/kitesurf), a headless browser engine built for AI agents.
+
+Turn any VPS into a browser API: article→markdown extraction (Readability+turndown), rendered DOM, PNG screenshots, PDFs, page-context JS evaluation, and sequential batch fetching — over 6 tiny REST endpoints.
+
+```bash
+npm install surfbird
+```
+
+```js
+import { Surfbird } from "surfbird";
+
+const sb = new Surfbird("http://vps:8080", { token: process.env.SURFBIRD_TOKEN });
+
+// article → clean markdown (the RSS-digest / LLM-summarizer path)
+const { title, markdown } = await sb.markdown("https://blog.example.com/post");
+
+// rendered DOM / binary output
+const { html } = await sb.content("https://spa.example.com");
+const png = await sb.screenshot(url, { fullPage: true });
+const pdf = await sb.pdf(url);
+
+// run JS inside the page
+const links = await sb.evaluate(url, `[...document.querySelectorAll("a")].map(a=>a.href)`);
+
+// many urls, one call — sequential server-side, failures don't abort the batch
+const results = await sb.batch("markdown", [url1, url2, url3]);
+// → [{url, ok:true, status:200, data:{...}}, {url, ok:false, status:422, error:"no_article"}]
+```
+
+## API
+
+| Method | Returns |
+|---|---|
+| `sb.markdown(url)` | `{title, byline, excerpt, url, markdown}` (throws `SurfbirdError` status 422 when no article) |
+| `sb.content(url)` | `{title, url, html}` |
+| `sb.screenshot(url, {width, height, fullPage})` | PNG `Buffer` |
+| `sb.pdf(url, {landscape, format})` | PDF `Buffer` |
+| `sb.evaluate(url, script)` | JSON-serializable result |
+| `sb.batch(action, urls, {timeout})` | `[{url, ok, status, data\|error}]` (action: markdown/content/evaluate/screenshot/pdf) |
+| `sb.health()` | `boolean` |
+| `sb.openapi()` | server's OpenAPI JSON |
+
+Env vars used by examples: `SURFBIRD_URL`, `SURFBIRD_TOKEN`.
+
+## Get a server
+
+```bash
+docker run -d -p 8080:8080 -e SURFBIRD_TOKEN=$(openssl rand -hex 24) terry2010/surfbird:auth
+```
+
+MCP instead of a client lib? → [`surfbird-mcp`](https://www.npmjs.com/package/surfbird-mcp)
+
+Apache-2.0 · Not affiliated with Cloudflare · [GitHub](https://github.com/terry2010/surfbird)

package/index.mjs

@@ -0,0 +1,103 @@
+// surfbird — JS/TS client for the Surfbird REST API. Zero dependencies.
+//
+//   import { Surfbird } from "surfbird";
+//   const sb = new Surfbird("http://vps:8080", { token: "..." });
+//   const { markdown } = await sb.markdown("https://example.com/post");
+
+export class SurfbirdError extends Error {
+  constructor(status, code, message) {
+    super(`HTTP ${status} ${code}: ${message}`);
+    this.status = status;
+    this.code = code;
+  }
+}
+
+export class Surfbird {
+  /**
+   * @param {string} base  e.g. "http://127.0.0.1:8080" (auth) or ":8787" (raw)
+   * @param {object} [opts]
+   * @param {string} [opts.token]   Bearer token (required on auth images)
+   * @param {number} [opts.timeout] per-request ms, default 120000
+   */
+  constructor(base = "http://127.0.0.1:8080", { token = "", timeout = 120_000 } = {}) {
+    this.base = base.replace(/\/+$/, "");
+    this.token = token;
+    this.timeout = timeout;
+  }
+
+  async #post(action, body, timeout = this.timeout) {
+    const res = await fetch(`${this.base}/${action}`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        ...(this.token ? { authorization: `Bearer ${this.token}` } : {}),
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(timeout),
+    });
+    const buf = Buffer.from(await res.arrayBuffer());
+    if (!res.ok) {
+      let code = "http_error", message = res.statusText;
+      try {
+        const e = JSON.parse(buf.toString()).error || {};
+        if (e.code) code = e.code;
+        if (e.message) message = e.message;
+      } catch { /* non-JSON error body */ }
+      throw new SurfbirdError(res.status, code, message);
+    }
+    return buf;
+  }
+
+  /** Engine liveness (unauthenticated). */
+  async health() {
+    try {
+      const r = await fetch(`${this.base}/health`, { signal: AbortSignal.timeout(10_000) });
+      return r.ok;
+    } catch {
+      return false;
+    }
+  }
+
+  /** OpenAPI description of the server's REST surface (unauthenticated). */
+  async openapi() {
+    const r = await fetch(`${this.base}/openapi.json`, { signal: AbortSignal.timeout(10_000) });
+    return r.json();
+  }
+
+  /** Article extraction → {title, byline, excerpt, url, markdown}. Throws 422 SurfbirdError when no article. */
+  async markdown(url, opts = {}) {
+    return JSON.parse((await this.#post("markdown", { url, ...opts })).toString());
+  }
+
+  /** Rendered DOM → {title, url, html}. */
+  async content(url, opts = {}) {
+    return JSON.parse((await this.#post("content", { url, ...opts })).toString());
+  }
+
+  /** PNG screenshot → Buffer. opts: {width, height, fullPage} */
+  async screenshot(url, opts = {}) {
+    return this.#post("screenshot", { url, ...opts });
+  }
+
+  /** PDF → Buffer. opts: {landscape, format} */
+  async pdf(url, opts = {}) {
+    return this.#post("pdf", { url, ...opts });
+  }
+
+  /** Evaluate JS in page context → result (JSON-serializable). */
+  async evaluate(url, script, opts = {}) {
+    return (JSON.parse((await this.#post("evaluate", { url, script, ...opts })).toString())).result;
+  }
+
+  /**
+   * Run one action over many urls, sequentially (respects the server
+   * concurrency gate). Returns [{url, ok, status, data|error}] in input order.
+   * opts: {timeout} — overall batch timeout, default 10min.
+   */
+  async batch(action, urls, opts = {}) {
+    const res = await this.#post("batch", { action, urls }, opts.timeout ?? 600_000);
+    return JSON.parse(res.toString());
+  }
+}
+
+export default Surfbird;

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "surfbird",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "JS/TS client for Surfbird — the self-hosted Kitesurf headless browser engine. Article markdown extraction, screenshots, PDFs, page JS evaluation and batch fetching over a tiny REST API.",
+  "main": "./index.mjs",
+  "exports": {
+    ".": "./index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "README.md"
+  ],
+  "keywords": [
+    "surfbird",
+    "kitesurf",
+    "headless-browser",
+    "web-scraping",
+    "markdown",
+    "readability",
+    "screenshot",
+    "pdf",
+    "ai-agents",
+    "browser-automation",
+    "self-hosted"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/terry2010/surfbird.git",
+    "directory": "sdk"
+  },
+  "homepage": "https://github.com/terry2010/surfbird",
+  "engines": {
+    "node": ">=18"
+  }
+}