alchemy 0.25.0 → 0.26.1

package/src/cloudflare/email-routing.ts

@@ -0,0 +1,230 @@
+import type { Context } from "../context.ts";
+import { Resource } from "../resource.ts";
+import { handleApiError } from "./api-error.ts";
+import { type CloudflareApiOptions, createCloudflareApi } from "./api.ts";
+import type { CloudflareResponse } from "./response.ts";
+import type { Zone } from "./zone.ts";
+
+/**
+ * Cloudflare Email Routing response format
+ */
+interface CloudflareEmailRouting {
+  enabled: boolean;
+  name: string;
+  created: string;
+  modified: string;
+  tag: string;
+}
+
+/**
+ * Properties for configuring email routing on a zone
+ */
+export interface EmailRoutingProps extends CloudflareApiOptions {
+  /**
+   * Zone ID or Zone resource where email routing will be configured
+   */
+  zone: string | Zone;
+
+  /**
+   * Whether email routing should be enabled
+   *
+   * @default true
+   */
+  enabled?: boolean;
+
+  /**
+   * Skip the DNS setup wizard when enabling email routing
+   *
+   * @default false
+   */
+  skipWizard?: boolean;
+}
+
+/**
+ * Email routing configuration for a Cloudflare zone
+ */
+export interface EmailRouting extends Resource<"cloudflare::EmailRouting"> {
+  /**
+   * Zone ID where email routing is configured
+   */
+  zoneId: string;
+
+  /**
+   * Whether email routing is enabled
+   */
+  enabled: boolean;
+
+  /**
+   * Zone name
+   */
+  name: string;
+
+  /**
+   * When email routing was created
+   */
+  created: string;
+
+  /**
+   * When email routing was last modified
+   */
+  modified: string;
+
+  /**
+   * Zone tag
+   */
+  tag: string;
+}
+
+/**
+ * Configures email routing for a Cloudflare zone, allowing emails sent to the zone's domain
+ * to be routed according to defined rules.
+ *
+ * @example
+ * ## Enable email routing for a zone
+ *
+ * Enable email routing for your domain to start receiving and routing emails.
+ *
+ * ```ts
+ * const emailRouting = await EmailRouting("example.com-routing", {
+ *   zone: "example.com",
+ *   enabled: true
+ * });
+ * ```
+ *
+ * @example
+ * ## Use with existing Zone resource
+ *
+ * Configure email routing using an existing Zone resource reference.
+ *
+ * ```ts
+ * const zone = await Zone("my-zone", {
+ *   name: "example.com"
+ * });
+ *
+ * const emailRouting = await EmailRouting("example.com-routing", {
+ *   zone: zone,
+ *   enabled: true,
+ *   skipWizard: true
+ * });
+ * ```
+ */
+export const EmailRouting = Resource(
+  "cloudflare::EmailRouting",
+  async function (
+    this: Context<EmailRouting>,
+    _id: string,
+    props: EmailRoutingProps,
+  ): Promise<EmailRouting> {
+    const api = await createCloudflareApi(props);
+    const zoneId = typeof props.zone === "string" ? props.zone : props.zone.id;
+
+    if (this.phase === "delete") {
+      // Disable email routing DNS
+      const response = await api.delete(`/zones/${zoneId}/email/routing/dns`);
+      if (!response.ok && response.status !== 404) {
+        await handleApiError(response, "disabling", "email routing DNS");
+      }
+      return this.destroy();
+    }
+
+    if (this.phase === "update" && this.output) {
+      // Check if we need to update the enabled state
+      const currentEnabled = this.output.enabled;
+      const desiredEnabled = props.enabled ?? true;
+
+      if (currentEnabled !== desiredEnabled) {
+        if (desiredEnabled) {
+          // Enable email routing DNS
+          const enablePayload = {
+            enabled: true,
+            ...(props.skipWizard && { skip_wizard: props.skipWizard }),
+          };
+          const response = await api.post(
+            `/zones/${zoneId}/email/routing/dns`,
+            enablePayload,
+          );
+          if (!response.ok) {
+            await handleApiError(response, "enabling", "email routing DNS");
+          }
+        } else {
+          // Disable email routing DNS
+          const response = await api.delete(
+            `/zones/${zoneId}/email/routing/dns`,
+          );
+          if (!response.ok) {
+            await handleApiError(response, "disabling", "email routing DNS");
+          }
+        }
+      }
+
+      // Get current state
+      const getResponse = await api.get(`/zones/${zoneId}/email/routing/dns`);
+      if (!getResponse.ok) {
+        if (getResponse.status === 404) {
+          throw new Error("Email routing DNS is not configured for this zone");
+        }
+        await handleApiError(
+          getResponse,
+          "getting",
+          "email routing DNS settings",
+        );
+      }
+
+      const result =
+        (await getResponse.json()) as CloudflareResponse<CloudflareEmailRouting>;
+
+      return this({
+        zoneId,
+        enabled: result.result.enabled,
+        name: result.result.name,
+        created: result.result.created,
+        modified: result.result.modified,
+        tag: result.result.tag,
+      });
+    }
+
+    // Create/Enable email routing
+    const enabled = props.enabled ?? true;
+
+    if (enabled) {
+      const enablePayload = {
+        enabled: true,
+        ...(props.skipWizard && { skip_wizard: props.skipWizard }),
+      };
+      const response = await api.post(
+        `/zones/${zoneId}/email/routing/dns`,
+        enablePayload,
+      );
+      if (!response.ok) {
+        await handleApiError(response, "enabling", "email routing DNS");
+      }
+    }
+
+    // Get the current state
+    const getResponse = await api.get(`/zones/${zoneId}/email/routing/dns`);
+    if (!getResponse.ok) {
+      if (getResponse.status === 404) {
+        throw new Error(
+          "Email routing DNS is not configured. Set enabled: true to configure it.",
+        );
+      }
+      await handleApiError(
+        getResponse,
+        "getting",
+        "email routing DNS settings",
+      );
+    }
+
+    const result =
+      (await getResponse.json()) as CloudflareResponse<CloudflareEmailRouting>;
+
+    return this({
+      zoneId,
+      enabled: result.result.enabled,
+      name: result.result.name,
+      created: result.result.created,
+      modified: result.result.modified,
+      tag: result.result.tag,
+    });
+  },
+);

