alchemy 0.30.0 → 0.30.1

package/src/cloudflare/bindings.ts

@@ -15,16 +15,17 @@ import type { D1DatabaseResource } from "./d1-database.ts";
 import type { DispatchNamespaceResource } from "./dispatch-namespace.ts";
 import type { DurableObjectNamespace } from "./durable-object-namespace.ts";
 import type { HyperdriveResource } from "./hyperdrive.ts";
+import type { Images } from "./images.ts";
 import type { KVNamespaceResource } from "./kv-namespace.ts";
 import type { PipelineResource } from "./pipeline.ts";
 import type { QueueResource } from "./queue.ts";
+import type { SecretKey } from "./secret-key.ts";
+import type { Secret as CloudflareSecret } from "./secret.ts";
 import type { VectorizeIndexResource } from "./vectorize-index.ts";
 import type { VersionMetadata } from "./version-metadata.ts";
 import type { WorkerStub } from "./worker-stub.ts";
 import type { Worker, WorkerRef } from "./worker.ts";
 import type { Workflow } from "./workflow.ts";
-import type { Images } from "./images.ts";
-import type { Secret as CloudflareSecret } from "./secret.ts";
 
 export type Bindings = {
   [bindingName: string]: Binding;
@@ -59,6 +60,7 @@ export type Binding =
       id: string;
     }
   | Secret
+  | SecretKey
   | string
   | VectorizeIndexResource
   | Worker
@@ -105,6 +107,7 @@ export type WorkerBindingSpec =
   | WorkerBindingPlainText
   | WorkerBindingQueue
   | WorkerBindingR2Bucket
+  | WorkerBindingSecretKey
   | WorkerBindingSecretText
   | WorkerBindingSecretsStore
   | WorkerBindingSecretsStoreSecret
@@ -291,6 +294,35 @@ export interface WorkerBindingR2Bucket {
   bucket_name: string;
 }
 
+/**
+ * Secret Key binding type
+ */
+export interface WorkerBindingSecretKey {
+  /** The name of the binding */
+  name: string;
+  /** Type identifier for Secret Key binding */
+  type: "secret_key";
+  /** Algorithm-specific key parameters */
+  algorithm: unknown;
+  /** Data format of the key */
+  format: "raw" | "pkcs8" | "spki" | "jwk";
+  /** Allowed operations with the key */
+  usages: Array<
+    | "encrypt"
+    | "decrypt"
+    | "sign"
+    | "verify"
+    | "deriveKey"
+    | "deriveBits"
+    | "wrapKey"
+    | "unwrapKey"
+  >;
+  /** Base64-encoded key data. Required if format is "raw", "pkcs8", or "spki" */
+  key_base64?: string;
+  /** Key data in JSON Web Key format. Required if format is "jwk" */
+  key_jwk?: unknown;
+}
+
 /**
  * Secret Text binding type
  */

package/src/cloudflare/bound.ts

@@ -1,6 +1,5 @@
 import type { Pipeline } from "cloudflare:pipelines";
 import type { Secret } from "../secret.ts";
-import type { Secret as CloudflareSecret } from "./secret.ts";
 import type { AiGatewayResource as _AiGateway } from "./ai-gateway.ts";
 import type { Ai as _Ai } from "./ai.ts";
 import type { AnalyticsEngineDataset as _AnalyticsEngineDataset } from "./analytics-engine.ts";
@@ -15,6 +14,8 @@ import type { HyperdriveResource as _Hyperdrive } from "./hyperdrive.ts";
 import type { Images as _Images } from "./images.ts";
 import type { PipelineResource as _Pipeline } from "./pipeline.ts";
 import type { QueueResource as _Queue } from "./queue.ts";
+import type { SecretKey } from "./secret-key.ts";
+import type { Secret as CloudflareSecret } from "./secret.ts";
 import type { VectorizeIndexResource as _VectorizeIndex } from "./vectorize-index.ts";
 import type { VersionMetadata as _VersionMetadata } from "./version-metadata.ts";
 import type { Worker as _Worker, WorkerRef } from "./worker.ts";
@@ -46,35 +47,37 @@ export type Bound<T extends Binding> = T extends _DurableObjectNamespace<
               : T extends Secret
                 ? string
                 : T extends CloudflareSecret
