alchemy 0.1.11 → 0.1.13

package/src/cloudflare/asset-manifest.ts

@@ -0,0 +1,16 @@
+export type AssetManifest = AssetManifestEntry[];
+
+export interface AssetManifestEntry {
+  source: string;
+  key: string;
+  hash: string;
+  cacheControl: string;
+  contentType?: string;
+}
+
+export interface FileOption {
+  files: string | string[];
+  cacheControl: string;
+  contentType?: string;
+  ignore?: string[];
+}

package/src/cloudflare/auth.ts

@@ -0,0 +1,187 @@
+/**
+ * Authentication options for Cloudflare API
+ */
+export interface CloudflareAuthOptions {
+  /**
+   * If true, throw an error when no authentication is found
+   * @default true
+   */
+  required?: boolean;
+
+  /**
+   * Email to use with API Key
+   * If not provided, will attempt to discover from Cloudflare API
+   */
+  email?: string;
+}
+
+/**
+ * Authentication headers for Cloudflare API
+ */
+export interface CloudflareAuthHeaders {
+  /**
+   * Authentication headers to use with fetch
+   */
+  headers: Record<string, string>;
+
+  /**
+   * Type of authentication being used
+   */
+  type: "token" | "key" | "none";
+
+  /**
+   * User email (only present when using API Key auth)
+   */
+  email?: string;
+}
+
+/**
+ * Response from the Cloudflare User API
+ */
+interface CloudflareUserResponse {
+  success: boolean;
+  result: {
+    id: string;
+    email: string;
+    name: string;
+    [key: string]: any;
+  };
+}
+
+/**
+ * Get authentication headers for Cloudflare API
+ *
+ * Priority:
+ * 1. API Token (CLOUDFLARE_API_TOKEN) - Recommended by Cloudflare
+ * 2. API Key (CLOUDFLARE_API_KEY) - Will attempt to discover email automatically
+ *
+ * @param options Authentication options
+ * @returns Authentication headers
+ */
+export async function getCloudflareAuth(
+  options: CloudflareAuthOptions = {},
+): Promise<CloudflareAuthHeaders> {
+  const { required = true } = options;
+
+  // Check for API Token (preferred method)
+  const apiToken = process.env.CLOUDFLARE_API_TOKEN;
+  if (apiToken) {
+    return {
+      headers: {
+        Authorization: `Bearer ${apiToken}`,
+      },
+      type: "token",
+    };
+  }
+
+  // Check for API Key
+  const apiKey = process.env.CLOUDFLARE_API_KEY;
+  if (apiKey) {
+    // If email is provided directly, use it
+    const providedEmail = options.email || process.env.CLOUDFLARE_EMAIL;
+    if (providedEmail) {
+      return {
+        headers: {
+          "X-Auth-Key": apiKey,
+          "X-Auth-Email": providedEmail,
+        },
+        type: "key",
+        email: providedEmail,
+      };
+    }
+
+    // Otherwise, try to discover email from Cloudflare API
+    try {
+      const email = await getUserEmailFromApiKey(apiKey);
+      return {
+        headers: {
+          "X-Auth-Key": apiKey,
+          "X-Auth-Email": email,
+        },
+        type: "key",
+        email,
+      };
+    } catch (error) {
+      console.error("Failed to discover email from API key:", error);
+      throw new Error(
+        "Failed to automatically discover email for API Key authentication.\n" +
+          "Options:\n" +
+          "1. Set CLOUDFLARE_EMAIL environment variable\n" +
+          "2. Use CLOUDFLARE_API_TOKEN instead (recommended by Cloudflare)",
+      );
+    }
+  }
+
+  // No authentication found
+  if (required) {
+    throw new Error(
+      "Cloudflare authentication required. Set either:\n" +
+        "1. CLOUDFLARE_API_TOKEN (recommended by Cloudflare)\n" +
+        "   Generate a token at: https://dash.cloudflare.com/profile/api-tokens\n" +
+        "2. CLOUDFLARE_API_KEY environment variable",
+    );
+  }
+
+  return {
+    headers: {},
+    type: "none",
+  };
+}
+
+/**
+ * Fetch the user's email from Cloudflare API using API Key
+ *
+ * @param apiKey The Cloudflare API key
+ * @returns The user's email
+ */
+async function getUserEmailFromApiKey(apiKey: string): Promise<string> {
+  try {
+    const baseUrl = "https://api.cloudflare.com/client/v4";
+
+    // Call the /user endpoint to get user information
+    const response = await fetch(`${baseUrl}/user`, {
+      headers: {
+        "Content-Type": "application/json",
+        "X-Auth-Key": apiKey,
+      },
+    });
+
+    if (!response.ok) {
+      throw new Error(
+        `Failed to get user information: ${response.status} ${response.statusText}`,
+      );
+    }
+
+    const data = (await response.json()) as CloudflareUserResponse;
+
+    if (!data.success || !data.result || !data.result.email) {
+      throw new Error("Cloudflare API did not return valid user information");
+    }
+
+    return data.result.email;
+  } catch (error) {
+    console.error("Error retrieving email from Cloudflare API:", error);
+    throw new Error(
+      "Failed to automatically discover email for API Key authentication",
+    );
+  }
+}
+
+/**
+ * Get headers for a Cloudflare API request, including content-type
+ *
+ * @param contentType Content type for the request
+ * @param options Authentication options
+ * @returns Complete headers for the request
+ */
+export async function getCloudflareHeaders(
+  contentType = "application/json",
+  options: CloudflareAuthOptions = {},
+): Promise<Record<string, string>> {
+  const auth = await getCloudflareAuth(options);
+
+  return {
+    "Content-Type": contentType,
+    ...auth.headers,
+  };
+}