package/src/cloudflare/email-rule.ts

@@ -0,0 +1,322 @@
+import type { Context } from "../context.ts";
+import { Resource } from "../resource.ts";
+import { handleApiError } from "./api-error.ts";
+import { type CloudflareApiOptions, createCloudflareApi } from "./api.ts";
+import type { CloudflareResponse } from "./response.ts";
+import type { Zone } from "./zone.ts";
+
+/**
+ * Email routing matcher - defines what emails to match
+ */
+export interface EmailMatcher {
+  /**
+   * Type of matcher
+   * - "literal": Exact string match
+   * - "all": Matches all emails
+   */
+  type: "literal" | "all";
+
+  /**
+   * Field to match against (required for literal matchers)
+   */
+  field?: "to" | "from" | "subject";
+
+  /**
+   * Value to match (required for literal matchers)
+   */
+  value?: string;
+}
+
+/**
+ * Email routing action - defines what to do with matched emails
+ */
+export interface EmailAction {
+  /**
+   * Type of action to take
+   * - "forward": Forward email to destination addresses
+   * - "worker": Process email with a Cloudflare Worker
+   * - "drop": Drop/reject the email
+   */
+  type: "forward" | "worker" | "drop";
+
+  /**
+   * Action configuration
+   * - For "forward": Array of destination email addresses
+   * - For "worker": Worker script name
+   * - For "drop": Not used
+   */
+  value?: string[];
+}
+
+/**
+ * Cloudflare Email Rule response format
+ */
+interface CloudflareEmailRule {
+  id: string;
+  name: string;
+  enabled: boolean;
+  priority: number;
+  matchers: EmailMatcher[];
+  actions: EmailAction[];
+  tag: string;
+}
+
+/**
+ * Properties for creating an email routing rule
+ */
+export interface EmailRuleProps extends CloudflareApiOptions {
+  /**
+   * Zone ID or Zone resource where the rule will be created
+   */
+  zone: string | Zone;
+
+  /**
+   * Name for the email routing rule
+   */
+  name?: string;
+
+  /**
+   * Whether the rule is enabled
+   *
+   * @default true
+   */
+  enabled?: boolean;
+
+  /**
+   * Rule priority - lower numbers have higher priority
+   * Rules are evaluated in priority order
+   *
+   * @default 0
+   */
+  priority?: number;
+
+  /**
+   * Array of matchers that define which emails this rule applies to
+   */
+  matchers: EmailMatcher[];
+
+  /**
+   * Array of actions to take when emails match this rule
+   */
+  actions: EmailAction[];
+}
+
+/**
+ * An email routing rule for a Cloudflare zone
+ */
+export interface EmailRule extends Resource<"cloudflare::EmailRule"> {
+  /**
+   * Zone ID where the rule is created
+   */
+  zoneId: string;
+
+  /**
+   * Rule ID
+   */
+  ruleId: string;
+
+  /**
+   * Rule name
+   */
+  name: string;
+
+  /**
+   * Whether the rule is enabled
+   */
+  enabled: boolean;
+
+  /**
+   * Rule priority
+   */
+  priority: number;
+
+  /**
+   * Matchers for this rule
+   */
+  matchers: EmailMatcher[];
+
+  /**
+   * Actions for this rule
+   */
+  actions: EmailAction[];
+
+  /**
+   * Rule tag
+   */
+  tag: string;
+}
+
+/**
+ * Creates email routing rules that define how emails sent to your domain are processed.
+ * Rules are evaluated in priority order (lower number = higher priority).
+ *
+ * @example
+ * ## Forward emails to a specific address
+ *
+ * Forward all emails sent to info@example.com to a destination address.
+ *
+ * ```ts
+ * const infoRule = await EmailRule("info-forwarding", {
+ *   zone: "example.com",
+ *   name: "Forward info emails",
+ *   matchers: [
+ *     {
+ *       type: "literal",
+ *       field: "to",
+ *       value: "info@example.com"
+ *     }
+ *   ],
+ *   actions: [
+ *     {
+ *       type: "forward",
+ *       value: ["admin@company.com"]
+ *     }
+ *   ]
+ * });
+ * ```
+ *
+ * @example
+ * ## Process emails with a Worker
+ *
+ * Route emails to a Cloudflare Worker for custom processing.
+ *
+ * ```ts
+ * const workerRule = await EmailRule("worker-processing", {
+ *   zone: "example.com",
+ *   name: "Process with Worker",
+ *   priority: 1,
+ *   matchers: [
+ *     {
+ *       type: "literal",
+ *       field: "to",
+ *       value: "webhook@example.com"
+ *     }
+ *   ],
+ *   actions: [
+ *     {
+ *       type: "worker",
+ *       value: ["email-processor"]
+ *     }
+ *   ]
+ * });
+ * ```
+ *
+ * @example
+ * ## Multiple matchers and actions
+ *
+ * Create a rule with multiple conditions and actions.
+ *
+ * ```ts
+ * const complexRule = await EmailRule("support-routing", {
+ *   zone: "example.com",
+ *   name: "Support email routing",
+ *   priority: 2,
+ *   matchers: [
+ *     {
+ *       type: "literal",
+ *       field: "to",
+ *       value: "support@example.com"
+ *     }
+ *   ],
+ *   actions: [
+ *     {
+ *       type: "forward",
+ *       value: ["support@company.com", "backup@company.com"]
+ *     }
+ *   ]
+ * });
+ * ```
+ */
+export const EmailRule = Resource(
+  "cloudflare::EmailRule",
+  async function (
+    this: Context<EmailRule>,
+    _id: string,
+    props: EmailRuleProps,
+  ): Promise<EmailRule> {
+    const api = await createCloudflareApi(props);
+    const zoneId = typeof props.zone === "string" ? props.zone : props.zone.id;
+
+    if (this.phase === "delete") {
+      if (this.output?.ruleId) {
+        const response = await api.delete(
+          `/zones/${zoneId}/email/routing/rules/${this.output.ruleId}`,
+        );
+        if (!response.ok && response.status !== 404) {
+          await handleApiError(response, "delete", "email rule");
+        }
+      }
+      return this.destroy();
+    }
+
+    if (this.phase === "update" && this.output) {
+      // Update the existing rule
+      const updatePayload = {
+        name: props.name || this.output.name,
+        enabled: props.enabled ?? true,
+        priority: props.priority ?? 0,
+        matchers: props.matchers,
+        actions: props.actions,
+      };
+
+      const response = await api.put(
+        `/zones/${zoneId}/email/routing/rules/${this.output.ruleId}`,
+        updatePayload,
+      );
+
+      if (!response.ok) {
+        if (response.status === 404) {
+          // Rule was deleted externally, create a new one
+        } else {
+          await handleApiError(response, "update", "email rule");
+        }
+      } else {
+        const result =
+          (await response.json()) as CloudflareResponse<CloudflareEmailRule>;
+
+        return this({
+          zoneId,
+          ruleId: result.result.id,
+          name: result.result.name,
+          enabled: result.result.enabled,
+          priority: result.result.priority,
+          matchers: result.result.matchers,
+          actions: result.result.actions,
+          tag: result.result.tag,
+        });
+      }
+    }
+
+    // Create new rule
+    const createPayload = {
+      name: props.name || "Email routing rule",
+      enabled: props.enabled ?? true,
+      priority: props.priority ?? 0,
+      matchers: props.matchers,
+      actions: props.actions,
+    };
+
+    const createResponse = await api.post(
+      `/zones/${zoneId}/email/routing/rules`,
+      createPayload,
+    );
+
+    if (!createResponse.ok) {
+      await handleApiError(createResponse, "create", "email rule");
+    }
+
+    const result =
+      (await createResponse.json()) as CloudflareResponse<CloudflareEmailRule>;
+
+    return this({
+      zoneId,
+      ruleId: result.result.id,
+      name: result.result.name,
+      enabled: result.result.enabled,
+      priority: result.result.priority,
+      matchers: result.result.matchers,
+      actions: result.result.actions,
+      tag: result.result.tag,
+    });
+  },
+);

