@ts-cloud/core 0.2.3 → 0.2.5

package/dist/modules/queue.d.ts

@@ -0,0 +1,411 @@
+import type { EventBridgeRule, SQSQueue } from '@ts-cloud/aws-types';
+import type { EnvironmentType } from '../types';
+export interface QueueOptions {
+    slug: string;
+    environment: EnvironmentType;
+    name?: string;
+    delaySeconds?: number;
+    visibilityTimeout?: number;
+    messageRetentionPeriod?: number;
+    maxMessageSize?: number;
+    receiveMessageWaitTime?: number;
+    fifo?: boolean;
+    contentBasedDeduplication?: boolean;
+    encrypted?: boolean;
+    kmsKeyId?: string;
+}
+export interface DeadLetterQueueOptions {
+    slug: string;
+    environment: EnvironmentType;
+    maxReceiveCount?: number;
+}
+export interface ScheduleOptions {
+    slug: string;
+    environment: EnvironmentType;
+    name?: string;
+    description?: string;
+    enabled?: boolean;
+}
+export interface EcsScheduleOptions extends ScheduleOptions {
+    taskDefinitionArn: string;
+    clusterArn: string;
+    subnets: string[];
+    securityGroups?: string[];
+    assignPublicIp?: boolean;
+    taskCount?: number;
+    containerOverrides?: Array<{
+        name: string;
+        environment?: Array<{
+            name: string;
+            value: string;
+        }>;
+        command?: string[];
+    }>;
+}
+export interface LambdaScheduleOptions extends ScheduleOptions {
+    functionArn: string;
+    input?: Record<string, unknown>;
+}
+export interface SqsTargetOptions extends ScheduleOptions {
+    queueArn: string;
+    messageGroupId?: string;
+}
+/**
+ * Queue & Scheduling Module - EventBridge + SQS
+ * Provides clean API for creating queues, cron jobs, and scheduled tasks
+ */
+export declare class Queue {
+    /**
+     * Create an SQS queue
+     */
+    static createQueue(options: QueueOptions): {
+        queue: SQSQueue;
+        logicalId: string;
+    };
+    /**
+     * Create a dead letter queue and attach it to a source queue
+     */
+    static createDeadLetterQueue(sourceQueueLogicalId: string, options: DeadLetterQueueOptions): {
+        deadLetterQueue: SQSQueue;
+        updatedSourceQueue: SQSQueue;
+        deadLetterLogicalId: string;
+    };
+    /**
+     * Create an EventBridge rule with a cron schedule
+     */
+    static createSchedule(cronExpression: string, options: ScheduleOptions): {
+        rule: EventBridgeRule;
+        logicalId: string;
+    };
+    /**
+     * Schedule an ECS Fargate task with cron
+     */
+    static scheduleEcsTask(cronExpression: string, roleArn: string, options: EcsScheduleOptions): {
+        rule: EventBridgeRule;
+        logicalId: string;
+    };
+    /**
+     * Schedule a Lambda function with cron
+     */
+    static scheduleLambda(cronExpression: string, options: LambdaScheduleOptions): {
+        rule: EventBridgeRule;
+        logicalId: string;
+    };
+    /**
+     * Schedule an SQS message with cron
+     */
+    static scheduleSqsMessage(cronExpression: string, options: SqsTargetOptions): {
+        rule: EventBridgeRule;
+        logicalId: string;
+    };
+    /**
+     * Add a target to an existing EventBridge rule
+     */
+    static addTarget(rule: EventBridgeRule, target: {
+        id: string;
+        arn: string;
+        roleArn?: string;
+        input?: Record<string, unknown>;
+    }): EventBridgeRule;
+    /**
+     * Helper: Convert cron expression to rate expression
+     * EventBridge supports both cron() and rate() expressions
+     */
+    static toCronExpression(expression: string): string;
+    /**
+     * Helper: Create rate expression
+     */
+    static rateExpression(value: number, unit: 'minute' | 'minutes' | 'hour' | 'hours' | 'day' | 'days'): string;
+    /**
+     * Common cron expressions
+     */
+    static readonly CronExpressions: {
+        readonly EveryMinute: "cron(* * * * ? *)";
+        readonly Every5Minutes: "cron(*/5 * * * ? *)";
+        readonly Every15Minutes: "cron(*/15 * * * ? *)";
+        readonly Every30Minutes: "cron(*/30 * * * ? *)";
+        readonly Hourly: "cron(0 * * * ? *)";
+        readonly Daily: "cron(0 0 * * ? *)";
+        readonly DailyAt9AM: "cron(0 9 * * ? *)";
+        readonly DailyAtMidnight: "cron(0 0 * * ? *)";
+        readonly Weekly: "cron(0 0 ? * SUN *)";
+        readonly Monthly: "cron(0 0 1 * ? *)";
+    };
+    /**
+     * Common rate expressions
+     */
+    static readonly RateExpressions: {
+        readonly Every1Minute: "rate(1 minute)";
+        readonly Every5Minutes: "rate(5 minutes)";
+        readonly Every10Minutes: "rate(10 minutes)";
+        readonly Every15Minutes: "rate(15 minutes)";
+        readonly Every30Minutes: "rate(30 minutes)";
+        readonly Every1Hour: "rate(1 hour)";
+        readonly Every6Hours: "rate(6 hours)";
+        readonly Every12Hours: "rate(12 hours)";
+        readonly Every1Day: "rate(1 day)";
+    };
+    /**
+     * Convert a human-readable rate string to a cron/rate expression
+     * Supports formats like: "every 5 minutes", "every hour", "daily at 9am", etc.
+     */
+    static rateStringToExpression(rateString: string): string;
+    /**
+     * Job configuration interface
+     */
+    static readonly JobConfig: {
+        /**
+         * Create job configuration with retry settings
+         */
+        create: (options: {
+            name: string;
+            handler: string;
+            retries?: number;
+            backoff?: "linear" | "exponential" | "fixed";
+            backoffDelay?: number;
+            maxDelay?: number;
+            timeout?: number;
+            jitter?: boolean;
+        }) => JobConfiguration;
+        /**
+         * Calculate delay for a given retry attempt
+         */
+        calculateDelay: (attempt: number, config: Pick<JobConfiguration, "backoff" | "backoffDelay" | "maxDelay" | "jitter">) => number;
+        /**
+         * Common job configurations
+         */
+        presets: {
+            /**
+             * Fast retry for transient failures
+             */
+            fastRetry: {
+                retries: number;
+                backoff: "exponential";
+                backoffDelay: number;
+                maxDelay: number;
+                jitter: boolean;
+            };
+            /**
+             * Standard job with moderate retries
+             */
+            standard: {
+                retries: number;
+                backoff: "exponential";
+                backoffDelay: number;
+                maxDelay: number;
+                jitter: boolean;
+            };
+            /**
+             * Long-running job with extended timeouts
+             */
+            longRunning: {
+                retries: number;
+                backoff: "exponential";
+                backoffDelay: number;
+                maxDelay: number;
+                timeout: number;
+                jitter: boolean;
+            };
+            /**
+             * Critical job with many retries
+             */
+            critical: {
+                retries: number;
+                backoff: "exponential";
+                backoffDelay: number;
+                maxDelay: number;
+                jitter: boolean;
+            };
+            /**
+             * No retry (fire and forget)
+             */
+            noRetry: {
+                retries: number;
+                backoff: "fixed";
+                backoffDelay: number;
+                maxDelay: number;
+                jitter: boolean;
+            };
+        };
+    };
+    /**
+     * Create ECS container override for job execution
+     */
+    static createJobContainerOverride(options: {
+        containerName: string;
+        jobClass: string;
+        jobData?: Record<string, unknown>;
+        environment?: Record<string, string>;
+    }): {
+        name: string;
+        command: string[];
+        environment: Array<{
+            name: string;
+            value: string;
+        }>;
+    };
+    /**
+     * Generate scheduled job resources
+     */
+    static createScheduledJob(options: {
+        slug: string;
+        environment: EnvironmentType;
+        schedule: string;
+        jobClass: string;
+        jobData?: Record<string, unknown>;
+        taskDefinitionArn: string;
+        clusterArn: string;
+        subnets: string[];
+        securityGroups?: string[];
+        roleArn: string;
+        containerName?: string;
+    }): {
+        rule: EventBridgeRule;
+        logicalId: string;
+    };
+    /**
+     * Queue presets for common use cases
+     */
+    static readonly QueuePresets: {
+        /**
+         * High-throughput queue with short visibility
+         */
+        highThroughput: (slug: string, environment: EnvironmentType) => {
+            queue: SQSQueue;
+            logicalId: string;
+        };
+        /**
+         * Long-running job queue
+         */
+        longRunning: (slug: string, environment: EnvironmentType) => {
+            queue: SQSQueue;
+            logicalId: string;
+        };
+        /**
+         * FIFO queue for ordered processing
+         */
+        fifo: (slug: string, environment: EnvironmentType) => {
+            queue: SQSQueue;
+            logicalId: string;
+        };
+        /**
+         * Delayed queue for scheduled messages
+         */
+        delayed: (slug: string, environment: EnvironmentType, delaySeconds?: number) => {
+            queue: SQSQueue;
+            logicalId: string;
+        };
+    };
+}
+/**
+ * Job configuration type
+ */
+export interface JobConfiguration {
+    name: string;
+    handler: string;
+    retries: number;
+    backoff: 'linear' | 'exponential' | 'fixed';
+    backoffDelay: number;
+    maxDelay: number;
+    timeout: number;
+    jitter: boolean;
+}
+/**
+ * Discovered job definition from file scanning
+ */
+export interface DiscoveredJob {
+    name: string;
+    path: string;
+    schedule?: string;
+    handler: string;
+    enabled: boolean;
+    retries?: number;
+    backoff?: 'linear' | 'exponential' | 'fixed';
+    timeout?: number;
+    description?: string;
+}
+/**
+ * Discovered action definition from file scanning
+ */
+export interface DiscoveredAction {
+    name: string;
+    path: string;
+    handler: string;
+    description?: string;
+}
+/**
+ * Dynamic job and action loader for Stacks framework integration
+ */
+export declare class JobLoader {
+    /**
+     * Discover jobs from app/Jobs directory
+     * Scans *.ts files and extracts job metadata from exports
+     */
+    static discoverJobs(options: {
+        projectRoot: string;
+        jobsPath?: string;
+    }): Promise<DiscoveredJob[]>;
+    /**
+     * Parse job metadata from file content
+     * Looks for exported schedule, handle function, and config
+     */
+    static parseJobMetadata(content: string, name: string, path: string): DiscoveredJob | null;
+    /**
+     * Discover actions from app/Actions directory
+     * Scans *.ts files and extracts action metadata
+     */
+    static discoverActions(options: {
+        projectRoot: string;
+        actionsPath?: string;
+    }): Promise<DiscoveredAction[]>;
+    /**
+     * Parse action metadata from file content
+     */
+    static parseActionMetadata(content: string, name: string, path: string): DiscoveredAction | null;
+    /**
+     * Generate scheduled job resources from discovered jobs
+     */
+    static generateScheduledJobResources(options: {
+        slug: string;
+        environment: EnvironmentType;
+        jobs: DiscoveredJob[];
+        taskDefinitionArn: string;
+        clusterArn: string;
+        subnets: string[];
+        securityGroups?: string[];
+        roleArn: string;
+        containerName?: string;
+    }): {
+        rules: Record<string, EventBridgeRule>;
+        count: number;
+    };
+    /**
+     * Generate a job runner script for ECS tasks
+     */
+    static generateJobRunnerScript(): string;
+    /**
+     * Generate job manifest file for CI/CD deployments
+     */
+    static generateJobManifest(options: {
+        projectRoot: string;
+        jobsPath?: string;
+    }): Promise<{
+        jobs: DiscoveredJob[];
+        scheduledCount: number;
+        totalCount: number;
+    }>;
+}
+/**
+ * Stacks framework job/action integration helpers
+ */
+export declare const StacksIntegration: {
+    loadJobs: typeof JobLoader.discoverJobs;
+    loadActions: typeof JobLoader.discoverActions;
+    generateScheduledJobs: typeof JobLoader.generateScheduledJobResources;
+    generateRunner: typeof JobLoader.generateJobRunnerScript;
+    paths: {
+        jobs: string;
+        actions: string;
+        runner: string;
+    };
+};

