alchemy 0.69.0 → 0.70.0

package/src/coinbase/faucet.ts

@@ -0,0 +1,173 @@
+#!/usr/bin/env bun
+/**
+ * Request testnet tokens from Coinbase faucet for accounts with faucet metadata
+ *
+ * Usage:
+ *   bun node_modules/alchemy/src/coinbase/faucet.ts              # Fund all accounts with faucet config
+ *   bun node_modules/alchemy/src/coinbase/faucet.ts dev          # Fund only accounts in dev scope
+ *   bun node_modules/alchemy/src/coinbase/faucet.ts backend/dev  # Fund specific scope
+ */
+
+import { readFile, access } from "node:fs/promises";
+import { join } from "node:path";
+import { glob } from "glob";
+import { createCdpClient } from "./client.ts";
+import type { EvmAccount } from "./evm-account.ts";
+import type { EvmSmartAccount } from "./evm-smart-account.ts";
+import type { FaucetNetwork, FaucetToken } from "./types.ts";
+
+// Track funded combinations to avoid duplicates within this run
+const funded = new Set<string>();
+
+// Get optional scope argument
+const scope = process.argv[2];
+
+// Initialize CDP client (uses CDP_* env vars automatically)
+const cdp = await createCdpClient();
+
+let stateFiles: string[];
+
+if (scope) {
+  // If scope provided, find matching directories
+  const scopePath = join(".alchemy", scope);
+
+  let scopeExists = false;
+  try {
+    await access(scopePath);
+    scopeExists = true;
+  } catch {
+    scopeExists = false;
+  }
+
+  if (scopeExists) {
+    // Exact match found
+    console.log(`Using scope: ${scope}`);
+    stateFiles = await glob("*.json", {
+      cwd: scopePath,
+      absolute: true,
+    });
+  } else {
+    // Try to find directories that end with the provided scope
+    // We need to find directories, so we'll look for JSON files and extract the directory paths
+    const allFiles = await glob(`**/${scope}/*.json`, {
+      cwd: ".alchemy",
+    });
+
+    // Extract unique directory paths
+    const possibleScopes = [
+      ...new Set(allFiles.map((f) => f.replace(/\/[^/]+\.json$/, ""))),
+    ];
+
+    if (possibleScopes.length === 0) {
+      console.error(`No scope found matching: ${scope}`);
+      process.exit(1);
+    } else if (possibleScopes.length === 1) {
+      // Found exactly one match
+      const foundScope = possibleScopes[0];
+      console.log(`Using scope: ${foundScope}`);
+      stateFiles = await glob("*.json", {
+        cwd: join(".alchemy", foundScope),
+        absolute: true,
+      });
+    } else {
+      // Multiple matches found - use all of them
+      console.log(`Found ${possibleScopes.length} scopes matching '${scope}':`);
+      for (const s of possibleScopes) {
+        console.log(`  - ${s}`);
+      }
+
+      // Collect state files from all matching scopes
+      stateFiles = [];
+      for (const foundScope of possibleScopes) {
+        const files = await glob("*.json", {
+          cwd: join(".alchemy", foundScope),
+          absolute: true,
+        });
+        stateFiles.push(...files);
+      }
+    }
+  }
+} else {
+  // No scope provided, search all .alchemy subdirectories
+  console.log("Searching all scopes for accounts with faucet configuration...");
+  stateFiles = await glob("**/*.json", {
+    cwd: ".alchemy",
+    absolute: true,
+  });
+}
+
+const allStates = (
+  await Promise.all(
+    stateFiles.map(async (file) => {
+      try {
+        const content = await readFile(file, "utf-8");
+        return JSON.parse(content);
+      } catch {
+        return null;
+      }
+    }),
+  )
+).filter(Boolean);
+
+const accounts = allStates
+  .filter(
+    (state) =>
+      state?.kind?.startsWith("coinbase::evm") &&
+      state.output &&
+      (state.output as EvmAccount | EvmSmartAccount).faucet,
+  )
+  .map((state) => {
+    const output = state.output as EvmAccount | EvmSmartAccount;
+    return {
+      address: output.address,
+      name: output.name,
+      faucet: output.faucet!,
+    };
+  });
+
+if (accounts.length === 0) {
+  console.log("No accounts with faucet configuration found");
+  process.exit(0);
+}
+
+console.log(`Found ${accounts.length} accounts with faucet configuration\n`);
+
+for (const account of accounts) {
+  console.log(`Account: ${account.name} (${account.address})`);
+
+  for (const [network, tokens] of Object.entries(account.faucet)) {
+    for (const token of tokens) {
+      const key = `${account.address}-${network}-${token}`;
+
+      // Skip if already processed in this run
+      if (funded.has(key)) {
+        console.log(`  ⏭️  Skipping ${token} on ${network} (already requested)`);
+        continue;
+      }
+
+      // Request tokens from faucet
+      try {
+        console.log(`  💧 Requesting ${token} on ${network}...`);
+
+        const response = await cdp.evm.requestFaucet({
+          address: account.address,
+          network: network as FaucetNetwork,
+          token: token as FaucetToken,
+        });
+
+        console.log(`  ✅ Funded: ${response.transactionHash}`);
+        funded.add(key);
+
+        // Small delay to avoid rate limits
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+      } catch (error: any) {
+        console.log(
+          `  ❌ Error funding ${token} on ${network}: ${error.message}`,
+        );
+      }
+    }
+  }
+  console.log();
+}
+
+console.log("✨ Funding complete!");

