alchemy 0.24.0 → 0.25.0

package/src/cloudflare/zone.ts

@@ -165,9 +165,9 @@ export interface ZoneProps extends CloudflareApiOptions {
 }
 
 /**
- * Output returned after Zone creation/update
+ * Zone data structure (used for lookup functions)
  */
-export interface Zone extends Resource<"cloudflare::Zone"> {
+export interface ZoneData {
   /**
    * The ID of the zone
    */
@@ -246,6 +246,11 @@ export interface Zone extends Resource<"cloudflare::Zone"> {
   };
 }
 
+/**
+ * Output returned after Zone creation/update
+ */
+export interface Zone extends Resource<"cloudflare::Zone">, ZoneData {}
+
 /**
  * A Cloudflare Zone represents a domain and its configuration settings on Cloudflare.
  * Zones allow you to manage DNS, SSL/TLS, caching, security and other settings for a domain.
@@ -539,6 +544,74 @@ async function getZoneSettings(
   };
 }
 
+/**
+ * Look up a Cloudflare zone by domain name
+ *
+ * @param domainName The domain name to look up (e.g., "example.com")
+ * @param options Optional API configuration
+ * @returns Promise resolving to zone details or null if not found
+ *
+ * @example
+ * // Look up a zone by domain name
+ * const zone = await getZoneByDomain("example.com");
+ * if (zone) {
+ *   console.log(`Zone ID: ${zone.id}`);
+ *   console.log(`Nameservers: ${zone.nameservers.join(", ")}`);
+ * }
+ *
+ * @example
+ * // Look up a zone with custom API options
+ * const zone = await getZoneByDomain("example.com", {
+ *   apiToken: myApiToken,
+ *   accountId: "my-account-id"
+ * });
+ */
+export async function getZoneByDomain(
+  domainName: string,
+  options: Partial<CloudflareApiOptions> = {},
+): Promise<ZoneData | null> {
+  const api = await createCloudflareApi(options);
+
+  const response = await api.get(
+    `/zones?name=${encodeURIComponent(domainName)}`,
+  );
+
+  if (!response.ok) {
+    throw new Error(
+      `Error fetching zone for '${domainName}': ${response.statusText}`,
+    );
+  }
+
+  const zones = ((await response.json()) as { result: CloudflareZone[] })
+    .result;
+
+  if (zones.length === 0) {
+    return null;
+  }
+
+  const zoneData = zones[0];
+
+  // Get zone settings
+  const settings = await getZoneSettings(api, zoneData.id);
+
+  return {
+    id: zoneData.id,
+    name: zoneData.name,
+    type: zoneData.type,
+    status: zoneData.status,
+    paused: zoneData.paused,
+    accountId: zoneData.account.id,
+    nameservers: zoneData.name_servers,
+    originalNameservers: zoneData.original_name_servers,
+    createdAt: new Date(zoneData.created_on).getTime(),
+    modifiedAt: new Date(zoneData.modified_on).getTime(),
+    activatedAt: zoneData.activated_on
+      ? new Date(zoneData.activated_on).getTime()
+      : null,
+    settings,
+  };
+}
+
 /**
  * Cloudflare Zone response format
  */

package/src/fs/file-system-state-store.ts

@@ -11,8 +11,13 @@ const stateRootDir = path.join(process.cwd(), ".alchemy");
 export class FileSystemStateStore implements StateStore {
   public readonly dir: string;
   private initialized = false;
-  constructor(public readonly scope: Scope) {
-    this.dir = path.join(stateRootDir, ...scope.chain);
+  constructor(
+    public readonly scope: Scope,
+    options?: {
+      rootDir?: string;
+    },
+  ) {
+    this.dir = path.join(options?.rootDir ?? stateRootDir, ...scope.chain);
   }
 
   async init(): Promise<void> {

package/src/stripe/card.ts

@@ -0,0 +1,320 @@
+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 card
+ */
+export interface CardProps {
+  /**
+   * The ID of the customer to attach the card to
+   */
+  customer: string;
+
+  /**
+   * A token or source to attach to the customer
+   */
+  source?: string;
+
+  /**
+   * The card number, as a string without any separators
+   */
+  number?: string;
+
+  /**
+   * Two-digit number representing the card's expiration month
+   */
+  expMonth?: number;
+
+  /**
+   * Four-digit number representing the card's expiration year
+   */
+  expYear?: number;
+
+  /**
+   * Card security code
+   */
+  cvc?: string;
+
+  /**
+   * Cardholder's full name
+   */
+  name?: string;
+
+  /**
+   * City/District/Suburb/Town/Village
+   */
+  addressCity?: string;
+
+  /**
+   * Billing address country, if provided when creating card
+   */
+  addressCountry?: string;
+
+  /**
+   * Address line 1 (Street address/PO Box/Company name)
+   */
+  addressLine1?: string;
+
+  /**
+   * Address line 2 (Apartment/Suite/Unit/Building)
+   */
+  addressLine2?: string;
+
+  /**
+   * State/County/Province/Region
+   */
+  addressState?: string;
+
+  /**
+   * ZIP or postal code
+   */
+  addressZip?: string;
+
+  /**
+   * Required when adding a card to an account (not applicable to customers or recipients)
+   */
+  currency?: string;
+
+  /**
+   * Only applicable on accounts (not customers or recipients)
+   */
+  defaultForCurrency?: 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 card
+ */
+export interface Card extends Resource<"stripe::Card">, CardProps {
+  /**
+   * The ID of the card
+   */
+  id: string;
+
+  /**
+   * String representing the object's type
+   */
+  object: "card";
+
+  /**
+   * Card brand (Visa, American Express, MasterCard, Discover, JCB, Diners Club, or Unknown)
+   */
+  brand: string;
+
+  /**
+   * Two-letter ISO code representing the country of the card
+   */
+  country?: string;
+
+  /**
+   * The last four digits of the device account number
+   */
+  dynamicLast4?: string;
+
+  /**
+   * Uniquely identifies this particular card number
+   */
+  fingerprint?: string;
+
+  /**
+   * Card funding type (credit, debit, prepaid, or unknown)
+   */
+  funding: string;
+
+  /**
+   * The last four digits of the card
+   */
+  last4: string;
+
+  /**
+   * If the card number is tokenized, this is the method that was used
+   */
+  tokenizationMethod?: string;
+}
+
+/**
+ * Create and manage Stripe cards attached to customers
+ *
+ * @example
+ * // Create a card using raw card details
+ * const customerCard = await Card("customer-card", {
+ *   customer: "cus_xyz123",
+ *   number: "4242424242424242",
+ *   expMonth: 12,
+ *   expYear: 2025,
+ *   cvc: "123",
+ *   name: "John Doe",
+ *   addressLine1: "123 Main St",
+ *   addressCity: "San Francisco",
+ *   addressState: "CA",
+ *   addressZip: "94105",
+ *   addressCountry: "US"
+ * });
+ *
+ * @example
+ * // Create a card using a token
+ * const tokenCard = await Card("token-card", {
+ *   customer: "cus_xyz123",
+ *   source: "tok_visa",
+ *   metadata: {
+ *     type: "primary",
+ *     source: "mobile_app"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a card for international customer
+ * const internationalCard = await Card("international-card", {
+ *   customer: "cus_international456",
+ *   number: "4000000000000002",
+ *   expMonth: 6,
+ *   expYear: 2026,
+ *   name: "Maria Garcia",
+ *   addressLine1: "Calle Principal 123",
+ *   addressCity: "Madrid",
+ *   addressCountry: "ES",
+ *   addressZip: "28001",
+ *   metadata: {
+ *     region: "europe",
+ *     currency_preference: "eur"
+ *   }
+ * });
+ */
+export const Card = Resource(
+  "stripe::Card",
+  async function (
+    this: Context<Card>,
+    _id: string,
+    props: CardProps,
+  ): Promise<Card> {
+    const stripe = createStripeClient({ apiKey: props.apiKey });
+
+    if (this.phase === "delete") {
+      try {
+        if (this.output?.id && this.output?.customer) {
+          await stripe.customers.deleteSource(
+            this.output.customer,
+            this.output.id,
+          );
+        }
+      } catch (error) {
+        handleStripeDeleteError(error, "Card", this.output?.id);
+      }
+      return this.destroy();
+    }
+
+    try {
+      let card: Stripe.Card;
+
+      if (this.phase === "update" && this.output?.id) {
+        const updateParams = {
+          name: props.name,
+          address_city: props.addressCity,
+          address_country: props.addressCountry,
+          address_line1: props.addressLine1,
+          address_line2: props.addressLine2,
+          address_state: props.addressState,
+          address_zip: props.addressZip,
+          exp_month: props.expMonth?.toString(),
+          exp_year: props.expYear?.toString(),
+          metadata: props.metadata,
+        };
+
+        card = (await stripe.customers.updateSource(
+          props.customer,
+          this.output.id,
+          updateParams,
+        )) as Stripe.Card;
+      } else {
+        const createParams: any = {
+          metadata: props.metadata,
+        };
+
+        if (props.source) {
+          createParams.source = props.source;
+        } else if (props.number) {
+          createParams.source = {
+            object: "card",
+            number: props.number,
+            exp_month: props.expMonth,
+            exp_year: props.expYear,
+            cvc: props.cvc,
+            name: props.name,
+            address_city: props.addressCity,
+            address_country: props.addressCountry,
+            address_line1: props.addressLine1,
+            address_line2: props.addressLine2,
+            address_state: props.addressState,
+            address_zip: props.addressZip,
+            currency: props.currency,
+            default_for_currency: props.defaultForCurrency,
+          };
+        }
+
+        try {
+          card = (await stripe.customers.createSource(
+            props.customer,
+            createParams,
+          )) as Stripe.Card;
+        } catch (error) {
+          if (isStripeConflictError(error) && props.adopt) {
+            throw new Error(
+              "Card adoption is not supported - cards cannot be uniquely identified for adoption",
+            );
+          } else {
+            throw error;
+          }
+        }
+      }
+
+      return this({
+        id: card.id,
+        object: card.object,
+        customer: props.customer,
+        brand: card.brand,
+        country: card.country || undefined,
+        dynamicLast4: card.dynamic_last4 || undefined,
+        expMonth: card.exp_month,
+        expYear: card.exp_year,
+        fingerprint: card.fingerprint || undefined,
+        funding: card.funding,
+        last4: card.last4,
+        name: card.name || undefined,
+        addressCity: card.address_city || undefined,
+        addressCountry: card.address_country || undefined,
+        addressLine1: card.address_line1 || undefined,
+        addressLine2: card.address_line2 || undefined,
+        addressState: card.address_state || undefined,
+        addressZip: card.address_zip || undefined,
+        currency: card.currency || undefined,
+        defaultForCurrency: card.default_for_currency || undefined,
+        metadata: card.metadata || undefined,
+        tokenizationMethod: card.tokenization_method || undefined,
+      });
+    } catch (error) {
+      console.error("Error creating/updating card:", error);
+      throw error;
+    }
+  },
+);

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