alchemy 0.24.0 → 0.25.0

package/src/stripe/product-feature.ts

@@ -0,0 +1,150 @@
+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";
+
+/**
+ * Properties for creating a Stripe product feature
+ */
+export interface ProductFeatureProps {
+  /**
+   * The ID of the product that this feature will be attached to
+   */
+  product: string;
+
+  /**
+   * The ID of the entitlements feature to attach to the product
+   */
+  entitlementFeature: 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 product feature
+ */
+export interface ProductFeature
+  extends Resource<"stripe::ProductFeature">,
+    ProductFeatureProps {
+  /**
+   * The ID of the product feature
+   */
+  id: string;
+
+  /**
+   * String representing the object's type
+   */
+  object: "product_feature";
+
+  /**
+   * The entitlement feature object attached to this product
+   */
+  entitlementFeatureObject?: {
+    id: string;
+    name: string;
+    lookupKey?: string;
+    metadata?: Record<string, string>;
+  };
+
+  /**
+   * 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 product features
+ *
+ * @example
+ * // Attach an API access feature to a product
+ * const productApiFeature = await ProductFeature("product-api-access", {
+ *   product: "prod_xyz123",
+ *   entitlementFeature: "feat_abc456"
+ * });
+ *
+ * @example
+ * // Attach analytics feature to a premium product
+ * const productAnalytics = await ProductFeature("premium-analytics", {
+ *   product: "prod_premium789",
+ *   entitlementFeature: "feat_analytics123"
+ * });
+ *
+ * @example
+ * // Attach custom integrations to enterprise product
+ * const enterpriseIntegrations = await ProductFeature("enterprise-integrations", {
+ *   product: "prod_enterprise456",
+ *   entitlementFeature: "feat_integrations789"
+ * });
+ */
+export const ProductFeature = Resource(
+  "stripe::ProductFeature",
+  async function (
+    this: Context<ProductFeature>,
+    _id: string,
+    props: ProductFeatureProps,
+  ): Promise<ProductFeature> {
+    const stripe = createStripeClient({ apiKey: props.apiKey });
+
+    if (this.phase === "delete") {
+      try {
+        if (this.output?.id && this.output?.product) {
+          await stripe.products.deleteFeature(
+            this.output.product,
+            this.output.id,
+          );
+        }
+      } catch (error) {
+        handleStripeDeleteError(error, "ProductFeature", this.output?.id);
+      }
+      return this.destroy();
+    }
+
+    try {
+      let productFeature: Stripe.ProductFeature;
+
+      if (this.phase === "update" && this.output?.id) {
+        throw new Error("Product features cannot be updated after creation");
+      } else {
+        try {
+          productFeature = await stripe.products.createFeature(props.product, {
+            entitlement_feature: props.entitlementFeature,
+          });
+        } catch (error) {
+          if (isStripeConflictError(error) && props.adopt) {
+            throw new Error(
+              "ProductFeature adoption is not supported - product features cannot be uniquely identified for adoption",
+            );
+          } else {
+            throw error;
+          }
+        }
+      }
+
+      return this({
+        id: productFeature.id,
+        object: productFeature.object,
+        product: props.product,
+        entitlementFeature: props.entitlementFeature,
+        entitlementFeatureObject:
+          productFeature.entitlement_feature || undefined,
+        livemode: productFeature.livemode,
+      });
+    } catch (error) {
+      console.error("Error creating product feature:", error);
+      throw error;
+    }
+  },
+);

package/src/stripe/product.ts

@@ -1,6 +1,8 @@
-import Stripe from "stripe";
+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 } from "./client.ts";
 
 type ProductType = Stripe.Product.Type;
 
@@ -62,6 +64,16 @@ export interface ProductProps {
    * Default tax code for the product
    */
   taxCode?: string;
+
+  /**
+   * API key to use (overrides environment variable)
+   */
+  apiKey?: Secret;
+
+  /**
+   * If true, adopt existing resource if creation fails due to conflict
+   */
+  adopt?: boolean;
 }
 
 /**
@@ -144,14 +156,7 @@ export const Product = Resource(
     _id: string,
     props: ProductProps,
   ): Promise<Product> {
-    // Get Stripe API key from context or environment
-    const apiKey = process.env.STRIPE_API_KEY;
-    if (!apiKey) {
-      throw new Error("STRIPE_API_KEY environment variable is required");
-    }
-
-    // Initialize Stripe client
-    const stripe = new Stripe(apiKey);
+    const stripe = createStripeClient({ apiKey: props.apiKey });
 
     if (this.phase === "delete") {
       try {
@@ -159,8 +164,7 @@ export const Product = Resource(
           await stripe.products.update(this.output.id, { active: false });
         }
       } catch (error) {
-        // Ignore if the product doesn't exist
-        console.error("Error deactivating product:", error);
+        handleStripeDeleteError(error, "Product", this.output?.id);
       }
 
       // Return a minimal output for deleted state
@@ -171,7 +175,7 @@ export const Product = Resource(
 
       if (this.phase === "update" && this.output?.id) {
         // Update existing product
-        product = await stripe.products.update(this.output.id, {
+        const updateParams = {
           name: props.name,
           description: props.description,
           active: props.active,
@@ -180,10 +184,11 @@ export const Product = Resource(
           statement_descriptor: props.statementDescriptor,
           metadata: props.metadata,
           tax_code: props.taxCode,
-        });
+        };
+        product = await stripe.products.update(this.output.id, updateParams);
       } else {
         // Create new product
-        product = await stripe.products.create({
+        const createParams = {
           name: props.name,
           description: props.description,
           active: props.active,
@@ -195,7 +200,35 @@ export const Product = Resource(
           statement_descriptor: props.statementDescriptor,
           metadata: props.metadata,
           tax_code: props.taxCode,
-        });
+        };
+        if (props.adopt) {
+          const existingProducts = await stripe.products.list({
+            limit: 100,
+          });
+          const existingProduct = existingProducts.data.find(
+            (p) => p.name === props.name,
+          );
+          if (existingProduct) {
+            const updateParams = {
+              name: props.name,
+              description: props.description,
+              active: props.active,
+              images: props.images,
+              url: props.url,
+              statement_descriptor: props.statementDescriptor,
+              metadata: props.metadata,
+              tax_code: props.taxCode,
+            };
+            product = await stripe.products.update(
+              existingProduct.id,
+              updateParams,
+            );
+          } else {
+            product = await stripe.products.create(createParams);
+          }
+        } else {
+          product = await stripe.products.create(createParams);
+        }
       }
 
       return this({

package/src/stripe/promotion-code.ts

@@ -0,0 +1,268 @@
+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";
+
+/**
+ * Restrictions for promotion code usage
+ */
+export interface PromotionCodeRestrictions {
+  /**
+   * Promotion codes defined with this restriction will only work for Checkout Sessions in payment mode
+   */
+  firstTimeTransaction?: boolean;
+  /**
+   * Minimum amount required to redeem this promotion code into a coupon
+   */
+  minimumAmount?: number;
+  /**
+   * Three-letter ISO code for minimum_amount
+   */
+  minimumAmountCurrency?: string;
+}
+
+/**
+ * Properties for creating a Stripe promotion code
+ */
+export interface PromotionCodeProps {
+  /**
+   * The coupon for this promotion code
+   */
+  coupon: string;
+  /**
+   * The customer-facing code. Regardless of case, this code must be unique across all active promotion codes for a specific customer
+   */
+  code?: string;
+  /**
+   * Whether the promotion code is currently active
+   */
+  active?: boolean;
+  /**
+   * The customer that this promotion code can be used by
+   */
+  customer?: string;
+  /**
+   * The timestamp at which this promotion code will expire
+   */
+  expiresAt?: number;
+  /**
+   * The maximum number of times this promotion code can be redeemed
+   */
+  maxRedemptions?: number;
+  /**
+   * Set of key-value pairs that you can attach to an object
+   */
+  metadata?: Record<string, string>;
+  /**
+   * Settings that restrict the redemption of the promotion code
+   */
+  restrictions?: PromotionCodeRestrictions;
+
+  /**
+   * 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 promotion code
+ */
+export interface PromotionCode
+  extends Resource<"stripe::PromotionCode">,
+    PromotionCodeProps {
+  /**
+   * The ID of the promotion code
+   */
+  id: string;
+  /**
+   * String representing the object's type
+   */
+  object: "promotion_code";
+  /**
+   * 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;
+  /**
+   * Number of times this promotion code has been used
+   */
+  timesRedeemed: number;
+}
+
+/**
+ * Create and manage Stripe promotion codes for coupons
+ *
+ * @example
+ * // Create a basic promotion code
+ * const basicPromoCode = await PromotionCode("summer-promo", {
+ *   coupon: "SUMMER25",
+ *   code: "SAVE25NOW",
+ *   active: true,
+ *   metadata: {
+ *     campaign: "summer_sale",
+ *     channel: "email"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a customer-specific promotion code
+ * const customerPromoCode = await PromotionCode("vip-discount", {
+ *   coupon: "VIP15",
+ *   code: "VIP15OFF",
+ *   customer: "cus_xyz123",
+ *   maxRedemptions: 1,
+ *   expiresAt: Math.floor(Date.now() / 1000) + 86400 * 30,
+ *   metadata: {
+ *     type: "vip_exclusive",
+ *     tier: "gold"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a promotion code with restrictions
+ * const restrictedPromoCode = await PromotionCode("first-time-buyer", {
+ *   coupon: "WELCOME10",
+ *   code: "FIRSTTIME10",
+ *   restrictions: {
+ *     firstTimeTransaction: true,
+ *     minimumAmount: 5000,
+ *     minimumAmountCurrency: "usd"
+ *   },
+ *   maxRedemptions: 1000,
+ *   metadata: {
+ *     campaign: "new_customer_acquisition",
+ *     minimum_order: "50_usd"
+ *   }
+ * });
+ */
+export const PromotionCode = Resource(
+  "stripe::PromotionCode",
+  async function (
+    this: Context<PromotionCode>,
+    _id: string,
+    props: PromotionCodeProps,
+  ): Promise<PromotionCode> {
+    const stripe = createStripeClient({ apiKey: props.apiKey });
+
+    if (this.phase === "delete") {
+      try {
+        if (this.output?.id) {
+          await stripe.promotionCodes.update(this.output.id, { active: false });
+        }
+      } catch (error) {
+        handleStripeDeleteError(error, "PromotionCode", this.output?.id);
+      }
+      return this.destroy();
+    }
+
+    try {
+      let promotionCode: Stripe.PromotionCode;
+
+      if (this.phase === "update" && this.output?.id) {
+        const updateParams: Stripe.PromotionCodeUpdateParams = {
+          active: props.active,
+          metadata: props.metadata,
+        };
+        promotionCode = await stripe.promotionCodes.update(
+          this.output.id,
+          updateParams,
+        );
+      } else {
+        const createParams: Stripe.PromotionCodeCreateParams = {
+          coupon: props.coupon,
+          code: props.code,
+          active: props.active,
+          customer: props.customer,
+          expires_at: props.expiresAt,
+          max_redemptions: props.maxRedemptions,
+          metadata: props.metadata,
+        };
+
+        if (props.restrictions) {
+          createParams.restrictions = {
+            first_time_transaction: props.restrictions.firstTimeTransaction,
+            minimum_amount: props.restrictions.minimumAmount,
+            minimum_amount_currency: props.restrictions.minimumAmountCurrency,
+          };
+        }
+
+        try {
+          promotionCode = await stripe.promotionCodes.create(createParams);
+        } catch (error) {
+          if (isStripeConflictError(error) && props.adopt) {
+            if (props.code) {
+              const existingPromotionCodes = await stripe.promotionCodes.list({
+                code: props.code,
+                limit: 1,
+              });
+              if (existingPromotionCodes.data.length > 0) {
+                const existingPromotionCode = existingPromotionCodes.data[0];
+                const updateParams: Stripe.PromotionCodeUpdateParams = {
+                  active: props.active,
+                  metadata: props.metadata,
+                };
+                promotionCode = await stripe.promotionCodes.update(
+                  existingPromotionCode.id,
+                  updateParams,
+                );
+              } else {
+                throw error;
+              }
+            } else {
+              throw error;
+            }
+          } else {
+            throw error;
+          }
+        }
+      }
+
+      return this({
+        id: promotionCode.id,
+        object: promotionCode.object,
+        coupon:
+          typeof promotionCode.coupon === "string"
+            ? promotionCode.coupon
+            : promotionCode.coupon.id,
+        code: promotionCode.code,
+        active: promotionCode.active,
+        customer:
+          typeof promotionCode.customer === "string"
+            ? promotionCode.customer
+            : promotionCode.customer?.id,
+        expiresAt: promotionCode.expires_at || undefined,
+        maxRedemptions: promotionCode.max_redemptions || undefined,
+        metadata: promotionCode.metadata || undefined,
+        restrictions: promotionCode.restrictions
+          ? {
+              firstTimeTransaction:
+                promotionCode.restrictions.first_time_transaction || undefined,
+              minimumAmount:
+                promotionCode.restrictions.minimum_amount || undefined,
+              minimumAmountCurrency:
+                promotionCode.restrictions.minimum_amount_currency || undefined,
+            }
+          : undefined,
+        created: promotionCode.created,
+        livemode: promotionCode.livemode,
+        timesRedeemed: promotionCode.times_redeemed,
+      });
+    } catch (error) {
+      console.error("Error creating/updating promotion code:", error);
+      throw error;
+    }
+  },
+);