Type-safe APIs for every web app

Lenses turns web pages into functions that return JSON. It runs them in your own Chrome, so a lens can read any page you are signed in to.

Documentation

you

Which supplier invoices are still unpaid?

$ lens call portal/invoices
  1. ›http: needs a signed-in page, skipped
  2. ›intercept: read GET /api/invoices
  3. ›Checked 24 invoices against returns

agent

Three are unpaid: INV-2207, INV-2211 and INV-2230.

Focus on the task, not the browser

An agent that drives a browser takes a screenshot, clicks, scrolls and reads the page again at every step. With a lens it makes one call and gets JSON back. The same question gets the same answer, in a form the agent can pass to the next step.

browser{ }lens{ }

A page becomes a function

A lens is a JSON file. It names a page, the parameters the page takes, the shape of the data it returns, and how to read that data from the page.

Calling the lens opens the page in your browser and returns the data as JSON. Links come back as $lens references, so you follow a link by making another call.

{
  "name": "@acme/portal/invoices",
  "url": "https://portal.supplier.com/invoices?cursor={params.cursor}",
  "params": { "cursor": { "type": "string", "default": "" } },
  "returns": {
    "type": "object",
    "fields": {
      "invoices": {
        "type": "array",
        "items": {
          "id": "string",
          "total": "number",
          "pdf": { "$lens": "@acme/portal/invoice.pdf", "params": { "id": "$item.id" } }
        }
      },
      "next_page": { "$lens": "@acme/portal/invoices", "params": { "cursor": "$item.next_page" } }
    }
  },
  "resolve": [{
    "kind": "intercept",
    "request": { "method": "GET", "url": "https://portal.supplier.com/api/invoices*" },
    "map": {
      "invoices": "[$res.body.items.{ 'id': id, 'total': total, 'pdf': id }]",
      "next_page": "$res.body.cursor"
    }
  }]
}
$ lens call portal/invoices -c ./lenses{
  "kind": "value",
  "value": {
    "invoices": [
      {
        "id": "INV-2207",
        "total": 1840.5,
        "pdf": { "$lens": "@acme/portal/invoice.pdf", "params": { "id": "INV-2207" } }
      }
    ],
    "next_page": { "$lens": "@acme/portal/invoices", "params": { "cursor": "c2Vlaz01MA" } }
  },
  "resolver": "intercept"
}

Everything an agent needs in one call

Typed results in one call

Name a lens and pass its parameters. The parameters are checked before the call runs, and the result is checked against the shape the lens declares in returns. If the page changes and the data no longer fits, you get an error that lists the mismatches instead of bad data. lens gen ts-sdk writes a typed client for a catalog.

Terminal
$ lens gen ts-sdk ./examples -o src/lenses.gen.ts

Cheapest path first

A lens lists several ways to get its data, cheapest first: the site's own API, the JSON the page fetches, the rendered HTML, and last the page text read by your model. The call uses the first one that works, and returns the same shape whichever one it used. While the site's API works, no tab opens.

@acme/portal/invoices · resolve
  • httpthe site's own API401, next
  • interceptthe JSON the page fetchesReturned
  • domthe rendered HTML
  • llmthe page text, read by your model

Sign-ins handled, not hidden

The broker makes each request from inside your Chrome, so the site sees your normal session. No password, cookie or token leaves the browser. When you are signed out, the call returns a named outcome with a hint, and code reads kind instead of error text. The agent asks you to sign in, then tries again.

Terminal
$ 

Writes that are safe to retry

A lens that changes something on a site declares it in effects. The broker refuses the call unless it passes --allow-writes. If a write times out, the result says whether the change happened, so the agent knows whether to try again.

acme.ledger.bills.approve.json
"effects": {
  "writes": ["ledger (approves a supplier bill)"],
  "idempotent": false
}

// after a timeout
{
  "kind": "error",
  "message": "call 7 for @acme/ledger/bills.approve timed out after 60000ms",
  "mutation": { "performed": "no" }
}

Agents write the lenses they need

When no lens fits, an agent observes the page, writes a lens file and tests it. lens observe lists the JSON requests a page makes, and lens eval tries expressions on real responses. Catalogs live in git, so you review the pull request like any other code, and every agent gets the new lens.

Terminal
$ 

Call it from anywhere

The CLI, the TypeScript client, the MCP server and the GraphQL server share one broker and one catalog of lens files. Over MCP, every lens in the catalog becomes a tool your agent can call.

Terminal
$ lens call hn/top --params '{"page": 2}' -c ./examples{
  "kind": "value",
  "value": { "stories": [ … ] },
  "resolver": "dom"
}

Install

Installation guideQuick start