Embedding Scrape in Your App

Embed Scrape when you want the engine to live in your process, share local dependencies, or expose /api/scrape/* from an existing app. Call the API when you want process isolation or a separately deployed Scrape service.

Embed as Bun Middleware

The server exposes a fetch-style handler, so Bun embedding is direct.

import { createScrapeServer } from "@cuitty/scrape/server";

const scrape = createScrapeServer();

Bun.serve({
  port: 8080,
  async fetch(request) {
    const url = new URL(request.url);
    if (url.pathname.startsWith("/api/scrape/")) {
      return scrape.handleRequest(request);
    }
    return new Response("app route");
  },
});

Express, Hono, and Astro Routes

Use the same rule: convert or forward the platform request to a standard Request, call handleRequest, and return the standard Response. Keep the /api/scrape/* prefix intact because the handler strips that prefix internally.

In-Process Worker

Use server.run() when an internal job queue or test runner does not need HTTP.

import { createScrapeServer } from "@cuitty/scrape/server";

const server = createScrapeServer();

export async function runContentCheck(url: string) {
  return server.run({
    url,
    intent: "Verify the page has a visible main heading",
    mode: "content",
    budget: { maxSteps: 4 },
  });
}

console.log((await runContentCheck("https://example.com")).status);

Embedding in Cuitty Test

Cuitty Test should consume Scrape through @cuitty/scrape/client or the HTTP API. That keeps test assertions on the product contract and avoids importing the engine internals.

Embedding in Cuitty Pilot

Cuitty Pilot should use @cuitty/scrape/pilot. The adapter delegates browser goals to Scrape through the client boundary and returns structural Pilot step results.

Configuration Reference

Layer	Configuration
Client	baseUrl, auth.bearerToken, mock, custom fetch.
Server	bridge, sessionFactory, credentials, clock, idgen.
Live server	playwright, apiKey, forceMockBridge, safe.
Request	url, intent, mode, schema, auth, budget, emit, interaction, project, captureSessionAs.

Operational Notes

Mocks are the default. Optional dependencies are lazy. A package consumer can use the client and mock server without Playwright, Anthropic, or Safe installed.