@ts-cloud/core 0.2.3 → 0.2.4

package/dist/advanced-features.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/aws/cloudformation.d.ts

@@ -0,0 +1,136 @@
+/**
+ * AWS CloudFormation API Client
+ * Direct API calls without AWS SDK dependency
+ */
+export interface CloudFormationStack {
+    StackName: string;
+    StackId?: string;
+    StackStatus?: string;
+    CreationTime?: string;
+    LastUpdatedTime?: string;
+    StackStatusReason?: string;
+    Description?: string;
+    Parameters?: Array<{
+        ParameterKey: string;
+        ParameterValue: string;
+    }>;
+    Outputs?: Array<{
+        OutputKey: string;
+        OutputValue: string;
+        Description?: string;
+    }>;
+    Tags?: Array<{
+        Key: string;
+        Value: string;
+    }>;
+}
+export interface CreateStackOptions {
+    stackName: string;
+    templateBody?: string;
+    templateURL?: string;
+    parameters?: Record<string, string>;
+    capabilities?: string[];
+    tags?: Record<string, string>;
+    timeoutInMinutes?: number;
+    onFailure?: 'DO_NOTHING' | 'ROLLBACK' | 'DELETE';
+}
+export interface UpdateStackOptions {
+    stackName: string;
+    templateBody?: string;
+    templateURL?: string;
+    parameters?: Record<string, string>;
+    capabilities?: string[];
+    tags?: Record<string, string>;
+}
+export interface StackEvent {
+    EventId: string;
+    StackName: string;
+    LogicalResourceId: string;
+    PhysicalResourceId?: string;
+    ResourceType: string;
+    Timestamp: string;
+    ResourceStatus: string;
+    ResourceStatusReason?: string;
+}
+/**
+ * CloudFormation API Client
+ */
+export declare class CloudFormationClient {
+    private readonly profile;
+    private credentials;
+    private region;
+    constructor(region?: string, profile?: string);
+    /**
+     * Initialize client with credentials
+     */
+    init(): Promise<void>;
+    /**
+     * Ensure credentials are loaded
+     */
+    private ensureCredentials;
+    /**
+     * Make a CloudFormation API request
+     */
+    private request;
+    /**
+     * Create a new CloudFormation stack
+     */
+    createStack(options: CreateStackOptions): Promise<string>;
+    /**
+     * Update an existing CloudFormation stack
+     */
+    updateStack(options: UpdateStackOptions): Promise<string>;
+    /**
+     * Delete a CloudFormation stack
+     */
+    deleteStack(stackName: string): Promise<void>;
+    /**
+     * Describe a CloudFormation stack
+     */
+    describeStack(stackName: string): Promise<CloudFormationStack>;
+    /**
+     * List all CloudFormation stacks
+     */
+    listStacks(statusFilter?: string[]): Promise<CloudFormationStack[]>;
+    /**
+     * Get stack events
+     */
+    describeStackEvents(stackName: string): Promise<StackEvent[]>;
+    /**
+     * Wait for stack to reach a terminal state
+     */
+    waitForStack(stackName: string, desiredStates: string[], onProgress?: (event: StackEvent) => void): Promise<CloudFormationStack>;
+    /**
+     * Wait for stack using waiter-style name (e.g., 'stack-create-complete')
+     * Convenience method that maps waiter names to CloudFormation states
+     */
+    waitForStackWithProgress(stackName: string, waiterName: string, onProgress?: (event: StackEvent) => void): Promise<CloudFormationStack>;
+    /**
+     * Create a change set
+     */
+    createChangeSet(options: {
+        stackName: string;
+        changeSetName: string;
+        templateBody?: string;
+        templateURL?: string;
+        parameters?: Record<string, string>;
+        capabilities?: string[];
+    }): Promise<string>;
+    /**
+     * Execute a change set
+     */
+    executeChangeSet(changeSetName: string, stackName: string): Promise<void>;
+    /**
+     * Describe stacks (SDK-compatible interface returning { Stacks: [...] })
+     * Accepts either a string stackName or an object { stackName: string }
+     */
+    describeStacks(input: string | {
+        stackName: string;
+    }): Promise<{
+        Stacks: CloudFormationStack[];
+    }>;
+    /**
+     * Get stack outputs as a key-value map
+     */
+    getStackOutputs(stackName: string): Promise<Record<string, string>>;
+}

