alchemy 2.0.0-beta.56 → 2.0.0-beta.58

package/src/Cloudflare/Firewall/UaRule.ts

@@ -95,7 +95,9 @@ export type UaRule = Resource<
  * state, `read` scans the zone for an existing rule with the same
  * User-Agent string and reports it as `Unowned`, so the engine refuses to
  * take it over unless `--adopt` (or `adopt(true)`) is set.
- *
+ * @resource
+ * @product Firewall
+ * @category Application Security
  * @section Blocking a User-Agent
  * @example Block a scraper outright
  * ```typescript

package/src/Cloudflare/Flagship/App.ts

@@ -65,7 +65,9 @@ export type FlagshipApp = Resource<
  * apps that map to your projects or services; the app's `appId` is what a
  * Worker's `Flagship` binding points at and what every evaluation call is
  * scoped to. The name is mutable in place; the app id never changes.
- *
+ * @resource
+ * @product Flagship
+ * @category Developer Platform
  * @section Creating an App
  * @example App with a generated name
  * ```typescript

package/src/Cloudflare/Flagship/Flag.ts

@@ -213,7 +213,9 @@ export type FlagshipFlag = Resource<
  * endpoint); changing variations, rules, enablement, or the default
  * variation takes effect without redeploying code. Everything except the
  * flag key and the parent app is mutable in place.
- *
+ * @resource
+ * @product Flagship
+ * @category Developer Platform
  * @section Creating a Flag
  * @example Boolean flag
  * ```typescript

package/src/Cloudflare/Flagship/FlagshipBinding.ts

@@ -9,6 +9,7 @@ import type { ResourceLike } from "../../Resource.ts";
 import type { RuntimeContext } from "../../RuntimeContext.ts";
 import { isWorker, WorkerEnvironment } from "../Workers/Worker.ts";
 import type { FlagshipApp } from "./App.ts";
+import type { Providers } from "../Providers.ts";
 
 export class FlagshipError extends Data.TaggedError("FlagshipError")<{
   message: string;
@@ -125,6 +126,9 @@ export interface FlagshipClient {
  * Binding service that turns a {@link FlagshipApp} resource into a typed
  * {@link FlagshipClient} for Worker runtime code. Prefer the
  * `Cloudflare.FlagshipApp.bind(app)` alias.
+ * @binding
+ * @product Flagship
+ * @category Developer Platform
  */
 export class FlagshipBinding extends Binding.Service<
   FlagshipBinding,
@@ -148,7 +152,8 @@ export const FlagshipBindingLive = Layer.effect(
 
 export class FlagshipBindingPolicy extends Binding.Policy<
   FlagshipBindingPolicy,
-  (app: FlagshipApp) => Effect.Effect<void>
+  (app: FlagshipApp) => Effect.Effect<void>,
+  Providers
 >()("Cloudflare.Flagship.Binding") {}
 
 export const FlagshipBindingPolicyLive = FlagshipBindingPolicy.layer.succeed(

package/src/Cloudflare/Fraud/FraudDetectionSettings.ts

@@ -119,7 +119,9 @@ export type FraudDetectionSettings = Resource<
  * Fields that were never set by this resource are not touched.
  * `authenticationSettings` that did not exist before the first write
  * cannot be cleared and are left as-is.
- *
+ * @resource
+ * @product Fraud Detection
+ * @category Application Security
  * @section Fraud User Profiles
  * @example Enable user profiles with a username expression
  * ```typescript

package/src/Cloudflare/Gateway/Certificate.ts

@@ -90,7 +90,9 @@ export type GatewayCertificate = Resource<
  * To make Gateway actually intercept with this certificate, reference its
  * `certificateId` from the Gateway configuration's `certificate` setting
  * (see `Cloudflare.GatewayConfiguration`).
