alchemy 0.3.1 → 0.4.1

package/lib/cloudflare/account-api-token.js

@@ -0,0 +1,179 @@
+import { alchemy } from "../alchemy";
+import { Resource } from "../resource";
+import { Secret } from "../secret";
+import { sha256 } from "../util/sha256";
+import { createCloudflareApi } from "./api";
+/**
+ * Creates a Cloudflare Account API Token with specified permissions.
+ *
+ * @see https://developers.cloudflare.com/api/resources/accounts/subresources/tokens/methods/create/
+ *
+ * @example
+ * // First, fetch all permission groups
+ * const permissions = await PermissionGroups("cloudflare-permissions", {
+ *   accountId: cfAccountId,
+ * });
+ *
+ * // Create a token with read-only permissions for specific zones
+ * const readOnlyToken = await AccountApiToken("readonly-token", {
+ *   name: "Readonly Zone Token",
+ *   policies: [
+ *     {
+ *       effect: "allow",
+ *       permissionGroups: [
+ *         { id: permissions["Zone Read"].id },
+ *         { id: permissions["Analytics Read"].id }
+ *       ],
+ *       resources: {
+ *         "com.cloudflare.api.account.zone.22b1de5f1c0e4b3ea97bb1e963b06a43": "*",
+ *         "com.cloudflare.api.account.zone.eb78d65290b24279ba6f44721b3ea3c4": "*"
+ *       }
+ *     }
+ *   ],
+ *   expiresOn: "2024-12-31T23:59:59Z"
+ * });
+ *
+ * @example
+ * // Create a token with time and IP restrictions
+ * const restrictedToken = await AccountApiToken("restricted-token", {
+ *   name: "Restricted Access Token",
+ *   policies: [
+ *     {
+ *       effect: "allow",
+ *       permissionGroups: [
+ *         { id: permissions["Worker Routes Edit"].id }
+ *       ],
+ *       resources: {
+ *         "com.cloudflare.api.account.worker.route.*": "*"
+ *       }
+ *     }
+ *   ],
+ *   notBefore: "2023-01-01T00:00:00Z",
+ *   expiresOn: "2023-12-31T23:59:59Z",
+ *   condition: {
+ *     requestIp: {
+ *       in: ["192.168.1.0/24", "10.0.0.0/8"],
+ *       notIn: ["192.168.1.100/32"]
+ *     }
+ *   }
+ * });
+ */
+export const AccountApiToken = Resource("cloudflare::AccountApiToken", async function (id, props) {
+    // Create Cloudflare API client with automatic account discovery
+    const api = await createCloudflareApi();
+    if (this.phase === "delete") {
+        // Delete token if we have an ID
+        if (this.output?.id) {
+            try {
+                const deleteResponse = await api.delete(`/accounts/${api.accountId}/tokens/${this.output.id}`);
+                if (!deleteResponse.ok && deleteResponse.status !== 404) {
+                    const errorData = await deleteResponse.json().catch(() => ({
+                        errors: [{ message: deleteResponse.statusText }],
+                    }));
+                    console.error(`Error deleting token '${props.name}':`, errorData);
+                }
+            }
+            catch (error) {
+                console.error(`Error deleting token '${props.name}':`, error);
+            }
+        }
+        // Return destroyed state
+        return this.destroy();
+    }
+    // Transform our properties to API format
+    const apiPayload = {
+        name: props.name,
+        policies: props.policies.map((policy) => ({
+            effect: policy.effect,
+            permission_groups: policy.permissionGroups.map((pg) => ({
+                id: pg.id,
+                meta: pg.meta || {},
+            })),
+            resources: policy.resources,
+        })),
+        // Format dates for Cloudflare API (removing milliseconds)
+        ...(props.expiresOn
+            ? { expires_on: formatCloudflareDate(props.expiresOn) }
+            : {}),
+        ...(props.notBefore
+            ? { not_before: formatCloudflareDate(props.notBefore) }
+            : {}),
+        ...(props.condition
+            ? {
+                condition: {
+                    request_ip: props.condition.requestIp
+                        ? {
+                            in: props.condition.requestIp.in || [],
+                            not_in: props.condition.requestIp.notIn || [],
+                        }
+                        : undefined,
+                },
+            }
+            : {}),
+    };
+    /**
+     * Formats a date string for Cloudflare API by removing milliseconds
+     * Converts from "2023-01-01T00:00:00.000Z" to "2023-01-01T00:00:00Z"
+     */
+    function formatCloudflareDate(dateStr) {
+        return dateStr.replace(/\.\d{3}Z$/, "Z");
+    }
+    let response;
+    let tokenValue;
+    if (this.phase === "update" && this.output?.id) {
+        // Update existing token
+        response = await api.put(`/accounts/${api.accountId}/tokens/${this.output.id}`, apiPayload);
+    }
+    else {
+        // Create new token
+        response = await api.post(`/accounts/${api.accountId}/tokens`, apiPayload);
+    }
+    if (!response.ok) {
+        const errorData = await response.json().catch(() => ({
+            errors: [{ message: response.statusText }],
+        }));
+        throw new Error(`Error ${this.phase === "update" ? "updating" : "creating"} token '${props.name}': ${errorData.errors?.[0]?.message || response.statusText}`);
+    }
+    const result = await response.json();
+    const tokenData = result.result;
+    if (tokenData.value) {
+        tokenValue = alchemy.secret(tokenData.value);
+    }
+    else {
+        if (!this.output?.value) {
+            throw new Error(`Token '${props.name}' was created but we have no record of its value. Try deleting and recreating the token.`);
+        }
+        tokenValue = this.output?.value;
+    }
+    // Transform API response to our format
+    return this({
+        id: tokenData.id,
+        name: tokenData.name,
+        status: tokenData.status,
+        policies: tokenData.policies.map((policy) => ({
+            effect: policy.effect,
+            permissionGroups: policy.permission_groups.map((pg) => ({
+                id: pg.id,
+                meta: pg.meta,
+            })),
+            resources: policy.resources,
+        })),
+        ...(tokenData.expires_on ? { expiresOn: tokenData.expires_on } : {}),
+        ...(tokenData.not_before ? { notBefore: tokenData.not_before } : {}),
+        ...(tokenData.condition
+            ? {
+                condition: {
+                    requestIp: tokenData.condition.request_ip
+                        ? {
+                            in: tokenData.condition.request_ip.in || [],
+                            notIn: tokenData.condition.request_ip.not_in || [],
+                        }
+                        : undefined,
+                },
+            }
+            : {}),
+        value: tokenValue,
+        accessKeyId: tokenData.id,
+        secretAccessKey: sha256(tokenValue.unencrypted),
+    });
+});

