alchemy 2.0.0-beta.46 → 2.0.0-beta.48

package/src/Cloudflare/AiGateway/index.ts

@@ -1,2 +1,3 @@
 export * from "./AiGateway.ts";
 export * from "./AiGatewayBinding.ts";
+export * from "./LanguageModel.ts";

package/src/Cloudflare/ApiToken/AccountApiToken.ts

@@ -9,9 +9,11 @@ import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
 import type { Providers } from "../Providers.ts";
 import {
   buildConditionPayload,
+  collectPolicies,
   conditionFingerprint,
   policyFingerprint,
   resolvePolicies,
+  type ApiTokenBinding,
   type ApiTokenProps,
 } from "./Common.ts";
 
@@ -30,7 +32,7 @@ export type AccountApiToken = Resource<
     value: Redacted.Redacted<string>;
     accountId: string;
   },
-  never,
+  ApiTokenBinding,
   Providers
 >;
 
@@ -70,6 +72,44 @@ export type AccountApiToken = Resource<
  *   value: token.value,
  * });
  * ```
+ *
+ * @section Attaching Policies via Bindings
+ * @example Let a downstream capability contribute its own policies
+ * A token can be created with no `policies` of its own; the policies are
+ * supplied through its binding contract (see {@link ApiTokenBinding}). This is
+ * how capabilities like {@link CreateTunnel} provision a least-privilege token.
+ * ```typescript
+ * const token = yield* Cloudflare.AccountApiToken("scoped-token");
+ *
+ * yield* token.bind("MyCapability", {
+ *   policies: [
+ *     {
+ *       effect: "allow",
+ *       permissionGroups: ["Cloudflare Tunnel Write"],
+ *       resources: { [`com.cloudflare.api.account.${accountId}`]: "*" },
+ *     },
+ *   ],
+ * });
+ * ```
+ *
+ * @section Exposing a Token to a Worker
+ * @example Read the token value at runtime
+ * Bind the token's outputs in the Worker's Init phase to get runtime
+ * accessors. Binding `token.value` injects it as a `secret_text` Worker
+ * binding; the returned accessor reads it back (as `Redacted`) at runtime.
+ * ```typescript
+ * // init
+ * const value = yield* token.value; // Accessor<Redacted<string>>
+ * const accountId = yield* token.accountId; // Accessor<string>
+ *
+ * return {
+ *   fetch: Effect.gen(function* () {
+ *     const apiToken = yield* value; // Redacted<string>
+ *     // ... call the Cloudflare API with `apiToken`
+ *     return HttpServerResponse.text("ok");
+ *   }),
+ * };
+ * ```
  */
 export const AccountApiToken = Resource<AccountApiToken>(
   "Cloudflare.AccountApiToken",
@@ -96,21 +136,25 @@ export const AccountApiTokenProvider = () =>
         tokenData: {
           id?: string | null;
           name?: string | null;
-          status?: "active" | "disabled" | "expired" | null;
+          // Distilled widened generated string enums to open unions (`string & {}`).
+          status?: string | null;
         },
         value: Redacted.Redacted<string>,
         accountId: string,
       ): AccountApiTokenAttributes => ({
         tokenId: tokenData.id ?? "",
         name: tokenData.name ?? "",
-        status: tokenData.status ?? "active",
+        status: (tokenData.status ?? "active") as
+          | "active"
+          | "disabled"
+          | "expired",
         value,
         accountId,
       });
 
       return {
         stables: ["tokenId", "accountId"],
-        diff: Effect.fn(function* ({ id, olds, news, output }) {
+        diff: Effect.fn(function* ({ id, olds, news = {}, output }) {
           if (!isResolved(news)) return undefined;
           const newAccountId = news.accountId ?? defaultAccountId;
           const oldAccountId =
@@ -123,7 +167,9 @@ export const AccountApiTokenProvider = () =>
           const oldPolicyFp = policyFingerprint(
             resolvePolicies(olds?.policies ?? []),
           );
-          const newPolicyFp = policyFingerprint(resolvePolicies(news.policies));
+          const newPolicyFp = policyFingerprint(
+            resolvePolicies(news.policies ?? []),
+          );
           const oldCondFp = conditionFingerprint(olds?.condition);
           const newCondFp = conditionFingerprint(news.condition);
           if (
@@ -136,10 +182,17 @@ export const AccountApiTokenProvider = () =>
             return { action: "update" } as const;
           }
         }),
-        reconcile: Effect.fn(function* ({ id, news, output }) {
+        reconcile: Effect.fn(function* ({ id, news = {}, output, bindings }) {
           const accountId = news.accountId ?? defaultAccountId;
           const name = yield* resolveName(id, news.name);
-          const policies = resolvePolicies(news.policies);
+          const collected = collectPolicies(news.policies, bindings);
+          if (collected.length === 0) {
+            return yield* Effect.die(
+              `Cloudflare requires at least one policy on token "${name}". ` +
+                "Pass `policies` or attach them via a binding.",
+            );
+          }
+          const policies = resolvePolicies(collected);
 
           // Observe — fetch current state if we already know the token id.
           // Cloudflare reports a deleted token as `InvalidRoute` or

package/src/Cloudflare/ApiToken/Common.ts

@@ -52,10 +52,11 @@ export type ApiTokenProps = {
    */
   accountId?: string;
   /**
-   * Access policies attached to the token. At least one policy is required
-   * by Cloudflare.
+   * Access policies attached to the token. Cloudflare requires at least one
+   * policy on a token; if you omit `policies` here, the policies must instead
+   * be contributed by bindings (see {@link ApiTokenBinding}).
    */
-  policies: ApiTokenPolicy[];
+  policies?: ApiTokenPolicy[];
   /** ISO 8601 expiration timestamp. */
   expiresOn?: string;
   /** ISO 8601 "not before" timestamp. */
@@ -64,6 +65,34 @@ export type ApiTokenProps = {
   condition?: ApiTokenCondition;
 };
 
+/**
+ * Binding contract for {@link AccountApiToken} / {@link UserApiToken}.
+ *
+ * A binding contributes additional access policies to the token. This lets a
+ * downstream resource (e.g. a runtime capability that needs to call a specific
+ * Cloudflare API) create a token and attach exactly the policies it requires,
+ * without the token's owner having to enumerate them up front.
+ *
+ * Binding-contributed policies are merged with any `policies` passed directly
+ * as props; the union must contain at least one policy.
+ */
+export type ApiTokenBinding = {
+  /** Access policies to attach to the token. */
+  policies?: ApiTokenPolicy[];
+};
+
+/**
+ * Collect the policies a token should be created with: those passed directly
+ * as props, plus those contributed by bindings.
+ */
+export const collectPolicies = (
+  props: ApiTokenPolicy[] | undefined,
+  bindings: { data: ApiTokenBinding }[],
+): ApiTokenPolicy[] => [
+  ...(props ?? []),
+  ...bindings.flatMap((binding) => binding.data.policies ?? []),
+];
+
 export type ResolvedPolicy = {
   effect: "allow" | "deny";
   permissionGroups: { id: string; meta?: { key?: string; value?: string } }[];

package/src/Cloudflare/ApiToken/UserApiToken.ts

@@ -8,9 +8,11 @@ import { Resource } from "../../Resource.ts";
 import type { Providers } from "../Providers.ts";
 import {
   buildConditionPayload,
+  collectPolicies,
   conditionFingerprint,
   policyFingerprint,
   resolvePolicies,
+  type ApiTokenBinding,
   type ApiTokenProps,
 } from "./Common.ts";
 
@@ -27,7 +29,7 @@ export type UserApiToken = Resource<
      */
     value: Redacted.Redacted<string>;
   },
-  never,
+  ApiTokenBinding,
   Providers
 >;
 
@@ -60,6 +62,42 @@ export type UserApiToken = Resource<
  *   ],
  * });
  * ```
