alchemy 0.2.2 → 0.2.4

package/src/aws/bucket.ts

@@ -14,23 +14,118 @@ import type { Context } from "../context";
 import { Resource } from "../resource";
 import { ignore } from "../util/ignore";
 
+/**
+ * Properties for creating or updating an S3 bucket
+ */
 export interface BucketProps {
+  /**
+   * The name of the bucket. Must be globally unique across all AWS accounts.
+   * Should be lowercase alphanumeric characters or hyphens.
+   */
   bucketName: string;
+
+  /**
+   * Optional tags to apply to the bucket for organization and cost tracking.
+   * Each tag is a key-value pair.
+   */
   tags?: Record<string, string>;
 }
 
+/**
+ * Output returned after S3 bucket creation/update
+ */
 export interface Bucket extends Resource<"s3::Bucket">, BucketProps {
+  /**
+   * The ARN (Amazon Resource Name) of the bucket
+   * Format: arn:aws:s3:::bucket-name
+   */
   arn: string;
-  bucketDomainName: string; // Format: bucket-name.s3.amazonaws.com
-  bucketRegionalDomainName?: string; // Format: bucket-name.s3.region.amazonaws.com
-  hostedZoneId?: string; // S3 hosted zone ID for the region
-  region?: string; // AWS Region where bucket resides
-  websiteEndpoint?: string; // Only if website hosting is enabled
-  websiteDomain?: string; // Only if website hosting is enabled
+
+  /**
+   * The global domain name for the bucket
+   * Format: bucket-name.s3.amazonaws.com
+   */
+  bucketDomainName: string;
+
+  /**
+   * The regional domain name for the bucket
+   * Format: bucket-name.s3.region.amazonaws.com
+   */
+  bucketRegionalDomainName?: string;
+
+  /**
+   * The S3 hosted zone ID for the region where the bucket resides
+   * Used for DNS configuration with Route 53
+   */
+  hostedZoneId?: string;
+
+  /**
+   * The AWS region where the bucket is located
+   */
+  region?: string;
+
+  /**
+   * The website endpoint URL if static website hosting is enabled
+   * Format: http://bucket-name.s3-website-region.amazonaws.com
+   */
+  websiteEndpoint?: string;
+
+  /**
+   * The website domain if static website hosting is enabled
+   * Format: bucket-name.s3-website-region.amazonaws.com
+   */
+  websiteDomain?: string;
+
+  /**
+   * Whether versioning is enabled for the bucket
+   */
   versioningEnabled?: boolean;
+
+  /**
+   * The canned ACL applied to the bucket
+   * Common values: private, public-read, public-read-write, authenticated-read
+   */
   acl?: string;
 }
 