package/lib/cloudflare/account-id.d.ts

@@ -0,0 +1 @@
+export {};

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/assets.d.ts

@@ -0,0 +1,74 @@
+import type { Context } from "../context";
+import { Resource } from "../resource";
+/**
+ * Properties for creating or updating Assets
+ */
+export interface AssetsProps {
+    /**
+     * Path to a directory containing static assets to be uploaded
+     * These files will be served by Cloudflare's Workers runtime
+     */
+    path: string;
+}
+/**
+ * Output returned after Assets creation/update
+ */
+export interface Assets extends Resource<"cloudflare::Asset">, AssetsProps {
+    /**
+     * The type of binding
+     */
+    type: "assets";
+    /**
+     * The ID of the assets bundle
+     */
+    id: string;
+    /**
+     * Asset files that were found
+     */
+    files: AssetFile[];
+    /**
+     * Time at which the assets were created
+     */
+    createdAt: number;
+    /**
+     * Time at which the assets were last updated
+     */
+    updatedAt: number;
+}
+/**
+ * Represents a single asset file
+ */
+export interface AssetFile {
+    /**
+     * Path relative to the assets directory
+     */
+    path: string;
+    /**
+     * Full filesystem path to the file
+     */
+    filePath: string;
+    /**
+     * Content type of the file
+     */
+    contentType: string;
+}
+/**
+ * Cloudflare Assets represent a collection of static files that can be uploaded and served
+ * by Cloudflare Workers.
+ *
+ * @example
+ * // Create a basic assets bundle from a local directory
+ * const staticAssets = await Assets("static", {
+ *   path: "./src/assets"
+ * });
+ *
+ * // Use these assets with a worker
+ * const worker = await Worker("frontend", {
+ *   name: "frontend-worker",
+ *   entrypoint: "./src/worker.ts",
+ *   bindings: {
+ *     ASSETS: staticAssets
+ *   }
+ * });
+ */
+export declare const Assets: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<Assets>, id: string, props: AssetsProps) => Promise<Assets>);

