alchemy 0.15.10 → 0.15.12

package/src/cloudflare/account-api-token.ts

@@ -3,12 +3,16 @@ import type { Context } from "../context.js";
 import { Resource } from "../resource.js";
 import type { Secret } from "../secret.js";
 import { sha256 } from "../util/sha256.js";
-import { type CloudflareApiOptions, createCloudflareApi } from "./api.js";
+import { createCloudflareApi, type CloudflareApiOptions } from "./api.js";
+import {
+  PermissionGroups,
+  type PermissionGroupName,
+} from "./permission-groups.js";
 
 /**
  * Permission group for a token policy
  */
-export interface TokenPolicyPermissionGroup {
+export type TokenPolicyPermissionGroup = {
   /**
    * ID of the permission group
    */
@@ -18,7 +22,7 @@ export interface TokenPolicyPermissionGroup {
    * Optional metadata for the permission group
    */
   meta?: Record<string, any>;
-}
+};
 
 /**
  * Policy that defines what the token can access
@@ -32,14 +36,27 @@ export interface TokenPolicy {
   /**
    * Permission groups to include in the policy
    */
-  permissionGroups: TokenPolicyPermissionGroup[];
+  permissionGroups: (PermissionGroupName | TokenPolicyPermissionGroup)[];
 
   /**
    * Resources the policy applies to
    */
-  resources: Record<string, string>;
+  resources: {
+    [key in TokenPolicyResourceKey]?: string;
+  };
 }
 
+/**
+ * @see https://developers.cloudflare.com/fundamentals/api/reference/permissions/
+ */
+type TokenPolicyResourceKey =
+  | `com.cloudflare.api.account`
+  | `com.cloudflare.api.account.${string}`
+  // | `com.cloudflare.api.account.zone`
+  | `com.cloudflare.api.account.zone.${string}`
+  // | `com.cloudflare.api.user`
+  | `com.cloudflare.api.user.${string}`;
+
 /**
  * Condition for token usage (e.g., IP restrictions)
  */
@@ -120,8 +137,7 @@ interface CloudflareApiToken {
  * Output returned after Account API Token creation/update
  */
 export interface AccountApiToken
-  extends Resource<"cloudflare::AccountApiToken">,
-    AccountApiTokenProps {
+  extends Resource<"cloudflare::AccountApiToken"> {
   /**
    * The ID of the token
    *
@@ -129,6 +145,11 @@ export interface AccountApiToken
    */
   id: string;
 
+  /**
+   * Name of the token
+   */
+  name: string;
+
   /**
    * Status of the token
    */
@@ -147,7 +168,7 @@ export interface AccountApiToken
    *
    * An alias of {@link id}
    */
-  accessKeyId: string;
+  accessKeyId: Secret;
 
   /**
    * Secret access key for the token
@@ -156,7 +177,7 @@ export interface AccountApiToken
    *
    * @see https://developers.cloudflare.com/r2/api/tokens/#get-s3-api-credentials-from-an-api-token
    */
-  secretAccessKey: string;
+  secretAccessKey: Secret;
 }
 
 /**
@@ -169,21 +190,13 @@ export interface AccountApiToken
  * @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 }
- *       ],
+ *       permissionGroups: ["Zone Read", "Analytics Read"],
  *       resources: {
  *         "com.cloudflare.api.account.zone.22b1de5f1c0e4b3ea97bb1e963b06a43": "*",
  *         "com.cloudflare.api.account.zone.eb78d65290b24279ba6f44721b3ea3c4": "*"
@@ -200,9 +213,7 @@ export interface AccountApiToken
  *   policies: [
  *     {
  *       effect: "allow",
- *       permissionGroups: [
- *         { id: permissions["Worker Routes Edit"].id }
- *       ],
+ *       permissionGroups: ["Worker Routes Edit"],
  *       resources: {
  *         "com.cloudflare.api.account.worker.route.*": "*"
  *       }
@@ -217,6 +228,21 @@ export interface AccountApiToken
  *     }
  *   }
  * });
+ *
+ * @example
+ * // Create a token with bucket access permissions
+ * const storageToken = await AccountApiToken("account-access-token", {
+ *   name: "alchemy-account-access-token",
+ *   policies: [
+ *     {
+ *       effect: "allow",
+ *       permissionGroups: ["Workers R2 Storage Write"],
+ *       resources: {
+ *         "com.cloudflare.api.account": "*",
+ *       },
+ *     },
+ *   ],
+ * });
  */
 export const AccountApiToken = Resource(
   "cloudflare::AccountApiToken",
@@ -251,16 +277,34 @@ export const AccountApiToken = Resource(
       return this.destroy();
     }
 
+    const permissionGroups = await PermissionGroups(
+      "cloudflare-permission-groups",
+      props,
+    );
+
     // 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,
+        permission_groups: policy.permissionGroups.map((pg) =>
+          typeof pg === "string"
+            ? {
+                id: permissionGroups[pg].id,
+              }
+            : {
+                id: pg.id,
+                meta: pg.meta || {},
+              },
+        ),
+        resources: Object.fromEntries(
+          Object.entries(policy.resources).map(([key, value]) => {
+            if (key === "com.cloudflare.api.account") {
+              return [`com.cloudflare.api.account.${api.accountId}`, value];
+            }
+            return [key, value];
+          }),
+        ),
       })),
       // Format dates for Cloudflare API (removing milliseconds)
       ...(props.expiresOn
@@ -339,14 +383,6 @@ export const AccountApiToken = Resource(
       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
@@ -362,8 +398,8 @@ export const AccountApiToken = Resource(
           }
         : {}),
       value: tokenValue,
-      accessKeyId: tokenData.id,
-      secretAccessKey: sha256(tokenValue.unencrypted),
+      accessKeyId: alchemy.secret(tokenData.id),
+      secretAccessKey: alchemy.secret(sha256(tokenValue.unencrypted)),
     });
   },
 );

