alchemy 0.15.5 → 0.15.7

package/lib/stripe/meter.js

@@ -0,0 +1,226 @@
+import Stripe from "stripe";
+import { Resource } from "../resource.js";
+/**
+ * Manages Stripe Billing Meters. Meters allow you to define how usage of a product
+ * is measured and aggregated for billing purposes. You can track events and their
+ * values, and Stripe will calculate the usage based on the meter's configuration.
+ *
+ * Stripe Meters have several properties that are immutable after creation:
+ * `displayName`, `eventName`, `defaultAggregation`, `customerMapping`, and
+ * `valueSettings`. Attempting to update these will result in an error.
+ * The `status` of a meter (active/inactive) can be updated.
+ *
+ * @example
+ * // Create a new active meter to track API calls, summing the 'count' field from events.
+ * const apiCallMeter = await Meter("apiUsageMeter", {
+ *  displayName: "API Call Usage",
+ *  eventName: "api.call.recorded", // The event name Stripe will listen for
+ *  defaultAggregation: {
+ *    formula: "sum" // Sum up the values of events
+ *  },
+ *  customerMapping: {
+ *    eventPayloadKey: "customer_id", // Field in the event payload that identifies the Stripe Customer
+ *    type: "by_id"
+ *  },
+ *  valueSettings: {
+ *    eventPayloadKey: "count" // Field in the event payload that represents the value to aggregate
+ *  }
+ *  // status defaults to 'active' if not specified
+ * });
+ *
+ * @example
+ * // Create a new meter for data storage, initially inactive.
+ * // This meter will take the last reported 'gb_used' value within a billing period.
+ * const dataStorageMeterInactive = await Meter("dataStorageMeter", {
+ *  displayName: "Data Storage GB",
+ *  eventName: "data.storage.reported",
+ *  status: "inactive", // Explicitly set to inactive
+ *  defaultAggregation: {
+ *    formula: "last_during_period"
+ *  },
+ *  customerMapping: {
+ *    eventPayloadKey: "user_stripe_id",
+ *    type: "by_id"
+ *  },
+ *  valueSettings: {
+ *    eventPayloadKey: "gb_used"
+ *  }
+ * });
+ *
+ * @example
+ * // (Scenario: Assuming 'dataStorageMeterInactive' from the previous example was created
+ * // and its ID is available, e.g., via `dataStorageMeterInactive.id`) *
+ * // If dataStorageMeterInactive was previously defined and we want to activate it:
+ * const activatedStorageMeter = await Meter("dataStorageMeter", { // Same logicalId
+ *  displayName: "Data Storage GB", // Immutable, must match existing
+ *  eventName: "data.storage.reported", // Immutable, must match existing
+ *  status: "active", // Update: change status to active
+ *  defaultAggregation: { // Immutable, must match existing
+ *    formula: "last_during_period"
+ *  },
+ *  customerMapping: { // Immutable, must match existing
+ *    eventPayloadKey: "user_stripe_id",
+ *    type: "by_id"
+ *  },
+ *  valueSettings: { // Immutable, must match existing
+ *    eventPayloadKey: "gb_used"
+ *  }
+ * });
+ *
+ * @example
+ * // To deactivate an existing active meter (e.g. 'apiCallMeter' from first example):
+ * const deactivatedApiMeter = await Meter("apiUsageMeter", { // Same logicalId
+ *  displayName: "API Call Usage", // Immutable, must match existing
+ *  eventName: "api.call.recorded", // Immutable, must match existing
+ *  status: "inactive", // Update: change status to inactive
+ *  defaultAggregation: { // Immutable, must match existing
+ *    formula: "sum"
+ *  },
+ *  customerMapping: { // Immutable, must match existing
+ *    eventPayloadKey: "customer_id",
+ *    type: "by_id"
+ *  },
+ *  valueSettings: { // Immutable, must match existing
+ *    eventPayloadKey: "count"
+ *  }
+ * });
+ */
+export const Meter = Resource("stripe::Meter", async function (logicalId, props) {
+    const apiKey = process.env.STRIPE_API_KEY;
+    if (!apiKey) {
+        throw new Error("STRIPE_API_KEY environment variable is required");
+    }
+    const stripe = new Stripe(apiKey);
+    const currentOutputId = this.output?.id;
+    // Helper to map MeterProps (camelCase nested) to Stripe API params (snake_case nested)
+    const mapPropsToStripeParams = (inputProps) => ({
+        display_name: inputProps.displayName,
+        event_name: inputProps.eventName,
+        default_aggregation: {
+            formula: inputProps.defaultAggregation.formula,
+        },
+        customer_mapping: {
+            event_payload_key: inputProps.customerMapping.eventPayloadKey,
+            type: inputProps.customerMapping.type,
+        },
+        value_settings: {
+            event_payload_key: inputProps.valueSettings.eventPayloadKey,
+        },
+    });
+    // Helper to map Stripe API response (snake_case) to Meter output interface (camelCase)
+    const mapStripeObjectToMeterOutput = (stripeMeter) => ({
+        id: stripeMeter.id,
+        object: stripeMeter.object,
+        displayName: stripeMeter.display_name,
+        eventName: stripeMeter.event_name,
+        defaultAggregation: {
+            formula: stripeMeter.default_aggregation.formula,
+        },
+        customerMapping: {
+            eventPayloadKey: stripeMeter.customer_mapping.event_payload_key,
+            type: stripeMeter.customer_mapping.type,
+        },
+        valueSettings: {
+            eventPayloadKey: stripeMeter.value_settings.event_payload_key,
+        },
+        status: stripeMeter.status,
+        createdAt: stripeMeter.created,
+        updatedAt: stripeMeter.updated,
+        livemode: stripeMeter.livemode,
+        statusTransitions: stripeMeter.status_transitions
+            ? {
+                deactivatedAt: stripeMeter.status_transitions.deactivated_at,
+            }
+            : undefined,
+    });
+    if (this.phase === "delete") {
+        if (currentOutputId) {
+            try {
+                const meter = await stripe.billing.meters.retrieve(currentOutputId);
+                if (meter.status === "active") {
+                    await stripe.billing.meters.deactivate(currentOutputId);
+                }
+            }
+            catch (error) {
+                if (error?.code !== "resource_missing") {
+                    throw error;
+                }
+            }
+        }
+        return this.destroy();
+    }
+    // --- Create or Update Phase ---
+    let stripeAPIResponse;
+    if (this.phase === "update" && currentOutputId) {
+        const existingStripeMeter = await stripe.billing.meters.retrieve(currentOutputId);
+        // Normalize existingMeter's relevant fields for immutable comparison
+        const existingPropsForCompare = {
+            displayName: existingStripeMeter.display_name,
+            eventName: existingStripeMeter.event_name,
+            defaultAggregation: {
+                formula: existingStripeMeter.default_aggregation.formula,
+            },
+            customerMapping: {
+                eventPayloadKey: existingStripeMeter.customer_mapping.event_payload_key,
+                type: existingStripeMeter.customer_mapping.type,
+            },
+            valueSettings: {
+                eventPayloadKey: existingStripeMeter.value_settings.event_payload_key,
+            },
+        };
+        // Check for immutable property changes (comparing against props passed to resource)
+        if (props.displayName !== existingPropsForCompare.displayName ||
+            props.eventName !== existingPropsForCompare.eventName ||
+            JSON.stringify(props.defaultAggregation) !==
+                JSON.stringify(existingPropsForCompare.defaultAggregation) ||
+            JSON.stringify(props.customerMapping) !==
+                JSON.stringify(existingPropsForCompare.customerMapping) ||
+            JSON.stringify(props.valueSettings) !==
+                JSON.stringify(existingPropsForCompare.valueSettings)) {
+            throw new Error(`Attempted to update immutable properties for Stripe Meter ${currentOutputId}. ` +
+                "displayName, eventName, defaultAggregation, customerMapping, and valueSettings cannot be changed.");
+        }
+        // Handle status change
+        if (props.status && props.status !== existingStripeMeter.status) {
+            if (props.status === "inactive" &&
+                existingStripeMeter.status === "active") {
+                stripeAPIResponse =
+                    await stripe.billing.meters.deactivate(currentOutputId);
+            }
+            else if (props.status === "active" &&
+                existingStripeMeter.status === "inactive") {
+                console.log(`Reactivating Stripe Meter ${currentOutputId}.`);
+                stripeAPIResponse =
+                    await stripe.billing.meters.reactivate(currentOutputId);
+            }
+            else {
+                stripeAPIResponse = existingStripeMeter; // No change in status
+            }
+        }
+        else {
+            stripeAPIResponse = existingStripeMeter; // No status change requested
+        }
+    }
+    else {
+        // Create phase
+        if (!props.displayName ||
+            !props.eventName ||
+            !props.defaultAggregation ||
+            !props.customerMapping ||
+            !props.valueSettings) {
+            throw new Error("displayName, eventName, defaultAggregation, customerMapping, and valueSettings are required for creating a Stripe Meter.");
+        }
+        const createParams = mapPropsToStripeParams(props);
+        stripeAPIResponse = await stripe.billing.meters.create(createParams);
+        // If status 'inactive' is requested during creation, and Stripe created it as 'active'
+        if (props.status === "inactive" &&
+            stripeAPIResponse.status === "active") {
+            stripeAPIResponse = await stripe.billing.meters.deactivate(stripeAPIResponse.id);
+        }
+        else if (props.status && props.status !== stripeAPIResponse.status) {
+            console.warn(`Meter ${stripeAPIResponse.id} created with status ${stripeAPIResponse.status} but requested ${props.status}. Ensure this is intended.`);
+        }
+    }
+    return this(mapStripeObjectToMeterOutput(stripeAPIResponse));
+});
+//# sourceMappingURL=meter.js.map

