alchemy 0.24.0 → 0.24.1

package/src/stripe/client.ts

@@ -0,0 +1,145 @@
+import Stripe from "stripe";
+import type { Secret } from "../secret.ts";
+import { withExponentialBackoff } from "../util/retry.ts";
+
+export interface StripeClientOptions {
+  apiKey?: Secret | string;
+}
+
+export function createStripeClient(options: StripeClientOptions = {}): Stripe {
+  let apiKey: string;
+
+  if (options.apiKey) {
+    apiKey =
+      typeof options.apiKey === "string"
+        ? options.apiKey
+        : options.apiKey.unencrypted;
+  } else {
+    const envApiKey = process.env.STRIPE_API_KEY;
+    if (!envApiKey) {
+      throw new Error(
+        "Stripe API key is required. Provide it via the apiKey parameter or set the STRIPE_API_KEY environment variable.",
+      );
+    }
+    apiKey = envApiKey;
+  }
+
+  const stripe = new Stripe(apiKey);
+  return createStripeProxy(stripe);
+}
+
+export function handleStripeDeleteError(
+  error: any,
+  resourceType: string,
+  resourceId?: string,
+): void {
+  if (error?.code === "resource_missing" || error?.status === 404) {
+    console.log(
+      `${resourceType} ${resourceId || "unknown"} not found during deletion (already deleted)`,
+    );
+    return;
+  }
+
+  console.error(
+    `Error deleting ${resourceType} ${resourceId || "unknown"}:`,
+    error,
+  );
+  throw error;
+}
+
+export function isStripeConflictError(error: any): boolean {
+  return error?.status === 409 || error?.statusCode === 409;
+}
+
+/**
+ * Creates a proxy that wraps Stripe API calls with retry logic
+ */
+function createStripeProxy(stripe: Stripe): Stripe {
+  // Cache for proxied resources to avoid creating new proxies for the same resource
+  const resourceProxyCache = new Map<string, any>();
+
+  return new Proxy(stripe, {
+    get(target, prop, receiver) {
+      const value = Reflect.get(target, prop, receiver);
+
+      // If it's not a property we want to proxy, return as-is
+      if (
+        typeof prop !== "string" ||
+        typeof value !== "object" ||
+        value === null
+      ) {
+        return value;
+      }
+
+      // Check if this looks like a Stripe resource (has methods like create, retrieve, etc.)
+      const hasStripeResourceMethods =
+        value &&
+        typeof value === "object" &&
+        (typeof value.create === "function" ||
+          typeof value.retrieve === "function" ||
+          typeof value.list === "function" ||
+          typeof value.update === "function" ||
+          typeof value.del === "function");
+
+      if (!hasStripeResourceMethods) {
+        return value;
+      }
+
+      // Return cached proxy if it exists
+      if (resourceProxyCache.has(prop)) {
+        return resourceProxyCache.get(prop);
+      }
+
+      // Create a new proxy for this resource
+      const resourceProxy = new Proxy(value, {
+        get(resourceTarget, methodName, resourceReceiver) {
+          const method = Reflect.get(
+            resourceTarget,
+            methodName,
+            resourceReceiver,
+          );
+
+          // If it's not a function, return as-is
+          if (typeof method !== "function") {
+            return method;
+          }
+
+          // Wrap the method with retry logic
+          return (...args: any[]) =>
+            withStripeRetry(() => method.apply(resourceTarget, args));
+        },
+      });
+
+      // Cache the proxy
+      resourceProxyCache.set(prop, resourceProxy);
+      return resourceProxy;
+    },
+  });
+}
+
+/**
+ * Determines if a Stripe error should trigger a retry
+ */
+function isStripeRetryableError(error: any): boolean {
+  return (
+    error?.raw?.statusCode === 429 ||
+    error?.code === "rate_limit" ||
+    error?.type === "rate_limit_error"
+  );
+}
+
+/**
+ * Wraps a Stripe API operation with retry logic for rate limiting
+ */
+async function withStripeRetry<T>(
+  operation: () => Promise<T>,
+  maxAttempts = 5,
+  initialDelayMs = 1000,
+): Promise<T> {
+  return withExponentialBackoff(
+    operation,
+    isStripeRetryableError,
+    maxAttempts,
+    initialDelayMs,
+  );
+}