package/src/cloudflare/d1-clone.ts

@@ -0,0 +1,113 @@
+import type { CloudflareApi } from "./api.js";
+import {
+  exportD1Database,
+  type ExportD1DatabaseOptions,
+  type ExportD1DatabaseResult,
+} from "./d1-export.js";
+import {
+  importD1Database,
+  type ImportD1DatabaseOptions,
+  type ImportD1DatabaseResult,
+} from "./d1-import.js";
+
+/**
+ * Options for cloning a D1 database
+ */
+export interface CloneD1DatabaseOptions {
+  /**
+   * The ID of the source D1 database to clone from
+   */
+  sourceDatabaseId: string;
+
+  /**
+   * The ID of the target D1 database to clone to
+   */
+  targetDatabaseId: string;
+
+  /**
+   * Optional export options for the source database
+   */
+  exportOptions?: Omit<ExportD1DatabaseOptions, "databaseId">;
+
+  /**
+   * Optional import options for the target database
+   */
+  importOptions?: Omit<ImportD1DatabaseOptions, "databaseId" | "sqlData">;
+}
+
+/**
+ * Response from the clone D1 database operation
+ */
+export interface CloneD1DatabaseResult {
+  /**
+   * Result of the export operation
+   */
+  exportResult: ExportD1DatabaseResult;
+
+  /**
+   * Result of the import operation
+   */
+  importResult: ImportD1DatabaseResult;
+
+  /**
+   * Whether the clone operation was successful
+   */
+  success: boolean;
+}
+
+/**
+ * Clones a D1 database by exporting from a source database and importing to a target database.
+ * Handles the full workflow:
+ * 1. Export source database to get a signed URL
+ * 2. Fetch SQL content from the signed URL
+ * 3. Import SQL content into the target database
+ *
+ * @param api The CloudflareApi instance to use for requests
+ * @param options Options including source and target database IDs
+ * @returns An object containing results from both export and import operations
+ * @throws Will throw an error if any part of the clone process fails
+ */
+export async function cloneD1Database(
+  api: CloudflareApi,
+  options: CloneD1DatabaseOptions,
+): Promise<CloneD1DatabaseResult> {
+  const exportResult = await exportD1Database(api, {
+    databaseId: options.sourceDatabaseId,
+    ...options.exportOptions,
+  });
+
+  if (!exportResult.success) {
+    throw new Error(
+      `Failed to export source database: ${options.sourceDatabaseId}`,
+    );
+  }
+
+  // Step 2: Fetch SQL content from the signed URL
+  const sqlResponse = await fetch(exportResult.signed_url);
+
+  if (!sqlResponse.ok) {
+    throw new Error(`Failed to fetch SQL content: ${sqlResponse.statusText}`);
+  }
+
+  const sqlData = await sqlResponse.text();
+
+  // Step 3: Import SQL content into target database
+  const importResult = await importD1Database(api, {
+    databaseId: options.targetDatabaseId,
+    sqlData,
+    filename: exportResult.filename,
+    ...options.importOptions,
+  });
+
+  if (!importResult.success) {
+    throw new Error(
+      `Failed to import to target database: ${options.targetDatabaseId}`,
+    );
+  }
+
+  return {
+    exportResult,
+    importResult,
+    success: true,
+  };
+}

package/src/cloudflare/d1-database.ts