-                  ? string
-                  : T extends Assets
-                    ? Service
-                    : T extends _Workflow<infer P>
-                      ? Workflow<P>
-                      : T extends D1DatabaseResource
-                        ? D1Database
-                        : T extends DispatchNamespaceResource
-                          ? { get(name: string): Fetcher }
-                          : T extends _VectorizeIndex
-                            ? VectorizeIndex
-                            : T extends _Queue<infer Body>
-                              ? Queue<Body>
-                              : T extends _AnalyticsEngineDataset
-                                ? AnalyticsEngineDataset
-                                : T extends _Pipeline<infer R>
-                                  ? Pipeline<R>
-                                  : T extends string
-                                    ? string
-                                    : T extends BrowserRendering
-                                      ? Fetcher
-                                      : T extends _Ai<infer M>
-                                        ? Ai<M>
-                                        : T extends _Images
-                                          ? ImagesBinding
-                                          : T extends _VersionMetadata
-                                            ? WorkerVersionMetadata
-                                            : T extends Self
-                                              ? Service
-                                              : T extends Json<infer T>
-                                                ? T
-                                                : Service;
+                  ? SecretsStoreSecret
+                  : T extends SecretKey
+                    ? CryptoKey
+                    : T extends Assets
+                      ? Service
+                      : T extends _Workflow<infer P>
+                        ? Workflow<P>
+                        : T extends D1DatabaseResource
+                          ? D1Database
+                          : T extends DispatchNamespaceResource
+                            ? { get(name: string): Fetcher }
+                            : T extends _VectorizeIndex
+                              ? VectorizeIndex
+                              : T extends _Queue<infer Body>
+                                ? Queue<Body>
+                                : T extends _AnalyticsEngineDataset
+                                  ? AnalyticsEngineDataset
+                                  : T extends _Pipeline<infer R>
+                                    ? Pipeline<R>
+                                    : T extends string
+                                      ? string
+                                      : T extends BrowserRendering
+                                        ? Fetcher
+                                        : T extends _Ai<infer M>
+                                          ? Ai<M>
+                                          : T extends _Images
+                                            ? ImagesBinding
+                                            : T extends _VersionMetadata
+                                              ? WorkerVersionMetadata
+                                              : T extends Self
+                                                ? Service
+                                                : T extends Json<infer T>
+                                                  ? T
+                                                  : Service;

package/src/cloudflare/index.ts

@@ -39,6 +39,7 @@ export * from "./react-router.ts";
 export * from "./redwood.ts";
 export * from "./route.ts";
 export * from "./secret.ts";
+export * from "./secret-key.ts";
 export * from "./secrets-store.ts";
 export * from "./sveltekit.ts";
 export * from "./tanstack-start.ts";

package/src/cloudflare/queue.ts

@@ -176,6 +176,30 @@ export type Queue<Body = unknown> = QueueResource<Body> &
  *   dlq: dlqQueue
  * });
  *
