sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Workers/ Browser.ts

import type * as cf from "@cloudflare/workers-types";
import type { RuntimeContext } from "alchemy/RuntimeContext";
import * as Data from "effect/Data";
import type * as Effect from "effect/Effect";
import type * as Stream from "effect/Stream";
import * as Binding from "./Binding.ts";
import type { BrowserBinding } from "./BrowserBinding.ts";

const TypeId = "Cloudflare.Browser" as const;
type TypeId = typeof TypeId;

export class BrowserError extends Data.TaggedError("BrowserError")<{
  message: string;
  cause: unknown;
}> {}

/** The `Response` type returned by the Cloudflare Browser Rendering binding. */
export type BrowserResponse = Awaited<ReturnType<cf.BrowserRun["fetch"]>>;

/** An Effect produced by a {@link BrowserClient} operation. */
type BrowserEffect<A> = Effect.Effect<A, BrowserError, RuntimeContext>;

/** A byte stream produced by a binary {@link BrowserClient} action. */
type BrowserByteStream = Stream.Stream<Uint8Array, BrowserError, RuntimeContext>;

// Quick action option types, re-exported so callers don't reach into the
// `@cloudflare/workers-types` namespace directly.
export type BrowserScreenshotOptions = cf.BrowserRunScreenshotOptions;
export type BrowserPDFOptions = cf.BrowserRunPDFOptions;
export type BrowserContentOptions = cf.BrowserRunContentOptions;
export type BrowserScrapeOptions = cf.BrowserRunScrapeOptions;
export type BrowserLinksOptions = cf.BrowserRunLinksOptions;
export type BrowserSnapshotOptions = cf.BrowserRunSnapshotOptions;
export type BrowserJsonOptions = cf.BrowserRunJsonOptions;
export type BrowserMarkdownOptions = cf.BrowserRunMarkdownOptions;

// Quick action success payloads.
export type BrowserContentResult = cf.BrowserRunContentSuccessResponse;
export type BrowserScrapeResult = cf.BrowserRunScrapeSuccessResponse;
export type BrowserLinksResult = cf.BrowserRunLinksSuccessResponse;
export type BrowserSnapshotResult = cf.BrowserRunSnapshotSuccessResponse;
export type BrowserJsonResult = cf.BrowserRunJsonSuccessResponse;
export type BrowserMarkdownResult = cf.BrowserRunMarkdownSuccessResponse;
export type BrowserErrorResponse = cf.BrowserRunErrorResponse;

/**
 * Effect-native client for a Cloudflare Browser Rendering binding.
 *
 * Mirrors the runtime {@link cf.BrowserRun} binding, translating its shapes into
 * Effect-native ones: JSON quick actions resolve to their parsed success
 * payload, and binary actions (`screenshot`, `pdf`) resolve to a `Stream` of the
 * response bytes. Non-success responses fail with {@link BrowserError}. The
 * {@link raw} accessor and {@link fetch} are the promise-shaped escape hatches
 * for libraries like `@cloudflare/puppeteer`.
 */