package/src/cloudflare/bindings.ts

@@ -0,0 +1,297 @@
+/**
+ * Type definitions for Cloudflare Worker bindings
+ * Based on Cloudflare API documentation:
+ * https://developers.cloudflare.com/api/resources/workers/subresources/scripts/methods/update/
+ */
+import type { DurableObjectNamespace } from "./durable-object-namespace";
+
+/**
+ * Union type for all Worker binding types (Alchemy abstraction)
+ */
+export type WorkerBinding = WorkerBindingSpec | DurableObjectNamespace;
+
+/**
+ * Union type for all Worker binding types (API spec)
+ */
+export type WorkerBindingSpec =
+  | WorkerBindingAI
+  | WorkerBindingAnalyticsEngine
+  | WorkerBindingAssets
+  | WorkerBindingBrowserRendering
+  | WorkerBindingD1
+  | WorkerBindingDispatchNamespace
+  | WorkerBindingDurableObjectNamespace
+  | WorkerBindingHyperdrive
+  | WorkerBindingJson
+  | WorkerBindingKVNamespace
+  | WorkerBindingMTLSCertificate
+  | WorkerBindingPlainText
+  | WorkerBindingQueue
+  | WorkerBindingR2Bucket
+  | WorkerBindingSecretText
+  | WorkerBindingService
+  | WorkerBindingStaticContent
+  | WorkerBindingTailConsumer
+  | WorkerBindingVectorize
+  | WorkerBindingVersionMetadata
+  | WorkerBindingWasmModule;
+
+/**
+ * AI binding type
+ */
+export interface WorkerBindingAI {
+  /** The name of the binding */
+  name: string;
+  /** Type identifier for AI binding */
+  type: "ai";
+}
+
+/**
+ * Analytics Engine binding type
+ */
+export interface WorkerBindingAnalyticsEngine {
+  /** The name of the binding */
+  name: string;
+  /** Type identifier for Analytics Engine binding */
+  type: "analytics_engine";
+  /** Dataset name */
+  dataset: string;
+}
+
+/**
+ * Assets binding type
+ */
+export interface WorkerBindingAssets {
+  /** The name of the binding */
+  name: string;
+  /** Type identifier for Assets binding */
+  type: "assets";
+}
+
+/**
+ * Browser Rendering binding type
+ */
+export interface WorkerBindingBrowserRendering {
+  /** The name of the binding */
+  name: string;
+  /** Type identifier for Browser Rendering binding */
+  type: "browser_rendering";
+}
+
+/**
+ * D1 database binding type
+ */
+export interface WorkerBindingD1 {
+  /** The name of the binding */
+  name: string;
+  /** Type identifier for D1 binding */
+  type: "d1";
+  /** D1 database ID */
+  id: string;
+}
+
+/**
+ * Dispatch Namespace binding type
+ */
+export interface WorkerBindingDispatchNamespace {
+  /** The name of the binding */
+  name: string;
+  /** Type identifier for Dispatch Namespace binding */
+  type: "dispatch_namespace";
+  /** Namespace identifier */
+  namespace: string;
+  /** Optional outbound service */
+  outbound?: any; // Documentation doesn't specify the exact type
+}
+
+/**
+ * Durable Object Namespace binding type
+ */
+export interface WorkerBindingDurableObjectNamespace {
+  /**
+   * The stable ID of the binding
+   * @internal
+   */
+  stableId?: string;
+  /** The name of the binding */
+  name: string;
+  /** Type identifier for Durable Object Namespace binding */
+  type: "durable_object_namespace";
+  /** Durable Object class name */
+  class_name: string;
+  /** Script name that contains the Durable Object */
+  script_name?: string;
+  /** Environment */
+  environment?: string;
+  /** Namespace ID */
+  namespace_id?: string;
+}
+
+/**
+ * Hyperdrive binding type
+ */
+export interface WorkerBindingHyperdrive {
+  /** The name of the binding */
+  name: string;
+  /** Type identifier for Hyperdrive binding */
+  type: "hyperdrive";
+  /** Hyperdrive ID */
+  id: string;
+}
+
+/**
+ * JSON binding type
+ */
+export interface WorkerBindingJson {
+  /** The name of the binding */
+  name: string;
+  /** Type identifier for JSON binding */
+  type: "json";
+  /** JSON value */
+  json: any;
+}
+
+/**
+ * KV Namespace binding type
+ */
+export interface WorkerBindingKVNamespace {
+  /** The name of the binding */
+  name: string;
+  /** Type identifier for KV Namespace binding */
+  type: "kv_namespace";
+  /** KV Namespace ID */
+  namespace_id: string;
+}
+
+/**
+ * MTLS Certificate binding type
+ */
+export interface WorkerBindingMTLSCertificate {
+  /** The name of the binding */
+  name: string;
+  /** Type identifier for MTLS Certificate binding */
+  type: "mtls_certificate";
+  /** Certificate ID */
+  certificate_id: string;
+}
+
+/**
+ * Plain Text binding type
+ */
+export interface WorkerBindingPlainText {
+  /** The name of the binding */
+  name: string;
+  /** Type identifier for Plain Text binding */
+  type: "plain_text";
+  /** Text content */
+  text: string;
+}
+
+/**
+ * Queue binding type
+ */
+export interface WorkerBindingQueue {
+  /** The name of the binding */
+  name: string;
+  /** Type identifier for Queue binding */
+  type: "queue";
+  /** Queue name */
+  queue_name: string;
+}
+
+/**
+ * R2 Bucket binding type
+ */
+export interface WorkerBindingR2Bucket {
+  /** The name of the binding */
+  name: string;
+  /** Type identifier for R2 Bucket binding */
+  type: "r2_bucket";
+  /** Bucket name */
+  bucket_name: string;
+}
+
+/**
+ * Secret Text binding type
+ */
+export interface WorkerBindingSecretText {
+  /** The name of the binding */
+  name: string;
+  /** Type identifier for Secret Text binding */
+  type: "secret_text";
+  /** Secret value */
+  text: string;
+}
+
+/**
+ * Service binding type
+ */
+export interface WorkerBindingService {
+  /** The name of the binding */
+  name: string;
+  /** Type identifier for Service binding */
+  type: "service";
+  /** Service name */
+  service: string;
+  /** Environment */
+  environment?: string;
+  /** Service namespace */
+  namespace?: string;
+}
+
+/**
+ * Tail Consumer binding type
+ */
+export interface WorkerBindingTailConsumer {
+  /** The name of the binding */
+  name: string;
+  /** Type identifier for Tail Consumer binding */
+  type: "tail_consumer";
+  /** Service name */
+  service: string;
+}
+
+/**
+ * Vectorize binding type
+ */
+export interface WorkerBindingVectorize {
+  /** The name of the binding */
+  name: string;
+  /** Type identifier for Vectorize binding */
+  type: "vectorize";
+  /** Index name */
+  index_name: string;
+}
+
+/**
+ * Version Metadata binding type
+ */
+export interface WorkerBindingVersionMetadata {
+  /** The name of the binding */
+  name: string;
+  /** Type identifier for Version Metadata binding */
+  type: "version_metadata";
+}
+
+/**
+ * WASM Module binding type
+ */
+export interface WorkerBindingWasmModule {
+  /** The name of the binding */
+  name: string;
+  /** Type identifier for WASM Module binding */
+  type: "wasm_module";
+  /** Module name */
+  module: string;
+}
+
+/**
+ * Static content binding for Cloudflare Workers
+ * Used for Workers Sites and static assets
+ */
+export interface WorkerBindingStaticContent {
+  /** The name of the binding */
+  name: string;
+  /** Type identifier for Static Content binding */
+  type: "static_content";
+}

