@stacksjs/ts-cloud 0.2.2 → 0.2.5

package/dist/config.d.ts

@@ -0,0 +1,5 @@
+import type { CloudOptions } from '@ts-cloud/core';
+export declare const defaultConfig: CloudOptions;
+export declare function getConfig(): Promise<CloudOptions>;
+export declare const loadCloudConfig: () => Promise<CloudOptions>;
+export declare const config: CloudOptions;

package/dist/deploy/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Deployment Modules
+ * High-level deployment functions for common AWS architectures
+ */
+export * from './static-site';
+export * from './static-site-external-dns';

package/dist/deploy/static-site-external-dns.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Static Site Deployment with External DNS Provider Support
+ * Deploys static sites to AWS (S3 + CloudFront + ACM) with DNS managed by external providers (Porkbun, GoDaddy, etc.)
+ */
+import type { DnsProviderConfig } from '../dns/types';
+export interface ExternalDnsStaticSiteConfig {
+    /** Site name used for resource naming */
+    siteName: string;
+    /** AWS region for S3 bucket */
+    region?: string;
+    /** Custom domain (e.g., bunpress.org) */
+    domain: string;
+    /** S3 bucket name (auto-generated if not provided) */
+    bucket?: string;
+    /** ACM certificate ARN (auto-created if not provided) */
+    certificateArn?: string;
+    /** CloudFormation stack name */
+    stackName?: string;
+    /** Default root object */
+    defaultRootObject?: string;
+    /** Error document */
+    errorDocument?: string;
+    /** Cache control for assets */
+    cacheControl?: string;
+    /** Tags to apply to resources */
+    tags?: Record<string, string>;
+    /** DNS provider configuration */
+    dnsProvider: DnsProviderConfig;
+    /** Skip DNS verification and record creation (use when DNS is already configured) */
+    skipDnsVerification?: boolean;
+    /** When true, serves raw files without URL rewriting (for curl | bash install scripts) */
+    passthroughUrls?: boolean;
+}
+export interface ExternalDnsDeployResult {
+    success: boolean;
+    stackId?: string;
+    stackName: string;
+    bucket: string;
+    distributionId?: string;
+    distributionDomain?: string;
+    domain?: string;
+    certificateArn?: string;
+    message: string;
+    filesUploaded?: number;
+    filesSkipped?: number;
+}
+/**
+ * Generate CloudFormation template for static site infrastructure (without Route53)
+ */
+export declare function generateExternalDnsStaticSiteTemplate(config: {
+    bucketName: string;
+    domain?: string;
+    aliases?: string[];
+    certificateArn?: string;
+    defaultRootObject?: string;
+    errorDocument?: string;
+    passthroughUrls?: boolean;
+}): object;
+/**
+ * Deploy a static site to AWS with external DNS provider
+ */
+export declare function deployStaticSiteWithExternalDns(config: ExternalDnsStaticSiteConfig): Promise<ExternalDnsDeployResult>;
+/**
+ * Full deployment with external DNS: infrastructure + files + cache invalidation
+ */
+export declare function deployStaticSiteWithExternalDnsFull(config: ExternalDnsStaticSiteConfig & {
+    sourceDir: string;
+    cleanBucket?: boolean;
+    onProgress?: (stage: string, detail?: string) => void;
+}): Promise<ExternalDnsDeployResult>;

