alchemy 2.0.0-beta.56 → 2.0.0-beta.57

package/src/Cloudflare/Access/Policy.ts

@@ -132,7 +132,9 @@ export type AccessPolicy = Resource<
  * A reusable, account-scoped Cloudflare Access policy. Distinct from the
  * inline policies attached directly to an `AccessApplication` — a reusable
  * policy can be referenced by multiple applications by id.
- *
+ * @resource
+ * @product Access
+ * @category Cloudflare One (Zero Trust)
  * @section Creating a Policy
  * @example Allow a single email domain
  * ```typescript

package/src/Cloudflare/Access/ServiceToken.ts

@@ -80,7 +80,9 @@ export type AccessServiceToken = Resource<
  *
  * The client secret is only revealed by Cloudflare on create and rotate; the
  * provider stores it redacted in state and carries it forward across reads.
- *
+ * @resource
+ * @product Access
+ * @category Cloudflare One (Zero Trust)
  * @section Creating a Service Token
  * @example Basic token with a generated name
  * ```typescript

package/src/Cloudflare/Access/Tag.ts

@@ -41,7 +41,9 @@ export type AccessTag = Resource<
  *
  * The tag's name is its identity — there is nothing to update in place, so
  * renaming replaces the tag.
- *
+ * @resource
+ * @product Access
+ * @category Cloudflare One (Zero Trust)
  * @section Creating a Tag
  * @example Tag with a generated name
  * ```typescript

package/src/Cloudflare/Account/Account.ts

@@ -116,7 +116,9 @@ export type Account = Resource<
  * The account's physical identity is the Cloudflare-assigned `accountId`.
  * Account names are not unique, so there is no find-by-name fallback: if
  * state is lost, the account is treated as missing rather than guessed at.
- *
+ * @resource
+ * @product Accounts
+ * @category Account & Identity
  * @section Creating an account
  * @example Standard subaccount with a generated name
  * ```typescript

package/src/Cloudflare/Account/Member.ts

@@ -128,7 +128,9 @@ export type AccountMember = Resource<
  * state, `read` scans the account for an existing membership with the same
  * email and reports it as `Unowned`, so the engine refuses to take it over
  * unless `--adopt` (or `adopt(true)`) is set.
- *
+ * @resource
+ * @product Accounts
+ * @category Account & Identity
  * @section Inviting a member
  * @example Invite with a role looked up by name
  * ```typescript

package/src/Cloudflare/Acm/CustomTrustStore.ts

@@ -91,7 +91,9 @@ export type CustomTrustStore = Resource<
  * no ownership markers, so a cold `read` scans the zone for a certificate
  * with the same PEM body and reports it as `Unowned` — the engine refuses
  * to take it over unless `--adopt` (or `adopt(true)`) is set.
- *
+ * @resource
+ * @product ACM
+ * @category SSL/TLS & Certificates
  * @section Uploading a root CA
  * @example Trust a private root CA for origin pulls
  * ```typescript

package/src/Cloudflare/Acm/TotalTls.ts

@@ -98,7 +98,9 @@ export type TotalTls = Resource<
  *
  * Only one `TotalTls` resource per zone makes sense — two instances
  * managing the same zone would fight over the singleton.
- *
+ * @resource
+ * @product ACM
+ * @category SSL/TLS & Certificates
  * @section Managing Total TLS
  * @example Enable Total TLS on a zone
  * ```typescript

package/src/Cloudflare/Addressing/AddressMap.ts

@@ -109,7 +109,9 @@ export type AddressMap = Resource<
  * Requires the BYOIP add-on or Cloudflare-assigned static IPs on the
  * account; without the entitlement every mutating call fails with the typed
  * `FeatureNotEnabled` error (`address_maps_not_enabled_on_account`).
- *
+ * @resource
+ * @product Addressing
+ * @category Network
  * @section Creating an Address Map
  * @example Disabled map with a description
  * ```typescript

package/src/Cloudflare/Addressing/BgpPrefix.ts

@@ -92,7 +92,9 @@ export type AddressingBgpPrefix = Resource<
  * reconcile adopts an existing BGP prefix matching the CIDR before creating
  * a new one. There is **no delete API** — destroying this resource only
  * withdraws the advertisement (`advertised: false`) and drops the state.
