alchemy 2.0.0-beta.47 → 2.0.0-beta.49

package/src/Cloudflare/ApiToken/Common.ts

@@ -27,10 +27,20 @@ export type ApiTokenPermissionGroupRef =
   | PermissionGroupName
   | { id: string; meta?: { key?: string; value?: string } };
 
+/**
+ * Value of a resource entry in an {@link ApiTokenPolicy}. Usually `"*"`, but
+ * account-owned tokens must nest zone resources under the account resource —
+ * e.g. `{ "com.cloudflare.api.account.<id>": { "com.cloudflare.api.account.zone.*": "*" } }`
+ * — so a nested object is also allowed.
+ */
+export type ApiTokenResourceScope =
+  | string
+  | { [K in ApiTokenResourceKey]?: string };
+
 export interface ApiTokenPolicy {
   effect: "allow" | "deny";
   permissionGroups: ApiTokenPermissionGroupRef[];
-  resources: { [K in ApiTokenResourceKey]?: string };
+  resources: { [K in ApiTokenResourceKey]?: ApiTokenResourceScope };
 }
 
 export interface ApiTokenCondition {
@@ -52,10 +62,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 +75,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 } }[];
@@ -87,8 +126,8 @@ export const resolvePermissionGroup = (ref: ApiTokenPermissionGroupRef) => {
 
 const resolveResources = (
   resources: ApiTokenPolicy["resources"],
-): Record<string, string> => {
-  const out: Record<string, string> = {};
+): Record<string, ApiTokenResourceScope> => {
+  const out: Record<string, ApiTokenResourceScope> = {};
   for (const [key, value] of Object.entries(resources)) {
     if (value === undefined) continue;
     out[key] = value;

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/Dns/DnsBinding.ts

@@ -0,0 +1,123 @@
+import {
+  Credentials,
+  fromApiToken,
+} from "@distilled.cloud/cloudflare/Credentials";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Redacted from "effect/Redacted";
+import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
+import { type HttpClient } from "effect/unstable/http/HttpClient";
+import type * as Binding from "../../Binding.ts";
+import * as Output from "../../Output.ts";
+import { RuntimeContext } from "../../RuntimeContext.ts";
+import { AccountApiToken } from "../ApiToken/AccountApiToken.ts";
+import type { ApiTokenPermissionGroupRef } from "../ApiToken/Common.ts";
+import type { Zone } from "../Zone/Zone.ts";
+
+/**
+ * Runtime accessor for a DNS binding's token, obtained by binding the
+ * {@link AccountApiToken}'s `value` output in the Worker's Init phase. Reads the
+ * value back from the Worker's environment at runtime. DNS record operations
+ * are zone-scoped (the `zoneId` is passed per call), so the account id is not
+ * needed at runtime.
+ */
+export interface DnsToken {
+  /** The token's plaintext value (injected as a `secret_text` binding). */
+  value: Effect.Effect<Redacted.Redacted<string>>;
+}
+
+/**
+ * Bind an {@link AccountApiToken}'s `value` output into the Worker (as a
+ * `secret_text` binding) and return the {@link DnsToken} accessor.
+ */
+export const bindDnsToken = (token: AccountApiToken) =>
+  Effect.gen(function* () {
+    const value = yield* token.value;
+    return { value } satisfies DnsToken;
+  });
+
+/**
+ * Resolve credentials from a bound token and provide them (plus the
+ * fetch-based HTTP client) to a raw SDK operation.
+ */
+export const authorizeDns =
+  (token: DnsToken) =>
+  <A, E>(
+    eff: Effect.Effect<A, E, Credentials | HttpClient>,
+  ): Effect.Effect<A, E, RuntimeContext> =>
+    token.value.pipe(
+      Effect.flatMap((value) =>
+        eff.pipe(
+          Effect.provide(
+            fromApiToken({ apiToken: Redacted.value(value) }).pipe(
+              Layer.provideMerge(FetchHttpClient.layer),
+            ),
+          ),
+        ),
+      ),
+    );
+
+/**
+ * Shared runtime body for a DNS binding: create a token scoped to the requested
+ * zone, attach the (narrow) policy, bind the token's value and the zone's id
+ * into the Worker, then build the client. Pass the result to
+ * `Layer.effect(<Binding>, ...)`.
+ *
+ * The zone's `zoneId` is bound into the Worker at init time, so the resulting
+ * client closes over it and callers never pass it per request — the
+ * provisioned token only grants access to that one zone anyway.
+ */
+export const makeDnsClient = <C>(
+  Policy: Binding.Policy<
+    any,
+    any,
+    (token: AccountApiToken, zone: Zone) => Effect.Effect<void>
+  >,
+  tokenId: string,
+  makeClient: (token: DnsToken, zoneId: Effect.Effect<string>) => C,
+) =>
+  Effect.gen(function* () {
+    const Token = yield* AccountApiToken;
+    const attach = yield* Policy;
+
+    return Effect.fn(function* (zone: Zone) {
+      const token = yield* Token(tokenId);
+      yield* attach(token, zone);
+      const zoneId = yield* zone.zoneId;
+      return makeClient(yield* bindDnsToken(token), zoneId);
+    });
+  });
+
+/**
+ * Build the deploy-time policy layer for a DNS binding: attach an allow policy
+ * with the given permission groups, scoped to the requested zone
+ * (`com.cloudflare.api.account.zone.<zoneId>`).
+ */
+export const makeDnsPolicyLive = <Self, Id extends string>(
+  Policy: Binding.Policy<
+    Self,
+    Id,
+    (token: AccountApiToken, zone: Zone) => Effect.Effect<void>
+  >,
+  sid: string,
+  permissionGroups: ApiTokenPermissionGroupRef[],
+) =>
+  Policy.layer.succeed((_host, token, zone) =>
+    token.bind`${sid}(${zone})`({
+      policies: [
+        {
+          effect: "allow",
+          permissionGroups,
+          resources: zone.zoneId.pipe(
+            Output.flatMap(
+              (zoneId) =>
+                Output.interpolate`com.cloudflare.api.account.zone.${zoneId}`,
+            ),
+            Output.map((zoneId) => ({
+              [zoneId]: "*",
+            })),
+          ),
+        },
+      ],
+    }),
+  );