From 5f634204256348ed3d631e472ad31eec056b8e89 Mon Sep 17 00:00:00 2001 From: ttmx Date: Thu, 16 Jul 2026 12:06:07 +0100 Subject: [PATCH 01/39] feat(cloudflare): add AI Search plugin Cloudflare-native AI Search integration: content sync hooks, metadata-based documents with always-on metadata-only retrieval, locale-aware search, a cron-flushed reindex queue, query synonyms, an index-status endpoint, and the settings admin UI. --- packages/cloudflare/package.json | 22 +- .../src/plugins/ai-search-admin.tsx | 510 +++++++ packages/cloudflare/src/plugins/ai-search.ts | 1322 +++++++++++++++++ packages/cloudflare/src/plugins/index.ts | 1 + packages/cloudflare/tsdown.config.ts | 3 + 5 files changed, 1857 insertions(+), 1 deletion(-) create mode 100644 packages/cloudflare/src/plugins/ai-search-admin.tsx create mode 100644 packages/cloudflare/src/plugins/ai-search.ts diff --git a/packages/cloudflare/package.json b/packages/cloudflare/package.json index 3770bc72e0..39728b6c9b 100644 --- a/packages/cloudflare/package.json +++ b/packages/cloudflare/package.json @@ -65,6 +65,15 @@ "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-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" @@ -103,13 +112,21 @@ "peerDependencies": { "@astrojs/cloudflare": ">=12.0.0", "@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 + }, + "@phosphor-icons/react": { + "optional": true + }, + "react": { + "optional": true } }, "devDependencies": { @@ -117,7 +134,10 @@ "@astrojs/cloudflare": "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:" 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..68f5a032fa --- /dev/null +++ b/packages/cloudflare/src/plugins/ai-search-admin.tsx @@ -0,0 +1,510 @@ +/** + * 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" : ""}`; + +// ============================================================================= +// 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 [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 [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); + + 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)); + // Restore the last configured selection; fall back to the common + // content collections when nothing has been configured yet. + const initial = + saved.length > 0 + ? saved + : options.filter((c) => c.slug === "posts" || c.slug === "pages").map((c) => c.slug); + setSelected(initial); + } catch (err) { + if (!cancelled) { + setCollectionsError(err instanceof Error ? err.message : "Failed to load collections"); + } + } finally { + if (!cancelled) setLoadingCollections(false); + } + })(); + return () => { + cancelled = true; + }; + }, []); + + const labelForSlug = React.useCallback( + (slug: string) => available.find((c) => c.slug === slug)?.label ?? slug, + [available], + ); + + // Persist the operator's selection so it is restored on the next visit. + const persistSelection = React.useCallback((next: string[]) => { + void apiFetch(`${API_BASE}/config`, { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ collections: next }), + }).catch(() => { + // Non-critical: selection still applies for this session. + }); + }, []); + + const handleSelectionChange = React.useCallback( + (value: unknown) => { + const next = Array.isArray(value) ? (value as string[]) : []; + setSelected(next); + persistSelection(next); + }, + [persistSelection], + ); + + const runSync = React.useCallback( + async (body: Record, mode: "full" | "missing") => { + setSyncMode(mode); + setError(null); + try { + const response = await apiFetch(`${API_BASE}/reindex`, { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify(body), + }); + let data = await parseApiResponse(response); + if ("error" in data) throw new Error(data.error); + setResult(data); + + while (!data.done) { + await new Promise((resolve) => setTimeout(resolve, 5_000)); + const statusResponse = await apiFetch(`${API_BASE}/reindex`); + const jobStatus = await parseApiResponse(statusResponse); + if (!jobStatus || jobStatus.jobId !== data.jobId) { + throw new Error("Reindex job not found"); + } + data = jobStatus; + setResult(data); + } + } catch (err) { + setError(err instanceof Error ? err.message : "Sync failed"); + } finally { + 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); + if ("error" in data) { + setStatusError(data.error); + } else { + 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[]; error?: string }>(response); + if (data.error) { + setSynonymsError(data.error); + } else { + setSynonyms(data.synonyms ?? cleaned); + setSynonymsSaved(true); + } + } catch (err) { + setSynonymsError(err instanceof Error ? err.message : "Failed to save synonyms"); + } finally { + setIsSavingSynonyms(false); + } + }; + + return ( +
+

AI Search

+ +
+

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)} + + )} + + + + )} + +
+ + + + + + + {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. +

+ +
+ {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..3c757c82a5 --- /dev/null +++ b/packages/cloudflare/src/plugins/ai-search.ts @@ -0,0 +1,1322 @@ +/** + * 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" } + * ] + * } + * ``` + */ + +import type { + ContentDeleteEvent, + ContentHookEvent, + ContentPublishStateChangeEvent, + PluginContext, + PluginDescriptor, + ResolvedPlugin, + RouteContext, +} from "emdash"; +import { definePlugin, extractPlainText } from "emdash"; + +const MD_EXT = /\.md$/; +const ITEM_PREFIX = /^item:/; + +// ============================================================================= +// 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; +} + +/** + * 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"; + +/** + * 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 AiSearchConfig { + id: string; + type?: string; + source?: string; + custom_metadata?: Array<{ field_name: string; data_type: "text" | "number" | "boolean" }>; + [key: string]: unknown; +} + +interface AiSearchInstance { + search(params: AiSearchSearchRequest): Promise; + update(config: Partial): Promise; + info(): Promise<{ id: string; [key: string]: unknown }>; + items: { + upload( + name: string, + content: string, + options?: { metadata?: Record }, + ): Promise; + delete(itemId: string): Promise; + }; +} + +interface AiSearchNamespace { + get(name: string): AiSearchInstance; + create(config: AiSearchConfig): Promise; +} + +// ============================================================================= +// Helpers +// ============================================================================= + +/** Get Cloudflare runtime env via cloudflare:workers. */ +async function getCloudflareEnv(): Promise | null> { + try { + const { env } = await import("cloudflare:workers"); + return env as unknown as Record; + } 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 { + import("cloudflare:workers").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)) { + // eslint-disable-next-line @typescript-eslint/no-explicit-any, typescript-eslint(no-unsafe-type-assertion) -- Portable Text arrays are untyped; extractPlainText handles validation + return extractPlainText(value as any); + } + 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 a content entry, + * used as searchable/returnable metadata so metadata-only retrieval can render + * a snippet without fetching the full document. Prefers an explicit excerpt, + * then falls back to other indexable content fields. Excludes system metadata + * and truncates to `DESCRIPTION_MAX_LENGTH` at a word boundary. + */ +function contentToDescription(content: Record): string { + const excerpt = extractIndexableText(content.excerpt); + if (excerpt) return truncateDescription(excerpt); + + const parts: string[] = []; + for (const [key, value] of Object.entries(content)) { + if (key === "title" || key === "excerpt" || isSystemContentKey(key)) continue; + const text = extractIndexableText(value); + if (text) parts.push(text); + } + return truncateDescription(parts.join(" ")); +} + +function imageUrlFromValue(value: unknown): string { + if (!value || typeof value !== "object" || Array.isArray(value)) return ""; + const obj = value as Record; + if (typeof obj.src === "string" && obj.src) return obj.src; + const meta = obj.meta as Record | 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; +} + +interface UploadItemOptions { + /** Called as soon as AI Search accepts the upload, before mirror bookkeeping. */ + onUploaded?: (item: AiSearchItemInfo) => Promise; + /** Leave accepted uploads in place when mirror bookkeeping fails. */ + tolerateMirrorFailure?: boolean; +} + +/** Replace a mirrored item before uploading because AI Search keys are unique. */ +async function uploadItem( + instance: AiSearchInstance, + key: string, + markdown: string, + metadata: Record, + ctx: PluginContext, + options: UploadItemOptions = {}, +): Promise { + const mirrorKey = `item:${key}`; + const previousId = await ctx.kv.get(mirrorKey); + let previousRemoved = false; + if (previousId) { + try { + await instance.items.delete(previousId); + previousRemoved = true; + } catch { + // A stale mirror is harmless: upload will either succeed or surface + // the real key conflict to the caller. + } + } + + let item: AiSearchItemInfo; + try { + item = await instance.items.upload(key, markdown, { metadata }); + } catch (error) { + if (previousRemoved) await ctx.kv.delete(mirrorKey); + throw error; + } + // AI Search's non-polling upload call returning without throwing is the + // acceptance boundary. Reindex progress is checkpointed here; indexing may + // continue asynchronously inside AI Search. + await options.onUploaded?.(item); + + if (!item?.id) { + if (options.tolerateMirrorFailure) return; + throw new Error(`upload for ${key} returned no item id`); + } + try { + await ctx.kv.set(mirrorKey, item.id); + } catch (error) { + if (options.tolerateMirrorFailure) { + console.error(`[ai-search] Failed to mirror accepted upload ${key}:`, error); + return; + } + // Hook-driven writes retain their stronger rollback guarantee. Reindexing + // can reconcile an accepted-but-unmirrored upload in a later pass. + try { + await instance.items.delete(item.id); + } catch {} + if (previousRemoved) await ctx.kv.delete(mirrorKey); + throw error; + } +} + +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); +} + +/** + * 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 (typeof entry !== "object" || entry === null) continue; + const from = (entry as Record).from; + const to = (entry as Record).to; + 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. + */ +interface SynonymRewriter { + re: RegExp | null; + lookup: Map; +} + +/** + * Compile a synonym set into a single reusable regex. Benchmarking showed that + * recompiling a regex per synonym per query is O(synonyms) and dominates the + * cost (~29µs at 100 synonyms), while one combined precompiled alternation is + * flat (~0.2µs) and still supports multi-word phrases — unlike a word-split + * `Map`/`find` lookup. Callers cache the result so compilation happens only + * when the synonym set changes. + */ +function compileSynonyms(synonyms: Synonym[]): SynonymRewriter { + // Longer phrases first so multi-word terms win over their sub-words. + const sorted = [...synonyms].filter((s) => s.from).sort((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(`\\b(?:${pattern})\\b`, "gi"), lookup }; +} + +/** + * Transparently rewrite a query by substituting configured synonym terms in + * place, using a precompiled rewriter. Whole-word (case-insensitive) + * occurrences of each `from` anywhere in the query are replaced with `to` — + * e.g. with `autorag` -> `AI Search`, "what is autorag" becomes "what is AI + * Search". + */ +function applySynonyms(query: string, rewriter: SynonymRewriter): string { + if (!rewriter.re) return query; + rewriter.re.lastIndex = 0; + return query.replace(rewriter.re, (match) => rewriter.lookup.get(match.toLowerCase()) ?? match); +} + +// ============================================================================= +// 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: "AI Search", icon: "search" }], + }; +} + +// ============================================================================= +// Plugin implementation (loaded at runtime via entrypoint) +// ============================================================================= + +export function createPlugin(config: AISearchConfig = {}): ResolvedPlugin { + 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; + } + + /** 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); + } + + /** 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 : []; + } + + // Cache the compiled synonym regex across requests in this isolate so we only + // recompile when the configured set actually changes (keyed by its JSON). + let synonymCache: { key: string; rewriter: SynonymRewriter } | null = null; + + /** Read synonyms from KV and return a compiled (cached) rewriter. */ + async function getSynonymRewriter(ctx: PluginContext): Promise { + const synonyms = await getConfiguredSynonyms(ctx); + const key = JSON.stringify(synonyms); + if (synonymCache?.key !== key) { + synonymCache = { key, rewriter: compileSynonyms(synonyms) }; + } + return synonymCache.rewriter; + } + + /** 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); + } + + /** + * Whether a content hook should act on the given collection. Content is + * synced only for collections the operator selected in the dashboard. When + * nothing has been configured yet, all collections are indexed so the + * plugin works out of the box until the operator narrows the selection. + */ + async function shouldSync(collection: string, ctx: PluginContext): Promise { + const configured = await getConfiguredCollections(ctx); + return configured === null || configured.includes(collection); + } + + async function getBinding(): Promise { + const env = await getCloudflareEnv(); + if (!env?.[bindingName]) return null; + return env[bindingName] as AiSearchNamespace; + } + + async function ensureInstance(ns: AiSearchNamespace): Promise { + const handle = ns.get(instanceName); + try { + await handle.info(); + return handle; + } catch { + return ns.create({ + id: instanceName, + hybrid_search_enabled: hybridSearch, + // AI Search allows at most 5 custom metadata fields, so title and + // description are packed into a single `title_desc` field to make + // room for `locale`. + 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" }, + ], + }); + } + } + + /** + * 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); + } + } + + /** Remove a content item from the AI Search index. */ + async function removeFromIndex( + collection: string, + id: string, + ctx: PluginContext, + ): Promise { + const ns = await getBinding(); + if (!ns) return; + + const key = contentKey(collection, id); + try { + const itemId = await ctx.kv.get(`item:${key}`); + if (!itemId) 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})`); + } 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, { + onUploaded: () => checkpointAcceptedUpload(key), + tolerateMirrorFailure: true, + }), + ); + } 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: "AI Search", icon: "search" }], + }, + + hooks: { + "plugin:install": { + handler: async (_event: unknown, ctx: PluginContext): Promise => { + const collections = (await getConfiguredCollections(ctx)) ?? ["posts", "pages"]; + await saveConfiguredCollections(ctx, collections); + const job = createReindexJob(collections, false); + await ctx.kv.set(REINDEX_JOB_KEY, job); + await ctx.cron?.schedule(REINDEX_CRON_TASK, { schedule: "* * * * *" }); + }, + }, + + 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; + if (!(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; + if (!(await shouldSync(collection, ctx))) return; + + 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; + if (!(await shouldSync(collection, ctx))) return; + + // 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 (!(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; + if (!(await shouldSync(collection, ctx))) return; + + return waitForSync(removeFromIndex(collection, id, ctx)); + }, + }, + }, + + routes: { + query: { + public: true, + handler: async (ctx: RouteContext): Promise => { + const start = Date.now(); + + // Support both JSON body input and URL query params (for GET requests) + const input = ctx.input as Record | undefined; + const url = new URL(ctx.request.url); + const params = url.searchParams; + + const ns = await getBinding(); + if (!ns) { + console.warn("[ai-search] Query failed: binding not available"); + return { error: `${bindingName} binding not available`, results: [] }; + } + + const q = + (typeof input?.q === "string" ? input.q : undefined) ?? params.get("q") ?? undefined; + if (!q) { + return { error: "Query parameter 'q' is required", results: [] }; + } + + const locale = + (typeof input?.locale === "string" ? input.locale : undefined) ?? + params.get("locale") ?? + undefined; + if (!locale) { + return { error: "Query parameter 'locale' is required", results: [] }; + } + + const limit = + (typeof input?.limit === "number" ? input.limit : undefined) ?? + (params.has("limit") ? Number(params.get("limit")) : undefined) ?? + 10; + const collection = + (typeof input?.collection === "string" ? input.collection : undefined) ?? + params.get("collection") ?? + undefined; + + // Transparently substitute configured synonym terms so the query + // sent to AI Search uses the canonical wording that indexes better. + const rewriter = await getSynonymRewriter(ctx); + const effectiveQuery = applySynonyms(q, rewriter); + + console.log( + `[ai-search] Query: q=${JSON.stringify(q)}${ + effectiveQuery === q ? "" : ` -> ${JSON.stringify(effectiveQuery)}` + } limit=${limit} collection=${collection ?? "all"}`, + ); + + try { + const instance = await ensureInstance(ns); + const nowSeconds = Math.floor(Date.now() / 1000); + + // Run a search for a specific locale and return deduped, mapped + // results. Extracted so the locale fallback can reuse it verbatim. + const searchLocale = async (searchLocaleCode: string) => { + const response = await instance.search({ + messages: [{ role: "user", content: effectiveQuery }], + ai_search_options: { + retrieval: { + max_num_results: limit, + filters: { + visible_after: { $lte: nowSeconds }, + locale: { $eq: searchLocaleCode }, + }, + // Metadata-only retrieval is always used: results are + // rendered from the packed title/description metadata, + // skipping the slower full-text chunk retrieval. + metadata_only: true, + }, + }, + }); + + let chunks = response.chunks; + if (collection) { + const cols = collection.split(",").map((c) => c.trim()); + chunks = chunks.filter((c) => cols.some((col) => c.item.key.startsWith(`${col}/`))); + } + + // Deduplicate by item key, keeping the highest-scoring chunk per item + const bestByKey = new Map(); + for (const c of chunks) { + const existing = bestByKey.get(c.item.key); + if (!existing || c.score > existing.score) { + bestByKey.set(c.item.key, c); + } + } + const uniqueChunks = [...bestByKey.values()]; + + // Resolve slug/title/description for each result. Title and + // description are packed into the `title_desc` metadata field + // (present in both normal and metadata-only mode); unpack it. + // The snippet uses the full-text chunk when available, otherwise + // the description (the only text available in metadata-only mode). + const mapped = uniqueChunks.map((c) => { + const parsed = parseContentKey(c.item.key); + const md = c.item.metadata ?? {}; + const slug = typeof md.slug === "string" && md.slug ? md.slug : null; + const packed = typeof md.title_desc === "string" ? md.title_desc : ""; + const { title: rawTitle, description: rawDescription } = + unpackTitleDescription(packed); + const title = rawTitle ? rawTitle : null; + const description = rawDescription ? rawDescription : null; + const image = typeof md.image === "string" && md.image ? md.image : null; + + const snippet = c.text && c.text.trim() ? c.text : (description ?? ""); + return { + ...parsed, + slug, + title, + description, + image, + score: c.score, + snippet, + }; + }); + + return { searchQuery: response.search_query, results: mapped }; + }; + + let { searchQuery, results } = await searchLocale(locale); + + // Fall back to the site default locale when the requested locale + // returns nothing, so untranslated content is still discoverable. + if (results.length === 0 && ctx.site?.locale && locale !== ctx.site.locale) { + ({ searchQuery, results } = await searchLocale(ctx.site.locale)); + } + + const elapsed = Date.now() - start; + console.log( + `[ai-search] Query complete: ${results.length} results in ${elapsed}ms (rewritten: ${JSON.stringify(searchQuery)})`, + ); + return { query: searchQuery, results }; + } catch (error) { + const elapsed = Date.now() - start; + console.error(`[ai-search] Query failed after ${elapsed}ms:`, error); + return { + error: error instanceof Error ? error.message : "Search failed", + results: [], + }; + } + }, + }, + + status: { + handler: async (ctx: RouteContext): Promise => { + if (!ctx.content) { + return { error: "Content access not available" }; + } + + // 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 = ctx.input as Record | undefined; + const params = new URL(ctx.request.url).searchParams; + const requested = + typeof input?.collections === "string" + ? input.collections.split(",") + : Array.isArray(input?.collections) + ? (input.collections as 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 getConfiguredCollections(ctx)) ?? [], + synonyms: await getConfiguredSynonyms(ctx), + }; + } + + const input = ctx.input as Record | undefined; + + if (input?.collections !== undefined) { + const collections = parseCollections(input.collections); + if (!collections) { + return { error: "collections must be an array of collection slugs" }; + } + await saveConfiguredCollections(ctx, collections); + } + + if (input?.synonyms !== undefined) { + const synonyms = parseSynonyms(input.synonyms); + if (!synonyms) { + return { error: "synonyms must be an array of { from, to } objects" }; + } + await saveConfiguredSynonyms(ctx, synonyms); + } + + return { + collections: (await getConfiguredCollections(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) return { error: "Cron scheduling is not available" }; + + const input = ctx.input as Record | undefined; + const requestedJobId = typeof input?.jobId === "string" ? input.jobId : undefined; + if (requestedJobId && current?.id !== requestedJobId) { + return { error: "Reindex job not found" }; + } + + let job = current?.status === "running" ? current : null; + if (!job) { + const collections = + parseCollections(input?.collections) ?? (await getConfiguredCollections(ctx)) ?? []; + if (collections.length === 0) { + return { + error: "No collections specified. Select collections in the dashboard first.", + }; + } + await saveConfiguredCollections(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; 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/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", From 7e9e09392965ddbccdf9c10ef07474ad3bee50c8 Mon Sep 17 00:00:00 2001 From: ttmx Date: Thu, 16 Jul 2026 15:29:15 +0100 Subject: [PATCH 02/39] feat(demo): wire AI Search into the Cloudflare demo Registers the AI_SEARCH namespace binding, adds a cron trigger to flush the reindex queue, documents the aiSearch() options at their defaults, and adds the search UI: Cloudflare's AI Search snippet (search-modal-snippet) opened by a nav button or Cmd/Ctrl+K, backed by a /api/ai-search/search endpoint that queries the binding directly. Replaces the previous custom /search page. --- demos/cloudflare/astro.config.mjs | 9 + demos/cloudflare/package.json | 1 + demos/cloudflare/src/layouts/Base.astro | 190 +- .../src/pages/api/ai-search/search.ts | 161 ++ demos/cloudflare/src/pages/search.astro | 182 -- demos/cloudflare/worker-configuration.d.ts | 2360 +++++++++++++++-- demos/cloudflare/wrangler.jsonc | 10 + pnpm-lock.yaml | 98 +- 8 files changed, 2478 insertions(+), 533 deletions(-) create mode 100644 demos/cloudflare/src/pages/api/ai-search/search.ts delete mode 100644 demos/cloudflare/src/pages/search.astro diff --git a/demos/cloudflare/astro.config.mjs b/demos/cloudflare/astro.config.mjs index a349f89745..69c5b0b6cc 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,14 @@ 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, + }), ], // 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..042d0fb8f6 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"; @@ -110,14 +109,23 @@ const isLoggedIn = !!Astro.locals.user; }
- + +
{ menu?.items.map((item) => ( @@ -622,133 +630,66 @@ const isLoggedIn = !!Astro.locals.user; gap: var(--spacing-6); } - .nav-links { - display: flex; - gap: var(--spacing-5); - font-size: var(--font-size-sm); - } - - .nav-links a { - text-decoration: none; - color: var(--color-text); - transition: color var(--transition-fast); - } - - .nav-links a:hover { - color: var(--color-accent); - } - - .nav-admin { - font-size: var(--font-size-sm); - color: var(--color-text-secondary); - text-decoration: none; - transition: color var(--transition-fast); - } - - .nav-admin:hover { - color: var(--color-text); - } - - /* Search styling */ - .site-search { - position: relative; - width: var(--search-input-width); - --emdash-search-border-focus: var(--color-accent); - } - - :global(.site-search-input) { - width: var(--search-input-width); + .nav-search-btn { + display: inline-flex; + align-items: center; + gap: var(--spacing-2); padding: var(--spacing-2) var(--spacing-3); font-family: var(--font-sans); font-size: var(--font-size-sm); + color: var(--color-text-secondary); + background: var(--color-bg); border: 1px solid var(--color-border); border-radius: var(--radius); - background: var(--color-bg); - color: var(--color-text); + cursor: pointer; transition: border-color var(--transition-fast), - box-shadow var(--transition-fast); + color var(--transition-fast); } - :global(.site-search-input)::placeholder { - color: var(--color-muted); + .nav-search-btn:hover { + color: var(--color-text); + border-color: var(--color-accent); } - :global(.site-search-input):focus, - :global(.site-search-input):focus-visible { - outline: none; - border-color: var(--color-accent) !important; - box-shadow: 0 0 0 3px var(--color-accent-ring); + .nav-search-icon { + width: 16px; + height: 16px; } - :global(.site-search-results) { - position: absolute; - top: 100%; - left: 0; - right: 0; - margin-top: var(--spacing-2); - background: var(--color-bg); + .nav-search-kbd { + font-family: var(--font-sans); + font-size: var(--font-size-xs); + color: var(--color-muted); border: 1px solid var(--color-border); - border-radius: var(--radius-lg); - box-shadow: var(--shadow-dropdown); - max-height: 400px; - overflow-y: auto; - z-index: 1000; + border-radius: var(--radius); + padding: 0 var(--spacing-1); } - :global(.site-search-results .emdash-live-search-loading), - :global(.site-search-results .emdash-live-search-no-results) { - padding: var(--spacing-4); - text-align: center; - color: var(--color-muted); + .nav-links { + display: flex; + gap: var(--spacing-5); font-size: var(--font-size-sm); } - :global(.site-search-result) { - display: block; - padding: var(--spacing-3) var(--spacing-4); + .nav-links a { text-decoration: none; color: var(--color-text); - border-bottom: 1px solid var(--color-border-subtle); - transition: background var(--transition-fast); - } - - :global(.site-search-result):last-child { - border-bottom: none; - } - - :global(.site-search-result):hover, - :global(.site-search-result):focus, - :global(.site-search-result.focused) { - background: var(--color-surface); - outline: none; - } - - :global(.site-search-result .emdash-live-search-result-title) { - display: block; - font-weight: 500; - font-size: var(--font-size-sm); + transition: color var(--transition-fast); } - :global(.site-search-result .emdash-live-search-result-collection) { - display: block; - font-size: var(--font-size-xs); - color: var(--color-muted); - text-transform: uppercase; - letter-spacing: var(--tracking-wide); - margin-top: 2px; + .nav-links a:hover { + color: var(--color-accent); } - :global(.site-search-result .emdash-live-search-result-snippet) { - display: block; + .nav-admin { font-size: var(--font-size-sm); - color: var(--color-muted); - margin-top: var(--spacing-1); - line-height: var(--leading-snug); + color: var(--color-text-secondary); + text-decoration: none; + transition: color var(--transition-fast); } - :global(.site-search-result .emdash-live-search-result-snippet mark) { - font-weight: 600; + .nav-admin:hover { color: var(--color-text); } @@ -945,17 +886,6 @@ const isLoggedIn = !!Astro.locals.user; display: contents; } - .site-search { - order: 0; - max-width: 140px; - } - - :global(.site-search-input) { - width: 140px !important; - padding: var(--spacing-1) var(--spacing-2) !important; - font-size: var(--font-size-sm) !important; - } - .nav-links { order: 1; width: 100%; @@ -996,18 +926,16 @@ 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..78c28028d2 --- /dev/null +++ b/demos/cloudflare/src/pages/api/ai-search/search.ts @@ -0,0 +1,161 @@ +export const prerender = false; + +import type { APIRoute } from "astro"; + +/** + * Search endpoint for the Cloudflare AI Search snippet. + * + * The `@cloudflare/ai-search-snippet` web components POST to `{api-url}/search` + * with a Cloudflare AI Search request body and expect the native AI Search + * response shape (`{ success, result: { chunks } }`). + * + * We query the `AI_SEARCH` binding directly (the same instance the ai-search + * plugin indexes into) rather than proxying to the plugin's HTTP route: a + * Worker fetching its own route is a self-subrequest that is unreliable in the + * Cloudflare runtime. The plugin stores `title`, `slug`, `description` and + * `image` as item metadata, and keys items as `{collection}/{id}.md`, so we can + * build public URLs and result cards straight from the search response. + */ + +const AI_SEARCH_INSTANCE = "emdash-content"; +const DEFAULT_LOCALE = "en-us"; +const MD_EXT = /\.md$/; + +// Title and description are packed into one metadata field by the ai-search +// plugin (AI Search allows at most 5 custom_metadata fields), joined by the +// ASCII Unit Separator. Keep this in sync with the plugin's TITLE_DESC_SEP. +const TITLE_DESC_SEP = "\u001F"; +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) }; +} + +interface SnippetSearchBody { + messages?: Array<{ role: string; content: string | null }>; + ai_search_options?: { + retrieval?: { max_num_results?: number }; + }; + locale?: string; +} + +interface AiSearchChunk { + id: string; + score: number; + text?: string; + item: { key: string; timestamp?: number; metadata?: Record }; +} + +interface AiSearchInstance { + search(params: { + messages: Array<{ role: string; content: string | null }>; + ai_search_options?: { retrieval?: Record }; + }): Promise<{ search_query: string; chunks: AiSearchChunk[] }>; +} + +interface AiSearchNamespace { + get(name: string): AiSearchInstance; +} + +/** Resolve the AI_SEARCH namespace binding from the Cloudflare runtime env. */ +async function getAiSearch(): Promise { + try { + const { env } = await import("cloudflare:workers"); + const binding = (env as unknown as Record).AI_SEARCH; + return binding ? (binding as AiSearchNamespace) : null; + } catch { + return null; + } +} + +function str(value: unknown): string { + return typeof value === "string" ? value : ""; +} + +export const POST: APIRoute = async ({ request }) => { + let body: SnippetSearchBody; + try { + body = await request.json(); + } catch { + return Response.json({ success: false, error: "Invalid request body" }, { status: 400 }); + } + + // The snippet sends the query as the last user message. + const query = (body.messages ?? []).findLast((m) => m.role === "user")?.content?.trim(); + if (!query) { + return Response.json({ success: true, result: { chunks: [] } }); + } + + const ns = await getAiSearch(); + if (!ns) { + return Response.json({ success: false, error: "Search is not available" }, { status: 503 }); + } + + const limit = body.ai_search_options?.retrieval?.max_num_results ?? 30; + const locale = typeof body.locale === "string" && body.locale ? body.locale : DEFAULT_LOCALE; + + try { + const instance = ns.get(AI_SEARCH_INSTANCE); + const nowSeconds = Math.floor(Date.now() / 1000); + // Built here where `query` is narrowed to string; the nested helper closure + // would otherwise widen it back to `string | undefined`. + const messages = [{ role: "user", content: query }]; + + async function runSearch(localeCode: string): Promise { + const response = await instance.search({ + messages, + ai_search_options: { + retrieval: { + max_num_results: limit, + // The plugin gates scheduled content behind `visible_after`. + filters: { visible_after: { $lte: nowSeconds }, locale: { $eq: localeCode } }, + }, + }, + }); + return response.chunks; + } + + let chunks = await runSearch(locale); + // Fall back to the default locale when the requested locale has no matches. + if (chunks.length === 0 && locale !== DEFAULT_LOCALE) { + chunks = await runSearch(DEFAULT_LOCALE); + } + + // Keep the highest-scoring chunk per indexed item. + 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); + } + } + + const resultChunks = Array.from(bestByKey.values(), (chunk) => { + const [collection = "", ...rest] = chunk.item.key.split("/"); + const id = rest.join("/").replace(MD_EXT, ""); + const meta = chunk.item.metadata ?? {}; + const slug = str(meta.slug) || id; + const { title, description } = unpackTitleDescription(str(meta.title_desc)); + const text = chunk.text?.trim(); + return { + id: chunk.item.key, + score: chunk.score, + item: { + key: `/${collection}/${slug}?lang=${encodeURIComponent(locale)}`, + metadata: { + title: title || slug, + description: text || description, + ...(str(meta.image) ? { image: str(meta.image) } : {}), + }, + }, + }; + }); + + return Response.json({ success: true, result: { chunks: resultChunks } }); + } catch { + return Response.json( + { success: false, error: "Search is temporarily unavailable" }, + { status: 500 }, + ); + } +}; 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/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/pnpm-lock.yaml b/pnpm-lock.yaml index e2fdeeb538..ce06f5624b 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 @@ -1594,12 +1597,21 @@ importers: '@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 +3701,12 @@ 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/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 +3723,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 +3743,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 +3758,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 +3780,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 +3792,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 +3801,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 +3810,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 +14258,8 @@ snapshots: fast-wrap-ansi: 0.2.0 sisteransi: 1.0.5 + '@cloudflare/ai-search-snippet@0.0.40': {} + '@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 From 1f8406d7e59b2284e79a60d14b4f3025acb87a0b Mon Sep 17 00:00:00 2001 From: ttmx Date: Thu, 16 Jul 2026 15:29:15 +0100 Subject: [PATCH 03/39] chore: AI Search changeset and lockfile --- .changeset/ai-search-plugin.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/ai-search-plugin.md diff --git a/.changeset/ai-search-plugin.md b/.changeset/ai-search-plugin.md new file mode 100644 index 0000000000..bd0d598258 --- /dev/null +++ b/.changeset/ai-search-plugin.md @@ -0,0 +1,5 @@ +--- +"@emdash-cms/cloudflare": minor +--- + +Adds AI Search plugin with content indexing, search modal, and admin settings UI. Includes a Cloudflare-native integration using the AI Search worker binding and a standalone package using the REST API. From faa7142478f8c8e8255d185b6d8982040f0436f0 Mon Sep 17 00:00:00 2001 From: ttmx Date: Thu, 16 Jul 2026 16:41:12 +0100 Subject: [PATCH 04/39] fix(ai-search): address review feedback --- .changeset/ai-search-plugin.md | 2 +- demos/cloudflare/src/layouts/Base.astro | 4 +- .../src/pages/api/ai-search/search.ts | 12 +- packages/cloudflare/package.json | 5 + .../src/plugins/ai-search-admin.tsx | 74 ++- packages/cloudflare/src/plugins/ai-search.ts | 103 ++-- .../tests/plugins/ai-search-indexing.test.ts | 449 ++++++++++++++++++ .../tests/plugins/ai-search.test.ts | 134 ++++++ pnpm-lock.yaml | 3 + 9 files changed, 718 insertions(+), 68 deletions(-) create mode 100644 packages/cloudflare/tests/plugins/ai-search-indexing.test.ts create mode 100644 packages/cloudflare/tests/plugins/ai-search.test.ts diff --git a/.changeset/ai-search-plugin.md b/.changeset/ai-search-plugin.md index bd0d598258..59e7ec55d1 100644 --- a/.changeset/ai-search-plugin.md +++ b/.changeset/ai-search-plugin.md @@ -2,4 +2,4 @@ "@emdash-cms/cloudflare": minor --- -Adds AI Search plugin with content indexing, search modal, and admin settings UI. Includes a Cloudflare-native integration using the AI Search worker binding and a standalone package using the REST API. +Adds a Cloudflare AI Search plugin with automatic content indexing, cron-driven reindexing, language-aware queries, synonyms, index status, and admin configuration. diff --git a/demos/cloudflare/src/layouts/Base.astro b/demos/cloudflare/src/layouts/Base.astro index 042d0fb8f6..c02f0c145f 100644 --- a/demos/cloudflare/src/layouts/Base.astro +++ b/demos/cloudflare/src/layouts/Base.astro @@ -927,7 +927,9 @@ const isLoggedIn = !!Astro.locals.user; diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 3e6f260bcc..83fd601201 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -1566,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) @@ -3708,6 +3711,10 @@ packages: 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==, tarball: https://registry.npmjs.org/@cloudflare/codemode/-/codemode-0.3.8.tgz} peerDependencies: @@ -14263,6 +14270,8 @@ snapshots: '@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 From fa2f435fffd634f4c0dab37275b58b624dd2365f Mon Sep 17 00:00:00 2001 From: ttmx Date: Thu, 30 Jul 2026 12:32:00 +0100 Subject: [PATCH 10/39] Fixed scheduled handler in worker.ts --- demos/cloudflare/src/worker.ts | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) 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; From 268a905a488707a68bd58822c4404a36c64030bd Mon Sep 17 00:00:00 2001 From: scottbuscemi Date: Thu, 30 Jul 2026 13:50:29 -0500 Subject: [PATCH 11/39] fix(ai-search): make public search endpoint work on anonymous requests MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The snippet search endpoint read `locals.emdash.db` to load synonyms, but on the anonymous request path EmDash only attaches the partial fast-path facade, where `db` is undefined. Every public (unauthenticated) search therefore threw "Cannot read properties of undefined (reading 'selectFrom')" and returned 503 "Search is temporarily unavailable" — i.e. site search was broken for all real visitors. Resolve a request-scoped runtime via `withEmDashRuntime()` (whose `db` works regardless of auth) instead. Import it lazily with a dynamic `import()`: a top-level import of `emdash/middleware` pulls the `astro:middleware` virtual module into Astro config evaluation (via `aiSearch()` in astro.config) and breaks `astro build` with an 'astro:' scheme error. Add tests: - ai-search-endpoint.test.ts: the endpoint wrapper succeeds when `locals.emdash.db` is undefined (and when `emdash` is absent), and never constructs OptionsRepository from an undefined db. - ai-search-build-safety.test.ts: guards that `emdash/middleware` is only referenced as `import type` or a dynamic import, so config-time evaluation never loads an 'astro:' module. --- packages/cloudflare/src/plugins/ai-search.ts | 39 ++++-- .../plugins/ai-search-build-safety.test.ts | 52 +++++++ .../tests/plugins/ai-search-endpoint.test.ts | 131 ++++++++++++++++++ 3 files changed, 207 insertions(+), 15 deletions(-) create mode 100644 packages/cloudflare/tests/plugins/ai-search-build-safety.test.ts create mode 100644 packages/cloudflare/tests/plugins/ai-search-endpoint.test.ts diff --git a/packages/cloudflare/src/plugins/ai-search.ts b/packages/cloudflare/src/plugins/ai-search.ts index 4a4e7648a9..c3cda5b180 100644 --- a/packages/cloudflare/src/plugins/ai-search.ts +++ b/packages/cloudflare/src/plugins/ai-search.ts @@ -1395,21 +1395,30 @@ export async function handleAISearchSnippetRequest( } export function createAISearchSnippetEndpoint(config?: AISearchConfig): APIRoute { - return async ({ request, locals }) => { - const emdash = (locals as typeof locals & { emdash?: EmDashRuntime }).emdash; - if (!emdash) { - return Response.json({ success: false, error: "Search is not available" }, { status: 503 }); - } - - const options = new OptionsRepository(emdash.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", + 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) => { + 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", + }); }); }; } diff --git a/packages/cloudflare/tests/plugins/ai-search-build-safety.test.ts b/packages/cloudflare/tests/plugins/ai-search-build-safety.test.ts new file mode 100644 index 0000000000..1702fe6924 --- /dev/null +++ b/packages/cloudflare/tests/plugins/ai-search-build-safety.test.ts @@ -0,0 +1,52 @@ +import { readFileSync } from "node:fs"; +import { fileURLToPath } from "node:url"; + +import { describe, it, expect } from "vitest"; + +// Build-safety regression guard. +// +// `demos/*/astro.config.mjs` imports `aiSearch` from +// `@emdash-cms/cloudflare/plugins`, so the ai-search module is evaluated by the +// Astro *config loader*, which runs under plain Node ESM. `emdash/middleware` +// transitively imports `astro:middleware` (a virtual module) at its top level. +// If ai-search.ts imports `emdash/middleware` as a VALUE at the top level, that +// specifier is pulled into config evaluation and `astro build` fails with: +// "Only URLs with a scheme in: file, data, and node are supported ... +// Received protocol 'astro:'" +// +// The runtime (`withEmDashRuntime`) must therefore be loaded lazily via a +// dynamic `import()` inside the request handler, and any `emdash/middleware` +// reference at the top level must be `import type` only (erased at compile). +const source = readFileSync( + fileURLToPath(new URL("../../src/plugins/ai-search.ts", import.meta.url)), + "utf8", +); + +describe("ai-search.ts must not eagerly import runtime-only Astro modules", () => { + it("only references emdash/middleware as `import type` or a dynamic import", () => { + const lines = source.split("\n"); + const offending: string[] = []; + + for (const raw of lines) { + const line = raw.trim(); + if (!line.includes("emdash/middleware")) continue; + const isTypeOnlyImport = /^import\s+type\b/.test(line); + const isDynamicImport = /\bimport\s*\(/.test(line); + const isComment = line.startsWith("//") || line.startsWith("*") || line.startsWith("/*"); + if (!isTypeOnlyImport && !isDynamicImport && !isComment) { + offending.push(line); + } + } + + expect( + offending, + `A top-level value import of "emdash/middleware" breaks \`astro build\` (astro: scheme). ` + + `Use a dynamic import() inside the handler or \`import type\`. Offending lines:\n` + + offending.join("\n"), + ).toEqual([]); + }); + + it("loads emdash/middleware through a dynamic import inside the endpoint", () => { + expect(source).toMatch(/await import\(\s*["']emdash\/middleware["']\s*\)/); + }); +}); 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..ae548f5cdc --- /dev/null +++ b/packages/cloudflare/tests/plugins/ai-search-endpoint.test.ts @@ -0,0 +1,131 @@ +import { describe, it, expect, vi } from "vitest"; + +// The AI Search snippet endpoint is PUBLIC: anonymous site visitors hit it for +// site search. On the anonymous request path EmDash attaches only a partial +// `locals.emdash` facade whose `db` getter is undefined. The endpoint must NOT +// read `locals.emdash.db` directly (that throws +// "Cannot read properties of undefined (reading 'selectFrom')" when it loads +// synonyms); it must resolve a real, request-scoped runtime via +// `withEmDashRuntime()`. +// +// These tests mock the AI Search binding, `emdash` (OptionsRepository), and +// `emdash/middleware` (withEmDashRuntime) so we can drive the endpoint wrapper +// exactly the way an anonymous request does. + +const { fakeEnv, controls } = vi.hoisted(() => { + const state = { + 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: () => {} })); + +// A tracked OptionsRepository that records the db handle it was constructed +// with, so we can assert the endpoint never passes `undefined`. +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) { + // Mirror the real failure mode: OptionsRepository.get() calls + // this.db.selectFrom(...), which throws on a nullish db. + throw new TypeError("Cannot read properties of undefined (reading 'selectFrom')"); + } + } + async get() { + return null; + } + } + return { ...actual, OptionsRepository: TrackingOptionsRepository }; +}); + +// withEmDashRuntime yields a fully-initialized runtime whose `.db` is always a +// real handle, regardless of request auth. This is the whole point of the fix. +const { runtimeDbHandle } = vi.hoisted(() => ({ runtimeDbHandle: { selectFrom: () => ({}) } })); +vi.mock("emdash/middleware", () => ({ + withEmDashRuntime: async (run: (rt: { db: unknown }) => unknown) => + run({ db: runtimeDbHandle }), +})); + +const { createAISearchSnippetEndpoint } = await import("../../src/plugins/ai-search.js"); + +/** Build an APIContext-ish object with the ANONYMOUS fast-path facade. */ +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), + }), + // The anonymous fast-path facade: `emdash` exists but has NO `db`. + 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 () => { + 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" }] })); + + // Before the fix this threw synchronously (undefined db) -> 503/500. + expect(response.status).toBe(200); + await expect(response.json()).resolves.toMatchObject({ success: true }); + + // The OptionsRepository must have been built from the withEmDashRuntime + // db handle, never from the (undefined) locals facade db. + expect(optionsConstructedWith).toContain(runtimeDbHandle); + expect(optionsConstructedWith).not.toContain(undefined); + }); + + it("still works when locals has no emdash at all", async () => { + 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); + }); +}); From b4a56aac6b11180c073726d7c30359b935d785eb Mon Sep 17 00:00:00 2001 From: "emdashbot[bot]" Date: Thu, 30 Jul 2026 18:54:44 +0000 Subject: [PATCH 12/39] style: format --- .../cloudflare/tests/plugins/ai-search-endpoint.test.ts | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/packages/cloudflare/tests/plugins/ai-search-endpoint.test.ts b/packages/cloudflare/tests/plugins/ai-search-endpoint.test.ts index ae548f5cdc..79fe24b048 100644 --- a/packages/cloudflare/tests/plugins/ai-search-endpoint.test.ts +++ b/packages/cloudflare/tests/plugins/ai-search-endpoint.test.ts @@ -65,8 +65,7 @@ vi.mock("emdash", async (importOriginal) => { // real handle, regardless of request auth. This is the whole point of the fix. const { runtimeDbHandle } = vi.hoisted(() => ({ runtimeDbHandle: { selectFrom: () => ({}) } })); vi.mock("emdash/middleware", () => ({ - withEmDashRuntime: async (run: (rt: { db: unknown }) => unknown) => - run({ db: runtimeDbHandle }), + withEmDashRuntime: async (run: (rt: { db: unknown }) => unknown) => run({ db: runtimeDbHandle }), })); const { createAISearchSnippetEndpoint } = await import("../../src/plugins/ai-search.js"); @@ -99,7 +98,9 @@ describe("createAISearchSnippetEndpoint() on the anonymous request path", () => ]; const endpoint = createAISearchSnippetEndpoint(); - const response = await endpoint(anonymousContext({ messages: [{ role: "user", content: "hi" }] })); + const response = await endpoint( + anonymousContext({ messages: [{ role: "user", content: "hi" }] }), + ); // Before the fix this threw synchronously (undefined db) -> 503/500. expect(response.status).toBe(200); From 113f90e0393b42692d2474d57bbe3b10d8122d80 Mon Sep 17 00:00:00 2001 From: ttmx Date: Thu, 30 Jul 2026 20:24:24 +0100 Subject: [PATCH 13/39] Add docs for the Cloudflare AI Search plugin --- .../content/docs/deployment/cloudflare.mdx | 59 ++++++++++++++++++- 1 file changed, 58 insertions(+), 1 deletion(-) diff --git a/docs/src/content/docs/deployment/cloudflare.mdx b/docs/src/content/docs/deployment/cloudflare.mdx index 14f3729241..878cec9502 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,63 @@ 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 + ``` + + +After deployment, open **Settings > AI Search** in the EmDash admin panel to choose which collections to index and monitor indexing progress. New and updated published content is kept in sync automatically. + ## Email On Workers, the only built-in `email:deliver` handler is a dev console stub, so From 8689771bf30610b7f46ee73b3bb454c996ad0979 Mon Sep 17 00:00:00 2001 From: ttmx Date: Thu, 30 Jul 2026 20:30:25 +0100 Subject: [PATCH 14/39] Change plugin name from AI Search to Cloudflare AI Search --- packages/cloudflare/src/plugins/ai-search.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/cloudflare/src/plugins/ai-search.ts b/packages/cloudflare/src/plugins/ai-search.ts index c3cda5b180..117343f28e 100644 --- a/packages/cloudflare/src/plugins/ai-search.ts +++ b/packages/cloudflare/src/plugins/ai-search.ts @@ -768,7 +768,7 @@ export function aiSearch(config: AISearchConfig = {}): PluginDescriptor Date: Fri, 31 Jul 2026 16:59:17 +0100 Subject: [PATCH 15/39] Simplify uploadItem() --- packages/cloudflare/src/plugins/ai-search.ts | 62 ++----------------- .../tests/plugins/ai-search-indexing.test.ts | 11 ++-- 2 files changed, 12 insertions(+), 61 deletions(-) diff --git a/packages/cloudflare/src/plugins/ai-search.ts b/packages/cloudflare/src/plugins/ai-search.ts index 117343f28e..b58a82a2d4 100644 --- a/packages/cloudflare/src/plugins/ai-search.ts +++ b/packages/cloudflare/src/plugins/ai-search.ts @@ -419,66 +419,18 @@ async function retry(operation: () => Promise): Promise { throw lastError; } -interface UploadItemOptions { - /** Called as soon as AI Search accepts the upload, before mirror bookkeeping. */ - onUploaded?: (item: AiSearchItemInfo) => Promise; - /** Leave accepted uploads in place when mirror bookkeeping fails. */ - tolerateMirrorFailure?: boolean; -} - -/** Replace a mirrored item before uploading because AI Search keys are unique. */ +/** 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, - options: UploadItemOptions = {}, ): Promise { const mirrorKey = `item:${key}`; - const previousId = await ctx.kv.get(mirrorKey); - let previousRemoved = false; - if (previousId) { - try { - await instance.items.delete(previousId); - previousRemoved = true; - } catch { - // A stale mirror is harmless: upload will either succeed or surface - // the real key conflict to the caller. - } - } + const item = await instance.items.upload(key, markdown, { metadata }); - let item: AiSearchItemInfo; - try { - item = await instance.items.upload(key, markdown, { metadata }); - } catch (error) { - if (previousRemoved) await ctx.kv.delete(mirrorKey); - throw error; - } - // AI Search's non-polling upload call returning without throwing is the - // acceptance boundary. Reindex progress is checkpointed here; indexing may - // continue asynchronously inside AI Search. - await options.onUploaded?.(item); - - if (!item?.id) { - if (options.tolerateMirrorFailure) return; - throw new Error(`upload for ${key} returned no item id`); - } - try { - await ctx.kv.set(mirrorKey, item.id); - } catch (error) { - if (options.tolerateMirrorFailure) { - console.error(`[ai-search] Failed to mirror accepted upload ${key}:`, error); - return; - } - // Hook-driven writes retain their stronger rollback guarantee. Reindexing - // can reconcile an accepted-but-unmirrored upload in a later pass. - try { - await instance.items.delete(item.id); - } catch {} - if (previousRemoved) await ctx.kv.delete(mirrorKey); - throw error; - } + await ctx.kv.set(mirrorKey, item.id); } function createReindexJob(collections: string[], onlyMissing: boolean): ReindexJob { @@ -1006,12 +958,8 @@ export function createPlugin(config: AISearchConfig = {}): ResolvedPlugin { }; const image = extractImageUrl(record); if (image) metadata.image = image; - await retry(() => - uploadItem(instance, key, markdown, metadata, ctx, { - onUploaded: () => checkpointAcceptedUpload(key), - tolerateMirrorFailure: true, - }), - ); + 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++; diff --git a/packages/cloudflare/tests/plugins/ai-search-indexing.test.ts b/packages/cloudflare/tests/plugins/ai-search-indexing.test.ts index ebdafbe4a8..e8ccaf17d9 100644 --- a/packages/cloudflare/tests/plugins/ai-search-indexing.test.ts +++ b/packages/cloudflare/tests/plugins/ai-search-indexing.test.ts @@ -241,7 +241,7 @@ describe("ai-search reindex jobs", () => { expect(complete.indexed).toBe(3); }); - it("replaces an item already mirrored by EmDash", async () => { + it("overwrites an item already mirrored by EmDash without deleting it first", async () => { uploads.length = 0; deletions.length = 0; controls.uploadFailures = 0; @@ -271,11 +271,13 @@ describe("ai-search reindex jobs", () => { await handler(routeContext(ctx, { collections: ["posts"] }) as never); await runReindexCron(plugin, ctx); - expect(deletions).toContain("old-item-id"); 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("clears a stale mirror when replacement uploads exhaust their retries", async () => { + it("preserves the mirrored item when replacement uploads exhaust their retries", async () => { uploads.length = 0; deletions.length = 0; controls.uploadFailures = 3; @@ -305,7 +307,8 @@ describe("ai-search reindex jobs", () => { await handler(routeContext(ctx, { collections: ["posts"] }) as never); await runReindexCron(plugin, ctx); - expect(await ctx.kv.get("item:posts/broken.md")).toBeNull(); + expect(deletions).toHaveLength(0); + expect(await ctx.kv.get("item:posts/broken.md")).toBe("old-item-id"); }); }); From 9c5acdfdfcbb91e0870ac5d9427bd429a180e306 Mon Sep 17 00:00:00 2001 From: ttmx Date: Fri, 31 Jul 2026 17:09:15 +0100 Subject: [PATCH 16/39] Remove "limit" from AISearchQueryInput, it is configurable in the instance. --- packages/cloudflare/src/plugins/ai-search.ts | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/packages/cloudflare/src/plugins/ai-search.ts b/packages/cloudflare/src/plugins/ai-search.ts index b58a82a2d4..10245e0e93 100644 --- a/packages/cloudflare/src/plugins/ai-search.ts +++ b/packages/cloudflare/src/plugins/ai-search.ts @@ -565,7 +565,6 @@ async function getSynonymRewriter(kv: KVReader): Promise { interface AISearchQueryInput { query: string; locale: string; - limit: number; collection?: string; } @@ -651,7 +650,6 @@ export async function searchAISearch( messages: [{ role: "user", content: effectiveQuery }], ai_search_options: { retrieval: { - max_num_results: input.limit, filters: { visible_after: { $lte: nowSeconds }, locale: { $eq: locale }, @@ -1316,11 +1314,7 @@ export async function handleAISearchSnippetRequest( return Response.json({ success: true, result: { search_query: "", chunks: [] } }); } - const requestedLimit = body.ai_search_options?.retrieval?.max_num_results; - const limit = - typeof requestedLimit === "number" && Number.isFinite(requestedLimit) - ? Math.max(1, Math.min(Math.floor(requestedLimit), 100)) - : 30; + const locale = typeof body.locale === "string" && body.locale ? body.locale : options.defaultLocale; const collection = @@ -1329,7 +1323,7 @@ export async function handleAISearchSnippetRequest( try { const result = await searchAISearch( options.config, - { query: query.trim(), locale, limit, collection }, + { query: query.trim(), locale, collection }, options.kv, options.defaultLocale, ); From 6dc9db00a37b77142125a50cbe5911e395c6c145 Mon Sep 17 00:00:00 2001 From: ttmx Date: Fri, 31 Jul 2026 17:28:01 +0100 Subject: [PATCH 17/39] Don't index draft content if post was previously indexed. --- packages/cloudflare/src/plugins/ai-search.ts | 5 ++++ .../tests/plugins/ai-search-indexing.test.ts | 25 +++++++++++++++++++ 2 files changed, 30 insertions(+) diff --git a/packages/cloudflare/src/plugins/ai-search.ts b/packages/cloudflare/src/plugins/ai-search.ts index 10245e0e93..e7a48bd2d5 100644 --- a/packages/cloudflare/src/plugins/ai-search.ts +++ b/packages/cloudflare/src/plugins/ai-search.ts @@ -1022,6 +1022,11 @@ export function createPlugin(config: AISearchConfig = {}): ResolvedPlugin { "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 (!(await shouldSync(collection, ctx))) return; // Sync based on the current status: published content is visible diff --git a/packages/cloudflare/tests/plugins/ai-search-indexing.test.ts b/packages/cloudflare/tests/plugins/ai-search-indexing.test.ts index e8ccaf17d9..aeae2bc7e8 100644 --- a/packages/cloudflare/tests/plugins/ai-search-indexing.test.ts +++ b/packages/cloudflare/tests/plugins/ai-search-indexing.test.ts @@ -521,4 +521,29 @@ describe("ai-search content:afterSave indexing", () => { 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); + }); }); From 29a9ecef0d45f41f94111e4d5ace0b2ac28ca86e Mon Sep 17 00:00:00 2001 From: ttmx Date: Fri, 31 Jul 2026 17:59:53 +0100 Subject: [PATCH 18/39] Actually disable ai search plugin endpoint when plugin is disabled. --- packages/cloudflare/src/plugins/ai-search.ts | 3 +++ .../tests/plugins/ai-search-endpoint.test.ts | 26 ++++++++++++++++++- 2 files changed, 28 insertions(+), 1 deletion(-) diff --git a/packages/cloudflare/src/plugins/ai-search.ts b/packages/cloudflare/src/plugins/ai-search.ts index e7a48bd2d5..e9c829c5c7 100644 --- a/packages/cloudflare/src/plugins/ai-search.ts +++ b/packages/cloudflare/src/plugins/ai-search.ts @@ -1356,6 +1356,9 @@ export function createAISearchSnippetEndpoint(config?: AISearchConfig): APIRoute // 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 = { diff --git a/packages/cloudflare/tests/plugins/ai-search-endpoint.test.ts b/packages/cloudflare/tests/plugins/ai-search-endpoint.test.ts index 79fe24b048..696c42176e 100644 --- a/packages/cloudflare/tests/plugins/ai-search-endpoint.test.ts +++ b/packages/cloudflare/tests/plugins/ai-search-endpoint.test.ts @@ -14,6 +14,7 @@ import { describe, it, expect, vi } from "vitest"; const { fakeEnv, controls } = vi.hoisted(() => { const state = { + pluginEnabled: true, searchChunks: [] as Array>, searchRequests: [] as Array>, }; @@ -65,7 +66,13 @@ vi.mock("emdash", async (importOriginal) => { // real handle, regardless of request auth. This is the whole point of the fix. const { runtimeDbHandle } = vi.hoisted(() => ({ runtimeDbHandle: { selectFrom: () => ({}) } })); vi.mock("emdash/middleware", () => ({ - withEmDashRuntime: async (run: (rt: { db: unknown }) => unknown) => run({ db: runtimeDbHandle }), + 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"); @@ -85,6 +92,7 @@ function anonymousContext(body: unknown) { 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 = [ @@ -113,6 +121,7 @@ describe("createAISearchSnippetEndpoint() on the anonymous request path", () => }); it("still works when locals has no emdash at all", async () => { + controls.pluginEnabled = true; optionsConstructedWith.length = 0; controls.searchChunks = []; const endpoint = createAISearchSnippetEndpoint(); @@ -129,4 +138,19 @@ describe("createAISearchSnippetEndpoint() on the anonymous request path", () => 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); + }); }); From e426115176d1368ffea145b9764faa14395a6c51 Mon Sep 17 00:00:00 2001 From: "emdashbot[bot]" Date: Fri, 31 Jul 2026 17:08:51 +0000 Subject: [PATCH 19/39] style: format --- packages/cloudflare/src/plugins/ai-search.ts | 1 - packages/cloudflare/tests/plugins/ai-search-endpoint.test.ts | 5 ++++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/packages/cloudflare/src/plugins/ai-search.ts b/packages/cloudflare/src/plugins/ai-search.ts index e9c829c5c7..bdcaa65589 100644 --- a/packages/cloudflare/src/plugins/ai-search.ts +++ b/packages/cloudflare/src/plugins/ai-search.ts @@ -1319,7 +1319,6 @@ export async function handleAISearchSnippetRequest( return Response.json({ success: true, result: { search_query: "", chunks: [] } }); } - const locale = typeof body.locale === "string" && body.locale ? body.locale : options.defaultLocale; const collection = diff --git a/packages/cloudflare/tests/plugins/ai-search-endpoint.test.ts b/packages/cloudflare/tests/plugins/ai-search-endpoint.test.ts index 696c42176e..03592ec71c 100644 --- a/packages/cloudflare/tests/plugins/ai-search-endpoint.test.ts +++ b/packages/cloudflare/tests/plugins/ai-search-endpoint.test.ts @@ -67,7 +67,10 @@ vi.mock("emdash", async (importOriginal) => { 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: (rt: { + db: unknown; + getPluginRouteMeta: (id: string, path: string) => object | null; + }) => unknown, ) => run({ db: runtimeDbHandle, From 770beeff005a6c828a566580506d7eb8fee55eec Mon Sep 17 00:00:00 2001 From: ttmx Date: Mon, 3 Aug 2026 12:27:36 +0100 Subject: [PATCH 20/39] Clarify AI Search result limit ownership --- packages/cloudflare/src/plugins/ai-search.ts | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/packages/cloudflare/src/plugins/ai-search.ts b/packages/cloudflare/src/plugins/ai-search.ts index bdcaa65589..39a802e3b7 100644 --- a/packages/cloudflare/src/plugins/ai-search.ts +++ b/packages/cloudflare/src/plugins/ai-search.ts @@ -1289,7 +1289,10 @@ interface SnippetSearchBody { locale?: unknown; collection?: unknown; ai_search_options?: { - retrieval?: { max_num_results?: unknown }; + retrieval?: { + /** Configured in the AI Search backoffice rather than controlled by public clients. */ + max_num_results?: unknown; + }; }; } From a5a7a1801648aeb08d8dee384608a19db87cede1 Mon Sep 17 00:00:00 2001 From: ttmx Date: Mon, 3 Aug 2026 12:34:02 +0100 Subject: [PATCH 21/39] Remove narrative comments from Cloudflare demo --- demos/cloudflare/src/layouts/Base.astro | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/demos/cloudflare/src/layouts/Base.astro b/demos/cloudflare/src/layouts/Base.astro index 6c300690c4..380a6e298b 100644 --- a/demos/cloudflare/src/layouts/Base.astro +++ b/demos/cloudflare/src/layouts/Base.astro @@ -22,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 }; } @@ -40,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", @@ -71,7 +62,6 @@ const pageCtx = createPublicPageContext({ siteName: siteTitle, }); -// Check if user is logged in (for showing admin link) const isLoggedIn = !!Astro.locals.user; --- @@ -290,7 +280,6 @@ const isLoggedIn = !!Astro.locals.user;