alchemy 0.2.2 → 0.2.4

package/lib/aws/policy.js

@@ -1,5 +1,83 @@
 import { CreatePolicyCommand, CreatePolicyVersionCommand, DeletePolicyCommand, DeletePolicyVersionCommand, GetPolicyCommand, GetPolicyVersionCommand, IAMClient, ListPolicyVersionsCommand, NoSuchEntityException, } from "@aws-sdk/client-iam";
 import { Resource } from "../resource";
+/**
+ * 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 (id, props) {
     const client = new IAMClient({});
     const policyArn = `arn:aws:iam::${process.env.AWS_ACCOUNT_ID}:policy${props.path || "/"}${props.policyName}`;

package/lib/aws/queue.d.ts

@@ -1,5 +1,8 @@
 import type { Context } from "../context";
 import { Resource } from "../resource";
+/**
+ * Properties for creating or updating an SQS queue
+ */
 export interface QueueProps {
     /**
      * Name of the queue
@@ -11,22 +14,101 @@ export interface QueueProps {
      * If true, the queueName must end with .fifo suffix
      */
     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;
     /**
      * Enables content-based deduplication for FIFO queues.
      * Only applicable when fifo is true.
      */
     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;
 }
-export declare const Queue: ((this: Context<Queue>, id: string, props: QueueProps) => Promise<Queue>) | (((this: any, id: string, props: QueueProps) => never) & (new (_: never) => never));
+/**
+ * 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 declare const Queue: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<Queue>, id: string, props: QueueProps) => Promise<Queue>);

package/lib/aws/queue.js

@@ -1,5 +1,44 @@
 import { CreateQueueCommand, DeleteQueueCommand, GetQueueAttributesCommand, GetQueueUrlCommand, SQSClient, } from "@aws-sdk/client-sqs";
 import { Resource } from "../resource";
+/**
+ * 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 (id, props) {
     const client = new SQSClient({});
     // Don't automatically add .fifo suffix - user must include it in queueName

package/lib/aws/role.d.ts

@@ -1,24 +1,185 @@
 import type { Context } from "../context";
 import { Resource } from "../resource";
 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;
+    /**
+     * Unique identifier for the role
+     */
     uniqueId: string;
+    /**
+     * The stable and unique string identifying the role
+     */
     roleId: string;
+    /**
+     * When the role was created
+     */
     createDate: Date;
 }
-export declare const Role: ((this: Context<Role>, id: string, props: RoleProps) => Promise<Role>) | (((this: any, id: string, props: RoleProps) => never) & (new (_: never) => never));
+/**
+ * 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 declare const Role: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<Role>, id: string, props: RoleProps) => Promise<Role>);

package/lib/aws/role.js

@@ -1,6 +1,120 @@
 import { AttachRolePolicyCommand, CreateRoleCommand, DeleteRoleCommand, DeleteRolePolicyCommand, DetachRolePolicyCommand, EntityAlreadyExistsException, GetRoleCommand, IAMClient, ListAttachedRolePoliciesCommand, NoSuchEntityException, PutRolePolicyCommand, TagRoleCommand, UpdateAssumeRolePolicyCommand, UpdateRoleCommand, } from "@aws-sdk/client-iam";
 import { Resource } from "../resource";
 import { ignore } from "../util/ignore";
+/**
+ * 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 (id, props) {
     const client = new IAMClient({});
     if (this.phase === "delete") {

package/lib/aws/ses.d.ts

@@ -7,38 +7,48 @@ import { Resource } from "../resource";
 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>;
 }
@@ -48,22 +58,67 @@ 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 declare const SES: ((this: Context<SES>, id: string, props: SESProps) => Promise<SES>) | (((this: any, id: string, props: SESProps) => never) & (new (_: never) => never));
+export declare const SES: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<SES>, id: string, props: SESProps) => Promise<SES>);