- *
+ * @resource
+ * @product Addressing
+ * @category Network
  * @section Advertising a Prefix
  * @example Advertise the whole BYOIP prefix
  * ```typescript

package/src/Cloudflare/Addressing/Prefix.ts

@@ -88,7 +88,9 @@ export type AddressingPrefix = Resource<
  *
  * Only `description` is mutable; `cidr`, `asn`, and the LOA settings force
  * a replacement.
- *
+ * @resource
+ * @product Addressing
+ * @category Network
  * @section Creating a Prefix
  * @example Onboard a prefix with a pre-uploaded LOA
  * ```typescript

package/src/Cloudflare/Addressing/PrefixDelegation.ts

@@ -61,7 +61,9 @@ export type AddressingPrefixDelegation = Resource<
  *
  * Delegations are create/delete only — every prop change forces a
  * replacement.
- *
+ * @resource
+ * @product Addressing
+ * @category Network
  * @section Delegating a Prefix
  * @example Delegate a /26 to another account
  * ```typescript

package/src/Cloudflare/Addressing/ServiceBinding.ts

@@ -69,7 +69,9 @@ export type AddressingServiceBinding = Resource<
  * replacement. Provisioning to the edge is asynchronous: the binding is
  * returned immediately with `provisioning.state: "provisioning"` and flips
  * to `"active"` on Cloudflare's side; the resource does not wait for it.
- *
+ * @resource
+ * @product Addressing
+ * @category Network
  * @section Binding a Prefix to a Service
  * @example Bind a /24 to the CDN
  * ```typescript

package/src/Cloudflare/AiGateway/AiGateway.ts

@@ -242,7 +242,9 @@ export const isAiGateway = (value: unknown): value is AiGateway =>
  * `LanguageModel` Layer so you use the standard `generateText` / `streamText`
  * APIs — provider-agnostic, with caching, rate limiting, retries, and a
  * unified request log handled by the gateway.
- *
+ * @resource
+ * @product AI Gateway
+ * @category AI
  * @section Creating a Gateway
  * @example Basic gateway
  * ```typescript

package/src/Cloudflare/AiGateway/AiGatewayBinding.ts

@@ -90,6 +90,8 @@ export interface AiGatewayClient {
  * `Layer`.
  *
  * @binding
+ * @product AI Gateway
+ * @category AI
  *
  * @section Calling AI Gateway
  * @example Run through a gateway

package/src/Cloudflare/AiGateway/AiGatewaySpendingLimit.ts

@@ -132,7 +132,9 @@ export const isAiGatewaySpendingLimit = (
  * account (`/accounts/{account_id}/ai-gateway/billing/spending-limit`), so
  * declaring more than one `AiGatewaySpendingLimit` against the same account
  * will make them fight over the same remote object. Declare exactly one.
- *
+ * @resource
+ * @product AI Gateway
+ * @category AI
  * @section Setting a spend cap
  * @example Monthly cap
  * ```ts

package/src/Cloudflare/AiGateway/Dataset.ts

@@ -127,7 +127,9 @@ export type AiGatewayDataset = Resource<
  * provider, model, success, cost, tokens, etc.) and serve as the input to AI
  * Gateway evaluations. Name, enablement, and filters are all mutable in
  * place; only moving the dataset to a different gateway forces a replacement.
- *
+ * @resource
+ * @product AI Gateway
+ * @category AI
  * @section Creating a Dataset
  * @example Capture successful requests
  * ```typescript

package/src/Cloudflare/AiGateway/DynamicRouting.ts

@@ -244,7 +244,9 @@ export type AiGatewayDynamicRouting = Resource<
  * new version and deploys it; the reconciler also re-deploys when the live
  * deployed version drifts from the desired graph. Renames are applied in
  * place; only moving the route to a different gateway forces a replacement.
- *
+ * @resource
+ * @product AI Gateway
+ * @category AI
  * @section Creating a Route
  * @example Route all traffic to one model
  * ```typescript

package/src/Cloudflare/AiGateway/Evaluation.ts

@@ -99,7 +99,9 @@ export type AiGatewayEvaluation = Resource<
  * traffic captured by one or more datasets on a gateway. They are
  * create-only on Cloudflare's side: any prop change replaces the
  * evaluation with a fresh job.