package/src/cloudflare/durable-object-namespace.ts

@@ -0,0 +1,43 @@
+import type { WorkerBinding } from "./bindings";
+
+export interface DurableObjectNamespaceInput {
+  bindingName: string;
+  className: string;
+  scriptName?: string | undefined;
+  environment?: string | undefined;
+  sqlite?: boolean | undefined;
+  namespaceId?: string | undefined;
+}
+
+export function isDurableObjectNamespace(
+  binding: WorkerBinding,
+): binding is DurableObjectNamespace {
+  return (
+    binding.type === "durable_object_namespace" &&
+    typeof (binding as any).bindingName === "string"
+  );
+}
+
+export class DurableObjectNamespace implements DurableObjectNamespaceInput {
+  public readonly type = "durable_object_namespace" as const;
+  // alias for bindingName to be consistent with other bindings
+  public readonly name: string;
+  public readonly bindingName: string;
+  public readonly className: string;
+  public readonly scriptName?: string | undefined;
+  public readonly environment?: string | undefined;
+  public readonly sqlite?: boolean | undefined;
+  public readonly namespaceId?: string | undefined;
+
+  constructor(
+    public readonly id: string,
+    input: DurableObjectNamespaceInput,
+  ) {
+    this.bindingName = input.bindingName;
+    this.name = this.bindingName;
+    this.className = input.className;
+    this.scriptName = input.scriptName;
+    this.environment = input.environment;
+    this.sqlite = input.sqlite;
+  }
+}