+ *
+ * @section Attaching Policies via Bindings
+ * @example Let a downstream capability contribute its own policies
+ * A token can be created with no `policies` of its own; the policies are
+ * supplied through its binding contract (see {@link ApiTokenBinding}).
+ * ```typescript
+ * const token = yield* Cloudflare.UserApiToken("scoped-token");
+ *
+ * yield* token.bind("MyCapability", {
+ *   policies: [
+ *     {
+ *       effect: "allow",
+ *       permissionGroups: ["Workers Scripts Read"],
+ *       resources: { [`com.cloudflare.api.account.${accountId}`]: "*" },
+ *     },
+ *   ],
+ * });
+ * ```
+ *
+ * @section Exposing a Token to a Worker
+ * @example Read the token value at runtime
+ * Bind the token's value output in the Worker's Init phase to get a runtime
+ * accessor. Binding it injects a `secret_text` Worker binding; the returned
+ * accessor reads it back (as `Redacted`) at runtime.
+ * ```typescript
+ * // init
+ * const value = yield* token.value; // Accessor<Redacted<string>>
+ *
+ * return {
+ *   fetch: Effect.gen(function* () {
+ *     const apiToken = yield* value; // Redacted<string>
+ *     // ... call the Cloudflare API with `apiToken`
+ *     return HttpServerResponse.text("ok");
+ *   }),
+ * };
+ * ```
  */
 export const UserApiToken = Resource<UserApiToken>("Cloudflare.UserApiToken");
 
