alchemy 0.12.6 → 0.12.7

package/src/cloudflare/ai-gateway.ts

@@ -151,7 +151,6 @@ export interface AiGateway
  */
 export const AiGateway = Resource(
   "cloudflare::AiGateway",
-  { alwaysUpdate: true }, // AI Gateway PUT updates, so always run update logic
   async function (
     this: Context<AiGateway>,
     id: string,

package/src/cloudflare/bindings.ts

@@ -9,6 +9,7 @@ import type { Assets } from "./assets.js";
 import type { R2Bucket } from "./bucket.js";
 import type { D1Database } from "./d1-database.js";
 import type { DurableObjectNamespace } from "./durable-object-namespace.js";
+import type { Hyperdrive } from "./hyperdrive.js";
 import type { KVNamespace } from "./kv-namespace.js";
 import type { Pipeline } from "./pipeline.js";
 import type { Queue } from "./queue.js";
@@ -24,9 +25,11 @@ export type Bindings = {
  * L2 Binding Resources.
  */
 export type Binding =
+  | AiGateway
   | Assets
   | D1Database
   | DurableObjectNamespace
+  | Hyperdrive
   | KVNamespace
   | Pipeline
   | Queue
@@ -35,8 +38,7 @@ export type Binding =
   | string
   | VectorizeIndex
   | Worker
-  | Workflow
-  | AiGateway;
+  | Workflow;
 
 /**
  * Union type for all Worker binding types (API spec)

package/src/cloudflare/bound.ts

@@ -6,6 +6,7 @@ import type { Binding } from "./bindings.js";
 import type { R2Bucket as _R2Bucket } from "./bucket.js";
 import type { D1Database as _D1Database } from "./d1-database.js";
 import type { DurableObjectNamespace as _DurableObjectNamespace } from "./durable-object-namespace.js";
+import type { Hyperdrive as _Hyperdrive } from "./hyperdrive.js";
 import type { KVNamespace as _KVNamespace } from "./kv-namespace.js";
 import type { Pipeline as _Pipeline } from "./pipeline.js";
 import type { Queue as _Queue } from "./queue.js";
@@ -23,20 +24,22 @@ export type Bound<T extends Binding> = T extends _DurableObjectNamespace
         ? R2Bucket
         : T extends _AiGateway
           ? AiGateway
-          : T extends Secret
-            ? string
-            : T extends Assets
-              ? Service
-              : T extends _Workflow<infer P>
-                ? Workflow<P>
-                : T extends _D1Database
-                  ? D1Database
-                  : T extends _VectorizeIndex
-                    ? VectorizeIndex
-                    : T extends _Queue
-                      ? Queue
-                      : T extends _Pipeline<infer R>
-                        ? Pipeline<R>
-                        : T extends string
-                          ? string
-                          : Service;
+          : T extends _Hyperdrive
+            ? Hyperdrive
+            : T extends Secret
+              ? string
+              : T extends Assets
+                ? Service
+                : T extends _Workflow<infer P>
+                  ? Workflow<P>
+                  : T extends _D1Database
+                    ? D1Database
+                    : T extends _VectorizeIndex
+                      ? VectorizeIndex
+                      : T extends _Queue
+                        ? Queue
+                        : T extends _Pipeline<infer R>
+                          ? Pipeline<R>
+                          : T extends string
+                            ? string
+                            : Service;

package/src/cloudflare/hyperdrive.ts

@@ -0,0 +1,375 @@
+import type { Context } from "../context.js";
+import { Resource } from "../resource.js";
+import type { Secret } from "../secret.js";
+import { handleApiError } from "./api-error.js";
+import { createCloudflareApi, type CloudflareApiOptions } from "./api.js";
+
+/**
+ * Origin configuration for a PostgreSQL database connection
+ */
+export interface HyperdriveOrigin {
+  /**
+   * Database name
+   */
+  database: string;
+
+  /**
+   * Database host
+   */
+  host: string;
+
+  /**
+   * Database password
+   * Use alchemy.secret() to securely store this value
+   */
+  password: Secret;
+
+  /**
+   * Database port
+   * @default 5432
+   */
+  port?: number;
+
+  /**
+   * Connection scheme
+   * @default "postgres"
+   */
+  scheme?: "postgres";
+
+  /**
+   * Database user
+   */
+  user: string;
+}
+
+/**
+ * Origin configuration for a database connection with access tokens
+ */
+export interface HyperdriveOriginWithAccess {
+  /**
+   * Access client ID
+   */
+  access_client_id: string;
+
+  /**
+   * Access client secret
+   * Use alchemy.secret() to securely store this value
+   */
+  access_client_secret: Secret;
+
+  /**
+   * Database host
+   */
+  host: string;
+
+  /**
+   * Database name
+   */
+  database: string;
+
+  /**
+   * Database port
+   * @default 5432
+   */
+  port?: number;
+
+  /**
+   * Connection scheme
+   * @default "postgres"
+   */
+  scheme?: "postgres";
+
+  /**
+   * Database user
+   */
+  user: string;
+}
+
+/**
+ * Caching configuration for Hyperdrive
+ */
+export interface HyperdriveCaching {
+  /**
+   * Whether caching is disabled
+   * @default false
+   */
+  disabled?: boolean;
+}
+
+/**
+ * mTLS configuration for Hyperdrive
+ */
+export interface HyperdriveMtls {
+  /**
+   * CA certificate ID
+   */
+  ca_certificate_id?: string;
+
+  /**
+   * mTLS certificate ID
+   */
+  mtls_certificate_id?: string;
+
+  /**
+   * SSL mode
+   * @default "verify-full"
+   */
+  sslmode?: "verify-ca" | "verify-full";
+}
+
+/**
+ * Properties for creating or updating a Cloudflare Hyperdrive.
+ */
+export interface HyperdriveProps extends CloudflareApiOptions {
+  /**
+   * Name of the Hyperdrive configuration
+   */
+  name: string;
+
+  /**
+   * Database connection origin configuration
+   */
+  origin: HyperdriveOrigin | HyperdriveOriginWithAccess;
+
+  /**
+   * Caching configuration
+   */
+  caching?: HyperdriveCaching;
+
+  /**
+   * mTLS configuration
+   */
+  mtls?: HyperdriveMtls;
+
+  /**
+   * UUID of the hyperdrive (only used for update/delete operations)
+   * This is provided by Cloudflare and is different from the resource ID
+   * @internal
+   */
+  hyperdriveId?: string;
+}
+
+/**
+ * Output returned after Cloudflare Hyperdrive creation/update.
+ * IMPORTANT: The interface name MUST match the exported resource name.
+ */
+export interface Hyperdrive
+  extends Resource<"cloudflare::Hyperdrive">,
+    Omit<HyperdriveProps, "origin"> {
+  /**
+   * The ID of the resource
+   */
+  id: string;
+
+  /**
+   * The Cloudflare-generated UUID of the hyperdrive
+   */
+  hyperdriveId: string;
+
+  /**
+   * Database connection origin configuration
+   */
+  origin: HyperdriveOrigin | HyperdriveOriginWithAccess;
+
+  /**
+   * Resource type identifier for binding.
+   * @internal
+   */
+  type: "hyperdrive";
+}
+
+/**
+ * Represents a Cloudflare Hyperdrive configuration.
+ *
+ * @example
+ * // Create a basic Hyperdrive connection to a PostgreSQL database
+ * const basicHyperdrive = await Hyperdrive("my-postgres-db", {
+ *   name: "my-postgres-db",
+ *   origin: {
+ *     database: "postgres",
+ *     host: "database.example.com",
+ *     password: alchemy.secret("your-password"),
+ *     port: 5432,
+ *     user: "postgres"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a Hyperdrive with caching disabled
+ * const noCacheHyperdrive = await Hyperdrive("no-cache-db", {
+ *   name: "no-cache-db",
+ *   origin: {
+ *     database: "postgres",
+ *     host: "database.example.com",
+ *     password: alchemy.secret(process.env.DB_PASSWORD),
+ *     port: 5432,
+ *     user: "postgres"
+ *   },
+ *   caching: {
+ *     disabled: true
+ *   }
+ * });
+ *
+ * @example
+ * // Create a Hyperdrive with mTLS configuration
+ * const mtlsHyperdrive = await Hyperdrive("secure-db", {
+ *   name: "secure-db",
+ *   origin: {
+ *     database: "postgres",
+ *     host: "database.example.com",
+ *     password: alchemy.secret(process.env.DB_PASSWORD),
+ *     port: 5432,
+ *     user: "postgres"
+ *   },
+ *   mtls: {
+ *     ca_certificate_id: "00000000-0000-0000-0000-0000000000",
+ *     mtls_certificate_id: "00000000-0000-0000-0000-0000000000",
+ *     sslmode: "verify-full"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a Hyperdrive with access client credentials
+ * const accessHyperdrive = await Hyperdrive("access-db", {
+ *   name: "access-db",
+ *   origin: {
+ *     database: "postgres",
+ *     host: "database.example.com",
+ *     access_client_id: "client-id",
+ *     access_client_secret: alchemy.secret(process.env.ACCESS_CLIENT_SECRET),
+ *     port: 5432,
+ *     user: "postgres"
+ *   }
+ * });
+ */
+export const Hyperdrive = Resource(
+  "cloudflare::Hyperdrive",
+  async function (
+    this: Context<Hyperdrive>,
+    id: string,
+    props: HyperdriveProps
+  ): Promise<Hyperdrive> {
+    const api = await createCloudflareApi(props);
+    const configsPath = `/accounts/${api.accountId}/hyperdrive/configs`;
+
+    // For create operations, we don't have a hyperdriveId yet
+    // For update/delete operations, we need to use the hyperdriveId from props or output
+    const hyperdriveId = props.hyperdriveId || this.output?.hyperdriveId;
+    const configPath = hyperdriveId
+      ? `${configsPath}/${hyperdriveId}`
+      : `${configsPath}`;
+
+    if (this.phase === "delete") {
+      if (!hyperdriveId) {
+        console.warn(`No hyperdriveId found for ${id}, skipping delete`);
+        return this.destroy();
+      }
+
+      try {
+        const deleteResponse = await api.delete(configPath);
+        // Only swallow 404 Not Found errors, all other errors should be handled
+        if (!deleteResponse.ok && deleteResponse.status !== 404) {
+          await handleApiError(deleteResponse, "delete", "hyperdrive", id);
+        }
+      } catch (error) {
+        console.error(`Error deleting Hyperdrive ${id}:`, error);
+        throw error;
+      }
+      return this.destroy();
+    }
+
+    let response: Response | undefined;
+    let apiResource: any;
+
+    // Prepare request body with unwrapped secrets
+    const requestBody = prepareRequestBody(props);
+
+    try {
+      if (this.phase === "update" && hyperdriveId) {
+        // Update existing hyperdrive
+        response = await api.put(configPath, requestBody);
+      } else {
+        // Create new hyperdrive
+        if (hyperdriveId) {
+          // If we have a hyperdriveId but we're in create phase, it could be because
+          // the resource exists but wasn't in state. Do a GET to check.
+          const getResponse = await api.get(configPath);
+          if (getResponse.status === 200) {
+            // Hyperdrive exists, update it
+            console.log(
+              `Hyperdrive '${id}' already exists. Updating existing resource.`
+            );
+            response = await api.put(configPath, requestBody);
+          } else if (getResponse.status === 404) {
+            // Hyperdrive doesn't exist, create new
+            response = await api.post(configsPath, {
+              ...requestBody,
+              // Ensure name is set correctly if not already set
+              name: props.name || id,
+            });
+          } else {
+            // Unexpected error during GET check
+            await handleApiError(getResponse, "get", "hyperdrive", id);
+          }
+        } else {
+          // No hyperdriveId, create new
+          response = await api.post(configsPath, {
+            ...requestBody,
+            // Ensure name is set correctly if not already set
+            name: props.name || id,
+          });
+        }
+      }
+
+      if (!response?.ok) {
+        const action = this.phase === "update" ? "update" : "create";
+        await handleApiError(response!, action, "hyperdrive", id);
+      }
+
+      const data: { result: Record<string, any> } = await response!.json();
+      apiResource = data.result;
+    } catch (error) {
+      console.error(`Error ${this.phase} Hyperdrive '${id}':`, error);
+      throw error;
+    }
+
+    // Construct the output object from API response and props
+    return this({
+      id,
+      hyperdriveId: apiResource.id, // Store the Cloudflare-assigned UUID
+      name: apiResource.name,
+      origin: props.origin, // Keep the original origin with secrets
+      caching: apiResource.caching,
+      mtls: apiResource.mtls,
+      type: "hyperdrive",
+    });
+  }
+);
+
+/**
+ * Prepare the request body by unwrapping secret values
+ */
+function prepareRequestBody(props: HyperdriveProps): any {
+  const requestBody: any = { ...props };
+
+  // Remove internal props
+  delete requestBody.hyperdriveId;
+
+  // Deep clone and unwrap secrets in the origin object
+  if ("password" in props.origin) {
+    // Regular origin with password
+    requestBody.origin = {
+      ...props.origin,
+      password: props.origin.password.unencrypted,
+      scheme: props.origin.scheme ?? "postgres",
+    };
+  } else if ("access_client_secret" in props.origin) {
+    // Origin with access client secret
+    requestBody.origin = {
+      ...props.origin,
+      access_client_secret: props.origin.access_client_secret.unencrypted,
+    };
+  }
+
+  return requestBody;
+}

package/src/cloudflare/index.ts

@@ -9,6 +9,7 @@ export * from "./custom-domain.js";
 export * from "./d1-database.js";
 export * from "./dns-records.js";
 export * from "./durable-object-namespace.js";
+export * from "./hyperdrive.js";
 export * from "./kv-namespace.js";
 export * from "./local-dev-cloudflare-shim.js";
 export * from "./nuxt.js";

package/src/cloudflare/worker.ts

@@ -784,6 +784,13 @@ async function prepareWorkerMetadata<B extends Bindings>(
         type: "ai",
         name: bindingName,
       });
+    } else if (binding.type === "hyperdrive") {
+      // Hyperdrive binding
+      meta.bindings.push({
+        type: "hyperdrive",
+        name: bindingName,
+        id: binding.hyperdriveId,
+      });
     } else {
       // @ts-expect-error - we should never reach here
       throw new Error(`Unsupported binding type: ${binding.type}`);

package/src/neon/api-error.ts

@@ -0,0 +1,81 @@
+/**
+ * Error class for Neon API errors
+ */
+export class NeonApiError extends Error {
+  /**
+   * HTTP status code
+   */
+  public readonly status: number;
+
+  /**
+   * HTTP status text
+   */
+  public readonly statusText: string;
+
+  /**
+   * Error data from the API response
+   */
+  public readonly errorData?: any;
+
+  /**
+   * Create a new NeonApiError
+   */
+  constructor(message: string, response: Response, errorData?: any) {
+    super(message);
+    this.name = "NeonApiError";
+    this.status = response.status;
+    this.statusText = response.statusText;
+    this.errorData = errorData;
+
+    // Capture stack trace
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, NeonApiError);
+    }
+  }
+}
+
+/**
+ * Handle API errors and throw NeonApiError with context
+ *
+ * @param response Response object from fetch
+ * @param action Action that was being performed
+ * @param resourceType Type of resource
+ * @param resourceId ID of the resource
+ */
+export async function handleApiError(
+  response: Response,
+  action: "get" | "create" | "update" | "delete" | "list",
+  resourceType: string,
+  resourceId?: string
+): Promise<never> {
+  const resourceDisplay = resourceId ? `'${resourceId}'` : "";
+  let errorData: any;
+
+  try {
+    errorData = await response.json();
+  } catch (e) {
+    // If we can't parse JSON, just use the response text
+    try {
+      errorData = { message: await response.text() };
+    } catch (textError) {
+      errorData = { message: response.statusText };
+    }
+  }
+
+  let message = `Error ${action} ${resourceType} ${resourceDisplay}: `;
+
+  if (errorData?.error?.message) {
+    message += errorData.error.message;
+  } else if (errorData?.message) {
+    message += errorData.message;
+  } else if (errorData?.error) {
+    message +=
+      typeof errorData.error === "string"
+        ? errorData.error
+        : JSON.stringify(errorData.error);
+  } else {
+    message += response.statusText;
+  }
+
+  throw new NeonApiError(message, response, errorData);
+}