- *
+ * @resource
+ * @product AI Gateway
+ * @category AI
  * @section Creating an Evaluation
  * @example Evaluate a dataset for speed and cost
  * ```typescript

package/src/Cloudflare/AiGateway/ProviderConfig.ts

@@ -132,7 +132,9 @@ export type AiGatewayProviderConfig = Resource<
  * Cloudflare imposes a strict naming contract: the gateway must reference a
  * Secrets Store via its `storeId`, and the secret must be scoped to
  * `ai_gateway` and named exactly `{gatewayId}_{providerSlug}_{alias}`.
- *
+ * @resource
+ * @product AI Gateway
+ * @category AI
  * @section Creating a Provider Config
  * @example Bring your own OpenAI key
  * ```typescript

package/src/Cloudflare/AiSearch/AiSearch.ts

@@ -0,0 +1,402 @@
+import * as Construct from "../../Construct.ts";
+import type { Input, InputProps } from "../../Input.ts";
+import { isResource } from "../../Resource.ts";
+import { AccountApiToken } from "../ApiToken/AccountApiToken.ts";
+import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
+import type { R2Bucket } from "../R2/R2Bucket.ts";
+import {
+  AiSearchInstance,
+  type AiSearchInstanceProps,
+  type AiSearchSourceParams,
+} from "./AiSearchInstance.ts";
+import type { AiSearchNamespace } from "./AiSearchNamespace.ts";
+import { AiSearchToken } from "./AiSearchToken.ts";
+
+type WebCrawlerParams = NonNullable<AiSearchSourceParams["webCrawler"]>;
+
+/**
+ * How a web crawler discovers and parses pages — Cloudflare's `parseType`
+ * folded together with its parse options. Defaults to `type: "sitemap"`.
+ */
+export type AiSearchParse = {
+  /**
+   * How pages are discovered:
+   * - `"sitemap"` (default) — read `<seed>/sitemap.xml` (found via
+   *   `robots.txt`) and index the URLs it lists.
+   * - `"crawl"` — start at `source` and follow links.
+   * - `"feed-rss"` — treat the seed as an RSS / Atom feed.
+   * @default "sitemap"
+   */
+  type?: NonNullable<WebCrawlerParams["parseType"]>;
+} & NonNullable<WebCrawlerParams["parseOptions"]>;
+
+/**
+ * Link-discovery options for a web crawler (mainly for `parse.type: "crawl"`):
+ * `depth`, `includeSubdomains`, `includeExternalLinks`, `maxAge`, and `source`
+ * (`"all"` | `"sitemaps"` | `"links"`).
+ */
+export type AiSearchCrawl = NonNullable<WebCrawlerParams["crawlOptions"]>;
+
+/**
+ * Where crawled content is stored. Cloudflare provisions managed storage by
+ * default; set this to store output in an R2 bucket you control.
+ */
+export type AiSearchStore = {
+  /** R2 bucket to store crawl output in. */
+  bucket: R2Bucket;
+  /** R2 data-residency jurisdiction for the store bucket. */
+  jurisdiction?: string;
+};
+
+/**
+ * Props common to every AI Search pipeline, regardless of data source. The
+ * underlying instance's `type`, `source`, and `sourceParams` are derived from
+ * the source-specific variant, so they're omitted here.
+ */
+export type AiSearchSharedProps = Omit<
+  InputProps<AiSearchInstanceProps, "type">,
+  "type" | "source" | "sourceParams" | "namespace"
+> & {
+  /**
+   * Namespace to group this pipeline under. Pass an {@link AiSearchNamespace}
+   * resource — the engine orders this pipeline after the namespace on deploy
+   * and tears it down before the namespace on destroy. Omit to place the
+   * pipeline in the account-provided `default` namespace. The namespace is
+   * immutable — changing it triggers a replacement.
+   * @default the account-provided `default` namespace
+   */
+  namespace?: AiSearchNamespace;
+};
+
+/**
+ * An R2-backed AI Search pipeline. Passing an {@link R2Bucket} as `source`
+ * selects R2 as the data source.
+ */
+export type AiSearchR2Props = AiSearchSharedProps & {
+  /**
+   * The R2 bucket to index. AI Search needs a service token to read it; the
+   * construct provisions one unless you pass your own `tokenId`.
+   */
+  source: R2Bucket;
+  /** Only index object keys under this prefix. */
+  prefix?: string;
+  /**
+   * Micromatch glob patterns; only objects matching at least one are
+   * indexed (`*` within a path segment, `**` across segments). Max 10.
+   */
+  include?: string[];
+  /**
+   * Micromatch glob patterns; objects matching any are skipped. Exclude
+   * takes precedence over `include`. Max 10.
+   */
+  exclude?: string[];
+  /** R2 data-residency jurisdiction of the source bucket. */
+  jurisdiction?: string;
+  parse?: never;
+  crawl?: never;
+  store?: never;
+};
+
+/**
+ * A web-crawler-backed AI Search pipeline. Passing a URL as `source` selects
+ * the web crawler as the data source (no service token needed).
+ */
+export type AiSearchWebCrawlerProps = AiSearchSharedProps & {
+  /** Seed URL to crawl and index. */
+  source: Input<string>;
+  /** How pages are discovered and parsed. */
+  parse?: AiSearchParse;
+  /** How links are followed from the seed. */
+  crawl?: AiSearchCrawl;
+  /** Where crawl output is stored (defaults to managed storage). */
+  store?: AiSearchStore;
+  prefix?: never;
+  include?: never;
+  exclude?: never;
+  jurisdiction?: never;
+};
+
+/**
+ * Props for the {@link AiSearch} construct — a union discriminated by what you
+ * pass as `source`: an {@link R2Bucket} for an R2 source, or a URL string for
+ * a web crawl.
+ */
+export type AiSearchProps = AiSearchR2Props | AiSearchWebCrawlerProps;
+
+/**
+ * The result of the {@link AiSearch} construct. It *is* the underlying
+ * {@link AiSearchInstance}, augmented with the managed `serviceToken`, so it
+ * can be passed anywhere an `AiSearchInstance` is expected —
+ * `AiSearchInstance.bind(search)`, a Worker's `env`, etc.
+ */
+export type AiSearch = AiSearchInstance & {
+  /**
+   * The managed AI Search service token minted for an R2 source, or
+   * `undefined` when the source is a web crawler (no token needed) or you
+   * supplied your own `tokenId`.
+   */
+  serviceToken: AiSearchToken | undefined;
+};
+
+/**
+ * A convenience construct over {@link AiSearchInstance} that auto-creates the
+ * sub-resources an AI Search instance typically needs, so a single call wires
+ * up a working pipeline. The data source is chosen by what you pass as
+ * `source` — an {@link R2Bucket} for R2, or a URL for a web crawl:
+ *
+ * - For an R2 source, it mints a least-privilege {@link AccountApiToken}
+ *   (`AI Search Index Engine`, stable child `ApiToken`) and an
+ *   {@link AiSearchToken} wrapping it (stable child `Token`), then passes
+ *   that token to the instance.
+ *   Cloudflare requires a service token to read an R2 bucket and only
+ *   provisions one through the dashboard / Wrangler — never on a
+ *   programmatic API create — so the construct provisions it for you. Pass
+ *   your own `tokenId` to skip minting and reuse an existing token.
+ * - It creates the {@link AiSearchInstance} (child `Instance`) with the
+ *   remaining props.
+ *
+ * Drop down to the low-level resources directly when you need to share a
+ * token across instances, adopt an existing one, or bind a namespace.
+ *
+ * The returned value *is* an {@link AiSearchInstance} (augmented with the
+ * managed `serviceToken`, `undefined` for a web crawler), so an `AiSearch`
+ * is usable anywhere an `AiSearchInstance` is expected — pass it straight to
+ * `AiSearchInstance.bind(search)` or a Worker's `env`.
+ *
+ * @resource
+ * @product AI Search
+ * @category AI
+ * @section Creating an AI Search pipeline
+ * @example R2-backed instance (token provisioned for you)
+ * Pass an {@link R2Bucket} as `source` — its presence selects R2.
+ * ```typescript
+ * const bucket = yield* Cloudflare.R2Bucket("docs");
+ * const search = yield* Cloudflare.AiSearch("docs-search", {
+ *   source: bucket,
+ * });
+ * ```
+ *
+ * @example Index only part of a bucket
+ * ```typescript
+ * const search = yield* Cloudflare.AiSearch("docs-search", {
+ *   source: bucket,
+ *   prefix: "docs/",
+ *   include: ["/docs/**"],
+ *   exclude: ["/docs/drafts/**"],
+ * });
+ * ```
+ *
+ * @example Reuse an existing service token
+ * ```typescript
+ * const search = yield* Cloudflare.AiSearch("docs-search", {
+ *   source: bucket,
+ *   tokenId: existingToken.id,
+ * });
+ * ```
+ *
+ * @example Web-crawler source
+ * Pass a URL as `source` to crawl and index a website (no service token
+ * needed). `parse.type` defaults to `"sitemap"`; use `"crawl"` to follow
+ * links from the seed instead.
+ * ```typescript
+ * const search = yield* Cloudflare.AiSearch("site-search", {
+ *   source: "https://example.com",
+ *   parse: { type: "crawl", contentSelector: [{ path: "/docs", selector: "main" }] },
+ *   crawl: { depth: 3, includeSubdomains: true },
+ * });
+ * ```
+ *
+ * @example Store crawl output in your own bucket
+ * ```typescript
+ * const store = yield* Cloudflare.R2Bucket("crawl-store");
+ * const search = yield* Cloudflare.AiSearch("site-search", {
+ *   source: "https://example.com",
+ *   parse: { type: "crawl" },
+ *   store: { bucket: store },
+ * });
+ * ```
+ *
+ * @section Binding to an Effect Worker
+ *
+ * The returned `search` is an {@link AiSearchInstance}. Bind it during the
+ * Worker's init phase with `Cloudflare.AiSearchInstance.bind(search)`, which
+ * attaches the single-instance `ai_search` binding and hands back an
+ * Effect-native client whose `search` / `chatCompletions` methods return
+ * `Effect`s. Provide `AiSearchInstanceBindingLive` in the Worker's runtime
+ * layer.
+ *
+ * @example Effect Worker that answers from AI Search
+ * ```typescript
+ * import * as Cloudflare from "alchemy/Cloudflare";
+ * import * as Effect from "effect/Effect";
+ * import { HttpServerRequest } from "effect/unstable/http/HttpServerRequest";
+ * import * as HttpServerResponse from "effect/unstable/http/HttpServerResponse";
+ *
+ * export default class Api extends Cloudflare.Worker<Api>()(
+ *   "api",
+ *   { main: import.meta.filename },
+ *   Effect.gen(function* () {
+ *     const bucket = yield* Cloudflare.R2Bucket("docs");
+ *     const aiSearch = yield* Cloudflare.AiSearch("docs-search", {
+ *       source: bucket,
+ *     });
+ *     const search = yield* Cloudflare.AiSearchInstance.bind(aiSearch);
+ *
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         const request = yield* HttpServerRequest;
+ *         const query = new URL(request.url).searchParams.get("q") ?? "";
+ *         const answer = yield* search.chatCompletions({
+ *           messages: [{ role: "user", content: query }],
+ *         });
+ *         return yield* HttpServerResponse.json(answer);
+ *       }),
+ *     };
+ *   }).pipe(Effect.provide(Cloudflare.AiSearchInstanceBindingLive)),
+ * ) {}
+ * ```
+ *
+ * @section Binding to an Async Worker
+ *
+ * For a vanilla `async fetch` Worker, pass the `search` under `Worker.env`.
+ * The engine attaches the same single-instance `ai_search` binding (see
+ * `toBinding` in `WorkerAsyncBindings.ts`), orders the deploy
+ * bucket → instance → worker, and `InferEnv` types `env.SEARCH` as the
+ * runtime `AiSearchInstance` handle — no hand-written types.
+ *
+ * @example Async Worker that answers from AI Search
+ * ```typescript
+ * // stack.ts
+ * const bucket = yield* Cloudflare.R2Bucket("docs");
+ * const search = yield* Cloudflare.AiSearch("docs-search", {
+ *   source: bucket,
+ * });
+ *
+ * export const Api = Cloudflare.Worker("api", {
+ *   main: "./worker.ts",
+ *   env: { SEARCH: search },
+ * });
+ * export type ApiEnv = Cloudflare.InferEnv<typeof Api>;
+ *
+ * // worker.ts
+ * import type { ApiEnv } from "./stack.ts";
+ * export default {
+ *   async fetch(request: Request, env: ApiEnv): Promise<Response> {
+ *     const query = new URL(request.url).searchParams.get("q") ?? "";
+ *     const answer = await env.SEARCH.chatCompletions({
+ *       messages: [{ role: "user", content: query }],
+ *     });
+ *     return Response.json(answer);
+ *   },
+ * };
+ * ```
+ *
+ * @see https://developers.cloudflare.com/ai-search/
+ */
+export const AiSearch = Construct.fn(function* (
+  id: string,
+  props: AiSearchProps,
+) {
+  const {
+    source,
+    prefix,
+    include,
+    exclude,
+    jurisdiction,
+    parse,
+    crawl,
+    store,
+    namespace,
+    ...shared
+  } = props;
+
+  let tokenId = shared.tokenId;
+  let serviceToken: AiSearchToken | undefined;
+  let type: "r2" | "web-crawler";
+  let instanceSource: Input<string>;
+  let sourceParams: Input<AiSearchSourceParams> | undefined;
+
+  // Discriminate the data source on what `source` is: an R2Bucket (a resource)
+  // indexes a bucket and needs a service token to read it; a URL crawls a seed
+  // and doesn't.
+  if (isResource(source)) {
+    const bucket = source as R2Bucket;
+    type = "r2";
+    instanceSource = bucket.bucketName;
+    sourceParams = clean({
+      prefix,
+      includeItems: include,
+      excludeItems: exclude,
+      r2Jurisdiction: jurisdiction,
+    }) as Input<AiSearchSourceParams> | undefined;
+
+    // Cloudflare requires a service token to read an R2 source and only
+    // auto-creates one via the dashboard/Wrangler — not on a programmatic
+    // API create. Mint one ourselves unless the caller passed a `tokenId`.
+    if (tokenId === undefined) {
+      const { accountId } = yield* yield* CloudflareEnvironment;
+      const apiToken = yield* AccountApiToken("ApiToken", {
+        policies: [
+          {
+            effect: "allow",
+            permissionGroups: ["AI Search Index Engine"],
+            resources: {
+              [`com.cloudflare.api.account.${accountId}`]: "*",
+            },
+          },
+        ],
+      });
+      serviceToken = yield* AiSearchToken("Token", {
+        cfApiId: apiToken.tokenId,
+        cfApiKey: apiToken.value,
+      });
+      tokenId = serviceToken.id;
+    }
+  } else {
+    type = "web-crawler";
+    instanceSource = source as Input<string>;
+
+    const { type: parseType, ...parseOptions } = parse ?? {};
+    const webCrawler = clean({
+      parseType,
+      parseOptions: clean(parseOptions),
+      crawlOptions: crawl ? clean(crawl) : undefined,
+      storeOptions: store
+        ? clean({
+            storageId: store.bucket.bucketName,
+            storageType: "r2" as const,
+            r2Jurisdiction: store.jurisdiction,
+          })
+        : undefined,
+    });
+    sourceParams = webCrawler
+      ? ({ webCrawler } as Input<AiSearchSourceParams>)
+      : undefined;
+  }
+
+  const instance = yield* AiSearchInstance("Instance", {
+    ...shared,
+    // The instance is keyed by namespace name; pass the namespace's `name`
+    // output so the engine orders instance-after-namespace.
+    namespace: namespace?.name,
+    type,
+    source: instanceSource,
+    tokenId,
+    sourceParams,
+  });
+
+  // Return the instance itself (augmented with the managed `serviceToken`)
+  // so an `AiSearch` is usable anywhere an `AiSearchInstance` is expected —
+  // `AiSearchInstance.bind(search)`, `env: { SEARCH: search }`, etc.
+  return Object.assign(instance, { serviceToken }) as AiSearch;
+});
+
+/** Drop `undefined` entries; return `undefined` when nothing is left. */
+const clean = <T extends Record<string, unknown>>(
+  obj: T,
+): { [K in keyof T]: T[K] } | undefined => {
+  const entries = Object.entries(obj).filter(([, v]) => v !== undefined);
+  return entries.length
+    ? (Object.fromEntries(entries) as { [K in keyof T]: T[K] })
+    : undefined;
+};