diff --git a/.changeset/ai-search-plugin.md b/.changeset/ai-search-plugin.md new file mode 100644 index 0000000000..80de61dcad --- /dev/null +++ b/.changeset/ai-search-plugin.md @@ -0,0 +1,5 @@ +--- +"@emdash-cms/cloudflare": minor +--- + +Adds a Cloudflare AI Search plugin with automatic content indexing, cron-driven reindexing, language-aware queries, synonyms, index status, admin configuration, and an Astro search component with the browser snippet included. diff --git a/demos/cloudflare/astro.config.mjs b/demos/cloudflare/astro.config.mjs index a349f89745..d642415079 100644 --- a/demos/cloudflare/astro.config.mjs +++ b/demos/cloudflare/astro.config.mjs @@ -10,6 +10,7 @@ import { cloudflareImages, cloudflareStream, } from "@emdash-cms/cloudflare"; +import { aiSearch } from "@emdash-cms/cloudflare/plugins"; import { formsPlugin } from "@emdash-cms/plugin-forms"; import webhookNotifier from "@emdash-cms/plugin-webhook-notifier"; import { defineConfig, fontProviders } from "astro/config"; @@ -72,6 +73,19 @@ export default defineConfig({ plugins: [ // Test plugin that exercises all v2 APIs formsPlugin(), + aiSearch({ + // AI Search instance name (created on first index). Default: "emdash-content". + instanceName: "emdash-content", + // wrangler.jsonc `ai_search_namespaces` binding name. Default: "AI_SEARCH". + binding: "AI_SEARCH", + // Hybrid search (vector + keyword). Default: true. + hybridSearch: true, + // Public result URLs returned to the AI Search snippet. + urlTemplates: { + posts: "/posts/{slug}?lang={locale}", + pages: "/pages/{slug}?lang={locale}", + }, + }), ], // Sandboxed plugins (run in isolated workers) sandboxed: [webhookNotifier], diff --git a/demos/cloudflare/package.json b/demos/cloudflare/package.json index 0459fa6213..82047e5080 100644 --- a/demos/cloudflare/package.json +++ b/demos/cloudflare/package.json @@ -15,6 +15,7 @@ "dependencies": { "@astrojs/cloudflare": "catalog:", "@astrojs/react": "catalog:", + "@cloudflare/ai-search-snippet": "^0.0.40", "@emdash-cms/cloudflare": "workspace:*", "@emdash-cms/plugin-forms": "workspace:*", "@emdash-cms/plugin-webhook-notifier": "workspace:*", diff --git a/demos/cloudflare/src/layouts/Base.astro b/demos/cloudflare/src/layouts/Base.astro index df078d8c05..380a6e298b 100644 --- a/demos/cloudflare/src/layouts/Base.astro +++ b/demos/cloudflare/src/layouts/Base.astro @@ -7,7 +7,6 @@ import { EmDashBodyEnd, } from "emdash/ui"; import { createPublicPageContext } from "emdash/page"; -import LiveSearch from "emdash/ui/search"; import { Font } from "astro:assets"; import { resolveBlogSiteIdentity } from "../utils/site-identity"; import "../styles/theme.css"; @@ -23,7 +22,6 @@ interface Props { publishedTime?: string | null; modifiedTime?: string | null; author?: string | null; - /** Pass content reference for plugin page contributions on content pages */ content?: { collection: string; id: string; slug?: string | null }; } @@ -41,22 +39,14 @@ const { content, } = Astro.props; const { siteTitle, siteTagline, siteLogo } = resolveBlogSiteIdentity(await getSiteSettings()); -// If title already includes site title (from getSeoMeta), use as-is const fullTitle = title.includes(siteTitle) ? title : `${title} — ${siteTitle}`; -// Fetch primary menu defined in seed const menu = await getMenu("primary"); -// Optional "social" menu. If a site defines a `social` menu in its seed, -// it'll render in the footer's "Connect" column. Otherwise that column -// just shows RSS, avoiding duplication with the "Navigate" column above. const socialMenu = await getMenu("social"); -// Fetch pages for footer const { entries: pages } = await getEmDashCollection("pages"); -// Build public page context for plugin contributions -// SEO data is passed here and rendered securely by EmDashHead const pageCtx = createPublicPageContext({ Astro, kind: content ? "content" : "custom", @@ -72,7 +62,6 @@ const pageCtx = createPublicPageContext({ siteName: siteTitle, }); -// Check if user is logged in (for showing admin link) const isLoggedIn = !!Astro.locals.user; --- @@ -110,14 +99,24 @@ const isLoggedIn = !!Astro.locals.user; }
- + +
{ menu?.items.map((item) => ( @@ -281,7 +280,6 @@ const isLoggedIn = !!Astro.locals.user; diff --git a/demos/cloudflare/src/pages/api/ai-search/search.ts b/demos/cloudflare/src/pages/api/ai-search/search.ts new file mode 100644 index 0000000000..8024dc25b1 --- /dev/null +++ b/demos/cloudflare/src/pages/api/ai-search/search.ts @@ -0,0 +1 @@ +export { POST, prerender } from "@emdash-cms/cloudflare/plugins/ai-search"; diff --git a/demos/cloudflare/src/pages/search.astro b/demos/cloudflare/src/pages/search.astro deleted file mode 100644 index 98e8a4e758..0000000000 --- a/demos/cloudflare/src/pages/search.astro +++ /dev/null @@ -1,182 +0,0 @@ ---- -export const prerender = false; - -import { search } from "emdash"; -import Base from "../layouts/Base.astro"; - -const query = Astro.url.searchParams.get("q")?.trim() || ""; - -// Use the FTS-backed search() API instead of loading every post and -// filtering in JS. FTS scales as the post count grows, returns ranked -// results, and handles tokenization/stemming. Templates that grep all -// post bodies in JS quickly become unusable past a few hundred posts. -const { items: results } = query - ? await search(query, { collections: ["posts"], limit: 30 }) - : { items: [] }; ---- - - -
-

Search

- -
- - -
- - { - query && ( -

- {results.length === 0 - ? `No results for "${query}"` - : `${results.length} result${results.length === 1 ? "" : "s"} for "${query}"`} -

- ) - } - - { - results.length > 0 && ( -
    - {results.map((result) => ( -
  1. - -

    - {result.title ?? "Untitled"} -

    - {result.snippet && ( -

    - )} - -

    2. - ))} -
- ) - } - - {!query &&

Enter a search term to find posts.

} -
- - - diff --git a/demos/cloudflare/src/worker.ts b/demos/cloudflare/src/worker.ts index 37f44345bd..d154c752d9 100644 --- a/demos/cloudflare/src/worker.ts +++ b/demos/cloudflare/src/worker.ts @@ -7,12 +7,11 @@ */ import handler from "@astrojs/cloudflare/entrypoints/server"; +import { createScheduledHandler, PluginBridge } from "@emdash-cms/cloudflare/worker"; -// Re-export PluginBridge from the cloudflare sandbox runtime -// This makes it available via ctx.exports.PluginBridge -export { PluginBridge } from "@emdash-cms/cloudflare/sandbox"; +export { PluginBridge }; -/** - * Default export - just re-export the Astro handler - */ -export default handler; +export default { + ...handler, + scheduled: createScheduledHandler(), +} satisfies ExportedHandler; diff --git a/demos/cloudflare/worker-configuration.d.ts b/demos/cloudflare/worker-configuration.d.ts index 629f0c7371..6603007357 100644 --- a/demos/cloudflare/worker-configuration.d.ts +++ b/demos/cloudflare/worker-configuration.d.ts @@ -1,6 +1,6 @@ /* eslint-disable */ -// Generated by Wrangler by running `wrangler types` (hash: 9c265de5f60dc95e990b3e1fb3254e99) -// Runtime types generated with workerd@1.20260205.0 2026-01-14 disable_nodejs_process_v2,nodejs_compat +// Generated by Wrangler by running `wrangler types` (hash: 7157f5986bd33a0a4daf3c50515c3bdc) +// Runtime types generated with workerd@1.20260401.1 2026-01-14 disable_nodejs_process_v2,nodejs_compat declare namespace Cloudflare { interface GlobalProps { mainModule: typeof import("./src/worker"); @@ -9,20 +9,10 @@ declare namespace Cloudflare { MEDIA: R2Bucket; DB: D1Database; LOADER: WorkerLoader; - CF_ACCESS_AUDIENCE: string; - CF_MEDIA_API_TOKEN: string; - CF_MEDIA_ACCOUNT_ID: string; + AI_SEARCH: AiSearchNamespace; } } interface Env extends Cloudflare.Env {} -type StringifyValues> = { - [Binding in keyof EnvType]: EnvType[Binding] extends string ? EnvType[Binding] : string; -}; -declare namespace NodeJS { - interface ProcessEnv extends StringifyValues< - Pick - > {} -} // Begin runtime types /*! ***************************************************************************** @@ -486,50 +476,61 @@ interface ExecutionContext { readonly exports: Cloudflare.Exports; readonly props: Props; } -type ExportedHandlerFetchHandler = ( +type ExportedHandlerFetchHandler = ( request: Request>, env: Env, - ctx: ExecutionContext, + ctx: ExecutionContext, ) => Response | Promise; -type ExportedHandlerTailHandler = ( +type ExportedHandlerConnectHandler = ( + socket: Socket, + env: Env, + ctx: ExecutionContext, +) => void | Promise; +type ExportedHandlerTailHandler = ( events: TraceItem[], env: Env, - ctx: ExecutionContext, + ctx: ExecutionContext, ) => void | Promise; -type ExportedHandlerTraceHandler = ( +type ExportedHandlerTraceHandler = ( traces: TraceItem[], env: Env, - ctx: ExecutionContext, + ctx: ExecutionContext, ) => void | Promise; -type ExportedHandlerTailStreamHandler = ( +type ExportedHandlerTailStreamHandler = ( event: TailStream.TailEvent, env: Env, - ctx: ExecutionContext, + ctx: ExecutionContext, ) => TailStream.TailEventHandlerType | Promise; -type ExportedHandlerScheduledHandler = ( +type ExportedHandlerScheduledHandler = ( controller: ScheduledController, env: Env, - ctx: ExecutionContext, + ctx: ExecutionContext, ) => void | Promise; -type ExportedHandlerQueueHandler = ( +type ExportedHandlerQueueHandler = ( batch: MessageBatch, env: Env, - ctx: ExecutionContext, + ctx: ExecutionContext, ) => void | Promise; -type ExportedHandlerTestHandler = ( +type ExportedHandlerTestHandler = ( controller: TestController, env: Env, - ctx: ExecutionContext, + ctx: ExecutionContext, ) => void | Promise; -interface ExportedHandler { - fetch?: ExportedHandlerFetchHandler; - tail?: ExportedHandlerTailHandler; - trace?: ExportedHandlerTraceHandler; - tailStream?: ExportedHandlerTailStreamHandler; - scheduled?: ExportedHandlerScheduledHandler; - test?: ExportedHandlerTestHandler; - email?: EmailExportedHandler; - queue?: ExportedHandlerQueueHandler; +interface ExportedHandler< + Env = unknown, + QueueHandlerMessage = unknown, + CfHostMetadata = unknown, + Props = unknown, +> { + fetch?: ExportedHandlerFetchHandler; + connect?: ExportedHandlerConnectHandler; + tail?: ExportedHandlerTailHandler; + trace?: ExportedHandlerTraceHandler; + tailStream?: ExportedHandlerTailStreamHandler; + scheduled?: ExportedHandlerScheduledHandler; + test?: ExportedHandlerTestHandler; + email?: EmailExportedHandler; + queue?: ExportedHandlerQueueHandler; } interface StructuredSerializeOptions { transfer?: any[]; @@ -544,12 +545,14 @@ declare abstract class Navigator { interface AlarmInvocationInfo { readonly isRetry: boolean; readonly retryCount: number; + readonly scheduledTime: number; } interface Cloudflare { readonly compatibilityFlags: Record; } interface DurableObject { fetch(request: Request): Response | Promise; + connect?(socket: Socket): void | Promise; alarm?(alarmInfo?: AlarmInvocationInfo): void | Promise; webSocketMessage?(ws: WebSocket, message: string | ArrayBuffer): void | Promise; webSocketClose?( @@ -562,7 +565,7 @@ interface DurableObject { } type DurableObjectStub = Fetcher< T, - "alarm" | "webSocketMessage" | "webSocketClose" | "webSocketError" + "alarm" | "connect" | "webSocketMessage" | "webSocketClose" | "webSocketError" > & { readonly id: DurableObjectId; readonly name?: string; @@ -571,6 +574,7 @@ interface DurableObjectId { toString(): string; equals(other: DurableObjectId): boolean; readonly name?: string; + readonly jurisdiction?: string; } declare abstract class DurableObjectNamespace< T extends Rpc.DurableObjectBranded | undefined = undefined, @@ -2916,6 +2920,11 @@ interface QueuingStrategyInit { */ highWaterMark: number; } +interface TracePreviewInfo { + id: string; + slug: string; + name: string; +} interface ScriptVersion { id?: string; tag?: string; @@ -2930,6 +2939,7 @@ interface TraceItem { | ( | TraceItemFetchEventInfo | TraceItemJsRpcEventInfo + | TraceItemConnectEventInfo | TraceItemScheduledEventInfo | TraceItemAlarmEventInfo | TraceItemQueueEventInfo @@ -2948,6 +2958,8 @@ interface TraceItem { readonly scriptVersion?: ScriptVersion; readonly dispatchNamespace?: string; readonly scriptTags?: string[]; + readonly tailAttributes?: Record; + readonly preview?: TracePreviewInfo; readonly durableObjectId?: string; readonly outcome: string; readonly executionModel: string; @@ -2958,6 +2970,7 @@ interface TraceItem { interface TraceItemAlarmEventInfo { readonly scheduledTime: Date; } +interface TraceItemConnectEventInfo {} interface TraceItemCustomEventInfo {} interface TraceItemScheduledEventInfo { readonly scheduledTime: number; @@ -3383,7 +3396,7 @@ declare var WebSocket: { * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WebSocket) */ interface WebSocket extends EventTarget { - accept(): void; + accept(options?: WebSocketAcceptOptions): void; /** * The **`WebSocket.send()`** method enqueues the specified data to be transmitted to the server over the WebSocket connection, increasing the value of `bufferedAmount` by the number of bytes needed to contain the data. * @@ -3422,6 +3435,22 @@ interface WebSocket extends EventTarget { * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WebSocket/extensions) */ extensions: string | null; + /** + * The **`WebSocket.binaryType`** property controls the type of binary data being received over the WebSocket connection. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WebSocket/binaryType) + */ + binaryType: "blob" | "arraybuffer"; +} +interface WebSocketAcceptOptions { + /** + * When set to `true`, receiving a server-initiated WebSocket Close frame will not + * automatically send a reciprocal Close frame, leaving the connection in a half-open + * state. This is useful for proxying scenarios where you need to coordinate closing + * both sides independently. Defaults to `false` when the + * `no_web_socket_half_open_by_default` compatibility flag is enabled. + */ + allowHalfOpen?: boolean; } declare const WebSocketPair: { new (): { @@ -3544,12 +3573,42 @@ interface Container { signal(signo: number): void; getTcpPort(port: number): Fetcher; setInactivityTimeout(durationMs: number | bigint): Promise; + interceptOutboundHttp(addr: string, binding: Fetcher): Promise; + interceptAllOutboundHttp(binding: Fetcher): Promise; + snapshotDirectory( + options: ContainerDirectorySnapshotOptions, + ): Promise; + snapshotContainer(options: ContainerSnapshotOptions): Promise; +} +interface ContainerDirectorySnapshot { + id: string; + size: number; + dir: string; + name?: string; +} +interface ContainerDirectorySnapshotOptions { + dir: string; + name?: string; +} +interface ContainerDirectorySnapshotRestoreParams { + snapshot: ContainerDirectorySnapshot; + mountPoint?: string; +} +interface ContainerSnapshot { + id: string; + size: number; + name?: string; +} +interface ContainerSnapshotOptions { + name?: string; } interface ContainerStartupOptions { entrypoint?: string[]; enableInternet: boolean; env?: Record; - hardTimeout?: number | bigint; + labels?: Record; + directorySnapshots?: ContainerDirectorySnapshotRestoreParams[]; + containerSnapshot?: ContainerSnapshot; } /** * The **`MessagePort`** interface of the Channel Messaging API represents one of the two ports of a MessageChannel, allowing messages to be sent from one port and listening out for them arriving at the other. @@ -3651,6 +3710,7 @@ interface WorkerLoader { name: string | null, getCode: () => WorkerLoaderWorkerCode | Promise, ): WorkerStub; + load(code: WorkerLoaderWorkerCode): WorkerStub; } interface WorkerLoaderModule { js?: string; @@ -3683,6 +3743,463 @@ declare abstract class Performance { get timeOrigin(): number; /* [Cloudflare Docs Reference](https://developers.cloudflare.com/workers/runtime-apis/performance/#performancenow) */ now(): number; + /** + * The **`toJSON()`** method of the Performance interface is a Serialization; it returns a JSON representation of the Performance object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Performance/toJSON) + */ + toJSON(): object; +} +// ============ AI Search Error Interfaces ============ +interface AiSearchInternalError extends Error {} +interface AiSearchNotFoundError extends Error {} +// ============ AI Search Request Types ============ +type AiSearchSearchRequest = { + messages: Array<{ + role: "system" | "developer" | "user" | "assistant" | "tool"; + content: string | null; + }>; + ai_search_options?: { + retrieval?: { + retrieval_type?: "vector" | "keyword" | "hybrid"; + /** Match threshold (0-1, default 0.4) */ + match_threshold?: number; + /** Maximum number of results (1-50, default 10) */ + max_num_results?: number; + filters?: VectorizeVectorMetadataFilter; + /** Context expansion (0-3, default 0) */ + context_expansion?: number; + [key: string]: unknown; + }; + query_rewrite?: { + enabled?: boolean; + model?: string; + rewrite_prompt?: string; + [key: string]: unknown; + }; + reranking?: { + enabled?: boolean; + model?: "@cf/baai/bge-reranker-base" | string; + /** Match threshold (0-1, default 0.4) */ + match_threshold?: number; + [key: string]: unknown; + }; + [key: string]: unknown; + }; +}; +type AiSearchChatCompletionsRequest = { + messages: Array<{ + role: "system" | "developer" | "user" | "assistant" | "tool"; + content: string | null; + [key: string]: unknown; + }>; + model?: string; + stream?: boolean; + ai_search_options?: { + retrieval?: { + retrieval_type?: "vector" | "keyword" | "hybrid"; + match_threshold?: number; + max_num_results?: number; + filters?: VectorizeVectorMetadataFilter; + context_expansion?: number; + [key: string]: unknown; + }; + query_rewrite?: { + enabled?: boolean; + model?: string; + rewrite_prompt?: string; + [key: string]: unknown; + }; + reranking?: { + enabled?: boolean; + model?: "@cf/baai/bge-reranker-base" | string; + match_threshold?: number; + [key: string]: unknown; + }; + [key: string]: unknown; + }; + [key: string]: unknown; +}; +// ============ AI Search Response Types ============ +type AiSearchSearchResponse = { + search_query: string; + chunks: Array<{ + id: string; + type: string; + /** Match score (0-1) */ + score: number; + text: string; + item: { + timestamp?: number; + key: string; + metadata?: Record; + }; + scoring_details?: { + /** Keyword match score (0-1) */ + keyword_score?: number; + /** Vector similarity score (0-1) */ + vector_score?: number; + [key: string]: unknown; + }; + }>; +}; +type AiSearchChatCompletionsResponse = { + id?: string; + object?: string; + model?: string; + choices: Array<{ + index?: number; + message: { + role: "system" | "developer" | "user" | "assistant" | "tool"; + content: string | null; + [key: string]: unknown; + }; + [key: string]: unknown; + }>; + chunks: AiSearchSearchResponse["chunks"]; + [key: string]: unknown; +}; +type AiSearchStatsResponse = { + queued?: number; + running?: number; + completed?: number; + error?: number; + skipped?: number; + outdated?: number; + last_activity?: string; +}; +// ============ AI Search Instance Info Types ============ +type AiSearchInstanceInfo = { + id: string; + type?: "r2" | "web-crawler" | string; + source?: string; + paused?: boolean; + status?: string; + namespace?: string; + created_at?: string; + modified_at?: string; + [key: string]: unknown; +}; +type AiSearchListResponse = { + result: AiSearchInstanceInfo[]; + result_info?: { + count: number; + page: number; + per_page: number; + total_count: number; + }; +}; +// ============ AI Search Config Types ============ +type AiSearchConfig = { + /** Instance ID (1-32 chars, pattern: ^[a-z0-9_]+(?:-[a-z0-9_]+)*$) */ + id: string; + /** Instance type. Omit to create with built-in storage. */ + type?: "r2" | "web-crawler" | string; + /** Source URL (required for web-crawler type). */ + source?: string; + source_params?: unknown; + /** Token ID (UUID format) */ + token_id?: string; + ai_gateway_id?: string; + /** Enable query rewriting (default false) */ + rewrite_query?: boolean; + /** Enable reranking (default false) */ + reranking?: boolean; + embedding_model?: string; + ai_search_model?: string; + [key: string]: unknown; +}; +// ============ AI Search Item Types ============ +type AiSearchItemInfo = { + id: string; + key: string; + status: "completed" | "error" | "skipped" | "queued" | "processing" | "outdated"; + metadata?: Record; + [key: string]: unknown; +}; +type AiSearchItemContentResult = { + body: ReadableStream; + contentType: string; + filename: string; + size: number; +}; +type AiSearchUploadItemOptions = { + metadata?: Record; +}; +type AiSearchListItemsParams = { + page?: number; + per_page?: number; +}; +type AiSearchListItemsResponse = { + result: AiSearchItemInfo[]; + result_info?: { + count: number; + page: number; + per_page: number; + total_count: number; + }; +}; +// ============ AI Search Job Types ============ +type AiSearchJobInfo = { + id: string; + source: "user" | "schedule"; + description?: string; + last_seen_at?: string; + started_at?: string; + ended_at?: string; + end_reason?: string; +}; +type AiSearchJobLog = { + id: number; + message: string; + message_type: number; + created_at: number; +}; +type AiSearchCreateJobParams = { + description?: string; +}; +type AiSearchListJobsParams = { + page?: number; + per_page?: number; +}; +type AiSearchListJobsResponse = { + result: AiSearchJobInfo[]; + result_info?: { + count: number; + page: number; + per_page: number; + total_count: number; + }; +}; +type AiSearchJobLogsParams = { + page?: number; + per_page?: number; +}; +type AiSearchJobLogsResponse = { + result: AiSearchJobLog[]; + result_info?: { + count: number; + page: number; + per_page: number; + total_count: number; + }; +}; +// ============ AI Search Sub-Service Classes ============ +/** + * Single item service for an AI Search instance. + * Provides info, delete, and download operations on a specific item. + */ +declare abstract class AiSearchItem { + /** Get metadata about this item. */ + info(): Promise; + /** + * Download the item's content. + * @returns Object with body stream, content type, filename, and size. + */ + download(): Promise; +} +/** + * Items collection service for an AI Search instance. + * Provides list, upload, and access to individual items. + */ +declare abstract class AiSearchItems { + /** List items in this instance. */ + list(params?: AiSearchListItemsParams): Promise; + /** + * Upload a file as an item. + * @param name Filename for the uploaded item. + * @param content File content as a ReadableStream, ArrayBuffer, or string. + * @param options Optional metadata to attach to the item. + * @returns The created item info. + */ + upload( + name: string, + content: ReadableStream | ArrayBuffer | string, + options?: AiSearchUploadItemOptions, + ): Promise; + /** + * Upload a file and poll until processing completes. + * @param name Filename for the uploaded item. + * @param content File content as a ReadableStream, ArrayBuffer, or string. + * @param options Optional metadata to attach to the item. + * @returns The item info after processing completes (or timeout). + */ + uploadAndPoll( + name: string, + content: ReadableStream | ArrayBuffer | string, + options?: AiSearchUploadItemOptions, + ): Promise; + /** + * Get an item by ID. + * @param itemId The item identifier. + * @returns Item service for info, delete, and download operations. + */ + get(itemId: string): AiSearchItem; + /** Delete this item from the instance. + * @param itemId The item identifier. + */ + delete(itemId: string): Promise; +} +/** + * Single job service for an AI Search instance. + * Provides info and logs for a specific job. + */ +declare abstract class AiSearchJob { + /** Get metadata about this job. */ + info(): Promise; + /** Get logs for this job. */ + logs(params?: AiSearchJobLogsParams): Promise; +} +/** + * Jobs collection service for an AI Search instance. + * Provides list, create, and access to individual jobs. + */ +declare abstract class AiSearchJobs { + /** List jobs for this instance. */ + list(params?: AiSearchListJobsParams): Promise; + /** + * Create a new indexing job. + * @param params Optional job parameters. + * @returns The created job info. + */ + create(params?: AiSearchCreateJobParams): Promise; + /** + * Get a job by ID. + * @param jobId The job identifier. + * @returns Job service for info and logs operations. + */ + get(jobId: string): AiSearchJob; +} +// ============ AI Search Binding Classes ============ +/** + * Instance-level AI Search service. + * + * Used as: + * - The return type of `AiSearchNamespace.get(name)` (namespace binding) + * - The type of `env.BLOG_SEARCH` (single instance binding via `ai_search`) + * + * Provides search, chat, update, stats, items, and jobs operations. + * + * @example + * ```ts + * // Via namespace binding + * const instance = env.AI_SEARCH.get("blog"); + * const results = await instance.search({ + * messages: [{ role: "user", content: "How does caching work?" }], + * }); + * + * // Via single instance binding + * const results = await env.BLOG_SEARCH.search({ + * messages: [{ role: "user", content: "How does caching work?" }], + * }); + * ``` + */ +declare abstract class AiSearchInstance { + /** + * Search the AI Search instance for relevant chunks. + * @param params Search request with messages and optional AI search options. + * @returns Search response with matching chunks and search query. + */ + search(params: AiSearchSearchRequest): Promise; + /** + * Generate chat completions with AI Search context (streaming). + * @param params Chat completions request with stream: true. + * @returns ReadableStream of server-sent events. + */ + chatCompletions( + params: AiSearchChatCompletionsRequest & { + stream: true; + }, + ): Promise; + /** + * Generate chat completions with AI Search context. + * @param params Chat completions request. + * @returns Chat completion response with choices and RAG chunks. + */ + chatCompletions(params: AiSearchChatCompletionsRequest): Promise; + /** + * Update the instance configuration. + * @param config Partial configuration to update. + * @returns Updated instance info. + */ + update(config: Partial): Promise; + /** Get metadata about this instance. */ + info(): Promise; + /** + * Get instance statistics (item count, indexing status, etc.). + * @returns Statistics with counts per status and last activity time. + */ + stats(): Promise; + /** Items collection — list, upload, and manage items in this instance. */ + get items(): AiSearchItems; + /** Jobs collection — list, create, and inspect indexing jobs. */ + get jobs(): AiSearchJobs; +} +/** + * Namespace-level AI Search service. + * + * Used as the type of `env.AI_SEARCH` (namespace binding via `ai_search_namespaces`). + * Scoped to a single namespace. Provides dynamic instance access, creation, and deletion. + * + * @example + * ```ts + * // Access an instance within the namespace + * const blog = env.AI_SEARCH.get("blog"); + * const results = await blog.search({ + * messages: [{ role: "user", content: "How does caching work?" }], + * }); + * + * // List all instances in the namespace + * const instances = await env.AI_SEARCH.list(); + * + * // Create a new instance with built-in storage + * const tenant = await env.AI_SEARCH.create({ + * id: "tenant-123", + * }); + * + * // Upload items into the instance + * await tenant.items.upload("doc.pdf", fileContent); + * + * // Delete an instance + * await env.AI_SEARCH.delete("tenant-123"); + * ``` + */ +declare abstract class AiSearchNamespace { + /** + * Get an instance by name within the bound namespace. + * @param name Instance name. + * @returns Instance service for search, chat, update, stats, items, and jobs. + */ + get(name: string): AiSearchInstance; + /** + * List all instances in the bound namespace. + * @returns Array of instance metadata. + */ + list(): Promise; + /** + * Create a new instance within the bound namespace. + * @param config Instance configuration. Only `id` is required — omit `type` and `source` to create with built-in storage. + * @returns Instance service for the newly created instance. + * + * @example + * ```ts + * // Create with built-in storage (upload items manually) + * const instance = await env.AI_SEARCH.create({ id: "my-search" }); + * + * // Create with web crawler source + * const instance = await env.AI_SEARCH.create({ + * id: "docs-search", + * type: "web-crawler", + * source: "https://developers.cloudflare.com", + * }); + * ``` + */ + create(config: AiSearchConfig): Promise; + /** + * Delete an instance from the bound namespace. + * @param name Instance name to delete. + */ + delete(name: string): Promise; } type AiImageClassificationInput = { image: number[]; @@ -3953,98 +4470,487 @@ declare abstract class BaseAiTranslation { postProcessedOutputs: AiTranslationOutput; } /** - * Workers AI support for OpenAI's Responses API - * Reference: https://github.com/openai/openai-node/blob/master/src/resources/responses/responses.ts - * - * It's a stripped down version from its source. - * It currently supports basic function calling, json mode and accepts images as input. - * - * It does not include types for WebSearch, CodeInterpreter, FileInputs, MCP, CustomTools. - * We plan to add those incrementally as model + platform capabilities evolve. + * Workers AI support for OpenAI's Chat Completions API */ -type ResponsesInput = { - background?: boolean | null; - conversation?: string | ResponseConversationParam | null; - include?: Array | null; - input?: string | ResponseInput; - instructions?: string | null; - max_output_tokens?: number | null; - parallel_tool_calls?: boolean | null; - previous_response_id?: string | null; - prompt_cache_key?: string; - reasoning?: Reasoning | null; - safety_identifier?: string; - service_tier?: "auto" | "default" | "flex" | "scale" | "priority" | null; - stream?: boolean | null; - stream_options?: StreamOptions | null; - temperature?: number | null; - text?: ResponseTextConfig; - tool_choice?: ToolChoiceOptions | ToolChoiceFunction; - tools?: Array; - top_p?: number | null; - truncation?: "auto" | "disabled" | null; +type ChatCompletionContentPartText = { + type: "text"; + text: string; }; -type ResponsesOutput = { - id?: string; - created_at?: number; - output_text?: string; - error?: ResponseError | null; - incomplete_details?: ResponseIncompleteDetails | null; - instructions?: string | Array | null; - object?: "response"; - output?: Array; - parallel_tool_calls?: boolean; - temperature?: number | null; - tool_choice?: ToolChoiceOptions | ToolChoiceFunction; - tools?: Array; - top_p?: number | null; - max_output_tokens?: number | null; - previous_response_id?: string | null; - prompt?: ResponsePrompt | null; - reasoning?: Reasoning | null; - safety_identifier?: string; - service_tier?: "auto" | "default" | "flex" | "scale" | "priority" | null; - status?: ResponseStatus; - text?: ResponseTextConfig; - truncation?: "auto" | "disabled" | null; - usage?: ResponseUsage; +type ChatCompletionContentPartImage = { + type: "image_url"; + image_url: { + url: string; + detail?: "auto" | "low" | "high"; + }; }; -type EasyInputMessage = { - content: string | ResponseInputMessageContentList; - role: "user" | "assistant" | "system" | "developer"; - type?: "message"; +type ChatCompletionContentPartInputAudio = { + type: "input_audio"; + input_audio: { + /** Base64 encoded audio data. */ + data: string; + format: "wav" | "mp3"; + }; }; -type ResponsesFunctionTool = { +type ChatCompletionContentPartFile = { + type: "file"; + file: { + /** Base64 encoded file data. */ + file_data?: string; + /** The ID of an uploaded file. */ + file_id?: string; + filename?: string; + }; +}; +type ChatCompletionContentPartRefusal = { + type: "refusal"; + refusal: string; +}; +type ChatCompletionContentPart = + | ChatCompletionContentPartText + | ChatCompletionContentPartImage + | ChatCompletionContentPartInputAudio + | ChatCompletionContentPartFile; +type FunctionDefinition = { name: string; - parameters: { - [key: string]: unknown; - } | null; - strict: boolean | null; + description?: string; + parameters?: Record; + strict?: boolean | null; +}; +type ChatCompletionFunctionTool = { type: "function"; - description?: string | null; + function: FunctionDefinition; }; -type ResponseIncompleteDetails = { - reason?: "max_output_tokens" | "content_filter"; +type ChatCompletionCustomToolGrammarFormat = { + type: "grammar"; + grammar: { + definition: string; + syntax: "lark" | "regex"; + }; }; -type ResponsePrompt = { - id: string; - variables?: { - [key: string]: string | ResponseInputText | ResponseInputImage; - } | null; - version?: string | null; +type ChatCompletionCustomToolTextFormat = { + type: "text"; }; -type Reasoning = { - effort?: ReasoningEffort | null; - generate_summary?: "auto" | "concise" | "detailed" | null; - summary?: "auto" | "concise" | "detailed" | null; +type ChatCompletionCustomToolFormat = + | ChatCompletionCustomToolTextFormat + | ChatCompletionCustomToolGrammarFormat; +type ChatCompletionCustomTool = { + type: "custom"; + custom: { + name: string; + description?: string; + format?: ChatCompletionCustomToolFormat; + }; }; -type ResponseContent = - | ResponseInputText - | ResponseInputImage - | ResponseOutputText - | ResponseOutputRefusal - | ResponseContentReasoningText; -type ResponseContentReasoningText = { +type ChatCompletionTool = ChatCompletionFunctionTool | ChatCompletionCustomTool; +type ChatCompletionMessageFunctionToolCall = { + id: string; + type: "function"; + function: { + name: string; + /** JSON-encoded arguments string. */ + arguments: string; + }; +}; +type ChatCompletionMessageCustomToolCall = { + id: string; + type: "custom"; + custom: { + name: string; + input: string; + }; +}; +type ChatCompletionMessageToolCall = + | ChatCompletionMessageFunctionToolCall + | ChatCompletionMessageCustomToolCall; +type ChatCompletionToolChoiceFunction = { + type: "function"; + function: { + name: string; + }; +}; +type ChatCompletionToolChoiceCustom = { + type: "custom"; + custom: { + name: string; + }; +}; +type ChatCompletionToolChoiceAllowedTools = { + type: "allowed_tools"; + allowed_tools: { + mode: "auto" | "required"; + tools: Array>; + }; +}; +type ChatCompletionToolChoiceOption = + | "none" + | "auto" + | "required" + | ChatCompletionToolChoiceFunction + | ChatCompletionToolChoiceCustom + | ChatCompletionToolChoiceAllowedTools; +type DeveloperMessage = { + role: "developer"; + content: + | string + | Array<{ + type: "text"; + text: string; + }>; + name?: string; +}; +type SystemMessage = { + role: "system"; + content: + | string + | Array<{ + type: "text"; + text: string; + }>; + name?: string; +}; +/** + * Permissive merged content part used inside UserMessage arrays. + * + * Cabidela has a limitation where anyOf/oneOf with enum-based discrimination + * inside nested array items does not correctly match different branches for + * different array elements, so the schema uses a single merged object. + */ +type UserMessageContentPart = { + type: "text" | "image_url" | "input_audio" | "file"; + text?: string; + image_url?: { + url?: string; + detail?: "auto" | "low" | "high"; + }; + input_audio?: { + data?: string; + format?: "wav" | "mp3"; + }; + file?: { + file_data?: string; + file_id?: string; + filename?: string; + }; +}; +type UserMessage = { + role: "user"; + content: string | Array; + name?: string; +}; +type AssistantMessageContentPart = { + type: "text" | "refusal"; + text?: string; + refusal?: string; +}; +type AssistantMessage = { + role: "assistant"; + content?: string | null | Array; + refusal?: string | null; + name?: string; + audio?: { + id: string; + }; + tool_calls?: Array; + function_call?: { + name: string; + arguments: string; + }; +}; +type ToolMessage = { + role: "tool"; + content: + | string + | Array<{ + type: "text"; + text: string; + }>; + tool_call_id: string; +}; +type FunctionMessage = { + role: "function"; + content: string; + name: string; +}; +type ChatCompletionMessageParam = + | DeveloperMessage + | SystemMessage + | UserMessage + | AssistantMessage + | ToolMessage + | FunctionMessage; +type ChatCompletionsResponseFormatText = { + type: "text"; +}; +type ChatCompletionsResponseFormatJSONObject = { + type: "json_object"; +}; +type ResponseFormatJSONSchema = { + type: "json_schema"; + json_schema: { + name: string; + description?: string; + schema?: Record; + strict?: boolean | null; + }; +}; +type ResponseFormat = + | ChatCompletionsResponseFormatText + | ChatCompletionsResponseFormatJSONObject + | ResponseFormatJSONSchema; +type ChatCompletionsStreamOptions = { + include_usage?: boolean; + include_obfuscation?: boolean; +}; +type PredictionContent = { + type: "content"; + content: + | string + | Array<{ + type: "text"; + text: string; + }>; +}; +type AudioParams = { + voice: + | string + | { + id: string; + }; + format: "wav" | "aac" | "mp3" | "flac" | "opus" | "pcm16"; +}; +type WebSearchUserLocation = { + type: "approximate"; + approximate: { + city?: string; + country?: string; + region?: string; + timezone?: string; + }; +}; +type WebSearchOptions = { + search_context_size?: "low" | "medium" | "high"; + user_location?: WebSearchUserLocation; +}; +type ChatTemplateKwargs = { + /** Whether to enable reasoning, enabled by default. */ + enable_thinking?: boolean; + /** If false, preserves reasoning context between turns. */ + clear_thinking?: boolean; +}; +/** Shared optional properties used by both Prompt and Messages input branches. */ +type ChatCompletionsCommonOptions = { + model?: string; + audio?: AudioParams; + frequency_penalty?: number | null; + logit_bias?: Record | null; + logprobs?: boolean | null; + top_logprobs?: number | null; + max_tokens?: number | null; + max_completion_tokens?: number | null; + metadata?: Record | null; + modalities?: Array<"text" | "audio"> | null; + n?: number | null; + parallel_tool_calls?: boolean; + prediction?: PredictionContent; + presence_penalty?: number | null; + reasoning_effort?: "low" | "medium" | "high" | null; + chat_template_kwargs?: ChatTemplateKwargs; + response_format?: ResponseFormat; + seed?: number | null; + service_tier?: "auto" | "default" | "flex" | "scale" | "priority" | null; + stop?: string | Array | null; + store?: boolean | null; + stream?: boolean | null; + stream_options?: ChatCompletionsStreamOptions; + temperature?: number | null; + tool_choice?: ChatCompletionToolChoiceOption; + tools?: Array; + top_p?: number | null; + user?: string; + web_search_options?: WebSearchOptions; + function_call?: + | "none" + | "auto" + | { + name: string; + }; + functions?: Array; +}; +type PromptTokensDetails = { + cached_tokens?: number; + audio_tokens?: number; +}; +type CompletionTokensDetails = { + reasoning_tokens?: number; + audio_tokens?: number; + accepted_prediction_tokens?: number; + rejected_prediction_tokens?: number; +}; +type CompletionUsage = { + prompt_tokens: number; + completion_tokens: number; + total_tokens: number; + prompt_tokens_details?: PromptTokensDetails; + completion_tokens_details?: CompletionTokensDetails; +}; +type ChatCompletionTopLogprob = { + token: string; + logprob: number; + bytes: Array | null; +}; +type ChatCompletionTokenLogprob = { + token: string; + logprob: number; + bytes: Array | null; + top_logprobs: Array; +}; +type ChatCompletionAudio = { + id: string; + /** Base64 encoded audio bytes. */ + data: string; + expires_at: number; + transcript: string; +}; +type ChatCompletionUrlCitation = { + type: "url_citation"; + url_citation: { + url: string; + title: string; + start_index: number; + end_index: number; + }; +}; +type ChatCompletionResponseMessage = { + role: "assistant"; + content: string | null; + refusal: string | null; + annotations?: Array; + audio?: ChatCompletionAudio; + tool_calls?: Array; + function_call?: { + name: string; + arguments: string; + } | null; +}; +type ChatCompletionLogprobs = { + content: Array | null; + refusal?: Array | null; +}; +type ChatCompletionChoice = { + index: number; + message: ChatCompletionResponseMessage; + finish_reason: "stop" | "length" | "tool_calls" | "content_filter" | "function_call"; + logprobs: ChatCompletionLogprobs | null; +}; +type ChatCompletionsPromptInput = { + prompt: string; +} & ChatCompletionsCommonOptions; +type ChatCompletionsMessagesInput = { + messages: Array; +} & ChatCompletionsCommonOptions; +type ChatCompletionsOutput = { + id: string; + object: string; + created: number; + model: string; + choices: Array; + usage?: CompletionUsage; + system_fingerprint?: string | null; + service_tier?: "auto" | "default" | "flex" | "scale" | "priority" | null; +}; +/** + * Workers AI support for OpenAI's Responses API + * Reference: https://github.com/openai/openai-node/blob/master/src/resources/responses/responses.ts + * + * It's a stripped down version from its source. + * It currently supports basic function calling, json mode and accepts images as input. + * + * It does not include types for WebSearch, CodeInterpreter, FileInputs, MCP, CustomTools. + * We plan to add those incrementally as model + platform capabilities evolve. + */ +type ResponsesInput = { + background?: boolean | null; + conversation?: string | ResponseConversationParam | null; + include?: Array | null; + input?: string | ResponseInput; + instructions?: string | null; + max_output_tokens?: number | null; + parallel_tool_calls?: boolean | null; + previous_response_id?: string | null; + prompt_cache_key?: string; + reasoning?: Reasoning | null; + safety_identifier?: string; + service_tier?: "auto" | "default" | "flex" | "scale" | "priority" | null; + stream?: boolean | null; + stream_options?: StreamOptions | null; + temperature?: number | null; + text?: ResponseTextConfig; + tool_choice?: ToolChoiceOptions | ToolChoiceFunction; + tools?: Array; + top_p?: number | null; + truncation?: "auto" | "disabled" | null; +}; +type ResponsesOutput = { + id?: string; + created_at?: number; + output_text?: string; + error?: ResponseError | null; + incomplete_details?: ResponseIncompleteDetails | null; + instructions?: string | Array | null; + object?: "response"; + output?: Array; + parallel_tool_calls?: boolean; + temperature?: number | null; + tool_choice?: ToolChoiceOptions | ToolChoiceFunction; + tools?: Array; + top_p?: number | null; + max_output_tokens?: number | null; + previous_response_id?: string | null; + prompt?: ResponsePrompt | null; + reasoning?: Reasoning | null; + safety_identifier?: string; + service_tier?: "auto" | "default" | "flex" | "scale" | "priority" | null; + status?: ResponseStatus; + text?: ResponseTextConfig; + truncation?: "auto" | "disabled" | null; + usage?: ResponseUsage; +}; +type EasyInputMessage = { + content: string | ResponseInputMessageContentList; + role: "user" | "assistant" | "system" | "developer"; + type?: "message"; +}; +type ResponsesFunctionTool = { + name: string; + parameters: { + [key: string]: unknown; + } | null; + strict: boolean | null; + type: "function"; + description?: string | null; +}; +type ResponseIncompleteDetails = { + reason?: "max_output_tokens" | "content_filter"; +}; +type ResponsePrompt = { + id: string; + variables?: { + [key: string]: string | ResponseInputText | ResponseInputImage; + } | null; + version?: string | null; +}; +type Reasoning = { + effort?: ReasoningEffort | null; + generate_summary?: "auto" | "concise" | "detailed" | null; + summary?: "auto" | "concise" | "detailed" | null; +}; +type ResponseContent = + | ResponseInputText + | ResponseInputImage + | ResponseOutputText + | ResponseOutputRefusal + | ResponseContentReasoningText; +type ResponseContentReasoningText = { text: string; type: "reasoning_text"; }; @@ -4366,6 +5272,12 @@ type ReasoningEffort = "minimal" | "low" | "medium" | "high" | null; type StreamOptions = { include_obfuscation?: boolean; }; +/** Marks keys from T that aren't in U as optional never */ +type Without = { + [P in Exclude]?: never; +}; +/** Either T or U, but not both (mutually exclusive) */ +type XOR = (T & Without) | (U & Without); type Ai_Cf_Baai_Bge_Base_En_V1_5_Input = | { text: string | string[]; @@ -4658,10 +5570,12 @@ declare abstract class Base_Ai_Cf_Openai_Whisper_Tiny_En { postProcessedOutputs: Ai_Cf_Openai_Whisper_Tiny_En_Output; } interface Ai_Cf_Openai_Whisper_Large_V3_Turbo_Input { - /** - * Base64 encoded value of the audio data. - */ - audio: string; + audio: + | string + | { + body?: object; + contentType?: string; + }; /** * Supported tasks are 'translate' or 'transcribe'. */ @@ -4679,9 +5593,33 @@ interface Ai_Cf_Openai_Whisper_Large_V3_Turbo_Input { */ initial_prompt?: string; /** - * The prefix it appended the the beginning of the output of the transcription and can guide the transcription result. + * The prefix appended to the beginning of the output of the transcription and can guide the transcription result. */ prefix?: string; + /** + * The number of beams to use in beam search decoding. Higher values may improve accuracy at the cost of speed. + */ + beam_size?: number; + /** + * Whether to condition on previous text during transcription. Setting to false may help prevent hallucination loops. + */ + condition_on_previous_text?: boolean; + /** + * Threshold for detecting no-speech segments. Segments with no-speech probability above this value are skipped. + */ + no_speech_threshold?: number; + /** + * Threshold for filtering out segments with high compression ratio, which often indicate repetitive or hallucinated text. + */ + compression_ratio_threshold?: number; + /** + * Threshold for filtering out segments with low average log probability, indicating low confidence. + */ + log_prob_threshold?: number; + /** + * Optional threshold (in seconds) to skip silent periods that may cause hallucinations. + */ + hallucination_silence_threshold?: number; } interface Ai_Cf_Openai_Whisper_Large_V3_Turbo_Output { transcription_info?: { @@ -4828,11 +5766,11 @@ interface Ai_Cf_Baai_Bge_M3_Input_Embedding_1 { truncate_inputs?: boolean; } type Ai_Cf_Baai_Bge_M3_Output = - | Ai_Cf_Baai_Bge_M3_Ouput_Query + | Ai_Cf_Baai_Bge_M3_Output_Query | Ai_Cf_Baai_Bge_M3_Output_EmbeddingFor_Contexts - | Ai_Cf_Baai_Bge_M3_Ouput_Embedding + | Ai_Cf_Baai_Bge_M3_Output_Embedding | Ai_Cf_Baai_Bge_M3_AsyncResponse; -interface Ai_Cf_Baai_Bge_M3_Ouput_Query { +interface Ai_Cf_Baai_Bge_M3_Output_Query { response?: { /** * Index of the context in the request @@ -4852,7 +5790,7 @@ interface Ai_Cf_Baai_Bge_M3_Output_EmbeddingFor_Contexts { */ pooling?: "mean" | "cls"; } -interface Ai_Cf_Baai_Bge_M3_Ouput_Embedding { +interface Ai_Cf_Baai_Bge_M3_Output_Embedding { shape?: number[]; /** * Embeddings of the requested text values @@ -4957,7 +5895,7 @@ interface Ai_Cf_Meta_Llama_3_2_11B_Vision_Instruct_Messages { */ role?: string; /** - * The tool call id. Must be supplied for tool calls for Mistral-3. If you don't know what to put here you can fall back to 000000001 + * The tool call id. If you don't know what to put here you can fall back to 000000001 */ tool_call_id?: string; content?: @@ -5212,10 +6150,18 @@ interface Ai_Cf_Meta_Llama_3_3_70B_Instruct_Fp8_Fast_Messages { * The role of the message sender (e.g., 'user', 'assistant', 'system', 'tool'). */ role: string; - /** - * The content of the message as a string. - */ - content: string; + content: + | string + | { + /** + * Type of the content (text) + */ + type?: string; + /** + * Text content + */ + text?: string; + }[]; }[]; functions?: { name: string; @@ -5869,7 +6815,7 @@ interface Ai_Cf_Qwen_Qwq_32B_Messages { */ role?: string; /** - * The tool call id. Must be supplied for tool calls for Mistral-3. If you don't know what to put here you can fall back to 000000001 + * The tool call id. If you don't know what to put here you can fall back to 000000001 */ tool_call_id?: string; content?: @@ -5996,7 +6942,7 @@ interface Ai_Cf_Qwen_Qwq_32B_Messages { } )[]; /** - * JSON schema that should be fulfilled for the response. + * JSON schema that should be fufilled for the response. */ guided_json?: object; /** @@ -6270,7 +7216,7 @@ interface Ai_Cf_Mistralai_Mistral_Small_3_1_24B_Instruct_Messages { } )[]; /** - * JSON schema that should be fulfilled for the response. + * JSON schema that should be fufilled for the response. */ guided_json?: object; /** @@ -6363,7 +7309,7 @@ interface Ai_Cf_Google_Gemma_3_12B_It_Prompt { */ prompt: string; /** - * JSON schema that should be fulfilled for the response. + * JSON schema that should be fufilled for the response. */ guided_json?: object; /** @@ -6527,7 +7473,7 @@ interface Ai_Cf_Google_Gemma_3_12B_It_Messages { } )[]; /** - * JSON schema that should be fulfilled for the response. + * JSON schema that should be fufilled for the response. */ guided_json?: object; /** @@ -6808,7 +7754,7 @@ interface Ai_Cf_Meta_Llama_4_Scout_17B_16E_Instruct_Messages { )[]; response_format?: Ai_Cf_Meta_Llama_4_Scout_17B_16E_Instruct_JSON_Mode; /** - * JSON schema that should be fulfilled for the response. + * JSON schema that should be fufilled for the response. */ guided_json?: object; /** @@ -7047,7 +7993,7 @@ interface Ai_Cf_Meta_Llama_4_Scout_17B_16E_Instruct_Messages_Inner { )[]; response_format?: Ai_Cf_Meta_Llama_4_Scout_17B_16E_Instruct_JSON_Mode; /** - * JSON schema that should be fulfilled for the response. + * JSON schema that should be fufilled for the response. */ guided_json?: object; /** @@ -7212,14 +8158,22 @@ interface Ai_Cf_Qwen_Qwen3_30B_A3B_Fp8_Messages { * The role of the message sender (e.g., 'user', 'assistant', 'system', 'tool'). */ role: string; - /** - * The content of the message as a string. - */ - content: string; - }[]; - functions?: { - name: string; - code: string; + content: + | string + | { + /** + * Type of the content (text) + */ + type?: string; + /** + * Text content + */ + text?: string; + }[]; + }[]; + functions?: { + name: string; + code: string; }[]; /** * A list of tools available for the assistant to use. @@ -7424,10 +8378,18 @@ interface Ai_Cf_Qwen_Qwen3_30B_A3B_Fp8_Messages_1 { * The role of the message sender (e.g., 'user', 'assistant', 'system', 'tool'). */ role: string; - /** - * The content of the message as a string. - */ - content: string; + content: + | string + | { + /** + * Type of the content (text) + */ + type?: string; + /** + * Text content + */ + text?: string; + }[]; }[]; functions?: { name: string; @@ -7987,12 +8949,12 @@ declare abstract class Base_Ai_Cf_Pipecat_Ai_Smart_Turn_V2 { postProcessedOutputs: Ai_Cf_Pipecat_Ai_Smart_Turn_V2_Output; } declare abstract class Base_Ai_Cf_Openai_Gpt_Oss_120B { - inputs: ResponsesInput; - postProcessedOutputs: ResponsesOutput; + inputs: XOR; + postProcessedOutputs: XOR; } declare abstract class Base_Ai_Cf_Openai_Gpt_Oss_20B { - inputs: ResponsesInput; - postProcessedOutputs: ResponsesOutput; + inputs: XOR; + postProcessedOutputs: XOR; } interface Ai_Cf_Leonardo_Phoenix_1_0_Input { /** @@ -8124,7 +9086,7 @@ interface Ai_Cf_Ai4Bharat_Indictrans2_En_Indic_1B_Input { */ text: string | string[]; /** - * Target language to translate to + * Target langauge to translate to */ target_language: | "asm_Beng" @@ -8240,10 +9202,18 @@ interface Ai_Cf_Aisingapore_Gemma_Sea_Lion_V4_27B_It_Messages { * The role of the message sender (e.g., 'user', 'assistant', 'system', 'tool'). */ role: string; - /** - * The content of the message as a string. - */ - content: string; + content: + | string + | { + /** + * Type of the content (text) + */ + type?: string; + /** + * Text content + */ + text?: string; + }[]; }[]; functions?: { name: string; @@ -8455,10 +9425,18 @@ interface Ai_Cf_Aisingapore_Gemma_Sea_Lion_V4_27B_It_Messages_1 { * The role of the message sender (e.g., 'user', 'assistant', 'system', 'tool'). */ role: string; - /** - * The content of the message as a string. - */ - content: string; + content: + | string + | { + /** + * Type of the content (text) + */ + type?: string; + /** + * Text content + */ + text?: string; + }[]; }[]; functions?: { name: string; @@ -9008,6 +9986,66 @@ declare abstract class Base_Ai_Cf_Deepgram_Aura_2_Es { inputs: Ai_Cf_Deepgram_Aura_2_Es_Input; postProcessedOutputs: Ai_Cf_Deepgram_Aura_2_Es_Output; } +interface Ai_Cf_Black_Forest_Labs_Flux_2_Dev_Input { + multipart: { + body?: object; + contentType?: string; + }; +} +interface Ai_Cf_Black_Forest_Labs_Flux_2_Dev_Output { + /** + * Generated image as Base64 string. + */ + image?: string; +} +declare abstract class Base_Ai_Cf_Black_Forest_Labs_Flux_2_Dev { + inputs: Ai_Cf_Black_Forest_Labs_Flux_2_Dev_Input; + postProcessedOutputs: Ai_Cf_Black_Forest_Labs_Flux_2_Dev_Output; +} +interface Ai_Cf_Black_Forest_Labs_Flux_2_Klein_4B_Input { + multipart: { + body?: object; + contentType?: string; + }; +} +interface Ai_Cf_Black_Forest_Labs_Flux_2_Klein_4B_Output { + /** + * Generated image as Base64 string. + */ + image?: string; +} +declare abstract class Base_Ai_Cf_Black_Forest_Labs_Flux_2_Klein_4B { + inputs: Ai_Cf_Black_Forest_Labs_Flux_2_Klein_4B_Input; + postProcessedOutputs: Ai_Cf_Black_Forest_Labs_Flux_2_Klein_4B_Output; +} +interface Ai_Cf_Black_Forest_Labs_Flux_2_Klein_9B_Input { + multipart: { + body?: object; + contentType?: string; + }; +} +interface Ai_Cf_Black_Forest_Labs_Flux_2_Klein_9B_Output { + /** + * Generated image as Base64 string. + */ + image?: string; +} +declare abstract class Base_Ai_Cf_Black_Forest_Labs_Flux_2_Klein_9B { + inputs: Ai_Cf_Black_Forest_Labs_Flux_2_Klein_9B_Input; + postProcessedOutputs: Ai_Cf_Black_Forest_Labs_Flux_2_Klein_9B_Output; +} +declare abstract class Base_Ai_Cf_Zai_Org_Glm_4_7_Flash { + inputs: ChatCompletionsInput; + postProcessedOutputs: ChatCompletionsOutput; +} +declare abstract class Base_Ai_Cf_Moonshotai_Kimi_K2_5 { + inputs: ChatCompletionsInput; + postProcessedOutputs: ChatCompletionsOutput; +} +declare abstract class Base_Ai_Cf_Nvidia_Nemotron_3_120B_A12B { + inputs: ChatCompletionsInput; + postProcessedOutputs: ChatCompletionsOutput; +} interface AiModels { "@cf/huggingface/distilbert-sst-2-int8": BaseAiTextClassification; "@cf/stabilityai/stable-diffusion-xl-base-1.0": BaseAiTextToImage; @@ -9026,7 +10064,6 @@ interface AiModels { "@hf/thebloke/zephyr-7b-beta-awq": BaseAiTextGeneration; "@hf/thebloke/openhermes-2.5-mistral-7b-awq": BaseAiTextGeneration; "@hf/thebloke/neural-chat-7b-v3-1-awq": BaseAiTextGeneration; - "@hf/thebloke/llamaguard-7b-awq": BaseAiTextGeneration; "@hf/thebloke/deepseek-coder-6.7b-base-awq": BaseAiTextGeneration; "@hf/thebloke/deepseek-coder-6.7b-instruct-awq": BaseAiTextGeneration; "@cf/deepseek-ai/deepseek-math-7b-instruct": BaseAiTextGeneration; @@ -9093,6 +10130,12 @@ interface AiModels { "@cf/deepgram/flux": Base_Ai_Cf_Deepgram_Flux; "@cf/deepgram/aura-2-en": Base_Ai_Cf_Deepgram_Aura_2_En; "@cf/deepgram/aura-2-es": Base_Ai_Cf_Deepgram_Aura_2_Es; + "@cf/black-forest-labs/flux-2-dev": Base_Ai_Cf_Black_Forest_Labs_Flux_2_Dev; + "@cf/black-forest-labs/flux-2-klein-4b": Base_Ai_Cf_Black_Forest_Labs_Flux_2_Klein_4B; + "@cf/black-forest-labs/flux-2-klein-9b": Base_Ai_Cf_Black_Forest_Labs_Flux_2_Klein_9B; + "@cf/zai-org/glm-4.7-flash": Base_Ai_Cf_Zai_Org_Glm_4_7_Flash; + "@cf/moonshotai/kimi-k2.5": Base_Ai_Cf_Moonshotai_Kimi_K2_5; + "@cf/nvidia/nemotron-3-120b-a12b": Base_Ai_Cf_Nvidia_Nemotron_3_120B_A12B; } type AiOptions = { /** @@ -9118,6 +10161,7 @@ type AiOptions = { returnRawResponse?: boolean; prefix?: string; extraHeaders?: object; + signal?: AbortSignal; }; type AiModelsSearchParams = { author?: string; @@ -9144,12 +10188,31 @@ type AiModelsSearchObject = { value: string; }[]; }; +type ChatCompletionsBase = XOR; +type ChatCompletionsInput = XOR< + ChatCompletionsBase, + { + requests: ChatCompletionsBase[]; + } +>; interface InferenceUpstreamError extends Error {} interface AiInternalError extends Error {} type AiModelListType = Record; declare abstract class Ai { aiGatewayLogId: string | null; gateway(gatewayId: string): AiGateway; + /** + * @deprecated Use the standalone `ai_search_namespaces` or `ai_search` Workers bindings instead. + * See https://developers.cloudflare.com/ai-search/usage/workers-binding/ + */ + aiSearch(): AiSearchNamespace; + /** + * @deprecated AutoRAG has been replaced by AI Search. + * Use the standalone `ai_search_namespaces` or `ai_search` Workers bindings instead. + * See https://developers.cloudflare.com/ai-search/usage/workers-binding/ + * + * @param autoragId Instance ID + */ autorag(autoragId: string): AutoRAG; run< Name extends keyof AiModelList, @@ -9304,9 +10367,25 @@ declare abstract class AiGateway { ): Promise; getUrl(provider?: AIGatewayProviders | string): Promise; // eslint-disable-line } +/** + * @deprecated Use the standalone AI Search Workers binding instead. + * See https://developers.cloudflare.com/ai-search/usage/workers-binding/ + */ interface AutoRAGInternalError extends Error {} +/** + * @deprecated Use the standalone AI Search Workers binding instead. + * See https://developers.cloudflare.com/ai-search/usage/workers-binding/ + */ interface AutoRAGNotFoundError extends Error {} +/** + * @deprecated Use the standalone AI Search Workers binding instead. + * See https://developers.cloudflare.com/ai-search/usage/workers-binding/ + */ interface AutoRAGUnauthorizedError extends Error {} +/** + * @deprecated Use the standalone AI Search Workers binding instead. + * See https://developers.cloudflare.com/ai-search/usage/workers-binding/ + */ interface AutoRAGNameNotSetError extends Error {} type ComparisonFilter = { key: string; @@ -9317,6 +10396,10 @@ type CompoundFilter = { type: "and" | "or"; filters: ComparisonFilter[]; }; +/** + * @deprecated Use the standalone AI Search Workers binding instead. + * See https://developers.cloudflare.com/ai-search/usage/workers-binding/ + */ type AutoRagSearchRequest = { query: string; filters?: CompoundFilter | ComparisonFilter; @@ -9331,13 +10414,25 @@ type AutoRagSearchRequest = { }; rewrite_query?: boolean; }; +/** + * @deprecated Use the standalone AI Search Workers binding instead. + * See https://developers.cloudflare.com/ai-search/usage/workers-binding/ + */ type AutoRagAiSearchRequest = AutoRagSearchRequest & { stream?: boolean; system_prompt?: string; }; +/** + * @deprecated Use the standalone AI Search Workers binding instead. + * See https://developers.cloudflare.com/ai-search/usage/workers-binding/ + */ type AutoRagAiSearchRequestStreaming = Omit & { stream: true; }; +/** + * @deprecated Use the standalone AI Search Workers binding instead. + * See https://developers.cloudflare.com/ai-search/usage/workers-binding/ + */ type AutoRagSearchResponse = { object: "vector_store.search_results.page"; search_query: string; @@ -9354,6 +10449,10 @@ type AutoRagSearchResponse = { has_more: boolean; next_page: string | null; }; +/** + * @deprecated Use the standalone AI Search Workers binding instead. + * See https://developers.cloudflare.com/ai-search/usage/workers-binding/ + */ type AutoRagListResponse = { id: string; enable: boolean; @@ -9363,14 +10462,42 @@ type AutoRagListResponse = { paused: boolean; status: string; }[]; +/** + * @deprecated Use the standalone AI Search Workers binding instead. + * See https://developers.cloudflare.com/ai-search/usage/workers-binding/ + */ type AutoRagAiSearchResponse = AutoRagSearchResponse & { response: string; }; +/** + * @deprecated Use the standalone AI Search Workers binding instead. + * See https://developers.cloudflare.com/ai-search/usage/workers-binding/ + */ declare abstract class AutoRAG { + /** + * @deprecated Use the standalone AI Search Workers binding instead. + * See https://developers.cloudflare.com/ai-search/usage/workers-binding/ + */ list(): Promise; + /** + * @deprecated Use the standalone AI Search Workers binding instead. + * See https://developers.cloudflare.com/ai-search/usage/workers-binding/ + */ search(params: AutoRagSearchRequest): Promise; + /** + * @deprecated Use the standalone AI Search Workers binding instead. + * See https://developers.cloudflare.com/ai-search/usage/workers-binding/ + */ aiSearch(params: AutoRagAiSearchRequestStreaming): Promise; + /** + * @deprecated Use the standalone AI Search Workers binding instead. + * See https://developers.cloudflare.com/ai-search/usage/workers-binding/ + */ aiSearch(params: AutoRagAiSearchRequest): Promise; + /** + * @deprecated Use the standalone AI Search Workers binding instead. + * See https://developers.cloudflare.com/ai-search/usage/workers-binding/ + */ aiSearch(params: AutoRagAiSearchRequest): Promise; } interface BasicImageTransformations { @@ -9492,6 +10619,41 @@ interface RequestInitCfProperties extends Record { * (e.g. { '200-299': 86400, '404': 1, '500-599': 0 }) */ cacheTtlByStatus?: Record; + /** + * Explicit Cache-Control header value to set on the response stored in cache. + * This gives full control over cache directives (e.g. 'public, max-age=3600, s-maxage=86400'). + * + * Cannot be used together with `cacheTtl` or the `cache` request option (`no-store`/`no-cache`), + * as these are mutually exclusive cache control mechanisms. Setting both will throw a TypeError. + * + * Can be used together with `cacheTtlByStatus`. + */ + cacheControl?: string; + /** + * Whether the response should be eligible for Cache Reserve storage. + */ + cacheReserveEligible?: boolean; + /** + * Whether to respect strong ETags (as opposed to weak ETags) from the origin. + */ + respectStrongEtag?: boolean; + /** + * Whether to strip ETag headers from the origin response before caching. + */ + stripEtags?: boolean; + /** + * Whether to strip Last-Modified headers from the origin response before caching. + */ + stripLastModified?: boolean; + /** + * Whether to enable Cache Deception Armor, which protects against web cache + * deception attacks by verifying the Content-Type matches the URL extension. + */ + cacheDeceptionArmor?: boolean; + /** + * Minimum file size in bytes for a response to be eligible for Cache Reserve storage. + */ + cacheReserveMinimumFileSize?: number; scrapeShield?: boolean; apps?: boolean; image?: RequestInitCfPropertiesImage; @@ -10583,10 +11745,10 @@ interface SendEmail { declare abstract class EmailEvent extends ExtendableEvent { readonly message: ForwardableEmailMessage; } -declare type EmailExportedHandler = ( +declare type EmailExportedHandler = ( message: ForwardableEmailMessage, env: Env, - ctx: ExecutionContext, + ctx: ExecutionContext, ) => void | Promise; declare module "cloudflare:email" { let _EmailMessage: { @@ -10745,6 +11907,86 @@ type ImageOutputOptions = { background?: string; anim?: boolean; }; +interface ImageMetadata { + id: string; + filename?: string; + uploaded?: string; + requireSignedURLs: boolean; + meta?: Record; + variants: string[]; + draft?: boolean; + creator?: string; +} +interface ImageUploadOptions { + id?: string; + filename?: string; + requireSignedURLs?: boolean; + metadata?: Record; + creator?: string; + encoding?: "base64"; +} +interface ImageUpdateOptions { + requireSignedURLs?: boolean; + metadata?: Record; + creator?: string; +} +interface ImageListOptions { + limit?: number; + cursor?: string; + sortOrder?: "asc" | "desc"; + creator?: string; +} +interface ImageList { + images: ImageMetadata[]; + cursor?: string; + listComplete: boolean; +} +interface HostedImagesBinding { + /** + * Get detailed metadata for a hosted image + * @param imageId The ID of the image (UUID or custom ID) + * @returns Image metadata, or null if not found + */ + details(imageId: string): Promise; + /** + * Get the raw image data for a hosted image + * @param imageId The ID of the image (UUID or custom ID) + * @returns ReadableStream of image bytes, or null if not found + */ + image(imageId: string): Promise | null>; + /** + * Upload a new hosted image + * @param image The image file to upload + * @param options Upload configuration + * @returns Metadata for the uploaded image + * @throws {@link ImagesError} if upload fails + */ + upload( + image: ReadableStream | ArrayBuffer, + options?: ImageUploadOptions, + ): Promise; + /** + * Update hosted image metadata + * @param imageId The ID of the image + * @param options Properties to update + * @returns Updated image metadata + * @throws {@link ImagesError} if update fails + */ + update(imageId: string, options: ImageUpdateOptions): Promise; + /** + * Delete a hosted image + * @param imageId The ID of the image + * @returns True if deleted, false if not found + */ + delete(imageId: string): Promise; + /** + * List hosted images with pagination + * @param options List configuration + * @returns List of images with pagination info + * @throws {@link ImagesError} if list fails + */ + list(options?: ImageListOptions): Promise; +} interface ImagesBinding { /** * Get image metadata (type, width and height) @@ -10758,6 +12000,10 @@ interface ImagesBinding { * @returns A transform handle */ input(stream: ReadableStream, options?: ImageInputOptions): ImageTransformer; + /** + * Access hosted images CRUD operations + */ + readonly hosted: HostedImagesBinding; } interface ImageTransformer { /** @@ -10827,7 +12073,13 @@ interface MediaTransformer { * @param transform - Configuration for how the media should be transformed * @returns A generator for producing the transformed media output */ - transform(transform: MediaTransformationInputOptions): MediaTransformationGenerator; + transform(transform?: MediaTransformationInputOptions): MediaTransformationGenerator; + /** + * Generates the final media output with specified options. + * @param output - Configuration for the output format and parameters + * @returns The final transformation result containing the transformed media + */ + output(output?: MediaTransformationOutputOptions): MediaTransformationResult; } /** * Generator for producing media transformation results. @@ -10839,7 +12091,7 @@ interface MediaTransformationGenerator { * @param output - Configuration for the output format and parameters * @returns The final transformation result containing the transformed media */ - output(output: MediaTransformationOutputOptions): MediaTransformationResult; + output(output?: MediaTransformationOutputOptions): MediaTransformationResult; } /** * Result of a media transformation operation. @@ -10848,19 +12100,19 @@ interface MediaTransformationGenerator { interface MediaTransformationResult { /** * Returns the transformed media as a readable stream of bytes. - * @returns A stream containing the transformed media data + * @returns A promise containing a readable stream with the transformed media */ - media(): ReadableStream; + media(): Promise>; /** * Returns the transformed media as an HTTP response object. - * @returns The transformed media as a Response, ready to store in cache or return to users + * @returns The transformed media as a Promise, ready to store in cache or return to users */ - response(): Response; + response(): Promise; /** * Returns the MIME type of the transformed media. - * @returns The content type string (e.g., 'image/jpeg', 'video/mp4') + * @returns A promise containing the content type string (e.g., 'image/jpeg', 'video/mp4') */ - contentType(): string; + contentType(): Promise; } /** * Configuration options for transforming media input. @@ -11252,6 +12504,7 @@ declare namespace CloudflareWorkersModule { constructor(ctx: ExecutionContext, env: Env); email?(message: ForwardableEmailMessage): void | Promise; fetch?(request: Request): Response | Promise; + connect?(socket: Socket): void | Promise; queue?(batch: MessageBatch): void | Promise; scheduled?(controller: ScheduledController): void | Promise; tail?(events: TraceItem[]): void | Promise; @@ -11270,6 +12523,7 @@ declare namespace CloudflareWorkersModule { constructor(ctx: DurableObjectState, env: Env); alarm?(alarmInfo?: AlarmInvocationInfo): void | Promise; fetch?(request: Request): Response | Promise; + connect?(socket: Socket): void | Promise; webSocketMessage?(ws: WebSocket, message: string | ArrayBuffer): void | Promise; webSocketClose?( ws: WebSocket, @@ -11310,12 +12564,18 @@ declare namespace CloudflareWorkersModule { timestamp: Date; type: string; }; + export type WorkflowStepContext = { + attempt: number; + }; export abstract class WorkflowStep { - do>(name: string, callback: () => Promise): Promise; + do>( + name: string, + callback: (ctx: WorkflowStepContext) => Promise, + ): Promise; do>( name: string, config: WorkflowStepConfig, - callback: () => Promise, + callback: (ctx: WorkflowStepContext) => Promise, ): Promise; sleep: (name: string, duration: WorkflowSleepDuration) => Promise; sleepUntil: (name: string, timestamp: Date | number) => Promise; @@ -11374,12 +12634,745 @@ declare module "cloudflare:sockets" { function _connect(address: string | SocketAddress, options?: SocketOptions): Socket; export { _connect as connect }; } +/** + * Binding entrypoint for Cloudflare Stream. + * + * Usage: + * - Binding-level operations: + * `await env.STREAM.videos.upload` + * `await env.STREAM.videos.createDirectUpload` + * `await env.STREAM.videos.*` + * `await env.STREAM.watermarks.*` + * - Per-video operations: + * `await env.STREAM.video(id).downloads.*` + * `await env.STREAM.video(id).captions.*` + * + * Example usage: + * ```ts + * await env.STREAM.video(id).downloads.generate(); + * + * const video = env.STREAM.video(id) + * const captions = video.captions.list(); + * const videoDetails = video.details() + * ``` + */ +interface StreamBinding { + /** + * Returns a handle scoped to a single video for per-video operations. + * @param id The unique identifier for the video. + * @returns A handle for per-video operations. + */ + video(id: string): StreamVideoHandle; + /** + * Uploads a new video from a provided URL. + * @param url The URL to upload from. + * @param params Optional upload parameters. + * @returns The uploaded video details. + * @throws {BadRequestError} if the upload parameter is invalid or the URL is invalid + * @throws {QuotaReachedError} if the account storage capacity is exceeded + * @throws {MaxFileSizeError} if the file size is too large + * @throws {RateLimitedError} if the server received too many requests + * @throws {AlreadyUploadedError} if a video was already uploaded to this URL + * @throws {InternalError} if an unexpected error occurs + */ + upload(url: string, params?: StreamUrlUploadParams): Promise; + /** + * Creates a direct upload that allows video uploads without an API key. + * @param params Parameters for the direct upload + * @returns The direct upload details. + * @throws {BadRequestError} if the parameters are invalid + * @throws {RateLimitedError} if the server received too many requests + * @throws {InternalError} if an unexpected error occurs + */ + createDirectUpload(params: StreamDirectUploadCreateParams): Promise; + videos: StreamVideos; + watermarks: StreamWatermarks; +} +/** + * Handle for operations scoped to a single Stream video. + */ +interface StreamVideoHandle { + /** + * The unique identifier for the video. + */ + id: string; + /** + * Get a full videos details + * @returns The full video details. + * @throws {NotFoundError} if the video is not found + * @throws {InternalError} if an unexpected error occurs + */ + details(): Promise; + /** + * Update details for a single video. + * @param params The fields to update for the video. + * @returns The updated video details. + * @throws {NotFoundError} if the video is not found + * @throws {BadRequestError} if the parameters are invalid + * @throws {InternalError} if an unexpected error occurs + */ + update(params: StreamUpdateVideoParams): Promise; + /** + * Deletes a video and its copies from Cloudflare Stream. + * @returns A promise that resolves when deletion completes. + * @throws {NotFoundError} if the video is not found + * @throws {InternalError} if an unexpected error occurs + */ + delete(): Promise; + /** + * Creates a signed URL token for a video. + * @returns The signed token that was created. + * @throws {InternalError} if the signing key cannot be retrieved or the token cannot be signed + */ + generateToken(): Promise; + downloads: StreamScopedDownloads; + captions: StreamScopedCaptions; +} +interface StreamVideo { + /** + * The unique identifier for the video. + */ + id: string; + /** + * A user-defined identifier for the media creator. + */ + creator: string | null; + /** + * The thumbnail URL for the video. + */ + thumbnail: string; + /** + * The thumbnail timestamp percentage. + */ + thumbnailTimestampPct: number; + /** + * Indicates whether the video is ready to stream. + */ + readyToStream: boolean; + /** + * The date and time the video became ready to stream. + */ + readyToStreamAt: string | null; + /** + * Processing status information. + */ + status: StreamVideoStatus; + /** + * A user modifiable key-value store. + */ + meta: Record; + /** + * The date and time the video was created. + */ + created: string; + /** + * The date and time the video was last modified. + */ + modified: string; + /** + * The date and time at which the video will be deleted. + */ + scheduledDeletion: string | null; + /** + * The size of the video in bytes. + */ + size: number; + /** + * The preview URL for the video. + */ + preview?: string; + /** + * Origins allowed to display the video. + */ + allowedOrigins: Array; + /** + * Indicates whether signed URLs are required. + */ + requireSignedURLs: boolean | null; + /** + * The date and time the video was uploaded. + */ + uploaded: string | null; + /** + * The date and time when the upload URL expires. + */ + uploadExpiry: string | null; + /** + * The maximum size in bytes for direct uploads. + */ + maxSizeBytes: number | null; + /** + * The maximum duration in seconds for direct uploads. + */ + maxDurationSeconds: number | null; + /** + * The video duration in seconds. -1 indicates unknown. + */ + duration: number; + /** + * Input metadata for the original upload. + */ + input: StreamVideoInput; + /** + * Playback URLs for the video. + */ + hlsPlaybackUrl: string; + dashPlaybackUrl: string; + /** + * The watermark applied to the video, if any. + */ + watermark: StreamWatermark | null; + /** + * The live input id associated with the video, if any. + */ + liveInputId?: string | null; + /** + * The source video id if this is a clip. + */ + clippedFromId: string | null; + /** + * Public details associated with the video. + */ + publicDetails: StreamPublicDetails | null; +} +type StreamVideoStatus = { + /** + * The current processing state. + */ + state: string; + /** + * The current processing step. + */ + step?: string; + /** + * The percent complete as a string. + */ + pctComplete?: string; + /** + * An error reason code, if applicable. + */ + errorReasonCode: string; + /** + * An error reason text, if applicable. + */ + errorReasonText: string; +}; +type StreamVideoInput = { + /** + * The input width in pixels. + */ + width: number; + /** + * The input height in pixels. + */ + height: number; +}; +type StreamPublicDetails = { + /** + * The public title for the video. + */ + title: string | null; + /** + * The public share link. + */ + share_link: string | null; + /** + * The public channel link. + */ + channel_link: string | null; + /** + * The public logo URL. + */ + logo: string | null; +}; +type StreamDirectUpload = { + /** + * The URL an unauthenticated upload can use for a single multipart request. + */ + uploadURL: string; + /** + * A Cloudflare-generated unique identifier for a media item. + */ + id: string; + /** + * The watermark profile applied to the upload. + */ + watermark: StreamWatermark | null; + /** + * The scheduled deletion time, if any. + */ + scheduledDeletion: string | null; +}; +type StreamDirectUploadCreateParams = { + /** + * The maximum duration in seconds for a video upload. + */ + maxDurationSeconds: number; + /** + * The date and time after upload when videos will not be accepted. + */ + expiry?: string; + /** + * A user-defined identifier for the media creator. + */ + creator?: string; + /** + * A user modifiable key-value store used to reference other systems of record for + * managing videos. + */ + meta?: Record; + /** + * Lists the origins allowed to display the video. + */ + allowedOrigins?: Array; + /** + * Indicates whether the video can be accessed using the id. When set to `true`, + * a signed token must be generated with a signing key to view the video. + */ + requireSignedURLs?: boolean; + /** + * The thumbnail timestamp percentage. + */ + thumbnailTimestampPct?: number; + /** + * The date and time at which the video will be deleted. Include `null` to remove + * a scheduled deletion. + */ + scheduledDeletion?: string | null; + /** + * The watermark profile to apply. + */ + watermark?: StreamDirectUploadWatermark; +}; +type StreamDirectUploadWatermark = { + /** + * The unique identifier for the watermark profile. + */ + id: string; +}; +type StreamUrlUploadParams = { + /** + * Lists the origins allowed to display the video. Enter allowed origin + * domains in an array and use `*` for wildcard subdomains. Empty arrays allow the + * video to be viewed on any origin. + */ + allowedOrigins?: Array; + /** + * A user-defined identifier for the media creator. + */ + creator?: string; + /** + * A user modifiable key-value store used to reference other systems of + * record for managing videos. + */ + meta?: Record; + /** + * Indicates whether the video can be a accessed using the id. When + * set to `true`, a signed token must be generated with a signing key to view the + * video. + */ + requireSignedURLs?: boolean; + /** + * Indicates the date and time at which the video will be deleted. Omit + * the field to indicate no change, or include with a `null` value to remove an + * existing scheduled deletion. If specified, must be at least 30 days from upload + * time. + */ + scheduledDeletion?: string | null; + /** + * The timestamp for a thumbnail image calculated as a percentage value + * of the video's duration. To convert from a second-wise timestamp to a + * percentage, divide the desired timestamp by the total duration of the video. If + * this value is not set, the default thumbnail image is taken from 0s of the + * video. + */ + thumbnailTimestampPct?: number; + /** + * The identifier for the watermark profile + */ + watermarkId?: string; +}; +interface StreamScopedCaptions { + /** + * Uploads the caption or subtitle file to the endpoint for a specific BCP47 language. + * One caption or subtitle file per language is allowed. + * @param language The BCP 47 language tag for the caption or subtitle. + * @param input The caption or subtitle stream to upload. + * @returns The created caption entry. + * @throws {NotFoundError} if the video is not found + * @throws {BadRequestError} if the language or file is invalid + * @throws {InternalError} if an unexpected error occurs + */ + upload(language: string, input: ReadableStream): Promise; + /** + * Generate captions or subtitles for the provided language via AI. + * @param language The BCP 47 language tag to generate. + * @returns The generated caption entry. + * @throws {NotFoundError} if the video is not found + * @throws {BadRequestError} if the language is invalid + * @throws {StreamError} if a generated caption already exists + * @throws {StreamError} if the video duration is too long + * @throws {StreamError} if the video is missing audio + * @throws {StreamError} if the requested language is not supported + * @throws {InternalError} if an unexpected error occurs + */ + generate(language: string): Promise; + /** + * Lists the captions or subtitles. + * Use the language parameter to filter by a specific language. + * @param language The optional BCP 47 language tag to filter by. + * @returns The list of captions or subtitles. + * @throws {NotFoundError} if the video or caption is not found + * @throws {InternalError} if an unexpected error occurs + */ + list(language?: string): Promise; + /** + * Removes the captions or subtitles from a video. + * @param language The BCP 47 language tag to remove. + * @returns A promise that resolves when deletion completes. + * @throws {NotFoundError} if the video or caption is not found + * @throws {InternalError} if an unexpected error occurs + */ + delete(language: string): Promise; +} +interface StreamScopedDownloads { + /** + * Generates a download for a video when a video is ready to view. Available + * types are `default` and `audio`. Defaults to `default` when omitted. + * @param downloadType The download type to create. + * @returns The current downloads for the video. + * @throws {NotFoundError} if the video is not found + * @throws {BadRequestError} if the download type is invalid + * @throws {StreamError} if the video duration is too long to generate a download + * @throws {StreamError} if the video is not ready to stream + * @throws {InternalError} if an unexpected error occurs + */ + generate(downloadType?: StreamDownloadType): Promise; + /** + * Lists the downloads created for a video. + * @returns The current downloads for the video. + * @throws {NotFoundError} if the video or downloads are not found + * @throws {InternalError} if an unexpected error occurs + */ + get(): Promise; + /** + * Delete the downloads for a video. Available types are `default` and `audio`. + * Defaults to `default` when omitted. + * @param downloadType The download type to delete. + * @returns A promise that resolves when deletion completes. + * @throws {NotFoundError} if the video or downloads are not found + * @throws {InternalError} if an unexpected error occurs + */ + delete(downloadType?: StreamDownloadType): Promise; +} +interface StreamVideos { + /** + * Lists all videos in a users account. + * @returns The list of videos. + * @throws {BadRequestError} if the parameters are invalid + * @throws {InternalError} if an unexpected error occurs + */ + list(params?: StreamVideosListParams): Promise; +} +interface StreamWatermarks { + /** + * Generate a new watermark profile + * @param input The image stream to upload + * @param params The watermark creation parameters. + * @returns The created watermark profile. + * @throws {BadRequestError} if the parameters are invalid + * @throws {InvalidURLError} if the URL is invalid + * @throws {TooManyWatermarksError} if the number of allowed watermarks is reached + * @throws {InternalError} if an unexpected error occurs + */ + generate(input: ReadableStream, params: StreamWatermarkCreateParams): Promise; + /** + * Generate a new watermark profile + * @param url The image url to upload + * @param params The watermark creation parameters. + * @returns The created watermark profile. + * @throws {BadRequestError} if the parameters are invalid + * @throws {InvalidURLError} if the URL is invalid + * @throws {TooManyWatermarksError} if the number of allowed watermarks is reached + * @throws {InternalError} if an unexpected error occurs + */ + generate(url: string, params: StreamWatermarkCreateParams): Promise; + /** + * Lists all watermark profiles for an account. + * @returns The list of watermark profiles. + * @throws {InternalError} if an unexpected error occurs + */ + list(): Promise; + /** + * Retrieves details for a single watermark profile. + * @param watermarkId The watermark profile identifier. + * @returns The watermark profile details. + * @throws {NotFoundError} if the watermark is not found + * @throws {InternalError} if an unexpected error occurs + */ + get(watermarkId: string): Promise; + /** + * Deletes a watermark profile. + * @param watermarkId The watermark profile identifier. + * @returns A promise that resolves when deletion completes. + * @throws {NotFoundError} if the watermark is not found + * @throws {InternalError} if an unexpected error occurs + */ + delete(watermarkId: string): Promise; +} +type StreamUpdateVideoParams = { + /** + * Lists the origins allowed to display the video. Enter allowed origin + * domains in an array and use `*` for wildcard subdomains. Empty arrays allow the + * video to be viewed on any origin. + */ + allowedOrigins?: Array; + /** + * A user-defined identifier for the media creator. + */ + creator?: string; + /** + * The maximum duration in seconds for a video upload. Can be set for a + * video that is not yet uploaded to limit its duration. Uploads that exceed the + * specified duration will fail during processing. A value of `-1` means the value + * is unknown. + */ + maxDurationSeconds?: number; + /** + * A user modifiable key-value store used to reference other systems of + * record for managing videos. + */ + meta?: Record; + /** + * Indicates whether the video can be a accessed using the id. When + * set to `true`, a signed token must be generated with a signing key to view the + * video. + */ + requireSignedURLs?: boolean; + /** + * Indicates the date and time at which the video will be deleted. Omit + * the field to indicate no change, or include with a `null` value to remove an + * existing scheduled deletion. If specified, must be at least 30 days from upload + * time. + */ + scheduledDeletion?: string | null; + /** + * The timestamp for a thumbnail image calculated as a percentage value + * of the video's duration. To convert from a second-wise timestamp to a + * percentage, divide the desired timestamp by the total duration of the video. If + * this value is not set, the default thumbnail image is taken from 0s of the + * video. + */ + thumbnailTimestampPct?: number; +}; +type StreamCaption = { + /** + * Whether the caption was generated via AI. + */ + generated?: boolean; + /** + * The language label displayed in the native language to users. + */ + label: string; + /** + * The language tag in BCP 47 format. + */ + language: string; + /** + * The status of a generated caption. + */ + status?: "ready" | "inprogress" | "error"; +}; +type StreamDownloadStatus = "ready" | "inprogress" | "error"; +type StreamDownloadType = "default" | "audio"; +type StreamDownload = { + /** + * Indicates the progress as a percentage between 0 and 100. + */ + percentComplete: number; + /** + * The status of a generated download. + */ + status: StreamDownloadStatus; + /** + * The URL to access the generated download. + */ + url?: string; +}; +/** + * An object with download type keys. Each key is optional and only present if that + * download type has been created. + */ +type StreamDownloadGetResponse = { + /** + * The audio-only download. Only present if this download type has been created. + */ + audio?: StreamDownload; + /** + * The default video download. Only present if this download type has been created. + */ + default?: StreamDownload; +}; +type StreamWatermarkPosition = "upperRight" | "upperLeft" | "lowerLeft" | "lowerRight" | "center"; +type StreamWatermark = { + /** + * The unique identifier for a watermark profile. + */ + id: string; + /** + * The size of the image in bytes. + */ + size: number; + /** + * The height of the image in pixels. + */ + height: number; + /** + * The width of the image in pixels. + */ + width: number; + /** + * The date and a time a watermark profile was created. + */ + created: string; + /** + * The source URL for a downloaded image. If the watermark profile was created via + * direct upload, this field is null. + */ + downloadedFrom: string | null; + /** + * A short description of the watermark profile. + */ + name: string; + /** + * The translucency of the image. A value of `0.0` makes the image completely + * transparent, and `1.0` makes the image completely opaque. Note that if the image + * is already semi-transparent, setting this to `1.0` will not make the image + * completely opaque. + */ + opacity: number; + /** + * The whitespace between the adjacent edges (determined by position) of the video + * and the image. `0.0` indicates no padding, and `1.0` indicates a fully padded + * video width or length, as determined by the algorithm. + */ + padding: number; + /** + * The size of the image relative to the overall size of the video. This parameter + * will adapt to horizontal and vertical videos automatically. `0.0` indicates no + * scaling (use the size of the image as-is), and `1.0 `fills the entire video. + */ + scale: number; + /** + * The location of the image. Valid positions are: `upperRight`, `upperLeft`, + * `lowerLeft`, `lowerRight`, and `center`. Note that `center` ignores the + * `padding` parameter. + */ + position: StreamWatermarkPosition; +}; +type StreamWatermarkCreateParams = { + /** + * A short description of the watermark profile. + */ + name?: string; + /** + * The translucency of the image. A value of `0.0` makes the image completely + * transparent, and `1.0` makes the image completely opaque. Note that if the + * image is already semi-transparent, setting this to `1.0` will not make the + * image completely opaque. + */ + opacity?: number; + /** + * The whitespace between the adjacent edges (determined by position) of the + * video and the image. `0.0` indicates no padding, and `1.0` indicates a fully + * padded video width or length, as determined by the algorithm. + */ + padding?: number; + /** + * The size of the image relative to the overall size of the video. This + * parameter will adapt to horizontal and vertical videos automatically. `0.0` + * indicates no scaling (use the size of the image as-is), and `1.0 `fills the + * entire video. + */ + scale?: number; + /** + * The location of the image. + */ + position?: StreamWatermarkPosition; +}; +type StreamVideosListParams = { + /** + * The maximum number of videos to return. + */ + limit?: number; + /** + * Return videos created before this timestamp. + * (RFC3339/RFC3339Nano) + */ + before?: string; + /** + * Comparison operator for the `before` field. + * @default 'lt' + */ + beforeComp?: StreamPaginationComparison; + /** + * Return videos created after this timestamp. + * (RFC3339/RFC3339Nano) + */ + after?: string; + /** + * Comparison operator for the `after` field. + * @default 'gte' + */ + afterComp?: StreamPaginationComparison; +}; +type StreamPaginationComparison = "eq" | "gt" | "gte" | "lt" | "lte"; +/** + * Error object for Stream binding operations. + */ +interface StreamError extends Error { + readonly code: number; + readonly statusCode: number; + readonly message: string; + readonly stack?: string; +} +interface InternalError extends StreamError { + name: "InternalError"; +} +interface BadRequestError extends StreamError { + name: "BadRequestError"; +} +interface NotFoundError extends StreamError { + name: "NotFoundError"; +} +interface ForbiddenError extends StreamError { + name: "ForbiddenError"; +} +interface RateLimitedError extends StreamError { + name: "RateLimitedError"; +} +interface QuotaReachedError extends StreamError { + name: "QuotaReachedError"; +} +interface MaxFileSizeError extends StreamError { + name: "MaxFileSizeError"; +} +interface InvalidURLError extends StreamError { + name: "InvalidURLError"; +} +interface AlreadyUploadedError extends StreamError { + name: "AlreadyUploadedError"; +} +interface TooManyWatermarksError extends StreamError { + name: "TooManyWatermarksError"; +} type MarkdownDocument = { name: string; blob: Blob; }; type ConversionResponse = | { + id: string; name: string; mimeType: string; format: "markdown"; @@ -11387,6 +13380,7 @@ type ConversionResponse = data: string; } | { + id: string; name: string; mimeType: string; format: "error"; @@ -11404,6 +13398,8 @@ type ConversionOptions = { images?: EmbeddedImageConversionOptions & { convertOGImage?: boolean; }; + hostname?: string; + cssSelector?: string; }; docx?: { images?: EmbeddedImageConversionOptions; @@ -11498,6 +13494,9 @@ declare namespace TailStream { readonly type: "fetch"; readonly statusCode: number; } + interface ConnectEventInfo { + readonly type: "connect"; + } type EventOutcome = | "ok" | "canceled" @@ -11528,6 +13527,7 @@ declare namespace TailStream { readonly scriptVersion?: ScriptVersion; readonly info: | FetchEventInfo + | ConnectEventInfo | JsRpcEventInfo | ScheduledEventInfo | AlarmEventInfo diff --git a/demos/cloudflare/wrangler.jsonc b/demos/cloudflare/wrangler.jsonc index 2dc5de41f2..a26e61406c 100644 --- a/demos/cloudflare/wrangler.jsonc +++ b/demos/cloudflare/wrangler.jsonc @@ -28,6 +28,10 @@ "bucket_name": "emdash-media", }, ], + // Cron trigger drives the AI Search reindex queue flush. + "triggers": { + "crons": ["* * * * *"], + }, // Observability "observability": { "enabled": true, @@ -38,4 +42,10 @@ "binding": "LOADER", }, ], + "ai_search_namespaces": [ + { + "binding": "AI_SEARCH", + "namespace": "default", + }, + ], } diff --git a/docs/src/content/docs/deployment/cloudflare.mdx b/docs/src/content/docs/deployment/cloudflare.mdx index 14f3729241..c66432fcbd 100644 --- a/docs/src/content/docs/deployment/cloudflare.mdx +++ b/docs/src/content/docs/deployment/cloudflare.mdx @@ -3,7 +3,7 @@ title: Deploy to Cloudflare description: Deploy EmDash to Cloudflare Workers with D1 and R2. --- -import { Aside, Tabs, TabItem } from "@astrojs/starlight/components"; +import { Aside, Steps, Tabs, TabItem } from "@astrojs/starlight/components"; Cloudflare Workers provides a fast, globally distributed runtime for EmDash. This guide covers deploying with D1 for the database and R2 for media storage. @@ -210,6 +210,67 @@ emdash({ See the [Authentication guide](/guides/authentication#cloudflare-access) for full configuration options. +## Cloudflare AI Search + +The AI Search plugin indexes published EmDash content and adds smart search interface to your site. + + +1. Register the plugin in the `plugins` array passed to EmDash: + + ```js title="astro.config.mjs" + import { aiSearch } from "@emdash-cms/cloudflare/plugins"; + + // ... + plugins: [ + formsPlugin(), + aiSearch(), + ], + ``` + +2. Add the AI Search namespace binding to your Worker configuration: + + ```jsonc title="wrangler.jsonc" + { + "ai_search_namespaces": [ + { + "binding": "AI_SEARCH", + "namespace": "default", + }, + ], + } + ``` + +3. Create the search endpoint used by the search interface: + + ```ts title="src/pages/api/ai-search/search.ts" + export { POST, prerender } from "@emdash-cms/cloudflare/plugins/ai-search"; + ``` + +4. Add the search interface to your site layout. The trigger slot can contain any button that fits your site's design: + + ```astro title="src/layouts/Base.astro" + --- + import AISearchSnippet from "@emdash-cms/cloudflare/plugins/ai-search/astro"; + --- + + + + + ``` + +5. Deploy the site: + + ```bash + pnpm deploy + ``` + +6. Open **Cloudflare AI Search** in the EmDash admin panel, select the collections to index, and click **Sync All Content**. + + This initial sync is required: the plugin's content hooks only fire for content created or updated after it was enabled, so anything published beforehand stays missing from the index until you run a full sync. + + +Content published or updated after setup is kept in sync automatically. The same page shows indexing progress. + ## Email On Workers, the only built-in `email:deliver` handler is a dev console stub, so diff --git a/packages/cloudflare/package.json b/packages/cloudflare/package.json index 3770bc72e0..c8f03cc315 100644 --- a/packages/cloudflare/package.json +++ b/packages/cloudflare/package.json @@ -65,6 +65,16 @@ "types": "./dist/plugins/cloudflare-email.d.mts", "default": "./dist/plugins/cloudflare-email.mjs" }, + "./plugins/ai-search": { + "types": "./dist/plugins/ai-search.d.mts", + "default": "./dist/plugins/ai-search.mjs" + }, + "./plugins/ai-search/astro": "./src/plugins/AISearchSnippet.astro", + "./plugins/ai-search-admin": { + "types": "./dist/plugins/ai-search-admin.d.mts", + "default": "./dist/plugins/ai-search-admin.mjs" + }, + "./media/images-runtime": { "types": "./dist/media/images-runtime.d.mts", "default": "./dist/media/images-runtime.mjs" @@ -95,6 +105,7 @@ "typecheck": "tsgo --noEmit" }, "dependencies": { + "@cloudflare/ai-search-snippet": "^0.0.42", "emdash": "workspace:*", "jose": "^6.1.3", "kysely-d1": "^0.4.0", @@ -102,22 +113,38 @@ }, "peerDependencies": { "@astrojs/cloudflare": ">=12.0.0", + "@cloudflare/kumo": "catalog:", "@cloudflare/workers-types": ">=4.0.0", + "@phosphor-icons/react": "^2.1.10", "astro": ">=6.0.0-beta.0", "kysely": ">=0.28.17", - "pg": ">=8.16.3" + "pg": ">=8.16.3", + "react": "^18.0.0 || ^19.0.0" }, "peerDependenciesMeta": { "pg": { "optional": true + }, + "@cloudflare/kumo": { + "optional": true + }, + "@phosphor-icons/react": { + "optional": true + }, + "react": { + "optional": true } }, "devDependencies": { "@arethetypeswrong/cli": "catalog:", "@astrojs/cloudflare": "catalog:", + "@cloudflare/kumo": "catalog:", "@cloudflare/workers-types": "catalog:", "@types/pg": "^8.16.0", + "@phosphor-icons/react": "catalog:", + "@types/react": "catalog:", "publint": "catalog:", + "react": "catalog:", "tsdown": "catalog:", "typescript": "catalog:", "vitest": "catalog:" @@ -140,4 +167,4 @@ ], "author": "Matt Kane", "license": "MIT" -} \ No newline at end of file +} diff --git a/packages/cloudflare/src/plugins/AISearchSnippet.astro b/packages/cloudflare/src/plugins/AISearchSnippet.astro new file mode 100644 index 0000000000..7a69963fc5 --- /dev/null +++ b/packages/cloudflare/src/plugins/AISearchSnippet.astro @@ -0,0 +1,75 @@ +--- +export interface Props { + id?: string; + apiUrl?: string; + placeholder?: string; + theme?: "light" | "dark" | "auto"; + maxResults?: number; + maxRenderResults?: number; + debounceMs?: number; + hideBranding?: boolean; + showUrl?: boolean; + showDate?: boolean; + hideThumbnails?: boolean; + seeMore?: string; + disableAnalytics?: boolean; +} + +const { + id, + apiUrl = "/api/ai-search", + placeholder = "Search...", + theme = "auto", + maxResults = 30, + maxRenderResults = 10, + debounceMs, + hideBranding, + showUrl = true, + showDate = true, + hideThumbnails, + seeMore, + disableAnalytics = true, +} = Astro.props; +--- + +
+ { + Astro.slots.has("trigger") && ( +
+ +
+ ) + } + +
+ + diff --git a/packages/cloudflare/src/plugins/ai-search-admin.tsx b/packages/cloudflare/src/plugins/ai-search-admin.tsx new file mode 100644 index 0000000000..6de5ed1132 --- /dev/null +++ b/packages/cloudflare/src/plugins/ai-search-admin.tsx @@ -0,0 +1,632 @@ +/** + * AI Search Plugin — Admin Components + * + * Settings page with a "Sync All Content" button that triggers + * a full reindex of all configured collections into AI Search. + */ + +import { Badge, Banner, Button, Combobox, Input, Loader } from "@cloudflare/kumo"; +import { + ArrowRight, + ArrowsClockwise, + CheckCircle, + ListMagnifyingGlass, + Plus, + Trash, +} from "@phosphor-icons/react"; +import type { PluginAdminExports } from "emdash"; +import { apiFetch, parseApiResponse } from "emdash/plugin-utils"; +import * as React from "react"; + +const API_BASE = "/_emdash/api/plugins/ai-search"; +const SCHEMA_API_BASE = "/_emdash/api/schema"; + +const indexedLabel = (n: number) => `${n} item${n !== 1 ? "s" : ""}`; + +function abortableDelay(ms: number, signal: AbortSignal): Promise { + return new Promise((resolve, reject) => { + const rejectAborted = () => reject(new DOMException("The operation was aborted", "AbortError")); + if (signal.aborted) { + rejectAborted(); + return; + } + const onAbort = () => { + window.clearTimeout(timer); + rejectAborted(); + }; + const timer = window.setTimeout(() => { + signal.removeEventListener("abort", onAbort); + resolve(); + }, ms); + signal.addEventListener("abort", onAbort, { once: true }); + }); +} + +// ============================================================================= +// Types +// ============================================================================= + +interface ReindexResult { + jobId: string; + status: "running" | "complete"; + done: boolean; + onlyMissing: boolean; + indexed: number; + errors: number; + skipped?: number; + collections: string[]; +} + +interface CollectionOption { + slug: string; + label: string; +} + +interface MissingItem { + id: string; + slug: string | null; + title: string | null; + status: string; +} + +interface CollectionStatus { + collection: string; + eligible: number; + indexed: number; + missing: MissingItem[]; +} + +interface IndexStatus { + instanceName: string; + binding: string; + hybridSearch: boolean; + totalIndexed: number; + collections: CollectionStatus[]; +} + +interface Synonym { + from: string; + to: string; +} + +// ============================================================================= +// Settings Page +// ============================================================================= + +function SettingsPage() { + const syncAbortRef = React.useRef(null); + const [syncMode, setSyncMode] = React.useState<"full" | "missing" | null>(null); + const isSyncing = syncMode !== null; + const [result, setResult] = React.useState(null); + const [error, setError] = React.useState(null); + const [available, setAvailable] = React.useState([]); + const [loadingCollections, setLoadingCollections] = React.useState(true); + const [collectionsError, setCollectionsError] = React.useState(null); + const [collectionsSaveError, setCollectionsSaveError] = React.useState(null); + const [selected, setSelected] = React.useState([]); + + const [status, setStatus] = React.useState(null); + const [isCheckingStatus, setIsCheckingStatus] = React.useState(false); + const [statusError, setStatusError] = React.useState(null); + + const [synonyms, setSynonyms] = React.useState([]); + const [isSavingSynonyms, setIsSavingSynonyms] = React.useState(false); + const [synonymsSaved, setSynonymsSaved] = React.useState(false); + const [synonymsError, setSynonymsError] = React.useState(null); + const [metadataValid, setMetadataValid] = React.useState(null); + const [isLoadingMetadata, setIsLoadingMetadata] = React.useState(true); + const [isRepairingMetadata, setIsRepairingMetadata] = React.useState(false); + const [metadataError, setMetadataError] = React.useState(null); + + React.useEffect(() => { + let cancelled = false; + void (async () => { + try { + const response = await apiFetch(`${API_BASE}/metadata`); + const data = await parseApiResponse<{ valid: boolean }>(response); + if (!cancelled) setMetadataValid(data.valid); + } catch (err) { + if (!cancelled) { + setMetadataError( + err instanceof Error ? err.message : "Failed to check metadata configuration", + ); + } + } finally { + if (!cancelled) setIsLoadingMetadata(false); + } + })(); + return () => { + cancelled = true; + }; + }, []); + + React.useEffect(() => { + let cancelled = false; + void (async () => { + try { + const [collectionsRes, configRes] = await Promise.all([ + apiFetch(`${SCHEMA_API_BASE}/collections`), + apiFetch(`${API_BASE}/config`), + ]); + const collectionsData = await parseApiResponse<{ items: CollectionOption[] }>( + collectionsRes, + ); + const configData = await parseApiResponse<{ + collections: string[]; + synonyms?: Synonym[]; + }>(configRes); + if (cancelled) return; + + setSynonyms(configData.synonyms ?? []); + + const options = collectionsData.items.map((c) => ({ slug: c.slug, label: c.label })); + setAvailable(options); + + const valid = new Set(options.map((c) => c.slug)); + const saved = (configData.collections ?? []).filter((slug) => valid.has(slug)); + setSelected(saved); + } catch (err) { + if (!cancelled) { + setCollectionsError(err instanceof Error ? err.message : "Failed to load collections"); + } + } finally { + if (!cancelled) setLoadingCollections(false); + } + })(); + return () => { + cancelled = true; + }; + }, []); + + React.useEffect( + () => () => { + syncAbortRef.current?.abort(); + }, + [], + ); + + const labelForSlug = React.useCallback( + (slug: string) => available.find((c) => c.slug === slug)?.label ?? slug, + [available], + ); + + const persistSelection = React.useCallback(async (next: string[]) => { + setCollectionsSaveError(null); + try { + const response = await apiFetch(`${API_BASE}/config`, { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ collections: next }), + }); + await parseApiResponse(response, "Failed to save collections"); + } catch (err) { + setCollectionsSaveError(err instanceof Error ? err.message : "Failed to save collections"); + } + }, []); + + const handleSelectionChange = React.useCallback( + (value: unknown) => { + const next = Array.isArray(value) + ? value.filter((item): item is string => typeof item === "string") + : []; + setSelected(next); + void persistSelection(next); + }, + [persistSelection], + ); + + const handleRepairMetadata = async () => { + setIsRepairingMetadata(true); + setMetadataError(null); + try { + const response = await apiFetch(`${API_BASE}/metadata`, { + method: "POST", + }); + const data = await parseApiResponse<{ valid: true }>( + response, + "Failed to fix metadata configuration", + ); + setMetadataValid(data.valid); + } catch (err) { + setMetadataError(err instanceof Error ? err.message : "Failed to fix metadata configuration"); + } finally { + setIsRepairingMetadata(false); + } + }; + + const runSync = React.useCallback( + async (body: Record, mode: "full" | "missing") => { + syncAbortRef.current?.abort(); + const controller = new AbortController(); + syncAbortRef.current = controller; + setSyncMode(mode); + setError(null); + try { + const response = await apiFetch(`${API_BASE}/reindex`, { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify(body), + signal: controller.signal, + }); + let data = await parseApiResponse(response); + if (controller.signal.aborted) return; + setResult(data); + + while (!data.done) { + await abortableDelay(5_000, controller.signal); + const statusResponse = await apiFetch(`${API_BASE}/reindex`, { + signal: controller.signal, + }); + const jobStatus = await parseApiResponse(statusResponse); + if (!jobStatus || jobStatus.jobId !== data.jobId) { + throw new Error("Reindex job not found"); + } + data = jobStatus; + if (!controller.signal.aborted) setResult(data); + } + } catch (err) { + if (!controller.signal.aborted) { + setError(err instanceof Error ? err.message : "Sync failed"); + } + } finally { + if (syncAbortRef.current === controller) { + syncAbortRef.current = null; + if (!controller.signal.aborted) setSyncMode(null); + } + } + }, + [], + ); + + const handleSync = (onlyMissing = false) => { + setResult(null); + void runSync({ collections: selected, onlyMissing }, onlyMissing ? "missing" : "full"); + }; + + React.useEffect(() => { + void (async () => { + try { + const response = await apiFetch(`${API_BASE}/reindex`); + const job = await parseApiResponse(response); + if (job && !job.done) { + await runSync({ jobId: job.jobId }, job.onlyMissing ? "missing" : "full"); + } + } catch { + // A missing prior job is normal. + } + })(); + }, [runSync]); + + const handleCheckStatus = async () => { + setIsCheckingStatus(true); + setStatus(null); + setStatusError(null); + try { + const query = selected.length > 0 ? `?collections=${selected.join(",")}` : ""; + const response = await apiFetch(`${API_BASE}/status${query}`); + const data = await parseApiResponse(response); + setStatus(data); + } catch (err) { + setStatusError(err instanceof Error ? err.message : "Failed to load status"); + } finally { + setIsCheckingStatus(false); + } + }; + + const updateSynonym = (index: number, patch: Partial) => { + setSynonymsSaved(false); + setSynonyms((prev) => prev.map((s, i) => (i === index ? { ...s, ...patch } : s))); + }; + + const addSynonym = () => { + setSynonymsSaved(false); + setSynonyms((prev) => [...prev, { from: "", to: "" }]); + }; + + const removeSynonym = (index: number) => { + setSynonymsSaved(false); + setSynonyms((prev) => prev.filter((_, i) => i !== index)); + }; + + const handleSaveSynonyms = async () => { + setIsSavingSynonyms(true); + setSynonymsSaved(false); + setSynonymsError(null); + // Drop incomplete rows before persisting. + const cleaned = synonyms + .map((s) => ({ from: s.from.trim(), to: s.to.trim() })) + .filter((s) => s.from && s.to); + try { + const response = await apiFetch(`${API_BASE}/config`, { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ synonyms: cleaned }), + }); + const data = await parseApiResponse<{ synonyms?: Synonym[] }>(response); + setSynonyms(data.synonyms ?? cleaned); + setSynonymsSaved(true); + } catch (err) { + setSynonymsError(err instanceof Error ? err.message : "Failed to save synonyms"); + } finally { + setIsSavingSynonyms(false); + } + }; + + return ( +
+

AI Search

+ + {isLoadingMetadata && ( +
+ + Checking metadata configuration… +
+ )} + + {metadataValid === false && ( +
+ + +

+ Fixing metadata triggers a full background reindex. Search results may be temporarily + inconsistent while it completes. +

+
+ )} + + {metadataError && ( + + )} + +
+

Sync Content

+

+ Re-upload all content to the search index. Content is indexed automatically on save — use + this for a full re-sync after initial setup or to recover from issues. +

+ +
+ {loadingCollections ? ( +
+ + Loading collections… +
+ ) : collectionsError ? ( + + ) : ( + c.slug)} + value={selected} + onValueChange={handleSelectionChange} + className="max-w-sm" + > + ( + + {labelForSlug(slug)} + + )} + /> + + No collections found + + {(slug: string) => ( + + {labelForSlug(slug)} + + )} + + + + )} + + {collectionsSaveError && ( + + )} + +
+ + + + + + + {result && !error && ( + + {indexedLabel(result.indexed)} indexed + + )} +
+ + {result?.done && ( + 0 ? "alert" : "default"} + icon={} + title="Sync complete" + description={ + <> + Indexed {indexedLabel(result.indexed)} across{" "} + {result.collections.join(", ")} + {result.skipped ? ` — ${result.skipped} already indexed` : ""} + {result.errors > 0 && ( + <> + {" "} + — {result.errors} error{result.errors !== 1 ? "s" : ""} + + )} + + } + /> + )} + + {error && } + + {statusError && ( + + )} + + {status && ( +
+
+ Instance {status.instanceName} ( + {status.binding}){" — "} + {indexedLabel(status.totalIndexed)} indexed total + {status.hybridSearch ? " · hybrid search" : ""} +
+ {status.collections.map((c) => { + const complete = c.missing.length === 0; + return ( +
+
+ {labelForSlug(c.collection)} + + {c.indexed} / {c.eligible} indexed + +
+ {!complete && ( +
    + {c.missing.slice(0, 10).map((m) => ( +
  • + {m.title || m.slug || m.id}{" "} + ({m.status}) +
    • + ))} + {c.missing.length > 10 &&
  • …and {c.missing.length - 10} more
    • } +
+ )} +
+ ); + })} +
+ )} +
+
+ +
+

Synonyms

+

+ Rewrite search queries before they reach the index. When a query contains a term on the + left, it is transparently replaced with the term on the right — e.g. “autorag” → “AI + Search”. Matching is whole-word and case-insensitive. +

+

+ Changes can take up to 60 seconds to reach all edge locations. +

+ +
+ {synonyms.length === 0 && ( +

No synonyms configured.

+ )} + + {synonyms.map((syn, index) => ( + // eslint-disable-next-line react/no-array-index-key -- rows are positional; no stable id +
+ ) => + updateSynonym(index, { from: e.target.value }) + } + placeholder="autorag" + className="max-w-[12rem]" + /> + + ) => + updateSynonym(index, { to: e.target.value }) + } + placeholder="AI Search" + className="max-w-[12rem]" + /> +
+ ))} + +
+ + + {synonymsSaved && Saved} +
+ + {synonymsError && ( + + )} +
+
+
+ ); +} + +// ============================================================================= +// Exports +// ============================================================================= + +export const pages: PluginAdminExports["pages"] = { + "/settings": SettingsPage, +}; diff --git a/packages/cloudflare/src/plugins/ai-search.ts b/packages/cloudflare/src/plugins/ai-search.ts new file mode 100644 index 0000000000..6de5fd242e --- /dev/null +++ b/packages/cloudflare/src/plugins/ai-search.ts @@ -0,0 +1,1570 @@ +/** + * AI Search Plugin + * + * Semantic search using Cloudflare AI Search namespace bindings. + * Indexes content on save, removes on delete, exposes a search route. + * + * Requires only the `ai_search_namespaces` binding in wrangler.jsonc — + * no API tokens, no account IDs, no manual instance creation. + * + * @example + * ```typescript + * // astro.config.mjs + * import { aiSearch } from "@emdash-cms/cloudflare/plugins"; + * + * export default defineConfig({ + * integrations: [ + * emdash({ + * plugins: [aiSearch()], + * }), + * ], + * }); + * ``` + * + * @example + * ```jsonc + * // wrangler.jsonc + * { + * "ai_search_namespaces": [ + * { "binding": "AI_SEARCH", "namespace": "default" } + * ] + * } + * ``` + * + * @example + * ```typescript + * // src/pages/api/ai-search/search.ts + * export { POST, prerender } from "@emdash-cms/cloudflare/plugins/ai-search"; + * ``` + */ + +import type { APIRoute } from "astro"; +import type { + ContentDeleteEvent, + ContentHookEvent, + ContentPublishStateChangeEvent, + KVAccess, + PluginContext, + PluginDescriptor, + ResolvedPlugin, + RouteContext, +} from "emdash"; +import { + definePlugin, + extractPlainText, + getI18nConfig, + OptionsRepository, + PluginRouteError, +} from "emdash"; +import type { EmDashRuntime } from "emdash/middleware"; + +const MD_EXT = /\.md$/; +const ITEM_PREFIX = /^item:/; +const INSTANCE_NOT_FOUND_MESSAGE = /ai_search_not_found|instance.*not found|not found.*instance/i; + +// ============================================================================= +// Configuration +// ============================================================================= + +export interface AISearchConfig { + /** AI Search instance name. @default "emdash-content" */ + instanceName?: string; + /** Binding name in wrangler.jsonc. @default "AI_SEARCH" */ + binding?: string; + /** Enable hybrid search (vector + keyword). @default true */ + hybridSearch?: boolean; + /** Public URL templates keyed by collection slug. @default "/{collection}/{slug}" */ + urlTemplates?: Record; +} + +const ACTIVE_CONFIG_KEY = Symbol.for("emdash.ai-search.config"); + +function activeConfigHolder(): { value: AISearchConfig } { + const globals = globalThis as typeof globalThis & { + [ACTIVE_CONFIG_KEY]?: { value: AISearchConfig }; + }; + return (globals[ACTIVE_CONFIG_KEY] ??= { value: {} }); +} + +export function getActiveAISearchConfig(): AISearchConfig { + return activeConfigHolder().value; +} + +/** + * KV key holding the collections the operator last configured in the admin + * dashboard. Persisted so the picker can restore the previous selection and + * the content hooks know which collections to index. + */ +const CONFIG_COLLECTIONS_KEY = "config:collections"; +const DEFAULT_COLLECTIONS = ["posts", "pages"]; + +/** KV prefix of the id-map mirrors (`item:{collection}/{id}.md` -> item id). */ +const MIRROR_PREFIX = "item:"; +/** Parallel deletions when purging mirrors of deselected collections. */ +const PURGE_CONCURRENCY = 4; + +/** + * KV key holding query synonyms configured in the admin dashboard. Each entry + * maps a term/phrase (`from`) to a replacement (`to`) that is substituted into + * search queries before they reach AI Search, to improve recall. + */ +const CONFIG_SYNONYMS_KEY = "config:synonyms"; + +const REINDEX_JOB_KEY = "reindex:job"; +const REINDEX_CRON_TASK = "reindex"; +const REINDEX_PAGE_SIZE = 50; +const REINDEX_PAGES_PER_TICK = 2; +const REINDEX_HOOK_TIMEOUT_MS = 300_000; + +type ReindexJobStatus = "running" | "complete"; + +interface ReindexJob { + id: string; + status: ReindexJobStatus; + collections: string[]; + collectionIndex: number; + cursor?: string; + onlyMissing: boolean; + indexed: number; + errors: number; + skipped: number; + /** Item keys accepted on the current page, used to resume mid-page safely. */ + completedItemKeys?: string[]; + updatedAt: string; +} + +/** AI Search's maximum length for a text custom-metadata value. */ +const METADATA_TEXT_MAX_LENGTH = 500; + +/** Preferred maximum length of the indexed article-preview description. */ +const DESCRIPTION_MAX_LENGTH = 400; + +/** + * Separator used to pack `title` and `description` into a single metadata + * field (AI Search allows at most 5 custom_metadata fields). The ASCII Unit + * Separator (U+001F) is chosen because it never appears in extracted plain + * text, so it can't collide with title or description content. + */ +const TITLE_DESC_SEP = "\u001F"; + +/** Pack a title and description into one value within AI Search's text limit. */ +export function packTitleDescription(title: string, description: string): string { + if ((title + TITLE_DESC_SEP + description).length <= METADATA_TEXT_MAX_LENGTH) { + return title + TITLE_DESC_SEP + description; + } + + // Real titles fit comfortably inside the limit; retain one character for the + // separator if an unexpectedly long title does not. + const packedTitle = title.slice(0, METADATA_TEXT_MAX_LENGTH - TITLE_DESC_SEP.length); + const descriptionBudget = METADATA_TEXT_MAX_LENGTH - packedTitle.length - TITLE_DESC_SEP.length; + return packedTitle + TITLE_DESC_SEP + truncateDescription(description, descriptionBudget); +} + +/** Unpack a packed `title_desc` value, splitting on the first separator only. */ +export function unpackTitleDescription(value: string): { title: string; description: string } { + const i = value.indexOf(TITLE_DESC_SEP); + if (i < 0) return { title: value, description: "" }; + return { title: value.slice(0, i), description: value.slice(i + 1) }; +} + +/** A single query synonym: replace `from` with `to` in incoming queries. */ +export interface Synonym { + from: string; + to: string; +} + +// ============================================================================= +// Minimal types for the AI Search namespace binding +// +// These mirror the generated types from `wrangler types` (see +// worker-configuration.d.ts). Remove once @cloudflare/workers-types +// ships the AI Search binding types. +// ============================================================================= + +interface AiSearchSearchRequest { + messages: Array<{ role: string; content: string | null }>; + ai_search_options?: { + retrieval?: { + retrieval_type?: "vector" | "keyword" | "hybrid"; + match_threshold?: number; + max_num_results?: number; + filters?: Record; + context_expansion?: number; + /** Return only item metadata, skipping the (slow) full-text chunks. */ + metadata_only?: boolean; + }; + query_rewrite?: { enabled?: boolean; model?: string; rewrite_prompt?: string }; + reranking?: { enabled?: boolean; model?: string; match_threshold?: number }; + }; +} + +interface AiSearchSearchResponse { + search_query: string; + chunks: Array<{ + id: string; + type: string; + score: number; + text: string; + item: { key: string; timestamp?: number; metadata?: Record }; + }>; +} + +interface AiSearchItemInfo { + id: string; + key: string; + status: string; + metadata?: Record; +} + +interface AiSearchCustomMetadata { + field_name: string; + data_type: "text" | "number" | "boolean" | "datetime"; +} + +interface AiSearchConfig { + id: string; + type?: string; + source?: string; + index_method?: { vector: boolean; keyword: boolean }; + custom_metadata?: AiSearchCustomMetadata[]; + [key: string]: unknown; +} + +interface AiSearchInstanceInfo { + id: string; + custom_metadata?: AiSearchCustomMetadata[]; + [key: string]: unknown; +} + +interface AiSearchInstance { + search(params: AiSearchSearchRequest): Promise; + update(config: Partial): Promise; + info(): Promise; + items: { + upload( + name: string, + content: string, + options?: { metadata?: Record }, + ): Promise; + delete(itemId: string): Promise; + }; +} + +const REQUIRED_CUSTOM_METADATA: AiSearchCustomMetadata[] = [ + { field_name: "visible_after", data_type: "number" }, + { field_name: "title_desc", data_type: "text" }, + { field_name: "slug", data_type: "text" }, + { field_name: "image", data_type: "text" }, + { field_name: "locale", data_type: "text" }, +]; + +interface AiSearchNamespace { + get(name: string): AiSearchInstance; + create(config: AiSearchConfig): Promise; +} + +// ============================================================================= +// Helpers +// ============================================================================= + +function isRecord(value: unknown): value is Record { + return typeof value === "object" && value !== null && !Array.isArray(value); +} + +function isMissingAISearchInstanceError(error: unknown): boolean { + if (isRecord(error) && (error.status === 404 || error.code === "NOT_FOUND")) return true; + return error instanceof Error && INSTANCE_NOT_FOUND_MESSAGE.test(error.message); +} + +function isAiSearchNamespace(value: unknown): value is AiSearchNamespace { + return isRecord(value) && typeof value.get === "function" && typeof value.create === "function"; +} + +const WORKERS_MODULE_KEY = Symbol.for("emdash.ai-search.workers-module"); + +type WorkersModule = typeof import("cloudflare:workers"); + +/** + * Import `cloudflare:workers` once per isolate. Several call sites need it, and + * a rejected import is not cached so a later call can retry. + */ +function loadWorkersModule(): Promise { + const globals = globalThis as typeof globalThis & { + [WORKERS_MODULE_KEY]?: Promise; + }; + return (globals[WORKERS_MODULE_KEY] ??= import("cloudflare:workers").catch((error: unknown) => { + delete globals[WORKERS_MODULE_KEY]; + throw error; + })); +} + +/** Get Cloudflare runtime env via cloudflare:workers. */ +async function getCloudflareEnv(): Promise { + try { + return (await loadWorkersModule()).env; + } catch { + return null; + } +} + +/** + * Keep the Worker isolate alive for the given promise. + * Uses cloudflare:workers waitUntil — safe to call after the response is sent. + * Silently no-ops outside Workers (e.g. during local dev). + */ +function cfWaitUntil(promise: Promise): void { + loadWorkersModule() + .then(({ waitUntil }) => waitUntil(promise)) + .catch(() => {}); +} + +const SYSTEM_CONTENT_KEYS = new Set([ + "id", + "slug", + "status", + "authorId", + "author_id", + "primaryBylineId", + "primary_byline_id", + "createdAt", + "created_at", + "updatedAt", + "updated_at", + "publishedAt", + "published_at", + "scheduledAt", + "scheduled_at", + "deletedAt", + "deleted_at", + "version", + "liveRevisionId", + "live_revision_id", + "draftRevisionId", + "draft_revision_id", + "locale", + "translationGroup", + "translation_group", +]); + +function isSystemContentKey(key: string): boolean { + return key.startsWith("_") || SYSTEM_CONTENT_KEYS.has(key); +} + +function extractIndexableText(value: unknown): string { + if (typeof value === "string") return extractPlainText(value); + if (Array.isArray(value)) return extractPlainText(JSON.stringify(value)); + return ""; +} + +function truncateDescription(value: string, maxLength: number = DESCRIPTION_MAX_LENGTH): string { + if (maxLength <= 0) return ""; + const normalized = value.replace(/\s+/g, " ").trim(); + if (normalized.length <= maxLength) return normalized; + if (maxLength === 1) return "\u2026"; + + const truncated = normalized.slice(0, maxLength - 1); + const lastSpace = truncated.lastIndexOf(" "); + return `${lastSpace > 0 ? truncated.slice(0, lastSpace) : truncated}\u2026`; +} + +/** Convert a content entry to Markdown for indexing. */ +function contentToMarkdown(content: Record, collection: string): string { + const parts: string[] = []; + + if (typeof content.title === "string") parts.push(`# ${content.title}`); + parts.push(`Collection: ${collection}`); + + for (const [key, value] of Object.entries(content)) { + if (key === "title" || isSystemContentKey(key)) continue; + const text = extractIndexableText(value); + if (text) parts.push(text); + } + + return parts.join("\n\n"); +} + +/** + * Build a short plain-text description (article preview) from the content's + * explicit excerpt. Returns an empty description when no excerpt is present. + */ +function contentToDescription(content: Record): string { + const excerpt = extractIndexableText(content.excerpt); + return excerpt ? truncateDescription(excerpt) : ""; +} + +function imageUrlFromValue(value: unknown): string { + if (!isRecord(value)) return ""; + if (typeof value.src === "string" && value.src) return value.src; + const meta = isRecord(value.meta) ? value.meta : undefined; + if (typeof meta?.storageKey === "string" && meta.storageKey) { + return `/_emdash/api/media/file/${meta.storageKey}`; + } + return ""; +} + +/** + * Extract a thumbnail URL from a content entry, preferring the conventional + * featured-image field before falling back to the first image-shaped value. + */ +function extractImageUrl(content: Record): string { + const featured = imageUrlFromValue(content.featured_image ?? content.featuredImage); + if (featured) return featured; + + for (const [key, value] of Object.entries(content)) { + if (key.startsWith("_") || key === "featured_image" || key === "featuredImage") continue; + const image = imageUrlFromValue(value); + if (image) return image; + } + return ""; +} + +/** + * Get the `visible_after` timestamp for a content item. + * Returns 0 for published content (immediately visible) or the + * scheduled_at unix timestamp in seconds for scheduled content. + */ +function getVisibleAfter(content: Record): number { + const status = typeof content.status === "string" ? content.status : ""; + // Hook events expose the camelCase `scheduledAt`; reindex merges the raw + // row which may still carry snake_case `scheduled_at`. Accept either. + const scheduledAt = content.scheduledAt ?? content.scheduled_at; + if ( + status === "scheduled" && + (typeof scheduledAt === "string" || typeof scheduledAt === "number") + ) { + const d = new Date(scheduledAt); + if (!isNaN(d.getTime())) return Math.floor(d.getTime() / 1000); + } + return 0; +} + +/** + * Flatten a content-hook record. Content hooks pass the `ContentItem` shape, + * where the editable fields (title, body, images) live under `.data` while the + * system columns (id, slug, status, locale, scheduledAt) sit at the top level. + * Merging `.data` up gives the same flat record the reindex path builds with + * `{ ...item, ...item.data }`, so field extraction behaves identically in both + * paths (without it, the hook path reads an empty title and skips the body). + */ +export function flattenContentRecord(content: Record): Record { + const data = content.data && typeof content.data === "object" ? content.data : {}; + return { ...content, ...data }; +} + +/** Deterministic document key: `{collection}/{id}.md`. */ +function contentKey(collection: string, id: string): string { + return `${collection}/${id}.md`; +} + +async function retry(operation: () => Promise): Promise { + let lastError: unknown; + for (let attempt = 0; attempt < 3; attempt++) { + try { + return await operation(); + } catch (error) { + lastError = error; + if (attempt < 2) await new Promise((resolve) => setTimeout(resolve, 250 * 2 ** attempt)); + } + } + throw lastError; +} + +/** Upload an item and mirror its AI Search item ID for later deletion. */ +async function uploadItem( + instance: AiSearchInstance, + key: string, + markdown: string, + metadata: Record, + ctx: PluginContext, +): Promise { + const mirrorKey = `item:${key}`; + const item = await instance.items.upload(key, markdown, { metadata }); + + await ctx.kv.set(mirrorKey, item.id); +} + +function createReindexJob(collections: string[], onlyMissing: boolean): ReindexJob { + return { + id: crypto.randomUUID(), + status: "running", + collections, + collectionIndex: 0, + onlyMissing, + indexed: 0, + errors: 0, + skipped: 0, + updatedAt: new Date().toISOString(), + }; +} + +function reindexResult(job: ReindexJob) { + return { + jobId: job.id, + status: job.status, + done: job.status === "complete", + onlyMissing: job.onlyMissing, + collections: job.collections, + indexed: job.indexed, + errors: job.errors, + skipped: job.skipped, + }; +} + +/** Parse a content key back into collection + id. */ +function parseContentKey(key: string): { collection: string; id: string } { + const [col, ...rest] = key.split("/"); + return { collection: col ?? "", id: rest.join("/").replace(MD_EXT, "") }; +} + +/** + * Normalize a `collections` request field into a trimmed slug array. + * Accepts a comma-separated string or an array of strings; returns `null` + * when the input is neither (so callers can fall back or error). + */ +function parseCollections(value: unknown): string[] | null { + const raw = + typeof value === "string" + ? value.split(",") + : Array.isArray(value) + ? value.filter((v): v is string => typeof v === "string") + : null; + if (raw === null) return null; + return raw.map((c) => c.trim()).filter(Boolean); +} + +function hasRequiredMetadataSchema(config: AiSearchInstanceInfo): boolean { + const actual = config.custom_metadata; + if (!actual || actual.length !== REQUIRED_CUSTOM_METADATA.length) return false; + + const fields = new Map(actual.map((field) => [field.field_name, field.data_type])); + return REQUIRED_CUSTOM_METADATA.every( + (field) => fields.get(field.field_name) === field.data_type, + ); +} + +/** + * Normalize a `synonyms` request field into a validated `Synonym[]`. Accepts an + * array of `{ from, to }` objects; trims whitespace and drops entries missing + * either side. Returns `null` when the input is not an array. + */ +function parseSynonyms(value: unknown): Synonym[] | null { + if (!Array.isArray(value)) return null; + const result: Synonym[] = []; + for (const entry of value) { + if (!isRecord(entry)) continue; + const { from, to } = entry; + if (typeof from !== "string" || typeof to !== "string") continue; + const trimmedFrom = from.trim(); + const trimmedTo = to.trim(); + if (!trimmedFrom || !trimmedTo) continue; + result.push({ from: trimmedFrom, to: trimmedTo }); + } + return result; +} + +/** Escape a string for safe use inside a RegExp. */ +function escapeRegex(value: string): string { + return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); +} + +/** + * A synonym rewriter compiled from a synonym set. Holds a single combined + * regex plus the `from` -> `to` lookup so a query can be rewritten in one pass. + */ +export interface SynonymRewriter { + re: RegExp | null; + lookup: Map; +} + +export function compileSynonyms(synonyms: Synonym[]): SynonymRewriter { + // Longer phrases first so multi-word terms win over their sub-words. + const sorted = synonyms.filter((s) => s.from).toSorted((a, b) => b.from.length - a.from.length); + const lookup = new Map(); + for (const s of sorted) { + const key = s.from.toLowerCase(); + if (!lookup.has(key)) lookup.set(key, s.to); + } + if (sorted.length === 0) return { re: null, lookup }; + const pattern = sorted.map((s) => escapeRegex(s.from)).join("|"); + return { + re: new RegExp(`(? rewriter.lookup.get(match.toLowerCase()) ?? match); +} + +const SYNONYM_CACHE_TTL_MS = 60_000; +const SYNONYM_CACHE_KEY = Symbol.for("emdash.ai-search.synonym-cache"); + +interface SynonymCache { + rewriter: SynonymRewriter; + refreshAfter: number; + generation: number; +} + +function synonymCacheHolder(): SynonymCache { + const globals = globalThis as typeof globalThis & { [SYNONYM_CACHE_KEY]?: SynonymCache }; + return (globals[SYNONYM_CACHE_KEY] ??= { + rewriter: compileSynonyms([]), + refreshAfter: 0, + generation: 0, + }); +} + +async function getSynonymRewriter(kv: KVReader): Promise { + const cache = synonymCacheHolder(); + const now = Date.now(); + if (now < cache.refreshAfter) return cache.rewriter; + + const generation = cache.generation; + cache.refreshAfter = now + SYNONYM_CACHE_TTL_MS; + const synonyms = (await kv.get(CONFIG_SYNONYMS_KEY)) ?? []; + if (cache.generation === generation) cache.rewriter = compileSynonyms(synonyms); + + return cache.rewriter; +} + +interface AISearchQueryInput { + query: string; + locale: string; + maxResults?: number; + collection?: string; +} + +interface AISearchSnippetResponse { + search_query: string; + chunks: Array<{ + id: string; + type: string; + score: number; + item: { + key: string; + metadata: { title: string; description: string; image?: string }; + }; + }>; +} + +interface KVReader { + get(key: string): Promise; +} + +function renderResultUrl( + config: AISearchConfig, + result: { collection: string; id: string; slug: string }, + locale: string, +): string { + const template = config.urlTemplates?.[result.collection] ?? "/{collection}/{slug}"; + return template + .replaceAll("{collection}", encodeURIComponent(result.collection)) + .replaceAll("{id}", encodeURIComponent(result.id)) + .replaceAll("{slug}", encodeURIComponent(result.slug)) + .replaceAll("{locale}", encodeURIComponent(locale)); +} + +async function resolveBinding(config: AISearchConfig): Promise { + const env = await getCloudflareEnv(); + if (!env) return null; + const candidate: unknown = Reflect.get(env, config.binding ?? "AI_SEARCH"); + return isAiSearchNamespace(candidate) ? candidate : null; +} + +async function ensureAISearchInstance( + ns: AiSearchNamespace, + config: AISearchConfig, +): Promise { + const instanceName = config.instanceName ?? "emdash-content"; + const handle = ns.get(instanceName); + try { + await handle.info(); + return handle; + } catch (error) { + if (!isMissingAISearchInstanceError(error)) throw error; + } + + try { + return await ns.create({ + id: instanceName, + index_method: { vector: true, keyword: config.hybridSearch ?? true }, + custom_metadata: REQUIRED_CUSTOM_METADATA, + }); + } catch (createError) { + // A concurrent initializer may have won the create; the failure is only + // fatal if the instance still is not there. + try { + await handle.info(); + } catch { + throw createError; + } + return handle; + } +} + +export async function searchAISearch( + config: AISearchConfig, + input: AISearchQueryInput, + kv: KVReader, + defaultLocale: string, +): Promise { + const ns = await resolveBinding(config); + if (!ns) { + throw new PluginRouteError("SEARCH_UNAVAILABLE", "Search is not available", 503); + } + + const effectiveQuery = applySynonyms(input.query, await getSynonymRewriter(kv)); + const instance = await ensureAISearchInstance(ns, config); + const nowSeconds = Math.floor(Date.now() / 1000); + const requestedCollections = parseCollections(input.collection) ?? []; + const folderFilter = + requestedCollections.length === 1 + ? `${requestedCollections[0]!}/` + : requestedCollections.length > 1 + ? { $in: requestedCollections.map((collection) => `${collection}/`) } + : undefined; + + const searchLocale = async (locale: string): Promise => { + const response = await instance.search({ + messages: [{ role: "user", content: effectiveQuery }], + ai_search_options: { + retrieval: { + ...(input.maxResults === undefined ? {} : { max_num_results: input.maxResults }), + filters: { + visible_after: { $lte: nowSeconds }, + locale: { $eq: locale }, + ...(folderFilter === undefined ? {} : { folder: folderFilter }), + }, + metadata_only: true, + }, + }, + }); + + const chunks = + requestedCollections.length === 0 + ? response.chunks + : response.chunks.filter((chunk) => + requestedCollections.some((collection) => chunk.item.key.startsWith(`${collection}/`)), + ); + const bestByKey = new Map(); + for (const chunk of chunks) { + const existing = bestByKey.get(chunk.item.key); + if (!existing || chunk.score > existing.score) bestByKey.set(chunk.item.key, chunk); + } + + return { + search_query: response.search_query, + chunks: Array.from(bestByKey.values(), (chunk) => { + const parsed = parseContentKey(chunk.item.key); + const metadata = chunk.item.metadata ?? {}; + const packed = typeof metadata.title_desc === "string" ? metadata.title_desc : ""; + const { title, description } = unpackTitleDescription(packed); + const slug = typeof metadata.slug === "string" && metadata.slug ? metadata.slug : parsed.id; + const image = + typeof metadata.image === "string" && metadata.image ? metadata.image : undefined; + return { + id: chunk.id, + type: chunk.type, + score: chunk.score, + item: { + key: renderResultUrl(config, { ...parsed, slug }, locale), + metadata: { + title: title || slug, + description, + ...(image ? { image } : {}), + }, + }, + }; + }), + }; + }; + + let response = await searchLocale(input.locale); + if (response.chunks.length === 0 && input.locale !== defaultLocale) { + response = await searchLocale(defaultLocale); + } + return response; +} + +// ============================================================================= +// Descriptor (for astro.config.mjs) +// ============================================================================= + +export function aiSearch(config: AISearchConfig = {}): PluginDescriptor { + return { + id: "ai-search", + version: "1.0.0", + entrypoint: "@emdash-cms/cloudflare/plugins/ai-search", + options: config, + capabilities: ["read:content"], + adminEntry: "@emdash-cms/cloudflare/plugins/ai-search-admin", + adminPages: [{ path: "/settings", label: "Cloudflare AI Search", icon: "search" }], + }; +} + +// ============================================================================= +// Plugin implementation (loaded at runtime via entrypoint) +// ============================================================================= + +export function createPlugin(config: AISearchConfig = {}): ResolvedPlugin { + activeConfigHolder().value = config; + const instanceName = config.instanceName ?? "emdash-content"; + const bindingName = config.binding ?? "AI_SEARCH"; + const hybridSearch = config.hybridSearch ?? true; + + /** + * Read the collections the operator last configured in the dashboard. + * Returns `null` when nothing has been configured yet (never persisted), + * distinct from an explicit empty selection. + */ + async function getConfiguredCollections(ctx: PluginContext): Promise { + const saved = await ctx.kv.get(CONFIG_COLLECTIONS_KEY); + return Array.isArray(saved) ? saved : null; + } + + async function getEffectiveCollections(ctx: PluginContext): Promise { + return (await getConfiguredCollections(ctx)) ?? DEFAULT_COLLECTIONS; + } + + /** Persist the operator's collection selection from the dashboard. */ + async function saveConfiguredCollections( + ctx: PluginContext, + collections: string[], + ): Promise { + await ctx.kv.set(CONFIG_COLLECTIONS_KEY, collections); + } + + /** + * Persist the operator's collection selection and purge every mirrored + * document whose collection is no longer selected. + * + * The selection is stored before any deletion so concurrent content hooks + * stop indexing deselected collections while the purge runs. An explicit + * empty selection therefore removes every mirrored document. + */ + async function applyConfiguredCollections( + ctx: PluginContext, + collections: string[], + ): Promise { + await saveConfiguredCollections(ctx, collections); + + const selected = new Set(collections); + const mirrors = await ctx.kv.list(MIRROR_PREFIX); + const excluded = mirrors + .map((entry) => entry.key.replace(ITEM_PREFIX, "")) + .filter((key) => !selected.has(parseContentKey(key).collection)); + if (excluded.length === 0) return; + + let cursor = 0; + let failures = 0; + await Promise.all( + Array.from({ length: Math.min(PURGE_CONCURRENCY, excluded.length) }, async () => { + // `cursor` advances synchronously between awaits, so each worker + // claims a distinct mirror. + while (cursor < excluded.length) { + const key = excluded[cursor++]!; + try { + const itemId = await ctx.kv.get(`${MIRROR_PREFIX}${key}`); + if (!itemId) continue; + await deleteIndexedItem(key, itemId, ctx); + } catch (error) { + failures++; + console.error(`[ai-search] Failed to remove deselected ${key}:`, error); + } + } + }), + ); + + if (failures > 0) { + throw new PluginRouteError( + "AI_SEARCH_PURGE_FAILED", + `Collections saved, but ${failures} deselected item(s) could not be removed from the index`, + 503, + ); + } + } + + /** Read the query synonyms configured in the dashboard. */ + async function getConfiguredSynonyms(ctx: PluginContext): Promise { + const saved = await ctx.kv.get(CONFIG_SYNONYMS_KEY); + return Array.isArray(saved) ? saved : []; + } + + /** Persist the operator's query synonyms from the dashboard. */ + async function saveConfiguredSynonyms(ctx: PluginContext, synonyms: Synonym[]): Promise { + await ctx.kv.set(CONFIG_SYNONYMS_KEY, synonyms); + const cache = synonymCacheHolder(); + cache.generation++; + cache.rewriter = compileSynonyms(synonyms); + cache.refreshAfter = Date.now() + SYNONYM_CACHE_TTL_MS; + } + + /** + * Whether a content hook should act on the given collection. Content is + * synced only for collections the operator selected in the dashboard, or the + * default collections when no selection has been saved yet. + */ + async function shouldSync(collection: string, ctx: PluginContext): Promise { + return (await getEffectiveCollections(ctx)).includes(collection); + } + + async function getBinding(): Promise { + return resolveBinding(config); + } + + async function ensureInstance(ns: AiSearchNamespace): Promise { + return ensureAISearchInstance(ns, config); + } + + /** + * Index a content item in AI Search. + * + * @param visibleAfter Unix timestamp (seconds) when the content becomes + * visible. Use 0 for already-published content. For scheduled content, + * pass the `scheduled_at` timestamp so the query filter + * `visible_after <= now` excludes it until the scheduled time. + */ + async function indexContent( + content: Record, + collection: string, + ctx: PluginContext, + visibleAfter: number = 0, + ): Promise { + const ns = await getBinding(); + if (!ns) { + console.warn("[ai-search] indexContent: binding not available"); + return; + } + + const key = contentKey(collection, String(content.id)); + try { + const instance = await ensureInstance(ns); + // Hook events nest editable fields under `.data`; flatten so title/body + // extraction matches the reindex path. + const record = flattenContentRecord(content); + const markdown = contentToMarkdown(record, collection); + if (!markdown.trim()) return; + + const slug = typeof record.slug === "string" ? record.slug : ""; + const title = typeof record.title === "string" ? record.title : ""; + const description = contentToDescription(record); + const image = extractImageUrl(record); + const locale = + typeof record.locale === "string" && record.locale + ? record.locale + : (ctx.site?.locale ?? "en"); + + const metadata: Record = { + visible_after: String(visibleAfter), + title_desc: packTitleDescription(title, description), + slug, + locale, + }; + if (image) metadata.image = image; + + await retry(() => uploadItem(instance, key, markdown, metadata, ctx)); + console.log(`[ai-search] Queued ${key}`); + } catch (error) { + console.error("[ai-search] Error indexing content:", error); + } + } + + /** + * Delete one mirrored document from AI Search and drop its KV mirror. + * Throws, so callers decide whether a failure is fatal. + */ + async function deleteIndexedItem(key: string, itemId: string, ctx: PluginContext): Promise { + const ns = await getBinding(); + if (!ns) return; + + const instance = await ensureInstance(ns); + await instance.items.delete(itemId); + // Do not erase a replacement written by a concurrent save/reindex. + if ((await ctx.kv.get(`item:${key}`)) === itemId) { + await ctx.kv.delete(`item:${key}`); + } + console.log(`[ai-search] Removed ${key} (item: ${itemId})`); + } + + /** Remove a content item from the AI Search index. */ + async function removeFromIndex( + collection: string, + id: string, + ctx: PluginContext, + ): Promise { + const key = contentKey(collection, id); + try { + const itemId = await ctx.kv.get(`item:${key}`); + if (!itemId) return; + + await deleteIndexedItem(key, itemId, ctx); + } catch (error) { + console.error("[ai-search] Error removing content:", error); + } + } + + /** + * Synchronize one content item with the public search index based on its + * status. Published content is indexed as immediately visible, scheduled + * content is indexed but gated behind its `visible_after` timestamp, and + * anything else (draft, trashed) is removed from the index. + */ + function syncSearchIndex( + content: Record, + collection: string, + ctx: PluginContext, + ): Promise { + const status = typeof content.status === "string" ? content.status : ""; + if (status === "published") { + return indexContent(content, collection, ctx, 0); + } + if (status === "scheduled") { + return indexContent(content, collection, ctx, getVisibleAfter(content)); + } + return removeFromIndex(collection, String(content.id), ctx); + } + + /** Keep the worker alive until the index write settles, then surface it. */ + function waitForSync(work: Promise): Promise { + cfWaitUntil(work); + return work; + } + + /** Process exactly one content page so every request stays bounded. */ + async function processReindexBatch(job: ReindexJob, ctx: PluginContext) { + if (job.status === "complete") return reindexResult(job); + if (!ctx.content) throw new Error("Content access not available"); + const ns = await getBinding(); + if (!ns) throw new Error("AI Search binding not available"); + const instance = await ensureInstance(ns); + const collection = job.collections[job.collectionIndex]; + if (!collection) { + job.status = "complete"; + await ctx.kv.set(REINDEX_JOB_KEY, job); + return reindexResult(job); + } + + const page = await ctx.content.list(collection, { + limit: REINDEX_PAGE_SIZE, + cursor: job.cursor, + }); + const completedItemKeys = new Set(job.completedItemKeys ?? []); + let checkpointWrites = Promise.resolve(); + + const checkpointAcceptedUpload = async (key: string): Promise => { + job.indexed++; + completedItemKeys.add(key); + job.completedItemKeys = [...completedItemKeys]; + job.updatedAt = new Date().toISOString(); + + // Uploads stay concurrent, while checkpoint writes are serialized so an + // older snapshot cannot overwrite a newer completion out of order. + const snapshot: ReindexJob = { ...job, completedItemKeys: [...completedItemKeys] }; + checkpointWrites = checkpointWrites.then(() => ctx.kv.set(REINDEX_JOB_KEY, snapshot)); + await checkpointWrites; + }; + + await Promise.all( + page.items.map(async (item) => { + const key = contentKey(collection, item.id); + if (completedItemKeys.has(key)) return; + try { + if (item.status !== "published" && item.status !== "scheduled") return; + if (job.onlyMissing && (await ctx.kv.get(`item:${key}`))) { + job.skipped++; + return; + } + + const record = { ...item, ...item.data }; + const markdown = contentToMarkdown(record, collection); + if (!markdown.trim()) { + job.skipped++; + return; + } + + const visibleAfter = getVisibleAfter(record); + if (item.status === "scheduled" && visibleAfter === 0) { + throw new Error("Scheduled content is missing its publication time"); + } + const metadata: Record = { + visible_after: String(visibleAfter), + title_desc: packTitleDescription( + typeof item.data.title === "string" ? item.data.title : "", + contentToDescription(record), + ), + slug: typeof item.slug === "string" ? item.slug : "", + locale: + typeof item.locale === "string" && item.locale + ? item.locale + : (ctx.site?.locale ?? "en"), + }; + const image = extractImageUrl(record); + if (image) metadata.image = image; + await retry(() => uploadItem(instance, key, markdown, metadata, ctx)); + await checkpointAcceptedUpload(key); + } catch (error) { + console.error(`[ai-search] Failed to index ${collection}/${item.id}:`, error); + job.errors++; + } + }), + ); + await checkpointWrites; + + if (page.cursor) { + job.cursor = page.cursor; + } else { + job.collectionIndex++; + delete job.cursor; + if (job.collectionIndex >= job.collections.length) job.status = "complete"; + } + delete job.completedItemKeys; + job.updatedAt = new Date().toISOString(); + await ctx.kv.set(REINDEX_JOB_KEY, job); + return reindexResult(job); + } + + return definePlugin({ + id: "ai-search", + version: "1.0.0", + capabilities: ["read:content"], + admin: { + entry: "@emdash-cms/cloudflare/plugins/ai-search-admin", + pages: [{ path: "/settings", label: "Cloudflare AI Search", icon: "search" }], + }, + + hooks: { + cron: { + // The default five-second plugin hook timeout can expire while a page + // of accepted uploads is still checkpointing. Keep the scheduled event + // alive for the bounded two-page batch; this does not poll for indexing. + timeout: REINDEX_HOOK_TIMEOUT_MS, + handler: async (event, ctx): Promise => { + if (event.name !== REINDEX_CRON_TASK) return; + const job = await ctx.kv.get(REINDEX_JOB_KEY); + if (!job || job.status === "complete") { + await ctx.cron?.cancel(REINDEX_CRON_TASK); + return; + } + + for (let page = 0; page < REINDEX_PAGES_PER_TICK; page++) { + if ((await processReindexBatch(job, ctx)).done) break; + } + if (reindexResult(job).done) await ctx.cron?.cancel(REINDEX_CRON_TASK); + }, + }, + + "content:afterSave": { + handler: async (event: ContentHookEvent, ctx: PluginContext): Promise => { + const { content, collection } = event; + const hasPendingDraft = + content.status === "published" && + typeof content.draftRevisionId === "string" && + content.draftRevisionId !== content.liveRevisionId; + if (hasPendingDraft) return; + if ( + (content.status === "published" || content.status === "scheduled") && + !(await shouldSync(collection, ctx)) + ) + return; + + // Sync based on the current status: published content is visible + // immediately (visible_after=0), scheduled content is indexed but + // gated until its scheduledAt timestamp, and drafts are removed. + return waitForSync(syncSearchIndex(content, collection, ctx)); + }, + }, + + "content:afterPublish": { + handler: async ( + event: ContentPublishStateChangeEvent, + ctx: PluginContext, + ): Promise => { + const { content, collection } = event; + if (!(await shouldSync(collection, ctx))) return; + + return waitForSync(indexContent(content, collection, ctx)); + }, + }, + + "content:afterUnpublish": { + handler: async ( + event: ContentPublishStateChangeEvent, + ctx: PluginContext, + ): Promise => { + const { content, collection } = event; + + return waitForSync(removeFromIndex(collection, String(content.id), ctx)); + }, + }, + + "content:afterSchedule": { + handler: async ( + event: ContentPublishStateChangeEvent, + ctx: PluginContext, + ): Promise => { + const { content, collection } = event; + if (!(await shouldSync(collection, ctx))) return; + + // Index the item with its `visible_after` gate so it stays hidden + // from search results until the scheduled time arrives. + return waitForSync(syncSearchIndex(content, collection, ctx)); + }, + }, + + "content:afterUnschedule": { + handler: async ( + event: ContentPublishStateChangeEvent, + ctx: PluginContext, + ): Promise => { + const { content, collection } = event; + + // Unscheduling returns the item to a draft state — drop it from + // the index. + return waitForSync(removeFromIndex(collection, String(content.id), ctx)); + }, + }, + + "content:afterRestore": { + handler: async ( + event: ContentPublishStateChangeEvent, + ctx: PluginContext, + ): Promise => { + const { content, collection } = event; + if ( + (content.status === "published" || content.status === "scheduled") && + !(await shouldSync(collection, ctx)) + ) + return; + + // Restored content re-enters the index according to its restored + // status (published/scheduled index, otherwise remove). + return waitForSync(syncSearchIndex(content, collection, ctx)); + }, + }, + + "content:afterDelete": { + handler: async (event: ContentDeleteEvent, ctx: PluginContext): Promise => { + const { id, collection } = event; + + return waitForSync(removeFromIndex(collection, id, ctx)); + }, + }, + }, + + routes: { + metadata: { + handler: async (ctx: RouteContext): Promise => { + const method = ctx.request.method.toUpperCase(); + if (method !== "GET" && method !== "POST") { + throw new PluginRouteError("METHOD_NOT_ALLOWED", "Method not allowed", 405); + } + + const ns = await getBinding(); + if (!ns) { + throw new PluginRouteError( + "AI_SEARCH_UNAVAILABLE", + "AI Search binding is not available", + 503, + ); + } + + if (method === "GET") { + try { + const info = await ns.get(instanceName).info(); + return { valid: hasRequiredMetadataSchema(info) }; + } catch (error) { + if (isMissingAISearchInstanceError(error)) return { valid: true }; + throw new PluginRouteError( + "AI_SEARCH_UNAVAILABLE", + "AI Search instance information is not available", + 503, + ); + } + } + + const instance = await ensureInstance(ns); + const valid = hasRequiredMetadataSchema(await instance.info()); + if (!valid) await instance.update({ custom_metadata: REQUIRED_CUSTOM_METADATA }); + return { valid: true }; + }, + }, + + status: { + handler: async (ctx: RouteContext): Promise => { + if (!ctx.content) { + throw new PluginRouteError( + "CONTENT_UNAVAILABLE", + "Content access is not available", + 500, + ); + } + + // Build the set of item keys currently present in the index from the + // KV id-map (`item:{collection}/{id}.md` -> AI Search item id). + const itemEntries = await ctx.kv.list("item:"); + const indexedKeys = new Set(); + for (const entry of itemEntries) { + const key = entry.key.replace(ITEM_PREFIX, "").replace(MD_EXT, ""); + indexedKeys.add(key); + } + + const input = isRecord(ctx.input) ? ctx.input : undefined; + const params = new URL(ctx.request.url).searchParams; + const requested = + typeof input?.collections === "string" + ? input.collections.split(",") + : Array.isArray(input?.collections) + ? input.collections.filter((value): value is string => typeof value === "string") + : (params.get("collections")?.split(",") ?? []); + const trimmed = requested.map((c) => c.trim()).filter(Boolean); + const collections = + trimmed.length > 0 ? trimmed : ((await getConfiguredCollections(ctx)) ?? []); + + const perCollection: Array<{ + collection: string; + eligible: number; + indexed: number; + missing: Array<{ + id: string; + slug: string | null; + title: string | null; + status: string; + }>; + }> = []; + + for (const collection of collections) { + let cursor: string | undefined; + let eligible = 0; + let indexed = 0; + const missing: Array<{ + id: string; + slug: string | null; + title: string | null; + status: string; + }> = []; + try { + do { + const page = await ctx.content.list(collection, { limit: 50, cursor }); + for (const item of page.items) { + const status = typeof item.status === "string" ? item.status : ""; + if (status !== "published" && status !== "scheduled") continue; + eligible++; + if (indexedKeys.has(`${collection}/${item.id}`)) { + indexed++; + } else { + missing.push({ + id: item.id, + slug: item.slug, + title: typeof item.data.title === "string" ? item.data.title : null, + status, + }); + } + } + cursor = page.cursor; + } while (cursor); + perCollection.push({ collection, eligible, indexed, missing }); + } catch (error) { + console.error(`[ai-search] Status failed for ${collection}:`, error); + perCollection.push({ collection, eligible, indexed, missing }); + } + } + + return { + instanceName, + binding: bindingName, + hybridSearch, + totalIndexed: indexedKeys.size, + collections: perCollection, + }; + }, + }, + + // Read or persist the operator's dashboard configuration (indexed + // collections and query synonyms). GET returns the saved config; POST + // updates whichever fields are provided. + config: { + handler: async (ctx: RouteContext): Promise => { + if (ctx.request.method.toUpperCase() === "GET") { + return { + collections: await getEffectiveCollections(ctx), + synonyms: await getConfiguredSynonyms(ctx), + }; + } + + const input = isRecord(ctx.input) ? ctx.input : undefined; + + if (input?.collections !== undefined) { + const collections = parseCollections(input.collections); + if (!collections) { + throw PluginRouteError.badRequest( + "collections must be an array or comma-separated list of collection slugs", + ); + } + await applyConfiguredCollections(ctx, collections); + } + + if (input?.synonyms !== undefined) { + const synonyms = parseSynonyms(input.synonyms); + if (!synonyms) { + throw PluginRouteError.badRequest( + "synonyms must be an array of { from, to } objects", + ); + } + await saveConfiguredSynonyms(ctx, synonyms); + } + + return { + collections: await getEffectiveCollections(ctx), + synonyms: await getConfiguredSynonyms(ctx), + }; + }, + }, + + reindex: { + handler: async (ctx: RouteContext): Promise => { + const current = await ctx.kv.get(REINDEX_JOB_KEY); + if (ctx.request.method.toUpperCase() === "GET") { + return current ? reindexResult(current) : null; + } + if (!ctx.cron) { + throw new PluginRouteError("CRON_UNAVAILABLE", "Cron scheduling is not available", 503); + } + + const input = isRecord(ctx.input) ? ctx.input : undefined; + const requestedJobId = typeof input?.jobId === "string" ? input.jobId : undefined; + if (requestedJobId && current?.id !== requestedJobId) { + throw PluginRouteError.notFound("Reindex job not found"); + } + + let job = current?.status === "running" ? current : null; + if (!job) { + const collections = + parseCollections(input?.collections) ?? (await getEffectiveCollections(ctx)); + if (collections.length === 0) { + throw PluginRouteError.badRequest( + "No collections specified. Select collections in the dashboard first.", + ); + } + await applyConfiguredCollections(ctx, collections); + job = createReindexJob(collections, input?.onlyMissing === true); + await ctx.kv.set(REINDEX_JOB_KEY, job); + } + + await ctx.cron.schedule(REINDEX_CRON_TASK, { schedule: "* * * * *" }); + return reindexResult(job); + }, + }, + }, + }); +} + +export default createPlugin; + +interface SnippetSearchBody { + messages?: Array<{ role?: unknown; content?: unknown }>; + locale?: unknown; + collection?: unknown; + ai_search_options?: { + retrieval?: { + /** Configured in the AI Search backoffice rather than controlled by public clients. */ + max_num_results?: unknown; + }; + }; +} + +interface SnippetHandlerOptions { + config: AISearchConfig; + kv: Pick; + defaultLocale: string; +} + +export async function handleAISearchSnippetRequest( + request: Request, + options: SnippetHandlerOptions, +): Promise { + let body: SnippetSearchBody; + try { + const parsed: unknown = await request.json(); + if (!isRecord(parsed)) throw new Error("Invalid request body"); + body = parsed; + } catch { + return Response.json({ success: false, error: "Invalid request body" }, { status: 400 }); + } + + const query = body.messages?.findLast( + (message) => message.role === "user" && typeof message.content === "string", + )?.content; + if (typeof query !== "string" || !query.trim()) { + return Response.json({ success: true, result: { search_query: "", chunks: [] } }); + } + + const locale = + typeof body.locale === "string" && body.locale ? body.locale : options.defaultLocale; + const collection = + typeof body.collection === "string" && body.collection ? body.collection : undefined; + const maxResults = body.ai_search_options?.retrieval?.max_num_results; + if ( + maxResults !== undefined && + (typeof maxResults !== "number" || + !Number.isInteger(maxResults) || + maxResults < 1 || + maxResults > 50) + ) { + return Response.json( + { success: false, error: "max_num_results must be an integer between 1 and 50" }, + { status: 400 }, + ); + } + + try { + const result = await searchAISearch( + options.config, + { query: query.trim(), locale, maxResults, collection }, + options.kv, + options.defaultLocale, + ); + return Response.json({ success: true, result }); + } catch (error) { + const status = error instanceof PluginRouteError ? error.status : 503; + const message = status === 503 ? "Search is temporarily unavailable" : "Search failed"; + console.error("[ai-search] Snippet search failed:", error); + return Response.json({ success: false, error: message }, { status }); + } +} + +export function createAISearchSnippetEndpoint(config?: AISearchConfig): APIRoute { + return async ({ request }) => { + // The snippet endpoint is public: anonymous site visitors hit it for + // site search. On the anonymous request path `locals.emdash` is the + // partial fast-path facade whose `db` getter is undefined, so reading + // `locals.emdash.db` throws when we load synonyms. Resolve a real, + // request-scoped runtime via withEmDashRuntime() so `runtime.db` works + // regardless of auth. + // + // Imported lazily: `emdash/middleware` references `astro:` virtual + // modules, which the Astro config loader (plain Node ESM) cannot + // resolve. A top-level import would drag that into config evaluation + // via `aiSearch()` and break `astro build`. + const { withEmDashRuntime } = await import("emdash/middleware"); + return withEmDashRuntime(async (runtime: EmDashRuntime) => { + if (!runtime.getPluginRouteMeta("ai-search", "status")) { + return Response.json({ success: false, error: "Search is not available" }, { status: 404 }); + } + const options = new OptionsRepository(runtime.db); + const prefix = "plugin:ai-search:"; + const kv: Pick = { + get: (key: string) => options.get(`${prefix}${key}`), + }; + return handleAISearchSnippetRequest(request, { + config: config ?? getActiveAISearchConfig(), + kv, + defaultLocale: getI18nConfig()?.defaultLocale ?? "en", + }); + }); + }; +} + +export const prerender = false; +export const POST: APIRoute = createAISearchSnippetEndpoint(); diff --git a/packages/cloudflare/src/plugins/index.ts b/packages/cloudflare/src/plugins/index.ts index 84dc964428..b60234d0ef 100644 --- a/packages/cloudflare/src/plugins/index.ts +++ b/packages/cloudflare/src/plugins/index.ts @@ -10,3 +10,4 @@ export { createCloudflareEmailDeliver, type CloudflareEmailConfig, } from "./cloudflare-email.js"; +export { aiSearch, type AISearchConfig } from "./ai-search.js"; diff --git a/packages/cloudflare/tests/plugins/ai-search-endpoint.test.ts b/packages/cloudflare/tests/plugins/ai-search-endpoint.test.ts new file mode 100644 index 0000000000..a1390bec0c --- /dev/null +++ b/packages/cloudflare/tests/plugins/ai-search-endpoint.test.ts @@ -0,0 +1,136 @@ +import { describe, it, expect, vi } from "vitest"; + +const { fakeEnv, controls } = vi.hoisted(() => { + const state = { + pluginEnabled: true, + searchChunks: [] as Array>, + searchRequests: [] as Array>, + }; + const instance = { + info: () => Promise.resolve({ id: "emdash-content" }), + search: (request: Record) => { + state.searchRequests.push(request); + return Promise.resolve({ search_query: "query", chunks: state.searchChunks }); + }, + items: { + upload: () => Promise.resolve({ id: "item-1" }), + delete: () => Promise.resolve(), + }, + }; + const namespace = { + get: () => instance, + create: () => Promise.resolve(instance), + }; + return { fakeEnv: { AI_SEARCH: namespace }, controls: state }; +}); + +vi.mock("cloudflare:workers", () => ({ env: fakeEnv, waitUntil: () => {} })); + +const { optionsConstructedWith } = vi.hoisted(() => ({ + optionsConstructedWith: [] as unknown[], +})); + +vi.mock("emdash", async (importOriginal) => { + const actual = await importOriginal(); + class TrackingOptionsRepository { + constructor(db: unknown) { + optionsConstructedWith.push(db); + if (db === undefined || db === null) { + throw new TypeError("Cannot read properties of undefined (reading 'selectFrom')"); + } + } + async get() { + return null; + } + } + return { ...actual, OptionsRepository: TrackingOptionsRepository }; +}); + +const { runtimeDbHandle } = vi.hoisted(() => ({ runtimeDbHandle: { selectFrom: () => ({}) } })); +vi.mock("emdash/middleware", () => ({ + withEmDashRuntime: async ( + run: (rt: { + db: unknown; + getPluginRouteMeta: (id: string, path: string) => object | null; + }) => unknown, + ) => + run({ + db: runtimeDbHandle, + getPluginRouteMeta: () => (controls.pluginEnabled ? {} : null), + }), +})); + +const { createAISearchSnippetEndpoint } = await import("../../src/plugins/ai-search.js"); + +function anonymousContext(body: unknown) { + return { + request: new Request("https://example.com/api/ai-search/search", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify(body), + }), + locals: { emdash: {} }, + } as never; +} + +describe("createAISearchSnippetEndpoint() on the anonymous request path", () => { + it("does not read locals.emdash.db and succeeds when it is undefined (regression)", async () => { + controls.pluginEnabled = true; + optionsConstructedWith.length = 0; + controls.searchRequests.length = 0; + controls.searchChunks = [ + { + id: "chunk-1", + type: "text", + score: 0.9, + text: "not returned", + item: { key: "posts/post-1.md", metadata: { title_desc: "Hi\u001FA result", slug: "hi" } }, + }, + ]; + + const endpoint = createAISearchSnippetEndpoint(); + const response = await endpoint( + anonymousContext({ messages: [{ role: "user", content: "hi" }] }), + ); + + expect(response.status).toBe(200); + await expect(response.json()).resolves.toMatchObject({ success: true }); + + expect(optionsConstructedWith).toContain(runtimeDbHandle); + expect(optionsConstructedWith).not.toContain(undefined); + }); + + it("still works when locals has no emdash at all", async () => { + controls.pluginEnabled = true; + optionsConstructedWith.length = 0; + controls.searchChunks = []; + const endpoint = createAISearchSnippetEndpoint(); + const ctx = { + request: new Request("https://example.com/api/ai-search/search", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ messages: [{ role: "user", content: "hi" }] }), + }), + locals: {}, + } as never; + + const response = await endpoint(ctx); + expect(response.status).toBe(200); + expect(optionsConstructedWith).toContain(runtimeDbHandle); + }); + + it("does not search when the plugin is disabled", async () => { + controls.pluginEnabled = false; + controls.searchRequests.length = 0; + optionsConstructedWith.length = 0; + const endpoint = createAISearchSnippetEndpoint(); + + const response = await endpoint( + anonymousContext({ messages: [{ role: "user", content: "hi" }] }), + ); + + expect(response.status).toBe(404); + expect(controls.searchRequests).toHaveLength(0); + expect(optionsConstructedWith).toHaveLength(0); + }); +}); diff --git a/packages/cloudflare/tests/plugins/ai-search-indexing.test.ts b/packages/cloudflare/tests/plugins/ai-search-indexing.test.ts new file mode 100644 index 0000000000..9fd74fbac4 --- /dev/null +++ b/packages/cloudflare/tests/plugins/ai-search-indexing.test.ts @@ -0,0 +1,1103 @@ +import type { PluginContext } from "emdash"; +import { describe, it, expect, vi, beforeEach, afterEach } from "vitest"; + +const { uploads, deletions, createConfigs, updates, controls, pendingUploads, fakeEnv } = + vi.hoisted(() => { + const captured: Array<{ + key: string; + content: string; + metadata: Record; + }> = []; + const removed: string[] = []; + const configs: Array> = []; + const instanceUpdates: Array> = []; + const state = { + uploadFailures: 0, + holdUploads: false, + instanceMissing: false, + infoError: null as Error | null, + createError: null as Error | null, + searchError: null as Error | null, + searchChunks: [] as Array>, + searchRequests: [] as Array>, + instanceInfo: { id: "emdash-content" } as Record, + }; + const pending = new Map< + string, + { resolve: (item: { id: string }) => void; reject: (error: Error) => void } + >(); + const instance = { + info: () => { + if (state.infoError) return Promise.reject(state.infoError); + if (!state.instanceMissing) return Promise.resolve(state.instanceInfo); + const error = new Error("ai_search_not_found"); + error.name = "AiSearchNotFoundError"; + return Promise.reject(error); + }, + update: (config: Record) => { + instanceUpdates.push(config); + state.instanceInfo = { ...state.instanceInfo, ...config }; + return Promise.resolve(); + }, + search: (request: Record) => { + state.searchRequests.push(request); + return state.searchError + ? Promise.reject(state.searchError) + : Promise.resolve({ search_query: "query", chunks: state.searchChunks }); + }, + items: { + upload: ( + key: string, + content: string, + options?: { metadata?: Record }, + ) => { + if (state.uploadFailures > 0) { + state.uploadFailures--; + return Promise.reject(new Error("upload failed")); + } + captured.push({ key, content, metadata: options?.metadata ?? {} }); + const item = { id: `item-${captured.length}` }; + if (!state.holdUploads) return Promise.resolve(item); + return new Promise<{ id: string }>((resolve, reject) => { + pending.set(key, { resolve, reject }); + }); + }, + delete: (id: string) => { + removed.push(id); + return Promise.resolve(); + }, + }, + }; + const namespace = { + get: () => instance, + create: (config: Record) => { + configs.push(config); + state.instanceMissing = false; + state.instanceInfo = config; + if (state.createError) return Promise.reject(state.createError); + return Promise.resolve(instance); + }, + }; + return { + uploads: captured, + deletions: removed, + createConfigs: configs, + updates: instanceUpdates, + controls: state, + pendingUploads: pending, + fakeEnv: { AI_SEARCH: namespace }, + }; + }); + +vi.mock("cloudflare:workers", () => ({ env: fakeEnv, waitUntil: () => {} })); + +const { createPlugin, handleAISearchSnippetRequest, unpackTitleDescription } = + await import("../../src/plugins/ai-search.js"); + +function makeContext(content?: PluginContext["content"]): PluginContext { + const store = new Map(); + const kv = { + get: async (key: string) => (store.has(key) ? (store.get(key) as T) : null), + set: async (key: string, value: unknown) => void store.set(key, value), + delete: async (key: string) => void store.delete(key), + list: async (prefix: string) => + [...store.keys()].filter((k) => k.startsWith(prefix)).map((key) => ({ key })), + }; + return { + kv, + content, + cron: { + schedule: vi.fn(), + cancel: vi.fn(), + list: vi.fn().mockResolvedValue([]), + }, + site: { name: "Test", url: "http://localhost", locale: "en" }, + } as unknown as PluginContext; +} + +function routeContext(ctx: PluginContext, input: Record, method = "POST") { + return { + ...ctx, + input, + request: new Request("http://localhost/_emdash/api/plugins/ai-search/reindex", { method }), + }; +} + +function snippetRequest(body: unknown): Request { + return new Request("https://example.com/api/ai-search/search", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify(body), + }); +} + +function snippetOptions(ctx: PluginContext, config = {}) { + return { config, kv: ctx.kv, defaultLocale: "en" }; +} + +async function runReindexCron(plugin: ReturnType, ctx: PluginContext) { + await plugin.hooks.cron!.handler( + { name: "reindex", scheduledAt: "2026-01-01T00:00:00.000Z" }, + ctx, + ); +} + +describe("ai-search reindex jobs", () => { + it("processes two pages per cron tick and resumes from its persisted cursor", async () => { + uploads.length = 0; + const items = Array.from({ length: 101 }, (_, index) => ({ + id: `post-${index}`, + type: "posts", + slug: `post-${index}`, + status: "published", + locale: "en-us", + data: { title: `Post ${index}`, content: `Body ${index}` }, + createdAt: "2026-01-01T00:00:00.000Z", + updatedAt: "2026-01-01T00:00:00.000Z", + publishedAt: "2026-01-01T00:00:00.000Z", + })); + const cursors: Array = []; + const ctx = makeContext({ + get: vi.fn(), + list: async (_collection, options) => { + cursors.push(options?.cursor); + const start = Number(options?.cursor ?? 0); + const next = start + 50; + return { + items: items.slice(start, next), + ...(next < items.length ? { cursor: String(next), hasMore: true } : { hasMore: false }), + }; + }, + } as PluginContext["content"]); + const plugin = createPlugin(); + const handler = plugin.routes.reindex!.handler; + + const started = (await handler( + routeContext(ctx, { collections: ["posts"] }) as never, + )) as Record; + expect(started.done).toBe(false); + expect(started.indexed).toBe(0); + expect(uploads).toHaveLength(0); + + await runReindexCron(plugin, ctx); + const firstTick = (await handler(routeContext(ctx, {}, "GET") as never)) as Record< + string, + unknown + >; + expect(firstTick.done).toBe(false); + expect(firstTick.indexed).toBe(100); + + await runReindexCron(plugin, ctx); + const complete = (await handler(routeContext(ctx, {}, "GET") as never)) as Record< + string, + unknown + >; + expect(complete.done).toBe(true); + expect(complete.indexed).toBe(101); + expect(cursors).toEqual([undefined, "50", "100"]); + }); + + it("uploads a page concurrently and checkpoints each accepted upload", async () => { + uploads.length = 0; + pendingUploads.clear(); + controls.uploadFailures = 0; + controls.holdUploads = true; + const items = Array.from({ length: 3 }, (_, index) => ({ + id: `concurrent-${index}`, + type: "posts", + slug: `concurrent-${index}`, + status: "published", + locale: "en-us", + data: { title: `Concurrent ${index}`, content: `Body ${index}` }, + createdAt: "2026-01-01T00:00:00.000Z", + updatedAt: "2026-01-01T00:00:00.000Z", + publishedAt: "2026-01-01T00:00:00.000Z", + })); + const ctx = makeContext({ + get: vi.fn(), + list: async () => ({ items, hasMore: false }), + } as PluginContext["content"]); + const plugin = createPlugin(); + const handler = plugin.routes.reindex!.handler; + + await handler(routeContext(ctx, { collections: ["posts"] }) as never); + const cron = runReindexCron(plugin, ctx); + + await vi.waitFor(() => expect(pendingUploads.size).toBe(3)); + expect(uploads.map((upload) => upload.key)).toEqual([ + "posts/concurrent-0.md", + "posts/concurrent-1.md", + "posts/concurrent-2.md", + ]); + + pendingUploads.get("posts/concurrent-1.md")!.resolve({ id: "accepted-1" }); + await vi.waitFor(async () => { + const progress = (await handler(routeContext(ctx, {}, "GET") as never)) as Record< + string, + unknown + >; + expect(progress.indexed).toBe(1); + }); + + pendingUploads.get("posts/concurrent-0.md")!.resolve({ id: "accepted-0" }); + pendingUploads.get("posts/concurrent-2.md")!.resolve({ id: "accepted-2" }); + await cron; + controls.holdUploads = false; + + const complete = (await handler(routeContext(ctx, {}, "GET") as never)) as Record< + string, + unknown + >; + expect(complete.done).toBe(true); + expect(complete.indexed).toBe(3); + }); + + it("overwrites an item already mirrored by EmDash without deleting it first", async () => { + uploads.length = 0; + deletions.length = 0; + controls.uploadFailures = 0; + const ctx = makeContext({ + get: vi.fn(), + list: async () => ({ + items: [ + { + id: "existing", + type: "posts", + slug: "existing", + status: "published", + locale: "en-us", + data: { title: "Existing", content: "Updated body" }, + createdAt: "2026-01-01T00:00:00.000Z", + updatedAt: "2026-01-01T00:00:00.000Z", + publishedAt: "2026-01-01T00:00:00.000Z", + }, + ], + hasMore: false, + }), + } as PluginContext["content"]); + await ctx.kv.set("item:posts/existing.md", "old-item-id"); + const plugin = createPlugin(); + const handler = plugin.routes.reindex!.handler; + + await handler(routeContext(ctx, { collections: ["posts"] }) as never); + await runReindexCron(plugin, ctx); + + expect(uploads).toHaveLength(1); + expect(uploads[0]?.key).toBe("posts/existing.md"); + expect(deletions).toHaveLength(0); + expect(await ctx.kv.get("item:posts/existing.md")).toBe("item-1"); + }); + + it("preserves the mirrored item when replacement uploads exhaust their retries", async () => { + uploads.length = 0; + deletions.length = 0; + controls.uploadFailures = 3; + const ctx = makeContext({ + get: vi.fn(), + list: async () => ({ + items: [ + { + id: "broken", + type: "posts", + slug: "broken", + status: "published", + locale: "en-us", + data: { title: "Broken", content: "Body" }, + createdAt: "2026-01-01T00:00:00.000Z", + updatedAt: "2026-01-01T00:00:00.000Z", + publishedAt: "2026-01-01T00:00:00.000Z", + }, + ], + hasMore: false, + }), + } as PluginContext["content"]); + await ctx.kv.set("item:posts/broken.md", "old-item-id"); + const plugin = createPlugin(); + const handler = plugin.routes.reindex!.handler; + + await handler(routeContext(ctx, { collections: ["posts"] }) as never); + await runReindexCron(plugin, ctx); + + expect(deletions).toHaveLength(0); + expect(await ctx.kv.get("item:posts/broken.md")).toBe("old-item-id"); + }); +}); + +describe("AI Search snippet endpoint", () => { + it("returns metadata-only snippet results using configured URL templates", async () => { + controls.searchRequests.length = 0; + controls.searchChunks = [ + { + id: "chunk-1", + type: "text", + score: 0.9, + text: "not returned", + item: { + key: "posts/post-1.md", + timestamp: 123, + metadata: { + title_desc: "Hello\u001FA useful result", + slug: "hello", + }, + }, + }, + ]; + const ctx = makeContext(); + const response = await handleAISearchSnippetRequest( + snippetRequest({ + messages: [{ role: "user", content: "hello" }], + locale: "fr", + ai_search_options: { retrieval: { max_num_results: 5 } }, + }), + snippetOptions(ctx, { urlTemplates: { posts: "/writing/{slug}?lang={locale}" } }), + ); + + expect(response.status).toBe(200); + expect(controls.searchRequests.at(-1)).toMatchObject({ + ai_search_options: { + retrieval: { + max_num_results: 5, + metadata_only: true, + filters: { locale: { $eq: "fr" } }, + }, + }, + }); + const body = (await response.json()) as { + result: { chunks: Array<{ item: Record }> }; + }; + expect(body).toMatchObject({ + success: true, + result: { + chunks: [ + { + item: { + key: "/writing/hello?lang=fr", + metadata: { + title: "Hello", + description: "A useful result", + }, + }, + }, + ], + }, + }); + expect(body.result.chunks[0]?.item).not.toHaveProperty("timestamp"); + }); + + it.each([0, 51, 1.5, "5"])("rejects invalid max_num_results value %j", async (value) => { + const response = await handleAISearchSnippetRequest( + snippetRequest({ + messages: [{ role: "user", content: "hello" }], + ai_search_options: { retrieval: { max_num_results: value } }, + }), + snippetOptions(makeContext()), + ); + + expect(response.status).toBe(400); + await expect(response.json()).resolves.toEqual({ + success: false, + error: "max_num_results must be an integer between 1 and 50", + }); + }); + + it("pushes one collection into the folder filter and excludes mismatched upstream results", async () => { + controls.searchRequests.length = 0; + controls.searchChunks = [ + { + id: "chunk-from-another-folder", + type: "text", + score: 0.9, + text: "", + item: { + key: "pages/page-1.md", + timestamp: 123, + metadata: { title_desc: "Page\u001FDescription", slug: "page-1" }, + }, + }, + ]; + const ctx = makeContext(); + + const response = await handleAISearchSnippetRequest( + snippetRequest({ + messages: [{ role: "user", content: "query" }], + collection: " posts ", + }), + snippetOptions(ctx), + ); + + expect(controls.searchRequests.at(-1)).toMatchObject({ + ai_search_options: { retrieval: { filters: { folder: "posts/" } } }, + }); + const body = (await response.json()) as { result: { chunks: Array> } }; + expect(body.result.chunks).toHaveLength(0); + }); + + it("pushes multiple collections into a built-in folder $in filter", async () => { + controls.searchRequests.length = 0; + controls.searchChunks = []; + const ctx = makeContext(); + + await handleAISearchSnippetRequest( + snippetRequest({ + messages: [{ role: "user", content: "query" }], + collection: "posts, pages", + }), + snippetOptions(ctx), + ); + + expect(controls.searchRequests.at(-1)).toMatchObject({ + ai_search_options: { + retrieval: { filters: { folder: { $in: ["posts/", "pages/"] } } }, + }, + }); + }); + + it("refreshes synonyms at most once per minute", async () => { + vi.useFakeTimers({ toFake: ["Date"] }); + vi.setSystemTime(new Date("2100-01-01T00:00:00.000Z")); + try { + const ctx = makeContext(); + const plugin = createPlugin(); + await plugin.routes.config!.handler( + routeContext(ctx, { synonyms: [{ from: "autorag", to: "AI Search" }] }) as never, + ); + const get = vi.spyOn(ctx.kv, "get"); + + await handleAISearchSnippetRequest( + snippetRequest({ messages: [{ role: "user", content: "autorag" }] }), + snippetOptions(ctx), + ); + await handleAISearchSnippetRequest( + snippetRequest({ messages: [{ role: "user", content: "autorag" }] }), + snippetOptions(ctx), + ); + + expect(get).toHaveBeenCalledTimes(0); + expect(controls.searchRequests.at(-1)).toMatchObject({ + messages: [{ role: "user", content: "AI Search" }], + }); + + vi.advanceTimersByTime(60_001); + await handleAISearchSnippetRequest( + snippetRequest({ messages: [{ role: "user", content: "autorag" }] }), + snippetOptions(ctx), + ); + expect(get).toHaveBeenCalledTimes(1); + } finally { + vi.useRealTimers(); + } + }); + + it("uses newly saved synonyms immediately in the same isolate", async () => { + vi.useFakeTimers({ toFake: ["Date"] }); + vi.setSystemTime(new Date("2100-06-01T00:00:00.000Z")); + try { + const ctx = makeContext(); + const plugin = createPlugin(); + await plugin.routes.config!.handler( + routeContext(ctx, { synonyms: [{ from: "autorag", to: "old term" }] }) as never, + ); + await handleAISearchSnippetRequest( + snippetRequest({ messages: [{ role: "user", content: "autorag" }] }), + snippetOptions(ctx), + ); + + await plugin.routes.config!.handler( + routeContext(ctx, { synonyms: [{ from: "autorag", to: "new term" }] }) as never, + ); + await handleAISearchSnippetRequest( + snippetRequest({ messages: [{ role: "user", content: "autorag" }] }), + snippetOptions(ctx), + ); + + expect(controls.searchRequests.at(-1)).toMatchObject({ + messages: [{ role: "user", content: "new term" }], + }); + } finally { + vi.useRealTimers(); + } + }); + + it("does not let a stale in-flight refresh overwrite newly saved synonyms", async () => { + vi.useFakeTimers({ toFake: ["Date"] }); + vi.setSystemTime(new Date("2100-09-01T00:00:00.000Z")); + const ctx = makeContext(); + const plugin = createPlugin(); + await plugin.routes.config!.handler( + routeContext(ctx, { synonyms: [{ from: "autorag", to: "old term" }] }) as never, + ); + vi.advanceTimersByTime(60_001); + + const originalGet = ctx.kv.get.bind(ctx.kv); + let releaseRead!: () => void; + const readGate = new Promise((resolve) => { + releaseRead = resolve; + }); + let blockRefresh = true; + const get = vi.spyOn(ctx.kv, "get").mockImplementation(async (key: string) => { + if (key !== "config:synonyms" || !blockRefresh) return originalGet(key); + blockRefresh = false; + const staleValue = await originalGet(key); + await readGate; + return staleValue; + }); + + const staleSearch = handleAISearchSnippetRequest( + snippetRequest({ messages: [{ role: "user", content: "autorag" }] }), + snippetOptions(ctx), + ); + await vi.waitFor(() => expect(get).toHaveBeenCalledTimes(1)); + await plugin.routes.config!.handler( + routeContext(ctx, { synonyms: [{ from: "autorag", to: "new term" }] }) as never, + ); + + try { + releaseRead(); + await staleSearch; + await handleAISearchSnippetRequest( + snippetRequest({ messages: [{ role: "user", content: "autorag" }] }), + snippetOptions(ctx), + ); + expect(controls.searchRequests.at(-1)).toMatchObject({ + messages: [{ role: "user", content: "new term" }], + }); + } finally { + vi.useRealTimers(); + } + }); + + it("coalesces concurrent synonym refreshes", async () => { + vi.useFakeTimers({ toFake: ["Date"] }); + vi.setSystemTime(new Date("2101-01-01T00:00:00.000Z")); + const ctx = makeContext(); + const plugin = createPlugin(); + await plugin.routes.config!.handler( + routeContext(ctx, { synonyms: [{ from: "autorag", to: "AI Search" }] }) as never, + ); + vi.advanceTimersByTime(60_001); + const originalGet = ctx.kv.get.bind(ctx.kv); + let releaseRead!: () => void; + const readGate = new Promise((resolve) => { + releaseRead = resolve; + }); + const get = vi.spyOn(ctx.kv, "get").mockImplementation(async (key: string) => { + await readGate; + return originalGet(key); + }); + const searchCount = controls.searchRequests.length; + + const first = handleAISearchSnippetRequest( + snippetRequest({ messages: [{ role: "user", content: "autorag" }] }), + snippetOptions(ctx), + ); + await vi.waitFor(() => expect(get).toHaveBeenCalledTimes(1)); + const second = handleAISearchSnippetRequest( + snippetRequest({ messages: [{ role: "user", content: "autorag" }] }), + snippetOptions(ctx), + ); + await vi.waitFor(() => expect(controls.searchRequests.length).toBeGreaterThan(searchCount)); + expect(get).toHaveBeenCalledTimes(1); + + try { + releaseRead(); + await Promise.all([first, second]); + } finally { + vi.useRealTimers(); + } + }); +}); + +describe("ai-search endpoint and route errors", () => { + it("uses structured errors instead of successful error payloads", async () => { + const plugin = createPlugin(); + const ctx = makeContext(); + + await expect( + plugin.routes.config!.handler(routeContext(ctx, { collections: 42 }) as never), + ).rejects.toMatchObject({ status: 400, code: "BAD_REQUEST" }); + }); + + it("does not expose an upstream search error through the snippet endpoint", async () => { + controls.searchError = new Error("secret upstream details"); + const ctx = makeContext(); + + const response = await handleAISearchSnippetRequest( + snippetRequest({ messages: [{ role: "user", content: "query" }] }), + snippetOptions(ctx), + ); + expect(response.status).toBe(503); + await expect(response.json()).resolves.toEqual({ + success: false, + error: "Search is temporarily unavailable", + }); + controls.searchError = null; + }); + + it("reports unavailable cron scheduling and unknown jobs with structured errors", async () => { + const plugin = createPlugin(); + const withoutCron = makeContext(); + delete (withoutCron as { cron?: unknown }).cron; + + await expect( + plugin.routes.reindex!.handler( + routeContext(withoutCron, { collections: ["posts"] }) as never, + ), + ).rejects.toMatchObject({ status: 503 }); + + const ctx = makeContext(); + await expect( + plugin.routes.reindex!.handler(routeContext(ctx, { jobId: "missing" }) as never), + ).rejects.toMatchObject({ status: 404, code: "NOT_FOUND" }); + }); +}); + +describe("ai-search collection configuration", () => { + it("returns effective defaults without persisting them", async () => { + const plugin = createPlugin(); + const ctx = makeContext(); + + await expect( + plugin.routes.config!.handler(routeContext(ctx, {}, "GET") as never), + ).resolves.toMatchObject({ collections: ["posts", "pages"] }); + await expect(ctx.kv.get("config:collections")).resolves.toBeNull(); + }); + + it("preserves an explicitly empty collection selection", async () => { + const plugin = createPlugin(); + const ctx = makeContext(); + + await plugin.routes.config!.handler(routeContext(ctx, { collections: [] }) as never); + + await expect( + plugin.routes.config!.handler(routeContext(ctx, {}, "GET") as never), + ).resolves.toMatchObject({ collections: [] }); + }); + + it("removes already-indexed items of a deselected collection", async () => { + uploads.length = 0; + deletions.length = 0; + createConfigs.length = 0; + controls.uploadFailures = 0; + controls.holdUploads = false; + controls.instanceMissing = false; + const plugin = createPlugin(); + const ctx = makeContext(); + + const index = async (collection: string, id: string) => { + await plugin.hooks["content:afterSave"]!.handler( + { + content: { + id, + slug: id, + status: "published", + locale: "en", + data: { title: `Title ${id}`, body: `Body ${id}` }, + }, + collection, + isNew: true, + }, + ctx, + ); + }; + + await index("posts", "stale-post"); + await index("pages", "kept-page"); + const staleItemId = await ctx.kv.get("item:posts/stale-post.md"); + const keptItemId = await ctx.kv.get("item:pages/kept-page.md"); + expect(staleItemId).toBeTruthy(); + expect(keptItemId).toBeTruthy(); + + await plugin.routes.config!.handler(routeContext(ctx, { collections: ["pages"] }) as never); + + expect(deletions).toEqual([staleItemId]); + await expect(ctx.kv.get("item:posts/stale-post.md")).resolves.toBeNull(); + await expect(ctx.kv.get("item:pages/kept-page.md")).resolves.toBe(keptItemId); + }); +}); + +describe("ai-search metadata schema route", () => { + const requiredSchema = [ + { field_name: "visible_after", data_type: "number" }, + { field_name: "title_desc", data_type: "text" }, + { field_name: "slug", data_type: "text" }, + { field_name: "image", data_type: "text" }, + { field_name: "locale", data_type: "text" }, + ]; + + it("reports a bare existing instance as invalid without mutating it", async () => { + createConfigs.length = 0; + updates.length = 0; + controls.instanceInfo = { id: "emdash-content" }; + const plugin = createPlugin(); + const ctx = makeContext(); + + await expect( + plugin.routes.metadata!.handler(routeContext(ctx, {}, "GET") as never), + ).resolves.toEqual({ valid: false }); + expect(updates).toHaveLength(0); + expect(createConfigs).toHaveLength(0); + }); + + it("treats Cloudflare's ai_search_not_found error as valid without creating or updating the instance", async () => { + createConfigs.length = 0; + updates.length = 0; + controls.instanceMissing = true; + const plugin = createPlugin(); + + try { + await expect( + plugin.routes.metadata!.handler(routeContext(makeContext(), {}, "GET") as never), + ).resolves.toEqual({ valid: true }); + expect(createConfigs).toHaveLength(0); + expect(updates).toHaveLength(0); + } finally { + controls.instanceMissing = false; + } + }); + + it("rejects unsupported methods without repairing the instance", async () => { + createConfigs.length = 0; + updates.length = 0; + controls.instanceInfo = { id: "emdash-content", custom_metadata: [] }; + const plugin = createPlugin(); + + await expect( + plugin.routes.metadata!.handler(routeContext(makeContext(), {}, "PUT") as never), + ).rejects.toMatchObject({ status: 405, code: "METHOD_NOT_ALLOWED" }); + expect(createConfigs).toHaveLength(0); + expect(updates).toHaveLength(0); + }); + + it("does not mutate a bare existing instance during normal search", async () => { + updates.length = 0; + controls.instanceInfo = { id: "emdash-content" }; + controls.searchChunks = []; + + await handleAISearchSnippetRequest( + snippetRequest({ messages: [{ role: "user", content: "query" }] }), + snippetOptions(makeContext()), + ); + + expect(updates).toHaveLength(0); + }); + + it("updates an invalid instance to the required schema", async () => { + updates.length = 0; + controls.instanceInfo = { id: "emdash-content", custom_metadata: [] }; + const plugin = createPlugin(); + const ctx = makeContext(); + + await expect( + plugin.routes.metadata!.handler(routeContext(ctx, {}, "POST") as never), + ).resolves.toEqual({ valid: true }); + expect(updates).toEqual([{ custom_metadata: requiredSchema }]); + }); + + it("accepts an equivalent schema in a different order without updating it", async () => { + updates.length = 0; + controls.instanceInfo = { + id: "emdash-content", + custom_metadata: requiredSchema.toReversed(), + }; + const plugin = createPlugin(); + const ctx = makeContext(); + + await expect( + plugin.routes.metadata!.handler(routeContext(ctx, {}, "POST") as never), + ).resolves.toEqual({ valid: true }); + expect(updates).toHaveLength(0); + }); + + it("returns a structured 503 when the binding is missing", async () => { + const binding = fakeEnv.AI_SEARCH; + Reflect.deleteProperty(fakeEnv, "AI_SEARCH"); + try { + const plugin = createPlugin(); + await expect( + plugin.routes.metadata!.handler(routeContext(makeContext(), {}, "GET") as never), + ).rejects.toMatchObject({ status: 503, code: "AI_SEARCH_UNAVAILABLE" }); + } finally { + fakeEnv.AI_SEARCH = binding; + } + }); +}); + +describe("ai-search content:afterSave indexing", () => { + it("uses the effective default collections before configuration is saved", async () => { + uploads.length = 0; + const plugin = createPlugin(); + + await plugin.hooks["content:afterSave"]!.handler( + { + content: { + id: "product", + slug: "product", + status: "published", + data: { title: "Product" }, + }, + collection: "products", + isNew: true, + }, + makeContext(), + ); + + expect(uploads).toHaveLength(0); + }); + + it("creates new instances with the current index_method configuration", async () => { + uploads.length = 0; + createConfigs.length = 0; + controls.instanceMissing = true; + const plugin = createPlugin({ hybridSearch: true }); + const ctx = makeContext(); + + await plugin.hooks["content:afterSave"]!.handler( + { + content: { + id: "create-instance", + slug: "create-instance", + status: "published", + locale: "en", + data: { title: "Create instance", body: "Body" }, + }, + collection: "posts", + isNew: true, + }, + ctx, + ); + + expect(createConfigs).toHaveLength(1); + expect(createConfigs[0]).toMatchObject({ + index_method: { vector: true, keyword: true }, + custom_metadata: [ + { field_name: "visible_after", data_type: "number" }, + { field_name: "title_desc", data_type: "text" }, + { field_name: "slug", data_type: "text" }, + { field_name: "image", data_type: "text" }, + { field_name: "locale", data_type: "text" }, + ], + }); + expect(createConfigs[0]).not.toHaveProperty("hybrid_search_enabled"); + controls.instanceMissing = false; + }); + it("indexes the real title and body from the hook's `.data` payload", async () => { + uploads.length = 0; + const plugin = createPlugin(); + const ctx = makeContext(); + + await plugin.hooks["content:afterSave"]!.handler( + { + content: { + id: "01H", + slug: "hello-world", + status: "published", + locale: "fr", + data: { title: "Hello World", body: "The quick brown fox jumps over the lazy dog" }, + }, + collection: "posts", + isNew: true, + }, + ctx, + ); + + expect(uploads).toHaveLength(1); + const [uploaded] = uploads; + const { title, description } = unpackTitleDescription(String(uploaded!.metadata.title_desc)); + + expect(title).toBe("Hello World"); + expect(description).toBe(""); + expect(uploaded!.content).toContain("Hello World"); + expect(uploaded!.content).toContain("quick brown fox"); + expect(uploaded!.metadata.locale).toBe("fr"); + expect(uploaded!.metadata.slug).toBe("hello-world"); + }); + + it("uses the excerpt and featured image without indexing system metadata", async () => { + uploads.length = 0; + const plugin = createPlugin(); + const ctx = makeContext(); + + await plugin.hooks["content:afterSave"]!.handler( + { + content: { + id: "01POST", + slug: "threat-intel", + status: "published", + authorId: "01AUTHOR", + createdAt: "2026-06-08T13:00:03.516Z", + updatedAt: "2026-06-08T14:00:00.000Z", + locale: "en-us", + translationGroup: "01GROUP", + data: { + title: "Threat intelligence", + excerpt: "The exact article excerpt.", + content: "The full article body.", + secondaryImage: { src: "https://example.com/secondary.png" }, + featured_image: { + meta: { storageKey: "featured.png" }, + }, + }, + }, + collection: "posts", + isNew: false, + }, + ctx, + ); + + expect(uploads).toHaveLength(1); + const [uploaded] = uploads; + const { description } = unpackTitleDescription(String(uploaded!.metadata.title_desc)); + + expect(description).toBe("The exact article excerpt."); + expect(uploaded!.metadata.image).toBe("/_emdash/api/media/file/featured.png"); + expect(uploaded!.content).toContain("The full article body."); + expect(uploaded!.content).not.toContain("01AUTHOR"); + expect(uploaded!.content).not.toContain("2026-06-08T13:00:03.516Z"); + expect(uploaded!.content).not.toContain("01GROUP"); + }); + + it("does not index a pending draft for published content", async () => { + uploads.length = 0; + const plugin = createPlugin(); + const ctx = makeContext(); + + await plugin.hooks["content:afterSave"]!.handler( + { + content: { + id: "published-with-draft", + slug: "published-with-draft", + status: "published", + liveRevisionId: "live-revision", + draftRevisionId: "draft-revision", + data: { title: "Unpublished title", body: "Unpublished body" }, + liveData: { title: "Published title", body: "Published body" }, + }, + collection: "posts", + isNew: false, + }, + ctx, + ); + + expect(uploads).toHaveLength(0); + }); + + it("removes non-public content even when its collection is deselected", async () => { + deletions.length = 0; + const plugin = createPlugin(); + const ctx = makeContext(); + await plugin.routes.config!.handler(routeContext(ctx, { collections: ["pages"] }) as never); + for (const id of ["saved-draft", "restored-draft"]) { + await ctx.kv.set(`item:posts/${id}.md`, `item-${id}`); + } + + await plugin.hooks["content:afterSave"]!.handler( + { + content: { id: "saved-draft", slug: "saved-draft", status: "draft", data: {} }, + collection: "posts", + isNew: false, + }, + ctx, + ); + await plugin.hooks["content:afterRestore"]!.handler( + { + content: { id: "restored-draft", slug: "restored-draft", status: "draft", data: {} }, + collection: "posts", + } as never, + ctx, + ); + + expect(deletions).toEqual(["item-saved-draft", "item-restored-draft"]); + }); + + it("always removes unpublished, unscheduled, and deleted content from deselected collections", async () => { + deletions.length = 0; + const plugin = createPlugin(); + const ctx = makeContext(); + await plugin.routes.config!.handler(routeContext(ctx, { collections: ["pages"] }) as never); + for (const id of ["unpublished", "unscheduled", "deleted"]) { + await ctx.kv.set(`item:posts/${id}.md`, `item-${id}`); + } + + await plugin.hooks["content:afterUnpublish"]!.handler( + { content: { id: "unpublished" }, collection: "posts" } as never, + ctx, + ); + await plugin.hooks["content:afterUnschedule"]!.handler( + { content: { id: "unscheduled" }, collection: "posts" } as never, + ctx, + ); + await plugin.hooks["content:afterDelete"]!.handler( + { id: "deleted", collection: "posts" } as never, + ctx, + ); + + expect(deletions).toEqual(["item-unpublished", "item-unscheduled", "item-deleted"]); + }); + + it("still gates public additions when a collection is deselected", async () => { + uploads.length = 0; + const plugin = createPlugin(); + const ctx = makeContext(); + await plugin.routes.config!.handler(routeContext(ctx, { collections: ["pages"] }) as never); + + await plugin.hooks["content:afterSave"]!.handler( + { + content: { + id: "published", + slug: "published", + status: "published", + data: { title: "Published" }, + }, + collection: "posts", + isNew: true, + }, + ctx, + ); + + expect(uploads).toHaveLength(0); + }); +}); + +describe("ai-search instance creation", () => { + beforeEach(() => { + createConfigs.length = 0; + controls.searchChunks = []; + controls.searchError = null; + controls.infoError = null; + controls.createError = null; + controls.instanceMissing = false; + controls.instanceInfo = { id: "emdash-content" }; + }); + + afterEach(() => { + controls.infoError = null; + controls.createError = null; + controls.instanceMissing = false; + controls.instanceInfo = { id: "emdash-content" }; + }); + + it("does not create an instance when the info probe fails transiently", async () => { + controls.infoError = new Error("internal error"); + + const response = await handleAISearchSnippetRequest( + snippetRequest({ messages: [{ role: "user", content: "query" }] }), + snippetOptions(makeContext()), + ); + + expect(response.status).toBe(503); + expect(createConfigs).toHaveLength(0); + }); + + it("searches successfully after losing a concurrent create race", async () => { + controls.instanceMissing = true; + controls.createError = new Error("instance already exists"); + + const response = await handleAISearchSnippetRequest( + snippetRequest({ messages: [{ role: "user", content: "query" }] }), + snippetOptions(makeContext()), + ); + + expect(response.status).toBe(200); + expect(createConfigs).toHaveLength(1); + }); +}); diff --git a/packages/cloudflare/tests/plugins/ai-search.test.ts b/packages/cloudflare/tests/plugins/ai-search.test.ts new file mode 100644 index 0000000000..c8d39ce1b2 --- /dev/null +++ b/packages/cloudflare/tests/plugins/ai-search.test.ts @@ -0,0 +1,134 @@ +import { describe, it, expect } from "vitest"; + +import { + applySynonyms, + compileSynonyms, + flattenContentRecord, + packTitleDescription, + unpackTitleDescription, +} from "../../src/plugins/ai-search.js"; + +describe("packTitleDescription() / unpackTitleDescription()", () => { + it("round-trips a normal title and multi-word description", () => { + const packed = packTitleDescription("My Post", "A short summary of the post"); + expect(unpackTitleDescription(packed)).toEqual({ + title: "My Post", + description: "A short summary of the post", + }); + }); + + it("handles an empty description", () => { + expect(unpackTitleDescription(packTitleDescription("Hello", ""))).toEqual({ + title: "Hello", + description: "", + }); + }); + + it("handles an empty title", () => { + expect(unpackTitleDescription(packTitleDescription("", "some desc"))).toEqual({ + title: "", + description: "some desc", + }); + }); + + it("handles both empty", () => { + expect(unpackTitleDescription(packTitleDescription("", ""))).toEqual({ + title: "", + description: "", + }); + }); + + it("preserves a separator inside the description (splits on first only)", () => { + expect(unpackTitleDescription(packTitleDescription("T", "a\u001Fb"))).toEqual({ + title: "T", + description: "a\u001Fb", + }); + }); + + it("treats a value with no separator as a bare title", () => { + expect(unpackTitleDescription("legacy raw string")).toEqual({ + title: "legacy raw string", + description: "", + }); + }); + + it("unpacks an empty string", () => { + expect(unpackTitleDescription("")).toEqual({ title: "", description: "" }); + }); + + it("round-trips unicode titles and punctuation descriptions exactly", () => { + const title = "Café ☕ del Mar — Título"; + const description = "Well, hello! (yes) — it's here: 100%."; + expect(unpackTitleDescription(packTitleDescription(title, description))).toEqual({ + title, + description, + }); + }); + + it("caps the packed metadata at 500 characters by truncating the description", () => { + const title = "T".repeat(165); + const description = "description ".repeat(40).trim(); + const packed = packTitleDescription(title, description); + const unpacked = unpackTitleDescription(packed); + + expect(packed.length).toBeLessThanOrEqual(500); + expect(unpacked.title).toBe(title); + expect(unpacked.description.length).toBeLessThan(description.length); + expect(unpacked.description).toMatch(/…$/); + }); + + it("keeps the separator within the limit when the title consumes the budget", () => { + const title = "T".repeat(499); + const packed = packTitleDescription(title, "No room for this description"); + + expect(packed).toHaveLength(500); + expect(unpackTitleDescription(packed)).toEqual({ title, description: "" }); + }); +}); + +describe("compileSynonyms() / applySynonyms()", () => { + it("rewrites whole words case-insensitively", () => { + const rewriter = compileSynonyms([{ from: "autorag", to: "AI Search" }]); + + expect(applySynonyms("What is AutoRAG?", rewriter)).toBe("What is AI Search?"); + expect(applySynonyms("autoragged", rewriter)).toBe("autoragged"); + }); + + it("prefers longer phrases and escapes regular-expression characters", () => { + const rewriter = compileSynonyms([ + { from: "AI", to: "artificial intelligence" }, + { from: "AI Search", to: "AutoRAG" }, + { from: "C++", to: "C plus plus" }, + ]); + + expect(applySynonyms("AI Search and C++", rewriter)).toBe("AutoRAG and C plus plus"); + }); + + it("returns the original query when no synonyms are configured", () => { + expect(applySynonyms("unchanged", compileSynonyms([]))).toBe("unchanged"); + }); +}); + +describe("flattenContentRecord()", () => { + it("lifts editable fields out of `.data` (the content-hook shape)", () => { + const hookContent = { + id: "01H", + slug: "hello-world", + status: "published", + locale: "fr", + data: { title: "Bonjour le monde", body: "Le renard brun rapide" }, + }; + const record = flattenContentRecord(hookContent); + expect(record.title).toBe("Bonjour le monde"); + expect(record.body).toBe("Le renard brun rapide"); + // System columns at the top level are preserved. + expect(record.slug).toBe("hello-world"); + expect(record.status).toBe("published"); + expect(record.locale).toBe("fr"); + }); + + it("is a no-op when there is no `.data` object", () => { + expect(flattenContentRecord({ id: "1", title: "Flat" })).toEqual({ id: "1", title: "Flat" }); + expect(flattenContentRecord({ id: "1", data: null })).toEqual({ id: "1", data: null }); + }); +}); diff --git a/packages/cloudflare/tsdown.config.ts b/packages/cloudflare/tsdown.config.ts index e6f8419a79..8c80350644 100644 --- a/packages/cloudflare/tsdown.config.ts +++ b/packages/cloudflare/tsdown.config.ts @@ -19,6 +19,9 @@ export default defineConfig({ // as their `entrypoint`, so the astro integration can statically import // `createPlugin` from it (#1721). "src/plugins/cloudflare-email.ts", + "src/plugins/ai-search.ts", + "src/plugins/ai-search-admin.tsx", + // Media provider runtimes "src/media/images-runtime.ts", "src/media/stream-runtime.ts", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index e2fdeeb538..83fd601201 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -433,6 +433,9 @@ importers: '@astrojs/react': specifier: 'catalog:' version: 6.0.0(@types/node@24.10.13)(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(esbuild@0.28.1)(jiti@2.7.0)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(tsx@4.21.0)(yaml@2.9.0) + '@cloudflare/ai-search-snippet': + specifier: ^0.0.40 + version: 0.0.40 '@emdash-cms/cloudflare': specifier: workspace:* version: link:../../packages/cloudflare @@ -1563,6 +1566,9 @@ importers: packages/cloudflare: dependencies: + '@cloudflare/ai-search-snippet': + specifier: ^0.0.42 + version: 0.0.42 astro: specifier: '>=6.0.0-beta.0' version: 7.0.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.10.0)(@types/node@26.1.1)(aws4fetch@1.0.20)(jiti@2.7.0)(rollup@4.55.2)(tsx@4.21.0)(yaml@2.9.0) @@ -1591,15 +1597,27 @@ importers: '@astrojs/cloudflare': specifier: 'catalog:' version: 14.0.0(@types/node@26.1.1)(astro@7.0.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.10.0)(@types/node@26.1.1)(aws4fetch@1.0.20)(jiti@2.7.0)(rollup@4.55.2)(tsx@4.21.0)(yaml@2.9.0))(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.21.0)(workerd@1.20260611.1)(wrangler@4.100.0(@cloudflare/workers-types@4.20260305.1))(yaml@2.9.0) + '@cloudflare/kumo': + specifier: 'catalog:' + version: 2.6.0(@date-fns/tz@1.4.1)(@phosphor-icons/react@2.1.10(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@types/react@19.2.14)(date-fns@4.1.0)(echarts@6.0.0)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(zod@4.4.1) '@cloudflare/workers-types': specifier: 'catalog:' version: 4.20260305.1 + '@phosphor-icons/react': + specifier: 'catalog:' + version: 2.1.10(react-dom@19.2.4(react@19.2.4))(react@19.2.4) '@types/pg': specifier: ^8.16.0 version: 8.16.0 + '@types/react': + specifier: 'catalog:' + version: 19.2.14 publint: specifier: 'catalog:' version: 0.3.17 + react: + specifier: 'catalog:' + version: 19.2.4 tsdown: specifier: 'catalog:' version: 0.20.3(@arethetypeswrong/core@0.18.2)(@typescript/native-preview@7.0.0-dev.20260421.2)(oxc-resolver@11.16.4(@emnapi/core@1.10.0)(@emnapi/runtime@1.10.0))(publint@0.3.17)(typescript@6.0.3) @@ -3689,8 +3707,16 @@ packages: resolution: {integrity: sha512-S0My7XPGIgpRWMDG8uRqalbgT+a6FmCUdOW+HaIOVVpUPHOb7RrpvjTjiODadKp06fsrVDJZlIzc6yCTp4AnxA==} engines: {node: '>= 20.12.0'} + '@cloudflare/ai-search-snippet@0.0.40': + resolution: {integrity: sha512-DB2sUIT7ZASoIv2bGNK6OzfUSEF6qNZJ/pz7opbLasgMPDz9e5ArtNEp3UyyNjy8Pfj+2sGsNcHpESHUkbGTuw==, tarball: https://registry.npmjs.org/@cloudflare/ai-search-snippet/-/ai-search-snippet-0.0.40.tgz} + engines: {node: '>=16.0.0'} + + '@cloudflare/ai-search-snippet@0.0.42': + resolution: {integrity: sha512-LSNCvszcgEb+hgH1jpKCGaBrXScbahpjFVoXuDGiUyC9Td7hDR57+YdMMcBbhDa7S4GYaoCO1aziJYjvC0fwnw==, tarball: https://registry.npmjs.org/@cloudflare/ai-search-snippet/-/ai-search-snippet-0.0.42.tgz} + engines: {node: '>=16.0.0'} + '@cloudflare/codemode@0.3.8': - resolution: {integrity: sha512-PVe99dFf/dvf0JOh1SBTYL7YT0nXusmqaK0lRrrlHGIQdGAnKRSb4VtaE5atiDVgN/U9G16bSkej7Pn5lWhG1g==} + resolution: {integrity: sha512-PVe99dFf/dvf0JOh1SBTYL7YT0nXusmqaK0lRrrlHGIQdGAnKRSb4VtaE5atiDVgN/U9G16bSkej7Pn5lWhG1g==, tarball: https://registry.npmjs.org/@cloudflare/codemode/-/codemode-0.3.8.tgz} peerDependencies: '@modelcontextprotocol/sdk': ^1.25.0 '@tanstack/ai': '>=0.8.0 <1.0.0' @@ -3707,7 +3733,7 @@ packages: optional: true '@cloudflare/codemode@0.4.1': - resolution: {integrity: sha512-i73cD7GeEzJVxcjqb4yPDCXXq7/h/Le/Vvz/Z3Xxf5qFiiw9G75fd1+KGWvZ/3/Gk6bgL7eUnnwMhByK3b5EUg==} + resolution: {integrity: sha512-i73cD7GeEzJVxcjqb4yPDCXXq7/h/Le/Vvz/Z3Xxf5qFiiw9G75fd1+KGWvZ/3/Gk6bgL7eUnnwMhByK3b5EUg==, tarball: https://registry.npmjs.org/@cloudflare/codemode/-/codemode-0.4.1.tgz} peerDependencies: '@modelcontextprotocol/sdk': ^1.25.0 '@tanstack/ai': '>=0.8.0 <1.0.0' @@ -3727,7 +3753,7 @@ packages: resolution: {integrity: sha512-DM9dm3FnIBSyiSJ1FLavKwl/lk3oAmTaynCzZQ9pZR0ncRPquSxkxd8Nu2MFILxmDDsPkxKsSNEh9mHHMty4Fw==} '@cloudflare/kumo@2.6.0': - resolution: {integrity: sha512-rcUUvhrtxI0veNJZLgKVSnxH/L0M48jtc4UoNhvu0l0RiRmjHORFTBYq/phFQyt7JGG3s98QPZc5w1eW+UQIOg==} + resolution: {integrity: sha512-rcUUvhrtxI0veNJZLgKVSnxH/L0M48jtc4UoNhvu0l0RiRmjHORFTBYq/phFQyt7JGG3s98QPZc5w1eW+UQIOg==, tarball: https://registry.npmjs.org/@cloudflare/kumo/-/kumo-2.6.0.tgz} hasBin: true peerDependencies: '@phosphor-icons/react': ^2.1.10 @@ -3742,11 +3768,11 @@ packages: optional: true '@cloudflare/kv-asset-handler@0.4.2': - resolution: {integrity: sha512-SIOD2DxrRRwQ+jgzlXCqoEFiKOFqaPjhnNTGKXSRLvp1HiOvapLaFG2kEr9dYQTYe8rKrd9uvDUzmAITeNyaHQ==} + resolution: {integrity: sha512-SIOD2DxrRRwQ+jgzlXCqoEFiKOFqaPjhnNTGKXSRLvp1HiOvapLaFG2kEr9dYQTYe8rKrd9uvDUzmAITeNyaHQ==, tarball: https://registry.npmjs.org/@cloudflare/kv-asset-handler/-/kv-asset-handler-0.4.2.tgz} engines: {node: '>=18.0.0'} '@cloudflare/kv-asset-handler@0.5.0': - resolution: {integrity: sha512-jxQYkj8dSIzc0cD6cMMNdOc1UVjqSqu8BZdor5s8cGjW2I8BjODt/kWPVdY+u9zj3ms75Q5qaZgnxUad83+eAg==} + resolution: {integrity: sha512-jxQYkj8dSIzc0cD6cMMNdOc1UVjqSqu8BZdor5s8cGjW2I8BjODt/kWPVdY+u9zj3ms75Q5qaZgnxUad83+eAg==, tarball: https://registry.npmjs.org/@cloudflare/kv-asset-handler/-/kv-asset-handler-0.5.0.tgz} engines: {node: '>=22.0.0'} '@cloudflare/sandbox@0.12.3': @@ -3764,10 +3790,10 @@ packages: optional: true '@cloudflare/shell@0.4.0': - resolution: {integrity: sha512-C4Ey9PyQEPHXJvU+V72JuxFLziRAj7c+oVDgj0aDMRTf+B6icnSCDPuiTA6vKjPp60LxkFbRQq7pMTy3v+TlPQ==} + resolution: {integrity: sha512-C4Ey9PyQEPHXJvU+V72JuxFLziRAj7c+oVDgj0aDMRTf+B6icnSCDPuiTA6vKjPp60LxkFbRQq7pMTy3v+TlPQ==, tarball: https://registry.npmjs.org/@cloudflare/shell/-/shell-0.4.0.tgz} '@cloudflare/unenv-preset@2.15.0': - resolution: {integrity: sha512-EGYmJaGZKWl+X8tXxcnx4v2bOZSjQeNI5dWFeXivgX9+YCT69AkzHHwlNbVpqtEUTbew8eQurpyOpeN8fg00nw==} + resolution: {integrity: sha512-EGYmJaGZKWl+X8tXxcnx4v2bOZSjQeNI5dWFeXivgX9+YCT69AkzHHwlNbVpqtEUTbew8eQurpyOpeN8fg00nw==, tarball: https://registry.npmjs.org/@cloudflare/unenv-preset/-/unenv-preset-2.15.0.tgz} peerDependencies: unenv: 2.0.0-rc.24 workerd: 1.20260301.1 || ~1.20260302.1 || ~1.20260303.1 || ~1.20260304.1 || >1.20260305.0 <2.0.0-0 @@ -3776,7 +3802,7 @@ packages: optional: true '@cloudflare/unenv-preset@2.16.0': - resolution: {integrity: sha512-8ovsRpwzPoEqPUzoErAYVv8l3FMZNeBVQfJTvtzP4AgLSRGZISRfuChFxHWUQd3n6cnrwkuTGxT+2cGo8EsyYg==} + resolution: {integrity: sha512-8ovsRpwzPoEqPUzoErAYVv8l3FMZNeBVQfJTvtzP4AgLSRGZISRfuChFxHWUQd3n6cnrwkuTGxT+2cGo8EsyYg==, tarball: https://registry.npmjs.org/@cloudflare/unenv-preset/-/unenv-preset-2.16.0.tgz} peerDependencies: unenv: 2.0.0-rc.24 workerd: 1.20260301.1 || ~1.20260302.1 || ~1.20260303.1 || ~1.20260304.1 || >1.20260305.0 <2.0.0-0 @@ -3785,7 +3811,7 @@ packages: optional: true '@cloudflare/unenv-preset@2.16.1': - resolution: {integrity: sha512-ECxObrMfyTl5bhQf/lZCXwo5G6xX9IAUo+nDMKK4SZ8m4Jvvxp52vilxyySSWh2YTZz8+HQ07qGH/2rEom1vDw==} + resolution: {integrity: sha512-ECxObrMfyTl5bhQf/lZCXwo5G6xX9IAUo+nDMKK4SZ8m4Jvvxp52vilxyySSWh2YTZz8+HQ07qGH/2rEom1vDw==, tarball: https://registry.npmjs.org/@cloudflare/unenv-preset/-/unenv-preset-2.16.1.tgz} peerDependencies: unenv: 2.0.0-rc.24 workerd: '>1.20260305.0 <2.0.0-0' @@ -3794,189 +3820,189 @@ packages: optional: true '@cloudflare/vite-plugin@1.26.1': - resolution: {integrity: sha512-CyebmOYAjnobU9DCn/4cUb3xipWSsqCQO+Syc0AteEl7q/A72RTvs2PHQt/O8Qj6hUutslQbmvswdL5KuDwuhw==} + resolution: {integrity: sha512-CyebmOYAjnobU9DCn/4cUb3xipWSsqCQO+Syc0AteEl7q/A72RTvs2PHQt/O8Qj6hUutslQbmvswdL5KuDwuhw==, tarball: https://registry.npmjs.org/@cloudflare/vite-plugin/-/vite-plugin-1.26.1.tgz} peerDependencies: vite: ^6.1.0 || ^7.0.0 wrangler: ^4.71.0 '@cloudflare/vite-plugin@1.32.3': - resolution: {integrity: sha512-a8ZkCA/SOiJ36jT3LlBLkUb7ZzGInhYJoTY4BMRBGdk+nsh44HavbNvtu/RdaqS5VJEMLM4+LqVIJ+V0ahGeFg==} + resolution: {integrity: sha512-a8ZkCA/SOiJ36jT3LlBLkUb7ZzGInhYJoTY4BMRBGdk+nsh44HavbNvtu/RdaqS5VJEMLM4+LqVIJ+V0ahGeFg==, tarball: https://registry.npmjs.org/@cloudflare/vite-plugin/-/vite-plugin-1.32.3.tgz} peerDependencies: vite: ^6.1.0 || ^7.0.0 || ^8.0.0 wrangler: ^4.83.0 '@cloudflare/vite-plugin@1.36.3': - resolution: {integrity: sha512-n3SZhEZQxk4B2xHaCwgXfc7oLkx/4leTxL254P09DK2Qoj1VVOqVELo62CsUYq5dZS+okMdeWqNa13xEOKMs4g==} + resolution: {integrity: sha512-n3SZhEZQxk4B2xHaCwgXfc7oLkx/4leTxL254P09DK2Qoj1VVOqVELo62CsUYq5dZS+okMdeWqNa13xEOKMs4g==, tarball: https://registry.npmjs.org/@cloudflare/vite-plugin/-/vite-plugin-1.36.3.tgz} peerDependencies: vite: ^6.1.0 || ^7.0.0 || ^8.0.0 wrangler: ^4.90.0 '@cloudflare/vite-plugin@1.40.1': - resolution: {integrity: sha512-hn7NH6gc2RNOThCJVTSRVvSpqSYVmoZrFQMjilTdwwsrvMD0Np8zM7pEDB1q5isSGy7F5D+dacRF6LiF4Z1QKw==} + resolution: {integrity: sha512-hn7NH6gc2RNOThCJVTSRVvSpqSYVmoZrFQMjilTdwwsrvMD0Np8zM7pEDB1q5isSGy7F5D+dacRF6LiF4Z1QKw==, tarball: https://registry.npmjs.org/@cloudflare/vite-plugin/-/vite-plugin-1.40.1.tgz} hasBin: true peerDependencies: vite: ^6.1.0 || ^7.0.0 || ^8.0.0 wrangler: ^4.99.0 '@cloudflare/vitest-pool-workers@0.16.3': - resolution: {integrity: sha512-cnxtKBWoP5uhO78Z9zlCexj7oIs6zYoIH4GCEFS0Z6bepFDdnxtuMGxmWaDg84cy9teoh5CLA/OEN6XLSKcnWA==} + resolution: {integrity: sha512-cnxtKBWoP5uhO78Z9zlCexj7oIs6zYoIH4GCEFS0Z6bepFDdnxtuMGxmWaDg84cy9teoh5CLA/OEN6XLSKcnWA==, tarball: https://registry.npmjs.org/@cloudflare/vitest-pool-workers/-/vitest-pool-workers-0.16.3.tgz} peerDependencies: '@vitest/runner': ^4.1.0 '@vitest/snapshot': ^4.1.0 vitest: ^4.1.0 '@cloudflare/workerd-darwin-64@1.20260301.1': - resolution: {integrity: sha512-+kJvwociLrvy1JV9BAvoSVsMEIYD982CpFmo/yMEvBwxDIjltYsLTE8DLi0mCkGsQ8Ygidv2fD9wavzXeiY7OQ==} + resolution: {integrity: sha512-+kJvwociLrvy1JV9BAvoSVsMEIYD982CpFmo/yMEvBwxDIjltYsLTE8DLi0mCkGsQ8Ygidv2fD9wavzXeiY7OQ==, tarball: https://registry.npmjs.org/@cloudflare/workerd-darwin-64/-/workerd-darwin-64-1.20260301.1.tgz} engines: {node: '>=16'} cpu: [x64] os: [darwin] '@cloudflare/workerd-darwin-64@1.20260415.1': - resolution: {integrity: sha512-dsxaKsQm3LnPGNPEdsRv09QN3Y4DqCw7kX5j6noKqbAtro2jTr95sVlYM1jUxZ5FkOl1f7SXgaKKB9t5H5Nkbg==} + resolution: {integrity: sha512-dsxaKsQm3LnPGNPEdsRv09QN3Y4DqCw7kX5j6noKqbAtro2jTr95sVlYM1jUxZ5FkOl1f7SXgaKKB9t5H5Nkbg==, tarball: https://registry.npmjs.org/@cloudflare/workerd-darwin-64/-/workerd-darwin-64-1.20260415.1.tgz} engines: {node: '>=16'} cpu: [x64] os: [darwin] '@cloudflare/workerd-darwin-64@1.20260507.1': - resolution: {integrity: sha512-S85aMwcaPJUjKWDiG6iMMnioKWtPLACa6m0j/EhHR1GYfVpnxb974cBc6d25L+sf7jHWHJI2u5hGp0UTJ7MtXQ==} + resolution: {integrity: sha512-S85aMwcaPJUjKWDiG6iMMnioKWtPLACa6m0j/EhHR1GYfVpnxb974cBc6d25L+sf7jHWHJI2u5hGp0UTJ7MtXQ==, tarball: https://registry.npmjs.org/@cloudflare/workerd-darwin-64/-/workerd-darwin-64-1.20260507.1.tgz} engines: {node: '>=16'} cpu: [x64] os: [darwin] '@cloudflare/workerd-darwin-64@1.20260609.1': - resolution: {integrity: sha512-AK8tYLQm+8BqQMzjZ55ZfuhfIm1eCkj+Ykxz6kWXojdACwjjU03MrwdM9fBDdgzU3upXOs4e1scOFHySlfVQjA==} + resolution: {integrity: sha512-AK8tYLQm+8BqQMzjZ55ZfuhfIm1eCkj+Ykxz6kWXojdACwjjU03MrwdM9fBDdgzU3upXOs4e1scOFHySlfVQjA==, tarball: https://registry.npmjs.org/@cloudflare/workerd-darwin-64/-/workerd-darwin-64-1.20260609.1.tgz} engines: {node: '>=16'} cpu: [x64] os: [darwin] '@cloudflare/workerd-darwin-64@1.20260611.1': - resolution: {integrity: sha512-iJICldmi4sBGgi7IrQles8cStOGXM/Tmv95C4OODVs6VIbMsJPqThUM5h3uYVQNULuJ8I/aVvnJ3Eh/wZCKwuA==} + resolution: {integrity: sha512-iJICldmi4sBGgi7IrQles8cStOGXM/Tmv95C4OODVs6VIbMsJPqThUM5h3uYVQNULuJ8I/aVvnJ3Eh/wZCKwuA==, tarball: https://registry.npmjs.org/@cloudflare/workerd-darwin-64/-/workerd-darwin-64-1.20260611.1.tgz} engines: {node: '>=16'} cpu: [x64] os: [darwin] '@cloudflare/workerd-darwin-arm64@1.20260301.1': - resolution: {integrity: sha512-PPIetY3e67YBr9O4UhILK8nbm5TqUDl14qx4rwFNrRSBOvlzuczzbd4BqgpAtbGVFxKp1PWpjAnBvGU/OI/tLQ==} + resolution: {integrity: sha512-PPIetY3e67YBr9O4UhILK8nbm5TqUDl14qx4rwFNrRSBOvlzuczzbd4BqgpAtbGVFxKp1PWpjAnBvGU/OI/tLQ==, tarball: https://registry.npmjs.org/@cloudflare/workerd-darwin-arm64/-/workerd-darwin-arm64-1.20260301.1.tgz} engines: {node: '>=16'} cpu: [arm64] os: [darwin] '@cloudflare/workerd-darwin-arm64@1.20260415.1': - resolution: {integrity: sha512-+JgSgVA49KyKteHRA1SnonE4Zn5Ei5zdAp5FQMxFmXI8qulZw4Hl7safXxRyK4i9sTO8gl7TFOKO5Q64VPvSDQ==} + resolution: {integrity: sha512-+JgSgVA49KyKteHRA1SnonE4Zn5Ei5zdAp5FQMxFmXI8qulZw4Hl7safXxRyK4i9sTO8gl7TFOKO5Q64VPvSDQ==, tarball: https://registry.npmjs.org/@cloudflare/workerd-darwin-arm64/-/workerd-darwin-arm64-1.20260415.1.tgz} engines: {node: '>=16'} cpu: [arm64] os: [darwin] '@cloudflare/workerd-darwin-arm64@1.20260507.1': - resolution: {integrity: sha512-GMEBu8Zp9Q97HLnf7bWJN4KjWpN5MxpeqdvHjBGWNl8UYprJI0k+Jkp89+Wh5S8vIon+HoVbDfOzPa7VwgL6Eg==} + resolution: {integrity: sha512-GMEBu8Zp9Q97HLnf7bWJN4KjWpN5MxpeqdvHjBGWNl8UYprJI0k+Jkp89+Wh5S8vIon+HoVbDfOzPa7VwgL6Eg==, tarball: https://registry.npmjs.org/@cloudflare/workerd-darwin-arm64/-/workerd-darwin-arm64-1.20260507.1.tgz} engines: {node: '>=16'} cpu: [arm64] os: [darwin] '@cloudflare/workerd-darwin-arm64@1.20260609.1': - resolution: {integrity: sha512-4kKXfr7ZHU6xQ/R9ShdSuj1A1bEouoRcHzUWdjnuMPBlRsAAVanlxAVYISotFUulLEinayOpRFbhpsfwzrpSSw==} + resolution: {integrity: sha512-4kKXfr7ZHU6xQ/R9ShdSuj1A1bEouoRcHzUWdjnuMPBlRsAAVanlxAVYISotFUulLEinayOpRFbhpsfwzrpSSw==, tarball: https://registry.npmjs.org/@cloudflare/workerd-darwin-arm64/-/workerd-darwin-arm64-1.20260609.1.tgz} engines: {node: '>=16'} cpu: [arm64] os: [darwin] '@cloudflare/workerd-darwin-arm64@1.20260611.1': - resolution: {integrity: sha512-yBbVXvbZyltR3I7NJdC4C4ItkItjZSiabcA/3HzEWOUQjLVKFqRh4so6ToHr70VCYh8VGeR8EDZL23igLhXqFQ==} + resolution: {integrity: sha512-yBbVXvbZyltR3I7NJdC4C4ItkItjZSiabcA/3HzEWOUQjLVKFqRh4so6ToHr70VCYh8VGeR8EDZL23igLhXqFQ==, tarball: https://registry.npmjs.org/@cloudflare/workerd-darwin-arm64/-/workerd-darwin-arm64-1.20260611.1.tgz} engines: {node: '>=16'} cpu: [arm64] os: [darwin] '@cloudflare/workerd-linux-64@1.20260301.1': - resolution: {integrity: sha512-Gu5vaVTZuYl3cHa+u5CDzSVDBvSkfNyuAHi6Mdfut7TTUdcb3V5CIcR/mXRSyMXzEy9YxEWIfdKMxOMBjupvYQ==} + resolution: {integrity: sha512-Gu5vaVTZuYl3cHa+u5CDzSVDBvSkfNyuAHi6Mdfut7TTUdcb3V5CIcR/mXRSyMXzEy9YxEWIfdKMxOMBjupvYQ==, tarball: https://registry.npmjs.org/@cloudflare/workerd-linux-64/-/workerd-linux-64-1.20260301.1.tgz} engines: {node: '>=16'} cpu: [x64] os: [linux] '@cloudflare/workerd-linux-64@1.20260415.1': - resolution: {integrity: sha512-tU+9pwsqCy8afOVlGtiWrWQc/fedQK4SRm4KPIAt+zOiQWDxWASm6YGBUJis5c648WN80yz47qnmdDi8DQNOcA==} + resolution: {integrity: sha512-tU+9pwsqCy8afOVlGtiWrWQc/fedQK4SRm4KPIAt+zOiQWDxWASm6YGBUJis5c648WN80yz47qnmdDi8DQNOcA==, tarball: https://registry.npmjs.org/@cloudflare/workerd-linux-64/-/workerd-linux-64-1.20260415.1.tgz} engines: {node: '>=16'} cpu: [x64] os: [linux] '@cloudflare/workerd-linux-64@1.20260507.1': - resolution: {integrity: sha512-QlrKEBdgA3uVc0Ok0Q3+0/CW0CTjgj5ySir1i1YY5FXVv0X6GpwtnB5umjunjF2MFprss+L+iFGZzxcSvMC1nA==} + resolution: {integrity: sha512-QlrKEBdgA3uVc0Ok0Q3+0/CW0CTjgj5ySir1i1YY5FXVv0X6GpwtnB5umjunjF2MFprss+L+iFGZzxcSvMC1nA==, tarball: https://registry.npmjs.org/@cloudflare/workerd-linux-64/-/workerd-linux-64-1.20260507.1.tgz} engines: {node: '>=16'} cpu: [x64] os: [linux] '@cloudflare/workerd-linux-64@1.20260609.1': - resolution: {integrity: sha512-T2Ebir2OPHAvvZ0HUh5mi1lN8q30sVi4lf7LIpc28AHoWtoOmJ0jA5AJK4IYJm1MKEbBldq+QsckaHOCQFmRpQ==} + resolution: {integrity: sha512-T2Ebir2OPHAvvZ0HUh5mi1lN8q30sVi4lf7LIpc28AHoWtoOmJ0jA5AJK4IYJm1MKEbBldq+QsckaHOCQFmRpQ==, tarball: https://registry.npmjs.org/@cloudflare/workerd-linux-64/-/workerd-linux-64-1.20260609.1.tgz} engines: {node: '>=16'} cpu: [x64] os: [linux] '@cloudflare/workerd-linux-64@1.20260611.1': - resolution: {integrity: sha512-PfNjpxOlaIgZFYuhD7+neEEewCN2Ud993wEEN0fmbtSOax1AK53LGqmXUDvFhnbkHxJLFAxYCSNISW8QbzaAIg==} + resolution: {integrity: sha512-PfNjpxOlaIgZFYuhD7+neEEewCN2Ud993wEEN0fmbtSOax1AK53LGqmXUDvFhnbkHxJLFAxYCSNISW8QbzaAIg==, tarball: https://registry.npmjs.org/@cloudflare/workerd-linux-64/-/workerd-linux-64-1.20260611.1.tgz} engines: {node: '>=16'} cpu: [x64] os: [linux] '@cloudflare/workerd-linux-arm64@1.20260301.1': - resolution: {integrity: sha512-igL1pkyCXW6GiGpjdOAvqMi87UW0LMc/+yIQe/CSzuZJm5GzXoAMrwVTkCFnikk6JVGELrM5x0tGYlxa0sk5Iw==} + resolution: {integrity: sha512-igL1pkyCXW6GiGpjdOAvqMi87UW0LMc/+yIQe/CSzuZJm5GzXoAMrwVTkCFnikk6JVGELrM5x0tGYlxa0sk5Iw==, tarball: https://registry.npmjs.org/@cloudflare/workerd-linux-arm64/-/workerd-linux-arm64-1.20260301.1.tgz} engines: {node: '>=16'} cpu: [arm64] os: [linux] '@cloudflare/workerd-linux-arm64@1.20260415.1': - resolution: {integrity: sha512-bR9uITnV19r5NQ14xnypi2xHXu2iQvfYV8cVgx0JouFUmWwTEEAwFVojDdssGq93VHX9hr/pi2IRUZeegbYBog==} + resolution: {integrity: sha512-bR9uITnV19r5NQ14xnypi2xHXu2iQvfYV8cVgx0JouFUmWwTEEAwFVojDdssGq93VHX9hr/pi2IRUZeegbYBog==, tarball: https://registry.npmjs.org/@cloudflare/workerd-linux-arm64/-/workerd-linux-arm64-1.20260415.1.tgz} engines: {node: '>=16'} cpu: [arm64] os: [linux] '@cloudflare/workerd-linux-arm64@1.20260507.1': - resolution: {integrity: sha512-eGbbupEtK2nh9V9Dhcx3vv3GTKeXqSVNgAEYVCCN0NGS9tl9HbMoHRX/4JL181FKXROMigWBCQVL//qPhsAzBQ==} + resolution: {integrity: sha512-eGbbupEtK2nh9V9Dhcx3vv3GTKeXqSVNgAEYVCCN0NGS9tl9HbMoHRX/4JL181FKXROMigWBCQVL//qPhsAzBQ==, tarball: https://registry.npmjs.org/@cloudflare/workerd-linux-arm64/-/workerd-linux-arm64-1.20260507.1.tgz} engines: {node: '>=16'} cpu: [arm64] os: [linux] '@cloudflare/workerd-linux-arm64@1.20260609.1': - resolution: {integrity: sha512-INfcYoSsKqEIvPL69/3RkqYoP8WUR0VEN6loWN/3tekXLoJrVOj3E5NjIetsdS8MJN6zc3st/ae4bMuWRRzoDg==} + resolution: {integrity: sha512-INfcYoSsKqEIvPL69/3RkqYoP8WUR0VEN6loWN/3tekXLoJrVOj3E5NjIetsdS8MJN6zc3st/ae4bMuWRRzoDg==, tarball: https://registry.npmjs.org/@cloudflare/workerd-linux-arm64/-/workerd-linux-arm64-1.20260609.1.tgz} engines: {node: '>=16'} cpu: [arm64] os: [linux] '@cloudflare/workerd-linux-arm64@1.20260611.1': - resolution: {integrity: sha512-GEp4XbuIKjlF8pakqXcUDJfKiJosD/Q7S83J0d+r+z9XIlYGfF3ntm08e2aiF5TFTwp3fnG4yMoPUAKNhNJpvQ==} + resolution: {integrity: sha512-GEp4XbuIKjlF8pakqXcUDJfKiJosD/Q7S83J0d+r+z9XIlYGfF3ntm08e2aiF5TFTwp3fnG4yMoPUAKNhNJpvQ==, tarball: https://registry.npmjs.org/@cloudflare/workerd-linux-arm64/-/workerd-linux-arm64-1.20260611.1.tgz} engines: {node: '>=16'} cpu: [arm64] os: [linux] '@cloudflare/workerd-windows-64@1.20260301.1': - resolution: {integrity: sha512-Q0wMJ4kcujXILwQKQFc1jaYamVsNvjuECzvRrTI8OxGFMx2yq9aOsswViE4X1gaS2YQQ5u0JGwuGi5WdT1Lt7A==} + resolution: {integrity: sha512-Q0wMJ4kcujXILwQKQFc1jaYamVsNvjuECzvRrTI8OxGFMx2yq9aOsswViE4X1gaS2YQQ5u0JGwuGi5WdT1Lt7A==, tarball: https://registry.npmjs.org/@cloudflare/workerd-windows-64/-/workerd-windows-64-1.20260301.1.tgz} engines: {node: '>=16'} cpu: [x64] os: [win32] '@cloudflare/workerd-windows-64@1.20260415.1': - resolution: {integrity: sha512-4NuMLlerI0Ijua3Ir8HXQ+qyNvCUDEG5gDco5Om+sAiK6rnWiz+aGoSlbB8W16yW9QAgzCstbmXLiVknUBflfQ==} + resolution: {integrity: sha512-4NuMLlerI0Ijua3Ir8HXQ+qyNvCUDEG5gDco5Om+sAiK6rnWiz+aGoSlbB8W16yW9QAgzCstbmXLiVknUBflfQ==, tarball: https://registry.npmjs.org/@cloudflare/workerd-windows-64/-/workerd-windows-64-1.20260415.1.tgz} engines: {node: '>=16'} cpu: [x64] os: [win32] '@cloudflare/workerd-windows-64@1.20260507.1': - resolution: {integrity: sha512-dmClJ/E0BAcuDetQIZFqbeAXejWrG5pysGRMQ6T83Y0IW/7IAamY2zFEkAJ10I5xwZsdHuYsZtzlOxpEXpJs7A==} + resolution: {integrity: sha512-dmClJ/E0BAcuDetQIZFqbeAXejWrG5pysGRMQ6T83Y0IW/7IAamY2zFEkAJ10I5xwZsdHuYsZtzlOxpEXpJs7A==, tarball: https://registry.npmjs.org/@cloudflare/workerd-windows-64/-/workerd-windows-64-1.20260507.1.tgz} engines: {node: '>=16'} cpu: [x64] os: [win32] '@cloudflare/workerd-windows-64@1.20260609.1': - resolution: {integrity: sha512-EWhfxKI1aqUr7S8xuGxgmRCumEzB8iSsCIz6oEqJN+3pZuW3EWiKDGFW4EY1BmwNINLW1eO5VMGYb8Fj6FVYxA==} + resolution: {integrity: sha512-EWhfxKI1aqUr7S8xuGxgmRCumEzB8iSsCIz6oEqJN+3pZuW3EWiKDGFW4EY1BmwNINLW1eO5VMGYb8Fj6FVYxA==, tarball: https://registry.npmjs.org/@cloudflare/workerd-windows-64/-/workerd-windows-64-1.20260609.1.tgz} engines: {node: '>=16'} cpu: [x64] os: [win32] '@cloudflare/workerd-windows-64@1.20260611.1': - resolution: {integrity: sha512-S6JkS0kEbcCKs19RGqEPhjCRbP8GBkQwqYLp2fhBJtD/KTlwqLzOJ9E6PQ7gQKgWHtxy1NBG3oXarlNFRNU/dw==} + resolution: {integrity: sha512-S6JkS0kEbcCKs19RGqEPhjCRbP8GBkQwqYLp2fhBJtD/KTlwqLzOJ9E6PQ7gQKgWHtxy1NBG3oXarlNFRNU/dw==, tarball: https://registry.npmjs.org/@cloudflare/workerd-windows-64/-/workerd-windows-64-1.20260611.1.tgz} engines: {node: '>=16'} cpu: [x64] os: [win32] '@cloudflare/workers-types@4.20260305.1': - resolution: {integrity: sha512-835BZaIcgjuYIUqgOWJSpwQxFSJ8g/X1OCZFLO7bmirM6TGmVgIGwiGItBgkjUXXCPrYzJEldsJkuFuK7ePuMw==} + resolution: {integrity: sha512-835BZaIcgjuYIUqgOWJSpwQxFSJ8g/X1OCZFLO7bmirM6TGmVgIGwiGItBgkjUXXCPrYzJEldsJkuFuK7ePuMw==, tarball: https://registry.npmjs.org/@cloudflare/workers-types/-/workers-types-4.20260305.1.tgz} '@colors/colors@1.5.0': resolution: {integrity: sha512-ooWCrlZP11i8GImSjTHYHLkvFDP48nS4+204nGb1RiX/WXYHmJA2III9/e2DWVabCESdW7hBAEzHRqUn9OUVvQ==} @@ -14242,6 +14268,10 @@ snapshots: fast-wrap-ansi: 0.2.0 sisteransi: 1.0.5 + '@cloudflare/ai-search-snippet@0.0.40': {} + + '@cloudflare/ai-search-snippet@0.0.42': {} + '@cloudflare/codemode@0.3.8(@modelcontextprotocol/sdk@1.29.0(@cfworker/json-schema@4.1.1)(zod@4.4.1))(ai@6.0.172(zod@4.4.1))(zod@4.4.1)': dependencies: '@types/json-schema': 7.0.15