alchemy 0.3.0 → 0.4.0

package/lib/cloudflare/index.d.ts

@@ -1,8 +1,12 @@
+export * from "./account-api-token";
+export * from "./api";
 export * from "./bindings";
 export * from "./bucket";
-export * from "./dns";
+export * from "./custom-domain";
+export * from "./dns-records";
 export * from "./durable-object-namespace";
 export * from "./kv-namespace";
+export * from "./permission-groups";
 export * from "./r2-rest-state-store";
 export * from "./static-site";
 export * from "./worker";

package/lib/cloudflare/index.js

@@ -1,8 +1,12 @@
+export * from "./account-api-token";
+export * from "./api";
 export * from "./bindings";
 export * from "./bucket";
-export * from "./dns";
+export * from "./custom-domain";
+export * from "./dns-records";
 export * from "./durable-object-namespace";
 export * from "./kv-namespace";
+export * from "./permission-groups";
 export * from "./r2-rest-state-store";
 export * from "./static-site";
 export * from "./worker";

package/lib/cloudflare/permission-groups.d.ts

@@ -0,0 +1,78 @@
+import type { Context } from "../context";
+import { Resource } from "../resource";
+import { type CloudflareApiOptions } from "./api";
+/**
+ * Cloudflare permission group as returned by the API
+ */
+export interface PermissionGroup {
+    /**
+     * Unique identifier for the permission group
+     */
+    id: string;
+    /**
+     * Human-readable name of the permission group
+     */
+    name: string;
+    /**
+     * Scopes included in this permission group
+     */
+    scopes: string[];
+}
+/**
+ * All Cloudflare permission groups mapped by name to ID
+ *
+ * @see https://developers.cloudflare.com/r2/api/tokens/#permissions
+ */
+export type PermissionGroups = Resource<"cloudflare::PermissionGroups"> & {
+    /**
+     * Admin Read & Write - Allows create, list, delete buckets and edit bucket configurations
+     * plus list, write, and read object access
+     */
+    "Workers R2 Storage Write": PermissionGroup;
+    /**
+     * Admin Read only - Allows list buckets and view bucket configuration
+     * plus list and read object access
+     */
+    "Workers R2 Storage Read": PermissionGroup;
+    /**
+     * Object Read & Write - Allows read, write, and list objects in specific buckets
+     */
+    "Workers R2 Storage Bucket Item Write": PermissionGroup;
+    /**
+     * Object Read only - Allows read and list objects in specific buckets
+     */
+    "Workers R2 Storage Bucket Item Read": PermissionGroup;
+    /**
+     * Dynamically discovered permission groups
+     */
+    [name: string]: PermissionGroup;
+};
+/**
+ * Lists all permission groups available for the Cloudflare account
+ * and returns a typed map of permission names to their IDs.
+ *
+ * This is primarily used when creating API tokens for Cloudflare services like R2.
+ *
+ * @example
+ * // Get all permission groups including those for R2
+ * const permissions = await PermissionGroups("cloudflare-permissions");
+ *
+ * // Use with AccountApiToken to create a token with proper permissions
+ * const token = await AccountApiToken("r2-token", {
+ *   name: "R2 Read-Only Token",
+ *   policies: [
+ *     {
+ *       effect: "allow",
+ *       resources: {
+ *         "com.cloudflare.edge.r2.bucket.abc123_default_my-bucket": "*"
+ *       },
+ *       permissionGroups: [
+ *         {
+ *           id: permissions["Workers R2 Storage Bucket Item Read"]
+ *         }
+ *       ]
+ *     }
+ *   ]
+ * });
+ */
+export declare const PermissionGroups: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<PermissionGroups>, id: string, options?: CloudflareApiOptions) => Promise<PermissionGroups>);

package/lib/cloudflare/permission-groups.js

