alchemy 0.3.0 → 0.4.0

package/lib/cloudflare/api.d.ts

@@ -1,3 +1,4 @@
+import type { Secret } from "../secret";
 /**
  * Options for Cloudflare API requests
  */
@@ -5,7 +6,7 @@ export interface CloudflareApiOptions {
     /**
      * API Key to use (overrides CLOUDFLARE_API_KEY env var)
      */
-    apiKey?: string;
+    apiKey?: Secret;
     /**
      * Account ID to use (overrides CLOUDFLARE_ACCOUNT_ID env var)
      * If not provided, will be automatically retrieved from the Cloudflare API
@@ -21,6 +22,38 @@ export interface CloudflareApiOptions {
      */
     email?: string;
 }
+/**
+ * Custom error class for Cloudflare API errors
+ * Includes HTTP status information from the Response
+ */
+export declare class CloudflareApiError extends Error {
+    /**
+     * HTTP status code
+     */
+    status: number;
+    /**
+     * HTTP status text
+     */
+    statusText: string;
+    /**
+     * Raw error data from the API
+     */
+    errorData?: any;
+    /**
+     * Create a new CloudflareApiError
+     */
+    constructor(message: string, response: Response, errorData?: any);
+}
+/**
+ * Helper function to handle API errors
+ *
+ * @param response The fetch Response object
+ * @param action The action being performed (e.g., "creating", "deleting")
+ * @param resourceType The type of resource being acted upon (e.g., "R2 bucket", "Worker")
+ * @param resourceName The name/identifier of the specific resource
+ * @returns Never returns - always throws an error
+ */
+export declare function handleApiError(response: Response, action: string, resourceType: string, resourceName: string): Promise<never>;
 /**
  * Creates a CloudflareApi instance with automatic account ID discovery if not provided
  *
@@ -28,6 +61,10 @@ export interface CloudflareApiOptions {
  * @returns Promise resolving to a CloudflareApi instance
  */
 export declare function createCloudflareApi(options?: CloudflareApiOptions): Promise<CloudflareApi>;
+export type CloudflareAccountId = string & {
+    readonly __brand: "CloudflareAccountId";
+};
+export declare function CloudflareAccountId(options?: CloudflareApiOptions): Promise<CloudflareAccountId>;
 /**
  * Cloudflare API client using raw fetch
  */

package/lib/cloudflare/api.js

@@ -1,4 +1,50 @@
 import { getCloudflareHeaders } from "./auth";
+/**
+ * Custom error class for Cloudflare API errors
+ * Includes HTTP status information from the Response
+ */
+export class CloudflareApiError extends Error {
+    /**
+     * HTTP status code
+     */
+    status;
+    /**
+     * HTTP status text
+     */
+    statusText;
+    /**
+     * Raw error data from the API
+     */
+    errorData;
+    /**
+     * Create a new CloudflareApiError
+     */
+    constructor(message, response, errorData) {
+        super(message);
+        this.name = "CloudflareApiError";
+        this.status = response.status;
+        this.statusText = response.statusText;
+        this.errorData = errorData;
+        // Ensure instanceof works correctly
+        Object.setPrototypeOf(this, CloudflareApiError.prototype);
+    }
+}
+/**
+ * Helper function to handle API errors
+ *
+ * @param response The fetch Response object
+ * @param action The action being performed (e.g., "creating", "deleting")
+ * @param resourceType The type of resource being acted upon (e.g., "R2 bucket", "Worker")
+ * @param resourceName The name/identifier of the specific resource
+ * @returns Never returns - always throws an error
+ */
+export async function handleApiError(response, action, resourceType, resourceName) {
+    const json = await response.json();
+    console.log(json);
+    const errorData = json.errors || [{ message: response.statusText }];
+    const errorMessage = `Error ${action} ${resourceType} '${resourceName}': ${errorData.errors?.[0]?.message || response.statusText}`;
+    throw new CloudflareApiError(errorMessage, response, errorData);
+}
 /**
  * Creates a CloudflareApi instance with automatic account ID discovery if not provided
  *
@@ -9,9 +55,7 @@ export async function createCloudflareApi(options = {}) {
     try {
         return new CloudflareApi({
             ...options,
-            accountId: options.accountId ||
-                process.env.CLOUDFLARE_ACCOUNT_ID ||
-                (await fetchAccountId()),
+            accountId: await CloudflareAccountId(options),
         });
     }
     catch (error) {
@@ -19,6 +63,11 @@ export async function createCloudflareApi(options = {}) {
         throw new Error("Failed to automatically discover Cloudflare account ID. Please provide an account ID explicitly or ensure your API token/key has sufficient permissions.");
     }
 }
+export async function CloudflareAccountId(options = {}) {
+    return (options.accountId ||
+        process.env.CLOUDFLARE_ACCOUNT_ID ||
+        (await fetchAccountId()));
+}
 /**
  * Cloudflare API client using raw fetch
  */