package/src/stripe/coupon.ts

@@ -0,0 +1,280 @@
+import type Stripe from "stripe";
+import type { Context } from "../context.ts";
+import { Resource } from "../resource.ts";
+import type { Secret } from "../secret.ts";
+import {
+  createStripeClient,
+  handleStripeDeleteError,
+  isStripeConflictError,
+} from "./client.ts";
+
+type CouponDuration = Stripe.CouponCreateParams.Duration;
+
+/**
+ * Properties for creating a Stripe coupon
+ */
+export interface CouponProps {
+  /**
+   * Unique string of your choice that will be used to identify this coupon when applying it to a customer
+   */
+  id?: string;
+
+  /**
+   * Specifies how long the discount will be in effect
+   */
+  duration: CouponDuration;
+
+  /**
+   * A positive integer representing the amount to subtract from an invoice total (required if percent_off is not passed)
+   */
+  amountOff?: number;
+
+  /**
+   * Three-letter ISO code for the currency of the amount_off parameter (required if amount_off is passed)
+   */
+  currency?: string;
+
+  /**
+   * Required only if duration is repeating, in which case it must be a positive integer that specifies the number of months the discount will be in effect
+   */
+  durationInMonths?: number;
+
+  /**
+   * A positive integer specifying the number of times the coupon can be redeemed before it's no longer valid
+   */
+  maxRedemptions?: number;
+
+  /**
+   * Name of the coupon displayed to customers on, for instance invoices, or receipts
+   */
+  name?: string;
+
+  /**
+   * A positive float larger than 0, and smaller or equal to 100, that represents the discount the coupon will apply (required if amount_off is not passed)
+   */
+  percentOff?: number;
+
+  /**
+   * Unix timestamp specifying the last time at which the coupon can be redeemed
+   */
+  redeemBy?: number;
+
+  /**
+   * Number of times this coupon has been applied to a customer
+   */
+  timesRedeemed?: number;
+
+  /**
+   * Taking account of the above properties, whether this coupon can still be applied to a customer
+   */
+  valid?: boolean;
+
+  /**
+   * Set of key-value pairs that you can attach to an object
+   */
+  metadata?: Record<string, string>;
+
+  /**
+   * API key to use (overrides environment variable)
+   */
+  apiKey?: Secret;
+
+  /**
+   * If true, adopt existing resource if creation fails due to conflict
+   */
+  adopt?: boolean;
+}
+
+/**
+ * Output from the Stripe coupon
+ */
+export interface Coupon extends Resource<"stripe::Coupon">, CouponProps {
+  /**
+   * The ID of the coupon
+   */
+  id: string;
+
+  /**
+   * String representing the object's type
+   */
+  object: "coupon";
+
+  /**
+   * Time at which the object was created
+   */
+  created: number;
+
+  /**
+   * Has the value true if the object exists in live mode or the value false if the object exists in test mode
+   */
+  livemode: boolean;
+}
+
+/**
+ * Create and manage Stripe coupons for discounts
+ *
+ * @example
+ * // Create a percentage-based coupon
+ * const percentageCoupon = await Coupon("summer-sale", {
+ *   id: "SUMMER25",
+ *   duration: "once",
+ *   percentOff: 25,
+ *   name: "Summer Sale 25% Off",
+ *   maxRedemptions: 1000,
+ *   metadata: {
+ *     campaign: "summer_2024",
+ *     type: "seasonal"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a fixed amount coupon
+ * const fixedAmountCoupon = await Coupon("new-customer", {
+ *   id: "WELCOME10",
+ *   duration: "once",
+ *   amountOff: 1000,
+ *   currency: "usd",
+ *   name: "Welcome $10 Off",
+ *   metadata: {
+ *     type: "welcome",
+ *     target: "new_customers"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a repeating coupon for subscriptions
+ * const subscriptionCoupon = await Coupon("loyal-customer", {
+ *   id: "LOYAL15",
+ *   duration: "repeating",
+ *   durationInMonths: 6,
+ *   percentOff: 15,
+ *   name: "Loyal Customer 15% Off",
+ *   metadata: {
+ *     type: "loyalty",
+ *     tier: "premium"
+ *   }
+ * });
+ */
+export const Coupon = Resource(
+  "stripe::Coupon",
+  async function (
+    this: Context<Coupon>,
+    _id: string,
+    props: CouponProps,
+  ): Promise<Coupon> {
+    const stripe = createStripeClient({ apiKey: props.apiKey });
+
+    if (this.phase === "delete") {
+      try {
+        if (this.output?.id) {
+          await stripe.coupons.del(this.output.id);
+        }
+      } catch (error) {
+        handleStripeDeleteError(error, "Coupon", this.output?.id);
+      }
+      return this.destroy();
+    }
+
+    try {
+      let coupon: Stripe.Coupon;
+
+      if (this.phase === "update" && this.output?.id) {
+        coupon = await stripe.coupons.update(this.output.id, {
+          name: props.name,
+          metadata: props.metadata,
+        });
+      } else {
+        const createParams: Stripe.CouponCreateParams = {
+          duration: props.duration,
+          name: props.name,
+          metadata: props.metadata,
+        };
+
+        if (props.id) {
+          createParams.id = props.id;
+        }
+        if (props.amountOff !== undefined) {
+          createParams.amount_off = props.amountOff;
+        }
+        if (props.currency) {
+          createParams.currency = props.currency;
+        }
+        if (props.durationInMonths !== undefined) {
+          createParams.duration_in_months = props.durationInMonths;
+        }
+        if (props.maxRedemptions !== undefined) {
+          createParams.max_redemptions = props.maxRedemptions;
+        }
+        if (props.percentOff !== undefined) {
+          createParams.percent_off = props.percentOff;
+        }
+        if (props.redeemBy !== undefined) {
+          createParams.redeem_by = props.redeemBy;
+        }
+
+        try {
+          try {
+            coupon = await stripe.coupons.create(createParams);
+          } catch (error) {
+            if (isStripeConflictError(error) && props.adopt) {
+              if (props.id) {
+                const existingCoupon = await stripe.coupons.retrieve(props.id);
+                const updateParams: Stripe.CouponUpdateParams = {
+                  metadata: props.metadata,
+                  name: props.name,
+                };
+                coupon = await stripe.coupons.update(
+                  existingCoupon.id,
+                  updateParams,
+                );
+              } else {
+                throw error;
+              }
+            } else {
+              throw error;
+            }
+          }
+        } catch (error) {
+          if (isStripeConflictError(error) && props.adopt) {
+            if (props.id) {
+              const existingCoupon = await stripe.coupons.retrieve(props.id);
+              const updateParams: Stripe.CouponUpdateParams = {
+                metadata: props.metadata,
+                name: props.name,
+              };
+              coupon = await stripe.coupons.update(
+                existingCoupon.id,
+                updateParams,
+              );
+            } else {
+              throw error;
+            }
+          } else {
+            throw error;
+          }
+        }
+      }
+
+      return this({
+        id: coupon.id,
+        object: coupon.object,
+        duration: coupon.duration as CouponDuration,
+        amountOff: coupon.amount_off || undefined,
+        currency: coupon.currency || undefined,
+        durationInMonths: coupon.duration_in_months || undefined,
+        maxRedemptions: coupon.max_redemptions || undefined,
+        name: coupon.name || undefined,
+        percentOff: coupon.percent_off || undefined,
+        redeemBy: coupon.redeem_by || undefined,
+        timesRedeemed: coupon.times_redeemed || undefined,
+        valid: coupon.valid,
+        metadata: coupon.metadata || undefined,
+        created: coupon.created,
+        livemode: coupon.livemode,
+      });
+    } catch (error) {
+      console.error("Error creating/updating coupon:", error);
+      throw error;
+    }
+  },
+);