@@ -0,0 +1,48 @@
+import { Resource } from "../resource";
+import { createCloudflareApi } from "./api";
+/**
+ * Lists all permission groups available for the Cloudflare account
+ * and returns a typed map of permission names to their IDs.
+ *
+ * This is primarily used when creating API tokens for Cloudflare services like R2.
+ *
+ * @example
+ * // Get all permission groups including those for R2
+ * const permissions = await PermissionGroups("cloudflare-permissions");
+ *
+ * // Use with AccountApiToken to create a token with proper permissions
+ * const token = await AccountApiToken("r2-token", {
+ *   name: "R2 Read-Only Token",
+ *   policies: [
+ *     {
+ *       effect: "allow",
+ *       resources: {
+ *         "com.cloudflare.edge.r2.bucket.abc123_default_my-bucket": "*"
+ *       },
+ *       permissionGroups: [
+ *         {
+ *           id: permissions["Workers R2 Storage Bucket Item Read"]
+ *         }
+ *       ]
+ *     }
+ *   ]
+ * });
+ */
+export const PermissionGroups = Resource("cloudflare::PermissionGroups", async function (id, options) {
+    // Only create and update phases are supported
+    if (this.phase === "delete") {
+        return this.destroy();
+    }
+    // Initialize API client
+    const api = await createCloudflareApi(options);
+    // Fetch permission groups from Cloudflare API
+    const response = await api.get(`/accounts/${api.accountId}/tokens/permission_groups`);
+    if (!response.ok) {
+        throw new Error(`Failed to fetch permission groups: ${response.statusText}`);
+    }
+    const data = (await response.json());
+    if (!data.success || !data.result) {
+        throw new Error(`API returned error: ${data.errors?.[0]?.message || "Unknown error"}`);
+    }
+    return this(Object.fromEntries(data.result.map((group) => [group.name, group])));
+});

package/lib/cloudflare/r2-rest-state-store.d.ts

@@ -1,4 +1,5 @@
 import type { Scope } from "../scope";
+import type { Secret } from "../secret";
 import type { State, StateStore } from "../state";
 /**
  * Options for CloudflareR2StateStore
@@ -17,7 +18,7 @@ export interface CloudflareR2StateStoreOptions {
     /**
      * API key to use (overrides CLOUDFLARE_API_KEY env var)
      */
-    apiKey?: string;
+    apiKey?: Secret;
     /**
      * Account ID to use (overrides CLOUDFLARE_ACCOUNT_ID env var)
      */

package/lib/cloudflare/r2-rest-state-store.js

@@ -1,5 +1,5 @@
+import { deserialize, serialize } from "../serde";
 import { withExponentialBackoff } from "../util/retry";
-import { deserialize, serialize } from "../util/serde";
 import { createCloudflareApi } from "./api";
 /**
  * State store implementation using Cloudflare R2 API
@@ -198,7 +198,8 @@ export class R2RestStateStore {
         }, 
         // Retry on transient errors
         (error) => error.message?.includes("503") || error.message?.includes("timeout"), 5, // 5 retry attempts
-        1000);
+        1000 // Start with 1 second delay
+        );
     }
     /**
      * Delete a state by key

package/lib/cloudflare/static-site-router.js

@@ -35,34 +35,44 @@ app.notFound(async (ctx) => {
     }
     // Fetch from KV
     {
-        const object = await env.ASSETS.getWithMetadata(filePath);
+        const object = await env.ASSETS.getWithMetadata(filePath, {
+            type: "arrayBuffer",
+        });
         if (object.value) {
             return await respond(200, filePath, object);
         }
     }
     {
         const guess = filePath + (filePath.endsWith("/") ? "" : "/") + "index.html";
-        const object = await env.ASSETS.getWithMetadata(guess);
+        const object = await env.ASSETS.getWithMetadata(guess, {
+            type: "arrayBuffer",
+        });
         if (object.value) {
             return await respond(200, guess, object);
         }
     }
     {
         const guess = filePath + ".html";
-        const object = await env.ASSETS.getWithMetadata(guess);
+        const object = await env.ASSETS.getWithMetadata(guess, {
+            type: "arrayBuffer",
+        });
         if (object.value) {
             return await respond(200, guess, object);
         }
     }
     // Handle error page
     if (env.ERROR_PAGE) {
-        const object = await env.ASSETS.getWithMetadata(env.ERROR_PAGE);
+        const object = await env.ASSETS.getWithMetadata(env.ERROR_PAGE, {
+            type: "arrayBuffer",
+        });
         if (object.value) {
             return await respond(404, env.ERROR_PAGE, object);
         }
     }
     else {
-        const object = await env.ASSETS.getWithMetadata(env.INDEX_PAGE);
+        const object = await env.ASSETS.getWithMetadata(env.INDEX_PAGE, {
+            type: "arrayBuffer",
+        });
         if (object.value) {
             return await respond(200, env.INDEX_PAGE, object);
         }
@@ -92,8 +102,7 @@ app.notFound(async (ctx) => {
             headers.set("content-type", object.metadata.contentType);
             headers.set("cache-control", object.metadata.cacheControl);
         }
-        // TODO: do we need base64 encoded here?
-        // const response = new Response(base64ToArrayBuffer(object.value), {
+        // Create response with the raw data directly
         const response = new Response(object.value, {
             status,
             headers,

package/lib/cloudflare/static-site.d.ts

@@ -72,13 +72,6 @@ export interface StaticSiteProps {
      * @default true
      */
     production?: boolean;