- *
+ * @resource
+ * @product Gateway
+ * @category Cloudflare One (Zero Trust)
  * @section Creating a Certificate
  * @example Activated certificate (default)
  * ```typescript

package/src/Cloudflare/Gateway/Configuration.ts

@@ -147,7 +147,9 @@ export type GatewayConfiguration = Resource<
  * before Alchemy managed them cannot be restored (Cloudflare's API has no
  * way to unset a block) — destroy leaves the last managed value and logs
  * a warning.
- *
+ * @resource
+ * @product Gateway
+ * @category Cloudflare One (Zero Trust)
  * @section Managing Gateway settings
  * @example Enable activity logging and TLS decryption
  * ```typescript

package/src/Cloudflare/Gateway/List.ts

@@ -113,7 +113,9 @@ export type GatewayList = Resource<
  * description, and items all converge in place. Items are managed as a
  * full set — the provider PUTs the complete desired item set and removes
  * anything not declared.
- *
+ * @resource
+ * @product Gateway
+ * @category Cloudflare One (Zero Trust)
  * @section Creating a List
  * @example Domain list
  * ```typescript

package/src/Cloudflare/Gateway/Location.ts

@@ -129,7 +129,9 @@ export type GatewayLocation = Resource<
  * `https://<dohSubdomain>.cloudflare-gateway.com/dns-query` and Gateway
  * DNS policies apply to its traffic. All declared properties converge in
  * place — nothing on a location forces a replacement.
- *
+ * @resource
+ * @product Gateway
+ * @category Cloudflare One (Zero Trust)
  * @section Creating a Location
  * @example DoH-only location
  * ```typescript

package/src/Cloudflare/Gateway/Logging.ts

@@ -85,7 +85,9 @@ export type GatewayLogging = Resource<
  * declare (merging them over the observed state before the PUT, since the
  * API is PUT-only). The pre-management snapshot is captured on first touch
  * and restored on destroy (capture-and-restore).
- *
+ * @resource
+ * @product Gateway
+ * @category Cloudflare One (Zero Trust)
  * @section Managing logging settings
  * @example Log everything, keep PII
  * ```typescript

package/src/Cloudflare/Gateway/ProxyEndpoint.ts

@@ -90,7 +90,9 @@ export type GatewayProxyEndpoint = Resource<
  * Zero Trust plans. The kind is immutable; name and `ips` converge in
  * place. Accounts are limited to a small number of proxy endpoints, so
  * prefer reusing one per account.
- *
+ * @resource
+ * @product Gateway
+ * @category Cloudflare One (Zero Trust)
  * @section Creating a Proxy Endpoint
  * @example Identity-based endpoint (all plans)
  * ```typescript

package/src/Cloudflare/Gateway/Rule.ts

@@ -171,7 +171,9 @@ export type GatewayRule = Resource<
  * `dns` rule with `action: "override"` that points an internal hostname at
  * a Cloudflare Tunnel — without it, WARP intercepts the lookup but has
  * nowhere to send the answer.
- *
+ * @resource
+ * @product Gateway
+ * @category Cloudflare One (Zero Trust)
  * @section DNS override for a private app
  * @example Resolve an internal hostname through a Cloudflare Tunnel
  * ```typescript

package/src/Cloudflare/GoogleTagGateway/GoogleTagGateway.ts

@@ -100,7 +100,9 @@ export type GoogleTagGateway = Resource<
  * idempotent upsert. Destroy restores the configuration the zone had before
  * Alchemy first managed it (or disables the gateway when the zone had never
  * configured it).
- *
+ * @resource
+ * @product Google Tag Gateway
+ * @category Performance & Reliability
  * @section Managing the gateway
  * @example Enable Google Tag Gateway on a zone
  * ```typescript
@@ -274,7 +276,7 @@ export const GoogleTagGatewayProvider = () =>
     }),
   });
 
-const resolve = Effect.fnUntraced(function* (zone: ZoneReference) {
+const resolve = Effect.fn(function* (zone: ZoneReference) {
   const { accountId } = yield* yield* CloudflareEnvironment;
   return yield* resolveZoneId({
     accountId,

package/src/Cloudflare/Healthcheck/Healthcheck.ts

@@ -251,7 +251,9 @@ export type Healthcheck = Resource<
  * prior state `read` matches by deterministic name and reports an
  * existing check as `Unowned` — the engine refuses to take it over
  * unless `--adopt` (or `adopt(true)`) is set.
- *
+ * @resource
+ * @product Health Checks
+ * @category Performance & Reliability
  * @section Creating a Health Check
  * @example Basic HTTP health check
  * ```typescript

