alchemy 0.5.1 → 0.6.0

package/lib/cloudflare/account-api-token.d.ts

@@ -1,6 +1,7 @@
 import type { Context } from "../context";
 import { Resource } from "../resource";
 import { Secret } from "../secret";
+import { type CloudflareApiOptions } from "./api";
 /**
  * Permission group for a token policy
  */
@@ -52,7 +53,7 @@ export interface TokenCondition {
 /**
  * Properties for creating or updating an Account API Token
  */
-export interface AccountApiTokenProps {
+export interface AccountApiTokenProps extends CloudflareApiOptions {
     /**
      * Name of the token
      */
@@ -113,6 +114,10 @@ export interface AccountApiToken extends Resource<"cloudflare::AccountApiToken">
 /**
  * Creates a Cloudflare Account API Token with specified permissions.
  *
+ * Note: Requires a Cloudflare API Key or Token with admin-level account access.
+ * The OAuth token from `wrangler login` is NOT sufficient for this operation.
+ * You must use an API token with permission to manage account API tokens.
+ *
  * @see https://developers.cloudflare.com/api/resources/accounts/subresources/tokens/methods/create/
  *
  * @example

package/lib/cloudflare/account-api-token.js

@@ -6,6 +6,10 @@ import { createCloudflareApi } from "./api";
 /**
  * Creates a Cloudflare Account API Token with specified permissions.
  *
+ * Note: Requires a Cloudflare API Key or Token with admin-level account access.
+ * The OAuth token from `wrangler login` is NOT sufficient for this operation.
+ * You must use an API token with permission to manage account API tokens.
+ *
  * @see https://developers.cloudflare.com/api/resources/accounts/subresources/tokens/methods/create/
  *
  * @example
@@ -60,7 +64,7 @@ import { createCloudflareApi } from "./api";
  */
 export const AccountApiToken = Resource("cloudflare::AccountApiToken", 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") {
         // Delete token if we have an ID
         if (this.output?.id) {

package/lib/cloudflare/account-id.d.ts

@@ -1 +1,5 @@
-export {};
+import { type CloudflareAuthOptions } from "./auth";
+export type CloudflareAccountId = string & {
+    readonly __brand: "CloudflareAccountId";
+};
+export declare function CloudflareAccountId(options: CloudflareAuthOptions): Promise<CloudflareAccountId>;

package/lib/cloudflare/account-id.js

@@ -0,0 +1,5 @@
+import { getCloudflareUserInfo } from "./auth";
+export async function CloudflareAccountId(options) {
+    const userInfo = await getCloudflareUserInfo(options);
+    return userInfo.accounts[0].id;
+}

package/lib/cloudflare/api-error.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Custom error class for Cloudflare API errors
+ * Includes HTTP status information from the Response
+ */
+export declare class CloudflareApiError extends Error {
+    /**
+     * HTTP status code
+     */
+    status: number;
+    /**
+     * HTTP status text
+     */
+    statusText: string;
+    /**
+     * Raw error data from the API
+     */
+    errorData?: any;
+    /**
+     * Create a new CloudflareApiError
+     */
+    constructor(message: string, response: Response, errorData?: any);
+}
+/**
+ * Helper function to handle API errors
+ *
+ * @param response The fetch Response object
+ * @param action The action being performed (e.g., "creating", "deleting")
+ * @param resourceType The type of resource being acted upon (e.g., "R2 bucket", "Worker")
+ * @param resourceName The name/identifier of the specific resource
+ * @returns Never returns - always throws an error
+ */
+export declare function handleApiError(response: Response, action: string, resourceType: string, resourceName: string): Promise<never>;

package/lib/cloudflare/api-error.js

@@ -0,0 +1,47 @@
+/**
+ * Custom error class for Cloudflare API errors
+ * Includes HTTP status information from the Response
+ */
+export class CloudflareApiError extends Error {
+    /**
+     * HTTP status code
+     */
+    status;
+    /**
+     * HTTP status text
+     */
+    statusText;
+    /**
+     * Raw error data from the API
+     */
+    errorData;
+    /**
+     * Create a new CloudflareApiError
+     */
+    constructor(message, response, errorData) {
+        super(message);
+        this.name = "CloudflareApiError";
+        this.status = response.status;
+        this.statusText = response.statusText;
+        this.errorData = errorData;
+        // Ensure instanceof works correctly
+        Object.setPrototypeOf(this, CloudflareApiError.prototype);
+    }
+}
+/**
+ * Helper function to handle API errors
+ *
+ * @param response The fetch Response object
+ * @param action The action being performed (e.g., "creating", "deleting")
+ * @param resourceType The type of resource being acted upon (e.g., "R2 bucket", "Worker")
+ * @param resourceName The name/identifier of the specific resource
+ * @returns Never returns - always throws an error
+ */
+export async function handleApiError(response, action, resourceType, resourceName) {
+    const json = await response.json();
+    const errors = json.errors || [
+        { message: response.statusText },
+    ];
+    const errorMessage = `Error ${action} ${resourceType} '${resourceName}': ${errors[0]?.message || response.statusText}`;
+    throw new CloudflareApiError(errorMessage, response, errors);
+}

package/lib/cloudflare/api.d.ts

@@ -3,10 +3,20 @@ import type { Secret } from "../secret";
  * Options for Cloudflare API requests
  */
 export interface CloudflareApiOptions {
+    /**
+     * Base URL for Cloudflare API
+     *
+     * @default https://api.cloudflare.com/client/v4
+     */
+    baseUrl?: string;
     /**
      * API Key to use (overrides CLOUDFLARE_API_KEY env var)
      */
     apiKey?: Secret;
+    /**
+     * API Token to use (overrides CLOUDFLARE_API_TOKEN env var)
+     */
+    apiToken?: Secret;
     /**
      * Account ID to use (overrides CLOUDFLARE_ACCOUNT_ID env var)
      * If not provided, will be automatically retrieved from the Cloudflare API
@@ -22,65 +32,20 @@ export interface CloudflareApiOptions {
      */
     email?: string;
 }
-/**
- * Custom error class for Cloudflare API errors
- * Includes HTTP status information from the Response
- */
-export declare class CloudflareApiError extends Error {
-    /**
-     * HTTP status code
-     */
-    status: number;
-    /**
-     * HTTP status text
-     */
-    statusText: string;
-    /**
-     * Raw error data from the API
-     */
-    errorData?: any;
-    /**
-     * Create a new CloudflareApiError
-     */
-    constructor(message: string, response: Response, errorData?: any);
-}
-/**
- * Helper function to handle API errors
- *
- * @param response The fetch Response object
- * @param action The action being performed (e.g., "creating", "deleting")
- * @param resourceType The type of resource being acted upon (e.g., "R2 bucket", "Worker")
- * @param resourceName The name/identifier of the specific resource
- * @returns Never returns - always throws an error
- */
-export declare function handleApiError(response: Response, action: string, resourceType: string, resourceName: string): Promise<never>;
 /**
  * Creates a CloudflareApi instance with automatic account ID discovery if not provided
  *
  * @param options API options
  * @returns Promise resolving to a CloudflareApi instance
  */
-export declare function createCloudflareApi(options?: CloudflareApiOptions): Promise<CloudflareApi>;
-export type CloudflareAccountId = string & {
-    readonly __brand: "CloudflareAccountId";
-};
-export declare function CloudflareAccountId(options?: CloudflareApiOptions): Promise<CloudflareAccountId>;
+export declare function createCloudflareApi(options?: Partial<CloudflareApiOptions>): Promise<CloudflareApi>;
 /**
  * Cloudflare API client using raw fetch
  */
 export declare class CloudflareApi {
-    /** Base URL for Cloudflare API */
-    readonly baseUrl: string;
-    /** Cloudflare API Key */
-    readonly apiKey: string;
-    /** Cloudflare account ID */
+    private readonly options;
     readonly accountId: string;
-    /** Cloudflare zone ID (if provided) */
-    readonly zoneId: string | null;
-    /** User email (when using API Key auth) */
-    readonly email?: string;
-    /** Auth options for making requests */
-    private readonly authOptions;
+    readonly baseUrl: string;
     /**
      * Create a new Cloudflare API client
      * Use createCloudflareApi factory function instead of direct constructor
@@ -88,7 +53,9 @@ export declare class CloudflareApi {
      *
      * @param options API options
      */
-    constructor(options?: CloudflareApiOptions);
+    constructor(options: CloudflareApiOptions & {
+        accountId: string;
+    });
     /**
      * Make a fetch request to the Cloudflare API
      *

package/lib/cloudflare/api.js

@@ -1,50 +1,5 @@
-import { getCloudflareHeaders } from "./auth";
-/**
- * Custom error class for Cloudflare API errors
- * Includes HTTP status information from the Response
- */
-export class CloudflareApiError extends Error {
-    /**
-     * HTTP status code
-     */
-    status;
-    /**
-     * HTTP status text
-     */
-    statusText;
-    /**
-     * Raw error data from the API
-     */
-    errorData;
-    /**
-     * Create a new CloudflareApiError
-     */
-    constructor(message, response, errorData) {
-        super(message);
-        this.name = "CloudflareApiError";
-        this.status = response.status;
-        this.statusText = response.statusText;
-        this.errorData = errorData;
-        // Ensure instanceof works correctly
-        Object.setPrototypeOf(this, CloudflareApiError.prototype);
-    }
-}
-/**
- * Helper function to handle API errors
- *
- * @param response The fetch Response object
- * @param action The action being performed (e.g., "creating", "deleting")
- * @param resourceType The type of resource being acted upon (e.g., "R2 bucket", "Worker")
- * @param resourceName The name/identifier of the specific resource
- * @returns Never returns - always throws an error
- */
-export async function handleApiError(response, action, resourceType, resourceName) {
-    const json = await response.json();
-    console.log(json);
-    const errorData = json.errors || [{ message: response.statusText }];
-    const errorMessage = `Error ${action} ${resourceType} '${resourceName}': ${errorData.errors?.[0]?.message || response.statusText}`;
-    throw new CloudflareApiError(errorMessage, response, errorData);
-}
+import { withExponentialBackoff } from "../util/retry";
+import { getCloudflareAuthHeaders, getCloudflareUserInfo } from "./auth";
 /**
  * Creates a CloudflareApi instance with automatic account ID discovery if not provided
  *
@@ -52,38 +7,23 @@ export async function handleApiError(response, action, resourceType, resourceNam
  * @returns Promise resolving to a CloudflareApi instance
  */
 export async function createCloudflareApi(options = {}) {
-    try {
-        return new CloudflareApi({
-            ...options,
-            accountId: await CloudflareAccountId(options),
-        });
-    }
-    catch (error) {
-        console.error("Error during Cloudflare account ID discovery:", error);
-        throw new Error("Failed to automatically discover Cloudflare account ID. Please provide an account ID explicitly or ensure your API token/key has sufficient permissions.");
-    }
-}
-export async function CloudflareAccountId(options = {}) {
-    return (options.accountId ||
-        process.env.CLOUDFLARE_ACCOUNT_ID ||
-        (await fetchAccountId()));
+    const userInfo = await getCloudflareUserInfo(options);
+    return new CloudflareApi({
+        baseUrl: options.baseUrl,
+        accountId: options.accountId ?? userInfo.accounts[0].id,
+        email: userInfo.email,
+        apiKey: userInfo.apiKey,
+        apiToken: userInfo.apiToken,
+        zoneId: options.zoneId,
+    });
 }
 /**
  * Cloudflare API client using raw fetch
  */
 export class CloudflareApi {
-    /** Base URL for Cloudflare API */
-    baseUrl;
-    /** Cloudflare API Key */
-    apiKey;
-    /** Cloudflare account ID */
+    options;
     accountId;
-    /** Cloudflare zone ID (if provided) */
-    zoneId;
-    /** User email (when using API Key auth) */
-    email;
-    /** Auth options for making requests */
-    authOptions;
+    baseUrl;
     /**
      * Create a new Cloudflare API client
      * Use createCloudflareApi factory function instead of direct constructor
@@ -91,31 +31,10 @@ export class CloudflareApi {
      *
      * @param options API options
      */
-    constructor(options = {}) {
-        this.baseUrl = "https://api.cloudflare.com/client/v4";
-        const apiKey = options.apiKey?.unencrypted ||
-            process.env.CLOUDFLARE_API_KEY ||
-            undefined;
-        if (!apiKey) {
-            throw new Error("No API key provided. Use createCloudflareApi() instead for automatic account discovery.");
-        }
-        this.apiKey = apiKey;
-        this.email = options.email || process.env.CLOUDFLARE_EMAIL;
-        if (!this.email) {
-            throw new Error("No email provided. Use createCloudflareApi() instead for automatic account discovery.");
-        }
-        // Get account ID from options or environment
-        this.accountId =
-            options.accountId || process.env.CLOUDFLARE_ACCOUNT_ID || "";
-        if (!this.accountId) {
-            throw new Error("No account ID provided. Use createCloudflareApi() instead for automatic account discovery.");
-        }
-        // Zone ID is optional for some operations
-        this.zoneId = options.zoneId || process.env.CLOUDFLARE_ZONE_ID || null;
-        // Store auth options for later use
-        this.authOptions = {
-            email: this.email,
-        };
+    constructor(options) {
+        this.options = options;
+        this.accountId = options.accountId;
+        this.baseUrl = options.baseUrl ?? "https://api.cloudflare.com/client/v4";
     }
     /**
      * Make a fetch request to the Cloudflare API
@@ -125,37 +44,45 @@ export class CloudflareApi {
      * @returns Raw Response object from fetch
      */
     async fetch(path, init = {}) {
-        // Get content type from init headers or default to application/json
-        let contentType = "application/json";
-        if (init.headers) {
-            const initHeaders = init.headers;
-            if (initHeaders["Content-Type"]) {
-                contentType = initHeaders["Content-Type"];
-            }
-        }
-        // Get auth headers (async now)
-        const authHeaders = await getCloudflareHeaders(contentType, this.authOptions);
-        // Combine all headers
-        const combinedHeaders = {
-            ...authHeaders,
+        let headers = {
+            "Content-Type": "application/json",
         };
-        // Add headers from init if provided
-        if (init.headers) {
-            const initHeadersObj = init.headers;
-            Object.keys(initHeadersObj).forEach((key) => {
-                combinedHeaders[key] = initHeadersObj[key];
+        if (Array.isArray(init.headers)) {
+            init.headers.forEach(([key, value]) => {
+                headers[key] = value;
+            });
+        }
+        else if (init.headers instanceof Headers) {
+            init.headers.forEach((value, key) => {
+                headers[key] = value;
             });
         }
-        // If using FormData, remove Content-Type to let browser set it with boundary
+        else if (init.headers) {
+            headers = init.headers;
+        }
+        headers = {
+            ...(await getCloudflareAuthHeaders(this.options)),
+            ...headers,
+        };
+        // TODO(sam): is this necessary?
         if (init.body instanceof FormData) {
-            delete combinedHeaders["Content-Type"];
+            delete headers["Content-Type"];
         }
-        const url = `${this.baseUrl}${path}`;
-        // Make the request
-        return fetch(url, {
+        // Use withExponentialBackoff for automatic retry on network errors
+        return withExponentialBackoff(() => fetch(`${this.baseUrl}${path}`, {
             ...init,
-            headers: combinedHeaders,
-        });
+            headers,
+        }), (error) => {
+            // Only retry on network-related errors
+            const errorMsg = error.message || "";
+            const isNetworkError = errorMsg.includes("socket connection was closed") ||
+                errorMsg.includes("ECONNRESET") ||
+                errorMsg.includes("ETIMEDOUT") ||
+                errorMsg.includes("ECONNREFUSED");
+            return isNetworkError;
+        }, 5, // Maximum 5 attempts (1 initial + 4 retries)
+        1000 // Start with 1s delay, will exponentially increase
+        );
     }
     /**
      * Helper for GET requests
@@ -204,31 +131,3 @@ export class CloudflareApi {
         return this.fetch(path, { ...init, method: "DELETE" });
     }
 }
-/**
- * Create a temporary API client for bootstrapping
- * This client can only be used to fetch the account ID
- */
-async function fetchAccountId() {
-    // Create a minimal API client for bootstrapping
-    const baseUrl = "https://api.cloudflare.com/client/v4";
-    // Get content type and auth headers
-    const authHeaders = await getCloudflareHeaders("application/json");
-    // Make the request to get accounts
-    const response = await fetch(`${baseUrl}/accounts`, {
-        method: "GET",
-        headers: authHeaders,
-    });
-    if (!response.ok) {
-        const errorData = await response.json().catch(() => ({
-            errors: [{ message: response.statusText }],
-        }));
-        throw new Error(`Error fetching Cloudflare accounts: ${errorData.errors?.[0]?.message || response.statusText}`);
-    }
-    const data = await response.json();
-    const accounts = data.result;
-    if (!accounts || accounts.length === 0) {
-        throw new Error("No Cloudflare accounts found. Check your API token/key permissions.");
-    }
-    // Return the first account ID
-    return accounts[0].id;
-}

package/lib/cloudflare/auth.d.ts

@@ -1,51 +1,68 @@
+import type { Secret } from "../secret";
+import type { CloudflareAccountId } from "./account-id";
 /**
  * Authentication options for Cloudflare API
  */
 export interface CloudflareAuthOptions {
     /**
-     * If true, throw an error when no authentication is found
-     * @default true
+     * API Key to use with API Key
      */
-    required?: boolean;
+    apiKey?: Secret;
+    /**
+     * API Token to use with API Key
+     */
+    apiToken?: Secret;
     /**
      * Email to use with API Key
      * If not provided, will attempt to discover from Cloudflare API
      */
     email?: string;
 }
-/**
- * Authentication headers for Cloudflare API
- */
-export interface CloudflareAuthHeaders {
-    /**
-     * Authentication headers to use with fetch
-     */
-    headers: Record<string, string>;
-    /**
-     * Type of authentication being used
-     */
-    type: "token" | "key" | "none";
-    /**
-     * User email (only present when using API Key auth)
-     */
-    email?: string;
+export interface CloudflareAccount {
+    name: string;
+    id: CloudflareAccountId;
+    type: "standard" | "zero_rating" | "full_control";
+    settings: {
+        enforce_twofactor: boolean;
+        api_access_enabled: null;
+        access_approval_expiry: null;
+        abuse_contact_email: null;
+    };
+    legacy_flags: {
+        enterprise_zone_quota: {
+            maximum: number;
+            current: number;
+            available: number;
+        };
+    };
 }
-/**
- * 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 declare function getCloudflareAuth(options?: CloudflareAuthOptions): Promise<CloudflareAuthHeaders>;
-/**
- * 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 declare function getCloudflareHeaders(contentType?: string, options?: CloudflareAuthOptions): Promise<Record<string, string>>;
+export interface CloudflareUserInfo {
+    apiToken?: Secret;
+    apiKey?: Secret;
+    email: string;
+    username: string;
+    accounts: CloudflareAccount[];
+    organizations: CloudflareOrganization[];
+    tokenPermissions: string[] | undefined;
+    first_name: string | null;
+    last_name: string | null;
+    telephone: string | null;
+    country: string | null;
+    zipcode: string | null;
+    two_factor_authentication_enabled: boolean;
+    two_factor_authentication_locked: boolean;
+    has_pro_zones: boolean;
+    has_business_zones: boolean;
+    has_enterprise_zones: boolean;
+    suspended: boolean;
+    betas: string[];
+}
+export interface CloudflareOrganization {
+    id: string;
+    name: string;
+    status: string;
+    permissions: string[];
+    roles: string[];
+}
+export declare function getCloudflareUserInfo(options: CloudflareAuthOptions): Promise<CloudflareUserInfo>;
+export declare function getCloudflareAuthHeaders(options?: CloudflareAuthOptions): Promise<Record<string, string>>;