alchemy 0.5.2 → 0.7.0

package/lib/cloudflare/zone.js

@@ -57,9 +57,7 @@ import { createCloudflareApi } from "./api";
  */
 export const Zone = Resource("cloudflare::Zone", async function (id, props) {
     // 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) {
             // Delete zone

package/lib/internal/docs/providers.js

@@ -21,13 +21,6 @@ export async function Providers({ srcDir, outDir, filter, parallel = true, }) {
     }))
         .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) => generateProviderDocs({ provider, outDir, parallel })));
     }
@@ -77,7 +70,7 @@ async function generateProviderDocs({ provider, outDir, parallel, }) {
       The ${provider} Service has the following resources:
       ${alchemy.files(files)}
 
-      A file is considered a "Resource" if it contains a const <ResourceName> = Resource(...) call or if it is a function that calls a Resource function, e.g. const TypeScriptFile = () => File(...).
+      A file is considered a "Resource" if it contains a const <ResourceName> = Resource(...) call or if it is a function that calls a Resource function, e.g. const TypeScriptFile = () => File(...), or it is the Workflow or DurableObject classes.
       A file is considered a "Client" if it exposes a wrapper around creating a SDK client or fetch.
       A file is considered a "Utility" if it contains utility functions that are not resources or clients.
       A file is considered a "Types" if it contains just type definitions and maybe helpers around working with those types.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alchemy",
-  "version": "0.5.2",
+  "version": "0.7.0",
   "type": "module",
   "module": "./lib/index.js",
   "scripts": {
@@ -39,6 +39,7 @@
     "@aws-sdk/client-sesv2": "^3.0.0",
     "@aws-sdk/client-sqs": "^3.0.0",
     "@aws-sdk/client-sts": "^3.0.0",
+    "@iarna/toml": "^2.2.5",
     "@octokit/rest": "^21.1.1",
     "ai": "^4.0.0",
     "arktype": "^2.0.0",
@@ -53,6 +54,7 @@
     "prettier": "^3.0.0",
     "stripe": "^17.0.0",
     "turndown": "^7.0.0",
+    "xdg-app-paths": "^8.0.0",
     "yaml": "^2.0.0",
     "zod": "^3.0.0"
   },
@@ -62,6 +64,7 @@
     "@aws-sdk/client-s3": "3.726.1",
     "@biomejs/biome": "^1.9.4",
     "@cloudflare/workers-types": "^4.20250303.0",
+    "@iarna/toml": "^2.2.5",
     "@octokit/rest": "^21.1.1",
     "@types/bun": "latest",
     "@types/diff": "^5.0.0",
@@ -82,6 +85,7 @@
     "vite": "^6.0.7",
     "vitepress": "^1.6.3",
     "wrangler": "^3.114.0",
+    "xdg-app-paths": "^8.3.0",
     "yaml": "^2.7.1"
   }
 }

package/src/cloudflare/account-api-token.ts

@@ -3,7 +3,7 @@ import type { Context } from "../context";
 import { Resource } from "../resource";
 import { Secret } from "../secret";
 import { sha256 } from "../util/sha256";
-import { createCloudflareApi } from "./api";
+import { createCloudflareApi, type CloudflareApiOptions } from "./api";
 
 /**
  * Permission group for a token policy
@@ -63,7 +63,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
    */
@@ -162,6 +162,10 @@ export interface 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
@@ -222,7 +226,7 @@ export const AccountApiToken = Resource(
     props: AccountApiTokenProps
   ): Promise<AccountApiToken> {
     // 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

package/src/cloudflare/account-id.ts

@@ -0,0 +1,12 @@
+import { getCloudflareUserInfo, type CloudflareAuthOptions } from "./auth";
+
+export type CloudflareAccountId = string & {
+  readonly __brand: "CloudflareAccountId";
+};
+
+export async function CloudflareAccountId(
+  options: CloudflareAuthOptions
+): Promise<CloudflareAccountId> {
+  const userInfo = await getCloudflareUserInfo(options);
+  return userInfo.accounts[0].id as CloudflareAccountId;
+}

package/src/cloudflare/api-error.ts

@@ -0,0 +1,58 @@
+/**
+ * Custom error class for Cloudflare API errors
+ * Includes HTTP status information from the Response
+ */
+export 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) {
+    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: Response,
+  action: string,
+  resourceType: string,
+  resourceName: string
+): Promise<never> {
+  const json: any = await response.json();
+  const errors: { message: string }[] = json.errors || [
+    { message: response.statusText },
+  ];
+  const errorMessage = `Error ${action} ${resourceType} '${resourceName}': ${errors[0]?.message || response.statusText}`;
+
+  throw new CloudflareApiError(errorMessage, response, errors);
+}

package/src/cloudflare/api.ts

