feat(cloudflare/ai-search): AiSearch, AiSearchInstance and AiSearchNamespace

[sam-goodwin]

Full Cloudflare AI Search (AutoRAG) coverage: a convenience construct with a discriminated data source, Worker bindings in both Effect-native and async styles, and the underlying namespace-scoped resources.

AiSearch construct — discriminated by source

The fast path for the common case. It picks the data source from what you pass as source: an R2Bucket for R2, or a URL string for a web crawl.

// R2 — pass the bucket; the construct mints the service token for you
const bucket = yield* Cloudflare.R2Bucket("docs");
const search = yield* Cloudflare.AiSearch("docs-search", {
  source: bucket,
});

// Web crawler — pass a URL; no service token needed
const crawlStore = yield* Cloudflare.R2Bucket("crawl-store");
yield* Cloudflare.AiSearch("site-search", {
  source: "https://example.com",
  parse: { type: "crawl" },
  crawl: { depth: 3, includeSubdomains: true },
  store: { bucket: crawlStore },
});

For R2, the construct mints a least-privilege AccountApiToken (AI Search Index Engine) + AiSearchToken and wires it into the instance — Cloudflare only provisions this token via dashboard/Wrangler, never on a programmatic create. Pass your own tokenId to skip minting.

Source-specific options are flattened onto the props:

• R2: prefix, include / exclude (micromatch globs, max 10 each, exclude wins), jurisdiction.
• Web crawler: parse, crawl, store (an R2 bucket to hold crawl output).

Group pipelines under a namespace by passing the AiSearchNamespace resource itself (not its name) — the engine then orders the pipeline after the namespace on deploy and before it on destroy:

const ns = yield* Cloudflare.AiSearchNamespace("docs", {});
const search = yield* Cloudflare.AiSearch("docs-search", {
  source: bucket,
  namespace: ns,
});

Worker bindings (Effect-native + async)

Bindings resolve to the current AiSearchInstance / AiSearchNamespace runtime shapes (the deprecated AutoRAG shape is gone). Bind the AiSearch result during a Worker's init phase with Cloudflare.AiSearchInstance.bind(search) for an Effect-native client:

const search = yield* Cloudflare.AiSearch("docs-search", { source: bucket });
const client = yield* Cloudflare.AiSearchInstance.bind(search);

const answer = yield* client.chatCompletions({
  messages: [{ role: "user", content: query }],
});
const hits = yield* client.search({ query }); // retrieval only

The client surfaces chatCompletions (retrieval + generation), search (retrieval only), info, stats, and raw. The namespace client adds .get(name), namespace-wide list / search, and raw.

Or pass it via env for a vanilla async Worker. InferEnv maps both flavors to the runtime types (AiSearchInstance, AiSearchNamespace):

const worker = yield* Cloudflare.Worker("api", {
  main: "./worker.ts",
  env: { SEARCH: search, NS: namespace },
});

Underlying resources

The construct is just these resources composed; drop down when you need to share a token across instances or adopt an existing one.

• AiSearchInstance uses the namespace-scoped API and exposes a namespace attribute (its identity is instanceId). The namespace, source, type, and embeddingModel are immutable — changing any replaces the instance.
• AiSearchNamespace treats the account-provided default namespace as reserved: it's bindable and adoptable but never updated or deleted on teardown (Cloudflare disallows deleting it).
• AiSearchToken wraps an AccountApiToken into the service-token shape the R2 indexer needs.

Docs

• New tutorial tutorial/cloudflare/ai-search favoring the AiSearch helper, explaining what it provisions and binding it into an Effect / async Worker.
• Richer resource-level JSDoc on AiSearch, AiSearchInstance, and AiSearchNamespace (R2-first ordering, source filters, web-crawler options, namespace grouping via the AiSearch construct, Effect/async binding), regenerated API reference.

distilled

Depends on the namespace-scoped instance operations (create/read/update/list/delete) with resource-qualified typed errors (AiSearchInstanceNotFound, NamespaceNotFound, WebCrawlerDomainNotOwned, …), pushed to distilled main and bumped here.

Tests

Live-tested against Cloudflare: Namespace, Instance (incl. custom-namespace + replacement), Token, the AiSearch construct (R2 + web-crawler), and Bindings (async + Effect workers). Web-crawler lifecycle uses an account-owned workers.dev target; an ungated probe asserts the WebCrawlerDomainNotOwned typed error for unowned domains.

[alchemy-version-bot]

Install the packages built from this commit:

alchemy

bun add alchemy@https://pkg.ing/alchemy/230210f

@alchemy.run/better-auth

bun add @alchemy.run/better-auth@https://pkg.ing/@alchemy.run/better-auth/230210f

@alchemy.run/pr-package

bun add @alchemy.run/pr-package@https://pkg.ing/@alchemy.run/pr-package/230210f