alchemy 0.69.0 → 0.70.0

package/src/cloudflare/tanstack-start/tanstack-start.ts

@@ -15,10 +15,21 @@ export async function TanStackStart<B extends Bindings>(
   props?: Partial<TanStackStartProps<B>>,
 ): Promise<TanStackStart<B>> {
   return await Vite(id, {
-    ...props,
+    entrypoint: "dist/server/index.js",
+    assets: "dist/client",
+    compatibility: "node",
     noBundle: true,
-    entrypoint: props?.entrypoint ?? ".output/server/index.mjs",
-    compatibilityFlags: ["nodejs_compat", ...(props?.compatibilityFlags ?? [])],
-    assets: props?.assets ?? ".output/public",
+    spa: false,
+    ...props,
+    wrangler: {
+      ...props?.wrangler,
+      transform: async (spec) => {
+        const transformed = (await props?.wrangler?.transform?.(spec)) ?? spec;
+        if (!props?.wrangler?.main) {
+          transformed.main = "@tanstack/react-start/server-entry";
+        }
+        return transformed;
+      },
+    },
   });
 }

package/src/cloudflare/util/filter-env-bindings.ts

@@ -0,0 +1,96 @@
+import { isSecret, type Secret } from "../../secret.ts";
+import type { Bindings } from "../bindings.ts";
+
+/**
+ * Extract string and Secret bindings from a Bindings object
+ *
+ * This utility filters a Bindings object to return only string values
+ * and optionally Secret objects. All other binding types (workers, KV, R2, etc.)
+ * are excluded from the result.
+ *
+ * @param bindings - The bindings object to filter
+ * @param includeSecrets - Whether to include Secret objects in the result
+ * @returns A record containing only string values and Secret objects (if includeSecrets is true)
+ *
+ * @example
+ * ```typescript
+ * const filtered = extractStringAndSecretBindings(props.bindings, true);
+ * // Returns: { API_KEY: Secret(...), DEBUG: "true" }
+ * // Excludes: { CACHE: KVNamespace, STORAGE: R2Bucket }
+ * ```
+ */
+export function extractStringAndSecretBindings(
+  bindings: Bindings,
+  includeSecrets: boolean,
+): Record<string, string | Secret> {
+  return Object.fromEntries(
+    Object.entries(bindings ?? {}).flatMap(([key, value]) => {
+      if (typeof value === "string" || (isSecret(value) && includeSecrets)) {
+        return [[key, value]];
+      }
+      return [];
+    }),
+  );
+}
+
+/**
+ * Unencrypt all Secret values in an environment object
+ *
+ * Takes a record that may contain Secret objects and returns a new record
+ * with all Secret values replaced by their unencrypted string values.
+ * Non-Secret values are passed through unchanged. Undefined values are filtered out.
+ *
+ * @param env - The environment object that may contain Secret values
+ * @returns A new record with all Secrets replaced by their unencrypted values
+ *
+ * @example
+ * ```typescript
+ * const env = { API_KEY: Secret("abc123"), DEBUG: "true" };
+ * const unencrypted = unencryptSecrets(env);
+ * // Returns: { API_KEY: "abc123", DEBUG: "true" }
+ * ```
+ */
+export function unencryptSecrets(
+  env: Record<string, string | Secret | undefined>,
+): Record<string, string> {
+  return Object.fromEntries(
+    Object.entries(env ?? {}).flatMap(([key, value]) => {
+      if (isSecret(value)) {
+        return [[key, value.unencrypted]];
+      }
+      if (typeof value === "string") {
+        return [[key, value]];
+      }
+      return [];
+    }),
+  );
+}
+
+/**
+ * Filter bindings to strings and unencrypt secrets in one operation
+ *
+ * This is a convenience function that combines extractStringAndSecretBindings
+ * and unencryptSecrets. It filters bindings to strings/secrets and immediately
+ * unencrypts any Secret values.
+ *
+ * Useful for preparing environment variables for dev/build commands where
+ * secrets need to be decrypted and all resource bindings need to be excluded.
+ *
+ * @param bindings - The bindings object to filter
+ * @param includeSecrets - Whether to include (and unencrypt) Secret objects
+ * @returns A record containing only string values with all secrets unencrypted
+ *
+ * @example
+ * ```typescript
+ * const env = filterStringBindings(props.bindings, true);
+ * // Input: { API_KEY: Secret("abc"), DEBUG: "true", CACHE: KVNamespace }
+ * // Returns: { API_KEY: "abc", DEBUG: "true" }
+ * ```
+ */
+export function filterStringBindings(
+  bindings: Bindings,
+  includeSecrets: boolean,
+): Record<string, string> {
+  const extracted = extractStringAndSecretBindings(bindings, includeSecrets);
+  return unencryptSecrets(extracted);
+}

