alchemy 0.2.5 → 0.3.0

package/src/cloudflare/index.ts

@@ -1,8 +1,9 @@
 export * from "./bindings";
 export * from "./bucket";
+export * from "./dns";
 export * from "./durable-object-namespace";
 export * from "./kv-namespace";
-export * from "./state";
+export * from "./r2-rest-state-store";
 export * from "./static-site";
 export * from "./worker";
 export * from "./wrangler.json";

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

@@ -0,0 +1,353 @@
+import type { Scope } from "../scope";
+import type { State, StateStore } from "../state";
+import { withExponentialBackoff } from "../util/retry";
+import { deserialize, serialize } from "../util/serde";
+import { type CloudflareApi, createCloudflareApi } from "./api";
+
+/**
+ * Options for CloudflareR2StateStore
+ */
+export interface CloudflareR2StateStoreOptions {
+  /**
+   * The prefix to use for object keys in the R2 bucket
+   * This allows multiple state stores to use the same R2 bucket
+   */
+  prefix?: string;
+
+  /**
+   * The R2 bucket name to use
+   * Required - the bucket must already exist
+   */
+  bucketName: string;
+
+  /**
+   * API key to use (overrides CLOUDFLARE_API_KEY env var)
+   */
+  apiKey?: string;
+
+  /**
+   * 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;
+}
+
+/**
+ * State store implementation using Cloudflare R2 API
+ * Uses R2 for immediate consistency compared to KV's eventual consistency
+ */
+export class R2RestStateStore implements StateStore {
+  private api: CloudflareApi;
+  private prefix: string;
+  private bucketName: string;
+  private apiKey: string | undefined;
+  private accountId: string | undefined;
+  private email: string | undefined;
+  private initialized = false;
+
+  /**
+   * Create a new CloudflareR2StateStore
+   *
+   * @param scope The scope this store belongs to
+   * @param options Options for the state store
+   */
+  constructor(
+    public readonly scope: Scope,
+    options: CloudflareR2StateStoreOptions,
+  ) {
+    // Use the scope's chain to build the prefix, similar to how FileSystemStateStore builds its directory
+    const scopePath = scope.chain.join("/");
+    this.prefix = options.prefix
+      ? `${options.prefix}${scopePath}/`
+      : `alchemy/${scopePath}/`;
+
+    if (!options.bucketName) {
+      throw new Error("bucketName is required for CloudflareR2StateStore");
+    }
+    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;
+  }
+
+  /**
+   * Initialize the R2 client
+   */
+  async init(): Promise<void> {
+    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.initialized = true;
+  }
+
+  /**
+   * R2 buckets cannot be deleted programmatically via this method
+   */
+  async deinit(): Promise<void> {
+    // We don't delete the bucket here, only via explicit resource deletion
+  }
+
+  /**
+   * List all resources in the state store
+   */
+  async list(): Promise<string[]> {
+    await this.ensureInitialized();
+
+    // Using pagination to get all objects
+    let keys: string[] = [];
+    let cursor: string | null = null;
+
+    do {
+      const params = new URLSearchParams({
+        prefix: this.prefix,
+        limit: "1000",
+      });
+
+      if (cursor) {
+        params.append("cursor", cursor);
+      }
+
+      const listPath = `/accounts/${this.api.accountId}/r2/buckets/${this.bucketName}/objects?${params.toString()}`;
+      const response = await this.api.get(listPath);
+
+      if (!response.ok) {
+        const errorData: any = await response.json().catch(() => ({
+          errors: [{ message: response.statusText }],
+        }));
+        throw new Error(
+          `Error listing R2 objects: ${errorData.errors?.[0]?.message || response.statusText}`,
+        );
+      }
+
+      const data = (await response.json()) as any;
+
+      // The result structure may be under "result" key in Cloudflare's API
+      const result = data.result || data;
+      const objects = result.objects || [];
+
+      // Add keys to our list, removing the prefix and converting from storage format
+      keys = keys.concat(
+        objects.map((obj: any) => {
+          const keyName = obj.key || obj.name;
+          return this.convertKeyFromStorage(keyName.slice(this.prefix.length));
+        }),
+      );
+
+      // Update cursor for next page if available
+      cursor =
+        result.truncated || result.cursor_pagination
+          ? result.cursor || null
+          : null;
+    } while (cursor);
+
+    return keys;
+  }
+
+  /**
+   * Count the number of items in the state store
+   */
+  async count(): Promise<number> {
+    const keys = await this.list();
+    return keys.length;
+  }
+
+  /**
+   * Get a state by key
+   *
+   * @param key The key to look up
+   * @returns The state or undefined if not found
+   */
+  async get(key: string): Promise<State | undefined> {
+    await this.ensureInitialized();
+
+    try {
+      const response = await this.api.get(
+        `/accounts/${this.api.accountId}/r2/buckets/${this.bucketName}/objects/${this.getObjectKey(key)}`,
+      );
+
+      if (!response.ok) {
+        if (response.status === 404) {
+          return undefined;
+        }
+
+        const errorData: any = await response.json().catch(() => ({
+          errors: [{ message: response.statusText }],
+        }));
+        throw new Error(
+          `Error getting R2 object: ${errorData.errors?.[0]?.message || response.statusText}`,
+        );
+      }
+
+      // Parse and deserialize the state data
+      const rawData = await response.json();
+      const state = (await deserialize(this.scope, rawData)) as State;
+
+      // Create a new state object with proper output
+      return {
+        ...state,
+        output: {
+          ...(state.output || {}),
+          Scope: this.scope,
+        },
+      };
+    } catch (error: any) {
+      if (error.message?.includes("404")) {
+        return undefined;
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Get multiple states by their keys
+   *
+   * @param ids Array of keys to fetch
+   * @returns Record mapping keys to their states
+   */
+  async getBatch(ids: string[]): Promise<Record<string, State>> {
+    const result: Record<string, State> = {};
+
+    // R2 REST API doesn't have a batch get operation, so we need to make multiple requests
+    const promises = ids.map(async (id) => {
+      const state = await this.get(id);
+      if (state) {
+        result[id] = state;
+      }
+    });
+
+    await Promise.all(promises);
+    return result;
+  }
+
+  /**
+   * Get all states in the store
+   *
+   * @returns Record mapping all keys to their states
+   */
+  async all(): Promise<Record<string, State>> {
+    const keys = await this.list();
+    return this.getBatch(keys);
+  }
+
+  /**
+   * Set a state for a key
+   *
+   * @param key The key to set
+   * @param value The state to store
+   */
+  async set(key: string, value: State): Promise<void> {
+    await this.ensureInitialized();
+
+    const objectKey = this.getObjectKey(key);
+
+    // Serialize the state to handle cyclic structures
+    const serializedData = await serialize(this.scope, value);
+
+    // Using withExponentialBackoff for reliability
+    await withExponentialBackoff(
+      async () => {
+        const response = await this.api.put(
+          `/accounts/${this.api.accountId}/r2/buckets/${this.bucketName}/objects/${objectKey}`,
+          serializedData,
+          {
+            headers: {
+              "Content-Type": "application/json",
+            },
+          },
+        );
+
+        if (!response.ok) {
+          const errorData: any = await response.json().catch(() => ({
+            errors: [{ message: response.statusText }],
+          }));
+          throw new Error(
+            `Error writing to R2: ${errorData.errors?.[0]?.message || response.statusText}`,
+          );
+        }
+
+        return response;
+      },
+      // Retry on transient errors
+      (error) =>
+        error.message?.includes("503") || error.message?.includes("timeout"),
+      5, // 5 retry attempts
+      1000, // Start with 1 second delay
+    );
+  }
+
+  /**
+   * Delete a state by key
+   *
+   * @param key The key to delete
+   */
+  async delete(key: string): Promise<void> {
+    await this.ensureInitialized();
+
+    const response = await this.api.delete(
+      `/accounts/${this.api.accountId}/r2/buckets/${this.bucketName}/objects/${this.getObjectKey(key)}`,
+    );
+
+    if (!response.ok && response.status !== 404) {
+      const errorData: any = await response.json().catch(() => ({
+        errors: [{ message: response.statusText }],
+      }));
+      throw new Error(
+        `Error deleting from R2: ${errorData.errors?.[0]?.message || response.statusText}`,
+      );
+    }
+  }
+
+  /**
+   * Convert key for storage by replacing slashes with colons
+   * since R2 treats slashes as directory separators
+   *
+   * @param key The original key
+   * @returns Key with slashes replaced by colons
+   */
+  private convertKeyForStorage(key: string): string {
+    return key.replaceAll("/", ":");
+  }
+
+  /**
+   * Convert key from storage by replacing colons with slashes
+   *
+   * @param key The storage key
+   * @returns Key with colons replaced by slashes
+   */
+  private convertKeyFromStorage(key: string): string {
+    return key.replaceAll(":", "/");
+  }
+
+  /**
+   * Get the full object key for storage
+   *
+   * @param key The original key
+   * @returns The key with prefix for use in the R2 bucket
+   */
+  private getObjectKey(key: string): string {
+    return `${this.prefix}${this.convertKeyForStorage(key)}`;
+  }
+
+  /**
+   * Ensure the store is initialized before operations
+   */
+  private async ensureInitialized(): Promise<void> {
+    if (!this.initialized) {
+      await this.init();
+    }
+  }
+}

package/src/cloudflare/response.ts

@@ -0,0 +1,9 @@
+/**
+ * Cloudflare API response format
+ */
+export interface CloudflareResponse<T = unknown> {
+  result: T;
+  success: boolean;
+  errors: Array<{ code: number; message: string }>;
+  messages: string[];
+}

package/src/cloudflare/zone.ts

@@ -341,8 +341,8 @@ export const Zone = Resource(
         );
       }
 
-      const result = (await response.json()) as CloudflareZoneResponse;
-      const zoneData = result.result;
+      const zoneData = ((await response.json()) as { result: CloudflareZone })
+        .result;
 
       // Update zone settings if provided
       if (props.settings) {
@@ -380,18 +380,39 @@ export const Zone = Resource(
       });
 
       const body = await response.text();
+      let zoneData;
       if (!response.ok) {
         if (response.status === 400 && body.includes("already exists")) {
-          // TODO: should we error?
+          // Zone already exists, fetch it instead
+          console.warn(
+            `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}`,
+            );
+          }
+
+          const zones = (
+            (await getResponse.json()) as { result: CloudflareZone[] }
+          ).result;
+          if (zones.length === 0) {
+            throw new Error(
+              `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}`,
           );
         }
+      } else {
+        zoneData = (JSON.parse(body) as { result: CloudflareZone }).result;
       }
 
-      const zoneData = (JSON.parse(body) as CloudflareZoneResponse).result;
-
       // Update zone settings if provided
       if (props.settings) {
         await updateZoneSettings(api, zoneData.id, props.settings);
@@ -522,25 +543,20 @@ async function getZoneSettings(
 }
 
 /**
- * Cloudflare Zone API response
+ * Cloudflare Zone response format
  */
-interface CloudflareZoneResponse {
-  result: {
+export interface CloudflareZone {
+  id: string;
+  name: string;
+  type: "full" | "partial" | "secondary";
+  status: string;
+  paused: boolean;
+  account: {
     id: string;
-    name: string;
-    type: "full" | "partial" | "secondary";
-    status: string;
-    paused: boolean;
-    account: {
-      id: string;
-    };
-    name_servers: string[];
-    original_name_servers: string[] | null;
-    created_on: string;
-    modified_on: string;
-    activated_on: string | null;
   };
-  success: boolean;
-  errors: Array<{ code: number; message: string }>;
-  messages: string[];
+  name_servers: string[];
+  original_name_servers: string[] | null;
+  created_on: string;
+  modified_on: string;
+  activated_on: string | null;
 }

package/src/dns/godaddy.ts

@@ -0,0 +1,29 @@
+export type UpdateNameserversOptions = {
+  domain: string;
+  apiKey: string;
+  apiSecret: string;
+  nameservers: string[];
+};
+
+export async function updateNameservers(options: UpdateNameserversOptions) {
+  const url = `https://api.godaddy.com/v1/domains/${options.domain}/nameservers`;
+
+  const response = await fetch(url, {
+    method: "PUT",
+    headers: {
+      Authorization: `sso-key ${options.apiKey}:${options.apiSecret}`,
+      "Content-Type": "application/json",
+      Accept: "application/json",
+    },
+    body: JSON.stringify({
+      nameservers: options.nameservers,
+    }),
+  });
+
+  if (response.ok) {
+    console.log(`✅ Nameservers updated for ${options.domain}`);
+  } else {
+    const error = await response.json();
+    console.error(`❌ Failed to update nameservers:`, error);
+  }
+}

package/src/dns/import-dns.ts

@@ -0,0 +1,213 @@
+import type { Context } from "../context";
+import { Resource } from "../resource";
+import { DEFAULT_RECORD_TYPES, type DnsRecordType } from "./record";
+
+/**
+ * DNS record response structure from Cloudflare DNS API
+ * with both data (original) and content (for compatibility)
+ */
+export interface DnsApiRecord {
+  name: string;
+  type: DnsRecordType;
+  TTL: number;
+  data: string;
+  content: string; // Added for compatibility with DnsRecords
+  ttl: number; // Normalized ttl (lowercase)
+  priority?: number; // Priority for MX and SRV records
+}
+
+/**
+ * Cloudflare DNS-over-HTTPS API response structure
+ */
+interface CloudflareDNSResponse {
+  Status: number;
+  TC: boolean;
+  RD: boolean;
+  RA: boolean;
+  AD: boolean;
+  CD: boolean;
+  Question: Array<{
+    name: string;
+    type: number;
+  }>;
+  Answer?: {
+    name: string;
+    type: number;
+    TTL: number;
+    data: string;
+  }[];
+}
+
+/**
+ * Properties for importing DNS records
+ */
+export interface ImportDnsRecordsProps {
+  /**
+   * The domain to fetch DNS records for
+   */
+  domain: string;
+
+  /**
+   * Specific record types to fetch. If not provided, defaults to all supported types.
+   */
+  recordTypes?: DnsRecordType[];
+
+  /**
+   * Bump the resource to force a new import
+   */
+  bump?: number;
+}
+
+/**
+ * Output returned after DNS records import
+ */
+export interface ImportDnsRecords
+  extends Resource<"dns::ImportDnsRecords">,
+    ImportDnsRecordsProps {
+  /**
+   * The DNS records as a flat array, directly compatible with DnsRecords function
+   */
+  records: DnsApiRecord[];
+
+  /**
+   * Time at which the records were imported
+   */
+  importedAt: number;
+}
+
+/**
+ * Map numeric DNS record type to string type
+ */
+function mapDnsRecordType(type: number): DnsRecordType {
+  const typeMap: Record<number, DnsRecordType> = {
+    1: "A",
+    2: "NS",
+    5: "CNAME",
+    6: "SOA",
+    15: "MX",
+    16: "TXT",
+    28: "AAAA",
+    33: "SRV",
+    12: "PTR",
+  };
+
+  return typeMap[type] || "A";
+}
+
+/**
+ * Import DNS records for a domain using Cloudflare's DNS-over-HTTPS API.
+ * This resource allows you to fetch DNS records for a domain and store them
+ * in a structured format.
+ *
+ * @example
+ * // Import all default record types
+ * const allRecords = await ImportDnsRecords("example.com", {
+ *   domain: "example.com"
+ * });
+ *
+ * @example
+ * // Import only specific record types
+ * const specificRecords = await ImportDnsRecords("example.com", {
+ *   domain: "example.com",
+ *   recordTypes: ["A", "MX"]
+ * });
+ *
+ * @example
+ * // Import DNS records and transfer them to a Cloudflare zone
+ * const dnsRecords = await ImportDnsRecords("dns-records", {
+ *   domain: "example.com",
+ * });
+ *
+ * const zone = await Zone("example.com", {
+ *   name: "example.com",
+ *   type: "full",
+ * });
+ *
+ * // Records are directly compatible with DnsRecords function
+ * await DnsRecords("transfer-dns-records", {
+ *   zoneId: zone.id,
+ *   records: dnsRecords.records,
+ * });
+ */
+export const ImportDnsRecords = Resource(
+  "dns::ImportDnsRecords",
+  async function (
+    this: Context<ImportDnsRecords>,
+    id: string,
+    props: ImportDnsRecordsProps,
+  ): Promise<ImportDnsRecords> {
+    // For delete phase, just return destroyed state since this is a read-only resource
+    if (this.phase === "delete") {
+      return this.destroy();
+    }
+
+    const recordTypes = props.recordTypes || DEFAULT_RECORD_TYPES;
+    const allRecords: DnsApiRecord[] = [];
+
+    for (const type of recordTypes) {
+      try {
+        const res = await fetch(
+          `https://cloudflare-dns.com/dns-query?name=${props.domain}&type=${type}`,
+          {
+            headers: {
+              accept: "application/dns-json",
+            },
+          },
+        );
+
+        if (!res.ok) {
+          throw new Error(`Failed to fetch ${type} records: ${res.statusText}`);
+        }
+
+        const data = (await res.json()) as CloudflareDNSResponse;
+
+        if (data.Answer) {
+          // Transform records to be compatible with DnsRecords function
+          const compatRecords = data.Answer.map((record) => {
+            const recordType = mapDnsRecordType(record.type);
+            const result: DnsApiRecord = {
+              name: record.name,
+              type: recordType,
+              TTL: record.TTL,
+              data: record.data,
+              content: record.data, // Default mapping
+              ttl: record.TTL, // Normalized lowercase ttl
+            };
+
+            // Special handling for MX records to split priority and content
+            if (recordType === "MX") {
+              const parts = record.data.split(" ");
+              if (parts.length >= 2) {
+                const priority = Number.parseInt(parts[0], 10);
+                // Join the rest as hostname in case there are spaces
+                const hostname = parts.slice(1).join(" ");
+
+                if (!isNaN(priority)) {
+                  result.priority = priority;
+                  result.content = hostname;
+                }
+              }
+            }
+
+            return result;
+          });
+
+          allRecords.push(...compatRecords);
+        }
+      } catch (error) {
+        console.warn(
+          `Failed to fetch ${type} records for ${props.domain}:`,
+          error,
+        );
+      }
+    }
+
+    // Return the resource with fetched records as a flat array
+    return this({
+      domain: props.domain,
+      recordTypes: [...recordTypes],
+      records: allRecords,
+      importedAt: Date.now(),
+    });
+  },
+);

package/src/dns/index.ts

@@ -0,0 +1,2 @@
+export * from "./import-dns";
+export * from "./record";