captify 0.1.15

package/dist/services/s3/services/s3.service.js

@@ -0,0 +1,1079 @@
+var __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
+var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _arguments, generator) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var g = generator.apply(thisArg, _arguments || []), i, q = [];
+    return i = Object.create((typeof AsyncIterator === "function" ? AsyncIterator : Object).prototype), verb("next"), verb("throw"), verb("return", awaitReturn), i[Symbol.asyncIterator] = function () { return this; }, i;
+    function awaitReturn(f) { return function (v) { return Promise.resolve(v).then(f, reject); }; }
+    function verb(n, f) { if (g[n]) { i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; if (f) i[n] = f(i[n]); } }
+    function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }
+    function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }
+    function fulfill(value) { resume("next", value); }
+    function reject(value) { resume("throw", value); }
+    function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
+};
+import { BaseAwsService } from "../../shared";
+import { AbortMultipartUploadCommand, CompleteMultipartUploadCommand, CopyObjectCommand, CreateMultipartUploadCommand, DeleteObjectCommand, DeleteObjectsCommand, GetObjectCommand, GetObjectTaggingCommand, HeadObjectCommand, ListBucketsCommand, ListObjectsV2Command, PutObjectCommand, PutObjectTaggingCommand, S3Client, UploadPartCommand, } from "@aws-sdk/client-s3";
+import { Upload } from "@aws-sdk/lib-storage";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+import { S3_ERROR_MESSAGES } from "../constants";
+import { classifyS3Error } from "../errors";
+import { maskKey, validateS3Key } from "../utilities";
+const DEFAULT_SIGNED_URL_EXPIRY = 3600;
+const MAX_PUT_OBJECT_SIZE = 5 * 1024 * 1024 * 1024; // 5GB
+const RECOMMENDED_MULTIPART_THRESHOLD = 100 * 1024 * 1024; // 100MB
+const DEFAULT_MULTIPART_PART_SIZE = 5 * 1024 * 1024; // 5MB
+const DEFAULT_MULTIPART_QUEUE_SIZE = 4; // 4 concurrent uploads
+const MAX_BATCH_DELETE_SIZE = 1000; // S3 limit
+const MAX_IN_MEMORY_DOWNLOAD_SIZE = 50 * 1024 * 1024; // 50MB - Maximum for in-memory downloads
+const LARGE_FILE_WARNING_THRESHOLD = 10 * 1024 * 1024; // 10MB - Warn for files larger than this
+const DEFAULT_CHUNK_SIZE = 10 * 1024 * 1024; // 10MB - Default chunk size for chunked downloads
+export class S3Service extends BaseAwsService {
+    constructor(deps) {
+        var _a;
+        super({ logger: deps.logger, serviceName: "s3" });
+        this.config = deps.s3Config;
+        this.bucketName = deps.s3Config.bucketName;
+        this.s3 =
+            (_a = deps.client) !== null && _a !== void 0 ? _a : new S3Client(Object.assign(Object.assign(Object.assign({ region: deps.s3Config.region }, (deps.s3Config.credentials ? { credentials: deps.s3Config.credentials } : {})), (deps.s3Config.endpoint ? { endpoint: deps.s3Config.endpoint } : {})), (deps.s3Config.forcePathStyle !== undefined
+                ? { forcePathStyle: deps.s3Config.forcePathStyle }
+                : {})));
+    }
+    /**
+     * Get S3 client with user-specific credentials for governance compliance
+     * If userCredentials are provided, creates a new client with those credentials
+     * Otherwise, returns the default service account client
+     */
+    getClientForOperation(userCredentials) {
+        if (!userCredentials) {
+            return this.s3;
+        }
+        // Create a new client with user's temporary credentials
+        // This enables IAM-based access control per user
+        const credentials = this.getAwsCredentials(userCredentials);
+        // Preserve the original client's configuration (endpoint, forcePathStyle, etc.)
+        // to avoid endpoint errors when switching between service account and user credentials
+        const originalConfig = this.s3.config;
+        return new S3Client(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ region: this.config.region }, (credentials ? { credentials } : {})), (originalConfig.endpoint ? { endpoint: originalConfig.endpoint } : {})), (originalConfig.forcePathStyle !== undefined
+            ? { forcePathStyle: originalConfig.forcePathStyle }
+            : {})), (originalConfig.useAccelerateEndpoint !== undefined
+            ? { useAccelerateEndpoint: originalConfig.useAccelerateEndpoint }
+            : {})), (originalConfig.useDualstackEndpoint !== undefined
+            ? { useDualstackEndpoint: originalConfig.useDualstackEndpoint }
+            : {})));
+    }
+    static create(config, logger) {
+        if (!config.bucketName) {
+            throw new Error(S3_ERROR_MESSAGES.BUCKET_NAME_REQUIRED);
+        }
+        if (!config.region) {
+            throw new Error(S3_ERROR_MESSAGES.REGION_REQUIRED);
+        }
+        // Either credentials are provided OR we rely on AWS SDK default credential chain
+        // Never use empty string credentials
+        const fullConfig = {
+            region: config.region,
+            bucketName: config.bucketName,
+            credentials: config.credentials,
+            endpoint: config.endpoint,
+            forcePathStyle: config.forcePathStyle,
+        };
+        const deps = { logger, s3Config: fullConfig };
+        return new S3Service(deps);
+    }
+    static loadEnvConfig(bucketName) {
+        const accessKeyId = process.env.AWS_ACCESS_KEY_ID;
+        const secretAccessKey = process.env.AWS_SECRET_ACCESS_KEY;
+        const forcePathStyleEnv = process.env.AWS_S3_FORCE_PATH_STYLE;
+        return Object.assign(Object.assign(Object.assign({ region: process.env.AWS_REGION, bucketName: bucketName || process.env.S3_BUCKET_NAME }, (accessKeyId && secretAccessKey
+            ? {
+                credentials: { accessKeyId, secretAccessKey },
+            }
+            : {})), { endpoint: process.env.AWS_S3_ENDPOINT }), (forcePathStyleEnv !== undefined ? { forcePathStyle: forcePathStyleEnv === "true" } : {}));
+    }
+    classifyError(err) {
+        return classifyS3Error(err);
+    }
+    async uploadFile(params) {
+        return this.executeWithRetry(async () => {
+            validateS3Key(params.key);
+            // Validate size for non-streaming uploads
+            let size = "unknown";
+            if (!(params.body instanceof ReadableStream)) {
+                size = params.body.length;
+                if (size > MAX_PUT_OBJECT_SIZE) {
+                    throw new Error(`File size (${size} bytes) exceeds S3 PutObject limit (${MAX_PUT_OBJECT_SIZE} bytes). Use uploadLargeFile() for multipart upload.`);
+                }
+                if (size > RECOMMENDED_MULTIPART_THRESHOLD) {
+                    this.logger.warn("Large file upload detected", {
+                        size,
+                        key: maskKey(params.key),
+                        recommendation: "Consider using uploadLargeFile() for better performance",
+                    });
+                }
+            }
+            const usingUserCredentials = Boolean(params.userCredentials);
+            this.logger.info("S3 upload file attempt", {
+                key: maskKey(params.key),
+                bucket: this.bucketName,
+                contentType: params.contentType,
+                size,
+                userCredentials: usingUserCredentials,
+            });
+            const command = new PutObjectCommand({
+                Bucket: this.bucketName,
+                Key: params.key,
+                Body: params.body,
+                ContentType: params.contentType,
+                Metadata: params.metadata,
+                StorageClass: params.storageClass,
+                ServerSideEncryption: params.serverSideEncryption,
+                ACL: params.acl,
+                CacheControl: params.cacheControl,
+                Expires: params.expires,
+            });
+            // Use user credentials if provided (governance compliance)
+            const client = this.getClientForOperation(params.userCredentials);
+            await client.send(command);
+            this.logger.info("S3 upload file successful", {
+                key: maskKey(params.key),
+                bucket: this.bucketName,
+                userCredentials: usingUserCredentials,
+            });
+        });
+    }
+    /**
+     * Download a file from S3 into memory
+     * WARNING: This method loads the entire file into memory. For files larger than 50MB,
+     * use downloadFileStream() or generateSignedUrl() instead.
+     *
+     * @param params - Download parameters including key and optional version ID
+     * @returns Promise<Uint8Array> - File contents as byte array
+     * @throws Error if file is larger than MAX_IN_MEMORY_DOWNLOAD_SIZE (50MB) unless skipSizeCheck is true
+     */
+    async downloadFile(params) {
+        return this.executeWithRetry(async () => {
+            validateS3Key(params.key);
+            const usingUserCredentials = Boolean(params.userCredentials);
+            const client = this.getClientForOperation(params.userCredentials);
+            // Check file size before downloading (unless explicitly skipped)
+            if (!params.skipSizeCheck) {
+                const headCommand = new HeadObjectCommand({
+                    Bucket: this.bucketName,
+                    Key: params.key,
+                    VersionId: params.versionId,
+                });
+                const headResponse = await client.send(headCommand);
+                const fileSize = headResponse.ContentLength || 0;
+                // Prevent memory issues for large files
+                if (fileSize > MAX_IN_MEMORY_DOWNLOAD_SIZE) {
+                    throw new Error(`File size (${fileSize} bytes / ${Math.round(fileSize / 1024 / 1024)}MB) exceeds maximum for in-memory download (${MAX_IN_MEMORY_DOWNLOAD_SIZE} bytes / ${MAX_IN_MEMORY_DOWNLOAD_SIZE / 1024 / 1024}MB). ` +
+                        `Use downloadFileStream() for streaming, downloadFileInChunks() for chunked downloads, or generateSignedUrl() for client-side downloads.`);
+                }
+                // Warning for moderately large files
+                if (fileSize > LARGE_FILE_WARNING_THRESHOLD) {
+                    this.logger.warn("Large file download detected", {
+                        size: fileSize,
+                        key: maskKey(params.key),
+                        recommendation: "Consider using downloadFileStream() or generateSignedUrl() for better performance",
+                    });
+                }
+                this.logger.info("S3 download file attempt", {
+                    key: maskKey(params.key),
+                    bucket: this.bucketName,
+                    size: fileSize,
+                    userCredentials: usingUserCredentials,
+                });
+            }
+            else {
+                this.logger.info("S3 download file attempt (size check skipped)", {
+                    key: maskKey(params.key),
+                    bucket: this.bucketName,
+                    userCredentials: usingUserCredentials,
+                });
+            }
+            const command = new GetObjectCommand({
+                Bucket: this.bucketName,
+                Key: params.key,
+                VersionId: params.versionId,
+            });
+            const response = await client.send(command);
+            if (!response.Body) {
+                throw new Error(`No body returned from S3 for key: ${maskKey(params.key)} in bucket: ${this.bucketName}`);
+            }
+            const result = await response.Body.transformToByteArray();
+            this.logger.info("S3 download file successful", {
+                key: maskKey(params.key),
+                bucket: this.bucketName,
+                size: result.length,
+                userCredentials: usingUserCredentials,
+            });
+            return result;
+        });
+    }
+    async deleteFile(params) {
+        return this.executeWithRetry(async () => {
+            validateS3Key(params.key);
+            const usingUserCredentials = Boolean(params.userCredentials);
+            this.logger.info("S3 delete file attempt", {
+                key: maskKey(params.key),
+                bucket: this.bucketName,
+                userCredentials: usingUserCredentials,
+            });
+            const command = new DeleteObjectCommand({
+                Bucket: this.bucketName,
+                Key: params.key,
+                VersionId: params.versionId,
+            });
+            // Use user credentials if provided (governance compliance)
+            const client = this.getClientForOperation(params.userCredentials);
+            await client.send(command);
+            this.logger.info("S3 delete file successful", {
+                key: maskKey(params.key),
+                bucket: this.bucketName,
+                userCredentials: usingUserCredentials,
+            });
+        });
+    }
+    async listFiles(params = {}) {
+        return this.executeWithRetry(async () => {
+            var _a;
+            const usingUserCredentials = Boolean(params.userCredentials);
+            this.logger.info("S3 list files attempt", {
+                bucket: this.bucketName,
+                prefix: params.prefix ? maskKey(params.prefix) : undefined,
+                userCredentials: usingUserCredentials,
+            });
+            const command = new ListObjectsV2Command({
+                Bucket: this.bucketName,
+                Prefix: params.prefix,
+                Delimiter: params.delimiter,
+                MaxKeys: params.maxKeys,
+                ContinuationToken: params.continuationToken,
+                StartAfter: params.startAfter,
+            });
+            // Use user credentials if provided (governance compliance)
+            const client = this.getClientForOperation(params.userCredentials);
+            const response = await client.send(command);
+            const objects = (response.Contents || [])
+                .filter((obj) => obj.Key)
+                .map((obj) => ({
+                key: obj.Key,
+                size: obj.Size,
+                lastModified: obj.LastModified,
+                etag: obj.ETag,
+                storageClass: obj.StorageClass,
+                owner: obj.Owner
+                    ? {
+                        id: obj.Owner.ID,
+                        displayName: obj.Owner.DisplayName,
+                    }
+                    : undefined,
+            }));
+            const commonPrefixes = (_a = response.CommonPrefixes) === null || _a === void 0 ? void 0 : _a.map((prefix) => prefix.Prefix).filter((prefix) => Boolean(prefix));
+            this.logger.info("S3 list files successful", {
+                bucket: this.bucketName,
+                objectCount: objects.length,
+                isTruncated: response.IsTruncated,
+            });
+            return {
+                objects,
+                isTruncated: response.IsTruncated || false,
+                nextContinuationToken: response.NextContinuationToken,
+                commonPrefixes,
+            };
+        });
+    }
+    /**
+     * List all S3 buckets accessible to the user
+     * Uses ListBucketsCommand to retrieve all buckets in the AWS account
+     * that the credentials have access to
+     *
+     * @param params - Optional parameters including user credentials
+     * @returns Promise<S3ListBucketsResult> - List of buckets with metadata
+     */
+    async listBuckets(params = {}) {
+        return this.executeWithRetry(async () => {
+            const usingUserCredentials = Boolean(params.userCredentials);
+            this.logger.info("S3 list buckets attempt", {
+                userCredentials: usingUserCredentials,
+            });
+            const command = new ListBucketsCommand({});
+            // Use user credentials if provided (governance compliance)
+            const client = this.getClientForOperation(params.userCredentials);
+            const response = await client.send(command);
+            const buckets = (response.Buckets || [])
+                .filter((bucket) => bucket.Name)
+                .map((bucket) => ({
+                name: bucket.Name,
+                creationDate: bucket.CreationDate,
+            }));
+            this.logger.info("S3 list buckets successful", {
+                bucketCount: buckets.length,
+                userCredentials: usingUserCredentials,
+            });
+            return {
+                buckets,
+                owner: response.Owner
+                    ? {
+                        id: response.Owner.ID,
+                        displayName: response.Owner.DisplayName,
+                    }
+                    : undefined,
+            };
+        });
+    }
+    /**
+     * Check if the user has access to this bucket.
+     * Uses a lightweight ListObjectsV2 with MaxKeys=0 to verify access without fetching data.
+     *
+     * @param params - Optional parameters including user credentials
+     * @returns Promise<boolean> - true if user has access, false otherwise
+     */
+    async checkBucketAccess(params = {}) {
+        const usingUserCredentials = Boolean(params.userCredentials);
+        this.logger.info("S3 check bucket access attempt", {
+            bucket: this.bucketName,
+            userCredentials: usingUserCredentials,
+        });
+        try {
+            const command = new ListObjectsV2Command({
+                Bucket: this.bucketName,
+                MaxKeys: 0, // Don't actually fetch any objects, just check access
+            });
+            const client = this.getClientForOperation(params.userCredentials);
+            await client.send(command);
+            this.logger.info("S3 check bucket access successful", {
+                bucket: this.bucketName,
+                hasAccess: true,
+                userCredentials: usingUserCredentials,
+            });
+            return true;
+        }
+        catch (error) {
+            // Check if this is an access denied error
+            const errorName = error === null || error === void 0 ? void 0 : error.name;
+            const errorCode = error === null || error === void 0 ? void 0 : error.code;
+            if (errorName === "AccessDenied" || errorCode === "AccessDenied") {
+                this.logger.info("S3 check bucket access - access denied", {
+                    bucket: this.bucketName,
+                    hasAccess: false,
+                    userCredentials: usingUserCredentials,
+                });
+                return false;
+            }
+            // For other errors (bucket doesn't exist, network issues, etc.), log and return false
+            this.logger.warn("S3 check bucket access failed with unexpected error", {
+                bucket: this.bucketName,
+                error: errorName || errorCode || "unknown",
+                userCredentials: usingUserCredentials,
+            });
+            return false;
+        }
+    }
+    async copyFile(params) {
+        return this.executeWithRetry(async () => {
+            validateS3Key(params.sourceKey);
+            validateS3Key(params.destinationKey);
+            this.logger.info("S3 copy file attempt", {
+                sourceKey: maskKey(params.sourceKey),
+                destinationKey: maskKey(params.destinationKey),
+                bucket: this.bucketName,
+            });
+            const sourceBucket = params.sourceBucket || this.bucketName;
+            const copySource = `${sourceBucket}/${params.sourceKey}`;
+            const command = new CopyObjectCommand({
+                Bucket: this.bucketName,
+                Key: params.destinationKey,
+                CopySource: copySource,
+                Metadata: params.metadata,
+                MetadataDirective: params.metadataDirective,
+                StorageClass: params.storageClass,
+                ServerSideEncryption: params.serverSideEncryption,
+                ACL: params.acl,
+            });
+            await this.s3.send(command);
+            this.logger.info("S3 copy file successful", {
+                sourceKey: maskKey(params.sourceKey),
+                destinationKey: maskKey(params.destinationKey),
+                bucket: this.bucketName,
+            });
+        });
+    }
+    async headObject(params) {
+        return this.executeWithRetry(async () => {
+            validateS3Key(params.key);
+            const usingUserCredentials = Boolean(params.userCredentials);
+            this.logger.info("S3 head object attempt", {
+                key: maskKey(params.key),
+                bucket: this.bucketName,
+                userCredentials: usingUserCredentials,
+            });
+            const command = new HeadObjectCommand({
+                Bucket: this.bucketName,
+                Key: params.key,
+                VersionId: params.versionId,
+            });
+            const client = this.getClientForOperation(params.userCredentials);
+            const response = await client.send(command);
+            this.logger.info("S3 head object successful", {
+                key: maskKey(params.key),
+                bucket: this.bucketName,
+                userCredentials: usingUserCredentials,
+            });
+            return {
+                contentLength: response.ContentLength,
+                contentType: response.ContentType,
+                lastModified: response.LastModified,
+                etag: response.ETag,
+                metadata: response.Metadata,
+                storageClass: response.StorageClass,
+                serverSideEncryption: response.ServerSideEncryption,
+            };
+        });
+    }
+    /**
+     * Generate a pre-signed URL for temporary access to S3 objects
+     * Supports range requests for resumable downloads
+     *
+     * @param params - Parameters including key, operation, expiry, and optional range
+     * @returns Promise<string> - Pre-signed URL
+     *
+     * @example
+     * ```typescript
+     * // Regular download URL
+     * const url = await service.generateSignedUrl({
+     *   key: 'file.pdf',
+     *   operation: 'getObject',
+     *   expiresIn: 300, // 5 minutes
+     *   responseContentDisposition: 'attachment; filename="document.pdf"'
+     * });
+     *
+     * // Resumable download with range
+     * const partialUrl = await service.generateSignedUrl({
+     *   key: 'large-file.bin',
+     *   operation: 'getObject',
+     *   range: 'bytes=0-1048575', // First 1MB
+     *   expiresIn: 3600
+     * });
+     * ```
+     */
+    async generateSignedUrl(params) {
+        return this.executeWithRetry(async () => {
+            validateS3Key(params.key);
+            const usingUserCredentials = Boolean(params.userCredentials);
+            this.logger.info("S3 generate signed URL attempt", {
+                key: maskKey(params.key),
+                operation: params.operation,
+                bucket: this.bucketName,
+                userCredentials: usingUserCredentials,
+                range: params.range || "none",
+            });
+            const expiresIn = params.expiresIn || DEFAULT_SIGNED_URL_EXPIRY;
+            let command;
+            if (params.operation === "getObject") {
+                command = new GetObjectCommand(Object.assign(Object.assign({ Bucket: this.bucketName, Key: params.key }, (params.responseContentDisposition && {
+                    ResponseContentDisposition: params.responseContentDisposition,
+                })), (params.range && { Range: params.range })));
+            }
+            else {
+                command = new PutObjectCommand({
+                    Bucket: this.bucketName,
+                    Key: params.key,
+                    ContentType: params.contentType,
+                });
+            }
+            const client = this.getClientForOperation(params.userCredentials);
+            const signedUrl = await getSignedUrl(client, command, { expiresIn });
+            this.logger.info("S3 generate signed URL successful", {
+                key: maskKey(params.key),
+                operation: params.operation,
+                bucket: this.bucketName,
+                expiresIn,
+                userCredentials: usingUserCredentials,
+            });
+            return signedUrl;
+        });
+    }
+    /**
+     * Initiate a multipart upload for client-side chunked uploads
+     * Returns an uploadId that must be used for all subsequent part uploads
+     */
+    async createMultipartUpload(params) {
+        return this.executeWithRetry(async () => {
+            validateS3Key(params.key);
+            const usingUserCredentials = Boolean(params.userCredentials);
+            this.logger.info("S3 create multipart upload attempt", {
+                key: maskKey(params.key),
+                bucket: this.bucketName,
+                userCredentials: usingUserCredentials,
+            });
+            const command = new CreateMultipartUploadCommand({
+                Bucket: this.bucketName,
+                Key: params.key,
+                ContentType: params.contentType,
+                Metadata: params.metadata,
+                ServerSideEncryption: params.serverSideEncryption,
+            });
+            const client = this.getClientForOperation(params.userCredentials);
+            const response = await client.send(command);
+            if (!response.UploadId) {
+                throw new Error("Failed to get uploadId from S3");
+            }
+            this.logger.info("S3 create multipart upload successful", {
+                key: maskKey(params.key),
+                bucket: this.bucketName,
+                uploadId: response.UploadId,
+                userCredentials: usingUserCredentials,
+            });
+            return {
+                uploadId: response.UploadId,
+                key: params.key,
+                bucket: this.bucketName,
+            };
+        });
+    }
+    /**
+     * Generate a presigned URL for uploading a specific part of a multipart upload
+     * Each part must be at least 5MB (except the last part)
+     */
+    async getUploadPartUrl(params) {
+        return this.executeWithRetry(async () => {
+            validateS3Key(params.key);
+            const usingUserCredentials = Boolean(params.userCredentials);
+            this.logger.info("S3 get upload part URL attempt", {
+                key: maskKey(params.key),
+                bucket: this.bucketName,
+                uploadId: params.uploadId,
+                partNumber: params.partNumber,
+                userCredentials: usingUserCredentials,
+            });
+            const expiresIn = params.expiresIn || DEFAULT_SIGNED_URL_EXPIRY;
+            const command = new UploadPartCommand({
+                Bucket: this.bucketName,
+                Key: params.key,
+                UploadId: params.uploadId,
+                PartNumber: params.partNumber,
+            });
+            const client = this.getClientForOperation(params.userCredentials);
+            const signedUrl = await getSignedUrl(client, command, { expiresIn });
+            this.logger.info("S3 get upload part URL successful", {
+                key: maskKey(params.key),
+                bucket: this.bucketName,
+                partNumber: params.partNumber,
+                userCredentials: usingUserCredentials,
+            });
+            return signedUrl;
+        });
+    }
+    /**
+     * Complete a multipart upload by combining all uploaded parts
+     * Parts must be provided in order with their ETags
+     */
+    async completeMultipartUpload(params) {
+        return this.executeWithRetry(async () => {
+            validateS3Key(params.key);
+            const usingUserCredentials = Boolean(params.userCredentials);
+            this.logger.info("S3 complete multipart upload attempt", {
+                key: maskKey(params.key),
+                bucket: this.bucketName,
+                uploadId: params.uploadId,
+                partCount: params.parts.length,
+                userCredentials: usingUserCredentials,
+            });
+            const command = new CompleteMultipartUploadCommand({
+                Bucket: this.bucketName,
+                Key: params.key,
+                UploadId: params.uploadId,
+                MultipartUpload: {
+                    Parts: params.parts.map((part) => ({
+                        PartNumber: part.partNumber,
+                        ETag: part.etag,
+                    })),
+                },
+            });
+            const client = this.getClientForOperation(params.userCredentials);
+            const response = await client.send(command);
+            this.logger.info("S3 complete multipart upload successful", {
+                key: maskKey(params.key),
+                bucket: this.bucketName,
+                etag: response.ETag,
+                userCredentials: usingUserCredentials,
+            });
+            return {
+                key: params.key,
+                bucket: this.bucketName,
+                etag: response.ETag || "",
+                location: response.Location,
+            };
+        });
+    }
+    /**
+     * Abort a multipart upload and clean up any uploaded parts
+     * Should be called when an upload fails or is cancelled
+     */
+    async abortMultipartUpload(params) {
+        return this.executeWithRetry(async () => {
+            validateS3Key(params.key);
+            const usingUserCredentials = Boolean(params.userCredentials);
+            this.logger.info("S3 abort multipart upload attempt", {
+                key: maskKey(params.key),
+                bucket: this.bucketName,
+                uploadId: params.uploadId,
+                userCredentials: usingUserCredentials,
+            });
+            const command = new AbortMultipartUploadCommand({
+                Bucket: this.bucketName,
+                Key: params.key,
+                UploadId: params.uploadId,
+            });
+            const client = this.getClientForOperation(params.userCredentials);
+            await client.send(command);
+            this.logger.info("S3 abort multipart upload successful", {
+                key: maskKey(params.key),
+                bucket: this.bucketName,
+                uploadId: params.uploadId,
+                userCredentials: usingUserCredentials,
+            });
+        });
+    }
+    /**
+     * Upload large files using multipart upload with progress tracking
+     * Automatically handles files with parallel part uploads for better performance
+     * Recommended for files larger than 100MB
+     */
+    async uploadLargeFile(params) {
+        return this.executeWithRetry(async () => {
+            var _a, _b, _c, _d;
+            validateS3Key(params.key);
+            const usingUserCredentials = Boolean(params.userCredentials);
+            this.logger.info("S3 multipart upload attempt", {
+                key: maskKey(params.key),
+                bucket: this.bucketName,
+                partSize: (_a = params.partSize) !== null && _a !== void 0 ? _a : DEFAULT_MULTIPART_PART_SIZE,
+                queueSize: (_b = params.queueSize) !== null && _b !== void 0 ? _b : DEFAULT_MULTIPART_QUEUE_SIZE,
+                userCredentials: usingUserCredentials,
+            });
+            // Use user credentials if provided (governance compliance)
+            const client = this.getClientForOperation(params.userCredentials);
+            const upload = new Upload({
+                client,
+                params: {
+                    Bucket: this.bucketName,
+                    Key: params.key,
+                    Body: params.body,
+                    ContentType: params.contentType,
+                    Metadata: params.metadata,
+                    StorageClass: params.storageClass,
+                    ServerSideEncryption: params.serverSideEncryption,
+                    ACL: params.acl,
+                    CacheControl: params.cacheControl,
+                    Expires: params.expires,
+                },
+                partSize: (_c = params.partSize) !== null && _c !== void 0 ? _c : DEFAULT_MULTIPART_PART_SIZE,
+                queueSize: (_d = params.queueSize) !== null && _d !== void 0 ? _d : DEFAULT_MULTIPART_QUEUE_SIZE,
+            });
+            // Track progress if callback provided
+            if (params.onProgress) {
+                upload.on("httpUploadProgress", (progress) => {
+                    params.onProgress(progress);
+                });
+            }
+            await upload.done();
+            this.logger.info("S3 multipart upload successful", {
+                key: maskKey(params.key),
+                bucket: this.bucketName,
+                userCredentials: usingUserCredentials,
+            });
+        });
+    }
+    /**
+     * Download file as a stream for large files or partial downloads
+     * Returns a readable stream instead of loading into memory
+     * Useful for large files or when you want to pipe the download
+     * Supports progress tracking for monitoring download progress
+     *
+     * @param params - Download parameters including key, range, and optional progress callback
+     * @returns Promise<Readable> - Readable stream of file contents
+     */
+    async downloadFileStream(params) {
+        return this.executeWithRetry(async () => {
+            validateS3Key(params.key);
+            const usingUserCredentials = Boolean(params.userCredentials);
+            const client = this.getClientForOperation(params.userCredentials);
+            // Get file size for progress tracking if callback provided
+            let totalSize = 0;
+            if (params.onProgress) {
+                const headCommand = new HeadObjectCommand({
+                    Bucket: this.bucketName,
+                    Key: params.key,
+                    VersionId: params.versionId,
+                });
+                const headResponse = await client.send(headCommand);
+                totalSize = headResponse.ContentLength || 0;
+            }
+            this.logger.info("S3 download stream attempt", {
+                key: maskKey(params.key),
+                bucket: this.bucketName,
+                range: params.range,
+                totalSize: totalSize || "unknown",
+                userCredentials: usingUserCredentials,
+            });
+            const command = new GetObjectCommand({
+                Bucket: this.bucketName,
+                Key: params.key,
+                VersionId: params.versionId,
+                Range: params.range,
+            });
+            const response = await client.send(command);
+            if (!response.Body) {
+                throw new Error(`No body returned from S3 for key: ${maskKey(params.key)} in bucket: ${this.bucketName}`);
+            }
+            const stream = response.Body;
+            // Add progress tracking if callback provided
+            if (params.onProgress && totalSize > 0) {
+                let loaded = 0;
+                stream.on("data", (chunk) => {
+                    loaded += chunk.length;
+                    const percentage = Math.round((loaded / totalSize) * 100);
+                    params.onProgress({ loaded, total: totalSize, percentage });
+                });
+                stream.on("end", () => {
+                    // Ensure we report 100% on completion
+                    params.onProgress({ loaded: totalSize, total: totalSize, percentage: 100 });
+                });
+                stream.on("error", (error) => {
+                    this.logger.error("S3 download stream error", {
+                        key: maskKey(params.key),
+                        error: error.message,
+                    });
+                });
+            }
+            this.logger.info("S3 download stream successful", {
+                key: maskKey(params.key),
+                bucket: this.bucketName,
+                totalSize: totalSize || "unknown",
+            });
+            // Return the stream directly for piping
+            return stream;
+        });
+    }
+    /**
+     * Download large files in chunks with progress tracking
+     * Returns an async generator that yields chunks
+     * Useful for very large files that shouldn't be loaded into memory all at once
+     *
+     * Supports AbortSignal for proper cancellation of in-flight requests when the
+     * caller abandons iteration early.
+     *
+     * @example
+     * ```typescript
+     * const controller = new AbortController();
+     * const chunks = [];
+     * try {
+     *   for await (const chunk of service.downloadFileInChunks({
+     *     key: 'large-file.bin',
+     *     chunkSize: 10 * 1024 * 1024, // 10MB chunks
+     *     onProgress: (progress) => console.log(`${progress.percentage}%`),
+     *     abortSignal: controller.signal
+     *   })) {
+     *     chunks.push(chunk);
+     *     if (shouldCancel) {
+     *       controller.abort();
+     *       break;
+     *     }
+     *   }
+     * } catch (err) {
+     *   if (err.name === 'AbortError') {
+     *     console.log('Download cancelled');
+     *   }
+     * }
+     * const fullFile = Buffer.concat(chunks.map(c => Buffer.from(c)));
+     * ```
+     *
+     * @param params - Download parameters including key, chunk size, progress callback, and abort signal
+     * @returns AsyncGenerator<Uint8Array> - Yields file chunks
+     */
+    downloadFileInChunks(params) {
+        return __asyncGenerator(this, arguments, function* downloadFileInChunks_1() {
+            validateS3Key(params.key);
+            const chunkSize = params.chunkSize || DEFAULT_CHUNK_SIZE;
+            const usingUserCredentials = Boolean(params.userCredentials);
+            const abortSignal = params.abortSignal;
+            // Check if already aborted before starting
+            if (abortSignal === null || abortSignal === void 0 ? void 0 : abortSignal.aborted) {
+                throw new DOMException("Download aborted", "AbortError");
+            }
+            // Get file size first using the same credentials as the chunked downloads
+            const headResult = yield __await(this.headObject({
+                key: params.key,
+                versionId: params.versionId,
+                userCredentials: params.userCredentials,
+            }));
+            const totalSize = headResult.contentLength || 0;
+            if (totalSize === 0) {
+                throw new Error(`Unable to determine file size for key: ${maskKey(params.key)}. Cannot perform chunked download.`);
+            }
+            const estimatedChunks = Math.ceil(totalSize / chunkSize);
+            this.logger.info("S3 chunked download started", {
+                key: maskKey(params.key),
+                bucket: this.bucketName,
+                totalSize,
+                chunkSize,
+                estimatedChunks,
+                userCredentials: usingUserCredentials,
+            });
+            let downloadedBytes = 0;
+            let chunkIndex = 0;
+            const client = this.getClientForOperation(params.userCredentials);
+            while (downloadedBytes < totalSize) {
+                // Check for abort before each chunk request
+                if (abortSignal === null || abortSignal === void 0 ? void 0 : abortSignal.aborted) {
+                    this.logger.info("S3 chunked download aborted by user", {
+                        key: maskKey(params.key),
+                        bucket: this.bucketName,
+                        downloadedBytes,
+                        totalSize,
+                        chunkIndex,
+                    });
+                    throw new DOMException("Download aborted", "AbortError");
+                }
+                const start = downloadedBytes;
+                const end = Math.min(downloadedBytes + chunkSize - 1, totalSize - 1);
+                const range = `bytes=${start}-${end}`;
+                this.logger.debug("Downloading chunk", {
+                    key: maskKey(params.key),
+                    chunkIndex,
+                    range,
+                    progress: `${chunkIndex + 1}/${estimatedChunks}`,
+                });
+                const command = new GetObjectCommand({
+                    Bucket: this.bucketName,
+                    Key: params.key,
+                    Range: range,
+                    VersionId: params.versionId,
+                });
+                // Pass abort signal to the S3 client send operation
+                const response = yield __await(client.send(command, { abortSignal }));
+                if (!response.Body) {
+                    throw new Error(`No body in chunk response for range: ${range}, key: ${maskKey(params.key)}`);
+                }
+                const chunk = yield __await(response.Body.transformToByteArray());
+                downloadedBytes += chunk.length;
+                chunkIndex++;
+                // Report progress
+                if (params.onProgress) {
+                    const percentage = Math.round((downloadedBytes / totalSize) * 100);
+                    params.onProgress({
+                        loaded: downloadedBytes,
+                        total: totalSize,
+                        percentage,
+                    });
+                }
+                yield yield __await(chunk);
+            }
+            this.logger.info("S3 chunked download completed", {
+                key: maskKey(params.key),
+                bucket: this.bucketName,
+                totalSize,
+                totalChunks: chunkIndex,
+                userCredentials: usingUserCredentials,
+            });
+        });
+    }
+    /**
+     * Delete multiple objects in a single request (up to 1000 objects)
+     * More efficient than individual delete operations
+     */
+    async batchDeleteFiles(params) {
+        return this.executeWithRetry(async () => {
+            var _a;
+            // Validate all keys
+            params.keys.forEach(validateS3Key);
+            // S3 limit is 1000 objects per request
+            if (params.keys.length > MAX_BATCH_DELETE_SIZE) {
+                throw new Error(`Cannot delete more than ${MAX_BATCH_DELETE_SIZE} objects in a single batch. Got ${params.keys.length} objects.`);
+            }
+            if (params.keys.length === 0) {
+                throw new Error("No keys provided for batch delete");
+            }
+            this.logger.info("S3 batch delete attempt", {
+                bucket: this.bucketName,
+                count: params.keys.length,
+            });
+            const command = new DeleteObjectsCommand({
+                Bucket: this.bucketName,
+                Delete: {
+                    Objects: params.keys.map((key) => ({ Key: key })),
+                    Quiet: (_a = params.quiet) !== null && _a !== void 0 ? _a : false,
+                },
+            });
+            const response = await this.s3.send(command);
+            const deleted = (response.Deleted || [])
+                .map((obj) => obj.Key)
+                .filter((key) => Boolean(key));
+            const errors = (response.Errors || []).map((err) => ({
+                key: err.Key || "",
+                code: err.Code,
+                message: err.Message,
+            }));
+            this.logger.info("S3 batch delete successful", {
+                bucket: this.bucketName,
+                deletedCount: deleted.length,
+                errorCount: errors.length,
+            });
+            if (errors.length > 0) {
+                this.logger.warn("Some objects failed to delete", {
+                    bucket: this.bucketName,
+                    errors,
+                });
+            }
+            return { deleted, errors };
+        });
+    }
+    /**
+     * Add or update tags on an S3 object
+     * Tags can be used for organization, access control, and cost allocation
+     */
+    async tagObject(key, tags) {
+        return this.executeWithRetry(async () => {
+            validateS3Key(key);
+            if (tags.length === 0) {
+                throw new Error("No tags provided");
+            }
+            if (tags.length > 10) {
+                throw new Error("S3 allows maximum of 10 tags per object");
+            }
+            this.logger.info("S3 tag object attempt", {
+                key: maskKey(key),
+                bucket: this.bucketName,
+                tagCount: tags.length,
+            });
+            const command = new PutObjectTaggingCommand({
+                Bucket: this.bucketName,
+                Key: key,
+                Tagging: {
+                    TagSet: tags.map((tag) => ({ Key: tag.key, Value: tag.value })),
+                },
+            });
+            await this.s3.send(command);
+            this.logger.info("S3 tag object successful", {
+                key: maskKey(key),
+                bucket: this.bucketName,
+                tagCount: tags.length,
+            });
+        });
+    }
+    /**
+     * Get tags for an S3 object
+     */
+    async getObjectTags(key) {
+        return this.executeWithRetry(async () => {
+            validateS3Key(key);
+            this.logger.info("S3 get object tags attempt", {
+                key: maskKey(key),
+                bucket: this.bucketName,
+            });
+            const command = new GetObjectTaggingCommand({
+                Bucket: this.bucketName,
+                Key: key,
+            });
+            const response = await this.s3.send(command);
+            const tags = (response.TagSet || []).map((tag) => ({
+                key: tag.Key || "",
+                value: tag.Value || "",
+            }));
+            this.logger.info("S3 get object tags successful", {
+                key: maskKey(key),
+                bucket: this.bucketName,
+                tagCount: tags.length,
+            });
+            return tags;
+        });
+    }
+    /**
+     * List all files with automatic pagination using async generator
+     * Usage: for await (const batch of service.listAllFiles({ prefix: 'photos/' })) { ... }
+     */
+    listAllFiles() {
+        return __asyncGenerator(this, arguments, function* listAllFiles_1(params = {}) {
+            let continuationToken;
+            do {
+                const result = yield __await(this.listFiles(Object.assign(Object.assign({}, params), { continuationToken })));
+                yield yield __await(result);
+                continuationToken = result.nextContinuationToken;
+            } while (continuationToken);
+        });
+    }
+    /**
+     * Cleanup and destroy the S3Client
+     * Call this when shutting down the service to free resources
+     */
+    async destroy() {
+        this.logger.info("Destroying S3Service", { bucket: this.bucketName });
+        try {
+            this.s3.destroy();
+            this.logger.info("S3Service destroyed successfully");
+        }
+        catch (error) {
+            this.logger.error("Error destroying S3 client", { error });
+            throw error;
+        }
+    }
+    onMetric(name, dims) {
+        this.logger.debug(`S3 Metric: ${name}`, dims);
+    }
+    getBucketName() {
+        return this.bucketName;
+    }
+    /**
+     * Get the public URL for an S3 object.
+     * Respects custom endpoint and forcePathStyle settings.
+     *
+     * @param key The S3 object key
+     * @returns The full URL to the object
+     */
+    getObjectUrl(key) {
+        if (this.config.endpoint) {
+            // Custom endpoint (e.g., MinIO, LocalStack)
+            const endpoint = this.config.endpoint.replace(/\/$/, ""); // Remove trailing slash
+            if (this.config.forcePathStyle) {
+                // Path-style: endpoint/bucket/key
+                return `${endpoint}/${this.bucketName}/${key}`;
+            }
+            else {
+                // Virtual-hosted style: bucket.endpoint/key
+                // Extract protocol and host from endpoint
+                const url = new URL(endpoint);
+                return `${url.protocol}//${this.bucketName}.${url.host}/${key}`;
+            }
+        }
+        else {
+            // Default AWS S3 endpoint
+            const region = this.config.region || "us-east-1";
+            return `https://${this.bucketName}.s3.${region}.amazonaws.com/${key}`;
+        }
+    }
+    /**
+     * Get the URL prefix for S3 objects.
+     * Useful for matching URLs to check if they belong to this bucket.
+     *
+     * @returns The URL prefix (without trailing slash)
+     */
+    getObjectUrlPrefix() {
+        if (this.config.endpoint) {
+            const endpoint = this.config.endpoint.replace(/\/$/, "");
+            if (this.config.forcePathStyle) {
+                return `${endpoint}/${this.bucketName}`;
+            }
+            else {
+                const url = new URL(endpoint);
+                return `${url.protocol}//${this.bucketName}.${url.host}`;
+            }
+        }
+        else {
+            const region = this.config.region || "us-east-1";
+            return `https://${this.bucketName}.s3.${region}.amazonaws.com`;
+        }
+    }
+}
+//# sourceMappingURL=s3.service.js.map