-    /**
-     * Custom domain for the site
-     */
-    domain?: string | {
-        name: string;
-        redirects?: string[];
-    };
     build?: {
         /**
          * Command to run before deploying the site
@@ -137,13 +130,6 @@ export interface StaticSite extends Resource<"cloudflare::StaticSite"> {
      * List of uploaded asset files
      */
     assets: string[];
-    /**
-     * Custom domain for the site
-     */
-    domain?: string | {
-        name: string;
-        redirects?: string[];
-    };
     /**
      * Whether the site is deployed to production
      */
@@ -198,13 +184,26 @@ export interface StaticSite extends Resource<"cloudflare::StaticSite"> {
  * });
  *
  * @example
- * // Create a static site with custom error page and index
- * const customSite = await StaticSite("custom-site", {
+ * // Create a static site with a custom domain using the CustomDomain resource
+ * const site = await StaticSite("custom-site", {
  *   name: "custom-site",
  *   dir: "./www",
  *   errorPage: "404.html",
- *   indexPage: "home.html",
- *   domain: "www.example.com"
+ *   indexPage: "home.html"
+ * });
+ *
+ * // Then configure the custom domain separately
+ * const domain = await CustomDomain("custom-domain", {
+ *   name: "www.example.com",
+ *   zoneId: "abcdef123456789",
+ *   workerName: site.name
+ * });
+ *
+ * @example
+ * // Create a static site with multiple domains (primary + redirects)
+ * const site = await StaticSite("multi-domain-site", {
+ *   name: "multi-domain-site",
+ *   dir: "./public"
  * });
  *
  * @see https://developers.cloudflare.com/workers/platform/sites

package/lib/cloudflare/static-site.js

@@ -50,13 +50,26 @@ const __dirname = import.meta.dirname;
  * });
  *
  * @example