package/src/cloudflare/generate-asset-manifest.ts

@@ -0,0 +1,93 @@
+import crypto from "crypto";
+import { promises as fs } from "fs";
+import { glob } from "glob";
+import path from "path";
+import { getContentType } from "../utils/content-type";
+import type {
+  AssetManifest,
+  AssetManifestEntry,
+  FileOption,
+} from "./asset-manifest";
+
+export async function generateAssetManifest(
+  dir: string,
+  fileOptions: FileOption[] = [
+    {
+      files: "**",
+      cacheControl: "max-age=0,no-cache,no-store,must-revalidate",
+    },
+    {
+      files: ["**/*.js", "**/*.css"],
+      cacheControl: "max-age=31536000,public,immutable",
+    },
+  ],
+): Promise<AssetManifest> {
+  // First, collect all file info based on fileOptions (reversed to prioritize later rules)
+  const fileInfos: Array<{
+    file: string;
+    cacheControl: string;
+    contentType?: string;
+  }> = [];
+  const filesProcessed: Set<string> = new Set();
+
+  // Process file options in reverse order (later rules override earlier ones)
+  // Use for...of to maintain order but allow await inside the loop
+  const reversedOptions = [...fileOptions].reverse();
+  for (const fileOption of reversedOptions) {
+    const patterns = Array.isArray(fileOption.files)
+      ? fileOption.files
+      : [fileOption.files];
+
+    // Get all files matching the pattern
+    const files = (
+      await Promise.all(
+        patterns.map(async (p) => {
+          // Use glob as async function instead of globSync
+          return glob(p, {
+            cwd: path.resolve(dir),
+            nodir: true,
+            dot: true,
+            ignore: [
+              ".git/**",
+              "node_modules/**",
+              ...(typeof fileOption.ignore === "string"
+                ? [fileOption.ignore]
+                : (fileOption.ignore ?? [])),
+            ],
+          });
+        }),
+      )
+    )
+      .flat()
+      .filter((file) => !filesProcessed.has(file));
+
+    // Add files to processed set
+    for (const file of files) {
+      filesProcessed.add(file);
+      fileInfos.push({
+        file,
+        cacheControl: fileOption.cacheControl,
+        contentType: fileOption.contentType,
+      });
+    }
+  }
+
+  // Process all files in parallel
+  const manifestEntries = await Promise.all(
+    fileInfos.map(async ({ file, cacheControl, contentType }) => {
+      const source = path.resolve(dir, file);
+      const content = await fs.readFile(source);
+      const hash = crypto.createHash("sha256").update(content).digest("hex");
+
+      return {
+        source,
+        key: file,
+        hash,
+        cacheControl,
+        contentType: contentType ?? getContentType(file),
+      } satisfies AssetManifestEntry;
+    }),
+  );
+
+  return manifestEntries;
+}

package/src/cloudflare/index.ts

@@ -0,0 +1,6 @@
+export * from "./bindings";
+export * from "./durable-object-namespace";
+export * from "./kv-namespace";
+export * from "./state";
+export * from "./static-site";
+export * from "./worker";