alchemy 0.5.2 → 0.6.0

package/src/cloudflare/kv-namespace.ts

@@ -1,7 +1,12 @@
 import type { Context } from "../context";
 import { Resource } from "../resource";
 import { withExponentialBackoff } from "../util/retry";
-import { createCloudflareApi } from "./api";
+import {
+  CloudflareApi,
+  createCloudflareApi,
+  type CloudflareApiOptions,
+} from "./api";
+import { handleApiError } from "./api-error";
 
 export function isKVNamespace(resource: any): resource is KVNamespace {
   return (
@@ -12,7 +17,7 @@ export function isKVNamespace(resource: any): resource is KVNamespace {
 /**
  * Properties for creating or updating a KV Namespace
  */
-export interface KVNamespaceProps {
+export interface KVNamespaceProps extends CloudflareApiOptions {
   /**
    * Title of the namespace
    */
@@ -119,28 +124,16 @@ export const KVNamespace = Resource(
   async function (
     this: Context<KVNamespace>,
     id: string,
-    props: KVNamespaceProps,
+    props: KVNamespaceProps
   ) {
     // Create Cloudflare API client with automatic account discovery
-    const api = await createCloudflareApi();
+    const api = await createCloudflareApi(props);
 
     if (this.phase === "delete") {
       // For delete operations, we need to check if the namespace ID exists in the output
       const namespaceId = this.output?.namespaceId;
       if (namespaceId) {
-        // Delete KV namespace
-        const deleteResponse = await api.delete(
-          `/accounts/${api.accountId}/storage/kv/namespaces/${namespaceId}`,
-        );
-
-        if (!deleteResponse.ok && deleteResponse.status !== 404) {
-          const errorData: any = await deleteResponse.json().catch(() => ({
-            errors: [{ message: deleteResponse.statusText }],
-          }));
-          throw new Error(
-            `Error deleting KV namespace '${props.title}': ${errorData.errors?.[0]?.message || deleteResponse.statusText}`,
-          );
-        }
+        await deleteKVNamespace(api, namespaceId);
       }
 
       // Return minimal output for deleted state
@@ -159,96 +152,12 @@ export const KVNamespace = Resource(
         // Can't update a KV namespace title directly, just work with existing ID
       } else {
         // TODO: if it already exists, then check the tags to see if we own it and continue
-
-        // Create new KV namespace
-        const createResponse = await api.post(
-          `/accounts/${api.accountId}/storage/kv/namespaces`,
-          {
-            title: props.title,
-          },
-        );
-
-        if (!createResponse.ok) {
-          const errorData: any = await createResponse.json().catch(() => ({
-            errors: [{ message: createResponse.statusText }],
-          }));
-          throw new Error(
-            `Error creating KV namespace '${props.title}': ${errorData.errors?.[0]?.message || createResponse.statusText}`,
-          );
-        }
-
-        const createResult: any = await createResponse.json();
-        namespaceId = createResult.result.id;
+        const { id } = await createKVNamespace(api, props);
         createdAt = Date.now();
+        namespaceId = id;
       }
 
-      // Handle KV pairs if provided
-      if (props.values && props.values.length > 0 && namespaceId) {
-        // Process KV pairs in batches of 10000 (API limit)
-        const BATCH_SIZE = 10000;
-
-        for (let i = 0; i < props.values.length; i += BATCH_SIZE) {
-          const batch = props.values.slice(i, i + BATCH_SIZE);
-
-          const bulkPayload = batch.map((entry) => {
-            const item: any = {
-              key: entry.key,
-              value:
-                typeof entry.value === "string"
-                  ? entry.value
-                  : JSON.stringify(entry.value),
-            };
-
-            if (entry.expiration) {
-              item.expiration = entry.expiration;
-            }
-
-            if (entry.expirationTtl) {
-              item.expiration_ttl = entry.expirationTtl;
-            }
-
-            if (entry.metadata) {
-              item.metadata = entry.metadata;
-            }
-
-            return item;
-          });
-
-          try {
-            await withExponentialBackoff(
-              async () => {
-                const bulkResponse = await api.put(
-                  `/accounts/${api.accountId}/storage/kv/namespaces/${namespaceId}/bulk`,
-                  bulkPayload,
-                );
-
-                if (!bulkResponse.ok) {
-                  const errorData: any = await bulkResponse
-                    .json()
-                    .catch(() => ({
-                      errors: [{ message: bulkResponse.statusText }],
-                    }));
-                  const errorMessage =
-                    errorData.errors?.[0]?.message || bulkResponse.statusText;
-
-                  // Throw error to trigger retry
-                  throw new Error(`Error writing KV batch: ${errorMessage}`);
-                }
-
-                return bulkResponse;
-              },
-              (error) => {
-                // Retry on "namespace not found" errors as they're likely propagation delays
-                return error.message?.includes("not found");
-              },
-              5, // 5 retry attempts
-              1000, // Start with 1 second delay
-            );
-          } catch (error: any) {
-            console.warn(error.message);
-          }
-        }
-      }
+      await insertKVRecords(api, namespaceId, props);
 
       return this({
         type: "kv_namespace",
@@ -259,5 +168,108 @@ export const KVNamespace = Resource(
         modifiedAt: Date.now(),
       });
     }
-  },
+  }
 );
+
+export async function createKVNamespace(
+  api: CloudflareApi,
+  props: KVNamespaceProps
+): Promise<{ id: string }> {
+  const createResponse = await api.post(
+    `/accounts/${api.accountId}/storage/kv/namespaces`,
+    {
+      title: props.title,
+    }
+  );
+
+  if (!createResponse.ok) {
+    await handleApiError(createResponse, "create", "kv_namespace", props.title);
+  }
+
+  return { id: ((await createResponse.json()) as any).result.id };
+}
+
+export async function deleteKVNamespace(
+  api: CloudflareApi,
+  namespaceId: string
+) {
+  // Delete KV namespace
+  const deleteResponse = await api.delete(
+    `/accounts/${api.accountId}/storage/kv/namespaces/${namespaceId}`
+  );
+
+  if (!deleteResponse.ok && deleteResponse.status !== 404) {
+    await handleApiError(deleteResponse, "delete", "kv_namespace", namespaceId);
+  }
+}
+
+export async function insertKVRecords(
+  api: CloudflareApi,
+  namespaceId: string,
+  props: KVNamespaceProps
+) {
+  if (props.values && props.values.length > 0) {
+    // Process KV pairs in batches of 10000 (API limit)
+    const BATCH_SIZE = 10000;
+
+    for (let i = 0; i < props.values.length; i += BATCH_SIZE) {
+      const batch = props.values.slice(i, i + BATCH_SIZE);
+
+      const bulkPayload = batch.map((entry) => {
+        const item: any = {
+          key: entry.key,
+          value:
+            typeof entry.value === "string"
+              ? entry.value
+              : JSON.stringify(entry.value),
+        };
+
+        if (entry.expiration) {
+          item.expiration = entry.expiration;
+        }
+
+        if (entry.expirationTtl) {
+          item.expiration_ttl = entry.expirationTtl;
+        }
+
+        if (entry.metadata) {
+          item.metadata = entry.metadata;
+        }
+
+        return item;
+      });
+
+      try {
+        await withExponentialBackoff(
+          async () => {
+            const bulkResponse = await api.put(
+              `/accounts/${api.accountId}/storage/kv/namespaces/${namespaceId}/bulk`,
+              bulkPayload
+            );
+
+            if (!bulkResponse.ok) {
+              const errorData: any = await bulkResponse.json().catch(() => ({
+                errors: [{ message: bulkResponse.statusText }],
+              }));
+              const errorMessage =
+                errorData.errors?.[0]?.message || bulkResponse.statusText;
+
+              // Throw error to trigger retry
+              throw new Error(`Error writing KV batch: ${errorMessage}`);
+            }
+
+            return bulkResponse;
+          },
+          (error) => {
+            // Retry on "namespace not found" errors as they're likely propagation delays
+            return error.message?.includes("not found");
+          },
+          5, // 5 retry attempts
+          1000 // Start with 1 second delay
+        );
+      } catch (error: any) {
+        console.warn(error.message);
+      }
+    }
+  }
+}

package/src/cloudflare/permission-groups.ts

@@ -72,6 +72,10 @@ export type PermissionGroups = Resource<"cloudflare::PermissionGroups"> & {
  *
  * This is primarily used when creating API tokens for Cloudflare services like R2.
  *
+ * Note: Requires a Cloudflare API Key or Token with account read access.
+ * The API token must have permission to read token permission groups.
+ * The OAuth token from `wrangler login` is NOT sufficient for this operation.
+ *
  * @example
  * // Get all permission groups including those for R2
  * const permissions = await PermissionGroups("cloudflare-permissions");
@@ -99,7 +103,7 @@ export const PermissionGroups = Resource(
   async function (
     this: Context<PermissionGroups>,
     id: string,
-    options?: CloudflareApiOptions
+    options: CloudflareApiOptions = {}
   ): Promise<PermissionGroups> {
     // Only create and update phases are supported
     if (this.phase === "delete") {

package/src/cloudflare/r2-rest-state-store.ts

@@ -1,14 +1,17 @@
 import type { Scope } from "../scope";
-import type { Secret } from "../secret";
 import { deserialize, serialize } from "../serde";
 import type { State, StateStore } from "../state";
 import { withExponentialBackoff } from "../util/retry";
-import { type CloudflareApi, createCloudflareApi } from "./api";
+import {
+  type CloudflareApi,
+  type CloudflareApiOptions,
+  createCloudflareApi,
+} from "./api";
 
 /**
  * Options for CloudflareR2StateStore
  */
-export interface CloudflareR2StateStoreOptions {
+export interface CloudflareR2StateStoreOptions extends CloudflareApiOptions {
   /**
    * The prefix to use for object keys in the R2 bucket
    * This allows multiple state stores to use the same R2 bucket
@@ -20,21 +23,6 @@ export interface CloudflareR2StateStoreOptions {
    * Required - the bucket must already exist
    */
   bucketName: string;
-
-  /**
-   * API key to use (overrides CLOUDFLARE_API_KEY env var)
-   */
-  apiKey?: Secret;
-
-  /**
-   * Account ID to use (overrides CLOUDFLARE_ACCOUNT_ID env var)
-   */
-  accountId?: string;
-
-  /**
-   * Email to use with API Key authentication (overrides CLOUDFLARE_EMAIL env var)
-   */
-  email?: string;
 }
 
 /**
@@ -45,9 +33,6 @@ export class R2RestStateStore implements StateStore {
   private api: CloudflareApi;
   private prefix: string;
   private bucketName: string;
-  private apiKey: Secret | undefined;
-  private accountId: string | undefined;
-  private email: string | undefined;
   private initialized = false;
 
   /**
@@ -58,7 +43,7 @@ export class R2RestStateStore implements StateStore {
    */
   constructor(
     public readonly scope: Scope,
-    options: CloudflareR2StateStoreOptions
+    private readonly options: CloudflareR2StateStoreOptions
   ) {
     // Use the scope's chain to build the prefix, similar to how FileSystemStateStore builds its directory
     const scopePath = scope.chain.join("/");
@@ -71,10 +56,6 @@ export class R2RestStateStore implements StateStore {
     }
     this.bucketName = options.bucketName;
 
-    this.apiKey = options.apiKey;
-    this.accountId = options.accountId;
-    this.email = options.email;
-
     // We'll initialize the API in init() to allow for async creation
     this.api = null as any;
   }
@@ -86,11 +67,7 @@ export class R2RestStateStore implements StateStore {
     if (this.initialized) return;
 
     // Create Cloudflare API client with automatic account discovery
-    this.api = await createCloudflareApi({
-      apiKey: this.apiKey,
-      accountId: this.accountId,
-      email: this.email,
-    });
+    this.api = await createCloudflareApi(this.options);
 
     this.initialized = true;
   }

package/src/cloudflare/worker.ts

@@ -7,7 +7,11 @@ import { isSecret } from "../secret";
 import { getContentType } from "../util/content-type";
 import { withExponentialBackoff } from "../util/retry";
 import { slugify } from "../util/slugify";
-import { type CloudflareApi, createCloudflareApi } from "./api";
+import {
+  type CloudflareApi,
+  type CloudflareApiOptions,
+  createCloudflareApi,
+} from "./api";
 import type { Assets } from "./assets";
 import {
   type Bindings,
@@ -24,7 +28,8 @@ import type { SingleStepMigration } from "./worker-migration";
 /**
  * Properties for creating or updating a Worker
  */
-export interface WorkerProps<B extends Bindings = Bindings> {
+export interface WorkerProps<B extends Bindings = Bindings>
+  extends CloudflareApiOptions {
   /**
    * The worker script content (JavaScript or WASM)
    * One of script, entryPoint, or bundle must be provided
@@ -58,12 +63,6 @@ export interface WorkerProps<B extends Bindings = Bindings> {
    */
   name: string;
 
-  /**
-   * Routes to associate with this worker
-   * Format: example.com/* or *.example.com/*
-   */
-  routes?: string[];
-
   /**
    * Bindings to attach to the worker
    */
@@ -236,7 +235,7 @@ export const Worker = Resource(
     props: WorkerProps<B>
   ): Promise<Worker<B>> {
     // Create Cloudflare API client with automatic account discovery
-    const api = await createCloudflareApi();
+    const api = await createCloudflareApi(props);
 
     // Use the provided name
     const workerName = props.name;
@@ -299,9 +298,6 @@ export const Worker = Resource(
     // TODO: it is less than ideal that this can fail, resulting in state problem
     await this.set("bindings", props.bindings);
 
-    // Handle routes if requested
-    await setupRoutes(api, workerName, props.routes || []);
-
     // Handle worker URL if requested
     const workerUrl = await configureURL(
       this,
@@ -320,7 +316,6 @@ export const Worker = Resource(
       name: workerName,
       script: scriptContent,
       format: props.format || "esm", // Include format in the output
-      routes: props.routes || [],
       bindings: props.bindings ?? ({} as B),
       env: props.env,
       observability: scriptMetadata.observability,
@@ -354,35 +349,6 @@ async function deleteWorker<B extends Bindings>(
     );
   }
 
-  // Also remove any associated routes if they exist
-  if (ctx.output?.routes && ctx.output.routes.length > 0 && api.zoneId) {
-    // First get existing routes to find their IDs
-    const routesResponse = await api.get(`/zones/${api.zoneId}/workers/routes`);
-
-    if (!routesResponse.ok) {
-      throw new Error(
-        `Could not fetch routes for cleanup: ${routesResponse.status} ${routesResponse.statusText}`
-      );
-    }
-    const routesData: any = await routesResponse.json();
-    const existingRoutes = routesData.result || [];
-
-    for (const route of existingRoutes) {
-      if (ctx.output.routes.includes(route.pattern)) {
-        // Delete the route
-        const routeDeleteResponse = await api.delete(
-          `/zones/${api.zoneId}/workers/routes/${route.id}`
-        );
-
-        if (!routeDeleteResponse.ok) {
-          console.warn(
-            `Failed to delete route ${route.pattern}: ${routeDeleteResponse.status} ${routeDeleteResponse.statusText}`
-          );
-        }
-      }
-    }
-  }
-
   // Disable the URL if it was enabled
   if (ctx.output?.url) {
     try {
@@ -717,67 +683,6 @@ async function bundleWorkerScript<B extends Bindings>(props: WorkerProps) {
   }
 }
 
-async function setupRoutes(
-  api: CloudflareApi,
-  workerName: string,
-  routes: string[]
-) {
-  // Set up routes if provided
-  if (routes && routes.length > 0 && api.zoneId) {
-    // First get existing routes
-    const routesResponse = await api.get(`/zones/${api.zoneId}/workers/routes`);
-
-    if (!routesResponse.ok) {
-      throw new Error(
-        `Could not fetch routes: ${routesResponse.status} ${routesResponse.statusText}`
-      );
-    }
-    const routesData: any = await routesResponse.json();
-    const existingRoutes = routesData.result || [];
-
-    // For each desired route
-    for (const pattern of routes) {
-      const existingRoute = existingRoutes.find(
-        (r: any) => r.pattern === pattern
-      );
-
-      if (existingRoute) {
-        // Update if script name doesn't match
-        if (existingRoute.script !== workerName) {
-          const updateRouteResponse = await api.put(
-            `/zones/${api.zoneId}/workers/routes/${existingRoute.id}`,
-            {
-              pattern,
-              script: workerName,
-            }
-          );
-
-          if (!updateRouteResponse.ok) {
-            console.warn(
-              `Failed to update route ${pattern}: ${updateRouteResponse.status} ${updateRouteResponse.statusText}`
-            );
-          }
-        }
-      } else {
-        // Create new route
-        const createRouteResponse = await api.post(
-          `/zones/${api.zoneId}/workers/routes`,
-          {
-            pattern,
-            script: workerName,
-          }
-        );
-
-        if (!createRouteResponse.ok) {
-          throw new Error(
-            `Failed to create route ${pattern}: ${createRouteResponse.status} ${createRouteResponse.statusText}`
-          );
-        }
-      }
-    }
-  }
-}
-
 async function configureURL<B extends Bindings>(
   ctx: Context<Worker<B>>,
   api: CloudflareApi,
@@ -1006,8 +911,6 @@ async function uploadAssets(
       formData.append(fileHash, blob, fileHash);
     }
 
-    console.log(`Uploading ${totalBytes} bytes of assets`);
-
     // Upload this batch of files
     const uploadResponse = await api.post(
       `/accounts/${api.accountId}/workers/assets/upload?base64=true`,

package/src/cloudflare/zone.ts

@@ -1,6 +1,6 @@
 import type { Context } from "../context";
 import { Resource } from "../resource";
-import { createCloudflareApi } from "./api";
+import { createCloudflareApi, type CloudflareApiOptions } from "./api";
 import type {
   AlwaysUseHTTPSValue,
   AutomaticHTTPSRewritesValue,
@@ -24,18 +24,12 @@ import type {
 /**
  * Properties for creating or updating a Zone
  */
-export interface ZoneProps {
+export interface ZoneProps extends CloudflareApiOptions {
   /**
    * The domain name for the zone
    */
   name: string;
 
-  /**
-   * Account ID to use for the zone
-   * If not provided, will use the default account
-   */
-  accountId?: string;
-
   /**
    * The type of zone to create
    * "full" - Full zone implies that DNS is hosted with Cloudflare
@@ -305,12 +299,10 @@ export const Zone = Resource(
   async function (
     this: Context<Zone>,
     id: string,
-    props: ZoneProps,
+    props: ZoneProps
   ): Promise<Zone> {
     // Create Cloudflare API client with automatic account discovery
-    const api = await createCloudflareApi({
-      accountId: props.accountId,
-    });
+    const api = await createCloudflareApi(props);
 
     if (this.phase === "delete") {
       if (this.output?.id) {
@@ -322,7 +314,7 @@ export const Zone = Resource(
             errors: [{ message: deleteResponse.statusText }],
           }));
           throw new Error(
-            `Error deleting zone '${props.name}': ${errorData.errors?.[0]?.message || deleteResponse.statusText}`,
+            `Error deleting zone '${props.name}': ${errorData.errors?.[0]?.message || deleteResponse.statusText}`
           );
         }
       } else {
@@ -337,7 +329,7 @@ export const Zone = Resource(
 
       if (!response.ok) {
         throw new Error(
-          `Error getting zone '${props.name}': ${response.statusText}`,
+          `Error getting zone '${props.name}': ${response.statusText}`
         );
       }
 
@@ -385,13 +377,13 @@ export const Zone = Resource(
         if (response.status === 400 && body.includes("already exists")) {
           // Zone already exists, fetch it instead
           console.warn(
-            `Zone '${props.name}' already exists during Zone create, adopting it...`,
+            `Zone '${props.name}' already exists during Zone create, adopting it...`
           );
           const getResponse = await api.get(`/zones?name=${props.name}`);
 
           if (!getResponse.ok) {
             throw new Error(
-              `Error fetching existing zone '${props.name}': ${getResponse.statusText}`,
+              `Error fetching existing zone '${props.name}': ${getResponse.statusText}`
             );
           }
 
@@ -400,13 +392,13 @@ export const Zone = Resource(
           ).result;
           if (zones.length === 0) {
             throw new Error(
-              `Zone '${props.name}' does not exist, but the name is reserved for another user.`,
+              `Zone '${props.name}' does not exist, but the name is reserved for another user.`
             );
           }
           zoneData = zones[0];
         } else {
           throw new Error(
-            `Error creating zone '${props.name}': ${response.statusText}\n${body}`,
+            `Error creating zone '${props.name}': ${response.statusText}\n${body}`
           );
         }
       } else {
@@ -437,7 +429,7 @@ export const Zone = Resource(
         settings: await getZoneSettings(api, zoneData.id),
       });
     }
-  },
+  }
 );
 
 /**
@@ -446,7 +438,7 @@ export const Zone = Resource(
 async function updateZoneSettings(
   api: any,
   zoneId: string,
-  settings: ZoneProps["settings"],
+  settings: ZoneProps["settings"]
 ): Promise<void> {
   if (!settings) return;
 
@@ -480,7 +472,7 @@ async function updateZoneSettings(
           `/zones/${zoneId}/settings/${settingId}`,
           {
             value,
-          } as UpdateZoneSettingParams,
+          } as UpdateZoneSettingParams
         );
 
         if (!response.ok) {
@@ -490,10 +482,10 @@ async function updateZoneSettings(
             return;
           }
           throw new Error(
-            `Failed to update zone setting ${key}: ${response.statusText}`,
+            `Failed to update zone setting ${key}: ${response.statusText}`
           );
         }
-      }),
+      })
   );
 }
 
@@ -502,13 +494,13 @@ async function updateZoneSettings(
  */
 async function getZoneSettings(
   api: any,
-  zoneId: string,
+  zoneId: string
 ): Promise<Zone["settings"]> {
   const settingsResponse = await api.get(`/zones/${zoneId}/settings`);
 
   if (!settingsResponse.ok) {
     throw new Error(
-      `Failed to fetch zone settings: ${settingsResponse.status} ${settingsResponse.statusText}`,
+      `Failed to fetch zone settings: ${settingsResponse.status} ${settingsResponse.statusText}`
     );
   }
 

package/src/internal/docs/providers.ts

@@ -67,13 +67,6 @@ export async function Providers({
     .filter((dirent) => dirent.isDirectory() && !exclude.includes(dirent.name))
     .map((dirent) => path.join(dirent.parentPath, dirent.name));
 
-  // For each provider, list all files
-  if (filter === false) {
-    return [];
-  } else if (typeof filter === "number") {
-    providers = providers.slice(0, filter);
-  }
-
   if (parallel) {
     return await Promise.all(
       providers.map((provider) =>