package/dist/aws/cloudfront.d.ts

@@ -0,0 +1,45 @@
+/**
+ * AWS CloudFront API Client
+ * Direct API calls for CloudFront invalidations without AWS SDK
+ */
+export interface InvalidationOptions {
+    distributionId: string;
+    paths: string[];
+    callerReference?: string;
+}
+/**
+ * CloudFront API Client
+ */
+export declare class CloudFrontClient {
+    private readonly profile;
+    private credentials;
+    constructor(profile?: string);
+    /**
+     * Initialize client with credentials
+     */
+    init(): Promise<void>;
+    /**
+     * Ensure credentials are loaded
+     */
+    private ensureCredentials;
+    /**
+     * Create a cache invalidation
+     */
+    createInvalidation(options: InvalidationOptions): Promise<string>;
+    /**
+     * Get invalidation status
+     */
+    getInvalidation(distributionId: string, invalidationId: string): Promise<any>;
+    /**
+     * List invalidations for a distribution
+     */
+    listInvalidations(distributionId: string): Promise<any[]>;
+    /**
+     * Wait for invalidation to complete
+     */
+    waitForInvalidation(distributionId: string, invalidationId: string, maxAttempts?: number, pollInterval?: number): Promise<void>;
+    /**
+     * Invalidate all files in a distribution
+     */
+    invalidateAll(distributionId: string): Promise<string>;
+}

package/dist/aws/credentials.d.ts

@@ -0,0 +1,77 @@
+/**
+ * AWS Credential Providers
+ *
+ * Automatically load AWS credentials from various sources:
+ * - Environment variables
+ * - Shared credentials file (~/.aws/credentials)
+ * - EC2 instance metadata
+ * - ECS task metadata
+ * - Web identity token (for Kubernetes/IRSA)
+ */
+export interface AWSCredentials {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+    expiration?: Date;
+    region?: string;
+}
+export interface CredentialProviderOptions {
+    /** Profile name for shared credentials file (default: 'default' or AWS_PROFILE env var) */
+    profile?: string;
+    /** Path to credentials file (default: ~/.aws/credentials) */
+    credentialsFile?: string;
+    /** Path to config file (default: ~/.aws/config) */
+    configFile?: string;
+    /** Timeout for metadata requests in ms (default: 1000) */
+    timeout?: number;
+}
+/**
+ * Get credentials from environment variables
+ * Checks: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN
+ */
+export declare function fromEnvironment(): AWSCredentials | null;
+/**
+ * Get credentials from shared credentials file (~/.aws/credentials)
+ */
+export declare function fromSharedCredentials(options?: CredentialProviderOptions): AWSCredentials | null;
+/**
+ * Get credentials from EC2 instance metadata service (IMDSv2)
+ */
+export declare function fromEC2Metadata(options?: CredentialProviderOptions): Promise<AWSCredentials | null>;
+/**
+ * Get credentials from ECS task metadata
+ */
+export declare function fromECSMetadata(options?: CredentialProviderOptions): Promise<AWSCredentials | null>;
+/**
+ * Get credentials from web identity token (for Kubernetes/IRSA)
+ */
+export declare function fromWebIdentity(options?: CredentialProviderOptions): Promise<AWSCredentials | null>;
+/**
+ * Get credentials using the default credential chain
+ * Tries providers in order: Environment -> Shared Credentials -> Web Identity -> ECS -> EC2
+ */
+export declare function getCredentials(options?: CredentialProviderOptions): Promise<AWSCredentials>;
+/**
+ * Create a credential provider that caches and auto-refreshes credentials
+ */
+export declare function createCredentialProvider(options?: CredentialProviderOptions): () => Promise<AWSCredentials>;
+export interface AWSProfile {
+    name: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+    region?: string;
+}
+/**
+ * Resolve AWS credentials from various sources
+ * @deprecated Use getCredentials() instead
+ */
+export declare function resolveCredentials(profile?: string): Promise<AWSCredentials>;
+/**
+ * Resolve AWS region from environment or config
+ */
+export declare function resolveRegion(profile?: string): string;
+/**
+ * Get AWS account ID using STS GetCallerIdentity
+ */
+export declare function getAccountId(credentials?: AWSCredentials): Promise<string>;