@@ -2,10 +2,11 @@ import type { Context } from "../context.js";
 import { Resource } from "../resource.js";
 import { CloudflareApiError, handleApiError } from "./api-error.js";
 import {
-  type CloudflareApi,
   createCloudflareApi,
+  type CloudflareApi,
   type CloudflareApiOptions,
 } from "./api.js";
+import { cloneD1Database } from "./d1-clone.js";
 import { applyMigrations, listMigrationsFiles } from "./d1-migrations.js";
 
 /**
@@ -61,6 +62,17 @@ export interface D1DatabaseProps extends CloudflareApiOptions {
    */
   adopt?: boolean;
 
+  /**
+   * Clone data from an existing database to this new database.
+   * Only applicable during creation phase.
+   *
+   * Can be specified as:
+   * - A D1Database object
+   * - An object with an id property
+   * - An object with a name property (will look up the ID by name)
+   */
+  clone?: D1Database | { id: string } | { name: string };
+
   /**
    * These files will be generated internally with the D1Database wrapper function when migrationsDir is specified
    *
@@ -123,20 +135,6 @@ export type D1Database = Resource<"cloudflare::D1Database"> &
     };
   };
 
-export async function D1Database(
-  id: string,
-  props: Omit<D1DatabaseProps, "migrationsFiles">,
-) {
-  const migrationsFiles = props.migrationsDir
-    ? await listMigrationsFiles(props.migrationsDir)
-    : [];
-
-  return D1DatabaseResource(id, {
-    ...props,
-    migrationsFiles,
-  });
-}
-
 /**
  * Creates and manages Cloudflare D1 Databases.
  *
@@ -173,8 +171,43 @@ export async function D1Database(
  *   migrationsDir: "./migrations",
  * });
  *
+ * @example
+ * // Clone an existing database by ID
+ * const clonedDb = await D1Database("cloned-db", {
+ *   name: "cloned-db",
+ *   clone: otherDb
+ * });
+ *
+ * @example
+ * // Clone an existing database by ID
+ * const clonedDb = await D1Database("cloned-db", {
+ *   name: "cloned-db",
+ *   clone: { id: "existing-db-uuid" }
+ * });
+ *
+ * @example
+ * // Clone an existing database by name
+ * const clonedDb = await D1Database("cloned-db", {
+ *   name: "cloned-db",
+ *   clone: { name: "existing-db-name" }
+ * });
+ *
  * @see https://developers.cloudflare.com/d1/
  */
