@broberg / lens-client
一、 用于托管Lens的瘦客户端 （lens.cardmem.com）. 截图页面和
通过HTTP驱动自修复流 没有剧作家，没有浏览器 站在你这边。
npm i @broberg/lens-client
三包分割
| 你需要…… | 使用 |
|---|---|
| 调用 主持 镜头通过HTTP（无浏览器） | @broberg/lens-client |
| 自己运行一个真正的浏览器（capture + flow） | @broberg/lens-engine (剧作家) |
| 创建/验证Lens会话（auth/compliance） | @broberg/lens (dep-free) |
使用(服务器端)
import { createLensClient } from "@broberg/lens-client";
const lens = createLensClient({
baseUrl: process.env.LENS_CLOUD_URL, // default https://lens.cardmem.com
token: process.env.LENS_CLOUD_TOKEN, // Bearer service token — server-side only
});
const shot = await lens.capture({ url: "https://example.com", mode: "fullPage" });
// → { run_id, screenshot_url, dom_hash, status: "ok", width, height, final_url, title }
const png = shot.screenshot_url ? await lens.fetchArtifact(shot.screenshot_url) : null;
const run = await lens.runFlow({
base_url: "https://appstoreconnect.apple.com",
steps: [
{ action: "goto", url: "/apps" },
{ action: "click", target: { role: "button", name: "New Version" } }, // self-healing LocateSpec
{ action: "fill", target: { label: "Version Number" }, value: "1.2.0" },
],
});
baseUrl/token 默认为 LENS_CLOUD_URL / LENS_CLOUD_TOKEN.
自愈定位器
一个步骤 target 是一个纯字符串(CSS选择器/裸 data-testid)或
LocateSpec - - - - - - { testid?, css?, role?, name?, label?, placeholder?, text?, exact?, nth?, vision? } - - - - - -
尝试固定优先级： testid → css → role → label → placeholder → text → vision.
每一步的结果 resolved_via （哪一层匹配）所以log a
degraded-match 当水流飘过时发出警报 testid 放到一个更模糊的图层上。
错误——失败的流是数据，而不是异常
一、 失败的步骤将停止流程并固定截图;流回来作为一个
正常结果 status: "failed" ——读 steps 看到 哪一个 步骤失败
为什么 （永远不会抛出丢失上下文的异常）：
const run = await lens.runFlow(manuscript);
if (run.status === "failed") {
const bad = run.steps.find((s) => s.status === "failed");
// bad.index, bad.action, bad.error, bad.screenshot_url
}
只有 传输/认证失败抛出 一个 LensClientError （.kind ＝ auth 在401年,
unavailable 在503年, network 后重试, http 否则)。
冷启动
托管Lens在空闲时自动停止。客户端 预热 与 GET /health
然后重试 502 /网络错误（1-2次尝试，退出）。它 从来没有 重试一
401 （坏记号）或 503 （船暗）-那些是终端。与
{ retries, retryBackoffMs, prewarm }.
工件令牌gotcha
screenshot_url 点 /artifact?key=… 并且需要 同样持票人 去拿。
fetchArtifact(url) 连接它 只有 当URL为同源时 baseUrl - - - - - -
永远不会将令牌泄露给外国主机。
浏览器代理 @broberg/lens-client/hono
所以一个产品 前端 可以在没有看到代币的情况下调用Lens，安装
您自己的服务器上的代理（同源） /api/lens/*，令牌留在服务器端)：
import { createLensProxy } from "@broberg/lens-client/hono";
app.route("/api/lens", createLensProxy()); // token from LENS_CLOUD_TOKEN
// browser:
const lens = createLensClient({ baseUrl: "/api/lens" }); // no token in the browser
hono 是一个 可选的对等 -仅用于代理。核心客户(.)
零运行时依赖项.
API
function createLensClient(opts?: LensClientOptions): LensClient;
// .capture(body) → CaptureResult .runFlow(body) → FlowResult
// .health() → boolean .fetchArtifact(url) → Uint8Array
function createLensProxy(opts?: LensProxyOptions): Hono; // "@broberg/lens-client/hono"
class LensClientError extends Error; // .kind, .status
麻省理工学院·一部分 @broberg/* 共享库的家庭。