package/lib/cloudflare/assets.js

@@ -0,0 +1,73 @@
+import * as fs from "fs/promises";
+import * as path from "path";
+import { Resource } from "../resource";
+import { getContentType } from "../util/content-type";
+/**
+ * Cloudflare Assets represent a collection of static files that can be uploaded and served
+ * by Cloudflare Workers.
+ *
+ * @example
+ * // Create a basic assets bundle from a local directory
+ * const staticAssets = await Assets("static", {
+ *   path: "./src/assets"
+ * });
+ *
+ * // Use these assets with a worker
+ * const worker = await Worker("frontend", {
+ *   name: "frontend-worker",
+ *   entrypoint: "./src/worker.ts",
+ *   bindings: {
+ *     ASSETS: staticAssets
+ *   }
+ * });
+ */
+export const Assets = Resource("cloudflare::Asset", async function (id, props) {
+    if (this.phase === "delete") {
+        return this.destroy();
+    }
+    try {
+        // Check if the assets directory exists
+        const stats = await fs.stat(props.path);
+        if (!stats.isDirectory()) {
+            throw new Error(`Assets path ${props.path} is not a directory`);
+        }
+    }
+    catch (error) {
+        throw new Error(`Assets directory ${props.path} does not exist or is not accessible`);
+    }
+    // Recursively get all files in the assets directory
+    const filesList = await getFilesRecursively(props.path);
+    // Create asset file objects
+    const files = filesList.map((filePath) => {
+        const relativePath = path.relative(props.path, filePath);
+        const normalizedPath = relativePath.split(path.sep).join("/"); // Ensure forward slashes for URLs
+        return {
+            path: normalizedPath,
+            filePath,
+            contentType: getContentType(filePath),
+        };
+    });
+    // Get current timestamp
+    const now = Date.now();
+    // Construct the output
+    return this({
+        id,
+        type: "assets",
+        path: props.path,
+        files,
+        createdAt: this.output?.createdAt || now,
+        updatedAt: now,
+    });
+});
+// Helper functions for file operations
+async function getFilesRecursively(dir) {
+    const files = await fs.readdir(dir, { withFileTypes: true });
+    const allFiles = await Promise.all(files.map(async (file) => {
+        const path = `${dir}/${file.name}`;
+        if (file.isDirectory()) {
+            return getFilesRecursively(path);
+        }
+        return path;
+    }));
+    return allFiles.flat();
+}

package/lib/cloudflare/bindings.d.ts

@@ -4,6 +4,7 @@
  * https://developers.cloudflare.com/api/resources/workers/subresources/scripts/methods/update/
  */
 import type { Secret } from "../secret";
+import type { Assets } from "./assets";
 import type { R2Bucket } from "./bucket";
 import type { DurableObjectNamespace } from "./durable-object-namespace";
 import type { KVNamespace } from "./kv-namespace";
@@ -14,8 +15,12 @@ export type Bindings = {
 /**
  * L2 Binding Resources.
  */
-export type Binding = DurableObjectNamespace | KVNamespace | Worker | R2Bucket | Secret | string;
+export type Binding = DurableObjectNamespace | KVNamespace | Worker | R2Bucket | Secret | string | Assets;
 export declare function isDurableObjectNamespace(binding: Binding): binding is DurableObjectNamespace;
+/**
+ * Check if a binding is an Assets resource
+ */
+export declare function isAssets(binding: Binding): binding is Assets;
 /**
  * Union type for all Worker binding types (API spec)
  */

package/lib/cloudflare/bindings.js

@@ -1,3 +1,9 @@
 export function isDurableObjectNamespace(binding) {
     return (typeof binding === "object" && binding.type === "durable_object_namespace");
 }
+/**
+ * Check if a binding is an Assets resource
+ */
+export function isAssets(binding) {
+    return typeof binding === "object" && binding.type === "assets";
+}

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 {};