+ * @example
+ * // Create a queue and configure Worker consumer with custom settings
+ * const processingQueue = await Queue("processing-queue", {
+ *   name: "processing-queue"
+ * });
+ *
+ * const processingWorker = await Worker("processor", {
+ *   entrypoint: "./src/processor.ts",
+ *   bindings: {
+ *     QUEUE: processingQueue  // Producer: bind queue for sending messages
+ *   },
+ *   eventSources: [{  // Consumer: configure processing settings
+ *     queue: processingQueue,
+ *     settings: {
+ *       batchSize: 25,           // Process 25 messages at once
+ *       maxConcurrency: 5,       // Allow 5 concurrent invocations
+ *       maxRetries: 3,           // Retry failed messages up to 3 times
+ *       maxWaitTimeMs: 1500,     // Wait up to 1.5 seconds to fill a batch
+ *       retryDelay: 45,          // Wait 45 seconds before retrying failed messages
+ *       deadLetterQueue: "failed-processing" // Send failed messages to DLQ
+ *     }
+ *   }]
+ * });
+ *
  * @see https://developers.cloudflare.com/queues/
  */
 export async function Queue<Body = unknown>(

package/src/cloudflare/secret-key.ts

@@ -0,0 +1,143 @@
+/**
+ * SecretKey binding for Cloudflare Workers
+ *
+ * A data class that represents a secret key binding with cryptographic properties.
+ * Keys are securely stored and exposed as CryptoKey objects for use with the Web Crypto API.
+ *
+ * @example
+ * // Create an RSA signing key from a JWK format:
+ * const keyPair = await crypto.subtle.generateKey(
+ *   {
+ *     name: "RSA-PSS",
+ *     modulusLength: 2048,
+ *     publicExponent: new Uint8Array([1, 0, 1]),
+ *     hash: "SHA-256",
+ *   },
+ *   true,
+ *   ["sign", "verify"]
+ * );
+ *
+ * const privateKeyJwk = await crypto.subtle.exportKey("jwk", keyPair.privateKey);
+ *
+ * const signingKey = new SecretKey({
+ *   algorithm: { name: "RSA-PSS", hash: "SHA-256" },
+ *   format: "jwk",
+ *   usages: ["sign"],
+ *   key_jwk: secret(privateKeyJwk),
+ * });
+ *
+ * @example
+ * // Create an AES encryption key from raw bytes:
+ * const aesKey = await crypto.subtle.generateKey(
+ *   { name: "AES-GCM", length: 256 },
+ *   true,
+ *   ["encrypt", "decrypt"]
+ * );
+ *
+ * const keyData = await crypto.subtle.exportKey("raw", aesKey);
+ * const keyBase64 = btoa(String.fromCharCode(...new Uint8Array(keyData)));
+ *
+ * const encryptionKey = new SecretKey({
+ *   algorithm: { name: "AES-GCM" },
+ *   format: "raw",
+ *   usages: ["encrypt", "decrypt"],
+ *   key_base64: secret(keyBase64),
+ * });
+ *
+ * @example
+ * // Create an ECDSA key from PKCS#8 format:
+ * const ecdsaKey = new SecretKey({
+ *   algorithm: { name: "ECDSA", namedCurve: "P-256" },
+ *   format: "pkcs8",
+ *   usages: ["sign"],
+ *   key_base64: secret("MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQg..."),
+ * });
+ *
+ * @example
+ * // Create an HMAC key for message authentication:
+ * const hmacKey = await crypto.subtle.generateKey(
+ *   { name: "HMAC", hash: "SHA-256" },
+ *   true,
+ *   ["sign", "verify"]
+ * );
+ *
+ * const keyData = await crypto.subtle.exportKey("raw", hmacKey);
+ * const keyBase64 = btoa(String.fromCharCode(...new Uint8Array(keyData)));
+ *
+ * const macKey = new SecretKey({
+ *   algorithm: { name: "HMAC", hash: "SHA-256" },
+ *   format: "raw",
+ *   usages: ["sign", "verify"],
+ *   key_base64: secret(keyBase64),
+ * });
+ *
+ * @see https://developers.cloudflare.com/api/resources/workers/subresources/scripts/methods/update/
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/importKey#keyusages
+ */
+
+import type { Secret } from "../secret.ts";
+
+/**
+ * Data format of the key
+ */
+export type SecretKeyFormat = "raw" | "pkcs8" | "spki" | "jwk";
+
+/**
+ * Allowed operations with the key
+ */
+export type SecretKeyUsage =
+  | "encrypt"
+  | "decrypt"
+  | "sign"
+  | "verify"
+  | "deriveKey"
+  | "deriveBits"
+  | "wrapKey"
+  | "unwrapKey";
+
+/**
+ * SecretKey binding properties
+ */
+export interface SecretKeyProps {
+  /**
+   * Algorithm-specific key parameters
+   */
+  algorithm: unknown;
+
+  /**
+   * Data format of the key
+   */
+  format: SecretKeyFormat;
+
+  /**
+   * Allowed operations with the key
+   */
+  usages: SecretKeyUsage[];
+
+  /**
+   * Base64-encoded key data. Required if format is "raw", "pkcs8", or "spki"
+   */
+  key_base64?: Secret;
+
+  /**
+   * Key data in JSON Web Key format. Required if format is "jwk"
+   */
+  key_jwk?: Secret<JsonWebKey>;
+}
+
+export class SecretKey {
+  readonly type = "secret_key";
+  readonly algorithm: unknown;
+  readonly format: SecretKeyFormat;
+  readonly usages: SecretKeyUsage[];
+  readonly key_base64?: Secret;
+  readonly key_jwk?: Secret<JsonWebKey>;
+
+  constructor(props: SecretKeyProps) {
+    this.algorithm = props.algorithm;
+    this.format = props.format;
+    this.usages = props.usages;
+    this.key_base64 = props.key_base64;
+    this.key_jwk = props.key_jwk;
+  }
+}

package/src/cloudflare/secret.ts

@@ -10,7 +10,7 @@ import {
   type CloudflareApi,
   type CloudflareApiOptions,
 } from "./api.ts";
-import type { SecretsStore } from "./secrets-store.ts";
+import { findSecretsStoreByName, SecretsStore } from "./secrets-store.ts";
 
 /**
  * Properties for creating or updating a Secret in a Secrets Store (internal interface)
@@ -18,8 +18,10 @@ import type { SecretsStore } from "./secrets-store.ts";
 interface _SecretProps extends CloudflareApiOptions {
   /**
    * The secrets store to add this secret to
+   *
+   * @default - the default-secret-store
    */
-  store: SecretsStore<any>;
+  store?: SecretsStore<any>;
 
   /**
    * The secret value to store (must be an AlchemySecret for security)
@@ -41,8 +43,10 @@ interface _SecretProps extends CloudflareApiOptions {
 export interface SecretProps extends CloudflareApiOptions {
   /**
    * The secrets store to add this secret to
+   *
+   * @default - the default-secret-store
    */
-  store: SecretsStore<any>;
+  store?: SecretsStore<any>;
 
   /**
    * The secret value to store
@@ -71,39 +75,38 @@ export function isSecret(resource: Resource): resource is Secret {
   return resource[ResourceKind] === "cloudflare::Secret";
 }
 
-export interface Secret
-  extends Resource<"cloudflare::Secret">,
-    Omit<_SecretProps, "delete"> {
-  /**
-   * The binding type for Cloudflare Workers
-   */
-  type: "secrets_store_secret";
-
-  /**
-   * The name of the secret
-   */
-  name: string;
-
-  /**
-   * The unique identifier of the secrets store this secret belongs to
-   */
-  storeId: string;
-
-  /**
-   * The secret value (as an alchemy Secret instance)
-   */
-  value: AlchemySecret;
-
-  /**
-   * Timestamp when the secret was created
-   */
-  createdAt: number;
-
-  /**
-   * Timestamp when the secret was last modified
-   */
-  modifiedAt: number;
-}
+export type Secret = Resource<"cloudflare::Secret"> &
+  Omit<_SecretProps, "delete"> & {
+    /**
+     * The binding type for Cloudflare Workers
+     */
+    type: "secrets_store_secret";
+
+    /**
+     * The name of the secret
+     */
+    name: string;
+
+    /**
+     * The unique identifier of the secrets store this secret belongs to
+     */
+    storeId: string;
+
+    /**
+     * The secret value (as an alchemy Secret instance)
+     */
+    value: AlchemySecret;
+
+    /**
+     * Timestamp when the secret was created
+     */
+    createdAt: number;
+
+    /**
+     * Timestamp when the secret was last modified
+     */
+    modifiedAt: number;
+  };
 
 /**
  * A Cloudflare Secret represents an individual secret stored in a Secrets Store.
@@ -179,9 +182,20 @@ const _Secret = Resource(
   ): Promise<Secret> {
     const api = await createCloudflareApi(props);
 
+    const storeId =
+      props.store?.id ??
+      (await findSecretsStoreByName(api, SecretsStore.Default))?.id ??
+      (
+        await SecretsStore("default-store", {
+          name: SecretsStore.Default,
+          adopt: true,
+          delete: false,
+        })
+      )?.id!;
+
     if (this.phase === "delete") {
       if (props.delete !== false) {
-        await deleteSecret(api, props.store.id, name);
+        await deleteSecret(api, storeId, name);
       }
       return this.destroy();
     }
@@ -192,12 +206,12 @@ const _Secret = Resource(
         : Date.now();
 
     // Insert or update the secret
-    await insertSecret(api, props.store.id, name, props.value);
+    await insertSecret(api, storeId, name, props.value);
 
     return this({
       type: "secrets_store_secret",
       name,
-      storeId: props.store.id,
+      storeId,
       store: props.store,
       value: props.value,
       createdAt,
@@ -317,10 +331,10 @@ export async function deleteSecret(
   storeId: string,
   secretName: string,
 ): Promise<void> {
+  const secretId = await getSecretId(api, storeId, secretName);
   const response = await api.delete(
-    `/accounts/${api.accountId}/secrets_store/stores/${storeId}/secrets`,
+    `/accounts/${api.accountId}/secrets_store/stores/${storeId}/secrets/${secretId}`,
     {
-      body: JSON.stringify([secretName]),
       headers: {
         "Content-Type": "application/json",
       },

package/src/cloudflare/secrets-store.ts

@@ -168,6 +168,10 @@ export async function SecretsStore<
   return _SecretsStore(name, normalizedProps);
 }
 
+export namespace SecretsStore {
+  export const Default = "default_secrets_store";
+}
+
 const _SecretsStore = Resource("cloudflare::SecretsStore", async function <
   S extends Record<string, Secret> | undefined = undefined,
 >(this: Context<SecretsStore<S>>, id: string, props: SecretsStoreProps<S>): Promise<
@@ -206,17 +210,12 @@ const _SecretsStore = Resource("cloudflare::SecretsStore", async function <
   } else {
     // If adopt is true, first check if a store with this name already exists
     if (props.adopt) {
-      console.log(`Checking for existing secrets store '${name}' to adopt`);
       const existingStore = await findSecretsStoreByName(api, name);
 
       if (existingStore) {
-        console.log(`Found existing secrets store '${name}', adopting it`);
         storeId = existingStore.id;
         createdAt = existingStore.createdAt || Date.now();
       } else {
-        console.log(
-          `No existing secrets store '${name}' found, creating new one`,
-        );
         const { id } = await createSecretsStore(api, {
           ...props,
           name,

package/src/cloudflare/worker-metadata.ts

@@ -484,6 +484,16 @@ export async function prepareWorkerMetadata<B extends Bindings>(
         name: bindingName,
         namespace: binding.namespaceName,
       });
+    } else if (binding.type === "secret_key") {
+      meta.bindings.push({
+        type: "secret_key",
+        name: bindingName,
+        algorithm: binding.algorithm,
+        format: binding.format,
+        usages: binding.usages,
+        key_base64: binding.key_base64?.unencrypted,
+        key_jwk: binding.key_jwk?.unencrypted,
+      });
     } else {
       // @ts-expect-error - we should never reach here
       throw new Error(`Unsupported binding type: ${binding.type}`);

package/src/cloudflare/worker.ts

@@ -599,8 +599,36 @@ export function WorkerRef<
  *   }
  * });
  *
- * @see
- * https://developers.cloudflare.com/workers/
+ * @example
+ * // Create a worker with queue event sources and custom consumer settings:
+ * const taskQueue = await Queue("task-queue", {
+ *   name: "task-queue"
+ * });
+ *
+ * const dlq = await Queue("failed-tasks", {
+ *   name: "failed-tasks"
+ * });
+ *
+ * const queueWorker = await Worker("queue-processor", {
+ *   name: "queue-processor",
+ *   entrypoint: "./src/processor.ts",
+ *   bindings: {
+ *     TASK_QUEUE: taskQueue  // Producer: bind queue for sending messages
+ *   },
+ *   eventSources: [{  // Consumer: configure processing settings
+ *     queue: taskQueue,
+ *     settings: {
+ *       batchSize: 15,           // Process 15 messages at once
+ *       maxConcurrency: 3,       // Allow 3 concurrent invocations
+ *       maxRetries: 5,           // Retry failed messages up to 5 times
+ *       maxWaitTimeMs: 2500,     // Wait up to 2.5 seconds to fill a batch
+ *       retryDelay: 60,          // Wait 60 seconds before retrying failed messages
+ *       deadLetterQueue: dlq     // Send failed messages to dead letter queue
+ *     }
+ *   }]
+ * });
+ *
+ * @see https://developers.cloudflare.com/workers/
  */
 export function Worker<
   const B extends Bindings,