package/src/coinbase/index.ts

@@ -0,0 +1,3 @@
+export * from "./types.ts";
+export * from "./evm-account.ts";
+export * from "./evm-smart-account.ts";

package/src/coinbase/types.ts

@@ -0,0 +1,33 @@
+/**
+ * Common types for Coinbase CDP resources
+ */
+
+/**
+ * Ethereum address format (20 bytes, 40 hex chars)
+ */
+export type Address = `0x${string}`;
+
+/**
+ * Private key format (32 bytes, 64 hex chars)
+ */
+export type PrivateKey = `0x${string}`;
+
+/**
+ * Transaction hash format (32 bytes, 64 hex chars)
+ */
+export type TransactionHash = `0x${string}`;
+
+/**
+ * Supported testnet networks for faucet requests
+ */
+export type FaucetNetwork = "base-sepolia" | "ethereum-sepolia";
+
+/**
+ * Supported tokens for faucet requests
+ */
+export type FaucetToken = "eth" | "usdc" | "eurc" | "cbbtc";
+
+/**
+ * Faucet configuration for requesting testnet tokens
+ */
+export type FaucetConfig = Partial<Record<FaucetNetwork, FaucetToken[]>>;

package/src/coinbase/utils.ts

@@ -0,0 +1,19 @@
+/**
+ * Utility functions for Coinbase CDP resources
+ */
+
+/**
+ * Validates that a CDP account name follows the required format.
+ * CDP only allows letters, numbers, and hyphens in account names.
+ * Names cannot start or end with a hyphen.
+ *
+ * @param name - The account name to validate
+ * @throws Error if the name contains invalid characters or starts/ends with hyphen
+ */
+export function validateAccountName(name: string): void {
+  if (!/^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$/.test(name)) {
+    throw new Error(
+      `Invalid account name '${name}'. CDP only allows letters, numbers, and hyphens. Names cannot start or end with a hyphen.`,
+    );
+  }
+}

package/src/docker/api.ts

@@ -3,6 +3,41 @@ import { Buffer } from "node:buffer";
 import { spawn } from "node:child_process";
 import fs from "node:fs/promises";
 import path from "node:path";
+import type { Duration, HealthcheckConfig } from "./container.ts";
+
+/**
+ * Normalize a duration value to Docker CLI format
+ * Accepts either a number (seconds) or a string with unit suffix (ms|s|m|h)
+ * Returns a string in Docker CLI format
+ *
+ * The Duration type provides compile-time type safety, ensuring only valid
+ * formats are accepted: number or string matching the pattern `${number}${unit}`
+ *
+ * @param duration Duration value (number in seconds or string with unit)
+ * @returns Normalized duration string for Docker CLI
+ *
+ * @example
+ * normalizeDuration(30) // "30s"
+ * normalizeDuration("30s") // "30s"
+ * normalizeDuration("1m") // "1m"
+ * normalizeDuration("500ms") // "500ms"
+ * normalizeDuration("1.5s") // "1.5s"
+ */
+export function normalizeDuration(duration: Duration): string {
+  if (typeof duration === "number") {
+    return `${duration}s`;
+  }
+
+  // Validate string format: must be a number followed by unit (ms|s|m|h)
+  const match = duration.match(/^(\d+(?:\.\d+)?)(ms|s|m|h)$/);
+  if (!match) {
+    throw new Error(
+      `Invalid duration format: "${duration}". Expected format: number followed by unit (ms|s|m|h), e.g., "30s", "1m", "500ms"`,
+    );
+  }
+
+  return duration;
+}
 
 /**
  * Options for Docker API requests
@@ -59,7 +94,10 @@ export class DockerApi {
    * @param args Command arguments to pass to Docker CLI
    * @returns Result of the command
    */
