alchemy 0.3.1 → 0.4.0

package/src/cloudflare/custom-domain.ts

@@ -0,0 +1,318 @@
+import type { Context } from "../context";
+import { Resource } from "../resource";
+import { CloudflareApi, createCloudflareApi, handleApiError } from "./api";
+
+/**
+ * Properties for creating or updating a CustomDomain
+ */
+export interface CustomDomainProps {
+  /**
+   * The domain name to bind to the worker
+   */
+  name: string;
+
+  /**
+   * Cloudflare Zone ID for the domain
+   */
+  zoneId: string;
+
+  /**
+   * Name of the worker to bind to the domain
+   */
+  workerName: string;
+
+  /**
+   * Worker environment (defaults to production)
+   * @default "production"
+   */
+  environment?: string;
+}
+
+/**
+ * Cloudflare Domain object structure from API
+ */
+interface CloudflareDomain {
+  id: string;
+  zone_id: string;
+  zone_name: string;
+  hostname: string;
+  service: string;
+  environment: string;
+}
+
+/**
+ * Output returned after CustomDomain creation/update
+ */
+export interface CustomDomain
+  extends Resource<"cloudflare::CustomDomain">,
+    CustomDomainProps {
+  /**
+   * The unique identifier for the Cloudflare domain binding.
+   */
+  id: string;
+
+  /**
+   * Time at which the domain binding was created (approximated if not returned by API)
+   */
+  createdAt: number;
+
+  /**
+   * Time at which the domain binding was last updated
+   */
+  updatedAt: number;
+}
+
+/**
+ * Configure custom domain for a Cloudflare Worker using the Cloudflare Custom Domains API
+ * This attaches a worker (either a standard Worker or the one backing a StaticSite)
+ * to a specific hostname within a zone.
+ *
+ * @example
+ * // Bind a domain to a standard Cloudflare Worker
+ * const apiWorker = await Worker("api", {
+ *   name: "my-api-worker",
+ *   entrypoint: "./src/api-worker.ts"
+ * });
+ *
+ * const apiDomain = await CustomDomain("api-domain-binding", {
+ *   name: "api.example.com",
+ *   zoneId: "YOUR_ZONE_ID", // Replace with actual Zone ID
+ *   workerName: apiWorker.name // Use the name from the Worker resource
+ * });
+ *
+ * @example
+ * // Bind a domain to a Cloudflare Static Site
+ * const mySite = await StaticSite("landing-page", {
+ *   name: "my-landing-page-site", // This becomes the underlying worker name
+ *   dir: "./dist/landing-page"
+ * });
+ *
+ * const siteDomain = await CustomDomain("site-domain-binding", {
+ *   name: "www.example.com",
+ *   zoneId: "YOUR_ZONE_ID", // Replace with actual Zone ID
+ *   workerName: mySite.name // Use the name from the StaticSite resource
+ * });
+ *
+ * @see https://developers.cloudflare.com/api/resources/workers/subresources/domains/
+ */
+export const CustomDomain = Resource(
+  "cloudflare::CustomDomain",
+  async function (
+    this: Context<CustomDomain>,
+    logicalId: string, // Changed param name from id to logicalId for clarity
+    props: CustomDomainProps
+  ): Promise<CustomDomain> {
+    // Create Cloudflare API client with automatic account discovery
+    const api = await createCloudflareApi();
+
+    // Validate required properties
+    if (!props.name) {
+      throw new Error("Domain name (props.name) is required");
+    }
+    if (!props.zoneId) {
+      throw new Error("Zone ID (props.zoneId) is required");
+    }
+    if (!props.workerName) {
+      throw new Error("Worker name (props.workerName) is required");
+    }
+
+    if (this.phase === "delete") {
+      await deleteCustomDomain(this, api, logicalId, props);
+      return this.destroy();
+    } else {
+      // Create or Update phase
+      return await ensureCustomDomain(this, api, logicalId, props);
+    }
+  }
+);
+
+// Helper function to delete the custom domain binding
+async function deleteCustomDomain(
+  context: Context<CustomDomain>,
+  api: CloudflareApi,
+  logicalId: string,
+  props: CustomDomainProps
+): Promise<void> {
+  const domainHostname = props.name;
+  const domainIdToDelete = context.output?.id;
+
+  if (!domainIdToDelete) {
+    console.warn(
+      `Cannot delete CustomDomain ${logicalId} (${domainHostname}): Missing domain ID in state. Assuming already deleted.`
+    );
+    return; // Exit early if no ID
+  }
+
+  console.log(
+    `Deleting CustomDomain binding ${domainIdToDelete} for ${domainHostname}`
+  );
+  const response = await api.delete(
+    `/accounts/${api.accountId}/workers/domains/${domainIdToDelete}`
+  );
+
+  console.log(
+    `Delete result for ${domainIdToDelete} (${domainHostname}):`,
+    response.status,
+    response.statusText
+  );
+
+  // 404 is acceptable during deletion for idempotency
+  if (!response.ok && response.status !== 404) {
+    await handleApiError(
+      response,
+      "deleting",
+      "custom domain binding",
+      domainIdToDelete
+    );
+    // Throw after handling to ensure failure is reported
+    throw new Error(
+      `Failed to delete custom domain binding ${domainIdToDelete}: ${response.statusText}`
+    );
+  }
+}
+
+// Helper function to create or update the custom domain binding
+async function ensureCustomDomain(
+  context: Context<CustomDomain>,
+  api: CloudflareApi,
+  logicalId: string,
+  props: CustomDomainProps
+): Promise<CustomDomain> {
+  const environment = props.environment || "production";
+  const domainHostname = props.name;
+
+  // Check if domain binding already exists for this account
+  console.log(`Checking existing domain bindings for account ${api.accountId}`);
+  const listResponse = await api.get(
+    `/accounts/${api.accountId}/workers/domains`
+  );
+
+  if (!listResponse.ok) {
+    // Fix: Added the 4th argument (resource identifier/context)
+    await handleApiError(
+      listResponse,
+      "listing",
+      "worker domains",
+      `Account ${api.accountId}`
+    );
+    // If listing fails, we cannot proceed reliably
+    throw new Error(
+      `Failed to list worker domains for account ${api.accountId}: ${listResponse.statusText}`
+    );
+  }
+
+  const listData = (await listResponse.json()) as {
+    result?: CloudflareDomain[];
+    success: boolean;
+  };
+
+  if (!listData.success || !listData.result) {
+    throw new Error(
+      `Failed to parse list worker domains response: ${JSON.stringify(listData)}`
+    );
+  }
+
+  // Find the specific binding by hostname AND zoneId
+  const existingBinding = listData.result.find(
+    (b) => b.hostname === domainHostname && b.zone_id === props.zoneId
+  );
+
+  let currentDomainId = existingBinding?.id;
+  const bindingExists = !!existingBinding;
+
+  console.log(
+    `Domain binding status for ${domainHostname} (Zone: ${props.zoneId}):`,
+    bindingExists
+      ? `Found (ID: ${currentDomainId}, Worker: ${existingBinding.service}, Env: ${existingBinding.environment})`
+      : "Not found"
+  );
+
+  // Determine if we need to update (binding exists but has different service or environment)
+  const needsUpdate =
+    bindingExists &&
+    (existingBinding.service !== props.workerName ||
+      existingBinding.environment !== environment);
+
+  let operationPerformed: "create" | "update" | "none" = "none";
+  let resultantBinding: CloudflareDomain | undefined = existingBinding;
+
+  // Create or Update the binding using PUT
+  // Cloudflare's PUT /accounts/{account_id}/workers/domains acts as an upsert
+  if (!bindingExists || needsUpdate) {
+    operationPerformed = bindingExists ? "update" : "create";
+    console.log(
+      `${operationPerformed === "update" ? "Updating" : "Creating"} domain binding: ${domainHostname} (Zone: ${props.zoneId}) → ${props.workerName}:${environment}`
+    );
+
+    const putPayload = {
+      zone_id: props.zoneId,
+      hostname: domainHostname,
+      service: props.workerName,
+      environment: environment,
+    };
+
+    const putResponse = await api.put(
+      `/accounts/${api.accountId}/workers/domains`,
+      putPayload
+    );
+
+    if (!putResponse.ok) {
+      await handleApiError(
+        putResponse,
+        operationPerformed === "update" ? "updating" : "creating",
+        "custom domain binding",
+        domainHostname
+      );
+      // Throw after handling to prevent inconsistent state
+      throw new Error(
+        `Failed to ${operationPerformed} custom domain binding: ${putResponse.statusText}`
+      );
+    }
+
+    const putResult = (await putResponse.json()) as {
+      result?: CloudflareDomain;
+      success: boolean;
+    };
+
+    if (!putResult.success || !putResult.result) {
+      throw new Error(
+        `Failed to parse ${operationPerformed} domain binding response: ${JSON.stringify(putResult)}`
+      );
+    }
+
+    resultantBinding = putResult.result;
+    currentDomainId = resultantBinding.id; // Update ID from the PUT response
+    console.log(
+      `Successfully ${operationPerformed}d binding, new ID: ${currentDomainId}`
+    );
+  } else {
+    console.log(
+      `Domain binding already exists and is up to date: ${domainHostname} (ID: ${currentDomainId}) → ${props.workerName}:${environment}`
+    );
+  }
+
+  // Ensure we have the final binding details
+  if (!resultantBinding || !currentDomainId) {
+    // This case should ideally not happen if API calls succeed
+    console.error("Error: Could not determine final domain binding state.", {
+      existingBinding,
+      resultantBinding,
+      currentDomainId,
+    });
+    throw new Error(
+      `Failed to get final state for custom domain ${domainHostname}`
+    );
+  }
+
+  const now = Date.now();
+
+  // Construct the output state
+  return context({
+    ...props, // Include all input props
+    id: currentDomainId, // Use the definitive ID
+    environment: resultantBinding.environment, // Use actual environment from CF
+    createdAt: context.output?.createdAt || now, // Preserve create time or set new
+    updatedAt:
+      operationPerformed !== "none" ? now : context.output?.updatedAt || now, // Update time only if changed
+  });
+}

