alchemy 0.2.3 → 0.2.4

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;

package/lib/stripe/product.d.ts

@@ -81,5 +81,43 @@ export interface Product extends Resource<"stripe::Product">, ProductProps {
         width: number;
     };
 }
-export declare const Product: ((this: Context<Product>, id: string, props: ProductProps) => Promise<Product>) | (((this: any, id: string, props?: ProductProps | undefined) => never) & (new (_: never) => never));
+/**
+ * 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 declare const Product: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<Product>, id: string, props: ProductProps) => Promise<Product>);
 export {};

package/lib/stripe/product.js

@@ -1,5 +1,43 @@
 import Stripe from "stripe";
 import { Resource } from "../resource";
+/**
+ * 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 (id, props) {
     // Get Stripe API key from context or environment
     const apiKey = process.env.STRIPE_API_KEY;

package/lib/stripe/webhook.d.ts

@@ -68,4 +68,49 @@ export interface WebhookEndpoint extends Resource<"stripe::WebhookEndpoint">, We
      */
     status: string;
 }
-export declare const WebhookEndpoint: ((this: Context<WebhookEndpoint>, id: string, props: WebhookEndpointProps) => Promise<WebhookEndpoint>) | (((this: any, id: string, props?: WebhookEndpointProps | undefined) => never) & (new (_: never) => never));
+/**
+ * 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 declare const WebhookEndpoint: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<WebhookEndpoint>, id: string, props: WebhookEndpointProps) => Promise<WebhookEndpoint>);

package/lib/stripe/webhook.js

@@ -1,5 +1,50 @@
 import Stripe from "stripe";
 import { Resource } from "../resource";
+/**
+ * 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 (id, props) {
     // Get Stripe API key from context or environment
     const apiKey = process.env.STRIPE_API_KEY;

package/lib/test/bun.d.ts

@@ -1,19 +1,83 @@
 import type { Scope } from "../scope";
+/**
+ * Extend the Alchemy interface to include test functionality
+ */
 declare module "../alchemy" {
     interface Alchemy {
         test: typeof test;
     }
 }
+/**
+ * Options for configuring test behavior
+ */
 export interface TestOptions {
+    /**
+     * Whether to automatically destroy resources after test.
+     * @default true.
+     */
     destroy?: boolean;
+    /**
+     * Whether to suppress logging output.
+     * @default false.
+     */
     quiet?: boolean;
+    /**
+     * Password to use for test resources.
+     * @default "test-password".
+     */
     password?: string;
 }
+/**
+ * Test function type definition with overloads
+ */
 type test = {
+    /**
+     * Create a test with default options
+     * @param name Test name
+     * @param fn Test function
+     * @param timeout Optional timeout in milliseconds
+     */
     (name: string, fn: (scope: Scope) => Promise<any>, timeout?: number): void;
+    /**
+     * Create a test with custom options
+     * @param name Test name
+     * @param options Test configuration options
+     * @param fn Test function
+     * @param timeout Optional timeout in milliseconds
+     */
     (name: string, options: TestOptions, fn: (scope: Scope) => Promise<any>, timeout?: number): void;
+    /**
+     * Skip test conditionally
+     * @param condition If true, test will be skipped
+     */
     skipIf(condition: boolean): test;
+    /**
+     * Current test scope
+     */
     scope: Scope;
 };
+/**
+ * Creates a test helper function that provides scoped resource management
+ *
+ * @param meta Import meta object from the test file
+ * @param defaultOptions Default options to apply to all tests
+ * @returns Test function with scope management
+ *
+ * @example
+ * ```typescript
+ * const test = alchemy.test(import.meta);
+ *
+ * describe("My Resource", () => {
+ *   test("create and delete", async (scope) => {
+ *     try {
+ *       const resource = await MyResource("test", { ... });
+ *       expect(resource.id).toBeTruthy();
+ *     } finally {
+ *       await alchemy.destroy(scope);
+ *     }
+ *   });
+ * });
+ * ```
+ */
 export declare function test(meta: ImportMeta, defaultOptions?: TestOptions): test;
 export {};

package/lib/test/bun.js

@@ -3,9 +3,39 @@ import { afterAll, it } from "bun:test";
 import path from "node:path";
 import { alchemy } from "../alchemy";
 import { destroy } from "../destroy";
+/**
+ * Add test functionality to alchemy instance
+ */
 alchemy.test = test;
+/**
+ * Global test scope for all tests
+ */
 const globalTestScope = alchemy.scope("test");