@@ -83,26 +121,32 @@ export const UserApiTokenProvider = () =>
         tokenData: {
           id?: string | null;
           name?: string | null;
-          status?: "active" | "disabled" | "expired" | null;
+          // Distilled widened generated string enums to open unions (`string & {}`).
+          status?: string | null;
         },
         value: Redacted.Redacted<string>,
       ): UserApiTokenAttributes => ({
         tokenId: tokenData.id ?? "",
         name: tokenData.name ?? "",
-        status: tokenData.status ?? "active",
+        status: (tokenData.status ?? "active") as
+          | "active"
+          | "disabled"
+          | "expired",
         value,
       });
 
       return {
         stables: ["tokenId"],
-        diff: Effect.fn(function* ({ id, olds, news, output }) {
+        diff: Effect.fn(function* ({ id, olds, news = {}, output }) {
           if (!isResolved(news)) return undefined;
           const oldName = output?.name ?? (yield* resolveName(id, olds?.name));
           const newName = yield* resolveName(id, news.name);
           const oldPolicyFp = policyFingerprint(
             resolvePolicies(olds?.policies ?? []),
           );
-          const newPolicyFp = policyFingerprint(resolvePolicies(news.policies));
+          const newPolicyFp = policyFingerprint(
+            resolvePolicies(news.policies ?? []),
+          );
           const oldCondFp = conditionFingerprint(olds?.condition);
           const newCondFp = conditionFingerprint(news.condition);
           if (
@@ -115,9 +159,16 @@ export const UserApiTokenProvider = () =>
             return { action: "update" } as const;
           }
         }),
-        reconcile: Effect.fn(function* ({ id, news, output }) {
+        reconcile: Effect.fn(function* ({ id, news = {}, output, bindings }) {
           const name = yield* resolveName(id, news.name);
-          const policies = resolvePolicies(news.policies);
+          const collected = collectPolicies(news.policies, bindings);
+          if (collected.length === 0) {
+            return yield* Effect.die(
+              `Cloudflare requires at least one policy on token "${name}". ` +
+                "Pass `policies` or attach them via a binding.",
+            );
+          }
+          const policies = resolvePolicies(collected);
 
           // Observe — fetch current state if we know the token id;
           // Cloudflare reports a deleted token as `TokenNotFound`, which

package/src/Cloudflare/Browser/Browser.ts

@@ -0,0 +1,140 @@
+import type * as Effect from "effect/Effect";
+import { SingleShotGen } from "effect/Utils";
+import { BrowserBinding, type BrowserClient } from "./BrowserBinding.ts";
+
+type BrowserTypeId = typeof BrowserTypeId;
+const BrowserTypeId = "Cloudflare.Browser" as const;
+
+export type BrowserProps = {
+  /**
+   * Binding name used when `Browser` is bound from inside a Worker init phase
+   * (`yield* Cloudflare.Browser(...)`). When passed through
+   * `Worker({ env: { ... } })`, the object key remains the binding name.
+   *
+   * @default "BROWSER"
+   */
+  name?: string;
+};
+
+/**
+ * The Effect yielded when a `Browser` marker is used inside a Worker init
+ * phase: it attaches the `browser` binding to the surrounding Worker and
+ * resolves to the runtime {@link BrowserClient}.
+ */
+type BindEffect = Effect.Effect<BrowserClient, never, BrowserBinding>;
+
+/**
+ * Marker for a Cloudflare Browser Rendering binding.
+ *
+ * It is a plain data structure (so it can be declared directly on a Worker's
+ * `env`) that is **also** yieldable inside an Effect-native Worker. Yielding it
+ * (`yield* Cloudflare.Browser(...)`) attaches the binding to the surrounding
+ * Worker and returns the runtime {@link BrowserClient} — no separate
+ * `.bind(...)` step required.
+ *
+ * The divergence is achieved via `[Symbol.iterator]`: the object is not an
+ * `Effect` (so `InferEnv` resolves it to the native `Fetcher` in the `env`
+ * position), but it is iterable as one when `yield*`-ed.
+ */
+export interface Browser {
+  kind: BrowserTypeId;
+  name: string;
+  asEffect(): BindEffect;
+  [Symbol.iterator](): SingleShotGen<BindEffect, BrowserClient>;
+}
+
+export const isBrowser = (value: unknown): value is Browser =>
+  typeof value === "object" && (value as Browser)?.kind === BrowserTypeId;
+
+/**
+ * A Cloudflare Browser Rendering binding for launching headless browser
+ * sessions from Workers via `@cloudflare/puppeteer`.
+ *
+ * @binding
+ *
+ * @section Effect-style Worker (recommended)
+ * @example Render a page title with managed browser cleanup
+ * ```typescript
+ * import puppeteer from "@cloudflare/puppeteer";
+ * import * as Effect from "effect/Effect";
+ *
+ * Cloudflare.Worker(
+ *   "BrowserWorker",
+ *   { main: import.meta.filename },
+ *   Effect.gen(function* () {
+ *     // Attaches the binding to this Worker AND returns the runtime client.
+ *     const browser = yield* Cloudflare.Browser({ name: "BROWSER" });
+ *
+ *     return {
+ *       fetch: browser.withBrowser(puppeteer, (browser) =>
+ *         Effect.gen(function* () {
+ *           const page = yield* Effect.tryPromise(() => browser.newPage());
+ *           yield* Effect.tryPromise(() => page.goto("https://example.com"));
+ *           const title = yield* Effect.tryPromise(() => page.title());
+ *           return Response.json({ title });
+ *         }),
+ *       ),
+ *     };
+ *   }).pipe(Effect.provide(Cloudflare.BrowserBindingLive)),
+ * );
+ * ```
+ *
+ * @section Worker binding metadata
+ * @example
+ * ```typescript
+ * export const Worker = Cloudflare.Worker("Worker", {
+ *   main: "./src/worker.ts",
+ *   env: {
+ *     BROWSER: Cloudflare.Browser(),
+ *   },
+ * });
+ *
+ * export type WorkerEnv = Cloudflare.InferEnv<typeof Worker>;
+ * //   { BROWSER: Fetcher }
+ * ```
+ *
+ * @example Async-style worker with the raw runtime binding
+ * ```typescript
+ * import puppeteer from "@cloudflare/puppeteer";
+ * import type { WorkerEnv } from "../alchemy.run.ts";
+ *
+ * export default {
+ *   async fetch(request: Request, env: WorkerEnv) {
+ *     const browser = await puppeteer.launch(env.BROWSER);
+ *     const page = await browser.newPage();
+ *     await page.goto("https://example.com");
+ *     const screenshot = await page.screenshot();
+ *     await browser.close();
+ *
+ *     return new Response(screenshot, {
+ *       headers: { "content-type": "image/png" },
+ *     });
+ *   },
+ * };
+ * ```
+ *
+ * @see https://developers.cloudflare.com/browser-rendering/workers-binding-api/
+ */
+export const Browser: {
+  (props?: BrowserProps): Browser;
+  /**
+   * Bind an existing `Browser` marker to the surrounding Worker, returning the
+   * runtime client. Equivalent to `yield* browser` — prefer yielding the marker
+   * directly.
+   */
+  bind: typeof BrowserBinding.bind;
+} = Object.assign(
+  (props?: BrowserProps): Browser => {
+    const self: Browser = {
+      kind: BrowserTypeId,
+      name: props?.name ?? "BROWSER",
+      asEffect: () => BrowserBinding.bind(self),
+      [Symbol.iterator]: () => new SingleShotGen(BrowserBinding.bind(self)),
+    };
+    return self;
+  },
+  {
+    bind: (...args: Parameters<typeof BrowserBinding.bind>) =>
+      BrowserBinding.bind(...args),
+  },
+);

package/src/Cloudflare/Browser/BrowserBinding.ts

@@ -0,0 +1,128 @@
+import type * as cf from "@cloudflare/workers-types";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Binding from "../../Binding.ts";
+import type { ResourceLike } from "../../Resource.ts";
+import { isWorker, WorkerEnvironment } from "../Workers/Worker.ts";
+import type { Browser as BrowserLike } from "./Browser.ts";
+
+export class BrowserError extends Data.TaggedError("BrowserError")<{
+  message: string;
+  cause: unknown;
+}> {}
+
+export interface BrowserHandle {
+  close(): Promise<void>;
+}
+
+export interface BrowserPuppeteer<Browser extends BrowserHandle> {
+  launch(binding: cf.Fetcher): Promise<Browser>;
+}
+
+/**
+ * Effect-native client for a Cloudflare Browser Rendering binding.
+ *
+ * Browser Rendering's Workers binding is consumed by `@cloudflare/puppeteer`.
+ * Alchemy keeps Puppeteer as a caller-provided dependency while wrapping
+ * launch and cleanup in Effects.
+ */
+export interface BrowserClient {
+  /**
+   * Effect resolving to the raw Cloudflare Browser Rendering runtime binding.
+   */
+  raw: Effect.Effect<cf.Fetcher, never, WorkerEnvironment>;
+  /**
+   * Launch a Browser Rendering session through `@cloudflare/puppeteer`.
+   */
+  launch<Browser extends BrowserHandle>(
+    puppeteer: BrowserPuppeteer<Browser>,
+  ): Effect.Effect<Browser, BrowserError, WorkerEnvironment>;
+  /**
+   * Launch a browser, run an Effect with it, and close it afterward.
+   */
+  withBrowser<Browser extends BrowserHandle, A, E, R>(
+    puppeteer: BrowserPuppeteer<Browser>,
+    use: (browser: Browser) => Effect.Effect<A, E, R>,
+  ): Effect.Effect<A, BrowserError | E, WorkerEnvironment | R>;
+}
+
+export class BrowserBinding extends Binding.Service<
+  BrowserBinding,
+  (browser: BrowserLike) => Effect.Effect<BrowserClient>
+>()("Cloudflare.Browser.Binding") {}
+
+export const BrowserBindingLive = Layer.effect(
+  BrowserBinding,
+  Effect.gen(function* () {
+    const Policy = yield* BrowserBindingPolicy;
+
+    return Effect.fn(function* (browser: BrowserLike) {
+      yield* Policy(browser);
+      // Cloudflare exposes Browser Rendering as a service-style binding for
+      // @cloudflare/puppeteer; workers-types has no narrower interface.
+      const raw = WorkerEnvironment.useSync(
+        (env) => (env as Record<string, cf.Fetcher>)[browser.name]!,
+      );
+      return makeBrowserClient(raw);
+    });
+  }),
+);
+
+export class BrowserBindingPolicy extends Binding.Policy<
+  BrowserBindingPolicy,
+  (browser: BrowserLike) => Effect.Effect<void>
+>()("Cloudflare.Browser.Binding") {}
+
+export const BrowserBindingPolicyLive = BrowserBindingPolicy.layer.succeed(
+  Effect.fn(function* (host: ResourceLike, browser: BrowserLike) {
+    if (isWorker(host)) {
+      yield* host.bind(browser.name, {
+        bindings: [
+          {
+            type: "browser",
+            name: browser.name,
+          },
+        ],
+      });
+    } else {
+      return yield* Effect.die(
+        new Error(`BrowserBinding does not support runtime '${host.Type}'`),
+      );
+    }
+  }),
+);
+
+const tryPromise = <T>(fn: () => Promise<T>): Effect.Effect<T, BrowserError> =>
+  Effect.tryPromise({
+    try: fn,
+    catch: (error) =>
+      new BrowserError({
+        message:
+          error instanceof Error
+            ? error.message
+            : "Unknown Browser Rendering error",
+        cause: error,
+      }),
+  });
+
+/** @internal */
+export const makeBrowserClient = (
+  raw: Effect.Effect<cf.Fetcher, never, WorkerEnvironment>,
+): BrowserClient => {
+  const launch = <Browser extends BrowserHandle>(
+    puppeteer: BrowserPuppeteer<Browser>,
+  ) =>
+    raw.pipe(
+      Effect.flatMap((binding) => tryPromise(() => puppeteer.launch(binding))),
+    );
+
+  return {
+    raw,
+    launch,
+    withBrowser: (puppeteer, use) =>
+      Effect.acquireUseRelease(launch(puppeteer), use, (browser) =>
+        tryPromise(() => browser.close()),
+      ),
+  } satisfies BrowserClient;
+};

package/src/Cloudflare/Browser/index.ts

@@ -0,0 +1,11 @@
+export * from "./Browser.ts";
+export {
+  BrowserBinding,
+  BrowserBindingLive,
+  BrowserBindingPolicy,
+  BrowserBindingPolicyLive,
+  BrowserError,
+  type BrowserClient,
+  type BrowserHandle,
+  type BrowserPuppeteer,
+} from "./BrowserBinding.ts";

package/src/Cloudflare/D1/D1Database.ts

@@ -332,7 +332,10 @@ export const DatabaseProvider = () =>
                 databaseId: db.uuid ?? output.databaseId,
                 databaseName: db.name ?? output.databaseName,
                 jurisdiction: output.jurisdiction,
-                readReplication: db.readReplication ?? undefined,
+                // Distilled widened generated string enums to open unions.
+                readReplication: (db.readReplication ?? undefined) as
+                  | { mode: "auto" | "disabled" }
+                  | undefined,
                 accountId: output.accountId,
                 migrationsDir: output.migrationsDir,
                 migrationsTable: output.migrationsTable,
@@ -375,7 +378,8 @@ export const DatabaseProvider = () =>
             | {
                 uuid?: string | null;
                 name?: string | null;
-                readReplication?: { mode: "auto" | "disabled" } | null;
+                // Distilled widened generated string enums to open unions.
+                readReplication?: { mode: string } | null;
               }
             | undefined;
           if (output?.databaseId) {

package/src/Cloudflare/Email/EmailRouting.ts

@@ -5,7 +5,7 @@ import * as Provider from "../../Provider.ts";
 import { Resource } from "../../Resource.ts";
 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
 import type { Providers } from "../Providers.ts";
-import { resolveZoneId, type ZoneReference } from "../Zone.ts";
+import { resolveZoneId, type ZoneReference } from "../Zone/index.ts";
 
 export type EmailRoutingStatus =
   | "ready"

package/src/Cloudflare/Email/EmailRule.ts

@@ -5,7 +5,7 @@ import * as Provider from "../../Provider.ts";
 import { Resource } from "../../Resource.ts";
 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
 import type { Providers } from "../Providers.ts";
-import { resolveZoneId, type ZoneReference } from "../Zone.ts";
+import { resolveZoneId, type ZoneReference } from "../Zone/index.ts";
 
 export type EmailMatcher =
   | { type: "all" }
@@ -88,16 +88,16 @@ const normalize = (
     name?: string | null;
     enabled?: boolean | null;
     priority?: number | null;
+    // Distilled widened generated string enums to open unions (`string & {}`);
+    // the runtime values are still the known variants, narrowed below.
     matchers?:
       | {
-          type: "all" | "literal";
-          field?: "to" | null;
+          type: string;
+          field?: string | null;
           value?: string | null;
         }[]
       | null;
-    actions?:
-      | { type: "drop" | "forward" | "worker"; value?: string[] | null }[]
-      | null;
+    actions?: { type: string; value?: string[] | null }[] | null;
   },
   zoneId: string,
 ) => ({