RAG-1300: Add Web Search binding types

types/defines/web-search.d.ts

@@ -0,0 +1,101 @@
+// ============ Web Search Request Types ============
+
+/**
+ * Options for a Web Search query.
+ */
+export type WebSearchSearchOptions = {
+  /** The search query. */
+  query: string;
+  /**
+   * Maximum number of results to return. Defaults to 10, capped at 50.
+   * The actual count may be lower if fewer matches exist.
+   */
+  limit?: number;
+};
+
+// ============ Web Search Response Types ============
+
+/**
+ * A single Web Search result.
+ *
+ * Web Search is discovery-only -- results carry catalog metadata about a page
+ * but never the page body. To read a result's content the caller invokes the
+ * global `fetch()` API against the result's `url`, at which point the
+ * destination's own access controls apply (including Cloudflare Pay-per-Crawl).
+ */
+export type WebSearchResult = {
+  /** Canonical URL. */
+  url: string;
+  /** Page title. */
+  title: string;
+  /** Page-level description. May be absent. */
+  description?: string;
+  /** Result classification. Forward-compatible closed enum. */
+  type: 'web' | 'news';
+  /** Authors when extractable. */
+  authors?: string[];
+  /** Optional preview image URL. */
+  thumbnailUrl?: string;
+  /** Optional favicon URL for UI hints. */
+  faviconUrl?: string;
+};
+
+/**
+ * Per-response metadata for a Web Search query. Carries operational
+ * fields useful for support and debugging.
+ */
+export type WebSearchResponseMetadata = {
+  /** The query that was executed. */
+  query: string;
+  /** Opaque request identifier used for support and debugging. */
+  requestId: string;
+  /** End-to-end latency for this search request, in milliseconds. */
+  latencyMs: number;
+};
+
+/**
+ * Response from a Web Search query.
+ */
+export type WebSearchSearchResponse = {
+  results: WebSearchResult[];
+  metadata: WebSearchResponseMetadata;
+};
+
+// ============ Web Search Binding Class ============
+
+/**
+ * Cloudflare Web Search binding.
+ *
+ * Discovery-only primitive for agents and Workers. Returns URLs and catalog
+ * metadata for a query; never returns page content or excerpts. To read a
+ * result's body, fetch the URL with the global `fetch()` API.
+ *
+ * Declared in wrangler with a single object (there is exactly one corpus, the
+ * public web, so there is no name, namespace, or instance to specify):
+ *
+ * ```jsonc
+ * { "web_search": { "binding": "WEBSEARCH" } }
+ * ```
+ *
+ * @example
+ * ```ts
+ * const { results, metadata } = await env.WEBSEARCH.search({
+ *   query: "Cloudflare Workers",
+ * });
+ *
+ * const top = results[0];
+ * console.log(top.url, top.title, metadata.latencyMs);
+ *
+ * // Read content yourself; pay-per-crawl and other publisher
+ * // controls apply at the fetch site, not at search time.
+ * const page = await fetch(top.url);
+ * ```
+ */
+export declare abstract class WebSearch {
+  /**
+   * Run a Web Search query.
+   * @param options Search options. Only `query` is required.
+   * @returns The matching results plus per-response metadata.
+   */
+  search(options: WebSearchSearchOptions): Promise<WebSearchSearchResponse>;
+}

types/generated-snapshot/experimental/index.d.ts

