feat(cloudflare): AI Search (#1317)

Co-authored-by: Sam Goodwin <sam@alchemy.run>
Co-authored-by: John Royal <34844819+john-royal@users.noreply.github.com>

Author: 3 people

alchemy-web/src/content/docs/providers/cloudflare/ai-crawler.md

@@ -0,0 +1,124 @@
+---
+title: AiCrawler
+description: Helper function to build AI Search web crawler configuration from URLs.
+---
+
+The `AiCrawler` helper function builds an `AiSearchWebCrawlerSource` configuration from URLs. It extracts the domain and path filters automatically, making it easy to set up web crawling for AI Search.
+
+## Minimal Example
+
+```ts
+import { AiSearch, AiCrawler } from "alchemy/cloudflare";
+
+const search = await AiSearch("docs-search", {
+  source: AiCrawler(["https://docs.example.com"]),
+});
+```
+
+## Crawl Specific Paths
+
+Provide multiple URLs to crawl specific sections of a site. The function automatically extracts the domain and builds path filters:
+
+```ts
+import { AiSearch, AiCrawler } from "alchemy/cloudflare";
+
+const search = await AiSearch("blog-search", {
+  source: AiCrawler([
+    "https://example.com/blog",
+    "https://example.com/news",
+  ]),
+});
+```
+
+This is equivalent to:
+
+```ts
+const search = await AiSearch("blog-search", {
+  source: {
+    type: "web-crawler",
+    domain: "example.com",
+    includePaths: ["**/blog**", "**/news**"],
+  },
+});
+```
+
+## How It Works
+
+`AiCrawler` performs the following transformations:
+
+1. **Parses URLs** - Extracts the hostname and path from each URL
+2. **Validates domain** - Ensures all URLs are from the same domain
+3. **Builds path filters** - Converts URL paths to glob patterns for `includePaths`
+
+```ts
+// Input
+AiCrawler([
+  "https://docs.example.com/getting-started",
+  "https://docs.example.com/api-reference",
+])
+
+// Output (AiSearchWebCrawlerSource)
+{
+  type: "web-crawler",
+  domain: "docs.example.com",
+  includePaths: ["**/getting-started**", "**/api-reference**"],
+}
+```
+
+## Domain Requirements
+
+:::warning
+The domain must be:
+- Added as a zone in your Cloudflare account
+- Have active nameservers pointing to Cloudflare
+- All URLs must be from the same domain
+:::
+
+If you try to crawl URLs from different domains, `AiCrawler` will throw an error:
+
+```ts
+// This will throw an error
+AiCrawler([
+  "https://docs.example.com",
+  "https://blog.example.org", // Different domain!
+]);
+// Error: All URLs must be from the same domain. Found: docs.example.com, blog.example.org
+```
+
+## URL Format Flexibility
+
+`AiCrawler` accepts URLs with or without the protocol:
+
+```ts
+// All of these work
+AiCrawler(["https://docs.example.com"])
+AiCrawler(["http://docs.example.com"])
+AiCrawler(["docs.example.com"]) // Protocol added automatically
+```
+
+## Complete Example
+
+```ts
+import { AiSearch, AiCrawler, Worker, Ai } from "alchemy/cloudflare";
+
+// Create AI Search instance that crawls documentation
+const search = await AiSearch("docs-search", {
+  source: AiCrawler(["https://docs.example.com"]),
+  chunkSize: 512,
+  reranking: true,
+});
+
+// Create a worker to query the search
+await Worker("search-api", {
+  entrypoint: "./src/worker.ts",
+  bindings: {
+    AI: Ai(),
+    RAG_NAME: search.name,
+  },
+});
+```
+
+## See Also
+
+- [AiSearch](/providers/cloudflare/ai-search) - The main AI Search resource
+- [Cloudflare AI Search Documentation](https://developers.cloudflare.com/ai-search/)

alchemy-web/src/content/docs/providers/cloudflare/ai-search-token.md

@@ -0,0 +1,111 @@
+---
+title: AiSearchToken
+description: Learn how to create and manage Cloudflare AI Search service tokens for authenticating with the AI Search API using Alchemy.
+---
+
+The AiSearchToken resource creates a service token for authenticating with [Cloudflare AI Search](https://developers.cloudflare.com/ai-search/). This token is required for AI Search to access your R2 buckets or other data sources.
+
+:::note
+In most cases, you don't need to create this resource directly. The [AiSearch](/providers/cloudflare/ai-search) resource automatically detects existing tokens or creates one for you.
+:::
+
+## When to Use
+
+Use `AiSearchToken` explicitly when you need to:
+
+- Share a single token across multiple AI Search instances
+- Have fine-grained control over token lifecycle
+- Inspect token properties (e.g., `tokenId`, `cfApiId`)
+
+## Minimal Example
+
+Create an AI Search token and use it with an AI Search instance:
+
+```ts
+import { AiSearch, AiSearchToken, R2Bucket } from "alchemy/cloudflare";
+
+const bucket = await R2Bucket("docs", { name: "my-docs" });
+
+const token = await AiSearchToken("search-token", {
+  name: "docs-search-token",
+});
+
+const search = await AiSearch("docs-search", {
+  source: {
+    type: "r2",
+    bucket,
+    token,
+  },
+});
+```
+
+## Share Token Across Instances
+
+Use a single token for multiple AI Search instances:
+
+```ts
+import { AiSearch, AiSearchToken, R2Bucket } from "alchemy/cloudflare";
+
+const docsToken = await AiSearchToken("shared-token", {
+  name: "shared-docs-token",
+});
+
+const docsBucket = await R2Bucket("docs", { name: "docs-bucket" });
+const blogBucket = await R2Bucket("blog", { name: "blog-bucket" });
+
+const docsSearch = await AiSearch("docs-search", {
+  source: { type: "r2", bucket: docsBucket, token: docsToken },
+});
+
+const blogSearch = await AiSearch("blog-search", {
+  source: { type: "r2", bucket: blogBucket, token: docsToken },
+});
+```
+
+## Adopt Existing Token
+
+Adopt a token that already exists in your account:
+
+```ts
+import { AiSearchToken } from "alchemy/cloudflare";
+
+const token = await AiSearchToken("existing-token", {
+  name: "my-existing-token",
+  adopt: true,
+});
+```
+
+## How It Works
+
+When you create an `AiSearchToken`, Alchemy:
+
+1. Creates an **account API token** with the required permissions:
+   - `AI Search Index Engine` — allows AI Search to index and query data
+   - `Workers R2 Storage Write` — allows AI Search to read from R2 buckets
+2. Registers the token with the **AI Search service**
+3. Returns the token details including the `tokenId` and `cfApiKey`
+
+When the resource is destroyed, both the AI Search token registration and the underlying account API token are cleaned up.
+
+## Configuration Options
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `name` | `string` | resource ID | Name of the token |
+| `adopt` | `boolean` | `false` | Adopt an existing token with the same name |
+| `delete` | `boolean` | `true` | Delete the token when removed from Alchemy |
+
+## Output Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `tokenId` | `string` | The AI Search token ID (UUID) |
+| `accountTokenId` | `string` | The underlying account API token ID |
+| `accountId` | `string` | The Cloudflare account ID |
+| `accountTag` | `string` | The Cloudflare account tag |
+| `name` | `string` | Name of the token |
+| `cfApiId` | `string` | The CF API ID for this token |
+| `cfApiKey` | `Secret` | The CF API key (stored securely) |
+| `enabled` | `boolean` | Whether the token is enabled |
+| `createdAt` | `string` | When the token was created |
+| `modifiedAt` | `string` | When the token was last modified |