alchemy 0.22.3 → 0.23.0

package/src/aws/ssm-parameter.ts

@@ -0,0 +1,315 @@
+import {
+  AddTagsToResourceCommand,
+  DeleteParameterCommand,
+  GetParameterCommand,
+  ParameterAlreadyExists,
+  ParameterNotFound,
+  PutParameterCommand,
+  SSMClient,
+  type Tag,
+} from "@aws-sdk/client-ssm";
+import type { Context } from "../context.ts";
+import { Resource } from "../resource.ts";
+import { type Secret, isSecret } from "../secret.ts";
+import { ignore } from "../util/ignore.ts";
+
+/**
+ * Base properties shared by all SSM Parameter types
+ */
+interface SSMParameterBaseProps {
+  /**
+   * Name of the parameter
+   */
+  name: string;
+
+  /**
+   * Description of the parameter's purpose
+   */
+  description?: string;
+
+  /**
+   * KMS Key ID for SecureString parameters
+   * If not specified, uses the default KMS key for SSM
+   */
+  keyId?: string;
+
+  /**
+   * Parameter tier (Standard or Advanced)
+   * Default: "Standard"
+   */
+  tier?: "Standard" | "Advanced";
+
+  /**
+   * Policies to apply to the parameter (JSON string)
+   */
+  policies?: string;
+
+  /**
+   * Data type for String parameters
+   */
+  dataType?: "text" | "aws:ec2:image";
+
+  /**
+   * Resource tags for the parameter
+   */
+  tags?: Record<string, string>;
+}
+
+/**
+ * Properties for creating or updating an SSM Parameter
+ */
+export type SSMParameterProps =
+  | (SSMParameterBaseProps & {
+      /**
+       * Type of parameter - SecureString for encrypted values
+       */
+      type: "SecureString";
+      /**
+       * Secret value that will be encrypted in AWS SSM and in alchemy state files
+       */
+      value: Secret;
+    })
+  | (SSMParameterBaseProps & {
+      /**
+       * Type of parameter - StringList for arrays of strings
+       */
+      type: "StringList";
+      /**
+       * Array of strings that will be stored as comma-separated values
+       */
+      value: string[];
+    })
+  | (SSMParameterBaseProps & {
+      /**
+       * Type of parameter - String for plain text values
+       * Default: "String"
+       */
+      type?: "String";
+      /**
+       * Plain text value of the parameter
+       */
+      value: string;
+    });
+
+/**
+ * Output returned after SSM Parameter creation/update
+ */
+export type SSMParameter = Resource<"ssm::Parameter"> & {
+  /**
+   * ARN of the parameter
+   */
+  arn: string;
+
+  /**
+   * Version of the parameter
+   */
+  version: number;
+
+  /**
+   * Last modified date
+   */
+  lastModifiedDate: Date;
+} & SSMParameterProps;
+
+/**
+ * AWS SSM Parameter Store Parameter Resource
+ *
+ * Creates and manages SSM parameters with support for different parameter types,
+ * encryption, and automatic tag management. Uses discriminated union types to
+ * ensure SecureString parameters always use Secret values and StringList uses arrays.
+ *
+ * @example
+ * // Create a basic string parameter
+ * const basicParam = await SSMParameter("app-config", {
+ *   name: "/myapp/config/database-url",
+ *   value: "postgresql://localhost:5432/myapp",
+ *   description: "Database connection URL",
+ *   tags: {
+ *     Environment: "production",
+ *     Application: "myapp"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a secure string parameter for secrets
+ * const secretParam = await SSMParameter("app-secret", {
+ *   name: "/myapp/secrets/api-key",
+ *   value: alchemy.secret("super-secret-api-key"),
+ *   type: "SecureString",
+ *   description: "Third-party API key",
+ *   tags: {
+ *     Environment: "production",
+ *     Secret: "true"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a parameter with custom KMS key
+ * const encryptedParam = await SSMParameter("encrypted-config", {
+ *   name: "/myapp/config/encrypted",
+ *   value: alchemy.secret("sensitive-configuration-data"),
+ *   type: "SecureString",
+ *   keyId: "alias/myapp-kms-key",
+ *   description: "Encrypted configuration data",
+ *   tier: "Advanced",
+ *   tags: {
+ *     Environment: "production",
+ *     Encrypted: "true"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a string list parameter
+ * const listParam = await SSMParameter("server-list", {
+ *   name: "/myapp/config/servers",
+ *   value: ["server1.example.com", "server2.example.com", "server3.example.com"],
+ *   type: "StringList",
+ *   description: "List of application servers",
+ *   tags: {
+ *     Environment: "production",
+ *     Type: "configuration"
+ *   }
+ * });
+ */
+export const SSMParameter = Resource(
+  "ssm::Parameter",
+  async function (
+    this: Context<SSMParameter>,
+    _id: string,
+    props: SSMParameterProps,
+  ): Promise<SSMParameter> {
+    const client = new SSMClient({});
+
+    if (this.phase === "delete") {
+      try {
+        await ignore(ParameterNotFound.name, () =>
+          client.send(
+            new DeleteParameterCommand({
+              Name: props.name,
+            }),
+          ),
+        );
+      } catch (error: any) {
+        if (!(error instanceof ParameterNotFound)) {
+          throw error;
+        }
+      }
+
+      return this.destroy();
+    }
+
+    const parameterType = props.type || "String";
+
+    // Extract the actual value and handle type-specific conversions
+    let parameterValue: string;
+    if (isSecret(props.value)) {
+      parameterValue = props.value.unencrypted;
+    } else if (Array.isArray(props.value)) {
+      // Convert string array to comma-separated string for StringList
+      parameterValue = props.value.join(",");
+    } else {
+      parameterValue = props.value;
+    }
+
+    try {
+      // First, try to create the parameter without overwrite to include tags
+      try {
+        await client.send(
+          new PutParameterCommand({
+            Name: props.name,
+            Value: parameterValue,
+            Type: parameterType,
+            Description: props.description,
+            KeyId: props.keyId,
+            Tier: props.tier,
+            Policies: props.policies,
+            DataType: props.dataType,
+            Overwrite: false, // Don't overwrite, include tags
+            Tags: [
+              ...Object.entries(props.tags || {}).map(([Key, Value]) => ({
+                Key,
+                Value,
+              })),
+              {
+                Key: "alchemy_stage",
+                Value: this.stage,
+              },
+              {
+                Key: "alchemy_resource",
+                Value: this.id,
+              },
+            ],
+          }),
+        );
+      } catch (error: any) {
+        // If parameter already exists, update it with overwrite (no tags in this call)
+        if (error instanceof ParameterAlreadyExists) {
+          await client.send(
+            new PutParameterCommand({
+              Name: props.name,
+              Value: parameterValue,
+              Type: parameterType,
+              Description: props.description,
+              KeyId: props.keyId,
+              Tier: props.tier,
+              Policies: props.policies,
+              DataType: props.dataType,
+              Overwrite: true, // Overwrite existing, no tags
+            }),
+          );
+
+          // Update tags separately for existing parameters
+          const tags: Tag[] = [
+            ...Object.entries(props.tags || {}).map(([Key, Value]) => ({
+              Key,
+              Value,
+            })),
+            {
+              Key: "alchemy_stage",
+              Value: this.stage,
+            },
+            {
+              Key: "alchemy_resource",
+              Value: this.id,
+            },
+          ];
+
+          await client.send(
+            new AddTagsToResourceCommand({
+              ResourceType: "Parameter",
+              ResourceId: props.name,
+              Tags: tags,
+            }),
+          );
+        } else {
+          throw error;
+        }
+      }
+
+      // Get the updated parameter
+      const parameter = await client.send(
+        new GetParameterCommand({
+          Name: props.name,
+          WithDecryption: true,
+        }),
+      );
+
+      if (!parameter?.Parameter) {
+        throw new Error(`Failed to create or update parameter ${props.name}`);
+      }
+
+      return this({
+        ...props,
+        arn: parameter.Parameter.ARN!,
+        version: parameter.Parameter.Version!,
+        lastModifiedDate: parameter.Parameter.LastModifiedDate!,
+        name: parameter.Parameter.Name ?? props.name,
+        value: props.value,
+        type: (parameter.Parameter.Type as any) ?? parameterType,
+      } as SSMParameter);
+    } catch (error: any) {
+      console.error(`Error creating/updating parameter ${props.name}:`, error);
+      throw error;
+    }
+  },
+);

