From bc9c1b2489ecd38134ebf6be36a4f7772810c644 Mon Sep 17 00:00:00 2001 From: Gabriel Massadas Date: Mon, 18 May 2026 16:23:49 +0100 Subject: [PATCH] Add Web Search binding types Adds TypeScript type definitions for the new `web_search` binding kind: - WebSearch (abstract class with single `search()` method) - WebSearchSearchOptions (query + optional limit) - WebSearchResult (url, title, description?, type, authors?, thumbnailUrl?, faviconUrl?) - WebSearchSearchResponse (results + per-response metadata) The container types are named `WebSearchSearchOptions` / `WebSearchSearchResponse` to avoid a name collision with the pre-existing `WebSearchOptions` type in ai.d.ts (used by the OpenAI-compatible `web_search_options` field on Workers AI chat completions). Discovery-only by design: no `snippets`, `content`, or `scoringDetails` fields. Pay-per-Crawl alignment -- callers fetch URLs themselves via the global `fetch()` API if they need bodies. Includes regenerated generated-snapshot files for latest + experimental. --- types/defines/web-search.d.ts | 101 ++++++++++++++++ .../experimental/index.d.ts | 111 +++++++++++++++++- .../generated-snapshot/experimental/index.ts | 111 +++++++++++++++++- types/generated-snapshot/latest/index.d.ts | 94 +++++++++++++++ types/generated-snapshot/latest/index.ts | 94 +++++++++++++++ 5 files changed, 499 insertions(+), 12 deletions(-) create mode 100644 types/defines/web-search.d.ts diff --git a/types/defines/web-search.d.ts b/types/defines/web-search.d.ts new file mode 100644 index 00000000000..a64dad38b41 --- /dev/null +++ b/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; +} diff --git a/types/generated-snapshot/experimental/index.d.ts b/types/generated-snapshot/experimental/index.d.ts index 9528577967c..54c8693ffbd 100755 --- a/types/generated-snapshot/experimental/index.d.ts +++ b/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; 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; output(): Promise; 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; +} interface DynamicDispatchLimits { /** * Limit CPU time in milliseconds. diff --git a/types/generated-snapshot/experimental/index.ts b/types/generated-snapshot/experimental/index.ts index fccf25f209f..bd14b436035 100755 --- a/types/generated-snapshot/experimental/index.ts +++ b/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; 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; output(): Promise; 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; +} export interface DynamicDispatchLimits { /** * Limit CPU time in milliseconds. diff --git a/types/generated-snapshot/latest/index.d.ts b/types/generated-snapshot/latest/index.d.ts index ada160044bf..04a1bbbfb8c 100755 --- a/types/generated-snapshot/latest/index.d.ts +++ b/types/generated-snapshot/latest/index.d.ts @@ -14518,6 +14518,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; +} interface DynamicDispatchLimits { /** * Limit CPU time in milliseconds. diff --git a/types/generated-snapshot/latest/index.ts b/types/generated-snapshot/latest/index.ts index 54bd199b596..01cac9fc908 100755 --- a/types/generated-snapshot/latest/index.ts +++ b/types/generated-snapshot/latest/index.ts @@ -14475,6 +14475,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; +} export interface DynamicDispatchLimits { /** * Limit CPU time in milliseconds.