@xenosystem/web-context-client

Dependency-free typed HTTP client and request/evidence contracts for XENO Web Context.

The server runtime, providers, workers, browser renderer, PostgreSQL, and S3 dependencies are deliberately not part of this package.

Entry points

| Import | Contents | |---|---| | @xenosystem/web-context-client | WebContextClient and the job-progress contract. | | @xenosystem/web-context-client/contract | Request, budget, policy, and evidence contracts. | | @xenosystem/web-context-client/job | WebJob, WebMonitor, MonitorCheck projections. | | @xenosystem/web-context-client/progress | WebJobProgress and its derivation helpers. |

Routing through the XENO account gateway

pathPrefix replaces the leading /v1 of every route. The default is empty, which sends routes unchanged. The XENO account gateway serves Web Context at /v1/web:

const client = new WebContextClient({
  baseUrl: "https://api.xenostudio.ai",
  token: accountCredential,
  pathPrefix: "/v1/web",
});

Only routes the gateway serves are reachable under the prefix: search, scrape, extract, map, render, search-and-scrape, parse, job get and job cancel.

Provider cost intent

For account-gateway search, an unset caller limit is represented by budget: { ...limits, maxProviderCostUsd: 0, providerCostMode: "account-default" }. The gateway resolves this marker to its configured allowance and removes the marker before dispatch. Direct runtimes do not grant an allowance from this marker.

An explicit caller limit omits providerCostMode: zero forbids provider spend, a positive number narrows the server allowance, and an invalid value is refused. Legacy zero budgets are preserved as zero, not reinterpreted as permission to spend. Provider cost limits are distinct from any customer credit price.

Job progress

waitForJob and scrapeAndWait accept an optional onProgress listener. It is the one progress contract shared by Chat, the Agent SDK, ACP v2, the CLI, and the Agent Interface — do not build a second polling engine on top of job().

const document = await client.scrapeAndWait(request, {
  onProgress: (progress) => {
    // WebJobProgress: schema identity, jobId, operation, state, terminal semantics,
    // and non-negative page counters. No token, query, purpose, request body,
    // provider body, artifact bytes, or tenant/fence authority.
    ui.render(progress);
  },
});

The initial observation is always emitted, then only observations whose content changed, then the terminal observation exactly once. A timeout raises WAIT_TIMEOUT and never invents a terminal observation. Progress is fail-closed: a listener that throws or rejects stops the wait and raises PROGRESS_LISTENER_FAILED with the original error on cause; the durable job is left running and can be cancelled explicitly. Omitting onProgress preserves the previous behavior exactly.