export interface BrowserClient {
  /** Effect resolving to the raw Cloudflare Browser Rendering runtime binding. */
  raw: Effect.Effect<cf.BrowserRun, never, RuntimeContext>;
  /** Send a raw HTTP request to the Browser Run API. */
  fetch(...args: Parameters<cf.BrowserRun["fetch"]>): BrowserEffect<BrowserResponse>;
  /** Run a Browser Run quick action, resolving to the parsed payload. */
  quickAction(action: "screenshot", options: BrowserScreenshotOptions): BrowserByteStream;
  quickAction(action: "pdf", options: BrowserPDFOptions): BrowserByteStream;
  quickAction(
    action: "content",
    options: BrowserContentOptions,
  ): BrowserEffect<BrowserContentResult>;
  quickAction(action: "scrape", options: BrowserScrapeOptions): BrowserEffect<BrowserScrapeResult>;
  quickAction(action: "links", options: BrowserLinksOptions): BrowserEffect<BrowserLinksResult>;
  quickAction(
    action: "snapshot",
    options: BrowserSnapshotOptions,
  ): BrowserEffect<BrowserSnapshotResult>;
  quickAction(action: "json", options: BrowserJsonOptions): BrowserEffect<BrowserJsonResult>;
  quickAction(
    action: "markdown",
    options: BrowserMarkdownOptions,
  ): BrowserEffect<BrowserMarkdownResult>;
  /** Take a screenshot of a web page, streaming the raw image bytes. */
  screenshot(options: BrowserScreenshotOptions): BrowserByteStream;
  /** Generate a PDF of a web page, streaming the raw PDF bytes. */
  pdf(options: BrowserPDFOptions): BrowserByteStream;
  /** Get the HTML content of a web page. */
  content(options: BrowserContentOptions): BrowserEffect<BrowserContentResult>;
  /** Scrape elements from a web page by CSS selector. */
  scrape(options: BrowserScrapeOptions): BrowserEffect<BrowserScrapeResult>;
  /** Extract all links from a web page. */
  links(options: BrowserLinksOptions): BrowserEffect<BrowserLinksResult>;
  /** Get both the HTML content and a base64-encoded screenshot of a web page. */
  snapshot(options: BrowserSnapshotOptions): BrowserEffect<BrowserSnapshotResult>;
  /** Extract structured JSON data from a web page using AI. */
  json(options: BrowserJsonOptions): BrowserEffect<BrowserJsonResult>;
  /** Convert a web page to Markdown. */
  markdown(options: BrowserMarkdownOptions): BrowserEffect<BrowserMarkdownResult>;
}

/**
 * A Cloudflare Browser Rendering binding for launching headless browser sessions
 * from Workers — a Worker-only binding with no backing cloud resource.
 *
 * `Browser` is a single value that is at once the `Binding.Service` tag, the
 * callable that produces a {@link BrowserBinding}, and the type. Declare it on a
 * Worker's `env` (it flows through `InferEnv` → `cf.BrowserRun`) or `yield*` it
 * inside an Effect-native Worker to attach the binding and obtain the
 * {@link BrowserClient}.
 *
 * ### Effect-style Worker (recommended)
 * **Example:** Bind the runtime client and convert a page to Markdown
 * ```typescript
 * import * as Effect from "effect/Effect";
 *
 * Cloudflare.Worker(
 *   "BrowserWorker",
 *   { main: import.meta.url },
 *   Effect.gen(function* () {
 *     const browser = yield* Cloudflare.Browser("BROWSER");
 *
 *     return {
 *       fetch: Effect.gen(function* () {
 *         return yield* browser.markdown({ url: "https://example.com" });
 *       }),
 *     };
 *   }).pipe(Effect.provide(Cloudflare.Workers.BrowserBinding)),
 * );
 * ```
 *
 * ### Worker binding metadata
 * **Example:** Declare the binding on `env`
 * ```typescript
 * export const Worker = Cloudflare.Worker("Worker", {
 *   main: "./src/worker.ts",
 *   env: { BROWSER: Cloudflare.Browser() },
 * });
 *
 * export type WorkerEnv = Cloudflare.InferEnv<typeof Worker>;
 * //   { BROWSER: BrowserRun }
 * ```
 *
 * ### Local development
 * **Example:** Proxy to the real Browser Rendering service in dev
 * ```typescript
 * // Default: a real headless Chrome is launched locally and driven over
 * // CDP under `alchemy dev`. Alchemy.remote() opts the binding into the
 * // real Browser Rendering service instead — in an Effect-native Worker:
 * const browser = yield* Cloudflare.Browser("BROWSER").pipe(Alchemy.remote());
 *
 * // or declared on an async Worker's env:
 * env: { BROWSER: Cloudflare.Browser("BROWSER").pipe(Alchemy.remote()) }
 * ```
 *
 * @see https://developers.cloudflare.com/browser-rendering/workers-binding-api/
 *
 * @binding
 * @product Browser Rendering
 * @category Developer Platform
 */
export interface Browser extends Binding.Service<Browser, TypeId, BrowserClient> {
  /**
   * @param name Binding name (logical id) — the `env` key it resolves to.
   * @default "BROWSER"
   */
  (name?: string): BrowserBinding;
}

export const Browser = Binding.Service<Browser>({
  id: TypeId,
  defaultName: "BROWSER",
  toWorkerBinding: (binding) => ({
    type: "browser",
    name: binding.name,
  }),
});

export const isBrowser = (value: unknown): value is BrowserBinding =>
  Binding.isBinding(value) && value.kind === TypeId;