package/dist/aws/credentials.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * AWS Credentials Provider Tests
+ */
+export {};

package/dist/aws/index.d.ts

@@ -0,0 +1,10 @@
+export { signRequest, signRequestAsync, makeAWSRequest, makeAWSRequestAsync, makeAWSRequestOnce, createPresignedUrl, createPresignedUrlAsync, detectServiceRegion, clearSigningKeyCache, getSigningKeyCacheSize, parseXMLResponse, parseJSONResponse, isNodeCryptoAvailable, isWebCryptoAvailable, } from './signature';
+export type { SignatureOptions, SignedRequest, PresignedUrlOptions, RetryOptions, } from './signature';
+export { fromEnvironment, fromSharedCredentials, fromEC2Metadata, fromECSMetadata, fromWebIdentity, getCredentials, createCredentialProvider, resolveCredentials, resolveRegion, getAccountId, } from './credentials';
+export type { AWSCredentials, AWSProfile, CredentialProviderOptions, } from './credentials';
+export { CloudFormationClient, } from './cloudformation';
+export type { CloudFormationStack, CreateStackOptions, UpdateStackOptions, StackEvent, } from './cloudformation';
+export { S3Client, S3Error, createS3Client, } from './s3';
+export type { S3ClientOptions, GetObjectOptions, PutObjectOptions, ListObjectsOptions, ListObjectsResult, S3Object, HeadObjectResult, CopyObjectOptions, MultipartUploadOptions, MultipartProgress, } from './s3';
+export { CloudFrontClient, } from './cloudfront';
+export type { InvalidationOptions, } from './cloudfront';

package/dist/aws/s3.d.ts