@@ -3955,23 +3955,28 @@ interface ExecOutput {
   readonly stdout: ArrayBuffer;
   readonly stderr: ArrayBuffer;
   readonly exitCode: number;
+  readonly __stdoutp: ArrayBuffer;
+  readonly __stderrp: ArrayBuffer;
 }
 interface ContainerExecOptions {
   cwd?: string;
   env?: Record<string, string>;
   user?: string;
-  stdin?: ReadableStream | "pipe";
-  stdout?: "pipe" | "ignore";
-  stderr?: "pipe" | "ignore" | "combined";
+  __stdinp?: ReadableStream | "pipe";
+  __stdoutp?: "pipe" | "ignore";
+  __stderrp?: "pipe" | "ignore" | "combined";
 }
 interface ExecProcess {
-  readonly stdin: WritableStream | null;
-  readonly stdout: ReadableStream | null;
-  readonly stderr: ReadableStream | null;
+  get stdin(): WritableStream | undefined;
+  get stdout(): ReadableStream | undefined;
+  get stderr(): ReadableStream | undefined;
   readonly pid: number;
   readonly exitCode: Promise<number>;
   output(): Promise<ExecOutput>;
   kill(signal?: number): void;
+  readonly __stdinp: WritableStream | null;
+  readonly __stdoutp: ReadableStream | null;
+  readonly __stderrp: ReadableStream | null;
 }
 interface Container {
   get running(): boolean;
@@ -15210,6 +15215,100 @@ type WorkerVersionMetadata = {
   /** The timestamp of when the Worker Version was uploaded */
   timestamp: string;
 };
+// ============ Web Search Request Types ============
+/**
+ * Options for a Web Search query.
+ */
+type WebSearchSearchOptions = {
+  /** The search query. */
+  query: string;
+  /**
+   * Maximum number of results to return. Defaults to 10, capped at 50.
+   * The actual count may be lower if fewer matches exist.
+   */
+  limit?: number;
+};
+// ============ Web Search Response Types ============
+/**
+ * A single Web Search result.
+ *
+ * Web Search is discovery-only -- results carry catalog metadata about a page
+ * but never the page body. To read a result's content the caller invokes the
+ * global `fetch()` API against the result's `url`, at which point the
+ * destination's own access controls apply (including Cloudflare Pay-per-Crawl).
+ */
+type WebSearchResult = {
+  /** Canonical URL. */
+  url: string;
+  /** Page title. */
+  title: string;
+  /** Page-level description. May be absent. */
+  description?: string;
+  /** Result classification. Forward-compatible closed enum. */
+  type: "web" | "news";
+  /** Authors when extractable. */
+  authors?: string[];
+  /** Optional preview image URL. */
+  thumbnailUrl?: string;
+  /** Optional favicon URL for UI hints. */
+  faviconUrl?: string;
+};
+/**
+ * Per-response metadata for a Web Search query. Carries operational
+ * fields useful for support and debugging.
+ */
+type WebSearchResponseMetadata = {
+  /** The query that was executed. */
+  query: string;
+  /** Opaque request identifier used for support and debugging. */
+  requestId: string;
+  /** End-to-end latency for this search request, in milliseconds. */
+  latencyMs: number;
+};
+/**
+ * Response from a Web Search query.
+ */
+type WebSearchSearchResponse = {
+  results: WebSearchResult[];
+  metadata: WebSearchResponseMetadata;
+};
+// ============ Web Search Binding Class ============
+/**
+ * Cloudflare Web Search binding.
+ *
+ * Discovery-only primitive for agents and Workers. Returns URLs and catalog
+ * metadata for a query; never returns page content or excerpts. To read a
+ * result's body, fetch the URL with the global `fetch()` API.
+ *
+ * Declared in wrangler with a single object (there is exactly one corpus, the
+ * public web, so there is no name, namespace, or instance to specify):
+ *
+ * ```jsonc
+ * { "web_search": { "binding": "WEBSEARCH" } }
+ * ```
+ *
+ * @example
+ * ```ts
+ * const { results, metadata } = await env.WEBSEARCH.search({
+ *   query: "Cloudflare Workers",
+ * });
+ *
+ * const top = results[0];
+ * console.log(top.url, top.title, metadata.latencyMs);
+ *
+ * // Read content yourself; pay-per-crawl and other publisher
+ * // controls apply at the fetch site, not at search time.
+ * const page = await fetch(top.url);
+ * ```
+ */
+declare abstract class WebSearch {
+  /**
+   * Run a Web Search query.
+   * @param options Search options. Only `query` is required.
+   * @returns The matching results plus per-response metadata.
+   */
+  search(options: WebSearchSearchOptions): Promise<WebSearchSearchResponse>;
+}
 interface DynamicDispatchLimits {
   /**
    * Limit CPU time in milliseconds.

types/generated-snapshot/experimental/index.ts

@@ -3961,23 +3961,28 @@ export interface ExecOutput {
   readonly stdout: ArrayBuffer;
   readonly stderr: ArrayBuffer;
   readonly exitCode: number;
+  readonly __stdoutp: ArrayBuffer;
+  readonly __stderrp: ArrayBuffer;
 }
 export interface ContainerExecOptions {
   cwd?: string;
   env?: Record<string, string>;
   user?: string;
-  stdin?: ReadableStream | "pipe";
-  stdout?: "pipe" | "ignore";
-  stderr?: "pipe" | "ignore" | "combined";
+  __stdinp?: ReadableStream | "pipe";
+  __stdoutp?: "pipe" | "ignore";
+  __stderrp?: "pipe" | "ignore" | "combined";
 }
 export interface ExecProcess {
-  readonly stdin: WritableStream | null;
-  readonly stdout: ReadableStream | null;
-  readonly stderr: ReadableStream | null;
+  get stdin(): WritableStream | undefined;
+  get stdout(): ReadableStream | undefined;
+  get stderr(): ReadableStream | undefined;
   readonly pid: number;
   readonly exitCode: Promise<number>;
   output(): Promise<ExecOutput>;
   kill(signal?: number): void;
+  readonly __stdinp: WritableStream | null;
+  readonly __stdoutp: ReadableStream | null;
+  readonly __stderrp: ReadableStream | null;
 }
 export interface Container {
   get running(): boolean;
@@ -15167,6 +15172,100 @@ export type WorkerVersionMetadata = {
   /** The timestamp of when the Worker Version was uploaded */
   timestamp: string;
 };
+// ============ Web Search Request Types ============
+/**
+ * Options for a Web Search query.
+ */
+export type WebSearchSearchOptions = {
+  /** The search query. */
+  query: string;
+  /**
+   * Maximum number of results to return. Defaults to 10, capped at 50.
+   * The actual count may be lower if fewer matches exist.
+   */
+  limit?: number;
+};
+// ============ Web Search Response Types ============
+/**
+ * A single Web Search result.
+ *
+ * Web Search is discovery-only -- results carry catalog metadata about a page
+ * but never the page body. To read a result's content the caller invokes the
+ * global `fetch()` API against the result's `url`, at which point the
+ * destination's own access controls apply (including Cloudflare Pay-per-Crawl).
+ */
+export type WebSearchResult = {
+  /** Canonical URL. */
+  url: string;
+  /** Page title. */
+  title: string;
+  /** Page-level description. May be absent. */
+  description?: string;
+  /** Result classification. Forward-compatible closed enum. */
+  type: "web" | "news";
+  /** Authors when extractable. */
+  authors?: string[];
+  /** Optional preview image URL. */
+  thumbnailUrl?: string;
+  /** Optional favicon URL for UI hints. */
+  faviconUrl?: string;
+};
+/**
+ * Per-response metadata for a Web Search query. Carries operational
+ * fields useful for support and debugging.
+ */
+export type WebSearchResponseMetadata = {
+  /** The query that was executed. */
+  query: string;
+  /** Opaque request identifier used for support and debugging. */
+  requestId: string;
+  /** End-to-end latency for this search request, in milliseconds. */
+  latencyMs: number;
+};
+/**
+ * Response from a Web Search query.
+ */
+export type WebSearchSearchResponse = {
+  results: WebSearchResult[];
+  metadata: WebSearchResponseMetadata;
+};
+// ============ Web Search Binding Class ============
+/**
+ * Cloudflare Web Search binding.
+ *
+ * Discovery-only primitive for agents and Workers. Returns URLs and catalog
+ * metadata for a query; never returns page content or excerpts. To read a
+ * result's body, fetch the URL with the global `fetch()` API.
+ *
+ * Declared in wrangler with a single object (there is exactly one corpus, the
+ * public web, so there is no name, namespace, or instance to specify):
+ *
+ * ```jsonc
+ * { "web_search": { "binding": "WEBSEARCH" } }
+ * ```
+ *
+ * @example
+ * ```ts
+ * const { results, metadata } = await env.WEBSEARCH.search({
+ *   query: "Cloudflare Workers",
+ * });
+ *
+ * const top = results[0];
+ * console.log(top.url, top.title, metadata.latencyMs);
+ *
+ * // Read content yourself; pay-per-crawl and other publisher
+ * // controls apply at the fetch site, not at search time.
+ * const page = await fetch(top.url);
+ * ```
+ */
+export declare abstract class WebSearch {
+  /**
+   * Run a Web Search query.
+   * @param options Search options. Only `query` is required.
+   * @returns The matching results plus per-response metadata.
+   */
+  search(options: WebSearchSearchOptions): Promise<WebSearchSearchResponse>;
+}
 export interface DynamicDispatchLimits {
   /**
    * Limit CPU time in milliseconds.