@@ -1,16 +1,28 @@
 import type { Secret } from "../secret";
 import { withExponentialBackoff } from "../util/retry";
-import { type CloudflareAuthOptions, getCloudflareHeaders } from "./auth";
+import { getCloudflareAuthHeaders, getCloudflareUserInfo } from "./auth";
 
 /**
  * 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
@@ -29,73 +41,6 @@ export interface CloudflareApiOptions {
   email?: string;
 }
 
-/**
- * Account information returned from Cloudflare API
- */
-interface CloudflareAccount {
-  id: string;
-  name: string;
-}
-
-/**
- * Custom error class for Cloudflare API errors
- * Includes HTTP status information from the Response
- */
-export 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) {
-    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: Response,
-  action: string,
-  resourceType: string,
-  resourceName: string
-): Promise<never> {
-  const json: any = await response.json();
-  console.log(json);
-  const errorData: any = json.errors || [{ message: response.statusText }];
-
-  const errorMessage = `Error ${action} ${resourceType} '${resourceName}': ${errorData.errors?.[0]?.message || response.statusText}`;
-
-  throw new CloudflareApiError(errorMessage, response, errorData);
-}
-
 /**
  * Creates a CloudflareApi instance with automatic account ID discovery if not provided
  *
@@ -103,55 +48,25 @@ export async function handleApiError(
  * @returns Promise resolving to a CloudflareApi instance
  */
 export async function createCloudflareApi(
-  options: CloudflareApiOptions = {}
+  options: Partial<CloudflareApiOptions> = {}
 ): Promise<CloudflareApi> {
-  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 type CloudflareAccountId = string & {
-  readonly __brand: "CloudflareAccountId";
-};
-
-export async function CloudflareAccountId(
-  options: CloudflareApiOptions = {}
-): Promise<CloudflareAccountId> {
-  return (options.accountId ||
-    process.env.CLOUDFLARE_ACCOUNT_ID ||
-    (await fetchAccountId())) as CloudflareAccountId;
+  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 */
-  readonly baseUrl: string;
-
-  /** Cloudflare API Key */
-  readonly apiKey: string;
-
-  /** Cloudflare account ID */
-  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: CloudflareAuthOptions;
-
+  public readonly accountId: string;
+  public readonly baseUrl: string;
   /**
    * Create a new Cloudflare API client
    * Use createCloudflareApi factory function instead of direct constructor
@@ -159,43 +74,13 @@ export class CloudflareApi {
    *
    * @param options API options
    */
-  constructor(options: CloudflareApiOptions = {}) {
-    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."
-      );
+  constructor(
+    private readonly options: CloudflareApiOptions & {
+      accountId: string;
     }
-
-    // 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,
-    };
+  ) {
+    this.accountId = options.accountId;
+    this.baseUrl = options.baseUrl ?? "https://api.cloudflare.com/client/v4";
   }
 
   /**
@@ -206,47 +91,36 @@ export class CloudflareApi {
    * @returns Raw Response object from fetch
    */
   async fetch(path: string, init: RequestInit = {}): Promise<Response> {
-    // Get content type from init headers or default to application/json
-    let contentType = "application/json";
-    if (init.headers) {
-      const initHeaders = init.headers as Record<string, string>;
-      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: Record<string, string> = {
-      ...authHeaders,
+    let headers: Record<string, string> = {
+      "Content-Type": "application/json",
     };
-
-    // Add headers from init if provided
-    if (init.headers) {
-      const initHeadersObj = init.headers as Record<string, string>;
-      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;
       });
+    } else if (init.headers) {
+      headers = init.headers;
     }
+    headers = {
+      ...(await getCloudflareAuthHeaders(this.options)),
+      ...headers,
+    };
 
-    // If using FormData, remove Content-Type to let browser set it with boundary
+    // TODO(sam): is this necessary?
     if (init.body instanceof FormData) {
-      delete combinedHeaders["Content-Type"];
+      delete headers["Content-Type"];
     }
 
-    const url = `${this.baseUrl}${path}`;
-
     // Use withExponentialBackoff for automatic retry on network errors
     return withExponentialBackoff(
       () =>
-        fetch(url, {
+        fetch(`${this.baseUrl}${path}`, {
           ...init,
-          headers: combinedHeaders,
+          headers,
         }),
       (error) => {
         // Only retry on network-related errors
@@ -328,43 +202,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(): Promise<string> {
-  // 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: any = await response.json().catch(() => ({
-      errors: [{ message: response.statusText }],
-    }));
-
-    throw new Error(
-      `Error fetching Cloudflare accounts: ${errorData.errors?.[0]?.message || response.statusText}`
-    );
-  }
-
-  const data: any = await response.json();
-  const accounts = data.result as CloudflareAccount[];
-
-  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;
-}