package/src/cloudflare/{dns.ts → dns-records.ts}

@@ -124,7 +124,7 @@ export const DnsRecords = Resource(
   async function (
     this: Context<DnsRecords>,
     id: string,
-    props: DnsRecordsProps,
+    props: DnsRecordsProps
   ): Promise<DnsRecords> {
     // Create Cloudflare API client
     const api = await createCloudflareApi();
@@ -139,17 +139,17 @@ export const DnsRecords = Resource(
           this.output.records.map(async (record) => {
             try {
               const response = await api.delete(
-                `/zones/${zoneId}/dns_records/${record.id}`,
+                `/zones/${zoneId}/dns_records/${record.id}`
               );
               if (!response.ok && response.status !== 404) {
                 console.error(
-                  `Failed to delete DNS record ${record.name}: ${response.statusText}`,
+                  `Failed to delete DNS record ${record.name}: ${response.statusText}`
                 );
               }
             } catch (error) {
               console.error(`Error deleting DNS record ${record.name}:`, error);
             }
-          }),
+          })
         );
       }
       return this.destroy();
@@ -165,8 +165,8 @@ export const DnsRecords = Resource(
         (current) =>
           !desiredRecords.some(
             (desired) =>
-              desired.name === current.name && desired.type === current.type,
-          ),
+              desired.name === current.name && desired.type === current.type
+          )
       );
 
       // Delete orphaned records