package/lib/stripe/meter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"meter.js","sourceRoot":"","sources":["../../src/stripe/meter.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alchemy",
-  "version": "0.15.5",
+  "version": "0.15.7",
   "type": "module",
   "module": "./lib/index.js",
   "scripts": {

package/src/cloudflare/index.ts

@@ -23,6 +23,7 @@ export * from "./queue-consumer.js";
 export * from "./queue.js";
 export * from "./r2-rest-state-store.js";
 export * from "./redwood.js";
+export * from "./route.js";
 export * from "./tanstack-start.js";
 export * from "./vectorize-index.js";
 export * from "./vectorize-metadata-index.js";

package/src/cloudflare/kv-namespace.ts

@@ -3,8 +3,8 @@ import { Resource } from "../resource.js";
 import { withExponentialBackoff } from "../util/retry.js";
 import { handleApiError } from "./api-error.js";
 import {
-  type CloudflareApi,
   createCloudflareApi,
+  type CloudflareApi,
   type CloudflareApiOptions,
 } from "./api.js";
 
@@ -22,6 +22,22 @@ export interface KVNamespaceProps extends CloudflareApiOptions {
    * Only used for initial setup or updates
    */
   values?: KVPair[];
+
+  /**
+   * Whether to adopt an existing namespace with the same title if it exists
+   * If true and a namespace with the same title exists, it will be adopted rather than creating a new one
+   *
+   * @default false
+   */
+  adopt?: boolean;
+
+  /**
+   * Whether to delete the namespace.
+   * If set to false, the namespace will remain but the resource will be removed from state
+   *
+   * @default true
+   */
+  delete?: boolean;
 }
 
 /**
@@ -112,6 +128,24 @@ export interface KVNamespace
  *     }
  *   }]
  * });
+ *
+ * @example
+ * // Adopt an existing namespace if it already exists instead of failing
+ * const existingNamespace = await KVNamespace("existing-ns", {
+ *   title: "existing-namespace",
+ *   adopt: true,
+ *   values: [{
+ *     key: "config",
+ *     value: { setting: "updated-value" }
+ *   }]
+ * });
+ *
+ * @example
+ * // When removing from Alchemy state, keep the namespace in Cloudflare
+ * const preservedNamespace = await KVNamespace("preserve-ns", {
+ *   title: "preserved-namespace",
+ *   delete: false
+ * });
  */
 export const KVNamespace = Resource(
   "cloudflare::KVNamespace",
@@ -126,7 +160,7 @@ export const KVNamespace = Resource(
     if (this.phase === "delete") {
       // For delete operations, we need to check if the namespace ID exists in the output
       const namespaceId = this.output?.namespaceId;
-      if (namespaceId) {
+      if (namespaceId && props.delete !== false) {
         await deleteKVNamespace(api, namespaceId);
       }
 
@@ -145,10 +179,39 @@ export const KVNamespace = Resource(
     if (this.phase === "update" && namespaceId) {
       // Can't update a KV namespace title directly, just work with existing ID
     } else {
-      // TODO: if it already exists, then check the tags to see if we own it and continue
-      const { id } = await createKVNamespace(api, props);
-      createdAt = Date.now();
-      namespaceId = id;
+      try {
+        // Try to create the KV namespace
+        const { id } = await createKVNamespace(api, props);
+        createdAt = Date.now();
+        namespaceId = id;
+      } catch (error) {
+        // Check if this is a "namespace already exists" error and adopt is enabled
+        if (
+          props.adopt &&
+          error instanceof Error &&
+          error.message.includes("already exists")
+        ) {
+          console.log(`Namespace '${props.title}' already exists, adopting it`);
+          // Find the existing namespace by title
+          const existingNamespace = await findKVNamespaceByTitle(
+            api,
+            props.title,
+          );
+
+          if (!existingNamespace) {
+            throw new Error(
+              `Failed to find existing namespace '${props.title}' for adoption`,
+            );
+          }
+
+          // Use the existing namespace ID
+          namespaceId = existingNamespace.id;
+          createdAt = existingNamespace.createdAt || Date.now();
+        } else {
+          // Re-throw the error if adopt is false or it's not a "namespace already exists" error
+          throw error;
+        }
+      }
     }
 
     await insertKVRecords(api, namespaceId, props);
@@ -232,37 +295,100 @@ export async function insertKVRecords(
         return item;
       });
 
-      try {
-        await withExponentialBackoff(
-          async () => {
-            const bulkResponse = await api.put(
-              `/accounts/${api.accountId}/storage/kv/namespaces/${namespaceId}/bulk`,
-              bulkPayload,
-            );
+      await withExponentialBackoff(
+        async () => {
+          const bulkResponse = await api.put(
+            `/accounts/${api.accountId}/storage/kv/namespaces/${namespaceId}/bulk`,
+            bulkPayload,
+          );
+
+          if (!bulkResponse.ok) {
+            const errorData: any = await bulkResponse.json().catch(() => ({
+              errors: [{ message: bulkResponse.statusText }],
+            }));
+            const errorMessage =
+              errorData.errors?.[0]?.message || bulkResponse.statusText;
+
+            // Throw error to trigger retry
+            throw new Error(`Error writing KV batch: ${errorMessage}`);
+          }
+
+          return bulkResponse;
+        },
+        (error) => {
+          // Retry on "namespace not found" errors as they're likely propagation delays
+          return error.message?.includes("not found");
+        },
+        5, // 5 retry attempts
+        1000, // Start with 1 second delay
+      );
+    }
+  }
+}
 
-            if (!bulkResponse.ok) {
-              const errorData: any = await bulkResponse.json().catch(() => ({
-                errors: [{ message: bulkResponse.statusText }],
-              }));
-              const errorMessage =
-                errorData.errors?.[0]?.message || bulkResponse.statusText;
-
-              // Throw error to trigger retry
-              throw new Error(`Error writing KV batch: ${errorMessage}`);
-            }
-
-            return bulkResponse;
-          },
-          (error) => {
-            // Retry on "namespace not found" errors as they're likely propagation delays
-            return error.message?.includes("not found");
-          },
-          5, // 5 retry attempts
-          1000, // Start with 1 second delay
-        );
-      } catch (error: any) {
-        console.warn(error.message);
-      }
+/**
+ * Interface representing a KV namespace as returned by Cloudflare API
+ */
+interface CloudflareKVNamespace {
+  id: string;
+  title: string;
+  supports_url_encoding?: boolean;
+  created_on?: string;
+}
+
+/**
+ * Find a KV namespace by title with pagination support
+ */
+export async function findKVNamespaceByTitle(
+  api: CloudflareApi,
+  title: string,
+): Promise<{ id: string; createdAt?: number } | null> {
+  let page = 1;
+  const perPage = 100; // Maximum allowed by API
+  let hasMorePages = true;
+
+  while (hasMorePages) {
+    const response = await api.get(
+      `/accounts/${api.accountId}/storage/kv/namespaces?page=${page}&per_page=${perPage}`,
+    );
+
+    if (!response.ok) {
+      await handleApiError(response, "list", "kv_namespace", "all");
     }
+
+    const data = (await response.json()) as {
+      result: CloudflareKVNamespace[];
+      result_info: {
+        count: number;
+        page: number;
+        per_page: number;
+        total_count: number;
+      };
+      success: boolean;
+      errors: any[];
+    };
+
+    const namespaces = data.result;
+    const resultInfo = data.result_info;
+
+    // Look for a namespace with matching title
+    const match = namespaces.find((ns) => ns.title === title);
+    if (match) {
+      return {
+        id: match.id,
+        // Convert ISO string to timestamp if available, otherwise use current time
+        createdAt: match.created_on
+          ? new Date(match.created_on).getTime()
+          : undefined,
+      };
+    }
+
+    // Check if we've seen all pages
+    hasMorePages =
+      resultInfo.page * resultInfo.per_page < resultInfo.total_count;
+    page++;
   }
+
+  // No matching namespace found
+  return null;
 }