-  async exec(args: string[]): Promise<{ stdout: string; stderr: string }> {
+  async exec(
+    args: string[],
+    remainingAttempts = 3,
+  ): Promise<{ stdout: string; stderr: string }> {
     // If a custom config directory is provided, ensure all commands use it by
     // setting the DOCKER_CONFIG env variable for the spawned process.
     const env = this.configDir
@@ -94,8 +132,16 @@ export class DockerApi {
     try {
       await subprocess;
     } catch (error: any) {
+      const message = stderr || error.message || "Command failed";
+      if (
+        message.includes("unexpected status from HEAD request") &&
+        remainingAttempts > 0
+      ) {
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+        return this.exec(args, remainingAttempts - 1);
+      }
       // Process failed, but we still have the output
-      throw new Error(stderr || error.message || "Command failed");
+      throw new Error(message);
     }
 
     return { stdout, stderr };
@@ -177,6 +223,7 @@ export class DockerApi {
       env?: Record<string, string>;
       volumes?: Record<string, string>;
       cmd?: string[];
+      healthcheck?: HealthcheckConfig;
     } = {},
   ): Promise<string> {
     const args = ["create", "--name", name];
@@ -202,6 +249,43 @@ export class DockerApi {
       }
     }
 
+    // Add healthcheck configuration
+    if (options.healthcheck) {
+      const hc = options.healthcheck;
+
+      // Format the cmd
+      const cmdStr = Array.isArray(hc.cmd) ? hc.cmd.join(" ") : hc.cmd;
+      args.push("--health-cmd", cmdStr);
+
+      // Add interval
+      if (hc.interval !== undefined) {
+        args.push("--health-interval", normalizeDuration(hc.interval));
+      }
+
+      // Add timeout
+      if (hc.timeout !== undefined) {
+        args.push("--health-timeout", normalizeDuration(hc.timeout));
+      }
+
+      // Add retries
+      if (hc.retries !== undefined) {
+        args.push("--health-retries", String(hc.retries));
+      }
+
+      // Add start period
+      if (hc.startPeriod !== undefined) {
+        args.push("--health-start-period", normalizeDuration(hc.startPeriod));
+      }
+
+      // Add start interval (API 1.44+)
+      if (hc.startInterval !== undefined) {
+        args.push(
+          "--health-start-interval",
+          normalizeDuration(hc.startInterval),
+        );
+      }
+    }
+
     args.push(image);
 
     // Add command if specified

package/src/docker/container.ts

@@ -59,6 +59,62 @@ export interface NetworkMapping {
   aliases?: string[];
 }
 
+/**
+ * Duration value supporting both number (seconds) and string format (value + unit)
+ * Units: ms (milliseconds), s (seconds), m (minutes), h (hours)
+ * Examples: 30, "30s", "1m", "500ms", "2h"
+ */
+export type Duration = number | `${number}${"ms" | "s" | "m" | "h"}`;
+
+/**
+ * Healthcheck configuration
+ */
+export interface HealthcheckConfig {
+  /**
+   * Command to run to check health.
+   * Can be an array of command arguments or a shell command string.
+   * Examples:
+   * - ["curl", "-f", "http://localhost/"]
+   * - "curl -f http://localhost/ || exit 1"
+   */
+  cmd: string[] | string;
+
+  /**
+   * Time between running the check
+   * Can be a number (in seconds) or string with unit (e.g., "30s", "1m")
+   * @default 0
+   */
+  interval?: Duration;
+
+  /**
+   * Maximum time to allow one check to run
+   * Can be a number (in seconds) or string with unit (e.g., "10s", "500ms")
+   * @default 0
+   */
+  timeout?: Duration;
+
+  /**
+   * Consecutive failures needed to report unhealthy
+   */
+  retries?: number;
+
+  /**
+   * Start period for the container to initialize before starting
+   * health-retries countdown
+   * Can be a number (in seconds) or string with unit (e.g., "40s", "1m")
+   * @default 0
+   */
+  startPeriod?: Duration;
+
+  /**
+   * Time between running the check during the start period
+   * Can be a number (in seconds) or string with unit (e.g., "5s", "500ms")
+   * Requires Docker API 1.44+
+   * @default 0
+   */
+  startInterval?: Duration;
+}
+
 /**
  * Properties for creating a Docker container
  */
@@ -115,6 +171,11 @@ export interface ContainerProps {
    * Start the container after creation
    */
   start?: boolean;
+
+  /**
+   * Healthcheck configuration
+   */
+  healthcheck?: HealthcheckConfig;
 }
 
 /**
@@ -172,6 +233,41 @@ export interface Container extends ContainerProps {
  *   restart: "always",
  *   start: true
  * });
+ *
+ * @example
+ * // Create a container with healthcheck using numeric values (seconds)
+ * const healthyContainer = await Container("api", {
+ *   image: "my-api:latest",
+ *   ports: [
+ *     { external: 3000, internal: 3000 }
+ *   ],
+ *   healthcheck: {
+ *     cmd: ["curl", "-f", "http://localhost:3000/health"],
+ *     interval: 30,
+ *     timeout: 10,
+ *     retries: 3,
+ *     startPeriod: 40
+ *   },
+ *   start: true
+ * });
+ *
+ * @example
+ * // Create a container with healthcheck using string duration format
+ * const healthyContainer2 = await Container("api2", {
+ *   image: "my-api:latest",
+ *   ports: [
+ *     { external: 3001, internal: 3000 }
+ *   ],
+ *   healthcheck: {
+ *     cmd: ["curl", "-f", "http://localhost:3000/health"],
+ *     interval: "30s",
+ *     timeout: "10s",
+ *     retries: 3,
+ *     startPeriod: "1m",
+ *     startInterval: "500ms"
+ *   },
+ *   start: true
+ * });
  */
 export const Container = Resource(
   "docker::Container",
@@ -245,6 +341,7 @@ export const Container = Resource(
         env: props.environment,
         volumes: volumeMappings,
         cmd: props.command,
+        healthcheck: props.healthcheck,
       });
 
       // Connect to networks if specified

package/src/neon/api/types.gen.ts

@@ -1899,6 +1899,7 @@ export type BillingAccountState =
 export type BillingSubscriptionType =
   | "UNKNOWN"
   | "direct_sales"
+  | "direct_sales_v3"
   | "aws_marketplace"
   | "free_v2"
   | "free_v3"
@@ -2527,6 +2528,11 @@ export type NeonAuthCreateIntegrationRequest = {
   role_name?: string;
 };
 
+export type EnableNeonAuthIntegrationRequest = {
+  auth_provider: NeonAuthSupportedAuthProvider;
+  database_name?: string;
+};
+
 export type NeonAuthCreateIntegrationResponse = {
   auth_provider: NeonAuthSupportedAuthProvider;
   auth_provider_project_id: string;
@@ -2677,7 +2683,12 @@ export type RoleOperations = RoleResponse & OperationsResponse;
 
 export type JwksCreationOperation = JwksResponse & OperationsResponse;
 
-export type SupportTicketSeverity = "low" | "normal" | "high" | "critical";
+export type SupportTicketSeverity =
+  | "low"
+  | "normal"
+  | "high"
+  | "critical"
+  | "urgent";
 
 export type AnnotationData = {
   object: AnnotationObjectData;
@@ -2758,6 +2769,7 @@ export type Snapshot = {
   source_branch_id?: string;
   created_at: string;
   expires_at?: string;
+  manual?: boolean;
 };
 
 export type SnapshotUpdateRequest = {

package/src/planetscale/api/types.gen.ts

@@ -514,6 +514,10 @@ export type PaginatedPostgresClusterResizeRequest = {
      * The SKU representing the branch cluster for display
      */
     cluster_display_name: string;
+    /**
+     * Whether or not this is a metal database
+     */
+    cluster_metal: boolean;
     /**
      * The total number of replicas
      */
@@ -532,6 +536,10 @@ export type PaginatedPostgresClusterResizeRequest = {
      * The previous SKU representing the branch cluster for display
      */
     previous_cluster_display_name: string;
+    /**
+     * Whether or not the previous SKU was a metal database
+     */
+    previous_cluster_metal: boolean;
     /**
      * The previous total number of replicas
      */
@@ -652,6 +660,10 @@ export type PostgresClusterResizeRequest = {
    * The SKU representing the branch cluster for display
    */
   cluster_display_name: string;
+  /**
+   * Whether or not this is a metal database
+   */
+  cluster_metal: boolean;
   /**
    * The total number of replicas
    */
@@ -670,6 +682,10 @@ export type PostgresClusterResizeRequest = {
    * The previous SKU representing the branch cluster for display
    */
   previous_cluster_display_name: string;
+  /**
+   * Whether or not the previous SKU was a metal database
+   */
+  previous_cluster_metal: boolean;
   /**
    * The previous total number of replicas
    */
@@ -1301,7 +1317,8 @@ export type PostgresClusterExtension = {
       | "milliseconds"
       | "seconds"
       | "select"
-      | "string";
+      | "string"
+      | "time";
     /**
      * The default value of the parameter
      */
@@ -1408,7 +1425,8 @@ export type PostgresClusterParameter = {
     | "milliseconds"
     | "seconds"
     | "select"
-    | "string";
+    | "string"
+    | "time";
   /**
    * The default value of the parameter
    */
@@ -6943,6 +6961,7 @@ export type PaginatedDatabaseWebhook = {
       | "branch.anomaly"
       | "branch.schema_recommendation"
       | "branch.sleeping"
+      | "branch.start_maintenance"
       | "cluster.storage"
       | "database.access_request"
       | "deploy_request.closed"
@@ -7004,6 +7023,7 @@ export type DatabaseWebhook = {
     | "branch.anomaly"
     | "branch.schema_recommendation"
     | "branch.sleeping"
+    | "branch.start_maintenance"
     | "cluster.storage"
     | "database.access_request"
     | "deploy_request.closed"

package/src/planetscale/api.ts

@@ -67,6 +67,7 @@ export function createPlanetScaleClient(
       headers: {
         Authorization: token, // PlanetScale does not use the Bearer prefix
       },
+      throwOnError: true,
     }),
   );
   client.interceptors.error.use((error, response, request) => {

package/src/planetscale/password.ts

@@ -1,8 +1,8 @@
-import { isDeepStrictEqual } from "node:util";
 import { alchemy } from "../alchemy.ts";
 import type { Context } from "../context.ts";
 import { Resource } from "../resource.ts";
 import type { Secret } from "../secret.ts";
+import { diff } from "../util/diff.ts";
 import { lowercaseId } from "../util/nanoid.ts";
 import { createPlanetScaleClient, type PlanetScaleProps } from "./api.ts";
 import type { Branch } from "./branch.ts";
@@ -357,16 +357,3 @@ export const Password = Resource(
     };
   },
 );
-
-/**
- * Returns an array of keys in `b` that are different from `a`.
- */
-const diff = <T>(a: T, b: NoInfer<T>) => {
-  const keys: (keyof T)[] = [];
-  for (const key in a) {
-    if (!isDeepStrictEqual(a[key], b[key])) {
-      keys.push(key);
-    }
-  }
-  return keys;
-};

package/src/resource.ts

@@ -2,6 +2,7 @@ import { apply } from "./apply.ts";
 import type { Context } from "./context.ts";
 import { DestroyStrategy } from "./destroy.ts";
 import { Scope as _Scope, type Scope } from "./scope.ts";
+import { createAndSendEvent } from "./util/telemetry.ts";
 
 declare global {
   var ALCHEMY_PROVIDERS: Map<ResourceKind, Provider<string, any>>;
@@ -178,11 +179,17 @@ export function Resource<
         const error = new Error(
           `Resource ${resourceID} already exists in the stack and is of a different type: '${otherResource?.[ResourceKind]}' !== '${type}'`,
         );
-        scope.telemetryClient.record({
-          event: "resource.error",
-          resource: type,
+        createAndSendEvent(
+          {
+            event: "resource.error",
+            resource: type,
+            phase: scope.phase,
+            status: "unknown",
+            duration: 0,
+            replaced: false,
+          },
           error,
-        });
+        );
         throw error;
       }
     }