@@ -174,17 +174,17 @@ export const DnsRecords = Resource(
         recordsToDelete.map(async (record) => {
           try {
             const response = await api.delete(
-              `/zones/${zoneId}/dns_records/${record.id}`,
+              `/zones/${zoneId}/dns_records/${record.id}`
             );
             if (!response.ok && response.status !== 404) {
               console.error(
-                `Failed to delete DNS record ${record.name}: ${response.statusText}`,
+                `Failed to delete DNS record ${record.name}: ${response.statusText}`
               );
             }
           } catch (error) {
             console.error(`Error deleting DNS record ${record.name}:`, error);
           }
-        }),
+        })
       );
 
       // Update or create records
@@ -193,7 +193,7 @@ export const DnsRecords = Resource(
           // Find matching existing record
           const existing = currentRecords.find(
             (current) =>
-              current.name === desired.name && current.type === desired.type,
+              current.name === desired.name && current.type === desired.type
           );
 
           if (existing) {
@@ -212,7 +212,7 @@ export const DnsRecords = Resource(
             // Create new record
             return createOrUpdateRecord(api, zoneId, desired);
           }
-        }),
+        })
       );
 
       return this({
@@ -224,22 +224,36 @@ export const DnsRecords = Resource(
     // Create new records
     const uniqueRecords = props.records.reduce(
       (acc, record) => {
-        const key = `${record.name}-${record.type}`;
+        // For record types that can have multiple entries with the same name (MX, TXT, NS, etc.),
+        // include content and/or priority in the key to avoid deduplication
+        let key = `${record.name}-${record.type}`;
+
+        // If it's a record type that can have multiple entries with the same name, make the key unique
+        if (["MX", "TXT", "NS", "SRV", "CAA"].includes(record.type)) {
+          // For MX, include priority in the key
+          if (record.type === "MX" || record.type === "SRV") {
+            key = `${key}-${record.priority}-${record.content}`;
+          } else {
+            // For other multi-record types, content is the differentiator
+            key = `${key}-${record.content}`;
+          }
+        }
+
         acc[key] = record;
         return acc;
       },
-      {} as Record<string, DnsRecordProps>,
+      {} as Record<string, DnsRecordProps>
     );
 
     const createdRecords = await Promise.all(
       Object.values(uniqueRecords).map(async (record) => {
         // First check if record exists
         const listResponse = await api.get(
-          `/zones/${zoneId}/dns_records?type=${record.type}&name=${record.name}`,
+          `/zones/${zoneId}/dns_records?type=${record.type}&name=${record.name}`
         );
         if (!listResponse.ok) {
           throw new Error(
-            `Failed to check existing DNS records: ${listResponse.statusText}`,
+            `Failed to check existing DNS records: ${listResponse.statusText}`
           );
         }
 
@@ -249,14 +263,14 @@ export const DnsRecords = Resource(
         const existingRecord = listResult.result[0];
 
         return createOrUpdateRecord(api, zoneId, record, existingRecord?.id);
-      }),
+      })
     );
 
     return this({
       zoneId,
       records: createdRecords,
     });
-  },
+  }
 );
 
 /**
@@ -266,7 +280,7 @@ async function createOrUpdateRecord(
   api: CloudflareApi,
   zoneId: string,
   record: DnsRecordProps,
-  existingId?: string,
+  existingId?: string
 ): Promise<DnsRecord> {
   const payload = getRecordPayload(record);
 
@@ -282,12 +296,12 @@ async function createOrUpdateRecord(
       try {
         const createResponse = await api.post(
           `/zones/${zoneId}/dns_records`,
-          payload,
+          payload
         );
         if (createResponse.ok) {
           return convertCloudflareRecord(
             ((await createResponse.json()) as any).result,
-            zoneId,
+            zoneId
           );
         }
       } catch (err) {
@@ -296,7 +310,7 @@ async function createOrUpdateRecord(
     }
 
     throw new Error(
-      `Failed to ${existingId ? "update" : "create"} DNS record ${record.name}: ${response.statusText}\nResponse: ${errorBody}`,
+      `Failed to ${existingId ? "update" : "create"} DNS record ${record.name}: ${response.statusText}\nResponse: ${errorBody}`
     );
   }
 
@@ -325,7 +339,7 @@ function getRecordPayload(record: DnsRecordProps) {
  */
 function convertCloudflareRecord(
   record: CloudflareDnsRecord,
-  zoneId: string,
+  zoneId: string
 ): DnsRecord {
   return {
     id: record.id,

package/src/cloudflare/index.ts

@@ -1,8 +1,12 @@
+export * from "./account-api-token";
+export * from "./api";
 export * from "./bindings";
 export * from "./bucket";
-export * from "./dns";
+export * from "./custom-domain";
+export * from "./dns-records";
 export * from "./durable-object-namespace";
 export * from "./kv-namespace";
+export * from "./permission-groups";
 export * from "./r2-rest-state-store";
 export * from "./static-site";
 export * from "./worker";

package/src/cloudflare/permission-groups.ts

@@ -0,0 +1,137 @@
+import type { Context } from "../context";
+import { Resource } from "../resource";
+import { createCloudflareApi, type CloudflareApiOptions } from "./api";
+
+/**
+ * Cloudflare permission group as returned by the API
+ */
+export interface PermissionGroup {
+  /**
+   * Unique identifier for the permission group
+   */
+  id: string;
+
+  /**
+   * Human-readable name of the permission group
+   */
+  name: string;
+
+  /**
+   * Scopes included in this permission group
+   */
+  scopes: string[];
+}
+
+/**
+ * Response from the Cloudflare permission groups API
+ */
+interface PermissionGroupsResponse {
+  result: PermissionGroup[];
+  success: boolean;
+  errors: any[];
+  messages: any[];
+}
+
+/**
+ * All Cloudflare permission groups mapped by name to ID
+ *
+ * @see https://developers.cloudflare.com/r2/api/tokens/#permissions
+ */
+export type PermissionGroups = Resource<"cloudflare::PermissionGroups"> & {
+  /**
+   * Admin Read & Write - Allows create, list, delete buckets and edit bucket configurations
+   * plus list, write, and read object access
+   */
+  "Workers R2 Storage Write": PermissionGroup;
+
+  /**
+   * Admin Read only - Allows list buckets and view bucket configuration
+   * plus list and read object access
+   */
+  "Workers R2 Storage Read": PermissionGroup;
+
+  /**
+   * Object Read & Write - Allows read, write, and list objects in specific buckets
+   */
+  "Workers R2 Storage Bucket Item Write": PermissionGroup;
+
+  /**
+   * Object Read only - Allows read and list objects in specific buckets
+   */
+  "Workers R2 Storage Bucket Item Read": PermissionGroup;
+
+  /**
+   * Dynamically discovered permission groups
+   */
+  [name: string]: PermissionGroup;
+};
+
+/**
+ * Lists all permission groups available for the Cloudflare account
+ * and returns a typed map of permission names to their IDs.
+ *
+ * This is primarily used when creating API tokens for Cloudflare services like R2.
+ *
+ * @example
+ * // Get all permission groups including those for R2
+ * const permissions = await PermissionGroups("cloudflare-permissions");
+ *
+ * // Use with AccountApiToken to create a token with proper permissions
+ * const token = await AccountApiToken("r2-token", {
+ *   name: "R2 Read-Only Token",
+ *   policies: [
+ *     {
+ *       effect: "allow",
+ *       resources: {
+ *         "com.cloudflare.edge.r2.bucket.abc123_default_my-bucket": "*"
+ *       },
+ *       permissionGroups: [
+ *         {
+ *           id: permissions["Workers R2 Storage Bucket Item Read"]
+ *         }
+ *       ]
+ *     }
+ *   ]
+ * });
+ */
+export const PermissionGroups = Resource(
+  "cloudflare::PermissionGroups",
+  async function (
+    this: Context<PermissionGroups>,
+    id: string,
+    options?: CloudflareApiOptions
+  ): Promise<PermissionGroups> {
+    // Only create and update phases are supported
+    if (this.phase === "delete") {
+      return this.destroy();
+    }
+
+    // Initialize API client
+    const api = await createCloudflareApi(options);
+
+    // Fetch permission groups from Cloudflare API
+    const response = await api.get(
+      `/accounts/${api.accountId}/tokens/permission_groups`
+    );
+
+    if (!response.ok) {
+      throw new Error(
+        `Failed to fetch permission groups: ${response.statusText}`
+      );
+    }
+
+    const data = (await response.json()) as PermissionGroupsResponse;
+
+    if (!data.success || !data.result) {
+      throw new Error(
+        `API returned error: ${data.errors?.[0]?.message || "Unknown error"}`
+      );
+    }
+
+    return this(
+      Object.fromEntries(
+        data.result.map((group) => [group.name, group])
+      ) as PermissionGroups
+    );
+  }
+);