+/**
+ * AWS S3 Bucket Resource
+ *
+ * Creates and manages Amazon S3 buckets with support for versioning, tags, and regional configuration.
+ * S3 buckets provide scalable object storage for any type of data, with features like versioning,
+ * lifecycle policies, and fine-grained access control.
+ *
+ * @example
+ * // Create a basic S3 bucket with default settings
+ * const basicBucket = await Bucket("my-app-storage", {
+ *   bucketName: "my-app-storage",
+ *   tags: {
+ *     Environment: "production",
+ *     Project: "my-app"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a bucket with versioning enabled and specific tags
+ * const versionedBucket = await Bucket("document-archive", {
+ *   bucketName: "document-archive",
+ *   tags: {
+ *     Environment: "production",
+ *     Purpose: "document-storage",
+ *     Versioning: "enabled"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a development bucket with minimal configuration
+ * const devBucket = await Bucket("dev-testing", {
+ *   bucketName: "dev-testing",
+ *   tags: {
+ *     Environment: "development",
+ *     Temporary: "true"
+ *   }
+ * });
+ */
 export const Bucket = Resource(
   "s3::Bucket",
   async function (this: Context<Bucket>, id: string, props: BucketProps) {
@@ -136,7 +231,16 @@ export const Bucket = Resource(
   },
 );
 
-// Helper function to get S3 hosted zone IDs by region
+/**
+ * Helper function to get S3 hosted zone IDs by region
+ *
+ * Returns the S3 hosted zone ID for a given AWS region. These IDs are used when
+ * configuring Route 53 DNS records that point to S3 buckets. If the region is not
+ * found in the mapping, defaults to the us-east-1 hosted zone ID.
+ *
+ * @param region - The AWS region code (e.g., us-east-1, eu-west-1)
+ * @returns The S3 hosted zone ID for the region
+ */
 function getHostedZoneId(region: string): string {
   const hostedZoneIds: Record<string, string> = {
     "us-east-1": "Z3AQBSTGFYJSTF",

package/src/aws/function.ts

@@ -16,61 +16,275 @@ import type { Context } from "../context";
 import { Resource } from "../resource";
 import { ignore } from "../util/ignore";
 
-async function resolveRegion(client: LambdaClient): Promise<string> {
-  const region = client.config.region;
-  if (typeof region === "string") return region;
-  if (typeof region === "function") return region();
-  throw new Error("Could not resolve AWS region");
-}
-
+/**
+ * Properties for creating or updating a Lambda function
+ */
 export interface FunctionProps {
+  /**
+   * Name of the Lambda function
+   */
   functionName: string;
+
+  /**
+   * Path to the zip file containing the function code
+   */
   zipPath: string;
+
+  /**
+   * ARN of the IAM role that Lambda assumes when executing the function
+   */
   roleArn: string;
+
+  /**
+   * Function handler in the format 'file.function'
+   * For Node.js this is typically 'index.handler' or similar
+   */
   handler?: string;
+
+  /**
+   * Lambda runtime environment for the function
+   * @default nodejs20.x if not specified
+   */
   runtime?: Runtime;
+
+  /**
+   * CPU architecture for the function
+   * @default x86_64 if not specified
+   */
   architecture?: Architecture;
+
+  /**
+   * Description of the function's purpose
+   */
   description?: string;
+
+  /**
+   * Maximum execution time in seconds
+   * @default 3 seconds if not specified
+   */
   timeout?: number;
+
+  /**
+   * Amount of memory available to the function in MB
+   * @default 128 MB if not specified
+   */
   memorySize?: number;
+
+  /**
+   * Environment variables available to the function code
+   */
   environment?: Record<string, string>;
+
+  /**
+   * Resource tags for the function
+   */
   tags?: Record<string, string>;
+
+  /**
+   * Function URL configuration for direct HTTP(S) invocation
+   */
   url?: {
+    /**
+     * Authentication type for the function URL
+     */
     authType?: "AWS_IAM" | "NONE";
+
+    /**
+     * CORS configuration for the function URL
+     */
     cors?: {
+      /**
+       * Whether to allow credentials in CORS requests
+       */
       allowCredentials?: boolean;
+
+      /**
+       * Allowed headers in CORS requests
+       */
       allowHeaders?: string[];
+
+      /**
+       * Allowed HTTP methods in CORS requests
+       */
       allowMethods?: string[];
+
+      /**
+       * Allowed origins in CORS requests
+       */
       allowOrigins?: string[];
+
+      /**
+       * Headers exposed to the browser
+       */
       exposeHeaders?: string[];
+
+      /**
+       * CORS preflight cache time in seconds
+       */
       maxAge?: number;
     };
   };
 }
 
+/**
+ * Output returned after Lambda function creation/update
+ */
 export interface Function extends Resource<"lambda::Function">, FunctionProps {
+  /**
+   * ARN of the Lambda function
+   */
   arn: string;
+
+  /**
+   * Timestamp of the last function modification
+   */
   lastModified: string;
+
+  /**
+   * Function version
+   */
   version: string;
-  qualifiedArn: string; // ARN with version
-  invokeArn: string; // ARN for API Gateway
+
+  /**
+   * ARN with version suffix
+   */
+  qualifiedArn: string;
+
+  /**
+   * ARN for invoking the function through API Gateway
+   */
+  invokeArn: string;
+
+  /**
+   * SHA256 hash of the function code
+   */
   sourceCodeHash: string;
+
+  /**
+   * Size of the function code in bytes
+   */
   sourceCodeSize: number;
+
+  /**
+   * Size of ephemeral storage (/tmp) in MB
+   */
   ephemeralStorageSize?: number;
+
+  /**
+   * List of supported CPU architectures
+   */
   architectures: string[];
-  masterArn?: string; // Only for Lambda@Edge
+
+  /**
+   * ARN of the master function (Lambda@Edge only)
+   */
+  masterArn?: string;
+
+  /**
+   * Unique identifier for the current function code/config
+   */
   revisionId: string;
+
+  /**
+   * Current state of the function
+   */
   state?: string;
+
+  /**
+   * Reason for the current state
+   */
   stateReason?: string;
+
+  /**
+   * Code for the current state reason
+   */
   stateReasonCode?: string;
+
+  /**
+   * Status of the last update operation
+   */
   lastUpdateStatus?: string;
+
+  /**
+   * Reason for the last update status
+   */
   lastUpdateStatusReason?: string;
+
+  /**
+   * Code for the last update status reason
+   */
   lastUpdateStatusReasonCode?: string;
+
+  /**
+   * Function package type (Zip or Image)
+   */
   packageType: string;
+
+  /**
+   * ARN of the signing profile version
+   */
   signingProfileVersionArn?: string;
+
+  /**
+   * ARN of the signing job
+   */
   signingJobArn?: string;
 }
 
+/**
+ * AWS Lambda Function Resource
+ *
+ * Creates and manages AWS Lambda functions with support for Node.js runtimes, custom handlers,
+ * environment variables, and function URLs. Handles deployment packaging, IAM role
+ * stabilization, and function updates.
+ *
+ * @example
+ * // Create a basic Lambda function with minimal configuration
+ * const basicFunction = await Function("api-handler", {
+ *   functionName: "api-handler",
+ *   zipPath: "./dist/api.zip",
+ *   roleArn: role.arn,
+ *   runtime: Runtime.nodejs20x,
+ *   handler: "index.handler",
+ *   tags: {
+ *     Environment: "production"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a function with environment variables and custom memory/timeout
+ * const configuredFunction = await Function("worker", {
+ *   functionName: "worker",
+ *   zipPath: "./dist/worker.zip",
+ *   roleArn: role.arn,
+ *   runtime: Runtime.nodejs20x,
+ *   handler: "worker.process",
+ *   memorySize: 512,
+ *   timeout: 30,
+ *   environment: {
+ *     QUEUE_URL: queue.url,
+ *     LOG_LEVEL: "info"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a function with a public URL endpoint and CORS
+ * const apiFunction = await Function("public-api", {
+ *   functionName: "public-api",
+ *   zipPath: "./dist/api.zip",
+ *   roleArn: role.arn,
+ *   handler: "api.handler",
+ *   url: {
+ *     authType: "NONE",
+ *     cors: {
+ *       allowOrigins: ["*"],
+ *       allowMethods: ["GET", "POST"],
+ *       allowHeaders: ["content-type"],
+ *       maxAge: 86400
+ *     }
+ *   }
+ * });
+ */
 export const Function = Resource(
   "lambda::Function",
   async function (this: Context<Function>, id: string, props: FunctionProps) {
@@ -280,3 +494,10 @@ async function zipCode(filePath: string): Promise<Buffer> {
     platform: "UNIX",
   });
 }
+
+async function resolveRegion(client: LambdaClient): Promise<string> {
+  const region = client.config.region;
+  if (typeof region === "string") return region;
+  if (typeof region === "function") return region();
+  throw new Error("Could not resolve AWS region");
+}

package/src/aws/oidc/github-oidc-provider.ts

@@ -7,13 +7,96 @@ import { OIDCProvider, type OIDCProviderProps } from "./oidc-provider";
  */
 const DEFAULT_GITHUB_THUMBPRINT = "6938fd4d98bab03faadb97b34396831e3780aea1";
 
+/**
+ * Properties for configuring GitHub-specific OIDC provider
+ * Simplified version of OIDCProviderProps that omits the thumbprint
+ * since it's automatically set to GitHub's known value
+ */
 export interface GitHubOIDCProviderProps
   extends Omit<OIDCProviderProps, "thumbprint"> {
+  /**
+   * The GitHub organization or user that owns the repository
+   * Example: "my-org" or "my-username"
+   */
   owner: string;
+
+  /**
+   * The name of the GitHub repository
+   * Example: "my-repo"
+   */
   repository: string;
 }
+
 export type GitHubOIDCProvider = ReturnType<typeof GitHubOIDCProvider>;
 
+/**
+ * GitHub-specific OIDC Provider Resource
+ *
+ * A simplified wrapper around OIDCProvider that automatically sets the correct
+ * thumbprint for GitHub Actions. This is the recommended way to set up OIDC
+ * authentication for GitHub Actions workflows.
+ *
+ * @example
+ * // Create a GitHub OIDC provider for all branches
+ * const provider = await GitHubOIDCProvider("github", {
+ *   owner: "my-org",
+ *   repository: "my-repo",
+ *   roleArn: "arn:aws:iam::123456789012:role/github-actions"
+ * });
+ *
+ * @example
+ * // Create a GitHub OIDC provider with branch and environment restrictions
+ * const provider = await GitHubOIDCProvider("github-restricted", {
+ *   owner: "my-org",
+ *   repository: "my-repo",
+ *   branches: ["main", "prod"],
+ *   environments: ["staging", "production"],
+ *   roleArn: "arn:aws:iam::123456789012:role/github-actions",
+ *   maxSessionDuration: 7200
+ * });
+ *
+ * @example
+ * // Complete setup with IAM role and OIDC provider
+ * import { Role, getAccountId } from "../aws";
+ *
+ * // Get the AWS account ID
+ * const accountId = await getAccountId();
+ *
+ * // Create the IAM role that GitHub Actions will assume
+ * const githubRole = await Role("github-oidc-role", {
+ *   roleName: "github-actions-role",
+ *   assumeRolePolicy: {
+ *     Version: "2012-10-17",
+ *     Statement: [
+ *       {
+ *         Sid: "GitHubOIDC",
+ *         Effect: "Allow",
+ *         Principal: {
+ *           Federated: `arn:aws:iam::${accountId}:oidc-provider/token.actions.githubusercontent.com`
+ *         },
+ *         Action: "sts:AssumeRoleWithWebIdentity",
+ *         Condition: {
+ *           StringEquals: {
+ *             "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
+ *           },
+ *           StringLike: {
+ *             "token.actions.githubusercontent.com:sub": "repo:my-org/my-repo:*"
+ *           }
+ *         }
+ *       }
+ *     ]
+ *   },
+ *   // Add required managed policies or inline policies for your use case
+ *   managedPolicyArns: ["arn:aws:iam::aws:policy/ReadOnlyAccess"]
+ * });
+ *
+ * // Create the OIDC provider using the role
+ * const provider = await GitHubOIDCProvider("github-oidc", {
+ *   owner: "my-org",
+ *   repository: "my-repo",
+ *   roleArn: githubRole.arn
+ * });
+ */
 export const GitHubOIDCProvider = async (
   id: string,
   props: GitHubOIDCProviderProps,

package/src/aws/oidc/oidc-provider.ts

@@ -17,43 +17,52 @@ import { getAccountId } from "../account-id";
 export interface OIDCProviderProps {
   /**
    * The GitHub organization or user that owns the repository
+   * Example: "my-org" or "my-username"
    */
   owner: string;
 
   /**
    * The name of the GitHub repository
+   * Example: "my-repo"
    */
   repository: string;
 
   /**
    * Optional list of branches to restrict access to
    * If not provided, all branches will be allowed
+   * Example: ["main", "prod"]
    */
   branches?: string[];
 
   /**
    * Optional list of environments to restrict access to
    * If not provided, all environments will be allowed
+   * Example: ["staging", "production"]
    */
   environments?: string[];
 
   /**
    * The ARN of the IAM role to be assumed
+   * Format: arn:aws:iam::account-id:role/role-name
    */
   roleArn: string;
 
   /**
-   * Optional maximum session duration in seconds (default: 3600)
+   * Optional maximum session duration in seconds
+   * Default: 3600 (1 hour)
+   * Range: 900-43200 seconds (15 minutes to 12 hours)
    */
   maxSessionDuration?: number;
 
   /**
    * Thumbprint for the OIDC provider
+   * Used to verify the identity provider's server certificate
    */
   thumbprint: string;
 
   /**
-   * Optional AWS region (defaults to AWS_REGION environment variable)
+   * Optional AWS region
+   * @default AWS_REGION environment variable
    */
   region?: string;
 }
@@ -66,24 +75,47 @@ export interface OIDCProvider
     OIDCProviderProps {
   /**
    * The ARN of the OIDC provider
+   * Format: arn:aws:iam::account-id:oidc-provider/token.actions.githubusercontent.com
    */
   providerArn: string;
 
   /**
    * Time at which the provider was created
+   * Unix timestamp in milliseconds
    */
   createdAt: number;
 }
 
 /**
- * Unique identifier for our trust policy statement
- * Used to track and remove our specific statement without affecting others
+ * AWS OIDC Provider Resource for GitHub Actions
+ *
+ * Creates and manages an OpenID Connect (OIDC) identity provider in AWS IAM
+ * for GitHub Actions workflows. This enables secure, token-based authentication
+ * between GitHub Actions and AWS without storing long-term credentials.
+ *
+ * @example
+ * // Create an OIDC provider for all branches
+ * const provider = await OIDCProvider("github", {
+ *   owner: "my-org",
+ *   repository: "my-repo",
+ *   roleArn: "arn:aws:iam::123456789012:role/github-actions",
+ *   thumbprint: "6938fd4d98bab03faadb97b34396831e3780aea1"
+ * });
+ *
+ * @example
+ * // Create an OIDC provider restricted to specific branches and environments
+ * const provider = await OIDCProvider("github-restricted", {
+ *   owner: "my-org",
+ *   repository: "my-repo",
+ *   branches: ["main", "prod"],
+ *   environments: ["staging", "production"],
+ *   roleArn: "arn:aws:iam::123456789012:role/github-actions",
+ *   thumbprint: "6938fd4d98bab03faadb97b34396831e3780aea1",
+ *   maxSessionDuration: 7200
+ * });
  */
 const TRUST_POLICY_SID = "GitHubOIDCTrust";
 
-/**
- * Resource for configuring AWS OIDC provider for GitHub Actions
- */
 export const OIDCProvider = Resource(
   "aws::OIDCProvider",
   async function (

package/src/aws/policy-attachment.ts

@@ -8,16 +8,59 @@ import type { Context } from "../context";
 import { Resource } from "../resource";
 import { ignore } from "../util/ignore";
 
-// PolicyAttachment resource
+/**
+ * Properties for creating or updating a policy attachment
+ */
 export interface PolicyAttachmentProps {
+  /**
+   * ARN of the IAM policy to attach
+   */
   policyArn: string;
+
+  /**
+   * Name of the IAM role to attach the policy to
+   */
   roleName: string;
 }
 
+/**
+ * Output returned after policy attachment creation/update
+ */
 export interface PolicyAttachment
   extends Resource<"iam::PolicyAttachment">,
     PolicyAttachmentProps {}
 
+/**
+ * AWS IAM Policy Attachment Resource
+ *
+ * Attaches an IAM policy to a role, enabling the role to use the permissions defined in the policy.
+ *
+ * @example
+ * // Attach an AWS managed policy to a role
+ * const adminAccess = await PolicyAttachment("admin-policy", {
+ *   policyArn: "arn:aws:iam::aws:policy/AdministratorAccess",
+ *   roleName: role.name
+ * });
+ *
+ * @example
+ * // Attach a custom policy to a role
+ * const customPolicy = await PolicyAttachment("custom-policy", {
+ *   policyArn: policy.arn,
+ *   roleName: role.name
+ * });
+ *
+ * @example
+ * // Attach multiple policies to a role
+ * const s3Access = await PolicyAttachment("s3-access", {
+ *   policyArn: "arn:aws:iam::aws:policy/AmazonS3FullAccess",
+ *   roleName: role.name
+ * });
+ *
+ * const sqsAccess = await PolicyAttachment("sqs-access", {
+ *   policyArn: "arn:aws:iam::aws:policy/AmazonSQSFullAccess",
+ *   roleName: role.name
+ * });
+ */
 export const PolicyAttachment = Resource(
   "iam::PolicyAttachment",
   async function (