package/dist/deploy/static-site.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Static Site Deployment Module
+ * Deploys static sites to AWS using CloudFormation (S3 + CloudFront + Route53/External DNS + ACM)
+ */
+import type { DnsProviderConfig } from '../dns/types';
+export interface StaticSiteConfig {
+    /** Site name used for resource naming */
+    siteName: string;
+    /** AWS region for S3 bucket */
+    region?: string;
+    /** Custom domain (e.g., docs.example.com) */
+    domain?: string;
+    /** Subdomain part (e.g., 'docs') - used with baseDomain */
+    subdomain?: string;
+    /** Base domain (e.g., 'example.com') - must have Route53 hosted zone */
+    baseDomain?: string;
+    /** S3 bucket name (auto-generated if not provided) */
+    bucket?: string;
+    /** Route53 hosted zone ID (auto-detected if not provided) */
+    hostedZoneId?: string;
+    /** ACM certificate ARN (auto-created if not provided) */
+    certificateArn?: string;
+    /** CloudFormation stack name */
+    stackName?: string;
+    /** Default root object */
+    defaultRootObject?: string;
+    /** Error document */
+    errorDocument?: string;
+    /** Cache control for assets */
+    cacheControl?: string;
+    /** Tags to apply to resources */
+    tags?: Record<string, string>;
+    /**
+     * External DNS provider configuration (optional)
+     * When provided, DNS records will be managed via the specified provider (Porkbun, GoDaddy, etc.)
+     * instead of Route53. Useful when your domain is registered outside AWS.
+     */
+    dnsProvider?: DnsProviderConfig;
+}
+export interface DeployResult {
+    success: boolean;
+    stackId?: string;
+    stackName: string;
+    bucket: string;
+    distributionId?: string;
+    distributionDomain?: string;
+    domain?: string;
+    certificateArn?: string;
+    message: string;
+}
+export interface UploadOptions {
+    /** Local directory containing built files */
+    sourceDir: string;
+    /** S3 bucket name */
+    bucket: string;
+    /** AWS region */
+    region: string;
+    /** Cache control header */
+    cacheControl?: string;
+    /** Callback for progress updates */
+    onProgress?: (uploaded: number, total: number, file: string) => void;
+}
+/**
+ * Generate CloudFormation template for static site infrastructure
+ */
+export declare function generateStaticSiteTemplate(config: {
+    bucketName: string;
+    domain?: string;
+    certificateArn?: string;
+    hostedZoneId?: string;
+    defaultRootObject?: string;
+    errorDocument?: string;
+}): object;
+/**
+ * Deploy a static site to AWS
+ * Automatically routes to external DNS deployment when a non-Route53 dnsProvider is configured
+ */
+export declare function deployStaticSite(config: StaticSiteConfig): Promise<DeployResult>;
+/**
+ * Upload files to S3 bucket (only uploads changed files)
+ */
+export declare function uploadStaticFiles(options: UploadOptions): Promise<{
+    uploaded: number;
+    skipped: number;
+    errors: string[];
+}>;
+/**
+ * Invalidate CloudFront cache
+ */
+export declare function invalidateCache(distributionId: string): Promise<{
+    invalidationId: string;
+}>;
+/**
+ * Delete static site infrastructure
+ */
+export declare function deleteStaticSite(stackName: string, region?: string): Promise<{
+    success: boolean;
+    message: string;
+}>;
+/**
+ * Full deployment: infrastructure + files + cache invalidation
+ */
+export declare function deployStaticSiteFull(config: StaticSiteConfig & {
+    sourceDir: string;
+    cleanBucket?: boolean;
+    onProgress?: (stage: string, detail?: string) => void;
+}): Promise<DeployResult & {
+    filesUploaded?: number;
+    filesSkipped?: number;
+}>;

package/dist/dns/cloudflare.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Cloudflare DNS Provider
+ * API documentation: https://developers.cloudflare.com/api/resources/dns/subresources/records/
+ */
+import type { CreateRecordResult, DeleteRecordResult, DnsProvider, DnsRecord, DnsRecordType, ListRecordsResult } from './types';
+export declare class CloudflareProvider implements DnsProvider {
+    readonly name = "cloudflare";
+    private apiToken;
+    private zoneCache;
+    constructor(apiToken: string);
+    /**
+     * Make an authenticated API request to Cloudflare
+     */
+    private request;
+    /**
+     * Get the root domain from a full domain name
+     * e.g., "api.example.com" -> "example.com"
+     */
+    private getRootDomain;
+    /**
+     * Get Zone ID for a domain (with caching)
+     */
+    private getZoneId;
+    /**
+     * Get the full record name
+     * Cloudflare stores records with full domain names
+     */
+    private getFullRecordName;
+    /**
+     * Convert DnsRecord to Cloudflare record format
+     */
+    private toCloudflareRecord;
+    /**
+     * Convert Cloudflare record to DnsRecordResult format
+     */
+    private fromCloudflareRecord;
+    createRecord(domain: string, record: DnsRecord): Promise<CreateRecordResult>;
+    upsertRecord(domain: string, record: DnsRecord): Promise<CreateRecordResult>;
+    deleteRecord(domain: string, record: DnsRecord): Promise<DeleteRecordResult>;
+    listRecords(domain: string, type?: DnsRecordType): Promise<ListRecordsResult>;
+    canManageDomain(domain: string): Promise<boolean>;
+    /**
+     * List all domains (zones) managed by this Cloudflare account
+     */
+    listDomains(): Promise<string[]>;
+    /**
+     * Get zone details (Cloudflare-specific)
+     */
+    getZoneDetails(domain: string): Promise<{
+        id: string;
+        name: string;
+        status: string;
+        nameServers: string[];
+        paused: boolean;
+    } | null>;
+    /**
+     * Purge cache for a domain (Cloudflare-specific)
+     */
+    purgeCache(domain: string, options?: {
+        purgeEverything?: boolean;
+        files?: string[];
+        tags?: string[];
+        hosts?: string[];
+    }): Promise<boolean>;
+    /**
+     * Get proxy status for a record (Cloudflare-specific)
+     * Returns whether a record is proxied through Cloudflare
+     */
+    getRecordProxyStatus(domain: string, record: DnsRecord): Promise<boolean | null>;
+    /**
+     * Update proxy status for a record (Cloudflare-specific)
+     */
+    setRecordProxyStatus(domain: string, record: DnsRecord, proxied: boolean): Promise<boolean>;
+}

