alchemy 0.2.5 → 0.3.0

package/lib/cloudflare/r2-rest-state-store.js

@@ -0,0 +1,254 @@
+import { withExponentialBackoff } from "../util/retry";
+import { deserialize, serialize } from "../util/serde";
+import { createCloudflareApi } from "./api";
+/**
+ * State store implementation using Cloudflare R2 API
+ * Uses R2 for immediate consistency compared to KV's eventual consistency
+ */
+export class R2RestStateStore {
+    scope;
+    api;
+    prefix;
+    bucketName;
+    apiKey;
+    accountId;
+    email;
+    initialized = false;
+    /**
+     * Create a new CloudflareR2StateStore
+     *
+     * @param scope The scope this store belongs to
+     * @param options Options for the state store
+     */
+    constructor(scope, options) {
+        this.scope = scope;
+        // 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;
+    }
+    /**
+     * Initialize the R2 client
+     */
+    async init() {
+        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() {
+        // We don't delete the bucket here, only via explicit resource deletion
+    }
+    /**
+     * List all resources in the state store
+     */
+    async list() {
+        await this.ensureInitialized();
+        // Using pagination to get all objects
+        let keys = [];
+        let cursor = 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 = 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());
+            // 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) => {
+                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() {
+        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) {
+        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 = 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));
+            // Create a new state object with proper output
+            return {
+                ...state,
+                output: {
+                    ...(state.output || {}),
+                    Scope: this.scope,
+                },
+            };
+        }
+        catch (error) {
+            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) {
+        const result = {};
+        // 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() {
+        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, value) {
+        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 = 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);
+    }
+    /**
+     * Delete a state by key
+     *
+     * @param key The key to delete
+     */
+    async delete(key) {
+        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 = 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
+     */
+    convertKeyForStorage(key) {
+        return key.replaceAll("/", ":");
+    }
+    /**
+     * Convert key from storage by replacing colons with slashes
+     *
+     * @param key The storage key
+     * @returns Key with colons replaced by slashes
+     */
+    convertKeyFromStorage(key) {
+        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
+     */
+    getObjectKey(key) {
+        return `${this.prefix}${this.convertKeyForStorage(key)}`;
+    }
+    /**
+     * Ensure the store is initialized before operations
+     */
+    async ensureInitialized() {
+        if (!this.initialized) {
+            await this.init();
+        }
+    }
+}

package/lib/cloudflare/response.d.ts

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

package/lib/cloudflare/zone.d.ts

@@ -249,3 +249,21 @@ export interface Zone extends Resource<"cloudflare::Zone"> {
  * @see https://developers.cloudflare.com/dns/zone-setups/
  */
 export declare const Zone: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<Zone>, id: string, props: ZoneProps) => Promise<Zone>);
+/**
+ * Cloudflare Zone response format
+ */
+export interface CloudflareZone {
+    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;
+}

package/lib/cloudflare/zone.js