- * // Create a static site with custom error page and index
- * const customSite = await StaticSite("custom-site", {
+ * // Create a static site with a custom domain using the CustomDomain resource
+ * const site = await StaticSite("custom-site", {
  *   name: "custom-site",
  *   dir: "./www",
  *   errorPage: "404.html",
- *   indexPage: "home.html",
- *   domain: "www.example.com"
+ *   indexPage: "home.html"
+ * });
+ *
+ * // Then configure the custom domain separately
+ * const domain = await CustomDomain("custom-domain", {
+ *   name: "www.example.com",
+ *   zoneId: "abcdef123456789",
+ *   workerName: site.name
+ * });
+ *
+ * @example
+ * // Create a static site with multiple domains (primary + redirects)
+ * const site = await StaticSite("multi-domain-site", {
+ *   name: "multi-domain-site",
+ *   dir: "./public"
  * });
  *
  * @see https://developers.cloudflare.com/workers/platform/sites
@@ -64,6 +77,8 @@ const __dirname = import.meta.dirname;
 export const StaticSite = Resource("cloudflare::StaticSite", {
     alwaysUpdate: true,
 }, async function (id, props) {
+    // Create Cloudflare API client with automatic account discovery
+    const api = await createCloudflareApi();
     if (this.phase === "delete") {
         // For delete operations, we'll rely on the Worker delete to clean up
         // Return empty output for deleted state
@@ -113,8 +128,6 @@ export const StaticSite = Resource("cloudflare::StaticSite", {
     // Use the provided name
     const siteName = props.name;
     const indexPage = props.indexPage || "index.html";
-    // Create Cloudflare API client with automatic account discovery
-    const api = await createCloudflareApi();
     // Step 1: Create or get the KV namespace for assets
     const [kv, assetManifest] = await Promise.all([
         KVNamespace("assets", {
@@ -193,7 +206,6 @@ export const StaticSite = Resource("cloudflare::StaticSite", {
         assets: assetManifest.map((item) => item.key),
         createdAt: this.output?.createdAt || now,
         updatedAt: now,
-        domain: props.domain,
         production: props.production !== false,
         url: worker.url,
         routes,

package/lib/cloudflare/upload-asset-manifest.js

@@ -34,8 +34,10 @@ export async function uploadAssetManifest(api, namespaceId, manifest) {
         // Create FormData for multipart upload
         const formData = new FormData();
         formData.append("metadata", JSON.stringify(metadata));
-        // Add file content as 'value'
-        const blob = new Blob([content]);
+        // Add file content as 'value' - Fix for binary file corruption
+        const blob = new Blob([new Uint8Array(content)], {
+            type: item.contentType,
+        });
         formData.append("value", blob);
         try {
             const response = await api.put(`/accounts/${api.accountId}/storage/kv/namespaces/${namespaceId}/values/${item.key}`, formData);

package/lib/{util/encrypt.d.ts → encrypt.d.ts}

@@ -5,7 +5,7 @@
  * @param key - The encryption key
  * @returns The base64-encoded encrypted value with nonce
  */
-export declare function encryptWithKey(value: string, key: string): Promise<string>;
+export declare function encrypt(value: string, key: string): Promise<string>;
 /**
  * Decrypt a value encrypted with a symmetric key
  *

package/lib/{util/encrypt.js → encrypt.js}

@@ -6,7 +6,7 @@ import sodium from "libsodium-wrappers";
  * @param key - The encryption key
  * @returns The base64-encoded encrypted value with nonce
  */
-export async function encryptWithKey(value, key) {
+export async function encrypt(value, key) {
     // Initialize libsodium
     await sodium.ready;
     // Derive a key from the passphrase

package/lib/fs/copy-file.d.ts

@@ -0,0 +1,54 @@
+import type { Context } from "../context";
+import { Resource } from "../resource";
+/**
+ * Properties for creating a CopyFile resource
+ */
+export interface CopyFileProps {
+    /**
+     * Source path of the file to copy
+     */
+    src: string;
+    /**
+     * Destination path where the file should be copied to
+     */
+    dest: string;
+    /**
+     * Whether to overwrite the destination file if it already exists
+     * @default true
+     */
+    overwrite?: boolean;
+}
+/**
+ * Output returned after CopyFile creation/update
+ */
+export interface CopyFile extends Resource<"fs::CopyFile">, CopyFileProps {
+    /**
+     * Time at which the object was created
+     */
+    createdAt: number;
+    /**
+     * Whether the file was successfully copied
+     */
+    copied: boolean;
+}
+/**
+ * CopyFile Resource
+ *
+ * Copies a file from a source location to a destination location.
+ *
+ * @example
+ * // Copy a file to a new location
+ * const copiedFile = await CopyFile("config-copy", {
+ *   src: "config.json",
+ *   dest: "backup/config.json"
+ * });
+ *
+ * @example
+ * // Copy a file without overwriting if destination exists
+ * const safeCopy = await CopyFile("safe-copy", {
+ *   src: "data.json",
+ *   dest: "backup/data.json",
+ *   overwrite: false
+ * });
+ */
+export declare const CopyFile: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<CopyFile>, id: string, props: CopyFileProps) => Promise<CopyFile>);

package/lib/fs/copy-file.js

@@ -0,0 +1,63 @@
+import fs from "node:fs";
+import { Resource } from "../resource";
+import { ignore } from "../util/ignore";
+/**
+ * CopyFile Resource
+ *
+ * Copies a file from a source location to a destination location.
+ *
+ * @example
+ * // Copy a file to a new location
+ * const copiedFile = await CopyFile("config-copy", {
+ *   src: "config.json",
+ *   dest: "backup/config.json"
+ * });
+ *
+ * @example
+ * // Copy a file without overwriting if destination exists
+ * const safeCopy = await CopyFile("safe-copy", {
+ *   src: "data.json",
+ *   dest: "backup/data.json",
+ *   overwrite: false
+ * });
+ */
+export const CopyFile = Resource("fs::CopyFile", async function (id, props) {
+    const { src, dest, overwrite = true } = props;
+    if (this.phase === "delete") {
+        // When deleting, remove the destination file
+        await ignore("ENOENT", async () => fs.promises.unlink(dest));
+        return this.destroy();
+    }
+    else {
+        try {
+            // Check if source file exists
+            await fs.promises.access(src, fs.constants.F_OK);
+            // If this is an update and the destination has changed, delete the old file
+            if (this.phase === "update" &&
+                this.output?.dest &&
+                this.output.dest !== dest) {
+                await ignore("ENOENT", async () => fs.promises.unlink(this.output.dest));
+            }
+            // Check if destination file exists
+            const destinationExists = await fs.promises
+                .access(dest, fs.constants.F_OK)
+                .then(() => true)
+                .catch(() => false);
+            // Copy file if destination doesn't exist or overwrite is true
+            if (!destinationExists || overwrite) {
+                await fs.promises.copyFile(src, dest);
+            }
+            return this({
+                src,
+                dest,
+                overwrite,
+                copied: true,
+                createdAt: Date.now(),
+            });
+        }
+        catch (error) {
+            console.error(`Error copying file from ${src} to ${dest}:`, error);
+            throw error;
+        }
+    }
+});

package/lib/fs/file-system-state-store.js

@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { deserialize, serialize } from "../serde";
 import { ignore } from "../util/ignore";
-import { deserialize, serialize } from "../util/serde";
 const stateRootDir = path.join(process.cwd(), ".alchemy");
 export class FileSystemStateStore {
     scope;

package/lib/fs/file.d.ts

@@ -45,6 +45,24 @@ declare module "../alchemy" {
          */
         files(paths: string[]): Promise<FileCollection>;
         files(path: string, ...paths: string[]): Promise<FileCollection>;
+        /**
+         * Gets all of the files in a directory.
+         * @param path Path to the directory
+         * @param props Optional properties
+         * @returns Promise resolving to a FileCollection
+         *
+         * @example
+         * // Get all files in a directory
+         * const files = await alchemy.folder("./docs");
+         *
+         */
+        folder(path: string, props?: {
+            /**
+             * Whether to recursively get all files in the directory
+             * @default false
+             */
+            recursive?: boolean;
+        }): Promise<FileCollection>;
     }
 }
 /**
@@ -79,6 +97,19 @@ export interface File extends Resource<"fs::File"> {
  *   path: "logs/app.log",
  *   content: "application log entry"
  * });
+ *
+ * @example
+ * // Update file content and path
+ * let file = await File("config.json", {
+ *   path: "config.json",
+ *   content: '{ "version": "1.0.0" }'
+ * });
+ *
+ * // Later, update the path and content (old file will be removed)
+ * file = await File("config.json", {
+ *   path: "config/config.json",
+ *   content: '{ "version": "1.0.1" }'
+ * });
  */
 export declare const File: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<File>, id: string, props: {
     path: string;

package/lib/fs/file.js

@@ -17,6 +17,12 @@ alchemy.files = async (...args) => {
         ]))),
     };
 };
+alchemy.folder = async (dir, props) => {
+    const files = await fs.promises.readdir(dir, {
+        recursive: props?.recursive ?? false,
+    });
+    return alchemy.files(files.map((file) => path.join(dir, file)));
+};
 /**
  * File Resource
  *
@@ -36,6 +42,19 @@ alchemy.files = async (...args) => {
  *   path: "logs/app.log",
  *   content: "application log entry"
  * });
+ *
+ * @example
+ * // Update file content and path
+ * let file = await File("config.json", {
+ *   path: "config.json",
+ *   content: '{ "version": "1.0.0" }'
+ * });
+ *
+ * // Later, update the path and content (old file will be removed)
+ * file = await File("config.json", {
+ *   path: "config/config.json",
+ *   content: '{ "version": "1.0.1" }'
+ * });
  */
 export const File = Resource("fs::File", async function (id, props) {
     const filePath = props?.path ?? id;
@@ -43,12 +62,18 @@ export const File = Resource("fs::File", async function (id, props) {
         await ignore("ENOENT", async () => fs.promises.unlink(filePath));
         return this.destroy();
     }
-    else {
-        await fs.promises.mkdir(path.dirname(filePath), {
-            recursive: true,
-        });
-        await fs.promises.writeFile(filePath, props.content);
+    else if (this.phase === "update" &&
+        this.output &&
+        this.output.path !== filePath) {
+        // If path has changed, delete the old file
+        console.log(`File: Path changed from ${this.output.path} to ${filePath}, removing old file`);
+        await ignore("ENOENT", async () => fs.promises.unlink(this.output.path));
     }
+    // Create directory and write file
+    await fs.promises.mkdir(path.dirname(filePath), {
+        recursive: true,
+    });
+    await fs.promises.writeFile(filePath, props.content);
     return this({
         path: filePath,
         content: props.content,

package/lib/fs/index.d.ts

@@ -1,8 +1,14 @@
+export * from "./copy-file";
 export * from "./file";
 export * from "./file-collection";
 export * from "./file-ref";
+export * from "./file-system-state-store";
 export * from "./folder";
+export * from "./static-astro-file";
+export * from "./static-css-file";
+export * from "./static-html-file";
 export * from "./static-json-file";
 export * from "./static-text-file";
 export * from "./static-typescript-file";
+export * from "./static-vue-file";
 export * from "./static-yaml-file";

package/lib/fs/index.js

@@ -1,8 +1,14 @@
+export * from "./copy-file";
 export * from "./file";
 export * from "./file-collection";
 export * from "./file-ref";
+export * from "./file-system-state-store";
 export * from "./folder";
+export * from "./static-astro-file";
+export * from "./static-css-file";
+export * from "./static-html-file";
 export * from "./static-json-file";
 export * from "./static-text-file";
 export * from "./static-typescript-file";
+export * from "./static-vue-file";
 export * from "./static-yaml-file";