alchemy 0.2.3 → 0.2.5

package/src/internal/docs.ts

@@ -0,0 +1,338 @@
+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 interface DocsProps {
+  docs?: boolean | number;
+}
+
+export type AlchemyDocs = Awaited<ReturnType<typeof AlchemyDocs>>;
+
+export async function AlchemyDocs({ docs: isDocsEnabled }: DocsProps) {
+  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,
+      } as const;
+    }),
+  );
+
+  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/src/resource.ts

@@ -75,7 +75,7 @@ type ResourceLifecycleHandler = (
 // see: https://x.com/samgoodwin89/status/1904640134097887653
 type Handler<F extends (...args: any[]) => any> =
   | F
-  | (((this: any, id: string, props?: Parameters<F>[1]) => never) & IsClass);
+  | (((this: any, id: string, props?: {}) => never) & IsClass);
 
 export function Resource<
   const Type extends string,

package/src/secret.ts

@@ -1,8 +1,46 @@
+/**
+ * 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 {
   public readonly type = "secret";
   constructor(readonly unencrypted: string) {}
 }
 
+/**
+ * Type guard to check if a value is a Secret wrapper
+ */
 export function isSecret(binding: any): binding is Secret {
   return (
     binding instanceof Secret ||
@@ -10,6 +48,35 @@ export 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 function secret<S extends string | undefined>(unencrypted: S): Secret {
   if (unencrypted === undefined) {
     throw new Error("Secret cannot be undefined");

package/src/stripe/price.ts

@@ -125,6 +125,56 @@ export interface Price extends Resource<"stripe::Price">, PriceProps {
   lookupKey?: string;
 }
 
+/**
+ * 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 (

package/src/stripe/product.ts

@@ -99,6 +99,44 @@ export interface Product extends Resource<"stripe::Product">, ProductProps {
   };
 }
 
+/**
+ * Create and manage Stripe products
+ *
+ * @example
+ * // Create a basic digital product
+ * const digitalProduct = await Product("basic-software", {
+ *   name: "Basic Software License",
+ *   description: "Single-user license for basic software package",
+ *   metadata: {
+ *     type: "digital",
+ *     features: "basic"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a physical product with shipping details
+ * const physicalProduct = await Product("premium-hardware", {
+ *   name: "Premium Hardware Kit",
+ *   description: "Complete hardware kit with premium components",
+ *   shippable: true,
+ *   images: ["https://example.com/hardware-kit.jpg"],
+ *   unitLabel: "kit",
+ *   statementDescriptor: "PREMIUM HW KIT"
+ * });
+ *
+ * @example
+ * // Create a service product with tax code
+ * const serviceProduct = await Product("consulting", {
+ *   name: "Professional Consulting",
+ *   description: "Expert consulting services",
+ *   type: "service",
+ *   taxCode: "txcd_10000000",
+ *   metadata: {
+ *     industry: "technology",
+ *     expertise: "cloud"
+ *   }
+ * });
+ */
 export const Product = Resource(
   "stripe::Product",
   async function (

package/src/stripe/webhook.ts

@@ -86,6 +86,51 @@ export interface WebhookEndpoint
   status: string;
 }
 
+/**
+ * Create and manage Stripe webhook endpoints
+ *
+ * @example
+ * // Create a basic webhook for payment events
+ * const paymentWebhook = await WebhookEndpoint("payment-webhook", {
+ *   url: "https://api.example.com/stripe/payments",
+ *   enabledEvents: [
+ *     "payment_intent.succeeded",
+ *     "payment_intent.payment_failed"
+ *   ],
+ *   description: "Webhook for payment notifications"
+ * });
+ *
+ * @example
+ * // Create a webhook for subscription management
+ * const subscriptionWebhook = await WebhookEndpoint("subscription-webhook", {
+ *   url: "https://api.example.com/stripe/subscriptions",
+ *   enabledEvents: [
+ *     "customer.subscription.created",
+ *     "customer.subscription.updated",
+ *     "customer.subscription.deleted",
+ *     "invoice.payment_succeeded",
+ *     "invoice.payment_failed"
+ *   ],
+ *   description: "Webhook for subscription lifecycle events"
+ * });
+ *
+ * @example
+ * // Create a webhook for Connect platform events
+ * const connectWebhook = await WebhookEndpoint("connect-webhook", {
+ *   url: "https://api.example.com/stripe/connect",
+ *   enabledEvents: [
+ *     "account.updated",
+ *     "account.application.deauthorized",
+ *     "payout.created",
+ *     "payout.failed"
+ *   ],
+ *   connect: true,
+ *   metadata: {
+ *     platform: "connect",
+ *     environment: "production"
+ *   }
+ * });
+ */
 export const WebhookEndpoint = Resource(
   "stripe::WebhookEndpoint",
   async function (