package/dist/dns/godaddy.d.ts

@@ -0,0 +1,63 @@
+/**
+ * GoDaddy DNS Provider
+ * API documentation: https://developer.godaddy.com/doc/endpoint/domains
+ */
+import type { CreateRecordResult, DeleteRecordResult, DnsProvider, DnsRecord, DnsRecordType, ListRecordsResult } from './types';
+export declare class GoDaddyProvider implements DnsProvider {
+    readonly name = "godaddy";
+    private apiKey;
+    private apiSecret;
+    private baseUrl;
+    constructor(apiKey: string, apiSecret: string, environment?: 'production' | 'ote');
+    /**
+     * Make an authenticated API request to GoDaddy
+     */
+    private request;
+    /**
+     * Extract the subdomain from a full record name
+     * GoDaddy uses @ for root domain
+     */
+    private getSubdomain;
+    /**
+     * Get the root domain from a full domain name
+     */
+    private getRootDomain;
+    /**
+     * Convert DnsRecord to GoDaddy record format
+     */
+    private toGoDaddyRecord;
+    /**
+     * Convert GoDaddy record to DnsRecordResult format
+     */
+    private fromGoDaddyRecord;
+    createRecord(domain: string, record: DnsRecord): Promise<CreateRecordResult>;
+    upsertRecord(domain: string, record: DnsRecord): Promise<CreateRecordResult>;
+    deleteRecord(domain: string, record: DnsRecord): Promise<DeleteRecordResult>;
+    listRecords(domain: string, type?: DnsRecordType): Promise<ListRecordsResult>;
+    canManageDomain(domain: string): Promise<boolean>;
+    /**
+     * List all domains managed by this GoDaddy account
+     */
+    listDomains(): Promise<string[]>;
+    /**
+     * Get domain details (GoDaddy-specific)
+     */
+    getDomainDetails(domain: string): Promise<{
+        domain: string;
+        status: string;
+        nameServers?: string[];
+        expires?: string;
+    } | null>;
+    /**
+     * Update nameservers for a domain (GoDaddy-specific)
+     */
+    updateNameServers(domain: string, nameservers: string[]): Promise<boolean>;
+    /**
+     * Check domain availability (GoDaddy-specific)
+     */
+    checkDomainAvailability(domain: string): Promise<{
+        available: boolean;
+        price?: number;
+        currency?: string;
+    }>;
+}

package/dist/dns/index.d.ts