package/dist/modules/redirects.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Redirects Module - URL Redirect Management
+ * Provides clean API for creating domain and path-based redirects
+ */
+import type { CloudFrontFunction, S3Bucket, S3BucketPolicy } from '@ts-cloud/aws-types';
+import type { EnvironmentType } from '../types';
+export interface RedirectRule {
+    source: string;
+    target: string;
+    statusCode?: 301 | 302 | 307 | 308;
+    preserveQueryString?: boolean;
+}
+export interface DomainRedirectOptions {
+    slug: string;
+    environment: EnvironmentType;
+    sourceDomain: string;
+    targetDomain: string;
+    protocol?: 'http' | 'https';
+    preservePath?: boolean;
+}
+export interface PathRedirectOptions {
+    slug: string;
+    environment: EnvironmentType;
+    rules: RedirectRule[];
+}
+/**
+ * Redirects Module - Domain and Path-based Redirects
+ * Provides clean API for URL redirects using S3 and CloudFront Functions
+ */
+export declare class Redirects {
+    /**
+     * Create an S3 bucket configured for domain redirect
+     * Redirects all requests from one domain to another
+     */
+    static createDomainRedirectBucket(options: DomainRedirectOptions): {
+        bucket: S3Bucket;
+        bucketPolicy: S3BucketPolicy;
+        logicalId: string;
+        policyLogicalId: string;
+    };
+    /**
+     * Create a CloudFront Function for path-based redirects
+     */
+    static createPathRedirectFunction(options: PathRedirectOptions): {
+        function: CloudFrontFunction;
+        logicalId: string;
+        functionCode: string;
+    };
+    /**
+     * Generate CloudFront Function code for path redirects
+     */
+    static generateRedirectFunctionCode(rules: RedirectRule[]): string;
+    /**
+     * Create common redirect patterns
+     */
+    static readonly CommonRedirects: {
+        /**
+         * www to non-www redirect
+         */
+        wwwToApex: (domain: string, protocol?: "http" | "https") => DomainRedirectOptions;
+        /**
+         * non-www to www redirect
+         */
+        apexToWww: (domain: string, protocol?: "http" | "https") => DomainRedirectOptions;
+        /**
+         * HTTP to HTTPS redirect (handled at CloudFront/ALB level typically)
+         */
+        httpToHttps: (path?: string) => RedirectRule;
+        /**
+         * Trailing slash normalization (add trailing slash)
+         */
+        addTrailingSlash: (paths: string[]) => RedirectRule[];
+        /**
+         * Trailing slash normalization (remove trailing slash)
+         */
+        removeTrailingSlash: (paths: string[]) => RedirectRule[];
+    };
+    /**
+     * Create redirect rules for common URL patterns
+     */
+    static readonly Patterns: {
+        /**
+         * Old blog URL pattern to new pattern
+         * /blog/2023/01/my-post -> /blog/my-post
+         */
+        flattenBlogUrls: (posts: Array<{
+            oldPath: string;
+            newPath: string;
+        }>) => RedirectRule[];
+        /**
+         * Category URL changes
+         */
+        categoryRename: (oldCategory: string, newCategory: string) => RedirectRule[];
+        /**
+         * Product page URL pattern
+         */
+        productSlugChange: (products: Array<{
+            oldSlug: string;
+            newSlug: string;
+        }>) => RedirectRule[];
+        /**
+         * Deprecated API version redirects
+         */
+        apiVersionRedirect: (oldVersion: string, newVersion: string, endpoints: string[]) => RedirectRule[];
+        /**
+         * Gone (410) redirects for deleted content
+         */
+        gonePages: (paths: string[]) => RedirectRule[];
+    };
+    /**
+     * Create a complete redirect setup with multiple rules
+     */
+    static createRedirectSetup(options: {
+        slug: string;
+        environment: EnvironmentType;
+        domainRedirects?: DomainRedirectOptions[];
+        pathRedirects?: RedirectRule[];
+    }): {
+        resources: Record<string, any>;
+        outputs: {
+            domainRedirectBuckets: string[];
+            pathRedirectFunctionLogicalId: string | null;
+        };
+    };
+    /**
+     * Generate redirect rules from a simple mapping object
+     */
+    static fromMapping(mapping: Record<string, string>, options?: {
+        statusCode?: 301 | 302 | 307 | 308;
+        preserveQueryString?: boolean;
+    }): RedirectRule[];
+    /**
+     * Validate redirect rules for common issues
+     */
+    static validateRules(rules: RedirectRule[]): {
+        valid: boolean;
+        errors: string[];
+        warnings: string[];
+    };
+}