alchemy 0.2.2 → 0.2.4

package/src/aws/policy.ts

@@ -12,44 +12,219 @@ import {
 import type { Context } from "../context";
 import { Resource } from "../resource";
 
-// Type-safe policy document types
+/**
+ * Type of effect for a policy statement
+ */
 export type Effect = "Allow" | "Deny";
 
+/**
+ * A single statement within an IAM policy document
+ */
 export interface PolicyStatement {
+  /**
+   * Optional identifier for the statement
+   */
   Sid?: string;
+
+  /**
+   * Whether to allow or deny the specified actions
+   */
   Effect: Effect;
+
+  /**
+   * Actions that the policy allows or denies
+   */
   Action: string | string[];
+
+  /**
+   * Resources that the policy applies to
+   */
   Resource?: string | string[];
+
+  /**
+   * Additional conditions for when the policy applies
+   */
   Condition?: Record<string, Record<string, string | string[]>>;
+
+  /**
+   * AWS principals that the policy applies to
+   */
   Principal?: Record<string, string | string[]>;
+
+  /**
+   * AWS principals that the policy explicitly does not apply to
+   */
   NotPrincipal?: Record<string, string | string[]>;
+
+  /**
+   * Actions that are explicitly not included in this statement
+   */
   NotAction?: string | string[];
+
+  /**
+   * Resources that are explicitly not included in this statement
+   */
   NotResource?: string | string[];
 }
 
+/**
+ * An IAM policy document containing one or more statements
+ */
 export interface PolicyDocument {
+  /**
+   * Policy language version (must be "2012-10-17")
+   */
   Version: "2012-10-17";
+
+  /**
+   * List of policy statements
+   */
   Statement: PolicyStatement[];
 }
 
-// Policy resource
+/**
+ * Properties for creating or updating an IAM policy
+ */
 export interface PolicyProps {
+  /**
+   * Name of the policy
+   */
   policyName: string;
+
+  /**
+   * Policy document defining the permissions
+   */
   document: PolicyDocument;
+
+  /**
+   * Optional description of the policy's purpose
+   */
   description?: string;
+
+  /**
+   * Optional path prefix for the policy
+   */
   path?: string;
+
+  /**
+   * Optional resource tags
+   */
   tags?: Record<string, string>;
 }
 
+/**
+ * Output returned after IAM policy creation/update
+ */
 export interface Policy extends Resource<"iam::Policy">, PolicyProps {
+  /**
+   * ARN of the policy
+   */
   arn: string;
+
+  /**
+   * ID of the default policy version
+   */
   defaultVersionId: string;
+
+  /**
+   * Number of entities the policy is attached to
+   */
   attachmentCount: number;
+
+  /**
+   * When the policy was created
+   */
   createDate: Date;
+
+  /**
+   * When the policy was last updated
+   */
   updateDate: Date;
+
+  /**
+   * Whether the policy can be attached to IAM users/roles
+   */
   isAttachable: boolean;
 }
 
+/**
+ * AWS IAM Policy Resource
+ *
+ * Creates and manages IAM policies that define permissions for AWS services and resources.
+ * Supports automatic versioning and updates when policy content changes.
+ *
+ * @example
+ * // Create a basic S3 bucket access policy
+ * const s3Policy = await Policy("bucket-access", {
+ *   policyName: "s3-bucket-access",
+ *   document: {
+ *     Version: "2012-10-17",
+ *     Statement: [{
+ *       Effect: "Allow",
+ *       Action: [
+ *         "s3:GetObject",
+ *         "s3:PutObject"
+ *       ],
+ *       Resource: `${bucket.arn}/*`
+ *     }]
+ *   }
+ * });
+ *
+ * @example
+ * // Create a policy with multiple statements and conditions
+ * const apiPolicy = await Policy("api-access", {
+ *   policyName: "api-gateway-access",
+ *   document: {
+ *     Version: "2012-10-17",
+ *     Statement: [
+ *       {
+ *         Sid: "InvokeAPI",
+ *         Effect: "Allow",
+ *         Action: "execute-api:Invoke",
+ *         Resource: `${api.executionArn}/*`,
+ *         Condition: {
+ *           StringEquals: {
+ *             "aws:SourceVpc": vpc.id
+ *           }
+ *         }
+ *       },
+ *       {
+ *         Sid: "ReadLogs",
+ *         Effect: "Allow",
+ *         Action: [
+ *           "logs:GetLogEvents",
+ *           "logs:FilterLogEvents"
+ *         ],
+ *         Resource: `${api.logGroupArn}:*`
+ *       }
+ *     ]
+ *   },
+ *   description: "Allows invoking API Gateway endpoints and reading logs",
+ *   tags: {
+ *     Service: "API Gateway",
+ *     Environment: "production"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a policy that denies access based on tags
+ * const denyPolicy = await Policy("deny-production", {
+ *   policyName: "deny-production-access",
+ *   document: {
+ *     Version: "2012-10-17",
+ *     Statement: [{
+ *       Effect: "Deny",
+ *       Action: "*",
+ *       Resource: "*",
+ *       Condition: {
+ *         StringEquals: {
+ *           "aws:ResourceTag/Environment": "production"
+ *         }
+ *       }
+ *     }]
+ *   }
+ * });
+ */
 export const Policy = Resource(
   "iam::Policy",
   async function (

package/src/aws/queue.ts

@@ -8,6 +8,9 @@ import {
 import type { Context } from "../context";
 import { Resource } from "../resource";
 
+/**
+ * Properties for creating or updating an SQS queue
+ */
 export interface QueueProps {
   /**
    * Name of the queue
@@ -21,10 +24,34 @@ export interface QueueProps {
    */
   fifo?: boolean;
 
+  /**
+   * The length of time (in seconds) that a message received from a queue will be invisible to other receiving components
+   * Default: 30 seconds
+   */
   visibilityTimeout?: number;
+
+  /**
+   * The length of time (in seconds) for which Amazon SQS retains a message
+   * Default: 345600 seconds (4 days)
+   */
   messageRetentionPeriod?: number;
+
+  /**
+   * The limit of how many bytes a message can contain before Amazon SQS rejects it
+   * Default: 262144 bytes (256 KB)
+   */
   maximumMessageSize?: number;
+
+  /**
+   * The time in seconds that the delivery of all messages in the queue will be delayed
+   * Default: 0 seconds
+   */
   delaySeconds?: number;
+
+  /**
+   * The length of time (in seconds) for which a ReceiveMessage action waits for a message to arrive
+   * Default: 0 seconds
+   */
   receiveMessageWaitTimeSeconds?: number;
 
   /**
@@ -33,16 +60,78 @@ export interface QueueProps {
    */
   contentBasedDeduplication?: boolean;
 
+  /**
+   * Specifies whether message deduplication occurs at the message group or queue level
+   * Only applicable when fifo is true
+   */
   deduplicationScope?: "messageGroup" | "queue";
+
+  /**
+   * Specifies whether the FIFO queue throughput quota applies to the entire queue or per message group
+   * Only applicable when fifo is true
+   */
   fifoThroughputLimit?: "perQueue" | "perMessageGroupId";
+
+  /**
+   * Resource tags for the queue
+   */
   tags?: Record<string, string>;
 }
 
+/**
+ * Output returned after SQS queue creation/update
+ */
 export interface Queue extends Resource<"sqs::Queue">, QueueProps {
+  /**
+   * ARN of the queue
+   */
   arn: string;
+
+  /**
+   * URL of the queue
+   */
   url: string;
 }
 
+/**
+ * AWS SQS Queue Resource
+ *
+ * Creates and manages Amazon SQS queues with support for both standard and FIFO queues.
+ * Handles queue creation, attribute configuration, and automatic cleanup of deleted queues.
+ *
+ * @example
+ * // Create a standard queue with custom visibility timeout
+ * const standardQueue = await Queue("my-queue", {
+ *   queueName: "my-queue",
+ *   visibilityTimeout: 30,
+ *   tags: {
+ *     Environment: "production"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a FIFO queue with content-based deduplication
+ * const fifoQueue = await Queue("orders-queue", {
+ *   queueName: "orders-queue.fifo",
+ *   fifo: true,
+ *   contentBasedDeduplication: true,
+ *   visibilityTimeout: 30,
+ *   tags: {
+ *     Environment: "production"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a queue with custom message retention and size
+ * const customQueue = await Queue("large-messages", {
+ *   queueName: "large-messages",
+ *   messageRetentionPeriod: 345600,  // 4 days
+ *   maximumMessageSize: 262144,      // 256 KB
+ *   visibilityTimeout: 60,
+ *   delaySeconds: 5,
+ *   receiveMessageWaitTimeSeconds: 20
+ * });
+ */
 export const Queue = Resource(
   "sqs::Queue",
   async function (

package/src/aws/role.ts

@@ -20,28 +20,200 @@ import { Resource } from "../resource";
 import { ignore } from "../util/ignore";
 import type { PolicyDocument } from "./policy";
 
+/**
+ * Properties for creating or updating an IAM role
+ */
 export interface RoleProps {
+  /**
+   * Name of the IAM role
+   */
   roleName: string;
+
+  /**
+   * Policy that defines which entities can assume this role
+   */
   assumeRolePolicy: PolicyDocument;
+
+  /**
+   * Optional description of the role's purpose
+   */
   description?: string;
+
+  /**
+   * Optional path prefix for the role
+   */
   path?: string;
+
+  /**
+   * Maximum session duration in seconds when assumed
+   * Default: 3600 seconds (1 hour)
+   */
   maxSessionDuration?: number;
+
+  /**
+   * ARN of the policy used to set the permissions boundary
+   */
   permissionsBoundary?: string;
+
+  /**
+   * Inline policies to embed in the role
+   * Each policy must have a unique name and policy document
+   */
   policies?: Array<{
     policyName: string;
     policyDocument: PolicyDocument;
   }>;
+
+  /**
+   * List of managed policy ARNs to attach to the role
+   */
   managedPolicyArns?: string[];
+
+  /**
+   * Resource tags for the role
+   */
   tags?: Record<string, string>;
 }
 
+/**
+ * Output returned after IAM role creation/update
+ */
 export interface Role extends Resource<"iam::Role">, RoleProps {
+  /**
+   * ARN of the role
+   */
   arn: string;
-  uniqueId: string; // Unique identifier for the role
-  roleId: string; // The stable and unique string identifying the role
+
+  /**
+   * Unique identifier for the role
+   */
+  uniqueId: string;
+
+  /**
+   * The stable and unique string identifying the role
+   */
+  roleId: string;
+
+  /**
+   * When the role was created
+   */
   createDate: Date;
 }
 
+/**
+ * AWS IAM Role Resource
+ *
+ * Creates and manages IAM roles with support for inline policies, managed policies,
+ * and automatic cleanup of attached policies during deletion.
+ *
+ * @example
+ * // Create a basic Lambda execution role with inline policy
+ * const basicRole = await Role("lambda-role", {
+ *   roleName: "lambda-role",
+ *   assumeRolePolicy: {
+ *     Version: "2012-10-17",
+ *     Statement: [{
+ *       Effect: "Allow",
+ *       Principal: {
+ *         Service: "lambda.amazonaws.com"
+ *       },
+ *       Action: "sts:AssumeRole"
+ *     }]
+ *   },
+ *   description: "Basic Lambda execution role",
+ *   tags: {
+ *     Environment: "production"
+ *   },
+ *   policies: [{
+ *     policyName: "logs",
+ *     policyDocument: {
+ *       Version: "2012-10-17",
+ *       Statement: [{
+ *         Effect: "Allow",
+ *         Action: [
+ *           "logs:CreateLogGroup",
+ *           "logs:CreateLogStream",
+ *           "logs:PutLogEvents"
+ *         ],
+ *         Resource: "*"
+ *       }]
+ *     }
+ *   }]
+ * });
+ *
+ * @example
+ * // Create a role with AWS managed policies
+ * const managedRole = await Role("readonly-role", {
+ *   roleName: "readonly-role",
+ *   assumeRolePolicy: {
+ *     Version: "2012-10-17",
+ *     Statement: [{
+ *       Effect: "Allow",
+ *       Principal: {
+ *         Service: "lambda.amazonaws.com"
+ *       },
+ *       Action: "sts:AssumeRole"
+ *     }]
+ *   },
+ *   description: "Role with managed policies",
+ *   managedPolicyArns: [
+ *     "arn:aws:iam::aws:policy/ReadOnlyAccess"
+ *   ],
+ *   tags: {
+ *     Environment: "production"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a role with multiple inline policies and custom session duration
+ * const customRole = await Role("custom-role", {
+ *   roleName: "custom-role",
+ *   assumeRolePolicy: {
+ *     Version: "2012-10-17",
+ *     Statement: [{
+ *       Effect: "Allow",
+ *       Principal: {
+ *         Service: "lambda.amazonaws.com"
+ *       },
+ *       Action: "sts:AssumeRole"
+ *     }]
+ *   },
+ *   description: "Role with multiple policies",
+ *   maxSessionDuration: 7200,
+ *   policies: [
+ *     {
+ *       policyName: "logs",
+ *       policyDocument: {
+ *         Version: "2012-10-17",
+ *         Statement: [{
+ *           Effect: "Allow",
+ *           Action: [
+ *             "logs:CreateLogGroup",
+ *             "logs:CreateLogStream",
+ *             "logs:PutLogEvents"
+ *           ],
+ *           Resource: "*"
+ *         }]
+ *       }
+ *     },
+ *     {
+ *       policyName: "s3",
+ *       policyDocument: {
+ *         Version: "2012-10-17",
+ *         Statement: [{
+ *           Effect: "Allow",
+ *           Action: "s3:ListBucket",
+ *           Resource: "*"
+ *         }]
+ *       }
+ *     }
+ *   ],
+ *   tags: {
+ *     Environment: "production",
+ *     Updated: "true"
+ *   }
+ * });
+ */
 export const Role = Resource(
   "iam::Role",
   async function (

package/src/aws/ses.ts

@@ -29,46 +29,56 @@ import { ignore } from "../util/ignore";
 export interface SESProps {
   /**
    * Name of the configuration set
+   * Used to group email sending and tracking settings
    */
   configurationSetName?: string;
 
   /**
    * Email identity to verify (email address or domain)
+   * For domains, use the format "example.com"
+   * For email addresses, use the format "user@example.com"
    */
   emailIdentity?: string;
 
   /**
    * Whether to enable DKIM signing for the email identity
+   * DKIM helps prevent email spoofing by verifying sender authenticity
    */
   enableDkim?: boolean;
 
   /**
    * Sending options for the configuration set
+   * Controls whether email sending is enabled and related settings
    */
   sendingOptions?: SendingOptions;
 
   /**
    * Reputation options for the configuration set
+   * Controls reputation tracking and metrics collection
    */
   reputationOptions?: ReputationOptions;
 
   /**
    * Tracking options for the configuration set
+   * Controls open and click tracking with optional custom domains
    */
   trackingOptions?: TrackingOptions;
 
   /**
    * Suppression options for the configuration set
+   * Controls how bounces and complaints are handled
    */
   suppressionOptions?: SuppressionOptions;
 
   /**
    * Delivery options for the configuration set
+   * Controls TLS settings and sending pool configuration
    */
   deliveryOptions?: DeliveryOptions;
 
   /**
    * Tags to apply to the SES resources
+   * Key-value pairs for resource organization
    */
   tags?: Record<string, string>;
 }
@@ -79,27 +89,72 @@ export interface SESProps {
 export interface SES extends Resource<"aws::SES">, SESProps {
   /**
    * ARN of the configuration set if created
+   * Format: arn:aws:ses:region:account-id:configuration-set/name
    */
   configurationSetArn?: string;
 
   /**
    * Email identity verification status if an identity was created
+   * Can be "PENDING" or "VERIFIED"
    */
   emailIdentityVerificationStatus?: string;
 
   /**
    * DKIM verification status if DKIM was enabled
+   * Can be "PENDING", "SUCCESS", "FAILED", "TEMPORARY_FAILURE", or "NOT_STARTED"
    */
   dkimVerificationStatus?: string;
 
   /**
    * Email identity ARN if an identity was created
+   * Format: arn:aws:ses:region:account-id:identity/name
    */
   emailIdentityArn?: string;
 }
 
 /**
- * AWS SES resource for creating and configuring Simple Email Service
+ * AWS SES Resource
+ *
+ * Creates and manages Amazon Simple Email Service (SES) configuration sets and email identities.
+ * Supports email sending configuration, DKIM signing, and identity verification.
+ *
+ * @example
+ * // Create a configuration set with sending options
+ * const configSet = await SES("email-config", {
+ *   configurationSetName: "my-email-config",
+ *   sendingOptions: {
+ *     SendingEnabled: true
+ *   },
+ *   tags: {
+ *     Environment: "production",
+ *     Project: "notifications"
+ *   }
+ * });
+ *
+ * @example
+ * // Create and verify a domain identity with DKIM
+ * const domainIdentity = await SES("domain-identity", {
+ *   emailIdentity: "example.com",
+ *   enableDkim: true,
+ *   tags: {
+ *     Environment: "production",
+ *     Project: "transactional-emails"
+ *   }
+ * });
+ *
+ * @example
+ * // Update configuration set sending options
+ * const updatedConfig = await SES("email-config", {
+ *   configurationSetName: "my-email-config",
+ *   sendingOptions: {
+ *     SendingEnabled: false
+ *   },
+ *   tags: {
+ *     Environment: "production",
+ *     Project: "notifications",
+ *     Updated: "true"
+ *   }
+ * });
  */
 export const SES = Resource(
   "aws::SES",