alchemy 0.24.0 → 0.25.0

package/src/stripe/shipping-rate.ts

@@ -0,0 +1,362 @@
+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";
+
+/**
+ * Delivery estimate for shipping rate
+ */
+export interface ShippingRateDeliveryEstimate {
+  /**
+   * The lower bound of the estimated range
+   */
+  minimum?: {
+    /**
+     * A unit of time
+     */
+    unit: Stripe.ShippingRateCreateParams.DeliveryEstimate.Minimum.Unit;
+    /**
+     * Must be greater than 0
+     */
+    value: number;
+  };
+  /**
+   * The upper bound of the estimated range
+   */
+  maximum?: {
+    /**
+     * A unit of time
+     */
+    unit: Stripe.ShippingRateCreateParams.DeliveryEstimate.Maximum.Unit;
+    /**
+     * Must be greater than 0
+     */
+    value: number;
+  };
+}
+
+/**
+ * Fixed amount configuration for shipping rate
+ */
+export interface ShippingRateFixedAmount {
+  /**
+   * A non-negative integer in cents representing how much to charge
+   */
+  amount: number;
+  /**
+   * Three-letter ISO currency code, in lowercase
+   */
+  currency: string;
+  /**
+   * Shipping rates defined in each available currency option
+   */
+  currencyOptions?: Record<
+    string,
+    {
+      /**
+       * A non-negative integer in cents representing how much to charge
+       */
+      amount: number;
+      /**
+       * Specifies whether the rate is considered inclusive or exclusive of taxes
+       */
+      taxBehavior?: Stripe.ShippingRateCreateParams.FixedAmount.CurrencyOptions.TaxBehavior;
+    }
+  >;
+}
+
+/**
+ * Properties for creating a Stripe shipping rate
+ */
+export interface ShippingRateProps {
+  /**
+   * The name of the shipping rate, meant to be displayable to the customer
+   */
+  displayName: string;
+  /**
+   * Describes a fixed amount to charge for shipping
+   */
+  fixedAmount?: ShippingRateFixedAmount;
+  /**
+   * The estimated range for how long shipping will take
+   */
+  deliveryEstimate?: ShippingRateDeliveryEstimate;
+  /**
+   * Set of key-value pairs that you can attach to an object
+   */
+  metadata?: Record<string, string>;
+  /**
+   * Whether the shipping rate can be used for new purchases
+   */
+  active?: boolean;
+  /**
+   * Specifies whether the rate is considered inclusive or exclusive of taxes
+   */
+  taxBehavior?: Stripe.ShippingRateCreateParams.TaxBehavior;
+  /**
+   * A tax code ID
+   */
+  taxCode?: string;
+  /**
+   * The type of calculation to use on the shipping rate
+   */
+  type?: "fixed_amount";
+
+  /**
+   * 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 shipping rate
+ */
+export interface ShippingRate
+  extends Resource<"stripe::ShippingRate">,
+    ShippingRateProps {
+  /**
+   * The ID of the shipping rate
+   */
+  id: string;
+  /**
+   * String representing the object's type
+   */
+  object: "shipping_rate";
+  /**
+   * 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 shipping rates
+ *
+ * @example
+ * // Create a standard shipping rate
+ * const standardShipping = await ShippingRate("standard-shipping", {
+ *   displayName: "Standard Shipping",
+ *   type: "fixed_amount",
+ *   fixedAmount: {
+ *     amount: 500,
+ *     currency: "usd"
+ *   },
+ *   deliveryEstimate: {
+ *     minimum: { unit: "business_day", value: 5 },
+ *     maximum: { unit: "business_day", value: 7 }
+ *   },
+ *   taxBehavior: "exclusive"
+ * });
+ *
+ * @example
+ * // Create an express shipping rate
+ * const expressShipping = await ShippingRate("express-shipping", {
+ *   displayName: "Express Shipping",
+ *   type: "fixed_amount",
+ *   fixedAmount: {
+ *     amount: 1500,
+ *     currency: "usd"
+ *   },
+ *   deliveryEstimate: {
+ *     minimum: { unit: "business_day", value: 1 },
+ *     maximum: { unit: "business_day", value: 2 }
+ *   },
+ *   taxBehavior: "exclusive",
+ *   metadata: {
+ *     priority: "high",
+ *     service_level: "express"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a free shipping rate
+ * const freeShipping = await ShippingRate("free-shipping", {
+ *   displayName: "Free Shipping",
+ *   type: "fixed_amount",
+ *   fixedAmount: {
+ *     amount: 0,
+ *     currency: "usd"
+ *   },
+ *   deliveryEstimate: {
+ *     minimum: { unit: "business_day", value: 7 },
+ *     maximum: { unit: "business_day", value: 10 }
+ *   },
+ *   taxBehavior: "unspecified",
+ *   metadata: {
+ *     promotion: "free_shipping_over_50",
+ *     cost_center: "marketing"
+ *   }
+ * });
+ */
+export const ShippingRate = Resource(
+  "stripe::ShippingRate",
+  async function (
+    this: Context<ShippingRate>,
+    _id: string,
+    props: ShippingRateProps,
+  ): Promise<ShippingRate> {
+    const stripe = createStripeClient({ apiKey: props.apiKey });
+
+    if (this.phase === "delete") {
+      try {
+        if (this.output?.id) {
+          await stripe.shippingRates.update(this.output.id, { active: false });
+        }
+      } catch (error) {
+        handleStripeDeleteError(error, "ShippingRate", this.output?.id);
+      }
+      return this.destroy();
+    }
+
+    try {
+      let shippingRate: Stripe.ShippingRate;
+
+      if (this.phase === "update" && this.output?.id) {
+        const updateParams: any = {
+          metadata: props.metadata,
+          tax_behavior: props.taxBehavior,
+        };
+        if (props.active !== undefined) updateParams.active = props.active;
+        shippingRate = await stripe.shippingRates.update(
+          this.output.id,
+          updateParams,
+        );
+      } else {
+        const createParams: Stripe.ShippingRateCreateParams = {
+          display_name: props.displayName,
+          metadata: props.metadata,
+
+          tax_behavior: props.taxBehavior,
+          tax_code: props.taxCode,
+          type: props.type,
+        };
+
+        if (props.fixedAmount) {
+          createParams.fixed_amount = {
+            amount: props.fixedAmount.amount,
+            currency: props.fixedAmount.currency,
+            currency_options: props.fixedAmount.currencyOptions
+              ? Object.fromEntries(
+                  Object.entries(props.fixedAmount.currencyOptions).map(
+                    ([key, value]) => [
+                      key,
+                      {
+                        amount: value.amount,
+                        tax_behavior: value.taxBehavior,
+                      },
+                    ],
+                  ),
+                )
+              : undefined,
+          };
+        }
+
+        if (props.deliveryEstimate) {
+          createParams.delivery_estimate = {
+            minimum: props.deliveryEstimate.minimum
+              ? {
+                  unit: props.deliveryEstimate.minimum.unit,
+                  value: props.deliveryEstimate.minimum.value,
+                }
+              : undefined,
+            maximum: props.deliveryEstimate.maximum
+              ? {
+                  unit: props.deliveryEstimate.maximum.unit,
+                  value: props.deliveryEstimate.maximum.value,
+                }
+              : undefined,
+          };
+        }
+
+        try {
+          try {
+            shippingRate = await stripe.shippingRates.create(createParams);
+          } catch (error) {
+            if (isStripeConflictError(error) && props.adopt) {
+              throw new Error(
+                "ShippingRate adoption is not supported - shipping rates cannot be uniquely identified for adoption",
+              );
+            } else {
+              throw error;
+            }
+          }
+        } catch (error) {
+          if (isStripeConflictError(error) && props.adopt) {
+            throw new Error(
+              "ShippingRate adoption is not supported - shipping rates cannot be uniquely identified for adoption",
+            );
+          } else {
+            throw error;
+          }
+        }
+      }
+
+      return this({
+        id: shippingRate.id,
+        object: shippingRate.object,
+        displayName: shippingRate.display_name || "",
+        fixedAmount: shippingRate.fixed_amount
+          ? {
+              amount: shippingRate.fixed_amount.amount,
+              currency: shippingRate.fixed_amount.currency,
+              currencyOptions: shippingRate.fixed_amount.currency_options
+                ? Object.fromEntries(
+                    Object.entries(
+                      shippingRate.fixed_amount.currency_options,
+                    ).map(([key, value]) => [
+                      key,
+                      {
+                        amount: value.amount,
+                        taxBehavior: value.tax_behavior,
+                      },
+                    ]),
+                  )
+                : undefined,
+            }
+          : undefined,
+        deliveryEstimate: shippingRate.delivery_estimate
+          ? {
+              minimum: shippingRate.delivery_estimate.minimum
+                ? {
+                    unit: shippingRate.delivery_estimate.minimum.unit,
+                    value: shippingRate.delivery_estimate.minimum.value,
+                  }
+                : undefined,
+              maximum: shippingRate.delivery_estimate.maximum
+                ? {
+                    unit: shippingRate.delivery_estimate.maximum.unit,
+                    value: shippingRate.delivery_estimate.maximum.value,
+                  }
+                : undefined,
+            }
+          : undefined,
+        metadata: shippingRate.metadata || undefined,
+        active: shippingRate.active,
+        taxBehavior: shippingRate.tax_behavior || undefined,
+        taxCode:
+          typeof shippingRate.tax_code === "string"
+            ? shippingRate.tax_code
+            : undefined,
+        type: shippingRate.type || undefined,
+        created: shippingRate.created,
+        livemode: shippingRate.livemode,
+      });
+    } catch (error) {
+      console.error("Error creating/updating shipping rate:", error);
+      throw error;
+    }
+  },
+);

package/src/stripe/tax-rate.ts

@@ -0,0 +1,218 @@
+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 tax rate
+ */
+export interface TaxRateProps {
+  /**
+   * The display name of the tax rate, which will be shown to users
+   */
+  displayName: string;
+  /**
+   * This represents the tax rate percent out of 100
+   */
+  percentage: number;
+  /**
+   * This specifies if the tax rate is inclusive or exclusive
+   */
+  inclusive: boolean;
+  /**
+   * Flag determining whether the tax rate is active or inactive
+   */
+  active?: boolean;
+  /**
+   * Two-letter country code (ISO 3166-1 alpha-2)
+   */
+  country?: string;
+  /**
+   * An arbitrary string attached to the tax rate for your internal use only
+   */
+  description?: string;
+  /**
+   * The jurisdiction for the tax rate
+   */
+  jurisdiction?: string;
+  /**
+   * Set of key-value pairs that you can attach to an object
+   */
+  metadata?: Record<string, string>;
+  /**
+   * ISO 3166-2 subdivision code, without country prefix
+   */
+  state?: string;
+  /**
+   * The high-level tax type, such as vat or sales_tax
+   */
+  taxType?: Stripe.TaxRateCreateParams.TaxType;
+  /**
+   * 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 tax rate
+ */
+export interface TaxRate extends Resource<"stripe::TaxRate">, TaxRateProps {
+  /**
+   * The ID of the tax rate
+   */
+  id: string;
+  /**
+   * String representing the object's type
+   */
+  object: "tax_rate";
+  /**
+   * 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 tax rates
+ *
+ * @example
+ * // Create a basic sales tax rate
+ * const salesTax = await TaxRate("ca-sales-tax", {
+ *   displayName: "CA Sales Tax",
+ *   percentage: 8.5,
+ *   inclusive: false,
+ *   active: true,
+ *   country: "US",
+ *   state: "CA",
+ *   description: "California sales tax",
+ *   taxType: "sales_tax"
+ * });
+ *
+ * @example
+ * // Create a VAT tax rate
+ * const vatTax = await TaxRate("uk-vat", {
+ *   displayName: "UK VAT",
+ *   percentage: 20.0,
+ *   inclusive: true,
+ *   active: true,
+ *   country: "GB",
+ *   description: "United Kingdom Value Added Tax",
+ *   taxType: "vat",
+ *   metadata: {
+ *     region: "europe",
+ *     tax_authority: "hmrc"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a city tax rate
+ * const cityTax = await TaxRate("nyc-tax", {
+ *   displayName: "NYC Local Tax",
+ *   percentage: 4.5,
+ *   inclusive: false,
+ *   active: true,
+ *   country: "US",
+ *   state: "NY",
+ *   jurisdiction: "New York City",
+ *   description: "New York City local sales tax",
+ *   taxType: "sales_tax",
+ *   metadata: {
+ *     locality: "nyc",
+ *     tax_level: "city"
+ *   }
+ * });
+ */
+export const TaxRate = Resource(
+  "stripe::TaxRate",
+  async function (
+    this: Context<TaxRate>,
+    _id: string,
+    props: TaxRateProps,
+  ): Promise<TaxRate> {
+    const stripe = createStripeClient({ apiKey: props.apiKey });
+
+    if (this.phase === "delete") {
+      try {
+        if (this.output?.id) {
+          await stripe.taxRates.update(this.output.id, { active: false });
+        }
+      } catch (error) {
+        handleStripeDeleteError(error, "TaxRate", this.output?.id);
+      }
+      return this.destroy();
+    }
+
+    try {
+      let taxRate: Stripe.TaxRate;
+
+      if (this.phase === "update" && this.output?.id) {
+        taxRate = await stripe.taxRates.update(this.output.id, {
+          active: props.active,
+          country: props.country,
+          description: props.description,
+          display_name: props.displayName,
+          jurisdiction: props.jurisdiction,
+          metadata: props.metadata,
+          state: props.state,
+          tax_type: props.taxType,
+        });
+      } else {
+        try {
+          taxRate = await stripe.taxRates.create({
+            display_name: props.displayName,
+            percentage: props.percentage,
+            inclusive: props.inclusive,
+            active: props.active,
+            country: props.country,
+            description: props.description,
+            jurisdiction: props.jurisdiction,
+            metadata: props.metadata,
+            state: props.state,
+            tax_type: props.taxType,
+          });
+        } catch (error) {
+          if (isStripeConflictError(error) && props.adopt) {
+            throw new Error(
+              "TaxRate adoption is not supported - tax rates cannot be uniquely identified for adoption",
+            );
+          } else {
+            throw error;
+          }
+        }
+      }
+
+      return this({
+        id: taxRate.id,
+        object: taxRate.object,
+        displayName: taxRate.display_name,
+        percentage: taxRate.percentage,
+        inclusive: taxRate.inclusive,
+        active: taxRate.active,
+        country: taxRate.country || undefined,
+        description: taxRate.description || undefined,
+        jurisdiction: taxRate.jurisdiction || undefined,
+        metadata: taxRate.metadata || undefined,
+        state: taxRate.state || undefined,
+        taxType: taxRate.tax_type || undefined,
+        created: taxRate.created,
+        livemode: taxRate.livemode,
+      });
+    } catch (error) {
+      console.error("Error creating/updating tax rate:", error);
+      throw error;
+    }
+  },
+);

package/src/stripe/webhook.ts

@@ -1,6 +1,12 @@
-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,
+  isStripeConflictError,
+} from "./client.ts";
 
 export type EnabledEvent = Stripe.WebhookEndpointUpdateParams.EnabledEvent;
 
@@ -42,6 +48,16 @@ export interface WebhookEndpointProps {
    * Webhook endpoint metadata
    */
   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;
 }
 
 /**
@@ -138,14 +154,7 @@ export const WebhookEndpoint = Resource(
     _id: string,
     props: WebhookEndpointProps,
   ) {
-    // 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 {
@@ -154,8 +163,7 @@ export const WebhookEndpoint = Resource(
           await stripe.webhookEndpoints.del(this.output.id);
         }
       } catch (error) {
-        // Ignore if the webhook doesn't exist
-        console.error("Error deleting webhook:", error);
+        handleStripeDeleteError(error, "WebhookEndpoint", this.output?.id);
       }
 
       return this.destroy();
@@ -165,21 +173,80 @@ export const WebhookEndpoint = Resource(
 
       if (this.phase === "update" && this.output?.id) {
         // Update existing webhook
-        webhook = await stripe.webhookEndpoints.update(this.output.id, {
+        const updateParams = {
           url: props.url,
           enabled_events: props.enabledEvents,
           description: props.description,
           disabled: props.active === false,
           metadata: props.metadata,
-        });
+        };
+        webhook = await stripe.webhookEndpoints.update(
+          this.output.id,
+          updateParams,
+        );
       } else {
         // Create new webhook
-        webhook = await stripe.webhookEndpoints.create({
+        const createParams = {
           url: props.url,
           enabled_events: props.enabledEvents,
           description: props.description,
           metadata: props.metadata,
-        });
+        };
+        try {
+          try {
+            webhook = await stripe.webhookEndpoints.create(createParams);
+          } catch (error) {
+            if (isStripeConflictError(error) && props.adopt) {
+              const existingWebhooks = await stripe.webhookEndpoints.list({
+                limit: 100,
+              });
+              const existingWebhook = existingWebhooks.data.find(
+                (w) => w.url === props.url,
+              );
+              if (existingWebhook) {
+                const updateParams: Stripe.WebhookEndpointUpdateParams = {
+                  url: props.url,
+                  enabled_events: props.enabledEvents as any,
+                  description: props.description,
+                  metadata: props.metadata,
+                };
+                webhook = await stripe.webhookEndpoints.update(
+                  existingWebhook.id,
+                  updateParams,
+                );
+              } else {
+                throw error;
+              }
+            } else {
+              throw error;
+            }
+          }
+        } catch (error) {
+          if (isStripeConflictError(error) && props.adopt) {
+            const existingWebhooks = await stripe.webhookEndpoints.list({
+              limit: 100,
+            });
+            const existingWebhook = existingWebhooks.data.find(
+              (w) => w.url === props.url,
+            );
+            if (existingWebhook) {
+              const updateParams: Stripe.WebhookEndpointUpdateParams = {
+                url: props.url,
+                enabled_events: props.enabledEvents as any,
+                description: props.description,
+                metadata: props.metadata,
+              };
+              webhook = await stripe.webhookEndpoints.update(
+                existingWebhook.id,
+                updateParams,
+              );
+            } else {
+              throw error;
+            }
+          } else {
+            throw error;
+          }
+        }
 
         // For connect parameter, need to handle it separately if it exists
         if (props.connect !== undefined) {