package/src/cloudflare/website.ts

@@ -3,7 +3,6 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { Exec } from "../os/index.ts";
 import { Scope } from "../scope.ts";
-import { isSecret } from "../secret.ts";
 import { dedent } from "../util/dedent.ts";
 import { logger } from "../util/logger.ts";
 import { Assets } from "./assets.ts";
@@ -11,6 +10,10 @@ import type { Bindings } from "./bindings.ts";
 import { DEFAULT_COMPATIBILITY_DATE } from "./compatibility-date.gen.ts";
 import { unionCompatibilityFlags } from "./compatibility-presets.ts";
 import { writeMiniflareSymlink } from "./miniflare/symlink-miniflare-state.ts";
+import {
+  extractStringAndSecretBindings,
+  unencryptSecrets,
+} from "./util/filter-env-bindings.ts";
 import { type AssetsConfig, Worker, type WorkerProps } from "./worker.ts";
 import { WranglerJson, type WranglerJsonSpec } from "./wrangler.json.ts";
 
@@ -67,7 +70,7 @@ export interface WebsiteProps<B extends Bindings>
         /**
          * The command to run to start the dev server
          */
-        command: string;
+        command?: string;
         /**
          * Additional environment variables to set when running the dev command
          */
@@ -226,14 +229,7 @@ export async function Website<B extends Bindings>(
   const env = {
     ...(process.env ?? {}),
     ...(props.env ?? {}),
-    ...Object.fromEntries(
-      Object.entries(props.bindings ?? {}).flatMap(([key, value]) => {
-        if (typeof value === "string" || (isSecret(value) && secrets)) {
-          return [[key, value]];
-        }
-        return [];
-      }),
-    ),
+    ...extractStringAndSecretBindings(props.bindings ?? {}, secrets),
   };
   const worker = {
     ...workerProps,
@@ -302,9 +298,10 @@ export async function Website<B extends Bindings>(
   }
 
   let url: string | undefined;
-  if (dev && scope.local) {
+  const devCommand = typeof dev === "string" ? dev : dev?.command;
+  if (devCommand && scope.local) {
     url = await scope.spawn(name, {
-      cmd: typeof dev === "string" ? dev : dev.command,
+      cmd: devCommand,
       cwd: paths.cwd,
       extract: (line) => {
         const URL_REGEX =
@@ -317,23 +314,14 @@ export async function Website<B extends Bindings>(
         }
       },
       env: {
-        ...Object.fromEntries(
-          Object.entries(env ?? {}).flatMap(([key, value]) => {
-            if (isSecret(value)) {
-              return [[key, value.unencrypted]];
-            }
-            if (typeof value === "string") {
-              return [[key, value]];
-            }
-            return [];
-          }),
-        ),
+        ...unencryptSecrets(env ?? {}),
         ...(typeof dev === "object" ? dev.env : {}),
         FORCE_COLOR: "1",
         ...process.env,
         // NOTE: we must set this to ensure the user does not accidentally set `NODE_ENV=production`
         // which breaks `vite dev` (it won't, for example, re-write `process.env.TSS_APP_BASE` in the `.js` client side bundle)
         NODE_ENV: "development",
+        ALCHEMY_ROOT: Scope.current.rootDir,
       },
     });
   }
@@ -370,7 +358,7 @@ export const spreadBuildProps = (
 export const spreadDevProps = (
   props: { dev?: WebsiteProps<Bindings>["dev"] } | undefined,
   defaultCommand: string,
-): WebsiteProps<Bindings>["dev"] => {
+): Exclude<WebsiteProps<Bindings>["dev"], undefined> => {
   if (typeof props?.dev === "object") {
     return {
       ...props.dev,

package/src/cloudflare/worker-metadata.ts

@@ -18,7 +18,7 @@ import type {
   MultiStepMigration,
   SingleStepMigration,
 } from "./worker-migration.ts";
-import type { AssetsConfig, WorkerProps } from "./worker.ts";
+import { isWorker, type AssetsConfig, type WorkerProps } from "./worker.ts";
 
 /**
  * Metadata returned by Cloudflare API for a worker script
@@ -175,6 +175,7 @@ export interface WorkerDefaultEnvironment extends WorkerEnvironment {
   script: WorkerScriptInfo;
 }
 
+//? (jacob): why is this not using BaseWorkerProps?
 export interface WorkerMetadata {
   compatibility_date: string;
   compatibility_flags?: string[];
@@ -182,6 +183,7 @@ export interface WorkerMetadata {
   observability: {
     enabled: boolean;
   };
+  logpush?: boolean;
   migrations?: SingleStepMigration;
   main_module?: string;
   body_part?: string;
@@ -202,6 +204,7 @@ export interface WorkerMetadata {
   limits?: {
     cpu_ms?: number;
   };
+  tail_consumers?: Array<Worker | { service: string }>;
 }
 
 export async function prepareWorkerMetadata(
@@ -316,10 +319,14 @@ export async function prepareWorkerMetadata(
   const meta: WorkerMetadata = {
     compatibility_date: props.compatibilityDate,
     compatibility_flags: props.compatibilityFlags,
+    tail_consumers: props.tailConsumers?.map((consumer) =>
+      isWorker(consumer) ? { service: consumer.name } : consumer,
+    ),
     bindings: [],
     observability: {
       enabled: props.observability?.enabled !== false,
     },
+    logpush: props.logpush ?? false,
     // TODO(sam): base64 encode instead? 0 collision risk vs readability.
     tags: [
       // encode a mapping table of Durable Object stable ID -> binding name

package/src/cloudflare/worker.ts

@@ -179,6 +179,17 @@ export interface BaseWorkerProps<
     enabled?: boolean;
   };
 
+  /**
+   * Enable Workers Logpush to export trace events (request/response metadata,
+   * console logs, and exceptions) to external destinations.
+   *
+   * Requires a separate Logpush job configuration via the Cloudflare API.
+   *
+   * @see https://developers.cloudflare.com/workers/observability/logging/logpush
+   * @default false
+   */
+  logpush?: boolean;
+
   /**
    * Whether to adopt the Worker if it already exists when creating
    */
@@ -324,7 +335,7 @@ export interface BaseWorkerProps<
   dev?:
     | {
         /**
-         * Port to use for local development
+         * Port to use for local development.
          */
         port?: number;
         /**
@@ -375,6 +386,11 @@ export interface BaseWorkerProps<
      */
     cpu_ms?: number;
   };
+
+  /**
+   * Tail consumers that will receive execution logs from this worker
+   */
+  tailConsumers?: Array<Worker | { service: string }>;
 }
 
 export interface InlineWorkerProps<
@@ -1018,6 +1034,7 @@ const _Worker = Resource(
         props.crons?.map((cron) => ({ cron })) ?? [],
       );
     }
+
     await Promise.all(
       options.workflows.map((workflow) =>
         upsertWorkflow(api, {
@@ -1063,6 +1080,7 @@ const _Worker = Resource(
       url: subdomain?.url,
       assets: props.assets,
       crons: props.crons,
+      tailConsumers: props.tailConsumers,
       routes,
       domains,
       namespace: props.namespace,

package/src/cloudflare/wrangler.json.ts

@@ -4,6 +4,7 @@ import type { Context } from "../context.ts";
 import { Resource } from "../resource.ts";
 import { Scope } from "../scope.ts";
 import { isSecret } from "../secret.ts";
+import { unencryptSecrets } from "./util/filter-env-bindings.ts";
 import { assertNever } from "../util/assert-never.ts";
 import type { Bindings, WorkerBindingRateLimit } from "./bindings.ts";
 import type { R2BucketJurisdiction } from "./bucket.ts";
@@ -11,7 +12,7 @@ import type { DurableObjectNamespace } from "./durable-object-namespace.ts";
 import type { EventSource } from "./event-source.ts";
 import { isQueueEventSource } from "./event-source.ts";
 import { isQueue } from "./queue.ts";
-import type { Worker, WorkerProps } from "./worker.ts";
+import { isWorker, type Worker, type WorkerProps } from "./worker.ts";
 
 type WranglerJsonRateLimit = Omit<WorkerBindingRateLimit, "type"> & {
   type: "rate_limit";
@@ -162,6 +163,7 @@ export async function WranglerJson(
       : undefined,
     placement: worker.placement,
     limits: worker.limits,
+    logpush: worker.logpush,
   };
 
   // Process bindings if they exist
@@ -182,6 +184,15 @@ export async function WranglerJson(
     spec.vars = { ...worker.env };
   }
 
+  if (worker.tailConsumers && worker.tailConsumers.length > 0) {
+    spec.tail_consumers = worker.tailConsumers.map((consumer) => {
+      if (isWorker(consumer)) {
+        return { service: consumer.name };
+      }
+      return { service: consumer.service };
+    });
+  }
+
   if (worker.crons && worker.crons.length > 0) {
     spec.triggers = { crons: worker.crons };
   }
@@ -201,14 +212,7 @@ export async function WranglerJson(
     // but do not modify `finalSpec` so that way secrets aren't written to state unencrypted.
     const withSecretsUnwrapped = {
       ...finalSpec,
-      vars: {
-        ...finalSpec.vars,
-        ...Object.fromEntries(
-          Object.entries(finalSpec.vars ?? {}).map(([key, value]) =>
-            isSecret(value) ? [key, value.unencrypted] : [key, value],
-          ),
-        ),
-      },
+      vars: unencryptSecrets(finalSpec.vars ?? {}),
     };
     await writeJSON(filePath, withSecretsUnwrapped);
   } else {
@@ -266,6 +270,15 @@ export interface WranglerJsonSpec {
     cpu_ms?: number;
   };
 
+  /**
+   * Send Trace Events from this Worker to Workers Logpush.
+   *
+   * This will not configure a corresponding Logpush job automatically.
+   *
+   * @default false
+   */
+  logpush?: boolean;
+
   /**
    * Whether to enable a workers.dev URL for this worker
    */
@@ -485,6 +498,11 @@ export interface WranglerJsonSpec {
     experimental_remote?: boolean;
   }[];
 
+  /**
+   * Tail consumers that will receive execution logs from this worker
+   */
+  tail_consumers?: Array<{ service: string }>;
+
   /**
    * Unsafe bindings section for experimental features
    */

package/src/coinbase/client.ts

@@ -0,0 +1,146 @@
+import type { CdpClient } from "@coinbase/cdp-sdk";
+import type { Secret } from "../secret.ts";
+import { logger } from "../util/logger.ts";
+import { importPeer } from "../util/peer.ts";
+
+export interface CoinbaseClientOptions {
+  /**
+   * CDP API Key ID. If not provided, falls back to CDP_API_KEY_ID environment variable.
+   */
+  apiKeyId?: Secret<string> | string;
+  /**
+   * CDP API Key Secret. If not provided, falls back to CDP_API_KEY_SECRET environment variable.
+   * Must be wrapped in alchemy.secret() for security.
+   */
+  apiKeySecret?: Secret<string>;
+  /**
+   * CDP Wallet Secret. If not provided, falls back to CDP_WALLET_SECRET environment variable.
+   * Must be wrapped in alchemy.secret() for security.
+   */
+  walletSecret?: Secret<string>;
+}
+
+/**
+ * Create an authenticated CDP client
+ *
+ * The CDP SDK automatically looks for these environment variables:
+ * - CDP_API_KEY_ID
+ * - CDP_API_KEY_SECRET
+ * - CDP_WALLET_SECRET
+ *
+ * You can override them by passing values in the options.
+ *
+ * @param options Options for creating the client
+ * @returns An authenticated CDP client
+ */
+export async function createCdpClient(
+  options: CoinbaseClientOptions = {},
+): Promise<CdpClient> {
+  const { CdpClient } = await importPeer(
+    import("@coinbase/cdp-sdk"),
+    "Coinbase resources",
+  );
+
+  // Build options object for CdpClient constructor
+  const clientOptions: {
+    apiKeyId?: string;
+    apiKeySecret?: string;
+    walletSecret?: string;
+  } = {};
+
+  // Only set values if explicitly provided, otherwise let CDP SDK use its defaults
+  if (options.apiKeyId) {
+    clientOptions.apiKeyId =
+      typeof options.apiKeyId === "string"
+        ? options.apiKeyId
+        : options.apiKeyId.unencrypted;
+  }
+
+  if (options.apiKeySecret) {
+    clientOptions.apiKeySecret = options.apiKeySecret.unencrypted;
+  }
+
+  if (options.walletSecret) {
+    clientOptions.walletSecret = options.walletSecret.unencrypted;
+  }
+
+  // CDP SDK will automatically use environment variables if not provided:
+  // CDP_API_KEY_ID, CDP_API_KEY_SECRET, CDP_WALLET_SECRET
+  return new CdpClient(clientOptions);
+}
+
+/**
+ * Handle CDP SDK deletion errors gracefully
+ *
+ * @param error The error from CDP SDK
+ * @param resourceType The type of resource being deleted
+ * @param resourceId The ID or name of the resource
+ */
+export function handleCdpDeleteError(
+  _error: any,
+  resourceType: string,
+  resourceId?: string,
+): void {
+  // CDP SDK doesn't support deleting accounts, so we just log
+  logger.log(
+    `${resourceType} ${resourceId || "unknown"} cannot be deleted from CDP (CDP limitation)`,
+  );
+}
+
+/**
+ * Check if an error indicates the resource already exists
+ *
+ * @param error The error from CDP SDK
+ * @returns True if the error indicates a conflict/already exists
+ */
+export function isCdpConflictError(error: any): boolean {
+  return (
+    error?.message?.toLowerCase()?.includes("already exists") ||
+    error?.message?.toLowerCase()?.includes("duplicate") ||
+    error?.code === "ALREADY_EXISTS" ||
+    error?.code === "CONFLICT"
+  );
+}
+
+/**
+ * Verifies CDP authentication and provides helpful error messages
+ *
+ * @param client CDP client
+ */
+export async function verifyCdpAuth(client: CdpClient): Promise<void> {
+  try {
+    // Make a test request to check authentication
+    // List accounts is a good test as it requires valid credentials
+    await client.evm.listAccounts();
+  } catch (error: any) {
+    if (error.errorType === "unauthorized") {
+      logger.error(
+        "\n⚠️ Coinbase CDP authentication failed. Please check your credentials:",
+      );
+      logger.error("1. Ensure CDP_API_KEY_ID is set with your API Key ID");
+      logger.error(
+        "2. Ensure CDP_API_KEY_SECRET is set with your API Key Secret",
+      );
+      logger.error(
+        "3. Ensure CDP_WALLET_SECRET is set with your Wallet Secret",
+      );
+      logger.error(
+        "\nTo create API credentials, visit: https://portal.cdp.coinbase.com/",
+      );
+      logger.error(
+        "Required permissions: Account management and transaction signing\n",
+      );
+      throw new Error("CDP authentication failed");
+    }
+    if (error.errorType === "unauthorized") {
+      logger.error(
+        "\n⚠️ Insufficient permissions. Your API key needs account management permissions.",
+      );
+      logger.error(
+        "Make sure your API key has the required scopes for creating and managing accounts\n",
+      );
+      throw new Error("Insufficient CDP permissions");
+    }
+    throw error;
+  }
+}