package/src/aws/table.ts

@@ -3,15 +3,13 @@ import {
   DeleteTableCommand,
   DescribeTableCommand,
   DynamoDBClient,
-  InternalServerError,
   type KeySchemaElement,
-  ResourceInUseException,
   ResourceNotFoundException,
 } from "@aws-sdk/client-dynamodb";
 import type { Context } from "../context.ts";
 import { Resource } from "../resource.ts";
 import { ignore } from "../util/ignore.ts";
-import { withExponentialBackoff } from "../util/retry.ts";
+import { retry } from "./retry.ts";
 
 /**
  * Properties for creating or updating a DynamoDB table
@@ -148,20 +146,15 @@ export const Table = Resource(
     const client = new DynamoDBClient({});
 
     if (this.phase === "delete") {
-      await withExponentialBackoff(
-        async () => {
-          await ignore(ResourceNotFoundException.name, () =>
-            client.send(
-              new DeleteTableCommand({
-                TableName: props.tableName,
-              }),
-            ),
-          );
-        },
-        isRetryableError,
-        10, // Max attempts
-        200, // Initial delay in ms
-      );
+      await retry(async () => {
+        await ignore(ResourceNotFoundException.name, () =>
+          client.send(
+            new DeleteTableCommand({
+              TableName: props.tableName,
+            }),
+          ),
+        );
+      });
 
       // Wait for table to be deleted
       let tableDeleted = false;
@@ -223,59 +216,54 @@ export const Table = Resource(
       });
     }
 
-    // Attempt to create the table with exponential backoff for ResourceInUseException
-    await withExponentialBackoff(
-      async () => {
-        try {
-          // First check if table already exists
-          const describeResponse = await client.send(
-            new DescribeTableCommand({
-              TableName: props.tableName,
-            }),
-          );
+    // Attempt to create the table with retry for retryable errors
+    await retry(async () => {
+      try {
+        // First check if table already exists
+        const describeResponse = await client.send(
+          new DescribeTableCommand({
+            TableName: props.tableName,
+          }),
+        );
 
-          // If table exists and is ACTIVE, no need to create it
-          if (describeResponse.Table?.TableStatus === "ACTIVE") {
-            return;
-          }
+        // If table exists and is ACTIVE, no need to create it
+        if (describeResponse.Table?.TableStatus === "ACTIVE") {
+          return;
+        }
 
-          // If table exists but not ACTIVE, wait for it in the polling loop below
-          if (describeResponse.Table) {
-            return;
-          }
-        } catch (error) {
-          if (error instanceof ResourceNotFoundException) {
-            // Table doesn't exist, try to create it
-            await client.send(
-              new CreateTableCommand({
-                TableName: props.tableName,
-                AttributeDefinitions: attributeDefinitions,
-                KeySchema: keySchema,
-                BillingMode: props.billingMode || "PAY_PER_REQUEST",
-                ProvisionedThroughput:
-                  props.billingMode === "PROVISIONED"
-                    ? {
-                        ReadCapacityUnits: props.readCapacity || 5,
-                        WriteCapacityUnits: props.writeCapacity || 5,
-                      }
-                    : undefined,
-                Tags: props.tags
-                  ? Object.entries(props.tags).map(([Key, Value]) => ({
-                      Key,
-                      Value,
-                    }))
+        // If table exists but not ACTIVE, wait for it in the polling loop below
+        if (describeResponse.Table) {
+          return;
+        }
+      } catch (error) {
+        if (error instanceof ResourceNotFoundException) {
+          // Table doesn't exist, try to create it
+          await client.send(
+            new CreateTableCommand({
+              TableName: props.tableName,
+              AttributeDefinitions: attributeDefinitions,
+              KeySchema: keySchema,
+              BillingMode: props.billingMode || "PAY_PER_REQUEST",
+              ProvisionedThroughput:
+                props.billingMode === "PROVISIONED"
+                  ? {
+                      ReadCapacityUnits: props.readCapacity || 5,
+                      WriteCapacityUnits: props.writeCapacity || 5,
+                    }
                   : undefined,
-              }),
-            );
-          } else {
-            throw error;
-          }
+              Tags: props.tags
+                ? Object.entries(props.tags).map(([Key, Value]) => ({
+                    Key,
+                    Value,
+                  }))
+                : undefined,
+            }),
+          );
+        } else {
+          throw error;
         }
-      },
-      isRetryableError,
-      10, // Max attempts
-      200, // Initial delay in ms
-    );
+      }
+    });
 
     // Wait for table to be active with timeout
     let tableActive = false;
@@ -285,10 +273,13 @@ export const Table = Resource(
 
     while (!tableActive && retryCount < maxRetries) {
       try {
-        const response = await client.send(
-          new DescribeTableCommand({
-            TableName: props.tableName,
-          }),
+        const response = await retry(
+          async () =>
+            await client.send(
+              new DescribeTableCommand({
+                TableName: props.tableName,
+              }),
+            ),
         );
 
         tableActive = response.Table?.TableStatus === "ACTIVE";
@@ -323,23 +314,3 @@ export const Table = Resource(
     });
   },
 );
-
-const retryableErrors = [
-  "ResourceInUseException",
-  "ResourceNotFoundException",
-  "InternalServerError",
-  "ThrottlingException",
-  "ProvisionedThroughputExceededException",
-  "LimitExceededException",
-  "RequestLimitExceeded",
-];
-
-function isRetryableError(error: any) {
-  return (
-    error instanceof ResourceInUseException ||
-    error instanceof InternalServerError ||
-    retryableErrors.includes(error?.name) ||
-    retryableErrors.includes(error?.code) ||
-    error?.$metadata?.httpStatusCode === 500
-  );
-}

package/src/cloudflare/account-id.ts

@@ -5,6 +5,8 @@ import { createCloudflareApi, type CloudflareApiOptions } from "./api.ts";
  */
 export interface GetCloudflareAccountIdOptions extends CloudflareApiOptions {}
 