@@ -44,7 +93,9 @@ export class CloudflareApi {
      */
     constructor(options = {}) {
         this.baseUrl = "https://api.cloudflare.com/client/v4";
-        const apiKey = options.apiKey || process.env.CLOUDFLARE_API_KEY || undefined;
+        const apiKey = options.apiKey?.unencrypted ||
+            process.env.CLOUDFLARE_API_KEY ||
+            undefined;
         if (!apiKey) {
             throw new Error("No API key provided. Use createCloudflareApi() instead for automatic account discovery.");
         }

package/lib/cloudflare/bucket.d.ts

@@ -1,9 +1,11 @@
+import { AwsClient } from "aws4fetch";
 import type { Context } from "../context";
 import { Resource } from "../resource";
+import { CloudflareApi, type CloudflareApiOptions } from "./api";
 /**
  * Properties for creating or updating an R2 Bucket
  */
-export interface BucketProps {
+export interface BucketProps extends CloudflareApiOptions {
     /**
      * Name of the bucket
      * Names can only contain lowercase letters (a-z), numbers (0-9), and hyphens (-)
@@ -25,6 +27,12 @@ export interface BucketProps {
      * Only for development purposes - use custom domains for production
      */
     allowPublicAccess?: boolean;
+    /**
+     * Whether to delete the bucket and its contents during resource deletion
+     * If set to false, the bucket will remain but the resource will be removed from state
+     * Default: true
+     */
+    delete?: boolean;
 }
 /**
  * Output returned after R2 Bucket creation/update
@@ -39,9 +47,9 @@ export interface R2Bucket extends Resource<"cloudflare::R2Bucket">, BucketProps
      */
     location: string;
     /**
-     * Time at which the bucket was created (Unix timestamp in seconds)
+     * Time at which the bucket was created
      */
-    creationDate: number;
+    creationDate: Date;
 }
 /**
  * Creates and manages Cloudflare R2 Buckets for object storage.
@@ -80,3 +88,110 @@ export interface R2Bucket extends Resource<"cloudflare::R2Bucket">, BucketProps
  * @see https://developers.cloudflare.com/r2/buckets/
  */
 export declare const R2Bucket: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<R2Bucket>, id: string, props: BucketProps) => Promise<R2Bucket>);
+/**
+ * Configuration for R2 client to connect to Cloudflare R2
+ */
+export interface R2ClientConfig {
+    accountId?: string;
+    accessKeyId?: string;
+    secretAccessKey?: string;
+    jurisdiction?: string;
+}
+type R2Client = AwsClient & {
+    accountId: string;
+};
+/**
+ * Creates an aws4fetch client configured for Cloudflare R2
+ *
+ * @see https://developers.cloudflare.com/r2/examples/aws/aws-sdk-js-v3/
+ */
+export declare function createR2Client(config?: R2ClientConfig): Promise<R2Client>;
+interface CloudflareBucketResponse {
+    result: {
+        name: string;
+        location?: string;
+        creation_date: string;
+    };
+    success: boolean;
+    errors: Array<{
+        code: number;
+        message: string;
+    }>;
+    messages: string[];
+}
+/**
+ * Adds jurisdiction header to the headers object if specified in props
+ *
+ * @param headers Headers object to modify
+ * @param props Props or jurisdiction string
+ * @returns Modified headers object
+ */
+export declare function withJurisdiction(headers: Record<string, string> | undefined, props: BucketProps | {
+    jurisdiction?: string;
+} | string | undefined): Record<string, string>;
+/**
+ * Create a new bucket
+ */
+export declare function createBucket(api: CloudflareApi, bucketName: string, props: BucketProps): Promise<CloudflareBucketResponse>;
+/**
+ * Delete a bucket
+ */
+export declare function deleteBucket(api: CloudflareApi, bucketName: string, props: BucketProps): Promise<void>;
+/**
+ * List objects in an R2 bucket
+ *
+ * @param r2 R2Client instance
+ * @param bucketName Name of the bucket
+ * @param continuationToken Optional token for pagination
+ * @param jurisdiction Optional jurisdiction for the bucket
+ * @returns Object containing the list of objects and the next continuation token
+ */
+export declare function listObjects(r2: R2Client, bucketName: string, continuationToken?: string, jurisdiction?: string): Promise<{
+    objects: {
+        Key: string;
+    }[];
+    continuationToken?: string;
+}>;
+/**
+ * Helper function to empty a bucket by deleting all objects
+ */
+export declare function emptyBucket(r2: R2Client, bucketName: string, jurisdiction?: string): Promise<void>;
+/**
+ * Update public access setting for a bucket
+ *
+ * This operation is not available through the S3 API for R2,
+ * so we still use the Cloudflare API directly.
+ */
+export declare function updatePublicAccess(api: CloudflareApi, bucketName: string, allowPublicAccess: boolean, jurisdiction?: string): Promise<void>;
+/**
+ * Set CORS configuration for a bucket using aws4fetch
+ */
+export declare function setCorsConfiguration(r2: R2Client, bucketName: string, allowedOrigins?: string[], allowedMethods?: string[], allowedHeaders?: string[], maxAgeSeconds?: number, jurisdiction?: string): Promise<void>;
+/**
+ * Information about an R2 bucket returned by list operations
+ */
+export interface R2BucketInfo {
+    /**
+     * Name of the bucket
+     */
+    Name: string;
+    /**
+     * Creation date of the bucket
+     */
+    CreationDate: Date;
+}
+/**
+ * List all R2 buckets in an account
+ *
+ * @param api CloudflareApi instance
+ * @param options Optional listing options
+ * @returns Array of bucket information
+ */
+export declare function listBuckets(api: CloudflareApi, options?: {
+    nameContains?: string;
+    perPage?: number;
+    cursor?: string;
+    direction?: "asc" | "desc";
+    jurisdiction?: string;
+}): Promise<R2BucketInfo[]>;
+export {};