alchemy 0.2.3 → 0.2.5

package/lib/github/secret.js

@@ -3,11 +3,71 @@ import { Resource } from "../resource";
 import { createGitHubClient, verifyGitHubAuth } from "./client";
 /**
  * Resource for managing GitHub repository secrets
+ *
+ * Authentication is handled in the following order:
+ * 1. `token` parameter in the resource props (if provided)
+ * 2. `GITHUB_TOKEN` environment variable
+ *
+ * The token must have the following permissions:
+ * - 'repo' scope for private repositories
+ * - 'public_repo' scope for public repositories
+ *
+ * @example
+ * // Create a secret using GITHUB_TOKEN environment variable:
+ * const secret = await GitHubSecret("my-secret", {
+ *   owner: "my-github-username",
+ *   repository: "my-repo",
+ *   name: "API_KEY",
+ *   value: alchemy.secret("my-secret-value")
+ * });
+ *
+ * @example
+ * // Create a secret with a custom GitHub token:
+ * const secret = await GitHubSecret("my-secret", {
+ *   owner: "my-github-username",
+ *   repository: "my-repo",
+ *   name: "API_KEY",
+ *   value: alchemy.secret("my-secret-value"),
+ *   token: alchemy.secret(process.env.CUSTOM_GITHUB_TOKEN)
+ * });
+ *
+ * @example
+ * // Create multiple secrets with environment variables:
+ * const secrets = await Promise.all([
+ *   GitHubSecret("aws-secret", {
+ *     owner: "my-github-username",
+ *     repository: "cloud-app",
+ *     name: "AWS_ROLE_ARN",
+ *     value: alchemy.secret(process.env.AWS_ROLE_ARN)
+ *   }),
+ *   GitHubSecret("cf-secret", {
+ *     owner: "my-github-username",
+ *     repository: "cloud-app",
+ *     name: "CLOUDFLARE_API_KEY",
+ *     value: alchemy.secret(process.env.CLOUDFLARE_API_KEY)
+ *   })
+ * ]);
+ *
+ * @example
+ * // Create a secret in a secure scope with a password:
+ * await alchemy.run("secure-scope", {
+ *   password: process.env.SECRET_PASSPHRASE
+ * }, async () => {
+ *   const secret = await GitHubSecret("deploy-secret", {
+ *     owner: "my-github-username",
+ *     repository: "my-app",
+ *     name: "DEPLOY_TOKEN",
+ *     value: alchemy.secret(process.env.DEPLOY_TOKEN),
+ *     token: alchemy.secret(process.env.GITHUB_TOKEN)
+ *   });
+ * });
  */
 export const GitHubSecret = Resource("github::Secret", async function (id, props) {
     // Create authenticated Octokit client - will automatically handle token resolution
     /// TODO: use fetch
-    const octokit = await createGitHubClient({ token: props.token });
+    const octokit = await createGitHubClient({
+        token: props.token?.unencrypted,
+    });
     // Verify authentication and permissions
     if (!this.quiet) {
         await verifyGitHubAuth(octokit, props.owner, props.repository);

package/lib/internal/docs.d.ts

@@ -0,0 +1,5 @@
+export interface DocsProps {
+    docs?: boolean | number;
+}
+export type AlchemyDocs = Awaited<ReturnType<typeof AlchemyDocs>>;
+export declare function AlchemyDocs({ docs: isDocsEnabled }: DocsProps): Promise<void>;

package/lib/internal/docs.js

@@ -0,0 +1,287 @@
+import { type } from "arktype";
+import fs from "fs/promises";
+import path from "path";
+import { Data } from "../ai/data";
+import { Document } from "../ai/document";
+import { alchemy } from "../alchemy";
+import { Folder } from "../fs/folder";
+import { VitePressProject } from "../vitepress/vitepress";
+export async function AlchemyDocs({ docs: isDocsEnabled }) {
+    const root = (await Folder("alchemy-web")).path;
+    const docs = (await Folder(path.join(root, "docs"))).path;
+    const providersDir = (await Folder(path.join(docs, "providers"))).path;
+    const exclude = ["util", "test", "vitepress", "vite", "shadcn", "internal"];
+    // Get all folders in the alchemy/src directory
+    let providers = (await fs.readdir(path.resolve("alchemy", "src"), {
+        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 (isDocsEnabled === false) {
+        return;
+    }
+    else if (typeof isDocsEnabled === "number") {
+        providers = providers.slice(0, isDocsEnabled);
+    }
+    const providerDocs = await Promise.all(providers.map(async (provider) => {
+        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}`, {
+            schema: type({
+                groups: type({
+                    title: type("string").describe("The title of the group, should be the Resource Name exactly without spaces, e.g. Bucket or Static Site."),
+                    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, e.g. "Bucket" or "Function", except with spaces, e.g. "Static Site" instead of "StaticSite". Maintain all other casing.
+        `,
+        });
+        const providerDocsDir = (await Folder(path.join(providersDir, providerName))).path;
+        const documents = await Promise.all(groups
+            .filter((g) => g.category === "Resource")
+            .map(async (g) => Document(`docs/${providerName}/${g.title}`, {
+            title: g.title,
+            path: path.join(providerDocsDir, `${g.filename.replace(".ts", "").replace(".md", "")}.md`),
+            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.title}" 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.title}
+
+                (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
+
+                \`\`\`ts
+                import { ${g.title.replaceAll(" ", "")} } from "alchemy/${providerName}";
+
+                (example)
+                \`\`\`
+
+
+                # Create the ${g.title}
+
+                \`\`\`ts
+                import { ${g.title.replaceAll(" ", "")} } from "alchemy/${providerName}";
+
+                (example)
+                \`\`\`
+
+                ${providerName === "cloudflare"
+                ? await alchemy `# Bind to a Worker
+                (if it is a Cloudflare Resource)
+
+                \`\`\`ts
+                import { Worker, ${g.title.replaceAll(" ", "")} } from "alchemy/${providerName}";
+
+                const myResource = await ${g.title.replaceAll(" ", "")}("my-resource", {
+                  // ...
+                });
+
+                await Worker("my-worker", {
+                  name: "my-worker",
+                  script: "console.log('Hello, world!')",
+                  bindings: {
+                    myResource,
+                  },
+                });
+                \`\`\``
+                : ""}
+              `,
+        })));
+        return {
+            dir: providerDocsDir,
+            provider: providerName,
+            documents,
+        };
+    }));
+    await VitePressProject("docs", {
+        name: "alchemy-web",
+        title: "Alchemy",
+        description: "Alchemy is an TypeScript-native, embeddable IaC library",
+        overwrite: true,
+        delete: false,
+        tsconfig: {
+            extends: "../tsconfig.base.json",
+            references: ["../alchemy/tsconfig.json"],
+        },
+        devDependencies: {
+            alchemy: "workspace:*",
+        },
+        theme: {
+            light: "light-plus",
+            dark: "dark-plus",
+        },
+        home: {
+            layout: "home",
+            hero: {
+                name: "Alchemy",
+                text: "Materialize all the things! 🪄",
+                tagline: "TypeScript-native Infrastructure-as-Code (IaC)",
+                image: {
+                    src: "./public/alchemist.png",
+                    alt: "The Alchemist",
+                },
+                actions: [
+                    {
+                        text: "Get Started",
+                        link: "/docs",
+                        theme: "brand",
+                    },
+                ],
+            },
+            features: [
+                {
+                    title: "JS-native",
+                    details: "No second language, toolchains, dependencies, processes, services, etc. to lug around.",
+                },
+                {
+                    title: "Async",
+                    details: "Resources are just async functions - no complex abstraction to learn.",
+                },
+                {
+                    title: "ESM",
+                    details: "Built exclusively on ESM, with a slight preference for modern JS runtimes like Bun.",
+                },
+                {
+                    title: "Embeddable",
+                    details: "Runs in any JavaScript/TypeScript environment, including the browser!",
+                },
+                {
+                    title: "Extensible",
+                    details: "Implement your own resources with a simple function.",
+                },
+                {
+                    title: "AI-first",
+                    details: "Create, copy, fork, and modify resources using LLMs to fit your needs.",
+                },
+                {
+                    title: "No dependencies",
+                    details: "The alchemy core package has 0 required dependencies.",
+                },
+                {
+                    title: "No service",
+                    details: "State files are stored locally in your project for easy inspection and version control.",
+                },
+                {
+                    title: "No strong opinions",
+                    details: "Structure your codebase however you want, store state anywhere - we don't care!",
+                },
+            ],
+        },
+        themeConfig: {
+            sidebar: {
+                "/blog/": [{ text: "Blog", items: [{ text: "Blog", link: "/blog/" }] }],
+                "/docs/": [
+                    {
+                        text: "Getting Started",
+                        items: [{ text: "Install", link: "/docs/getting-started/install" }],
+                    },
+                    {
+                        text: "Guides",
+                        items: [
+                            {
+                                text: "Custom Resource",
+                                link: "/docs/guides/custom-resource",
+                            },
+                            {
+                                text: "Automating with LLMs",
+                                link: "/docs/guides/llms",
+                            },
+                        ],
+                    },
+                    {
+                        text: "Core",
+                        collapsed: true,
+                        items: [
+                            { text: "App", link: "/docs/core/app" },
+                            { text: "Resource", link: "/docs/core/resource" },
+                            { text: "Scope", link: "/docs/core/scope" },
+                            { text: "Phase", link: "/docs/core/phase" },
+                            { text: "Finalize", link: "/docs/core/finalize" },
+                            { text: "State", link: "/docs/core/state" },
+                            { text: "Secret", link: "/docs/core/secret" },
+                            { text: "Context", link: "/docs/core/context" },
+                        ],
+                    },
+                    {
+                        text: "Providers",
+                        items: providerDocs
+                            .map((provider) => ({
+                            text: provider.provider,
+                            link: `/docs/providers/${provider.provider}`,
+                            collapsed: true,
+                            items: provider.documents.map((document) => ({
+                                text: document.title,
+                                link: `/docs/providers/${provider.provider}/${path.basename(document.path, ".md")}`,
+                            })),
+                        }))
+                            .sort((a, b) => a.text.localeCompare(b.text)),
+                    },
+                ],
+                "/examples/": [
+                    {
+                        text: "Examples",
+                        items: [{ text: "Foo", link: "/examples/foo" }],
+                    },
+                ],
+                "/": [
+                    {
+                        text: "Home",
+                        items: [
+                            { text: "Markdown Examples", link: "/markdown-examples" },
+                            { text: "Runtime API Examples", link: "/api-examples" },
+                        ],
+                    },
+                ],
+            },
+            socialLinks: [
+                {
+                    icon: "github",
+                    link: "https://github.com/sam-goodwin/alchemy",
+                },
+            ],
+        },
+    });
+}

package/lib/resource.d.ts

@@ -37,7 +37,7 @@ type IsClass = {
     new (_: never): never;
 };
 type ResourceLifecycleHandler = (this: Context<any, any>, id: string, props: any) => Promise<Resource<string>>;
-type Handler<F extends (...args: any[]) => any> = F | (((this: any, id: string, props?: Parameters<F>[1]) => never) & IsClass);
+type Handler<F extends (...args: any[]) => any> = F | (((this: any, id: string, props?: {}) => never) & IsClass);
 export declare function Resource<const Type extends string, F extends ResourceLifecycleHandler>(type: Type, fn: F): Handler<F>;
 export declare function Resource<const Type extends string, F extends ResourceLifecycleHandler>(type: Type, options: Partial<ProviderOptions>, fn: F): Handler<F>;
 export {};

package/lib/secret.d.ts

@@ -1,7 +1,74 @@
+/**
+ * Internal wrapper for sensitive values like API keys and credentials.
+ * When stored in alchemy state files, the value is automatically encrypted
+ * using the application's password. The password can be provided either:
+ *
+ * 1. Globally when initializing the alchemy application:
+ * ```ts
+ * const app = alchemy("my-app", {
+ *   password: process.env.SECRET_PASSPHRASE
+ * });
+ * ```
+ *
+ * 2. For a specific scope using alchemy.run:
+ * ```ts
+ * await alchemy.run("scope-name", {
+ *   password: process.env.SECRET_PASSPHRASE
+ * }, async () => {
+ *   // Secrets in this scope will use this password
+ *   alchemy.secret(process.env.MY_SECRET)
+ * });
+ * ```
+ *
+ * Without a password, secrets cannot be encrypted or decrypted, and operations
+ * involving sensitive values will fail.
+ *
+ * @example
+ * // In state file (.alchemy/app/prod/resource.json):
+ * {
+ *   "props": {
+ *     "apiKey": {
+ *       "@secret": "encrypted-value-here..." // encrypted using app password
+ *     }
+ *   }
+ * }
+ */
 export declare class Secret {
     readonly unencrypted: string;
     readonly type = "secret";
     constructor(unencrypted: string);
 }
+/**
+ * Type guard to check if a value is a Secret wrapper
+ */
 export declare function isSecret(binding: any): binding is Secret;
+/**
+ * Wraps a sensitive value so it will be encrypted when stored in state files.
+ * Requires a password to be set either globally in the alchemy application options
+ * or locally in an alchemy.run scope.
+ *
+ * @example
+ * // Global password for all secrets
+ * const app = alchemy("my-app", {
+ *   password: process.env.SECRET_PASSPHRASE
+ * });
+ *
+ * const resource = await Resource("my-resource", {
+ *   apiKey: alchemy.secret(process.env.API_KEY)
+ * });
+ *
+ * @example
+ * // Scoped password for specific secrets
+ * await alchemy.run("secure-scope", {
+ *   password: process.env.SCOPE_SECRET_PASSPHRASE
+ * }, async () => {
+ *   const resource = await Resource("my-resource", {
+ *     apiKey: alchemy.secret(process.env.API_KEY)
+ *   });
+ * });
+ *
+ * @param unencrypted The sensitive value to encrypt in state files
+ * @throws {Error} If the value is undefined
+ * @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;

package/lib/secret.js

@@ -1,3 +1,38 @@
+/**
+ * Internal wrapper for sensitive values like API keys and credentials.
+ * When stored in alchemy state files, the value is automatically encrypted
+ * using the application's password. The password can be provided either:
+ *
+ * 1. Globally when initializing the alchemy application:
+ * ```ts
+ * const app = alchemy("my-app", {
+ *   password: process.env.SECRET_PASSPHRASE
+ * });
+ * ```
+ *
+ * 2. For a specific scope using alchemy.run:
+ * ```ts
+ * await alchemy.run("scope-name", {
+ *   password: process.env.SECRET_PASSPHRASE
+ * }, async () => {
+ *   // Secrets in this scope will use this password
+ *   alchemy.secret(process.env.MY_SECRET)
+ * });
+ * ```
+ *
+ * Without a password, secrets cannot be encrypted or decrypted, and operations
+ * involving sensitive values will fail.
+ *
+ * @example
+ * // In state file (.alchemy/app/prod/resource.json):
+ * {
+ *   "props": {
+ *     "apiKey": {
+ *       "@secret": "encrypted-value-here..." // encrypted using app password
+ *     }
+ *   }
+ * }
+ */
 export class Secret {
     unencrypted;
     type = "secret";
@@ -5,10 +40,42 @@ export class Secret {
         this.unencrypted = unencrypted;
     }
 }
+/**
+ * Type guard to check if a value is a Secret wrapper
+ */
 export function isSecret(binding) {
     return (binding instanceof Secret ||
         (typeof binding === "object" && binding.type === "secret_text"));
 }
+/**
+ * Wraps a sensitive value so it will be encrypted when stored in state files.
+ * Requires a password to be set either globally in the alchemy application options
+ * or locally in an alchemy.run scope.
+ *
+ * @example
+ * // Global password for all secrets
+ * const app = alchemy("my-app", {
+ *   password: process.env.SECRET_PASSPHRASE
+ * });
+ *
+ * const resource = await Resource("my-resource", {
+ *   apiKey: alchemy.secret(process.env.API_KEY)
+ * });
+ *
+ * @example
+ * // Scoped password for specific secrets
+ * await alchemy.run("secure-scope", {
+ *   password: process.env.SCOPE_SECRET_PASSPHRASE
+ * }, async () => {
+ *   const resource = await Resource("my-resource", {
+ *     apiKey: alchemy.secret(process.env.API_KEY)
+ *   });
+ * });
+ *
+ * @param unencrypted The sensitive value to encrypt in state files
+ * @throws {Error} If the value is undefined
+ * @throws {Error} If no password is set in the alchemy application options or current scope
+ */
 export function secret(unencrypted) {
     if (unencrypted === undefined) {
         throw new Error("Secret cannot be undefined");

package/lib/shadcn/component.d.ts

@@ -26,4 +26,4 @@ export interface ShadcnComponent extends ShadcnComponentProps, Resource {
      */
     name: string;
 }
-export declare const ShadcnComponent: ((this: Context<ShadcnComponent>, id: string, props: ShadcnComponentProps) => Promise<ShadcnComponent>) | (((this: any, id: string, props?: ShadcnComponentProps | undefined) => never) & (new (_: never) => never));
+export declare const ShadcnComponent: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<ShadcnComponent>, id: string, props: ShadcnComponentProps) => Promise<ShadcnComponent>);

package/lib/stripe/price.d.ts

@@ -104,5 +104,55 @@ export interface Price extends Resource<"stripe::Price">, PriceProps {
      */
     lookupKey?: string;
 }
-export declare const Price: ((this: Context<Price>, id: string, props: PriceProps) => Promise<Price>) | (((this: any, id: string, props?: PriceProps | undefined) => never) & (new (_: never) => never));
+/**
+ * Create and manage Stripe prices for products
+ *
+ * @example
+ * // Create a one-time fixed price for a product
+ * const oneTimePrice = await Price("basic-license", {
+ *   currency: "usd",
+ *   unitAmount: 2999, // $29.99
+ *   product: "prod_xyz"
+ * });
+ *
+ * @example
+ * // Create a recurring subscription price with fixed monthly billing
+ * const subscriptionPrice = await Price("pro-monthly", {
+ *   currency: "usd",
+ *   unitAmount: 1499, // $14.99/month
+ *   product: "prod_xyz",
+ *   recurring: {
+ *     interval: "month",
+ *     usageType: "licensed"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a metered price for usage-based billing
+ * const meteredPrice = await Price("storage", {
+ *   currency: "usd",
+ *   unitAmount: 25, // $0.25 per GB
+ *   product: "prod_xyz",
+ *   recurring: {
+ *     interval: "month",
+ *     usageType: "metered",
+ *     aggregateUsage: "sum"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a tiered price with tax behavior
+ * const tieredPrice = await Price("enterprise", {
+ *   currency: "usd",
+ *   unitAmount: 10000, // $100.00
+ *   product: "prod_xyz",
+ *   billingScheme: "tiered",
+ *   taxBehavior: "exclusive",
+ *   metadata: {
+ *     tier: "enterprise",
+ *     features: "all"
+ *   }
+ * });
+ */
+export declare const Price: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<Price>, id: string, props: PriceProps) => Promise<Price>);
 export {};

package/lib/stripe/price.js

@@ -1,5 +1,55 @@
 import Stripe from "stripe";
 import { Resource } from "../resource";
+/**
+ * Create and manage Stripe prices for products
+ *
+ * @example
+ * // Create a one-time fixed price for a product
+ * const oneTimePrice = await Price("basic-license", {
+ *   currency: "usd",
+ *   unitAmount: 2999, // $29.99
+ *   product: "prod_xyz"
+ * });
+ *
+ * @example
+ * // Create a recurring subscription price with fixed monthly billing
+ * const subscriptionPrice = await Price("pro-monthly", {
+ *   currency: "usd",
+ *   unitAmount: 1499, // $14.99/month
+ *   product: "prod_xyz",
+ *   recurring: {
+ *     interval: "month",
+ *     usageType: "licensed"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a metered price for usage-based billing
+ * const meteredPrice = await Price("storage", {
+ *   currency: "usd",
+ *   unitAmount: 25, // $0.25 per GB
+ *   product: "prod_xyz",
+ *   recurring: {
+ *     interval: "month",
+ *     usageType: "metered",
+ *     aggregateUsage: "sum"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a tiered price with tax behavior
+ * const tieredPrice = await Price("enterprise", {
+ *   currency: "usd",
+ *   unitAmount: 10000, // $100.00
+ *   product: "prod_xyz",
+ *   billingScheme: "tiered",
+ *   taxBehavior: "exclusive",
+ *   metadata: {
+ *     tier: "enterprise",
+ *     features: "all"
+ *   }
+ * });
+ */
 export const Price = Resource("stripe::Price", async function (id, props) {
     // Get Stripe API key from context or environment
     const apiKey = process.env.STRIPE_API_KEY;