@@ -0,0 +1,67 @@
+/**
+ * DNS Provider Module
+ * Unified DNS management for Route53, Porkbun, and GoDaddy
+ */
+export * from './types';
+export { PorkbunProvider } from './porkbun';
+export { GoDaddyProvider } from './godaddy';
+export { CloudflareProvider } from './cloudflare';
+export { Route53Provider } from './route53-adapter';
+export { UnifiedDnsValidator, createPorkbunValidator, createGoDaddyValidator, createRoute53Validator, } from './validator';
+import type { DnsProvider, DnsProviderConfig } from './types';
+/**
+ * Create a DNS provider from configuration
+ */
+export declare function createDnsProvider(config: DnsProviderConfig): DnsProvider;
+/**
+ * Auto-detect DNS provider for a domain
+ * Tries each provider to see which one can manage the domain
+ */
+export declare function detectDnsProvider(domain: string, configs: DnsProviderConfig[]): Promise<DnsProvider | null>;
+/**
+ * DNS Provider factory with environment variable support
+ */
+export declare class DnsProviderFactory {
+    private providers;
+    private configs;
+    /**
+     * Add provider configuration
+     */
+    addConfig(config: DnsProviderConfig): this;
+    /**
+     * Add Route53 provider
+     */
+    addRoute53(region?: string, hostedZoneId?: string): this;
+    /**
+     * Add Porkbun provider
+     */
+    addPorkbun(apiKey: string, secretKey: string): this;
+    /**
+     * Add GoDaddy provider
+     */
+    addGoDaddy(apiKey: string, apiSecret: string, environment?: 'production' | 'ote'): this;
+    /**
+     * Add Cloudflare provider
+     */
+    addCloudflare(apiToken: string): this;
+    /**
+     * Load providers from environment variables
+     */
+    loadFromEnv(): this;
+    /**
+     * Get a provider by name
+     */
+    getProvider(name: 'route53' | 'porkbun' | 'godaddy' | 'cloudflare'): DnsProvider | null;
+    /**
+     * Auto-detect provider for a domain
+     */
+    getProviderForDomain(domain: string): Promise<DnsProvider | null>;
+    /**
+     * Get all configured providers
+     */
+    getAllProviders(): DnsProvider[];
+}
+/**
+ * Default factory instance (can be configured globally)
+ */
+export declare const dnsProviders: DnsProviderFactory;

package/dist/dns/porkbun.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Porkbun DNS Provider
+ * API documentation: https://porkbun.com/api/json/v3/documentation
+ */
+import type { CreateRecordResult, DeleteRecordResult, DnsProvider, DnsRecord, DnsRecordType, ListRecordsResult } from './types';
+export declare class PorkbunProvider implements DnsProvider {
+    readonly name = "porkbun";
+    private apiKey;
+    private secretKey;
+    constructor(apiKey: string, secretKey: string);
+    /**
+     * Make an authenticated API request to Porkbun
+     */
+    private request;
+    /**
+     * Extract the subdomain from a full record name
+     * e.g., "_acme-challenge.example.com" -> "_acme-challenge"
+     */
+    private getSubdomain;
+    /**
+     * Get the root domain from a full domain name
+     * e.g., "api.example.com" -> "example.com"
+     */
+    private getRootDomain;
+    createRecord(domain: string, record: DnsRecord): Promise<CreateRecordResult>;
+    upsertRecord(domain: string, record: DnsRecord): Promise<CreateRecordResult>;
+    deleteRecord(domain: string, record: DnsRecord): Promise<DeleteRecordResult>;
+    listRecords(domain: string, type?: DnsRecordType): Promise<ListRecordsResult>;
+    canManageDomain(domain: string): Promise<boolean>;
+    /**
+     * List all domains managed by this Porkbun account
+     * Uses the domain list API endpoint
+     */
+    listDomains(): Promise<string[]>;
+    /**
+     * Get nameservers for a domain (Porkbun-specific)
+     */
+    getNameServers(domain: string): Promise<string[]>;
+    /**
+     * Update nameservers for a domain (Porkbun-specific)
+     */
+    updateNameServers(domain: string, nameservers: string[]): Promise<boolean>;
+}

package/dist/dns/route53-adapter.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Route53 DNS Provider Adapter
+ * Wraps the existing Route53Client to implement the DnsProvider interface
+ */
+import { Route53Client } from '../aws/route53';
+import type { CreateRecordResult, DeleteRecordResult, DnsProvider, DnsRecord, DnsRecordType, ListRecordsResult } from './types';
+export declare class Route53Provider implements DnsProvider {
+    readonly name = "route53";
+    private client;
+    private hostedZoneCache;
+    private providedHostedZoneId?;
+    constructor(region?: string, hostedZoneId?: string);
+    /**
+     * Get the root domain from a full domain name
+     */
+    private getRootDomain;
+    /**
+     * Get the hosted zone ID for a domain
+     */
+    private getHostedZoneId;
+    /**
+     * Ensure domain name ends with a dot (Route53 requirement)
+     */
+    private normalizeName;
+    createRecord(domain: string, record: DnsRecord): Promise<CreateRecordResult>;
+    upsertRecord(domain: string, record: DnsRecord): Promise<CreateRecordResult>;
+    deleteRecord(domain: string, record: DnsRecord): Promise<DeleteRecordResult>;
+    listRecords(domain: string, type?: DnsRecordType): Promise<ListRecordsResult>;
+    canManageDomain(domain: string): Promise<boolean>;
+    /**
+     * List all domains (hosted zones) managed in Route53
+     */
+    listDomains(): Promise<string[]>;
+    /**
+     * Get the underlying Route53Client for advanced operations
+     */
+    getRoute53Client(): Route53Client;
+    /**
+     * Create an alias record (Route53-specific feature)
+     * Useful for CloudFront, ALB, etc.
+     */
+    createAliasRecord(params: {
+        domain: string;
+        name: string;
+        targetHostedZoneId: string;
+        targetDnsName: string;
+        evaluateTargetHealth?: boolean;
+        type?: 'A' | 'AAAA';
+    }): Promise<CreateRecordResult>;
+    /**
+     * Create CloudFront alias record (convenience method)
+     */
+    createCloudFrontAlias(params: {
+        domain: string;
+        name: string;
+        cloudFrontDomainName: string;
+    }): Promise<CreateRecordResult>;
+    /**
+     * Create ALB alias record (convenience method)
+     */
+    createAlbAlias(params: {
+        domain: string;
+        name: string;
+        albDnsName: string;
+        region: string;
+    }): Promise<CreateRecordResult>;
+}

