alchemy 0.2.2 → 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) => 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) => 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.d.ts

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

package/lib/util/serde.js

@@ -1,16 +1,29 @@
 import { Scope } from "../scope";
 import { Secret } from "../secret";
 import { decryptWithKey, encryptWithKey } from "./encrypt";
-export async function serialize(scope, value) {
+// 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)));
+        return Promise.all(value.map((value) => serialize(scope, value, options)));
     }
     else if (value instanceof Secret) {
         if (!scope.password) {
             throw new Error("Cannot serialize secret without password");
         }
         return {
-            "@secret": await encryptWithKey(value.unencrypted, scope.password),
+            "@secret": options?.encrypt !== false
+                ? await encryptWithKey(value.unencrypted, scope.password)
+                : value.unencrypted,
+        };
+    }
+    else if (isType(value)) {
+        return {
+            "@schema": value.toJSON(),
         };
     }
     else if (value instanceof Scope) {
@@ -19,7 +32,7 @@ export async function serialize(scope, value) {
     else if (value && typeof value === "object") {
         return Object.fromEntries(await Promise.all(Object.entries(value).map(async ([key, value]) => [
             key,
-            await serialize(scope, value),
+            await serialize(scope, value, options),
         ])));
     }
     return value;
@@ -35,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) => 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

@@ -0,0 +1,12 @@
+import type { Context } from "../context";
+import { Resource } from "../resource";
+export type InstallDependencies = Resource<"project::InstallDependencies">;
+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>);
+export declare function fixedDependencies(dependencies?: Record<string, string>): {
+    [k: string]: string;
+};
+export declare function installDependencies(cwd: string, dependencies: Record<string, string> | undefined, ...args: string[]): Promise<void>;

package/lib/vitepress/dependencies.js

@@ -0,0 +1,35 @@
+import { exec } from "child_process";
+import { promisify } from "util";
+import { Resource } from "../resource";
+const execAsync = promisify(exec);
+export const InstallDependencies = Resource("project::InstallDependencies", {
+    alwaysUpdate: true,
+}, async function (id, { cwd, dependencies, devDependencies, }) {
+    if (this.phase === "delete") {
+        return this.destroy();
+    }
+    await installDependencies(cwd, dependencies);
+    await installDependencies(cwd, devDependencies, "-D");
+    await execAsync("bun install", { cwd });
+    return this({});
+});
+function isInstallableVersion(version) {
+    // TODO: file:// ?
+    return !version.startsWith("workspace:");
+}
+export function fixedDependencies(dependencies) {
+    if (!dependencies)
+        return {};
+    return Object.fromEntries(Object.entries(dependencies).filter(([, value]) => !isInstallableVersion(value)));
+}
+export async function installDependencies(cwd, dependencies, ...args) {
+    if (!dependencies)
+        return;
+    const deps = Object.entries(dependencies)
+        .filter(([, value]) => isInstallableVersion(value))
+        .map(([pkg, version]) => `${pkg}@${version}`)
+        .join(" ");
+    const cmd = `bun add ${args.join(" ")} ${deps}`;
+    console.log(cmd);
+    await execAsync(cmd, { cwd });
+}

package/lib/vitepress/home-page.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Image that can be themed for light/dark mode
+ */
+export interface ThemeableImage {
+    /**
+     * Image source URL
+     */
+    src?: string;
+    /**
+     * Image alt text
+     */
+    alt?: string;
+    /**
+     * Light theme image URL
+     */
+    light?: string;
+    /**
+     * Dark theme image URL
+     */
+    dark?: string;
+}
+/**
+ * Hero action button configuration
+ */
+export interface HeroAction {
+    /**
+     * Color theme of the button
+     * @default "brand"
+     */
+    theme?: "brand" | "alt";
+    /**
+     * Label of the button
+     */
+    text: string;
+    /**
+     * Destination link of the button
+     */
+    link: string;
+    /**
+     * Link target attribute
+     */
+    target?: string;
+    /**
+     * Link rel attribute
+     */
+    rel?: string;
+}
+/**
+ * Hero section configuration
+ */
+export interface Hero {
+    /**
+     * The string shown top of text. Comes with brand color
+     * and expected to be short, such as product name.
+     */
+    name?: string;
+    /**
+     * The main text for the hero section. This will be defined
+     * as h1 tag.
+     */
+    text: string;
+    /**
+     * Tagline displayed below text
+     */
+    tagline?: string;
+    /**
+     * The image displayed next to the text and tagline area
+     */
+    image?: string | ThemeableImage;
+    /**
+     * Action buttons to display in home hero section
+     */
+    actions?: HeroAction[];
+}
+/**
+ * Feature item configuration
+ */
+export interface Feature {
+    /**
+     * Show icon on each feature box
+     */
+    icon?: string | ThemeableImage;
+    /**
+     * Title of the feature
+     */
+    title: string;
+    /**
+     * Details of the feature
+     */
+    details: string;
+    /**
+     * Link when clicked on feature component
+     */
+    link?: string;
+    /**
+     * Link text to be shown inside feature component
+     */
+    linkText?: string;
+    /**
+     * Link rel attribute
+     */
+    rel?: string;
+    /**
+     * Link target attribute
+     */
+    target?: string;
+}
+/**
+ * VitePress home page configuration
+ */
+export interface HomePage {
+    /**
+     * Use home page layout
+     */
+    layout: "home";
+    /**
+     * Hero section configuration
+     */
+    hero?: Hero;
+    /**
+     * Features section configuration
+     */
+    features?: Feature[];
+    /**
+     * Whether to apply default markdown styles
+     * @default true
+     */
+    markdownStyles?: boolean;
+}
+/**
+ * Parse YAML frontmatter to home page config
+ */
+export declare function parseHomePage(content: string): HomePage;

package/lib/vitepress/home-page.js

@@ -0,0 +1,11 @@
+import yaml from "yaml";
+/**
+ * Parse YAML frontmatter to home page config
+ */
+export function parseHomePage(content) {
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match) {
+        throw new Error("Invalid frontmatter format");
+    }
+    return yaml.parse(match[1]);
+}

package/lib/vitepress/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./home-page";
+export * from "./vitepress";

package/lib/vitepress/index.js

@@ -0,0 +1,2 @@
+export * from "./home-page";
+export * from "./vitepress";