+/**
+ * Creates a test helper function that provides scoped resource management
+ *
+ * @param meta Import meta object from the test file
+ * @param defaultOptions Default options to apply to all tests
+ * @returns Test function with scope management
+ *
+ * @example
+ * ```typescript
+ * const test = alchemy.test(import.meta);
+ *
+ * describe("My Resource", () => {
+ *   test("create and delete", async (scope) => {
+ *     try {
+ *       const resource = await MyResource("test", { ... });
+ *       expect(resource.id).toBeTruthy();
+ *     } finally {
+ *       await alchemy.destroy(scope);
+ *     }
+ *   });
+ * });
+ * ```
+ */
 export function test(meta, defaultOptions) {
+    // Add skipIf functionality
     test.skipIf = (condition) => {
         if (condition) {
             // TODO: proxy through to bun:test.skipIf
@@ -13,10 +43,12 @@ export function test(meta, defaultOptions) {
         }
         return test;
     };
+    // Create local test scope based on filename
     const localTestScope = alchemy.scope(path.basename(meta.filename), {
         parent: globalTestScope,
     });
     test.scope = localTestScope;
+    // Clean up test scope after all tests complete
     afterAll(() => alchemy.destroy(test.scope));
     return test;
     function test(...args) {
@@ -25,8 +57,9 @@ export function test(meta, defaultOptions) {
         const spread = (obj) => obj && typeof obj === "object"
             ? Object.fromEntries(Object.entries(obj).flatMap(([k, v]) => v !== undefined ? [[k, v]] : []))
             : {};
+        // Merge options with defaults
         const options = {
-            destroy: false,
+            destroy: true,
             quiet: false,
             password: "test-password",
             ...spread(defaultOptions),
@@ -38,14 +71,13 @@ export function test(meta, defaultOptions) {
             parent: localTestScope,
         }, async (scope) => {
             return it(testName, async () => {
-                // bun will call from a different scope, so we need to enter the test's scope manually
+                // Enter test scope since bun calls from different scope
                 scope.enter();
                 try {
                     await fn(scope);
                 }
                 finally {
                     if (options.destroy !== false) {
-                        // TODO: auto-destroy resources
                         await destroy(scope);
                     }
                 }

package/lib/util/serde.js

@@ -1,6 +1,12 @@
 import { Scope } from "../scope";
 import { Secret } from "../secret";
 import { decryptWithKey, encryptWithKey } from "./encrypt";
+// zero-dependency type guard for ArkType
+function isType(value) {
+    return (value &&
+        typeof value === "object" &&
+        typeof value.toJsonSchema === "function");
+}
 export async function serialize(scope, value, options) {
     if (Array.isArray(value)) {
         return Promise.all(value.map((value) => serialize(scope, value, options)));
@@ -15,6 +21,11 @@ export async function serialize(scope, value, options) {
                 : value.unencrypted,
         };
     }
+    else if (isType(value)) {
+        return {
+            "@schema": value.toJSON(),
+        };
+    }
     else if (value instanceof Scope) {
         return undefined;
     }
@@ -37,6 +48,9 @@ export async function deserialize(scope, value) {
             }
             return new Secret(await decryptWithKey(value["@secret"], scope.password));
         }
+        else if ("@schema" in value) {
+            return value["@schema"];
+        }
         else {
             return Object.fromEntries(await Promise.all(Object.entries(value).map(async ([key, value]) => [
                 key,

package/lib/vite/vite.d.ts

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

package/lib/vitepress/dependencies.d.ts

@@ -1,15 +1,11 @@
 import type { Context } from "../context";
 import { Resource } from "../resource";
 export type InstallDependencies = Resource<"project::InstallDependencies">;
-export declare const InstallDependencies: ((this: Context<InstallDependencies>, id: string, { cwd, dependencies, devDependencies, }: {
+export declare const InstallDependencies: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<InstallDependencies>, id: string, { cwd, dependencies, devDependencies, }: {
     cwd: string;
     dependencies?: Record<string, string>;
     devDependencies?: Record<string, string>;
-}) => Promise<InstallDependencies>) | (((this: any, id: string, props?: {
-    cwd: string;
-    dependencies?: Record<string, string>;
-    devDependencies?: Record<string, string>;
-} | undefined) => never) & (new (_: never) => never));
+}) => Promise<InstallDependencies>);
 export declare function fixedDependencies(dependencies?: Record<string, string>): {
     [k: string]: string;
 };

package/lib/vitepress/vitepress.d.ts

@@ -50,6 +50,17 @@ export interface VitePressProjectProps {
      * The home page configuration
      */
     home: HomePage;
+    /**
+     * Whether to delete the project folder during the delete phase
+     * @default true
+     */
+    delete?: boolean;
+    /**
+     * The directory to generate the docs in
+     *
+     * @default {@link name}
+     */
+    dir?: string;
 }
 export interface VitePressProject extends VitePressProjectProps, Resource {
     /**
@@ -57,4 +68,4 @@ export interface VitePressProject extends VitePressProjectProps, Resource {
      */
     name: string;
 }
-export declare const VitePressProject: ((this: Context<VitePressProject>, id: string, props: VitePressProjectProps) => Promise<VitePressProject>) | (((this: any, id: string, props?: VitePressProjectProps | undefined) => never) & (new (_: never) => never));
+export declare const VitePressProject: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<VitePressProject>, id: string, props: VitePressProjectProps) => Promise<VitePressProject>);

package/lib/vitepress/vitepress.js

@@ -10,11 +10,14 @@ const execAsync = promisify(exec);
 export const VitePressProject = Resource("project::VitePressProject", {
     alwaysUpdate: true,
 }, async function (id, props) {
+    const dir = props.dir ?? props.name;
     if (this.phase === "delete") {
         try {
-            if (await fs.exists(props.name)) {
-                // Delete the entire project directory
-                await execAsync(`rm -rf ${props.name}`);
+            if (props.delete !== false) {
+                if (await fs.exists(dir)) {
+                    // Delete the entire project directory
+                    await execAsync(`rm -rf ${dir}`);
+                }
             }
         }
         catch (error) {
@@ -22,7 +25,10 @@ export const VitePressProject = Resource("project::VitePressProject", {
         }
         return this.destroy();
     }
-    const cwd = (await Folder(props.name)).path;
+    const cwd = (await Folder("dir", {
+        path: dir,
+        delete: props.delete,
+    })).path;
     // Initialize package.json
     await JsonFile(path.join(cwd, "package.json"), {
         name: props.name,
@@ -57,25 +63,25 @@ export const VitePressProject = Resource("project::VitePressProject", {
             compilerOptions: props.tsconfig?.compilerOptions,
         }),
         TextFile(path.join(cwd, "index.md"), `---\n${yaml.stringify(props.home)}---\n`),
-        TypeScriptFile(path.join(cwd, "alchemy.run.ts"), `import alchemy from "alchemy";
-import { Folder } from "alchemy/fs";
-import { Document } from "alchemy/docs";
-import path from "path";
-
-await using _ = alchemy("alchemy.run", {
-  stage: "prod",
-  phase: process.argv.includes("--destroy") ? "destroy" : "up",
-  password: process.env.SECRET_PASSPHRASE,
-  quiet: !process.argv.includes("--verbose"),
-});
-
-const docs = await Folder(path.join("alchemy.run", "docs"));
-
-await Document("home.md", {
-  path: path.join(docs.path, "home.md"),
-  prompt: await alchemy\`Generate a landing page.\`,
-});
-`),
+        //       TypeScriptFile(
+        //         path.join(cwd, "alchemy.run.ts"),
+        //         `import alchemy from "alchemy";
+        // import { Folder } from "alchemy/fs";
+        // import { Document } from "alchemy/docs";
+        // import path from "path";
+        // await using _ = alchemy("alchemy.run", {
+        //   stage: "prod",
+        //   phase: process.argv.includes("--destroy") ? "destroy" : "up",
+        //   password: process.env.SECRET_PASSPHRASE,
+        //   quiet: !process.argv.includes("--verbose"),
+        // });
+        // const docs = await Folder(path.join("alchemy.run", "docs"));
+        // await Document("home.md", {
+        //   path: path.join(docs.path, "home.md"),
+        //   prompt: await alchemy\`Generate a landing page.\`,
+        // });
+        // `,
+        //       ),
         TypeScriptFile(path.join(cwd, ".vitepress", "theme", "index.ts"), `import TwoslashFloatingVue from "@shikijs/vitepress-twoslash/client";
 import "@shikijs/vitepress-twoslash/style.css";
 import type { Theme as ThemeConfig } from "vitepress";

package/package.json

@@ -1,18 +1,19 @@
 {
   "name": "alchemy",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "type": "module",
   "module": "./lib/index.js",
   "scripts": {
-    "publish:npm": "cp ../README.md . && rm -rf ./*.tsbuildinfo && rm -rf ./lib && tsc -b && npm publish && rm README.md"
+    "publish:npm": "cp ../README.md . && rm -rf ./*.tsbuildinfo && rm -rf ./lib && tsc -b && npm publish && rm README.md",
+    "docs:gen": "rm -rf ./docs && typedoc"
   },
   "files": ["lib", "src"],
   "exports": {
     ".": "./lib/index.js",
+    "./ai": "./lib/ai/index.js",
     "./aws": "./lib/aws/index.js",
     "./aws/oidc": "./lib/aws/oidc/index.js",
     "./cloudflare": "./lib/cloudflare/index.js",
-    "./docs": "./lib/docs/index.js",
     "./esbuild": "./lib/esbuild/index.js",
     "./fs": "./lib/fs/index.js",
     "./github": "./lib/github/index.js",
@@ -33,6 +34,7 @@
     "@aws-sdk/client-sesv2": "^3.0.0",
     "@aws-sdk/client-sqs": "^3.0.0",
     "@aws-sdk/client-sts": "^3.0.0",
+    "arktype": "^2.0.0",
     "prettier": "^3.0.0",
     "@octokit/rest": "^21.1.1",
     "ai": "^4.0.0",
@@ -59,11 +61,14 @@
     "@types/node": "latest",
     "@types/turndown": "^5.0.5",
     "ai": "^4.1.16",
+    "arktype": "^2.1.16",
     "change-case": "^5.4.4",
     "libsodium-wrappers": "^0.7.15",
     "openpgp": "^6.1.0",
     "prettier": "^3.5.3",
     "turndown": "^7.2.0",
+    "typedoc": "^0.28.1",
+    "typedoc-plugin-markdown": "^4.6.0",
     "typescript": "latest",
     "vite": "^6.0.7",
     "vitepress": "^1.6.3",