package/dist/dns/types.d.ts

@@ -0,0 +1,100 @@
+/**
+ * DNS Provider Types
+ * Common interfaces for DNS provider abstraction
+ */
+export type DnsRecordType = 'A' | 'AAAA' | 'CNAME' | 'TXT' | 'MX' | 'NS' | 'SRV' | 'CAA';
+export interface DnsRecord {
+    name: string;
+    type: DnsRecordType;
+    content: string;
+    /** Alias for content - some providers use 'value' instead */
+    value?: string;
+    ttl?: number;
+    priority?: number;
+    weight?: number;
+    port?: number;
+}
+export interface DnsRecordResult extends DnsRecord {
+    id?: string;
+}
+export interface CreateRecordResult {
+    success: boolean;
+    id?: string;
+    message?: string;
+}
+export interface DeleteRecordResult {
+    success: boolean;
+    message?: string;
+}
+export interface ListRecordsResult {
+    success: boolean;
+    records: DnsRecordResult[];
+    message?: string;
+}
+/**
+ * Common DNS Provider interface
+ * All DNS providers (Route53, Porkbun, GoDaddy, etc.) implement this
+ */
+export interface DnsProvider {
+    /**
+     * Provider name for logging/identification
+     */
+    readonly name: string;
+    /**
+     * Create a DNS record
+     */
+    createRecord(domain: string, record: DnsRecord): Promise<CreateRecordResult>;
+    /**
+     * Update an existing DNS record (upsert behavior)
+     */
+    upsertRecord(domain: string, record: DnsRecord): Promise<CreateRecordResult>;
+    /**
+     * Delete a DNS record
+     */
+    deleteRecord(domain: string, record: DnsRecord): Promise<DeleteRecordResult>;
+    /**
+     * List all DNS records for a domain
+     */
+    listRecords(domain: string, type?: DnsRecordType): Promise<ListRecordsResult>;
+    /**
+     * Check if the provider can manage this domain
+     */
+    canManageDomain(domain: string): Promise<boolean>;
+    /**
+     * List all domains managed by this provider
+     * Returns an array of domain names (e.g., ['example.com', 'mysite.org'])
+     */
+    listDomains(): Promise<string[]>;
+}
+/**
+ * DNS Provider configuration types
+ */
+export interface Route53ProviderConfig {
+    provider: 'route53';
+    region?: string;
+    hostedZoneId?: string;
+}
+export interface PorkbunProviderConfig {
+    provider: 'porkbun';
+    apiKey: string;
+    secretKey: string;
+}
+export interface GoDaddyProviderConfig {
+    provider: 'godaddy';
+    apiKey: string;
+    apiSecret: string;
+    environment?: 'production' | 'ote';
+}
+export interface CloudflareProviderConfig {
+    provider: 'cloudflare';
+    apiToken: string;
+}
+export type DnsProviderConfig = Route53ProviderConfig | PorkbunProviderConfig | GoDaddyProviderConfig | CloudflareProviderConfig;
+/**
+ * Extended configuration for certificate validation
+ */
+export interface CertificateValidationConfig {
+    provider: DnsProviderConfig;
+    waitForValidation?: boolean;
+    maxWaitMinutes?: number;
+}