alchemy 0.15.5 → 0.15.7

package/src/cloudflare/route.ts

@@ -0,0 +1,268 @@
+import type { Context } from "../context.js";
+import { Resource } from "../resource.js";
+import { CloudflareApiError, handleApiError } from "./api-error.js";
+import {
+  createCloudflareApi,
+  type CloudflareApi,
+  type CloudflareApiOptions,
+} from "./api.js";
+import type { Worker } from "./worker.js";
+
+/**
+ * Properties for creating or updating a Route
+ */
+export interface RouteProps extends CloudflareApiOptions {
+  /**
+   * URL pattern for the route
+   * @example "example.com/*"
+   */
+  pattern: string;
+
+  /**
+   * Worker script for the route
+   * This can be a Worker resource or script name as a string
+   */
+  script: Worker | string;
+
+  /**
+   * Zone ID for the route
+   */
+  zoneId: string;
+}
+
+/**
+ * Output returned after Route creation/update
+ */
+export interface Route extends Resource<"cloudflare::Route">, RouteProps {
+  /**
+   * The unique ID of the route
+   */
+  id: string;
+
+  /**
+   * The URL pattern for the route
+   */
+  pattern: string;
+
+  /**
+   * The Worker script name for the route
+   */
+  script: string;
+
+  /**
+   * The Zone ID for the route
+   */
+  zoneId: string;
+}
+
+/**
+ * Creates and manages Cloudflare Worker Routes.
+ *
+ * Routes map URL patterns to Worker scripts, allowing you to control which
+ * requests are handled by your Workers.
+ *
+ * @example
+ * // Create a route that maps all requests on a domain to a Worker
+ * const basicRoute = await Route("main-route", {
+ *   pattern: "example.com/*",
+ *   script: "my-worker",
+ *   zoneId: "your-zone-id"
+ * });
+ *
+ * @example
+ * // Create a route using a Worker resource
+ * const worker = await Worker("api-worker", {
+ *   script: `
+ *     export default {
+ *       fetch(request, env) {
+ *         return new Response("Hello from API!");
+ *       }
+ *     }
+ *   `
+ * });
+ *
+ * const apiRoute = await Route("api-route", {
+ *   pattern: "api.example.com/*",
+ *   script: worker,
+ *   zoneId: "your-zone-id"
+ * });
+ *
+ * @see https://developers.cloudflare.com/workers/configuration/routes/
+ */
+export const Route = Resource(
+  "cloudflare::Route",
+  async function (
+    this: Context<Route>,
+    id: string,
+    props: RouteProps,
+  ): Promise<Route> {
+    const api = await createCloudflareApi(props);
+
+    // Get script name from script prop (either a string or a Worker resource)
+    const scriptName =
+      typeof props.script === "string" ? props.script : props.script.name;
+
+    // Get zone ID from props
+    const { zoneId } = props;
+
+    if (this.phase === "delete") {
+      console.log("Deleting Route:", props.pattern);
+
+      // Only delete if we have an ID
+      if (this.output?.id) {
+        await deleteRoute(api, zoneId, this.output.id);
+      }
+
+      // Return void (a deleted route has no content)
+      return this.destroy();
+    }
+
+    let routeData: CloudflareRouteResponse;
+
+    if (this.phase === "update" && this.output?.id) {
+      console.log("Updating Route:", props.pattern);
+
+      // Update existing route
+      routeData = await updateRoute(
+        api,
+        zoneId,
+        this.output.id,
+        props.pattern,
+        scriptName,
+      );
+    } else {
+      console.log("Creating Route:", props.pattern);
+
+      // Create new route
+      routeData = await createRoute(api, zoneId, props.pattern, scriptName);
+    }
+
+    // Return the route resource
+    return this({
+      id: routeData.result.id,
+      pattern: routeData.result.pattern,
+      script: routeData.result.script,
+      zoneId,
+    });
+  },
+);
+
+interface CloudflareRouteResponse {
+  result: {
+    id: string;
+    pattern: string;
+    script: string;
+  };
+  success: boolean;
+  errors: Array<{ code: number; message: string }>;
+  messages: string[];
+}
+
+/**
+ * Create a new route
+ */
+async function createRoute(
+  api: CloudflareApi,
+  zoneId: string,
+  pattern: string,
+  script: string,
+): Promise<CloudflareRouteResponse> {
+  const createResponse = await api.post(`/zones/${zoneId}/workers/routes`, {
+    pattern,
+    script,
+  });
+
+  if (!createResponse.ok) {
+    return await handleApiError(createResponse, "creating", "Route", pattern);
+  }
+
+  return (await createResponse.json()) as CloudflareRouteResponse;
+}
+
+/**
+ * Update a route
+ */
+async function updateRoute(
+  api: CloudflareApi,
+  zoneId: string,
+  routeId: string,
+  pattern: string,
+  script: string,
+): Promise<CloudflareRouteResponse> {
+  const updateResponse = await api.put(
+    `/zones/${zoneId}/workers/routes/${routeId}`,
+    {
+      pattern,
+      script,
+    },
+  );
+
+  if (!updateResponse.ok) {
+    return await handleApiError(updateResponse, "updating", "Route", pattern);
+  }
+
+  return (await updateResponse.json()) as CloudflareRouteResponse;
+}
+
+/**
+ * Delete a route
+ */
+async function deleteRoute(
+  api: CloudflareApi,
+  zoneId: string,
+  routeId: string,
+): Promise<void> {
+  const deleteResponse = await api.delete(
+    `/zones/${zoneId}/workers/routes/${routeId}`,
+  );
+
+  if (!deleteResponse.ok && deleteResponse.status !== 404) {
+    const errorData: any = await deleteResponse.json().catch(() => ({
+      errors: [{ message: deleteResponse.statusText }],
+    }));
+
+    throw new CloudflareApiError(
+      `Error deleting Route '${routeId}': ${errorData.errors?.[0]?.message || deleteResponse.statusText}`,
+      deleteResponse,
+    );
+  }
+}
+
+/**
+ * Get a route by ID
+ */
+export async function getRoute(
+  api: CloudflareApi,
+  zoneId: string,
+  routeId: string,
+): Promise<CloudflareRouteResponse> {
+  const response = await api.get(`/zones/${zoneId}/workers/routes/${routeId}`);
+
+  if (!response.ok) {
+    throw new CloudflareApiError(
+      `Failed to get route ${routeId}: ${response.statusText}`,
+      response,
+    );
+  }
+
+  return (await response.json()) as CloudflareRouteResponse;
+}
+
+/**
+ * List all routes for a zone
+ */
+export async function listRoutes(
+  api: CloudflareApi,
+  zoneId: string,
+): Promise<CloudflareRouteResponse> {
+  const response = await api.get(`/zones/${zoneId}/workers/routes`);
+
+  if (!response.ok) {
+    throw new CloudflareApiError(
+      `Failed to list routes: ${response.statusText}`,
+      response,
+    );
+  }
+
+  return (await response.json()) as CloudflareRouteResponse;
+}