package/src/cloudflare/hyperdrive.ts

@@ -2,6 +2,7 @@ import type { Context } from "../context.ts";
 import { Resource } from "../resource.ts";
 import { tryGetBinding } from "../runtime/bind.ts";
 import type { Secret } from "../secret.ts";
+import { logger } from "../util/logger.ts";
 import { handleApiError } from "./api-error.ts";
 import { createCloudflareApi, type CloudflareApiOptions } from "./api.ts";
 import type { Bound } from "./bound.ts";
@@ -276,7 +277,7 @@ const HyperdriveResource = Resource(
 
     if (this.phase === "delete") {
       if (!hyperdriveId) {
-        console.warn(`No hyperdriveId found for ${id}, skipping delete`);
+        logger.warn(`No hyperdriveId found for ${id}, skipping delete`);
         return this.destroy();
       }
 
@@ -287,7 +288,7 @@ const HyperdriveResource = Resource(
           await handleApiError(deleteResponse, "delete", "hyperdrive", id);
         }
       } catch (error) {
-        console.error(`Error deleting Hyperdrive ${id}:`, error);
+        logger.error(`Error deleting Hyperdrive ${id}:`, error);
         throw error;
       }
       return this.destroy();
@@ -311,7 +312,7 @@ const HyperdriveResource = Resource(
           const getResponse = await api.get(configPath);
           if (getResponse.status === 200) {
             // Hyperdrive exists, update it
-            console.log(
+            logger.log(
               `Hyperdrive '${id}' already exists. Updating existing resource.`,
             );
             response = await api.put(configPath, requestBody);
@@ -344,7 +345,7 @@ const HyperdriveResource = Resource(
       const data: { result: Record<string, any> } = await response!.json();
       apiResource = data.result;
     } catch (error) {
-      console.error(`Error ${this.phase} Hyperdrive '${id}':`, error);
+      logger.error(`Error ${this.phase} Hyperdrive '${id}':`, error);
       throw error;
     }
 

package/src/cloudflare/images.ts

@@ -0,0 +1,59 @@
+/**
+ * Cloudflare Images binding for image transformation and manipulation.
+ *
+ * Provides access to Cloudflare Images API for transforming, drawing, and outputting images
+ * within Workers. The binding requires no configuration - just the binding name.
+ *
+ * **Requirements:**
+ * - Cloudflare Images enabled for your account
+ * - For deployed Workers: image transforms must be enabled for the zone
+ *
+ * @example
+ * // Create an Images binding and bind to a Worker:
+ * import { Worker, Images } from "alchemy/cloudflare";
+ *
+ * const images = new Images();
+ *
+ * const worker = await Worker("image-processor", {
+ *   name: "image-processor",
+ *   entrypoint: "./src/worker.ts",
+ *   bindings: {
+ *     IMAGES: images
+ *   }
+ * });
+ *
+ * @example
+ * // Runtime usage - Basic image transformation:
+ * export default {
+ *   async fetch(request: Request, env: any): Promise<Response> {
+ *     const imageData = await request.arrayBuffer();
+ *
+ *     const response = await env.IMAGES
+ *       .input(imageData)
+ *       .transform({ width: 800, height: 600, format: "webp" })
+ *       .output();
+ *
+ *     return response.response();
+ *   }
+ * };
+ *
+ * @example
+ * // Runtime usage - Advanced transformations with overlays:
+ * const watermark: ReadableStream = await fetchWatermark();
+ * const image: ReadableStream = await fetchMainImage();
+ *
+ * const response = await env.IMAGES
+ *   .input(image)
+ *   .draw(
+ *     env.IMAGES.input(watermark).transform({ width: 32, height: 32 }),
+ *     { bottom: 32, right: 32 }
+ *   )
+ *   .output({ format: "image/avif" });
+ *
+ * return response.response();
+ *
+ * @see https://developers.cloudflare.com/images/transform-images/bindings/
+ */
+export class Images {
+  public readonly type = "images";
+}

package/src/cloudflare/index.ts

@@ -6,6 +6,7 @@ export * from "./analytics-engine.ts";
 export * from "./api-error.ts";
 export * from "./api.ts";
 export * from "./assets.ts";
+export * from "./astro.ts";
 export * from "./bindings.ts";
 export * from "./bound.ts";
 export * from "./browser-rendering.ts";
@@ -17,10 +18,16 @@ export * from "./d1-clone.ts";
 export * from "./d1-database.ts";
 export * from "./d1-export.ts";
 export * from "./d1-import.ts";
+export * from "./dispatch-namespace.ts";
 export * from "./dns-records.ts";
 export * from "./do-state-store/index.ts";
 export * from "./durable-object-namespace.ts";
+export * from "./email-address.ts";
+export * from "./email-catch-all.ts";
+export * from "./email-routing.ts";
+export * from "./email-rule.ts";
 export * from "./hyperdrive.ts";
+export * from "./images.ts";
 export * from "./kv-namespace.ts";
 export * from "./nuxt.ts";
 export * from "./permission-groups.ts";
@@ -31,6 +38,9 @@ export * from "./r2-rest-state-store.ts";
 export * from "./react-router.ts";
 export * from "./redwood.ts";
 export * from "./route.ts";
+export * from "./secret.ts";
+export * from "./secrets-store.ts";
+export * from "./sveltekit.ts";
 export * from "./tanstack-start.ts";
 export * from "./vectorize-index.ts";
 export * from "./vectorize-metadata-index.ts";

package/src/cloudflare/kv-namespace.ts

@@ -1,6 +1,7 @@
 import type { Context } from "../context.ts";
 import { Resource, ResourceKind } from "../resource.ts";
 import { bind } from "../runtime/bind.ts";
+import { logger } from "../util/logger.ts";
 import { withExponentialBackoff } from "../util/retry.ts";
 import { handleApiError } from "./api-error.ts";
 import {
@@ -223,7 +224,7 @@ const _KVNamespace = Resource(
           error instanceof Error &&
           error.message.includes("already exists")
         ) {
-          console.log(`Namespace '${title}' already exists, adopting it`);
+          logger.log(`Namespace '${title}' already exists, adopting it`);
           // Find the existing namespace by title
           const existingNamespace = await findKVNamespaceByTitle(api, title);