package/src/Cloudflare/HostnameTlsSetting/HostnameTlsSetting.ts

@@ -118,7 +118,9 @@ export type HostnameTlsSetting = Resource<
  * state, `read` scans the setting's hostname list and reports an existing
  * override as `Unowned`, so the engine refuses to take it over unless
  * `--adopt` (or `adopt(true)`) is set.
- *
+ * @resource
+ * @product Hostname TLS Settings
+ * @category SSL/TLS & Certificates
  * @section Minimum TLS version
  * @example Require TLS 1.2 for a single hostname
  * ```typescript

package/src/Cloudflare/HttpClientUtils.ts

@@ -0,0 +1,31 @@
+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 { RuntimeContext } from "../RuntimeContext.ts";
+
+/**
+ * Resolve credentials from a bound token's value and provide them (plus the
+ * fetch-based HTTP client) to a raw SDK operation.
+ */
+export const authorizeWith =
+  (token: { value: Effect.Effect<Redacted.Redacted<string>> }) =>
+  <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),
+            ),
+          ),
+        ),
+      ),
+    );

package/src/Cloudflare/Hyperdrive/Hyperdrive.ts

@@ -133,7 +133,9 @@ export type Hyperdrive = Resource<
  * Hyperdrive accelerates and pools connections to existing PostgreSQL or
  * MySQL databases, exposing them to Workers via a binding. Create a config
  * as a resource, then bind it to a Worker to obtain a connection string.
- *
+ * @resource
+ * @product Hyperdrive
+ * @category Storage & Databases
  * @section Creating a Hyperdrive
  * @example Public Postgres origin
  * ```typescript

package/src/Cloudflare/Hyperdrive/HyperdriveBinding.ts

@@ -9,6 +9,7 @@ import type { RuntimeContext } from "../../RuntimeContext.ts";
 import { isWorker, WorkerEnvironment } from "../Workers/Worker.ts";
 import type { Hyperdrive } from "./Hyperdrive.ts";
 import { defaultPort, type HyperdriveDevOrigin } from "./Hyperdrive.ts";