package/src/cloudflare/wrangler.json.ts

@@ -607,6 +607,8 @@ function processBindings(
         binding: bindingName,
         namespace: binding.namespaceName,
       });
+    } else if (binding.type === "secret_key") {
+      // no-op
     } else {
       // biome-ignore lint/correctness/noVoidTypeReturn: it returns never
       return assertNever(binding);

package/src/secret.ts

@@ -8,7 +8,7 @@ declare global {
 
 // a global registry of all secrets that we will use when serializing an application
 const globalSecrets: {
-  [name: string]: Secret;
+  [name: string]: Secret<any>;
 } = (globalThis.__ALCHEMY_SECRETS__ ??= {});
 
 let i = 0;
@@ -53,19 +53,19 @@ const SecretSymbol = Symbol.for("alchemy::Secret");
  *   }
  * }
  */
-export class Secret {
+export class Secret<T = string> {
   [SecretSymbol] = true;
 
   /**
    * @internal
    */
-  public static all(): Secret[] {
+  public static all(): Secret<any>[] {
     return Object.values(globalSecrets);
   }
 
   public readonly type = "secret";
   constructor(
-    readonly unencrypted: string,
+    readonly unencrypted: T,
     readonly name: string = nextName(),
   ) {
     globalSecrets[name] = this;
@@ -111,10 +111,10 @@ export function isSecret(binding: any): binding is Secret {
  * @throws {Error} If the value is undefined
  * @throws {Error} If no password is set in the alchemy application options or current scope
  */
-export function secret<S extends string | undefined>(
-  unencrypted: S,
+export function secret<S = string>(
+  unencrypted: S | undefined,
   name?: string,
-): Secret {
+): Secret<S> {
   if (unencrypted === undefined) {
     throw new Error("Secret cannot be undefined");
   }