+export type AccountId = string;
+
 /**
  * Retrieves a Cloudflare Account ID for use with other Cloudflare resources.
  *

package/src/cloudflare/api.ts

@@ -1,6 +1,7 @@
 import { alchemy } from "../alchemy.ts";
 import type { Secret } from "../secret.ts";
 import { withExponentialBackoff } from "../util/retry.ts";
+import { safeFetch } from "../util/safe-fetch.ts";
 import {
   getCloudflareAuthHeaders,
   type CloudflareAuthOptions,
@@ -165,21 +166,35 @@ export class CloudflareApi {
       delete headers["Content-Type"];
     }
 
+    let forbidden = false;
+
     // Use withExponentialBackoff for automatic retry on network errors
     return withExponentialBackoff(
       async () => {
-        const response = await fetch(`${this.baseUrl}${path}`, {
+        const response = await safeFetch(`${this.baseUrl}${path}`, {
           ...init,
           headers,
         });
         if (response.status.toString().startsWith("5")) {
           throw new InternalError("5xx error");
         }
+        if (response.status === 403 && !forbidden) {
+          // we occasionally get 403s from Cloudflare tha tare actually transient
+          // so, we will retry this at MOST once
+          forbidden = true;
+          throw new ForbiddenError();
+        }
+        if (response.status === 429) {
+          throw new TooManyRequestsError();
+        }
         return response;
       },
       // transient errors should be retried aggressively
-      (error) => error instanceof InternalError,
-      5, // Maximum 5 attempts (1 initial + 4 retries)
+      (error) =>
+        error instanceof InternalError ||
+        error instanceof TooManyRequestsError ||
+        error instanceof ForbiddenError,
+      10, // Maximum 10 attempts (1 initial + 9 retries)
       1000, // Start with 1s delay, will exponentially increase
     );
   }
@@ -250,3 +265,11 @@ export class CloudflareApi {
 }
 
 class InternalError extends Error {}
+
+class TooManyRequestsError extends Error {
+  constructor() {
+    super(`Cloudflare Rate Limit Exceeded at ${new Date().toISOString()}`);
+  }
+}
+
+class ForbiddenError extends Error {}

package/src/cloudflare/bindings.ts

@@ -21,6 +21,7 @@ import type { VectorizeIndexResource } from "./vectorize-index.ts";
 import type { WorkerStub } from "./worker-stub.ts";
 import type { Worker } from "./worker.ts";
 import type { Workflow } from "./workflow.ts";
+import type { VersionMetadata } from "./version-metadata.ts";
 
 export type Bindings = {
   [bindingName: string]: Binding;
@@ -58,6 +59,7 @@ export type Binding =
   | WorkerStub
   | Workflow
   | BrowserRendering
+  | VersionMetadata
   | Self
   | Json;
 

package/src/cloudflare/bound.ts

@@ -15,6 +15,7 @@ import type { QueueResource as _Queue } from "./queue.ts";
 import type { VectorizeIndexResource as _VectorizeIndex } from "./vectorize-index.ts";
 import type { Worker as _Worker } from "./worker.ts";
 import type { Workflow as _Workflow } from "./workflow.ts";
+import type { VersionMetadata as _VersionMetadata } from "./version-metadata.ts";
 
 export type Bound<T extends Binding> = T extends _DurableObjectNamespace<
   infer O
@@ -61,8 +62,10 @@ export type Bound<T extends Binding> = T extends _DurableObjectNamespace<
                                   ? Fetcher
                                   : T extends _Ai<infer M>
                                     ? Ai<M>
-                                    : T extends Self
-                                      ? Service
-                                      : T extends Json<infer T>
-                                        ? T
-                                        : Service;
+                                    : T extends _VersionMetadata
+                                      ? Fetcher
+                                      : T extends Self
+                                        ? Service
+                                        : T extends Json<infer T>
+                                          ? T
+                                          : Service;

package/src/cloudflare/index.ts

@@ -2,6 +2,7 @@ export * from "./account-api-token.ts";
 export * from "./account-id.ts";
 export * from "./ai-gateway.ts";
 export * from "./ai.ts";
+export * from "./analytics-engine.ts";
 export * from "./api-error.ts";
 export * from "./api.ts";
 export * from "./assets.ts";
@@ -32,6 +33,7 @@ export * from "./route.ts";
 export * from "./tanstack-start.ts";
 export * from "./vectorize-index.ts";
 export * from "./vectorize-metadata-index.ts";
+export * from "./version-metadata.ts";
 export * from "./vite.ts";
 export * from "./website.ts";
 export * from "./worker.ts";

package/src/cloudflare/queue.ts

@@ -469,6 +469,8 @@ export async function findQueueByName(
     }>;
   };
 
+  console.log(data);
+
   if (!data.success) {
     const errorMessage = data.errors?.[0]?.message || "Unknown error";
     throw new Error(`Failed to list queues: ${errorMessage}`);