+export async function D1Database(
+  id: string,
+  props: Omit<D1DatabaseProps, "migrationsFiles">,
+) {
+  const migrationsFiles = props.migrationsDir
+    ? await listMigrationsFiles(props.migrationsDir)
+    : [];
+
+  return D1DatabaseResource(id, {
+    ...props,
+    migrationsFiles,
+  });
+}
+
 export const D1DatabaseResource = Resource(
   "cloudflare::D1Database",
   async function (
@@ -202,6 +235,11 @@ export const D1DatabaseResource = Resource(
       console.log("Creating D1 database:", databaseName);
       try {
         dbData = await createDatabase(api, databaseName, props);
+
+        // If clone property is provided, perform cloning after database creation
+        if (props.clone && dbData.result.uuid) {
+          await cloneDb(api, props.clone, dbData.result.uuid);
+        }
       } catch (error) {
         // Check if this is a "database already exists" error and adopt is enabled
         if (
@@ -480,3 +518,49 @@ export async function updateDatabase(
 
   return (await updateResponse.json()) as CloudflareD1Response;
 }
+
+/**
+ * Helper function to clone data from a source database to a target database
+ * Resolves the source database ID from different input formats and performs the cloning operation
+ *
+ * @param api CloudflareApi instance
+ * @param sourceDb Source database specification (can be an ID, a name, or a D1Database object)
+ * @param targetDbId Target database ID
+ */
+async function cloneDb(
+  api: CloudflareApi,
+  sourceDb: D1Database | { id: string } | { name: string },
+  targetDbId: string,
+): Promise<void> {
+  let sourceId: string;
+
+  // Determine source database ID
+  if ("id" in sourceDb && sourceDb.id) {
+    // Use provided ID directly
+    sourceId = sourceDb.id;
+  } else if ("name" in sourceDb && sourceDb.name) {
+    // Look up ID by name
+    const databases = await listDatabases(api, sourceDb.name);
+    const foundDb = databases.find((db) => db.name === sourceDb.name);
+
+    if (!foundDb) {
+      throw new Error(
+        `Source database with name '${sourceDb.name}' not found for cloning`,
+      );
+    }
+
+    sourceId = foundDb.id;
+  } else if ("type" in sourceDb && sourceDb.type === "d1" && "id" in sourceDb) {
+    // It's a D1Database object
+    sourceId = sourceDb.id;
+  } else {
+    throw new Error("Invalid clone property: must provide either id or name");
+  }
+
+  // Perform the cloning
+  console.log(`Cloning data from database ${sourceId} to ${targetDbId}`);
+  await cloneD1Database(api, {
+    sourceDatabaseId: sourceId,
+    targetDatabaseId: targetDbId,
+  });
+}

package/src/cloudflare/d1-export.ts

@@ -0,0 +1,173 @@
+import type { CloudflareApi } from "./api.js"; // Ensure CloudflareApi is exported if not already
+
+/**
+ * Options for exporting a D1 database
+ */
+export interface ExportD1DatabaseOptions {
+  /**
+   * The ID of the D1 database to export
+   */
+  databaseId: string;
+
+  /**
+   * Optional dump options to control what is exported
+   */
+  dumpOptions?: {
+    /**
+     * Optional list of tables to export
+     */
+    tables?: string[];
+
+    /**
+     * Whether to exclude schema in the export
+     */
+    no_schema?: boolean;
+
+    /**
+     * Whether to exclude data in the export
+     */
+    no_data?: boolean;
+  };
+}
+
+/**
+ * Response from the export D1 database operation
+ */
+export interface ExportD1DatabaseResult {
+  /**
+   * The filename of the exported database
+   */
+  filename: string;
+
+  /**
+   * The signed URL for downloading the exported database
+   */
+  signed_url: string;
+
+  /**
+   * The status of the export operation
+   */
+  status: "complete";
+
+  /**
+   * Whether the export operation was successful
+   */
+  success: boolean;
+}
+
+/**
+ * Error response from Cloudflare API
+ */
+interface CloudflareErrorResponse {
+  error?: string;
+  errors?: Array<{
+    message: string;
+  }>;
+}
+
+/**
+ * Response during polling for D1 database export
+ */
+interface ExportPollingResponse {
+  /**
+   * Bookmark for continuing the polling process
+   */
+  at_bookmark?: string;
+
+  /**
+   * Error message if any
+   */
+  error?: string;
+
+  /**
+   * Progress messages from the export process
+   */
+  messages: string[];
+
+  /**
+   * Result data if export is complete
+   */
+  result?: {
+    filename: string;
+    signed_url: string;
+  };
+
+  /**
+   * Status of the export process
+   */
+  status: "complete" | "error" | "processing";
+
+  /**
+   * Whether the current polling request was successful
+   */
+  success: boolean;
+
+  /**
+   * Type of operation
+   */
+  type: "export";
+}
+
+/**
+ * Initiates an export of a Cloudflare D1 database and returns a download URL.
+ * Implements recursive polling with bookmark handling, similar to wrangler.
+ * Waits indefinitely until the export process completes or fails.
+ *
+ * Based on Cloudflare API:
+ * https://developers.cloudflare.com/api/resources/d1/subresources/database/methods/export/
+ * and wrangler implementation.
+ *
+ * @param options Options including the database ID and optional dump parameters.
+ * @returns An object containing the download URL, filename, and status upon completion.
+ * @throws Will throw an error if the API call fails or the export process reports an error.
+ */
+export async function exportD1Database(
+  api: CloudflareApi,
+  options: ExportD1DatabaseOptions,
+  currentBookmark?: string,
+): Promise<ExportD1DatabaseResult> {
+  const response = await api.post(
+    `/accounts/${api.accountId}/d1/database/${options.databaseId}/export`,
+    {
+      output_format: "polling",
+      dump_options: options.dumpOptions || {},
+      current_bookmark: currentBookmark,
+    },
+  );
+
+  if (!response.ok) {
+    const errorData = (await response.json()) as CloudflareErrorResponse;
+    throw new Error(
+      `Failed to export D1 database: ${errorData.error || errorData.errors?.[0]?.message || "Unknown error"}`,
+    );
+  }
+
+  const { result: data } = (await response.json()) as {
+    result: ExportPollingResponse;
+  };
+
+  if (!data.success) {
+    throw new Error(data.error || "Unknown error during D1 export");
+  }
+
+  // Log messages for visibility
+  if (data.messages && data.messages.length > 0) {
+    for (const message of data.messages) {
+      console.log(`D1 Export: ${message}`);
+    }
+  }
+
+  if (data.status === "complete" && data.result) {
+    return {
+      filename: data.result.filename,
+      signed_url: data.result.signed_url,
+      status: data.status,
+      success: data.success,
+    };
+  } else if (data.status === "error") {
+    throw new Error(data.error || "Error during D1 export");
+  } else {
+    // Continue polling with bookmark
+    return exportD1Database(api, options, data.at_bookmark);
+  }
+}