@@ -0,0 +1,256 @@
+/**
+ * S3 High-Level API
+ *
+ * Simple, intuitive interface for S3 operations:
+ * - get, put, delete, list, head, copy
+ * - Streaming uploads/downloads
+ * - Multipart uploads for large files
+ * - Automatic content type detection
+ */
+import { type RetryOptions } from './signature';
+import { type AWSCredentials, type CredentialProviderOptions } from './credentials';
+export interface S3ClientOptions {
+    /** AWS region (default: 'us-east-1') */
+    region?: string;
+    /** Custom endpoint URL (for MinIO, LocalStack, etc.) */
+    endpoint?: string;
+    /** Force path-style URLs instead of virtual-hosted-style */
+    forcePathStyle?: boolean;
+    /** AWS credentials (if not provided, uses credential chain) */
+    credentials?: AWSCredentials;
+    /** Credential provider options */
+    credentialOptions?: CredentialProviderOptions;
+    /** Retry options for requests */
+    retryOptions?: RetryOptions;
+}
+export interface GetObjectOptions {
+    /** Byte range to fetch (e.g., 'bytes=0-1023') */
+    range?: string;
+    /** Only return if modified since this date */
+    ifModifiedSince?: Date;
+    /** Only return if ETag matches */
+    ifMatch?: string;
+    /** Only return if ETag doesn't match */
+    ifNoneMatch?: string;
+    /** Response content-type override */
+    responseContentType?: string;
+    /** Response content-disposition override */
+    responseContentDisposition?: string;
+}
+export interface PutObjectOptions {
+    /** Content type (auto-detected if not provided) */
+    contentType?: string;
+    /** Content encoding (e.g., 'gzip') */
+    contentEncoding?: string;
+    /** Cache-Control header */
+    cacheControl?: string;
+    /** Content-Disposition header */
+    contentDisposition?: string;
+    /** Custom metadata (x-amz-meta-*) */
+    metadata?: Record<string, string>;
+    /** Storage class (STANDARD, REDUCED_REDUNDANCY, GLACIER, etc.) */
+    storageClass?: string;
+    /** Server-side encryption (AES256, aws:kms) */
+    serverSideEncryption?: string;
+    /** ACL (private, public-read, etc.) */
+    acl?: string;
+    /** Tagging (URL-encoded key=value pairs) */
+    tagging?: string;
+}
+export interface ListObjectsOptions {
+    /** Prefix to filter objects */
+    prefix?: string;
+    /** Delimiter for grouping (usually '/') */
+    delimiter?: string;
+    /** Maximum number of keys to return (default: 1000) */
+    maxKeys?: number;
+    /** Continuation token for pagination */
+    continuationToken?: string;
+    /** Start listing after this key */
+    startAfter?: string;
+}
+export interface ListObjectsResult {
+    contents: S3Object[];
+    commonPrefixes: string[];
+    isTruncated: boolean;
+    continuationToken?: string;
+    nextContinuationToken?: string;
+    keyCount: number;
+    maxKeys: number;
+    prefix?: string;
+    delimiter?: string;
+}
+export interface S3Object {
+    key: string;
+    lastModified: Date;
+    etag: string;
+    size: number;
+    storageClass: string;
+}
+export interface HeadObjectResult {
+    contentLength: number;
+    contentType: string;
+    etag: string;
+    lastModified: Date;
+    metadata: Record<string, string>;
+    storageClass?: string;
+    serverSideEncryption?: string;
+}
+export interface CopyObjectOptions {
+    /** Metadata directive (COPY or REPLACE) */
+    metadataDirective?: 'COPY' | 'REPLACE';
+    /** New metadata (only used if metadataDirective is REPLACE) */
+    metadata?: Record<string, string>;
+    /** Content type (only used if metadataDirective is REPLACE) */
+    contentType?: string;
+    /** Storage class for the copy */
+    storageClass?: string;
+    /** ACL for the copy */
+    acl?: string;
+}
+export interface MultipartUploadOptions extends PutObjectOptions {
+    /** Part size in bytes (default: 5MB, minimum: 5MB) */
+    partSize?: number;
+    /** Maximum concurrent uploads (default: 4) */
+    concurrency?: number;
+    /** Progress callback */
+    onProgress?: (progress: MultipartProgress) => void;
+}
+export interface MultipartProgress {
+    loaded: number;
+    total: number;
+    part: number;
+    totalParts: number;
+}
+export interface PresignedUrlOptions {
+    /** Expiration time in seconds (default: 3600 = 1 hour) */
+    expiresIn?: number;
+    /** HTTP method (default: 'GET') */
+    method?: string;
+}
+/**
+ * S3 Client for high-level S3 operations
+ */
+export declare class S3Client {
+    private region;
+    private endpoint;
+    private forcePathStyle;
+    private credentials?;
+    private credentialOptions?;
+    private retryOptions;
+    constructor(options?: S3ClientOptions);
+    /**
+     * Get credentials (cached or from provider chain)
+     */
+    private getCredentials;
+    /**
+     * Build S3 URL for a bucket/key
+     */
+    private buildUrl;
+    /**
+     * Get an object from S3
+     */
+    get(bucket: string, key: string, options?: GetObjectOptions): Promise<Response>;
+    /**
+     * Get object as text
+     */
+    getText(bucket: string, key: string, options?: GetObjectOptions): Promise<string>;
+    /**
+     * Get object as JSON
+     */
+    getJSON<T = unknown>(bucket: string, key: string, options?: GetObjectOptions): Promise<T>;
+    /**
+     * Get object as ArrayBuffer
+     */
+    getBuffer(bucket: string, key: string, options?: GetObjectOptions): Promise<ArrayBuffer>;
+    /**
+     * Put an object to S3
+     * Automatically uses multipart upload for large files (>5MB)
+     */
+    put(bucket: string, key: string, body: string | ArrayBuffer | Uint8Array | Blob | ReadableStream, options?: PutObjectOptions): Promise<{
+        etag: string;
+    }>;
+    /**
+     * Simple PUT for small files
+     */
+    private putSimple;
+    /**
+     * Delete an object from S3
+     */
+    delete(bucket: string, key: string): Promise<void>;
+    /**
+     * Delete multiple objects from S3
+     */
+    deleteMany(bucket: string, keys: string[]): Promise<{
+        deleted: string[];
+        errors: Array<{
+            key: string;
+            error: string;
+        }>;
+    }>;
+    /**
+     * List objects in a bucket
+     */
+    list(bucket: string, options?: ListObjectsOptions): Promise<ListObjectsResult>;
+    /**
+     * List all objects with automatic pagination
+     */
+    listAll(bucket: string, options?: Omit<ListObjectsOptions, 'continuationToken'>): AsyncGenerator<S3Object>;
+    /**
+     * Check if an object exists and get its metadata
+     */
+    head(bucket: string, key: string): Promise<HeadObjectResult | null>;
+    /**
+     * Check if an object exists
+     */
+    exists(bucket: string, key: string): Promise<boolean>;
+    /**
+     * Copy an object
+     */
+    copy(sourceBucket: string, sourceKey: string, destBucket: string, destKey: string, options?: CopyObjectOptions): Promise<{
+        etag: string;
+    }>;
+    /**
+     * Generate a presigned URL for an object
+     */
+    getPresignedUrl(bucket: string, key: string, options?: PresignedUrlOptions): Promise<string>;
+    /**
+     * Multipart upload for large files or streams
+     */
+    uploadMultipart(bucket: string, key: string, body: ReadableStream | Blob | ArrayBuffer | Uint8Array, options?: MultipartUploadOptions): Promise<{
+        etag: string;
+    }>;
+    /**
+     * Initiate a multipart upload
+     */
+    private initiateMultipartUpload;
+    /**
+     * Upload parts of a multipart upload
+     */
+    private uploadParts;
+    /**
+     * Complete a multipart upload
+     */
+    private completeMultipartUpload;
+    /**
+     * Abort a multipart upload
+     */
+    abortMultipartUpload(bucket: string, key: string, uploadId: string): Promise<void>;
+    /**
+     * Empty all objects in a bucket and then delete the bucket
+     */
+    emptyAndDeleteBucket(bucket: string): Promise<void>;
+}
+/**
+ * S3 Error class
+ */
+export declare class S3Error extends Error {
+    statusCode: number;
+    bucket: string;
+    key?: string | undefined;
+    constructor(message: string, statusCode: number, bucket: string, key?: string | undefined);
+}
+/**
+ * Convenience function to create an S3 client
+ */
+export declare function createS3Client(options?: S3ClientOptions): S3Client;