@@ -82,8 +82,8 @@ export const Zone = Resource("cloudflare::Zone", async function (id, props) {
         if (!response.ok) {
             throw new Error(`Error getting zone '${props.name}': ${response.statusText}`);
         }
-        const result = (await response.json());
-        const zoneData = result.result;
+        const zoneData = (await response.json())
+            .result;
         // Update zone settings if provided
         if (props.settings) {
             await updateZoneSettings(api, this.output.id, props.settings);
@@ -118,15 +118,28 @@ export const Zone = Resource("cloudflare::Zone", async function (id, props) {
             },
         });
         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()).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}`);
             }
         }
-        const zoneData = JSON.parse(body).result;
+        else {
+            zoneData = JSON.parse(body).result;
+        }
         // Update zone settings if provided
         if (props.settings) {
             await updateZoneSettings(api, zoneData.id, props.settings);

package/lib/dns/godaddy.d.ts

@@ -0,0 +1,7 @@
+export type UpdateNameserversOptions = {
+    domain: string;
+    apiKey: string;
+    apiSecret: string;
+    nameservers: string[];
+};
+export declare function updateNameservers(options: UpdateNameserversOptions): Promise<void>;

package/lib/dns/godaddy.js

@@ -0,0 +1,21 @@
+export async function updateNameservers(options) {
+    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/lib/dns/import-dns.d.ts

@@ -0,0 +1,82 @@
+import type { Context } from "../context";
+import { Resource } from "../resource";
+import { 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;
+    ttl: number;
+    priority?: number;
+}
+/**
+ * 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;
+}
+/**
+ * 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 declare const ImportDnsRecords: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<ImportDnsRecords>, id: string, props: ImportDnsRecordsProps) => Promise<ImportDnsRecords>);

package/lib/dns/import-dns.js

@@ -0,0 +1,114 @@
+import { Resource } from "../resource";
+import { DEFAULT_RECORD_TYPES } from "./record";
+/**
+ * Map numeric DNS record type to string type
+ */
+function mapDnsRecordType(type) {
+    const typeMap = {
+        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 (id, props) {
+    // 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 = [];
+    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());
+            if (data.Answer) {
+                // Transform records to be compatible with DnsRecords function
+                const compatRecords = data.Answer.map((record) => {
+                    const recordType = mapDnsRecordType(record.type);
+                    const result = {
+                        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/lib/dns/index.d.ts

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

package/lib/dns/index.js

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

package/lib/dns/record.d.ts

@@ -0,0 +1,88 @@
+/**
+ * DNS record types supported across different providers
+ */
+export type DnsRecordType = "A" | "AAAA" | "MX" | "TXT" | "NS" | "CNAME" | "SOA" | "SRV" | "PTR";
+/**
+ * Default DNS record types to fetch
+ */
+export declare const DEFAULT_RECORD_TYPES: readonly DnsRecordType[];
+/**
+ * Base DNS record interface with common properties
+ */
+export interface DnsRecordBase {
+    /**
+     * DNS record name (e.g., "example.com", "subdomain.example.com")
+     */
+    name: string;
+    /**
+     * Record type (A, AAAA, CNAME, etc.)
+     */
+    type: DnsRecordType;
+}
+/**
+ * DNS record response structure from DNS-over-HTTPS APIs
+ */
+export interface DohDnsRecord extends DnsRecordBase {
+    /**
+     * Time To Live in seconds
+     */
+    TTL: number;
+    /**
+     * Record data/content (varies by record type)
+     */
+    data: string;
+}
+/**
+ * Comprehensive DNS record structure for creating/managing records
+ */
+export interface DnsRecord extends DnsRecordBase {
+    /**
+     * DNS record content (e.g., IP address, hostname)
+     */
+    content: string;
+    /**
+     * Time To Live (TTL) in seconds
+     * Setting to 1 means 'automatic'
+     * Value must be between 60 and 86400, with minimum reduced to 30 for Enterprise zones
+     * @default 1
+     */
+    ttl?: number;
+    /**
+     * Whether the record is receiving proxied traffic through Cloudflare
+     * @default false
+     */
+    proxied?: boolean;
+    /**
+     * Comments or notes about the record
+     */
+    comment?: string;
+    /**
+     * Record tags
+     */
+    tags?: string[];
+    /**
+     * Priority value for MX/SRV records
+     */
+    priority?: number;
+}
+/**
+ * DNS record with provider-specific ID and metadata
+ */
+export interface DnsRecordWithMetadata extends DnsRecord {
+    /**
+     * Record ID
+     */
+    id: string;
+    /**
+     * Zone or domain ID the record belongs to
+     */
+    zoneId: string;
+    /**
+     * Time at which the record was created
+     */
+    createdAt: number;
+    /**
+     * Time at which the record was last modified
+     */
+    modifiedAt?: number;
+}

package/lib/dns/record.js

@@ -0,0 +1,13 @@
+/**
+ * Default DNS record types to fetch
+ */
+export const DEFAULT_RECORD_TYPES = [
+    "A",
+    "AAAA",
+    "MX",
+    "TXT",
+    "NS",
+    "CNAME",
+    "SOA",
+    "SRV",
+];

package/lib/fs/file-system-state-store.d.ts

@@ -0,0 +1,17 @@
+import type { Scope } from "../scope";
+import type { State, StateStore } from "../state";
+export declare class FileSystemStateStore implements StateStore {
+    readonly scope: Scope;
+    readonly dir: string;
+    constructor(scope: Scope);
+    init(): Promise<void>;
+    deinit(): Promise<void>;
+    count(): Promise<number>;
+    list(): Promise<string[]>;
+    get(key: string): Promise<State | undefined>;
+    set(key: string, value: State): Promise<void>;
+    delete(key: string): Promise<void>;
+    all(): Promise<Record<string, State>>;
+    getBatch(ids: string[]): Promise<Record<string, State>>;
+    private getPath;
+}