+import type { Providers } from "../Providers.ts";
 
 export interface HyperdriveBindingClient {
   /**
@@ -60,6 +61,8 @@ export interface HyperdriveBindingClient {
  * ```
  *
  * @binding
+ * @product Hyperdrive
+ * @category Storage & Databases
  */
 export class HyperdriveBinding extends Binding.Service<
   HyperdriveBinding,
@@ -96,7 +99,8 @@ export const HyperdriveBindingLive = Layer.effect(
 
 export class HyperdriveBindingPolicy extends Binding.Policy<
   HyperdriveBindingPolicy,
-  (hyperdrive: Hyperdrive) => Effect.Effect<void>
+  (hyperdrive: Hyperdrive) => Effect.Effect<void>,
+  Providers
 >()("Cloudflare.Hyperdrive.Binding") {}
 
 export const HyperdriveBindingPolicyLive = HyperdriveBindingPolicy.layer.effect(

package/src/Cloudflare/Iam/ResourceGroup.ts

@@ -85,7 +85,9 @@ export type IamResourceGroup = Resource<
  *
  * Account-scoped IAM (resource groups, user groups) is an Enterprise
  * feature.
- *
+ * @resource
+ * @product IAM
+ * @category Account & Identity
  * @section Creating a Resource Group
  * @example Scope a group to the whole account
  * ```typescript

package/src/Cloudflare/Iam/UserGroup.ts

@@ -102,7 +102,9 @@ export type IamUserGroup = Resource<
  *
  * Account-scoped IAM (resource groups, user groups) is an Enterprise
  * feature.
- *
+ * @resource
+ * @product IAM
+ * @category Account & Identity
  * @section Creating a User Group
  * @example Empty group
  * ```typescript

package/src/Cloudflare/Iam/UserGroupMembership.ts

@@ -61,7 +61,9 @@ export type IamUserGroupMembership = Resource<
  *
  * Account-scoped IAM (user groups and their members) is an Enterprise
  * feature.
- *
+ * @resource
+ * @product IAM
+ * @category Account & Identity
  * @section Adding a Member
  * @example Add an account member to a user group
  * ```typescript
@@ -124,6 +126,13 @@ export const IamUserGroupMembershipProvider = () =>
               Effect.catchTag("UserGroupNotFound", () =>
                 Effect.succeed([] as IamUserGroupMembershipAttributes[]),
               ),
+              // A group whose policy Cloudflare can't validate rejects the
+              // member listing with a 400 ("Policy validation failed"). It's
+              // not ours to enumerate — contribute nothing rather than failing
+              // the whole account-wide listing.
+              Effect.catchTag("PolicyValidationFailed", () =>
+                Effect.succeed([] as IamUserGroupMembershipAttributes[]),
+              ),
             ),
         { concurrency: 10 },
       );

package/src/Cloudflare/Images/Images.ts

@@ -59,7 +59,9 @@ export const isImages = (value: unknown): value is Images =>
  * inputs and return `Effect`s — `info`, `input(...).transform(...)
  * .draw(...).output(...)`. The runtime conversion to Cloudflare's
  * `ReadableStream` is handled internally.
- *
+ * @binding
+ * @product Images
+ * @category Media
  * @section Effect-style Worker (recommended)
  * @example Read image format and dimensions from the request body
  * ```typescript

package/src/Cloudflare/Images/ImagesBinding.ts

@@ -8,6 +8,7 @@ import type { ResourceLike } from "../../Resource.ts";
 import type { RuntimeContext } from "../../RuntimeContext.ts";
 import { isWorker, WorkerEnvironment } from "../Workers/Worker.ts";
 import { type Images as ImagesLike } from "./Images.ts";
+import type { Providers } from "../Providers.ts";
 
 export class ImagesError extends Data.TaggedError("ImagesError")<{
   message: string;
@@ -76,6 +77,11 @@ export interface ImagesClient {
   ): Effect.Effect<ImageTransformerClient, never, RuntimeContext | R>;
 }
 
+/**
+ * @binding
+ * @product Images
+ * @category Media
+ */
 export class ImagesBinding extends Binding.Service<
   ImagesBinding,
   (images: ImagesLike) => Effect.Effect<ImagesClient>
@@ -115,7 +121,8 @@ export const ImagesBindingLive = Layer.effect(
 
 export class ImagesBindingPolicy extends Binding.Policy<
   ImagesBindingPolicy,
-  (images: ImagesLike) => Effect.Effect<void>
+  (images: ImagesLike) => Effect.Effect<void>,
+  Providers
 >()("Cloudflare.Images.Binding") {}
 
 export const ImagesBindingPolicyLive = ImagesBindingPolicy.layer.succeed(

package/src/Cloudflare/Images/SigningKey.ts

@@ -59,7 +59,9 @@ export type ImagesSigningKey = Resource<
  *
  * Requires the Cloudflare Images subscription; accounts without it receive
  * the typed `ImagesAccessNotEnabled` error.
- *
+ * @resource
+ * @product Images
+ * @category Media
  * @section Creating a Signing Key
  * @example Key with a generated name
  * ```typescript

package/src/Cloudflare/Images/Variant.ts

@@ -1,6 +1,7 @@
 import * as images from "@distilled.cloud/cloudflare/images";
 import * as Effect from "effect/Effect";
 import * as Predicate from "effect/Predicate";
+import * as Schedule from "effect/Schedule";
 
 import { Unowned } from "../../AdoptPolicy.ts";
 import { isResolved } from "../../Diff.ts";
@@ -108,7 +109,9 @@ export type ImagesVariant = Resource<
  * Note: every Images-enabled account has a built-in `public` variant. Do not
  * manage `public` with this resource — Cloudflare silently ignores deletes
  * of the built-in variant, so destroy would not actually remove it.
- *
+ * @resource
+ * @product Images
+ * @category Media
  * @section Creating a Variant
  * @example Thumbnail variant
  * ```typescript
@@ -244,14 +247,14 @@ export const ImagesVariantProvider = () =>
       return output?.variantName ? attrs : Unowned(attrs);
     }),
 
-    reconcile: Effect.fn(function* ({ id, news, output }) {
+    reconcile: Effect.fn(function* ({ id, news }) {
       const { accountId } = yield* yield* CloudflareEnvironment;
       // Inputs have been resolved to concrete strings by Plan.
       const acct = (news.accountId as string | undefined) ?? accountId;
       const name = news.name ?? id;
 
-      // 1. Observe — cloud state is authoritative. `output` is only a hint;
-      //    a missing variant falls through to create.
+      // 1. Observe — cloud state is authoritative. The cached output is only
+      //    a hint; a missing variant falls through to create.
       let observed = yield* getVariant(acct, name);
 
       // 2. Ensure — create when missing. A concurrent create surfaces as
@@ -316,6 +319,22 @@ export const ImagesVariantProvider = () =>
           variantId: output.variantName,
         })
         .pipe(Effect.catchTag("VariantNotFound", () => Effect.void));
+
+      // Cloudflare's variant DELETE is eventually consistent: the GET
+      // endpoint keeps returning the variant for a short window after a
+      // successful delete. Confirm it is actually gone before reporting
+      // success, so the engine's replacement GC (which deletes the OLD
+      // generation as the new one is created) leaves a genuinely clean slate
+      // rather than an orphan that lingers past the caller's verification.
+      // Bounded — if it never clears we stop polling and proceed.
+      yield* getVariant(output.accountId, output.variantName).pipe(
+        Effect.repeat({
+          schedule: Schedule.exponential("500 millis").pipe(
+            Schedule.both(Schedule.recurs(12)),
+          ),
+          until: (observed) => observed === undefined,
+        }),
+      );
     }),
   });
 

package/src/Cloudflare/Intel/IndicatorFeed.ts

@@ -107,7 +107,9 @@ export type IndicatorFeed = Resource<
  * adopts an existing feed with the same name instead of creating a
  * duplicate.
  * :::
- *
+ * @resource
+ * @product Intel
+ * @category Observability & Analytics
  * @section Creating a Feed
  * @example Basic feed
  * ```typescript

package/src/Cloudflare/Intel/IndicatorFeedPermission.ts

@@ -54,7 +54,9 @@ export type IndicatorFeedPermission = Resource<
  * Cloudflare exposes no API to list the grantees of a feed from the
  * provider side (the permissions "view" endpoint lists feeds the *calling*
  * account can consume), so `read` reports the last known state.
- *
+ * @resource
+ * @product Intel
+ * @category Observability & Analytics
  * @section Granting Access
  * @example Grant a consumer account access to a feed
  * ```typescript

package/src/Cloudflare/KV/{KVNamespace.ts → Namespace.ts}

@@ -8,7 +8,6 @@ import * as Provider from "../../Provider.ts";
 import { Resource } from "../../Resource.ts";
 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
 import type { Providers } from "../Providers.ts";
-import { KVNamespaceBinding } from "./KVNamespaceBinding.ts";
 
 export const isKVNamespace = (value: unknown): value is KVNamespace =>
   typeof value === "object" &&
@@ -42,7 +41,9 @@ export type KVNamespace = Resource<
  * KV provides eventually-consistent, low-latency reads with global
  * replication. Create a namespace as a resource, then bind it to a Worker
  * to get/put values at runtime.
- *
+ * @resource
+ * @product KV
+ * @category Storage & Databases
  * @section Creating a Namespace
  * @example Basic KV namespace
  * ```typescript
@@ -52,7 +53,7 @@ export type KVNamespace = Resource<
  * @section Binding to a Worker
  * @example Using KV inside a Worker
  * ```typescript
- * const kv = yield* Cloudflare.KVNamespace.bind(MyKV);
+ * const kv = yield* Cloudflare.KV.ReadWriteNamespace(MyKV);
  *
  * // Read a value
  * const value = yield* kv.get("my-key");
@@ -60,10 +61,14 @@ export type KVNamespace = Resource<
  * // Write a value
  * yield* kv.put("my-key", "hello world");
  * ```
+ *
+ * Provide `Cloudflare.KV.ReadWriteNamespaceBinding` (native Worker
+ * binding) or `Cloudflare.KV.ReadWriteNamespaceHttp` (scoped HTTP
+ * token) in the worker's runtime layer. Use `Cloudflare.KV.ReadNamespace`
+ * / `Cloudflare.KV.WriteNamespace` for least-privilege read- or
+ * write-only access.
  */
-export const KVNamespace = Resource<KVNamespace>("Cloudflare.KVNamespace")({
-  bind: KVNamespaceBinding.bind,
-});
+export const KVNamespace = Resource<KVNamespace>("Cloudflare.KVNamespace");
 
 export const KVNamespaceProvider = () =>
   Provider.succeed(KVNamespace, {
@@ -223,7 +228,7 @@ const createTitle = (id: string, title: string | undefined) =>
 // adoption-by-name has to scan every page. Use the paginated
 // `.items` stream off the un-yielded operation method (yielding
 // `kv.listNamespaces` collapses it to a single-page call).
-const findNamespaceByTitle = Effect.fnUntraced(function* (title: string) {
+const findNamespaceByTitle = Effect.fn(function* (title: string) {
   const { accountId } = yield* yield* CloudflareEnvironment;
   return yield* kv.listNamespaces.items({ accountId }).pipe(
     Stream.filter((ns) => ns.title === title),

package/src/Cloudflare/KV/NamespaceBinding.ts

@@ -0,0 +1,68 @@
+import type * as runtime from "@cloudflare/workers-types";
+import * as Effect from "effect/Effect";
+import { Worker, WorkerEnvironment } from "../Workers/Worker.ts";
+import type { KVNamespace } from "./Namespace.ts";
+import { KVNamespaceError } from "./NamespaceTypes.ts";
+
+/**
+ * Shared scaffolding for the Worker-binding implementations of the KV
+ * services.
+ *
+ * Resolves the {@link WorkerEnvironment} and host {@link Worker}, registers
+ * the `kv_namespace` binding at deploy time, then delegates to `makeClient`
+ * with the shared {@link makeKVNamespaceHelpers} to build the
+ * read/write/read-write client.
+ */
+export const makeKVNamespaceBinding = <Client>(options: {
+  makeClient: (helpers: ReturnType<typeof makeKVNamespaceHelpers>) => Client;
+}) =>
+  Effect.gen(function* () {
+    const env = yield* WorkerEnvironment;
+    const host = yield* Worker;
+
+    return Effect.fn(function* (namespace: KVNamespace) {
+      if (!globalThis.__ALCHEMY_RUNTIME__) {
+        yield* host.bind`${namespace}`({
+          bindings: [
+            {
+              type: "kv_namespace",
+              name: namespace.LogicalId,
+              namespaceId: namespace.namespaceId,
+            },
+          ],
+        });
+      }
+
+      return options.makeClient(makeKVNamespaceHelpers(env, namespace));
+    });
+  });
+
+/** Primitives shared by the read and write halves of the binding client. */
+export const makeKVNamespaceHelpers = (
+  env: Record<string, any>,
+  namespace: KVNamespace,
+) => {
+  const raw = Effect.sync(
+    // Lazy — the WorkerEnvironment binding is not populated until runtime.
+    () => (env as Record<string, runtime.KVNamespace>)[namespace.LogicalId]!,
+  );
+
+  const tryPromise = <T>(
+    fn: () => Promise<T>,
+  ): Effect.Effect<T, KVNamespaceError> =>
+    Effect.tryPromise({
+      try: fn,
+      catch: (error: any) =>
+        new KVNamespaceError({
+          message: error?.message ?? "Unknown error",
+          cause: error,
+        }),
+    });
+
+  const use = <T>(
+    fn: (raw: runtime.KVNamespace<string>) => Promise<T>,
+  ): Effect.Effect<T, KVNamespaceError> =>
+    raw.pipe(Effect.flatMap((raw) => tryPromise(() => fn(raw))));
+
+  return { raw, use, tryPromise };
+};