package/dist/aws/s3.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * S3 Client Tests
+ */
+export {};

package/dist/aws/signature.d.ts

@@ -0,0 +1,142 @@
+/**
+ * AWS Signature Version 4 Signing Process
+ * Implements request signing for direct AWS API calls without SDK
+ *
+ * Reference: https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html
+ *
+ * Browser compatible: Use async functions (signRequestAsync, createPresignedUrlAsync)
+ * Node.js/Bun: Use sync functions for better performance (signRequest, createPresignedUrl)
+ */
+export interface SignatureOptions {
+    method: string;
+    url: string;
+    /** Service name - if not provided, will be auto-detected from URL */
+    service?: string;
+    /** Region - if not provided, will be auto-detected from URL */
+    region?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+    /**
+     * Optional external cache for signing keys
+     * If not provided, uses internal cache
+     * Supports both Buffer (Node.js) and Uint8Array (browser)
+     */
+    cache?: Map<string, Buffer | Uint8Array>;
+    /**
+     * Sign via query string instead of Authorization header
+     * Used for presigned URLs (e.g., S3 presigned URLs)
+     */
+    signQuery?: boolean;
+    /**
+     * Expiration time in seconds for presigned URLs (default: 86400 = 24 hours)
+     * Only used when signQuery is true
+     */
+    expiresIn?: number;
+    /**
+     * Custom datetime for signing (format: YYYYMMDDTHHMMSSZ)
+     * If not provided, uses current time
+     * Useful for testing and reproducibility
+     */
+    datetime?: string;
+}
+export interface SignedRequest {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+}
+export interface PresignedUrlOptions {
+    url: string;
+    method?: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+    /** Service name - if not provided, will be auto-detected from URL */
+    service?: string;
+    /** Region - if not provided, will be auto-detected from URL */
+    region?: string;
+    /** Expiration time in seconds (default: 3600 = 1 hour, max: 604800 = 7 days) */
+    expiresIn?: number;
+    /** Optional external cache for signing keys */
+    cache?: Map<string, Buffer | Uint8Array>;
+}
+export interface RetryOptions {
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Initial delay in ms before first retry (default: 100) */
+    initialDelayMs?: number;
+    /** Maximum delay in ms between retries (default: 5000) */
+    maxDelayMs?: number;
+    /** HTTP status codes that should trigger a retry (default: [429, 500, 502, 503, 504]) */
+    retryableStatusCodes?: number[];
+    /** Request timeout in milliseconds (default: 30000 = 30 seconds) */
+    timeoutMs?: number;
+}
+/**
+ * Detect service and region from AWS URL
+ * Supports standard AWS endpoints, Lambda URLs, R2, and Backblaze B2
+ */
+export declare function detectServiceRegion(url: string | URL): {
+    service: string;
+    region: string;
+};
+/**
+ * Sign an AWS request using Signature Version 4
+ */
+export declare function signRequest(options: SignatureOptions): SignedRequest;
+/**
+ * Sign an AWS request using Signature Version 4 (async - browser compatible)
+ * Use this in browser environments where crypto.subtle is available
+ */
+export declare function signRequestAsync(options: SignatureOptions): Promise<SignedRequest>;
+/**
+ * Generate a presigned URL for AWS requests (e.g., S3 GetObject, PutObject)
+ */
+export declare function createPresignedUrl(options: PresignedUrlOptions): string;
+/**
+ * Generate a presigned URL for AWS requests (async - browser compatible)
+ */
+export declare function createPresignedUrlAsync(options: PresignedUrlOptions): Promise<string>;
+/**
+ * Make a signed AWS API request with automatic retry
+ */
+export declare function makeAWSRequest(options: SignatureOptions, retryOptions?: RetryOptions): Promise<Response>;
+/**
+ * Make a signed AWS API request without retry (for backwards compatibility)
+ */
+export declare function makeAWSRequestOnce(options: SignatureOptions): Promise<Response>;
+/**
+ * Make a signed AWS API request with automatic retry (async - browser compatible)
+ * Use this in browser environments where crypto.subtle is available
+ */
+export declare function makeAWSRequestAsync(options: SignatureOptions, retryOptions?: RetryOptions): Promise<Response>;
+/**
+ * Parse XML response from AWS
+ */
+export declare function parseXMLResponse<T = any>(response: Response): Promise<T>;
+/**
+ * Parse JSON response from AWS
+ */
+export declare function parseJSONResponse<T = any>(response: Response): Promise<T>;
+/**
+ * Clear the internal signing key cache
+ * Call this when credentials change or for testing
+ */
+export declare function clearSigningKeyCache(): void;
+/**
+ * Get current cache size (for diagnostics)
+ */
+export declare function getSigningKeyCacheSize(): number;
+/**
+ * Check if Node.js crypto is available (for sync operations)
+ * Returns true in Node.js/Bun, false in browser
+ */
+export declare function isNodeCryptoAvailable(): boolean;
+/**
+ * Check if Web Crypto API is available (for async operations)
+ * Returns true in modern browsers and Node.js 15+
+ */
+export declare function isWebCryptoAvailable(): boolean;

package/dist/aws/signature.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * AWS Signature V4 Tests
+ */
+export {};