alchemy 0.15.6 → 0.15.7

package/lib/stripe/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./price.js";
 export * from "./product.js";
 export * from "./webhook.js";
+export * from "./meter.js";
 //# sourceMappingURL=index.d.ts.map

package/lib/stripe/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/stripe/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/stripe/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC"}

package/lib/stripe/index.js

@@ -1,4 +1,5 @@
 export * from "./price.js";
 export * from "./product.js";
 export * from "./webhook.js";
+export * from "./meter.js";
 //# sourceMappingURL=index.js.map

package/lib/stripe/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/stripe/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/stripe/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC"}

package/lib/stripe/meter.d.ts

@@ -0,0 +1,137 @@
+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";
+    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;
+    updatedAt: number;
+    livemode: boolean;
+    statusTransitions?: {
+        deactivatedAt: number | null;
+    };
+}
+/**
+ * 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 declare const Meter: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<Meter>, logicalId: string, props: MeterProps) => Promise<Meter>);
+//# sourceMappingURL=meter.d.ts.map

package/lib/stripe/meter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meter.d.ts","sourceRoot":"","sources":["../../src/stripe/meter.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAC5B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC/B,kBAAkB,EAAE;QAClB,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,iBAAiB,CAAC,kBAAkB,CAAC,OAAO,CAAC;KACtE,CAAC;IACF,eAAe,EAAE;QACf,eAAe,EAAE,MAAM,CAAC;QACxB,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,iBAAiB,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;KAChE,CAAC;IACF,aAAa,EAAE;QACb,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,KAAM,SAAQ,QAAQ,CAAC,eAAe,CAAC;IACtD,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,eAAe,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB,EAAE;QAClB,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC;KAC7D,CAAC;IACF,eAAe,EAAE;QACf,eAAe,EAAE,MAAM,CAAC;QACxB,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;KACpD,CAAC;IACF,aAAa,EAAE;QACb,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC;IACF,MAAM,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,iBAAiB,CAAC,EAAE;QAClB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;KAC9B,CAAC;CACH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoFG;AAEH,eAAO,MAAM,KAAK,yFAGR,OAAO,CAAC,KAAK,CAAC,aACT,MAAM,SACV,UAAU,KAChB,OAAO,CAAC,KAAK,CAAC,CAwKlB,CAAC"}

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":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAmD1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoFG;AAEH,MAAM,CAAC,MAAM,KAAK,GAAG,QAAQ,CAC3B,eAAe,EACf,KAAK,WAEH,SAAiB,EACjB,KAAiB;IAEjB,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;IAC1C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;IACrE,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC;IAElC,MAAM,eAAe,GAAG,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;IAExC,uFAAuF;IACvF,MAAM,sBAAsB,GAAG,CAC7B,UAAsB,EACY,EAAE,CAAC,CAAC;QACtC,YAAY,EAAE,UAAU,CAAC,WAAW;QACpC,UAAU,EAAE,UAAU,CAAC,SAAS;QAChC,mBAAmB,EAAE;YACnB,OAAO,EAAE,UAAU,CAAC,kBAAkB,CAAC,OAAO;SAC/C;QACD,gBAAgB,EAAE;YAChB,iBAAiB,EAAE,UAAU,CAAC,eAAe,CAAC,eAAe;YAC7D,IAAI,EAAE,UAAU,CAAC,eAAe,CAAC,IAAI;SACtC;QACD,cAAc,EAAE;YACd,iBAAiB,EAAE,UAAU,CAAC,aAAa,CAAC,eAAe;SAC5D;KACF,CAAC,CAAC;IAEH,uFAAuF;IACvF,MAAM,4BAA4B,GAAG,CACnC,WAAiC,EACa,EAAE,CAAC,CAAC;QAClD,EAAE,EAAE,WAAW,CAAC,EAAE;QAClB,MAAM,EAAE,WAAW,CAAC,MAAM;QAC1B,WAAW,EAAE,WAAW,CAAC,YAAY;QACrC,SAAS,EAAE,WAAW,CAAC,UAAU;QACjC,kBAAkB,EAAE;YAClB,OAAO,EAAE,WAAW,CAAC,mBAAmB,CAAC,OAAO;SACjD;QACD,eAAe,EAAE;YACf,eAAe,EAAE,WAAW,CAAC,gBAAgB,CAAC,iBAAiB;YAC/D,IAAI,EAAE,WAAW,CAAC,gBAAgB,CAAC,IAAI;SACxC;QACD,aAAa,EAAE;YACb,eAAe,EAAE,WAAW,CAAC,cAAc,CAAC,iBAAiB;SAC9D;QACD,MAAM,EAAE,WAAW,CAAC,MAA+B;QACnD,SAAS,EAAE,WAAW,CAAC,OAAO;QAC9B,SAAS,EAAE,WAAW,CAAC,OAAO;QAC9B,QAAQ,EAAE,WAAW,CAAC,QAAQ;QAC9B,iBAAiB,EAAE,WAAW,CAAC,kBAAkB;YAC/C,CAAC,CAAC;gBACE,aAAa,EAAE,WAAW,CAAC,kBAAkB,CAAC,cAAc;aAC7D;YACH,CAAC,CAAC,SAAS;KACd,CAAC,CAAC;IAEH,IAAI,IAAI,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC5B,IAAI,eAAe,EAAE,CAAC;YACpB,IAAI,CAAC;gBACH,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC;gBACpE,IAAI,KAAK,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;oBAC9B,MAAM,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC;gBAC1D,CAAC;YACH,CAAC;YAAC,OAAO,KAAU,EAAE,CAAC;gBACpB,IAAI,KAAK,EAAE,IAAI,KAAK,kBAAkB,EAAE,CAAC;oBACvC,MAAM,KAAK,CAAC;gBACd,CAAC;YACH,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC;IACxB,CAAC;IAED,iCAAiC;IACjC,IAAI,iBAAuC,CAAC;IAE5C,IAAI,IAAI,CAAC,KAAK,KAAK,QAAQ,IAAI,eAAe,EAAE,CAAC;QAC/C,MAAM,mBAAmB,GACvB,MAAM,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC;QAExD,qEAAqE;QACrE,MAAM,uBAAuB,GAAG;YAC9B,WAAW,EAAE,mBAAmB,CAAC,YAAY;YAC7C,SAAS,EAAE,mBAAmB,CAAC,UAAU;YACzC,kBAAkB,EAAE;gBAClB,OAAO,EAAE,mBAAmB,CAAC,mBAAmB,CAAC,OAAO;aACzD;YACD,eAAe,EAAE;gBACf,eAAe,EACb,mBAAmB,CAAC,gBAAgB,CAAC,iBAAiB;gBACxD,IAAI,EAAE,mBAAmB,CAAC,gBAAgB,CAAC,IAAI;aAChD;YACD,aAAa,EAAE;gBACb,eAAe,EAAE,mBAAmB,CAAC,cAAc,CAAC,iBAAiB;aACtE;SACF,CAAC;QAEF,oFAAoF;QACpF,IACE,KAAK,CAAC,WAAW,KAAK,uBAAuB,CAAC,WAAW;YACzD,KAAK,CAAC,SAAS,KAAK,uBAAuB,CAAC,SAAS;YACrD,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,kBAAkB,CAAC;gBACtC,IAAI,CAAC,SAAS,CAAC,uBAAuB,CAAC,kBAAkB,CAAC;YAC5D,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,eAAe,CAAC;gBACnC,IAAI,CAAC,SAAS,CAAC,uBAAuB,CAAC,eAAe,CAAC;YACzD,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,aAAa,CAAC;gBACjC,IAAI,CAAC,SAAS,CAAC,uBAAuB,CAAC,aAAa,CAAC,EACvD,CAAC;YACD,MAAM,IAAI,KAAK,CACb,6DAA6D,eAAe,IAAI;gBAC9E,mGAAmG,CACtG,CAAC;QACJ,CAAC;QAED,uBAAuB;QACvB,IAAI,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,MAAM,KAAK,mBAAmB,CAAC,MAAM,EAAE,CAAC;YAChE,IACE,KAAK,CAAC,MAAM,KAAK,UAAU;gBAC3B,mBAAmB,CAAC,MAAM,KAAK,QAAQ,EACvC,CAAC;gBACD,iBAAiB;oBACf,MAAM,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC;YAC5D,CAAC;iBAAM,IACL,KAAK,CAAC,MAAM,KAAK,QAAQ;gBACzB,mBAAmB,CAAC,MAAM,KAAK,UAAU,EACzC,CAAC;gBACD,OAAO,CAAC,GAAG,CAAC,6BAA6B,eAAe,GAAG,CAAC,CAAC;gBAC7D,iBAAiB;oBACf,MAAM,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC;YAC5D,CAAC;iBAAM,CAAC;gBACN,iBAAiB,GAAG,mBAAmB,CAAC,CAAC,sBAAsB;YACjE,CAAC;QACH,CAAC;aAAM,CAAC;YACN,iBAAiB,GAAG,mBAAmB,CAAC,CAAC,6BAA6B;QACxE,CAAC;IACH,CAAC;SAAM,CAAC;QACN,eAAe;QACf,IACE,CAAC,KAAK,CAAC,WAAW;YAClB,CAAC,KAAK,CAAC,SAAS;YAChB,CAAC,KAAK,CAAC,kBAAkB;YACzB,CAAC,KAAK,CAAC,eAAe;YACtB,CAAC,KAAK,CAAC,aAAa,EACpB,CAAC;YACD,MAAM,IAAI,KAAK,CACb,0HAA0H,CAC3H,CAAC;QACJ,CAAC;QAED,MAAM,YAAY,GAAG,sBAAsB,CAAC,KAAK,CAAC,CAAC;QACnD,iBAAiB,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;QAErE,uFAAuF;QACvF,IACE,KAAK,CAAC,MAAM,KAAK,UAAU;YAC3B,iBAAiB,CAAC,MAAM,KAAK,QAAQ,EACrC,CAAC;YACD,iBAAiB,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CACxD,iBAAiB,CAAC,EAAE,CACrB,CAAC;QACJ,CAAC;aAAM,IAAI,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,MAAM,KAAK,iBAAiB,CAAC,MAAM,EAAE,CAAC;YACrE,OAAO,CAAC,IAAI,CACV,SAAS,iBAAiB,CAAC,EAAE,wBAAwB,iBAAiB,CAAC,MAAM,kBAAkB,KAAK,CAAC,MAAM,4BAA4B,CACxI,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC,4BAA4B,CAAC,iBAAiB,CAAC,CAAC,CAAC;AAC/D,CAAC,CACF,CAAC"}

package/package.json

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

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));
+  },
+);