@capsuleer/fetch

HTTP client module for Capsuleer agents. A thin traced wrapper around Bun's native fetch — every request logs status, size, and duration so Axon has a full record of what the agent called and what came back.

capsuleer install fetch

Also registers fetch as a bare global, so agents can call it directly without the fetch. namespace if they prefer.

API

// GET
const res = await fetch.fetch("https://api.github.com/repos/bun-sh/bun")
const repo = JSON.parse(res.body)

// POST with JSON
const res = await fetch.fetch("https://api.example.com/users", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Authorization": "Bearer token123" },
  body: JSON.stringify({ name: "Alice", email: "[email protected]" }),
})

// Check status before using body
if (!res.ok) throw new Error(`Request failed: ${res.status} ${res.statusText}`)
const data = JSON.parse(res.body)

Response shape

{
  status: 200,
  statusText: "OK",
  ok: true,                        // status in 200-299
  url: "https://...",              // final URL after redirects
  headers: { "content-type": "application/json", ... },
  body: "{ ... }",                 // always a string — JSON.parse() as needed
  durationMs: 142,
}

Observability

{ "ok": true, "op": "fetch", "data": { "url": "https://api.github.com/...", "method": "GET", "status": 200, "bytes": 4821, "durationMs": 142 } }
{ "ok": false, "op": "fetch", "data": { "url": "https://...", "method": "POST", "status": 401, "bytes": 32, "durationMs": 88 } }

Bare global

This module also exposes the native Bun fetch as a top-level global, so agent code can use the standard Web API directly:

const res = await fetch("https://example.com/api")
const data = await res.json()

Note: bare fetch calls bypass the trace logging. Use fetch.fetch() when observability matters.

Policy

const capsule = await Capsule({
  policy: {
    fetch: {
      fetch: { allow: ["https://api.github.com/*", "https://*.example.com/*"], deny: ["*"] }
    }
  }
})

See the policy docs for the full rule syntax.