alchemy 0.5.2 → 0.6.0

package/lib/cloudflare/auth.js

@@ -1,79 +1,68 @@
-/**
- * Get authentication headers for Cloudflare API
- *
- * Priority:
- * 1. API Token (CLOUDFLARE_API_TOKEN) - Recommended by Cloudflare
- * 2. API Key (CLOUDFLARE_API_KEY) - Will attempt to discover email automatically
- *
- * @param options Authentication options
- * @returns Authentication headers
- */
-export async function getCloudflareAuth(options = {}) {
-    const { required = true } = options;
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { handleApiError } from "./api-error";
+const userInfoCache = {};
+export async function getCloudflareUserInfo(options) {
+    const cacheKey = JSON.stringify({
+        apiKey: options.apiKey?.unencrypted,
+        apiToken: options.apiToken?.unencrypted,
+        email: options.email,
+    });
+    if (userInfoCache[cacheKey]) {
+        return userInfoCache[cacheKey];
+    }
+    const headers = await getCloudflareAuthHeaders(options);
+    const user = await fetch("https://api.cloudflare.com/client/v4/user", {
+        headers,
+    });
+    if (!user.ok) {
+        if (user.status === 403) {
+            throw new Error("Cloudflare authentication required. Did you forget to login with `wrangler login` or set CLOUDFLARE_API_TOKEN, CLOUDFLARE_API_KEY, or CLOUDFLARE_EMAIL, or CLOUDFLARE_API_KEY?");
+        }
+        await handleApiError(user, "getting", "user", "user");
+    }
+    const accounts = await fetch("https://api.cloudflare.com/client/v4/accounts", {
+        headers,
+    });
+    const userInfo = {
+        ...(await user.json()).result,
+        accounts: (await accounts.json()).result,
+    };
+    userInfoCache[cacheKey] = userInfo;
+    return userInfo;
+}
+export async function getCloudflareAuthHeaders(options = {}) {
     // Check for API Token (preferred method)
-    const apiToken = process.env.CLOUDFLARE_API_TOKEN;
+    const apiToken = options.apiToken?.unencrypted ?? process.env.CLOUDFLARE_API_TOKEN;
     if (apiToken) {
         return {
-            headers: {
-                Authorization: `Bearer ${apiToken}`,
-            },
-            type: "token",
+            Authorization: `Bearer ${apiToken}`,
         };
     }
     // Check for API Key
-    const apiKey = process.env.CLOUDFLARE_API_KEY;
+    const apiKey = options.apiKey?.unencrypted ?? process.env.CLOUDFLARE_API_KEY;
     if (apiKey) {
-        // If email is provided directly, use it
-        const providedEmail = options.email || process.env.CLOUDFLARE_EMAIL;
-        if (providedEmail) {
-            return {
-                headers: {
-                    "X-Auth-Key": apiKey,
-                    "X-Auth-Email": providedEmail,
-                },
-                type: "key",
-                email: providedEmail,
-            };
-        }
-        // Otherwise, try to discover email from Cloudflare API
-        try {
-            const email = await getUserEmailFromApiKey(apiKey);
-            return {
-                headers: {
-                    "X-Auth-Key": apiKey,
-                    "X-Auth-Email": email,
-                },
-                type: "key",
-                email,
-            };
-        }
-        catch (error) {
-            console.error("Failed to discover email from API key:", error);
-            throw new Error("Failed to automatically discover email for API Key authentication.\n" +
-                "Options:\n" +
-                "1. Set CLOUDFLARE_EMAIL environment variable\n" +
-                "2. Use CLOUDFLARE_API_TOKEN instead (recommended by Cloudflare)");
-        }
+        return {
+            "X-Auth-Key": apiKey,
+            "X-Auth-Email": options.email ??
+                process.env.CLOUDFLARE_EMAIL ??
+                (await getUserEmailFromApiKey(apiKey)),
+        };
     }
-    // No authentication found
-    if (required) {
-        throw new Error("Cloudflare authentication required. Set either:\n" +
-            "1. CLOUDFLARE_API_TOKEN (recommended by Cloudflare)\n" +
-            "   Generate a token at: https://dash.cloudflare.com/profile/api-tokens\n" +
-            "2. CLOUDFLARE_API_KEY environment variable");
+    const authConfig = await getRefreshedAuthConfig();
+    if (authConfig.oauth_token) {
+        return {
+            Authorization: `Bearer ${authConfig.oauth_token}`,
+        };
     }
-    return {
-        headers: {},
-        type: "none",
-    };
+    throw new Error("Cloudflare authentication required. Did you forget to login with `wrangler login` or set CLOUDFLARE_API_TOKEN, CLOUDFLARE_API_KEY, or CLOUDFLARE_EMAIL, or CLOUDFLARE_API_KEY?");
 }
-/**
- * Fetch the user's email from Cloudflare API using API Key
- *
- * @param apiKey The Cloudflare API key
- * @returns The user's email
- */
+const emailCache = {};
 async function getUserEmailFromApiKey(apiKey) {
+    if (emailCache[apiKey]) {
+        return emailCache[apiKey];
+    }
     try {
         const baseUrl = "https://api.cloudflare.com/client/v4";
         // Call the /user endpoint to get user information
@@ -90,6 +79,7 @@ async function getUserEmailFromApiKey(apiKey) {
         if (!data.success || !data.result || !data.result.email) {
             throw new Error("Cloudflare API did not return valid user information");
         }
+        emailCache[apiKey] = data.result.email;
         return data.result.email;
     }
     catch (error) {
@@ -97,17 +87,98 @@ async function getUserEmailFromApiKey(apiKey) {
         throw new Error("Failed to automatically discover email for API Key authentication");
     }
 }
-/**
- * Get headers for a Cloudflare API request, including content-type
- *
- * @param contentType Content type for the request
- * @param options Authentication options
- * @returns Complete headers for the request
- */
-export async function getCloudflareHeaders(contentType = "application/json", options = {}) {
-    const auth = await getCloudflareAuth(options);
-    return {
-        "Content-Type": contentType,
-        ...auth.headers,
+async function refreshAuthToken(options) {
+    const response = await fetch("https://dash.cloudflare.com/oauth2/token", {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: new URLSearchParams({
+            grant_type: "refresh_token",
+            refresh_token: options.refresh_token,
+            client_id: "54d11594-84e4-41aa-b438-e81b8fa78ee7",
+        }).toString(),
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to refresh auth token: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json();
+    if (!data.access_token) {
+        throw new Error("Failed to refresh auth token - no access token returned");
+    }
+    options.oauth_token = data.access_token;
+    options.refresh_token = data.refresh_token;
+    options.expiration_time = new Date(Date.now() + data.expires_in * 1000).toISOString();
+    options.scopes = data.scope?.split(" ") || [];
+    return options;
+}
+async function getRefreshedAuthConfig() {
+    let authConfig = await readWranglerConfig();
+    if (authConfig.expiration_time) {
+        const expiry = new Date(authConfig.expiration_time);
+        // if expiring in 10s
+        if (expiry.getTime() < Date.now() + 10 * 1000) {
+            authConfig = await refreshAuthToken(authConfig);
+            authConfigCache[authConfig.path] = authConfig;
+            await writeWranglerConfig(authConfig);
+        }
+    }
+    return authConfig;
+}
+async function writeWranglerConfig(config) {
+    const TOML = await import("@iarna/toml");
+    const configPath = await findWranglerConfig();
+    config = {
+        ...config,
     };
+    // @ts-ignore - i put this here
+    delete config.path;
+    const toml = TOML.stringify(config);
+    await fs.writeFile(configPath, toml);
+}
+// cache the file once per process
+const authConfigCache = {};
+async function readWranglerConfig() {
+    const configPath = await findWranglerConfig();
+    const config = (authConfigCache[configPath] ??= await parseTOML(await fs.readFile(configPath, "utf-8")));
+    config.path = configPath;
+    return config;
+}
+let wranglerConfigPath;
+async function findWranglerConfig() {
+    if (wranglerConfigPath) {
+        return wranglerConfigPath;
+    }
+    const environment = process.env.WRANGLER_API_ENVIRONMENT ?? "production";
+    const filePath = path.join("config", `${environment === "production" ? "default.toml" : `${environment}.toml`}`);
+    const xdgAppPaths = (await import("xdg-app-paths")).default;
+    //TODO: We should implement a custom path --global-config and/or the WRANGLER_HOME type environment variable
+    const configDir = xdgAppPaths(".wrangler").config(); // New XDG compliant config path
+    const legacyConfigDir = path.join(os.homedir(), ".wrangler"); // Legacy config in user's home directory
+    // Check for the .wrangler directory in root if it is not there then use the XDG compliant path.
+    wranglerConfigPath = path.join((await isDirectory(legacyConfigDir)) ? legacyConfigDir : configDir, filePath);
+    return wranglerConfigPath;
+}
+async function parseTOML(input) {
+    const TOML = await import("@iarna/toml");
+    try {
+        // Normalize CRLF to LF to avoid hitting https://github.com/iarna/iarna-toml/issues/33.
+        const normalizedInput = input.replace(/\r\n/g, "\n");
+        return TOML.parse(normalizedInput);
+    }
+    catch (err) {
+        const { name } = err;
+        if (name !== "TomlError") {
+            throw err;
+        }
+        throw new Error("TOML parse error");
+    }
+}
+async function isDirectory(dir) {
+    try {
+        return (await fs.stat(dir)).isDirectory();
+    }
+    catch (err) {
+        return false;
+    }
 }

package/lib/cloudflare/bucket.d.ts

@@ -1,11 +1,12 @@
 import { AwsClient } from "aws4fetch";
 import type { Context } from "../context";
 import { Resource } from "../resource";
-import { CloudflareApi, type CloudflareApiOptions } from "./api";
+import type { Secret } from "../secret";
+import { CloudflareApi } from "./api";
 /**
  * Properties for creating or updating an R2 Bucket
  */
-export interface BucketProps extends CloudflareApiOptions {
+export interface BucketProps {
     /**
      * Name of the bucket
      * Names can only contain lowercase letters (a-z), numbers (0-9), and hyphens (-)
@@ -39,6 +40,30 @@ export interface BucketProps extends CloudflareApiOptions {
      * @default false
      */
     empty?: boolean;
+    /**
+     * API Token to use for the bucket
+     */
+    apiToken?: Secret;
+    /**
+     * API Key to use for the bucket
+     */
+    apiKey?: Secret;
+    /**
+     * Email to use for the bucket
+     */
+    email?: string;
+    /**
+     * Account ID to use for the bucket
+     */
+    accountId?: string;
+    /**
+     * Access Key to use for the bucket
+     */
+    accessKey?: Secret;
+    /**
+     * Secret Access Key to use for the bucket
+     */
+    secretAccessKey?: Secret;
 }
 /**
  * Output returned after R2 Bucket creation/update
@@ -106,9 +131,9 @@ export declare const R2Bucket: (((this: any, id: string, props?: {}) => never) &
  * Configuration for R2 client to connect to Cloudflare R2
  */
 export interface R2ClientConfig {
-    accountId?: string;
-    accessKeyId?: string;
-    secretAccessKey?: string;
+    accountId: string;
+    accessKeyId?: Secret;
+    secretAccessKey?: Secret;
     jurisdiction?: string;
 }
 type R2Client = AwsClient & {

package/lib/cloudflare/bucket.js

@@ -1,6 +1,7 @@
 import { AwsClient } from "aws4fetch";
 import { Resource } from "../resource";
-import { CloudflareAccountId, CloudflareApi, CloudflareApiError, createCloudflareApi, handleApiError, } from "./api";
+import { CloudflareApi, createCloudflareApi } from "./api";
+import { CloudflareApiError, handleApiError } from "./api-error";
 /**
  * Creates and manages Cloudflare R2 Buckets for object storage.
  *
@@ -53,7 +54,10 @@ export const R2Bucket = Resource("cloudflare::R2Bucket", async function (id, pro
         if (props.delete !== false) {
             if (props.empty) {
                 console.log("Emptying R2 bucket:", bucketName);
-                const r2Client = await createR2Client(props);
+                const r2Client = await createR2Client({
+                    ...props,
+                    accountId: api.accountId,
+                });
                 // Empty the bucket first by deleting all objects
                 await emptyBucket(r2Client, bucketName, props.jurisdiction);
             }
@@ -76,6 +80,7 @@ export const R2Bucket = Resource("cloudflare::R2Bucket", async function (id, pro
             creationDate: new Date(),
             jurisdiction: props.jurisdiction || "default",
             type: "r2_bucket",
+            accountId: api.accountId,
         });
     }
 });
@@ -84,10 +89,10 @@ export const R2Bucket = Resource("cloudflare::R2Bucket", async function (id, pro
  *
  * @see https://developers.cloudflare.com/r2/examples/aws/aws-sdk-js-v3/
  */
-export async function createR2Client(config = {}) {
-    const accountId = await CloudflareAccountId(config);
-    const accessKeyId = config.accessKeyId || process.env.R2_ACCESS_KEY_ID;
-    const secretAccessKey = config.secretAccessKey || process.env.R2_SECRET_ACCESS_KEY;
+export function createR2Client(config) {
+    const accountId = config?.accountId ?? process.env.CLOUDFLARE_ACCOUNT_ID;
+    const accessKeyId = config?.accessKeyId?.unencrypted || process.env.R2_ACCESS_KEY_ID;
+    const secretAccessKey = config?.secretAccessKey?.unencrypted || process.env.R2_SECRET_ACCESS_KEY;
     if (!accountId) {
         throw new Error("CLOUDFLARE_ACCOUNT_ID environment variable is required");
     }
@@ -140,10 +145,7 @@ export async function createBucket(api, bucketName, props) {
     const headers = withJurisdiction({}, props);
     const createResponse = await api.post(`/accounts/${api.accountId}/r2/buckets`, createPayload, { headers });
     if (!createResponse.ok) {
-        const errorData = await createResponse.json().catch(() => ({
-            errors: [{ message: createResponse.statusText }],
-        }));
-        throw new CloudflareApiError(`Error creating R2 bucket '${bucketName}': ${errorData.errors?.[0]?.message || createResponse.statusText}`, createResponse);
+        return await handleApiError(createResponse, "creating", "R2 bucket", bucketName);
     }
     return (await createResponse.json());
 }
@@ -251,7 +253,6 @@ export async function emptyBucket(r2, bucketName, jurisdiction) {
  * so we still use the Cloudflare API directly.
  */
 export async function updatePublicAccess(api, bucketName, allowPublicAccess, jurisdiction) {
-    console.log(`/accounts/${api.accountId}/r2/buckets/${bucketName}/domains/managed`);
     const headers = withJurisdiction({}, jurisdiction);
     const response = await api.put(`/accounts/${api.accountId}/r2/buckets/${bucketName}/domains/managed`, {
         enabled: allowPublicAccess,

package/lib/cloudflare/custom-domain.d.ts

@@ -1,9 +1,10 @@
 import type { Context } from "../context";
 import { Resource } from "../resource";
+import { type CloudflareApiOptions } from "./api";
 /**
  * Properties for creating or updating a CustomDomain
  */
-export interface CustomDomainProps {
+export interface CustomDomainProps extends CloudflareApiOptions {
     /**
      * The domain name to bind to the worker
      */

package/lib/cloudflare/custom-domain.js

@@ -1,5 +1,6 @@
 import { Resource } from "../resource";
-import { CloudflareApi, createCloudflareApi, handleApiError } from "./api";
+import { CloudflareApi, createCloudflareApi, } from "./api";
+import { handleApiError } from "./api-error";
 /**
  * Configure custom domain for a Cloudflare Worker using the Cloudflare Custom Domains API
  * This attaches a worker to a specific hostname within a zone.
@@ -22,7 +23,7 @@ import { CloudflareApi, createCloudflareApi, handleApiError } from "./api";
 export const CustomDomain = Resource("cloudflare::CustomDomain", async function (logicalId, // Changed param name from id to logicalId for clarity
 props) {
     // Create Cloudflare API client with automatic account discovery
-    const api = await createCloudflareApi();
+    const api = await createCloudflareApi(props);
     // Validate required properties
     if (!props.name) {
         throw new Error("Domain name (props.name) is required");

package/lib/cloudflare/dns-records.d.ts

@@ -1,6 +1,7 @@
 import type { Context } from "../context";
 import type { DnsRecord as BaseDnsRecord, DnsRecordType, DnsRecordWithMetadata } from "../dns/record";
 import { Resource } from "../resource";
+import { type CloudflareApiOptions } from "./api";
 /**
  * Properties for a DNS record
  */
@@ -18,7 +19,7 @@ export interface DnsRecord extends DnsRecordWithMetadata {
 /**
  * Properties for managing multiple DNS records
  */
-export interface DnsRecordsProps {
+export interface DnsRecordsProps extends CloudflareApiOptions {
     /**
      * Zone ID or domain name where records will be created
      */

package/lib/cloudflare/dns-records.js

@@ -1,5 +1,5 @@
 import { Resource } from "../resource";
-import { createCloudflareApi } from "./api";
+import { createCloudflareApi, } from "./api";
 /**
  * Manages a batch of DNS records in a Cloudflare zone.
  * Supports creating, updating, and deleting multiple records at once.
@@ -46,7 +46,7 @@ import { createCloudflareApi } from "./api";
  */
 export const DnsRecords = Resource("cloudflare::DnsRecords", async function (id, props) {
     // Create Cloudflare API client
-    const api = await createCloudflareApi();
+    const api = await createCloudflareApi(props);
     // Get zone ID if domain name was provided
     const zoneId = props.zoneId;
     if (this.phase === "delete") {

package/lib/cloudflare/kv-namespace.d.ts

@@ -1,10 +1,11 @@
 import type { Context } from "../context";
 import { Resource } from "../resource";
+import { CloudflareApi, type CloudflareApiOptions } from "./api";
 export declare 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
      */
@@ -95,3 +96,8 @@ export interface KVNamespace extends Resource<"cloudflare::KVNamespace">, KVName
  * });
  */
 export declare const KVNamespace: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<KVNamespace>, id: string, props: KVNamespaceProps) => Promise<KVNamespace>);
+export declare function createKVNamespace(api: CloudflareApi, props: KVNamespaceProps): Promise<{
+    id: string;
+}>;
+export declare function deleteKVNamespace(api: CloudflareApi, namespaceId: string): Promise<void>;
+export declare function insertKVRecords(api: CloudflareApi, namespaceId: string, props: KVNamespaceProps): Promise<void>;

package/lib/cloudflare/kv-namespace.js

@@ -1,6 +1,7 @@
 import { Resource } from "../resource";
 import { withExponentialBackoff } from "../util/retry";
-import { createCloudflareApi } from "./api";
+import { CloudflareApi, createCloudflareApi, } from "./api";
+import { handleApiError } from "./api-error";
 export function isKVNamespace(resource) {
     return (resource && typeof resource === "object" && resource.type === "kv_namespace");
 }
@@ -42,19 +43,12 @@ export function isKVNamespace(resource) {
  */
 export const KVNamespace = Resource("cloudflare::KVNamespace", async function (id, props) {
     // 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 = 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
         return this.destroy();
@@ -71,69 +65,11 @@ export const KVNamespace = Resource("cloudflare::KVNamespace", async function (i
         }
         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 = 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 = 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 = {
-                        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 = 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);
-                }
-                catch (error) {
-                    console.warn(error.message);
-                }
-            }
-        }
+        await insertKVRecords(api, namespaceId, props);
         return this({
             type: "kv_namespace",
             namespaceId: namespaceId,
@@ -144,3 +80,68 @@ export const KVNamespace = Resource("cloudflare::KVNamespace", async function (i
         });
     }
 });
+export async function createKVNamespace(api, props) {
+    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()).result.id };
+}
+export async function deleteKVNamespace(api, namespaceId) {
+    // 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, namespaceId, props) {
+    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 = {
+                    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 = 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) {
+                console.warn(error.message);
+            }
+        }
+    }
+}

package/lib/cloudflare/permission-groups.d.ts

@@ -53,6 +53,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");

package/lib/cloudflare/permission-groups.js

@@ -6,6 +6,10 @@ import { createCloudflareApi } from "./api";
  *
  * 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");
@@ -28,7 +32,7 @@ import { createCloudflareApi } from "./api";
  *   ]
  * });
  */
-export const PermissionGroups = Resource("cloudflare::PermissionGroups", async function (id, options) {
+export const PermissionGroups = Resource("cloudflare::PermissionGroups", async function (id, options = {}) {
     // Only create and update phases are supported
     if (this.phase === "delete") {
         return this.destroy();