alchemy 0.25.0 → 0.26.0

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";
@@ -20,7 +21,12 @@ export * from "./d1-import.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 +37,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);
 

package/src/cloudflare/pipeline.ts

@@ -2,6 +2,7 @@ import type { Context } from "../context.ts";
 import { Resource, ResourceKind } from "../resource.ts";
 import { bind } from "../runtime/bind.ts";
 import type { Secret } from "../secret.ts";
+import { logger } from "../util/logger.ts";
 import { CloudflareApiError, handleApiError } from "./api-error.ts";
 import {
   createCloudflareApi,
@@ -211,6 +212,14 @@ export interface PipelineProps extends CloudflareApiOptions {
    * @default true
    */
   delete?: boolean;
+
+  /**
+   * Whether to adopt an existing pipeline instead of creating a new one.
+   * If set to true, the resource will attempt to adopt an existing pipeline with the same name
+   *
+   * @default false
+   */
+  adopt?: boolean;
 }
 
 /**
@@ -359,7 +368,34 @@ const PipelineResource = Resource("cloudflare::Pipeline", async function <
   let pipelineData: CloudflarePipelineResponse;
 
   if (this.phase === "create") {
-    pipelineData = await createPipeline(api, pipelineName, props);
+    console.log(props);
+    // Check if we should adopt an existing pipeline
+    try {
+      // Try to create pipeline first
+      console.log("Creating new Cloudflare Pipeline:", pipelineName);
+      pipelineData = await createPipeline(api, pipelineName, props);
+    } catch (error) {
+      // If creation fails with 409 (conflict), adopt existing pipeline
+      if (
+        error instanceof CloudflareApiError &&
+        (error.status === 409 ||
+          (error.status === 400 &&
+            error.message.includes("Pipeline with this name already exists")))
+      ) {
+        if (props.adopt) {
+          console.log(
+            "Pipeline already exists, adopting existing Cloudflare Pipeline:",
+            pipelineName,
+          );
+          pipelineData = await getPipeline(api, pipelineName);
+        } else {
+          throw error;
+        }
+      } else {
+        // For any other error, rethrow
+        throw error;
+      }
+    }
   } else {
     // Update operation
     if (this.output?.id) {
@@ -374,7 +410,7 @@ const PipelineResource = Resource("cloudflare::Pipeline", async function <
       pipelineData = await updatePipeline(api, pipelineName, props);
     } else {
       // If no ID exists, fall back to creating a new pipeline
-      console.log(
+      logger.log(
         "No existing Pipeline ID found, creating new Cloudflare Pipeline:",
         pipelineName,
       );

package/src/cloudflare/queue-consumer.ts

@@ -1,5 +1,6 @@
 import type { Context } from "../context.ts";
 import { Resource } from "../resource.ts";
+import { logger } from "../util/logger.ts";
 import { CloudflareApiError, handleApiError } from "./api-error.ts";
 import {
   createCloudflareApi,
@@ -157,7 +158,7 @@ export const QueueConsumer = Resource(
     }
 
     if (this.phase === "delete") {
-      console.log(`Deleting Queue Consumer for queue ${queueId}`);
+      logger.log(`Deleting Queue Consumer for queue ${queueId}`);
       if (props.delete !== false && this.output?.id) {
         // Delete the consumer
         await deleteQueueConsumer(api, queueId, this.output.id);

package/src/cloudflare/queue.ts

@@ -200,12 +200,8 @@ const QueueResource = Resource("cloudflare::Queue", async function <
   const queueName = props.name ?? id;
 
   if (this.phase === "delete") {
-    console.log("Deleting Cloudflare Queue:", queueName);
     if (props.delete !== false) {
       // Delete Queue
-      if (!this.output?.id) {
-        console.log(this.output);
-      }
       await deleteQueue(api, this.output?.id);
     }
 
@@ -215,7 +211,6 @@ const QueueResource = Resource("cloudflare::Queue", async function <
   let queueData: CloudflareQueueResponse;
 
   if (this.phase === "create") {
-    console.log("Creating Cloudflare Queue:", queueName);
     try {
       queueData = await createQueue(api, queueName, props);
     } catch (error) {
@@ -239,8 +234,6 @@ const QueueResource = Resource("cloudflare::Queue", async function <
   } else {
     // Update operation
     if (this.output?.id) {
-      console.log("Updating Cloudflare Queue:", queueName);
-
       // Check if name is being changed, which is not allowed
       if (queueName !== this.output.name) {
         throw new Error(
@@ -252,10 +245,6 @@ const QueueResource = Resource("cloudflare::Queue", async function <
       queueData = await updateQueue(api, this.output.id, props);
     } else {
       // If no ID exists, fall back to creating a new queue
-      console.log(
-        "No existing Queue ID found, creating new Cloudflare Queue:",
-        queueName,
-      );
       queueData = await createQueue(api, queueName, props);
     }
   }
@@ -368,7 +357,6 @@ export async function deleteQueue(
   queueId?: string,
 ): Promise<void> {
   if (!queueId) {
-    console.log("No Queue ID provided, skipping delete");
     return;
   }