How to Perform Network Requests from the Node.js Server or Browser Context in Ego-Lite

Ego-Lite provides a unified fetch facade that exposes fetch.server for Node.js HTTP requests and fetch.browser for requests executed within the controlled browser page, both implemented in src/http.ts and registered in src/helpers.ts.

Ego-Lite is an open-source browser automation framework that simplifies agent scripting by abstracting away environment-specific networking details. When building automation workflows, you often need to perform network requests from either the Node.js runtime or directly from the browser page context. The framework provides a consistent API through its fetch facade, allowing agents to execute HTTP requests seamlessly regardless of the execution environment.

Server-Side Network Requests with fetch.server

Agent scripts running in the Node.js environment can issue HTTP requests using fetch.server, implemented as serverFetch in src/http.ts (lines 11-27).

This function wraps Node.js's native global fetch and enforces a browser-like User-Agent header ("Mozilla/5.0") to ensure compatibility with servers that block non-browser clients. It accepts a URL string and an options object containing headers, method, body, and timeout (specified in seconds).

If the response status is not ok, the function throws a descriptive error containing the status code and status text. On success, it returns the response body as a plain text string.

// Request from Node.js server context
const html = await fetch.server('https://example.com', {
  headers: { 'Accept': 'text/html' },
  timeout: 10,
});
console.log('Response length:', html.length);

Browser Context Network Requests with fetch.browser

For requests that must originate from the browser page itself—useful for maintaining cookies, session state, or bypassing CORS restrictions—use fetch.browser, implemented as browserFetch in src/http.ts (lines 35-52).

This function serializes the request parameters and injects them into the active page using the evaluate helper from src/cdp-eval.ts, which executes code via the Chrome DevTools Protocol (CDP). The request runs inside an async IIFE within the page context, using the browser's native fetch implementation.

To ensure consistency with the server-side behavior, browserFetch implements a manual AbortController to enforce the timeout limit. Errors propagate with the same message format as serverFetch, maintaining a predictable debugging experience across both contexts.

// Request from within the browser page
const json = await fetch.browser('/api/data', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ foo: 'bar' }),
  timeout: 5,
});
const data = JSON.parse(json);

Facade Registration and Helper Context

The dual fetch API is exposed to agent scripts through the helper context created in src/helpers.ts (lines 18-31). Here, the fetch object containing both server and browser methods is attached to the agent's execution context.

Documentation for these helpers is automatically generated and available via the help('fetch') command, defined in the FACADE_HELP mapping within src/format.ts.

Configuration Options and Error Handling

Both fetch.server and fetch.browser accept a consistent options interface:

• headers: Object containing HTTP header key-value pairs
• method: HTTP method string (GET, POST, PUT, DELETE, etc.)
• body: Request payload as string
• timeout: Maximum wait time in seconds before aborting the request

Error handling is normalized across both environments. When a request fails or returns a non-2xx status code, the functions throw descriptive errors containing the status code and response details. This unified error format allows agents to handle network failures predictably without environment-specific branching logic.

Summary

• Ego-Lite provides a unified fetch facade with fetch.server for Node.js and fetch.browser for page-context requests
• serverFetch in src/http.ts wraps Node's native fetch with a forced Mozilla User-Agent
• browserFetch in src/http.ts executes requests via CDP's evaluate function within the browser page
• Both methods support custom headers, HTTP methods, request bodies, and configurable timeouts
• The facade is registered in src/helpers.ts and documented through the built-in help system
• Error handling is consistent across environments, throwing descriptive messages for non-ok responses

Frequently Asked Questions

What is the difference between fetch.server and fetch.browser in Ego-Lite?

fetch.server executes HTTP requests from the Node.js runtime environment using Node's native global fetch, while fetch.browser injects and executes the fetch call within the currently controlled browser page via Chrome DevTools Protocol. Use fetch.server for direct API calls from the automation script, and fetch.browser when you need the request to originate from the browser context to maintain session cookies or bypass CORS restrictions.

How does Ego-Lite handle request timeouts for browser-context fetches?

The browserFetch implementation in src/http.ts manually instantiates an AbortController and passes its signal to the fetch call executed within the page. If the specified timeout duration elapses before the response returns, the controller aborts the request, throwing a timeout error that matches the format used by serverFetch for consistency.

Can I send POST requests with JSON payloads using the Ego-Lite fetch facade?

Yes, both fetch.server and fetch.browser support POST requests with custom headers and bodies. Pass method: 'POST', set the appropriate Content-Type header (typically application/json), and provide the serialized JSON string in the body option. The response is always returned as plain text, which you can then parse using JSON.parse().

Where is the fetch facade registered and exposed to agent scripts?

The fetch object containing both server and browser methods is registered in src/helpers.ts (lines 18-31) as part of the helper context creation. This registration makes the methods available globally within agent scripts. Documentation for these methods is maintained in src/format.ts within the FACADE_HELP map and accessible via the help('fetch') command.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}