package/src/cloudflare/worker.ts

@@ -275,6 +275,12 @@ export interface Worker<B extends Bindings = Bindings>
  *   url: true
  * });
  *
+ * await Route("route", {
+ *   zoneId: zone.zoneId,
+ *   worker: api,
+ *   pattern: "api.example.com/*",
+ * });
+ *
  * @example
  * // Create a real-time chat worker using Durable Objects
  * // for state management:

package/src/cloudflare/wrangler.json.ts

@@ -268,6 +268,15 @@ export interface WranglerJsonSpec {
     binding: string;
   };
 
+  /**
+   * Migrations
+   */
+  migrations?: {
+    tag: string;
+    new_sqlite_classes?: string[];
+    new_classes?: string[];
+  }[];
+
   /**
    * Workflow bindings
    */
@@ -327,6 +336,9 @@ function processBindings(
     consumers: [],
   };
 
+  const new_sqlite_classes: string[] = [];
+  const new_classes: string[] = [];
+
   const vectorizeIndexes: { binding: string; index_name: string }[] = [];
 
   for (const eventSource of eventSources ?? []) {
@@ -383,6 +395,11 @@ function processBindings(
         script_name: doBinding.scriptName,
         environment: doBinding.environment,
       });
+      if (doBinding.sqlite) {
+        new_sqlite_classes.push(doBinding.className);
+      } else {
+        new_classes.push(doBinding.className);
+      }
     } else if (binding.type === "r2_bucket") {
       r2Buckets.push({
         binding: bindingName,
@@ -466,4 +483,14 @@ function processBindings(
   if (vectorizeIndexes.length > 0) {
     spec.vectorize_indexes = vectorizeIndexes;
   }
+
+  if (new_sqlite_classes.length > 0 || new_classes.length > 0) {
+    spec.migrations = [
+      {
+        tag: "v1",
+        new_sqlite_classes,
+        new_classes,
+      },
+    ];
+  }
 }

package/src/internal/docs/providers.ts

@@ -6,6 +6,14 @@ import { Document } from "../../ai/document.js";
 import { alchemy } from "../../alchemy.js";
 import { Folder } from "../../fs/folder.js";
 
+function getArg(arg: string) {
+  const idx = process.argv.findIndex((a) => a === arg);
+  return idx > -1 ? process.argv[idx + 1] : undefined;
+}
+
+const onlyProviderName = getArg("--provider");
+const onlyResourceName = getArg("--resource");
+
 export interface DocsProps {
   /**
    * The output directory for the docs.
@@ -117,7 +125,7 @@ async function generateProviderDocs({
         reasoningEffort: "high",
       },
     },
-    freeze: false,
+    freeze: onlyProviderName === undefined || onlyProviderName !== providerName,
     temperature: 0.1,
     schema: type({
       groups: type({
@@ -177,7 +185,8 @@ async function generateProviderDocs({
         providerDocsDir,
         `${g.filename.replace(".ts", "").replace(".md", "")}.md`,
       ),
-      freeze: false,
+      freeze:
+        onlyResourceName !== undefined && onlyResourceName !== g.identifier,
       model: {
         id: "claude-3-5-sonnet-latest",
         provider: "anthropic",

package/src/scope.ts

@@ -47,10 +47,15 @@ export class Scope {
 
   private isErrored = false;
 
-  constructor(private readonly options: ScopeOptions) {
+  constructor(options: ScopeOptions) {
     this.appName = options.appName;
     this.stage = options?.stage ?? DEFAULT_STAGE;
     this.scopeName = options.scopeName ?? null;
+    if (this.scopeName?.includes(":")) {
+      throw new Error(
+        `Scope name ${this.scopeName} cannot contain double colons`,
+      );
+    }
     this.parent = options.parent ?? Scope.get();
     this.quiet = options.quiet ?? this.parent?.quiet ?? false;
     if (this.parent && !this.scopeName) {

package/src/stripe/index.ts

@@ -1,3 +1,4 @@
 export * from "./price.js";
 export * from "./product.js";
 export * from "./webhook.js";
+export * from "./meter.js";

package/src/stripe/meter.ts

@@ -0,0 +1,314 @@
+import Stripe from "stripe";
+import type { Context } from "../context.js";
+import { Resource } from "../resource.js";
+
+/**
+ * Properties for creating or updating a Stripe Meter.
+ * Note: Nested objects like defaultAggregation, customerMapping, valueSettings
+ * use camelCase for keys here (e.g., eventPayloadKey), and the resource
+ * implementation will map them to snake_case for Stripe API calls.
+ */
+export interface MeterProps {
+  displayName: string;
+  eventName: string;
+  status?: "active" | "inactive"; // 'active' is default on create by Stripe
+  defaultAggregation: {
+    formula: Stripe.Billing.MeterCreateParams.DefaultAggregation.Formula;
+  };
+  customerMapping: {
+    eventPayloadKey: string;
+    type: Stripe.Billing.MeterCreateParams.CustomerMapping["type"];
+  };
+  valueSettings: {
+    eventPayloadKey: string;
+  };
+}
+
+/**
+ * Output returned after Stripe Meter creation/update.
+ */
+export interface Meter extends Resource<"stripe::Meter"> {
+  id: string;
+  object: "billing.meter";
+  displayName: string;
+  eventName: string;
+  defaultAggregation: {
+    formula: Stripe.Billing.Meter.DefaultAggregation["formula"];
+  };
+  customerMapping: {
+    eventPayloadKey: string;
+    type: Stripe.Billing.Meter.CustomerMapping["type"];
+  };
+  valueSettings: {
+    eventPayloadKey: string;
+  };
+  status: "active" | "inactive";
+  createdAt: number; // Unix timestamp
+  updatedAt: number; // Unix timestamp
+  livemode: boolean;
+  statusTransitions?: {
+    deactivatedAt: number | null; // Unix timestamp
+  };
+}
+
+/**
+ * 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 (
+    this: Context<Meter>,
+    logicalId: string,
+    props: MeterProps,
+  ): Promise<Meter> {
+    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: MeterProps,
+    ): Stripe.Billing.MeterCreateParams => ({
+      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: Stripe.Billing.Meter,
+    ): Omit<Meter, keyof Resource<"stripe::Meter">> => ({
+      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 as "active" | "inactive",
+      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: any) {
+          if (error?.code !== "resource_missing") {
+            throw error;
+          }
+        }
+      }
+      return this.destroy();
+    }
+
+    // --- Create or Update Phase ---
+    let stripeAPIResponse: Stripe.Billing.Meter;
+
+    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));
+  },
+);