alchemy 0.3.1 → 0.4.0

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.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", {
@@ -122,9 +135,6 @@ export const StaticSite = Resource("cloudflare::StaticSite", {
         }),
         generateAssetManifest(props.dir),
     ]);
-    console.log({
-        assetManifest,
-    });
     // Step 3: Upload assets to KV
     await uploadAssetManifest(api, kv.namespaceId, assetManifest);
     // Prepare the bindings for the worker
@@ -196,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/{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/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>;
     }
 }
 /**

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
  *

package/lib/internal/{providers.d.ts → docs/providers.d.ts}

@@ -1,5 +1,5 @@
-import { Document } from "../ai";
-import { Folder } from "../fs";
+import { Document } from "../../ai";
+import { Folder } from "../../fs";
 export interface DocsProps {
     /**
      * The output directory for the docs.
@@ -18,10 +18,16 @@ export interface DocsProps {
      * @default true (all docs)
      */
     filter?: boolean | number;
+    /**
+     * Whether to run in parallel.
+     *
+     * @default true
+     */
+    parallel?: boolean;
 }
-export type AlchemyProviderDocs = {
+export type Providers = {
     dir: string;
     provider: string;
     documents: Document[];
 }[];
-export declare function AlchemyProviderDocs({ srcDir, outDir, filter, }: DocsProps): Promise<AlchemyProviderDocs>;
+export declare function Providers({ srcDir, outDir, filter, parallel, }: DocsProps): Promise<Providers>;

package/lib/internal/docs/providers.js

@@ -0,0 +1,196 @@
+import { type } from "arktype";
+import fs from "fs/promises";
+import path from "path";
+import { Data, Document } from "../../ai";
+import { alchemy } from "../../alchemy";
+import { Folder } from "../../fs";
+export async function Providers({ srcDir, outDir, filter, parallel = true, }) {
+    outDir = typeof outDir === "string" ? outDir : outDir.path;
+    const exclude = [
+        "util",
+        "test",
+        "vitepress",
+        "vite",
+        "shadcn",
+        "internal",
+        "web",
+    ];
+    // Get all folders in the alchemy/src directory
+    let providers = (await fs.readdir(srcDir, {
+        withFileTypes: true,
+    }))
+        .filter((dirent) => dirent.isDirectory() && !exclude.includes(dirent.name))
+        .map((dirent) => path.join(dirent.parentPath, dirent.name));
+    // For each provider, list all files
+    if (filter === false) {
+        return [];
+    }
+    else if (typeof filter === "number") {
+        providers = providers.slice(0, filter);
+    }
+    if (parallel) {
+        return await Promise.all(providers.map((provider) => generateProviderDocs({ provider, outDir, parallel })));
+    }
+    else {
+        const generatedProviders = [];
+        for (const provider of providers) {
+            generatedProviders.push(await generateProviderDocs({ provider, outDir, parallel }));
+        }
+        return generatedProviders;
+    }
+}
+async function generateProviderDocs({ provider, outDir, parallel, }) {
+    const providerName = path.basename(provider);
+    const files = (await fs.readdir(path.resolve(provider), {
+        withFileTypes: true,
+    }))
+        .filter((dirent) => dirent.isFile())
+        .map((dirent) => path.relative(process.cwd(), path.resolve(provider, dirent.name)))
+        .filter((file) => file.endsWith(".ts") && !file.endsWith("index.ts"));
+    const { object: { groups }, } = await Data(`docs/${providerName}`, {
+        model: {
+            id: "o3-mini",
+            provider: "openai",
+            options: {
+                reasoningEffort: "high",
+            },
+        },
+        temperature: 0.1,
+        schema: type({
+            groups: type({
+                identifier: type("string").describe("The identifier of the file's primary exported Resource/Function/Type, e.g. Bucket or StaticSite, AstroFile, TypeScriptFile"),
+                filename: type("string").describe("The filename of the Resource's Document, e.g. bucket.md or static-site.md"),
+                category: type("'Resource'|'Client'|'Utility'|'Types'").describe("The classification of the Resource's Document, one of: Resource, Client, Utility, or Types."),
+            }).array(),
+        }),
+        system: await alchemy `
+      You are a technical writer tasked with identifying the distinct documents that need to be written for a document group (folder) in a documentation site.
+      You will be provided with a list of documents and instructions on how to classify them.
+      Each document has a title, file name, and category.
+    `,
+        prompt: await alchemy `
+      Identify and classify the documents that need to be written for the '${provider}' Service's Alchemy Resources.
+      For background knowledge on Alchemy, see ${alchemy.file("./README.md")}.
+      For background knowledge on the structure of an Alchemy Resource, see ${alchemy.file("./.cursorrules")}.
+
+      The ${provider} Service has the following resources:
+      ${alchemy.files(files)}
+
+      A file is considered a "Resource" if it contains a const <ResourceName> = Resource(...) call or if it is a function that calls a Resource function, e.g. const TypeScriptFile = () => File(...).
+      A file is considered a "Client" if it exposes a wrapper around creating a SDK client or fetch.
+      A file is considered a "Utility" if it contains utility functions that are not resources or clients.
+      A file is considered a "Types" if it contains just type definitions and maybe helpers around working with those types.
+
+      The title should be simply the name of the resource's const in code (with spaces added in between each word), e.g. "Bucket" or "Function", except with spaces, e.g. "Static Site" for "const StaticSite". Maintain all other casing.
+
+      // "Resource Name"
+      const ResourceName = Resource(...)
+    `,
+    });
+    const providerDocsDir = (await Folder(path.join(outDir, providerName))).path;
+    let documents = [];
+    if (parallel) {
+        documents = await Promise.all(groups.filter((g) => g.category === "Resource").map(generateDocument));
+    }
+    else {
+        for (const g of groups.filter((g) => g.category === "Resource")) {
+            documents.push(await generateDocument(g));
+        }
+    }
+    async function generateDocument(g) {
+        return Document(`docs/${providerName}/${g.identifier}`, {
+            title: g.identifier,
+            path: path.join(providerDocsDir, `${g.filename.replace(".ts", "").replace(".md", "")}.md`),
+            freeze: true,
+            model: {
+                id: "claude-3-5-sonnet-latest",
+                provider: "anthropic",
+                // options: {
+                //   reasoningEffort: "high",
+                // },
+            },
+            prompt: await alchemy `
+        You are a technical writer writing API documentation for an Alchemy IaC Resource.
+        See ${alchemy.file("./README.md")} to understand the overview of Alchemy.
+        See ${alchemy.file("./.cursorrules")} to better understand the structure and convention of an Alchemy Resource.
+
+        Relevant files for the ${providerName} Service:
+        ${alchemy.files(files)}
+        
+        Write concise documentation for the "${g.identifier}" Resource.
+
+        > [!CAUTION]
+        > Avoid the temptation to over explain or over describe. Focus on concise, simple, high value snippets. One heading and 0-1 descriptions per snippet.
+        
+        > [!TIP]
+        > Make sure the examples follow a natural progression from the minimal example to logical next steps of how the Resource might be used.
+
+        Each document must follow the following format:
+        
+        # ${g.identifier}
+
+        (simple description with an external link to the provider's website)
+        e.g.
+        The Efs component lets you add [Amazon Elastic File System (EFS)](https://docs.aws.amazon.com/efs/latest/ug/whatisefs.html) to your app.
+
+        # Minimal Example
+
+        (brief 1-2 sentences of what it does)
+
+        \`\`\`ts
+        import { ${g.identifier.replaceAll(" ", "")} } from "alchemy/${providerName}";
+
+        (example)
+        \`\`\`
+
+        # (one heading per variation)
+
+        (brief 1-2 sentences of what it does)
+
+        \`\`\`ts
+        import { ${g.identifier.replaceAll(" ", "")} } from "alchemy/${providerName}";
+
+        (example)
+        \`\`\`
+
+        Before writing the document, think through:
+        1. What is the minimal, most common example use case for this resource?
+        2. What are the variations (e.g. combination of different options) that are also commonly used, e.g. specifying the memory size of a lambda function.
+        3. Make sure to draw from the examples and your understanding of Alchemy.
+
+        Refer to alchemy docs to understand the context of how this documentation is consumed:
+        - ${alchemy.file("./alchemy-web/docs/what-is-alchemy.md")}
+        - ${alchemy.file("./alchemy-web/docs/getting-started.md")}
+        - ${alchemy.folder("./alchemy-web/docs/concepts/")}
+        
+        ${providerName === "cloudflare"
+                ? await alchemy `# Bind to a Worker
+        (if it is a Cloudflare Resource)
+
+        (brief 1-2 sentences of what it does)
+
+        \`\`\`ts
+        import { Worker, ${g.identifier.replaceAll(" ", "")} } from "alchemy/${providerName}";
+
+        const myResource = await ${g.identifier.replaceAll(" ", "")}("my-resource", {
+          // ...
+        });
+
+        await Worker("my-worker", {
+          name: "my-worker",
+          script: "console.log('Hello, world!')",
+          bindings: {
+            myResource,
+          },
+        });
+        \`\`\``
+                : ""}
+      `,
+        });
+    }
+    return {
+        dir: providerDocsDir,
+        provider: providerName,
+        documents,
+    };
+}

package/lib/secret.d.ts

@@ -72,3 +72,6 @@ export declare function isSecret(binding: any): binding is Secret;
  * @throws {Error} If no password is set in the alchemy application options or current scope
  */
 export declare function secret<S extends string | undefined>(unencrypted: S): Secret;
+export declare namespace secret {
+    function env(name: string, value?: string, error?: string): Promise<Secret>;
+}

package/lib/secret.js

@@ -82,3 +82,16 @@ export function secret(unencrypted) {
     }
     return new Secret(unencrypted);
 }
+(function (secret) {
+    async function env(name, value, error) {
+        const alchemy = await import("./alchemy");
+        const result = await alchemy.env(name, value, error);
+        if (typeof result === "string") {
+            return secret(result);
+        }
+        else {
+            throw new Error(`Secret environment variable ${name} is not a string`);
+        }
+    }
+    secret.env = env;
+})(secret || (secret = {}));

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

@@ -1,4 +1,4 @@
-import { Scope } from "../scope";
+import { Scope } from "./scope";
 export declare function serialize(scope: Scope, value: any, options?: {
     encrypt?: boolean;
 }): Promise<any>;

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

@@ -1,6 +1,6 @@
-import { Scope } from "../scope";
-import { Secret } from "../secret";
-import { decryptWithKey, encryptWithKey } from "./encrypt";
+import { decryptWithKey, encrypt } from "./encrypt";
+import { Scope } from "./scope";
+import { Secret } from "./secret";
 // zero-dependency type guard for ArkType
 function isType(value) {
     return (value &&
@@ -17,7 +17,7 @@ export async function serialize(scope, value, options) {
         }
         return {
             "@secret": options?.encrypt !== false
-                ? await encryptWithKey(value.unencrypted, scope.password)
+                ? await encrypt(value.unencrypted, scope.password)
                 : value.unencrypted,
         };
     }
@@ -26,6 +26,11 @@ export async function serialize(scope, value, options) {
             "@schema": value.toJSON(),
         };
     }
+    else if (value instanceof Date) {
+        return {
+            "@date": value.toISOString(),
+        };
+    }
     else if (value instanceof Scope) {
         return undefined;
     }
@@ -51,6 +56,9 @@ export async function deserialize(scope, value) {
         else if ("@schema" in value) {
             return value["@schema"];
         }
+        else if ("@date" in value) {
+            return new Date(value["@date"]);
+        }
         else {
             return Object.fromEntries(await Promise.all(Object.entries(value).map(async ([key, value]) => [
                 key,