s3mini 0.2.0 → 0.4.0

package/dist/s3mini.js

@@ -13,9 +13,9 @@ const DEFAULT_REQUEST_SIZE_IN_BYTES = 8 * 1024 * 1024;
 const HEADER_AMZ_CONTENT_SHA256 = 'x-amz-content-sha256';
 const HEADER_AMZ_DATE = 'x-amz-date';
 const HEADER_HOST = 'host';
-const HEADER_AUTHORIZATION = 'Authorization';
-const HEADER_CONTENT_TYPE = 'Content-Type';
-const HEADER_CONTENT_LENGTH = 'Content-Length';
+const HEADER_AUTHORIZATION = 'authorization';
+const HEADER_CONTENT_TYPE = 'content-type';
+const HEADER_CONTENT_LENGTH = 'content-length';
 const HEADER_ETAG = 'etag';
 // Error messages
 const ERROR_PREFIX = '[s3mini] ';
@@ -42,6 +42,9 @@ const _createHash = crypto.createHash || (await import('node:crypto')).createHas
 const hash = (content) => {
     return _createHash('sha256').update(content).digest('hex');
 };
+const md5base64 = (data) => {
+    return _createHash('md5').update(data).digest('base64');
+};
 /**
  * Compute HMAC-SHA-256 of arbitrary data and return a hex string.
  * @param {string|Buffer} key      – secret key
@@ -75,6 +78,19 @@ const entityMap = {
     '>': '>',
     '&': '&',
 };
+/**
+ * Escape special characters for XML
+ * @param value String to escape
+ * @returns XML-escaped string
+ */
+const escapeXml = (value) => {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+};
 const unescapeXml = (value) => value.replace(/&(quot|apos|lt|gt|amp);/g, m => entityMap[m] ?? m);
 /**
  * Parse a very small subset of XML into a JS structure.
@@ -83,29 +99,33 @@ const unescapeXml = (value) => value.replace(/&(quot|apos|lt|gt|amp);/g, m => en
  * @returns string for leaf nodes, otherwise a map of children
  */
 const parseXml = (input) => {
-    const RE_TAG = /<(\w)([-\w]+)(?:\/|[^>]*>((?:(?!<\1)[\s\S])*)<\/\1\2)>/gm;
+    const xmlContent = input.replace(/<\?xml[^?]*\?>\s*/, '');
+    const RE_TAG = /<([A-Za-z_][\w\-.]*)[^>]*>([\s\S]*?)<\/\1>/gm;
     const result = {}; // strong type, no `any`
     let match;
-    while ((match = RE_TAG.exec(input)) !== null) {
-        const [, prefix = '', key, inner] = match;
-        const fullKey = `${prefix.toLowerCase()}${key}`;
-        const node = inner ? parseXml(inner) : '';
-        const current = result[fullKey];
+    while ((match = RE_TAG.exec(xmlContent)) !== null) {
+        const tagName = match[1];
+        const innerContent = match[2];
+        const node = innerContent ? parseXml(innerContent) : unescapeXml(innerContent?.trim() || '');
+        if (!tagName) {
+            continue;
+        }
+        const current = result[tagName];
         if (current === undefined) {
-            // first occurrence
-            result[fullKey] = node;
+            // First occurrence
+            result[tagName] = node;
         }
         else if (Array.isArray(current)) {
-            // already an array
+            // Already an array
             current.push(node);
         }
         else {
-            // promote to array on the second occurrence
-            result[fullKey] = [current, node];
+            // Promote to array on the second occurrence
+            result[tagName] = [current, node];
         }
     }
     // No child tags? — return the text, after entity decode
-    return Object.keys(result).length > 0 ? result : unescapeXml(input);
+    return Object.keys(result).length > 0 ? result : unescapeXml(xmlContent.trim());
 };
 /**
  * Encode a character as a URI percent-encoded hex value
@@ -221,7 +241,7 @@ const runInBatches = async (tasks, batchSize = 30, minIntervalMs = 0) => {
  * // Delete a file
  * await s3.deleteObject('example.txt');
  */
-class s3mini {
+class S3mini {
     /**
      * Creates an instance of the S3 class.
      *
@@ -327,7 +347,7 @@ class s3mini {
     _validateMethodIsGetOrHead(method) {
         if (method !== 'GET' && method !== 'HEAD') {
             this._log('error', `${ERROR_PREFIX}method must be either GET or HEAD`);
-            throw new Error('method must be either GET or HEAD');
+            throw new Error(`${ERROR_PREFIX}method must be either GET or HEAD`);
         }
     }
     _checkKey(key) {
@@ -405,8 +425,12 @@ class s3mini {
         headers[HEADER_AMZ_CONTENT_SHA256] = UNSIGNED_PAYLOAD; // body ? U.hash(body) : C.UNSIGNED_PAYLOAD;
         headers[HEADER_AMZ_DATE] = fullDatetime;
         headers[HEADER_HOST] = url.host;
-        const canonicalHeaders = this._buildCanonicalHeaders(headers);
-        const signedHeaders = Object.keys(headers)
+        // sort headers alphabetically by key
+        const ignoredHeaders = ['authorization', 'content-length', 'content-type', 'user-agent'];
+        let headersForSigning = Object.fromEntries(Object.entries(headers).filter(([key]) => !ignoredHeaders.includes(key.toLowerCase())));
+        headersForSigning = Object.fromEntries(Object.entries(headersForSigning).sort(([keyA], [keyB]) => keyA.localeCompare(keyB)));
+        const canonicalHeaders = this._buildCanonicalHeaders(headersForSigning);
+        const signedHeaders = Object.keys(headersForSigning)
             .map(key => key.toLowerCase())
             .sort()
             .join(';');
@@ -420,18 +444,18 @@ class s3mini {
     _buildCanonicalHeaders(headers) {
         return Object.entries(headers)
             .map(([key, value]) => `${key.toLowerCase()}:${String(value).trim()}`)
-            .sort()
             .join('\n');
     }
     _buildCanonicalRequest(method, url, query, canonicalHeaders, signedHeaders) {
-        return [
+        const parts = [
             method,
             url.pathname,
             this._buildCanonicalQueryString(query),
-            `${canonicalHeaders}\n`,
+            canonicalHeaders + '\n', // Canonical headers end with extra newline
             signedHeaders,
             UNSIGNED_PAYLOAD,
-        ].join('\n');
+        ];
+        return parts.join('\n');
     }
     _buildCredentialScope(shortDatetime) {
         return [shortDatetime, this.region, S3_SERVICE, AWS_REQUEST_TYPE].join('/');
@@ -465,9 +489,6 @@ class s3mini {
         if (!['GET', 'HEAD', 'PUT', 'POST', 'DELETE'].includes(method)) {
             throw new Error(`${ERROR_PREFIX}Unsupported HTTP method ${method}`);
         }
-        if (key) {
-            this._checkKey(key); // allow '' for bucket‑level
-        }
         const { filteredOpts, conditionalHeaders } = ['GET', 'HEAD'].includes(method)
             ? this._filterIfHeaders(query)
             : { filteredOpts: query, conditionalHeaders: {} };
@@ -487,6 +508,13 @@ class s3mini {
         const signedHeadersString = Object.fromEntries(Object.entries(signedHeaders).map(([k, v]) => [k, String(v)]));
         return this._sendRequest(finalUrl, method, signedHeadersString, body, tolerated);
     }
+    /**
+     * Gets the current configuration properties of the S3 instance.
+     * @returns {IT.S3Config} The current S3 configuration object containing all settings.
+     * @example
+     * const config = s3.getProps();
+     * console.log(config.endpoint); // 'https://s3.amazonaws.com/my-bucket'
+     */
     getProps() {
         return {
             accessKeyId: this.accessKeyId,
@@ -498,6 +526,25 @@ class s3mini {
             logger: this.logger,
         };
     }
+    /**
+     * Updates the configuration properties of the S3 instance.
+     * @param {IT.S3Config} props - The new configuration object.
+     * @param {string} props.accessKeyId - The access key ID for authentication.
+     * @param {string} props.secretAccessKey - The secret access key for authentication.
+     * @param {string} props.endpoint - The endpoint URL of the S3-compatible service.
+     * @param {string} [props.region='auto'] - The region of the S3 service.
+     * @param {number} [props.requestSizeInBytes=8388608] - The request size of a single request in bytes.
+     * @param {number} [props.requestAbortTimeout] - The timeout in milliseconds after which a request should be aborted.
+     * @param {IT.Logger} [props.logger] - A logger object with methods like info, warn, error.
+     * @throws {TypeError} Will throw an error if required parameters are missing or of incorrect type.
+     * @example
+     * s3.setProps({
+     *   accessKeyId: 'new-access-key',
+     *   secretAccessKey: 'new-secret-key',
+     *   endpoint: 'https://new-endpoint.com/my-bucket',
+     *   region: 'us-west-2' // by default is auto
+     * });
+     */
     setProps(props) {
         this._validateConstructorParams(props.accessKeyId, props.secretAccessKey, props.endpoint);
         this.accessKeyId = props.accessKeyId;
@@ -508,10 +555,22 @@ class s3mini {
         this.requestAbortTimeout = props.requestAbortTimeout;
         this.logger = props.logger;
     }
+    /**
+     * Sanitizes an ETag value by removing surrounding quotes and whitespace.
+     * Still returns RFC compliant ETag. https://www.rfc-editor.org/rfc/rfc9110#section-8.8.3
+     * @param {string} etag - The ETag value to sanitize.
+     * @returns {string} The sanitized ETag value.
+     * @example
+     * const cleanEtag = s3.sanitizeETag('"abc123"'); // Returns: 'abc123'
+     */
     sanitizeETag(etag) {
         return sanitizeETag(etag);
     }
-    // TBD
+    /**
+     * Creates a new bucket.
+     * This method sends a request to create a new bucket in the specified in endpoint.
+     * @returns A promise that resolves to true if the bucket was created successfully, false otherwise.
+     */
     async createBucket() {
         const xmlBody = `
       <CreateBucketConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
@@ -529,10 +588,30 @@ class s3mini {
         });
         return res.status === 200;
     }
+    /**
+     * Checks if a bucket exists.
+     * This method sends a request to check if the specified bucket exists in the S3-compatible service.
+     * @returns A promise that resolves to true if the bucket exists, false otherwise.
+     */
     async bucketExists() {
         const res = await this._signedRequest('HEAD', '', { tolerated: [200, 404, 403] });
         return res.status === 200;
     }
+    /**
+     * Lists objects in the bucket with optional filtering and no pagination.
+     * This method retrieves all objects matching the criteria (not paginated like listObjectsV2).
+     * @param {string} [delimiter='/'] - The delimiter to use for grouping objects.
+     * @param {string} [prefix=''] - The prefix to filter objects by.
+     * @param {number} [maxKeys] - The maximum number of keys to return. If not provided, all keys will be returned.
+     * @param {Record<string, unknown>} [opts={}] - Additional options for the request.
+     * @returns {Promise<IT.ListObject[] | null>} A promise that resolves to an array of objects or null if the bucket is empty.
+     * @example
+     * // List all objects
+     * const objects = await s3.listObjects();
+     *
+     * // List objects with prefix
+     * const photos = await s3.listObjects('/', 'photos/', 100);
+     */
     async listObjects(delimiter = '/', prefix = '', maxKeys, 
     // method: IT.HttpMethod = 'GET', // 'GET' or 'HEAD'
     opts = {}) {
@@ -573,9 +652,9 @@ class s3mini {
                 this._log('error', `${ERROR_PREFIX}Unexpected listObjects response shape: ${JSON.stringify(raw)}`);
                 throw new Error(`${ERROR_PREFIX}Unexpected listObjects response shape`);
             }
-            const out = ('listBucketResult' in raw ? raw.listBucketResult : raw);
+            const out = (raw.ListBucketResult || raw.listBucketResult || raw);
             /* accumulate Contents */
-            const contents = out.contents;
+            const contents = out.Contents || out.contents; // S3 v2 vs v1
             if (contents) {
                 const batch = Array.isArray(contents) ? contents : [contents];
                 all.push(...batch);
@@ -583,13 +662,22 @@ class s3mini {
                     remaining -= batch.length;
                 }
             }
-            const truncated = out.isTruncated === 'true' || out.IsTruncated === 'true';
+            const truncated = out.IsTruncated === 'true' || out.isTruncated === 'true' || false;
             token = truncated
-                ? (out.nextContinuationToken || out.NextContinuationToken || out.nextMarker || out.NextMarker)
+                ? (out.NextContinuationToken || out.nextContinuationToken || out.NextMarker || out.nextMarker)
                 : undefined;
         } while (token && remaining > 0);
         return all;
     }
+    /**
+     * Lists multipart uploads in the bucket.
+     * This method sends a request to list multipart uploads in the specified bucket.
+     * @param {string} [delimiter='/'] - The delimiter to use for grouping uploads.
+     * @param {string} [prefix=''] - The prefix to filter uploads by.
+     * @param {IT.HttpMethod} [method='GET'] - The HTTP method to use for the request (GET or HEAD).
+     * @param {Record<string, string | number | boolean | undefined>} [opts={}] - Additional options for the request.
+     * @returns A promise that resolves to a list of multipart uploads or an error.
+     */
     async listMultipartUploads(delimiter = '/', prefix = '', method = 'GET', opts = {}) {
         this._checkDelimiter(delimiter);
         this._checkPrefix(prefix);
@@ -618,43 +706,104 @@ class s3mini {
         }
         return raw;
     }
-    async getObject(key, opts = {}) {
-        const res = await this._signedRequest('GET', key, { query: opts, tolerated: [200, 404, 412, 304] });
+    /**
+     * Get an object from the S3-compatible service.
+     * This method sends a request to retrieve the specified object from the S3-compatible service.
+     * @param {string} key - The key of the object to retrieve.
+     * @param {Record<string, unknown>} [opts] - Additional options for the request.
+     * @param {IT.SSECHeaders} [ssecHeaders] - Server-Side Encryption headers, if any.
+     * @returns A promise that resolves to the object data (string) or null if not found.
+     */
+    async getObject(key, opts = {}, ssecHeaders) {
+        // if ssecHeaders is set, add it to headers
+        const res = await this._signedRequest('GET', key, {
+            query: opts, // use opts.query if it exists, otherwise use an empty object
+            tolerated: [200, 404, 412, 304],
+            headers: ssecHeaders ? { ...ssecHeaders } : undefined,
+        });
         if ([404, 412, 304].includes(res.status)) {
             return null;
         }
         return res.text();
     }
-    async getObjectResponse(key, opts = {}) {
-        const res = await this._signedRequest('GET', key, { query: opts, tolerated: [200, 404, 412, 304] });
+    /**
+     * Get an object response from the S3-compatible service.
+     * This method sends a request to retrieve the specified object and returns the full response.
+     * @param {string} key - The key of the object to retrieve.
+     * @param {Record<string, unknown>} [opts={}] - Additional options for the request.
+     * @param {IT.SSECHeaders} [ssecHeaders] - Server-Side Encryption headers, if any.
+     * @returns A promise that resolves to the Response object or null if not found.
+     */
+    async getObjectResponse(key, opts = {}, ssecHeaders) {
+        const res = await this._signedRequest('GET', key, {
+            query: opts,
+            tolerated: [200, 404, 412, 304],
+            headers: ssecHeaders ? { ...ssecHeaders } : undefined,
+        });
         if ([404, 412, 304].includes(res.status)) {
             return null;
         }
         return res;
     }
-    async getObjectArrayBuffer(key, opts = {}) {
-        const res = await this._signedRequest('GET', key, { query: opts, tolerated: [200, 404, 412, 304] });
+    /**
+     * Get an object as an ArrayBuffer from the S3-compatible service.
+     * This method sends a request to retrieve the specified object and returns it as an ArrayBuffer.
+     * @param {string} key - The key of the object to retrieve.
+     * @param {Record<string, unknown>} [opts={}] - Additional options for the request.
+     * @param {IT.SSECHeaders} [ssecHeaders] - Server-Side Encryption headers, if any.
+     * @returns A promise that resolves to the object data as an ArrayBuffer or null if not found.
+     */
+    async getObjectArrayBuffer(key, opts = {}, ssecHeaders) {
+        const res = await this._signedRequest('GET', key, {
+            query: opts,
+            tolerated: [200, 404, 412, 304],
+            headers: ssecHeaders ? { ...ssecHeaders } : undefined,
+        });
         if ([404, 412, 304].includes(res.status)) {
             return null;
         }
         return res.arrayBuffer();
     }
-    async getObjectJSON(key, opts = {}) {
-        const res = await this._signedRequest('GET', key, { query: opts, tolerated: [200, 404, 412, 304] });
+    /**
+     * Get an object as JSON from the S3-compatible service.
+     * This method sends a request to retrieve the specified object and returns it as JSON.
+     * @param {string} key - The key of the object to retrieve.
+     * @param {Record<string, unknown>} [opts={}] - Additional options for the request.
+     * @param {IT.SSECHeaders} [ssecHeaders] - Server-Side Encryption headers, if any.
+     * @returns A promise that resolves to the object data as JSON or null if not found.
+     */
+    async getObjectJSON(key, opts = {}, ssecHeaders) {
+        const res = await this._signedRequest('GET', key, {
+            query: opts,
+            tolerated: [200, 404, 412, 304],
+            headers: ssecHeaders ? { ...ssecHeaders } : undefined,
+        });
         if ([404, 412, 304].includes(res.status)) {
             return null;
         }
         return res.json();
     }
-    async getObjectWithETag(key, opts = {}) {
+    /**
+     * Get an object with its ETag from the S3-compatible service.
+     * This method sends a request to retrieve the specified object and its ETag.
+     * @param {string} key - The key of the object to retrieve.
+     * @param {Record<string, unknown>} [opts={}] - Additional options for the request.
+     * @param {IT.SSECHeaders} [ssecHeaders] - Server-Side Encryption headers, if any.
+     * @returns A promise that resolves to an object containing the ETag and the object data as an ArrayBuffer or null if not found.
+     */
+    async getObjectWithETag(key, opts = {}, ssecHeaders) {
         try {
-            const res = await this._signedRequest('GET', key, { query: opts, tolerated: [200, 404, 412, 304] });
+            const res = await this._signedRequest('GET', key, {
+                query: opts,
+                tolerated: [200, 404, 412, 304],
+                headers: ssecHeaders ? { ...ssecHeaders } : undefined,
+            });
             if ([404, 412, 304].includes(res.status)) {
                 return { etag: null, data: null };
             }
             const etag = res.headers.get(HEADER_ETAG);
             if (!etag) {
-                throw new Error('ETag not found in response headers');
+                throw new Error(`${ERROR_PREFIX}ETag not found in response headers`);
             }
             return { etag: sanitizeETag(etag), data: await res.arrayBuffer() };
         }
@@ -663,19 +812,52 @@ class s3mini {
             throw err;
         }
     }
-    async getObjectRaw(key, wholeFile = true, rangeFrom = 0, rangeTo = this.requestSizeInBytes, opts = {}) {
+    /**
+     * Get an object as a raw response from the S3-compatible service.
+     * This method sends a request to retrieve the specified object and returns the raw response.
+     * @param {string} key - The key of the object to retrieve.
+     * @param {boolean} [wholeFile=true] - Whether to retrieve the whole file or a range.
+     * @param {number} [rangeFrom=0] - The starting byte for the range (if not whole file).
+     * @param {number} [rangeTo=this.requestSizeInBytes] - The ending byte for the range (if not whole file).
+     * @param {Record<string, unknown>} [opts={}] - Additional options for the request.
+     * @param {IT.SSECHeaders} [ssecHeaders] - Server-Side Encryption headers, if any.
+     * @returns A promise that resolves to the Response object.
+     */
+    async getObjectRaw(key, wholeFile = true, rangeFrom = 0, rangeTo = this.requestSizeInBytes, opts = {}, ssecHeaders) {
         const rangeHdr = wholeFile ? {} : { range: `bytes=${rangeFrom}-${rangeTo - 1}` };
         return this._signedRequest('GET', key, {
             query: { ...opts },
-            headers: rangeHdr,
+            headers: { ...rangeHdr, ...ssecHeaders },
             withQuery: true, // keep ?query=string behaviour
         });
     }
-    async getContentLength(key) {
-        const res = await this._signedRequest('HEAD', key);
-        const len = res.headers.get(HEADER_CONTENT_LENGTH);
-        return len ? +len : 0;
+    /**
+     * Get the content length of an object.
+     * This method sends a HEAD request to retrieve the content length of the specified object.
+     * @param {string} key - The key of the object to retrieve the content length for.
+     * @returns A promise that resolves to the content length of the object in bytes, or 0 if not found.
+     * @throws {Error} If the content length header is not found in the response.
+     */
+    async getContentLength(key, ssecHeaders) {
+        try {
+            const res = await this._signedRequest('HEAD', key, {
+                headers: ssecHeaders ? { ...ssecHeaders } : undefined,
+            });
+            const len = res.headers.get(HEADER_CONTENT_LENGTH);
+            return len ? +len : 0;
+        }
+        catch (err) {
+            this._log('error', `Error getting content length for object ${key}: ${String(err)}`);
+            throw new Error(`${ERROR_PREFIX}Error getting content length for object ${key}: ${String(err)}`);
+        }
     }
+    /**
+     * Checks if an object exists in the S3-compatible service.
+     * This method sends a HEAD request to check if the specified object exists.
+     * @param {string} key - The key of the object to check.
+     * @param {Record<string, unknown>} [opts={}] - Additional options for the request.
+     * @returns A promise that resolves to true if the object exists, false if not found, or null if ETag mismatch.
+     */
     async objectExists(key, opts = {}) {
         const res = await this._signedRequest('HEAD', key, {
             query: opts,
@@ -689,21 +871,54 @@ class s3mini {
         }
         return true; // found (200)
     }
-    async getEtag(key, opts = {}) {
+    /**
+     * Retrieves the ETag of an object without downloading its content.
+     * @param {string} key - The key of the object to retrieve the ETag for.
+     * @param {Record<string, unknown>} [opts={}] - Additional options for the request.
+     * @param {IT.SSECHeaders} [ssecHeaders] - Server-Side Encryption headers, if any.
+     * @returns {Promise<string | null>} A promise that resolves to the ETag value or null if the object is not found.
+     * @throws {Error} If the ETag header is not found in the response.
+     * @example
+     * const etag = await s3.getEtag('path/to/file.txt');
+     * if (etag) {
+     *   console.log(`File ETag: ${etag}`);
+     * }
+     */
+    async getEtag(key, opts = {}, ssecHeaders) {
         const res = await this._signedRequest('HEAD', key, {
             query: opts,
-            tolerated: [200, 404],
+            tolerated: [200, 304, 404, 412],
+            headers: ssecHeaders ? { ...ssecHeaders } : undefined,
         });
         if (res.status === 404) {
             return null;
         }
+        if (res.status === 412 || res.status === 304) {
+            return null; // ETag mismatch
+        }
         const etag = res.headers.get(HEADER_ETAG);
         if (!etag) {
-            throw new Error('ETag not found in response headers');
+            throw new Error(`${ERROR_PREFIX}ETag not found in response headers`);
         }
         return sanitizeETag(etag);
     }
-    async putObject(key, data, fileType = DEFAULT_STREAM_CONTENT_TYPE) {
+    /**
+     * Uploads an object to the S3-compatible service.
+     * @param {string} key - The key/path where the object will be stored.
+     * @param {string | Buffer} data - The data to upload (string or Buffer).
+     * @param {string} [fileType='application/octet-stream'] - The MIME type of the file.
+     * @param {IT.SSECHeaders} [ssecHeaders] - Server-Side Encryption headers, if any.
+     * @returns {Promise<Response>} A promise that resolves to the Response object from the upload request.
+     * @throws {TypeError} If data is not a string or Buffer.
+     * @example
+     * // Upload text file
+     * await s3.putObject('hello.txt', 'Hello, World!', 'text/plain');
+     *
+     * // Upload binary data
+     * const buffer = Buffer.from([0x89, 0x50, 0x4e, 0x47]);
+     * await s3.putObject('image.png', buffer, 'image/png');
+     */
+    async putObject(key, data, fileType = DEFAULT_STREAM_CONTENT_TYPE, ssecHeaders) {
         if (!(data instanceof Buffer || typeof data === 'string')) {
             throw new TypeError(ERROR_DATA_BUFFER_REQUIRED);
         }
@@ -712,44 +927,110 @@ class s3mini {
             headers: {
                 [HEADER_CONTENT_LENGTH]: typeof data === 'string' ? Buffer.byteLength(data) : data.length,
                 [HEADER_CONTENT_TYPE]: fileType,
+                ...ssecHeaders,
             },
             tolerated: [200],
         });
     }
-    async getMultipartUploadId(key, fileType = DEFAULT_STREAM_CONTENT_TYPE) {
+    /**
+     * Initiates a multipart upload and returns the upload ID.
+     * @param {string} key - The key/path where the object will be stored.
+     * @param {string} [fileType='application/octet-stream'] - The MIME type of the file.
+     * @param {IT.SSECHeaders?} [ssecHeaders] - Server-Side Encryption headers, if any.
+     * @returns {Promise<string>} A promise that resolves to the upload ID for the multipart upload.
+     * @throws {TypeError} If key is invalid or fileType is not a string.
+     * @throws {Error} If the multipart upload fails to initialize.
+     * @example
+     * const uploadId = await s3.getMultipartUploadId('large-file.zip', 'application/zip');
+     * console.log(`Started multipart upload: ${uploadId}`);
+     */
+    async getMultipartUploadId(key, fileType = DEFAULT_STREAM_CONTENT_TYPE, ssecHeaders) {
         this._checkKey(key);
         if (typeof fileType !== 'string') {
             throw new TypeError(`${ERROR_PREFIX}fileType must be a string`);
         }
         const query = { uploads: '' };
-        const headers = { [HEADER_CONTENT_TYPE]: fileType };
+        const headers = { [HEADER_CONTENT_TYPE]: fileType, ...ssecHeaders };
         const res = await this._signedRequest('POST', key, {
             query,
             headers,
             withQuery: true,
         });
         const parsed = parseXml(await res.text());
-        if (parsed &&
-            typeof parsed === 'object' &&
-            'initiateMultipartUploadResult' in parsed &&
-            parsed.initiateMultipartUploadResult &&
-            'uploadId' in parsed.initiateMultipartUploadResult) {
-            return parsed.initiateMultipartUploadResult.uploadId;
+        // if (
+        //   parsed &&
+        //   typeof parsed === 'object' &&
+        //   'initiateMultipartUploadResult' in parsed &&
+        //   parsed.initiateMultipartUploadResult &&
+        //   'uploadId' in (parsed.initiateMultipartUploadResult as { uploadId: string })
+        // ) {
+        //   return (parsed.initiateMultipartUploadResult as { uploadId: string }).uploadId;
+        // }
+        if (parsed && typeof parsed === 'object') {
+            // Check for both cases of InitiateMultipartUploadResult
+            const uploadResult = parsed.initiateMultipartUploadResult ||
+                parsed.InitiateMultipartUploadResult;
+            if (uploadResult && typeof uploadResult === 'object') {
+                // Check for both cases of uploadId
+                const uploadId = uploadResult.uploadId || uploadResult.UploadId;
+                if (uploadId && typeof uploadId === 'string') {
+                    return uploadId;
+                }
+            }
         }
         throw new Error(`${ERROR_PREFIX}Failed to create multipart upload: ${JSON.stringify(parsed)}`);
     }
-    async uploadPart(key, uploadId, data, partNumber, opts = {}) {
+    /**
+     * Uploads a part in a multipart upload.
+     * @param {string} key - The key of the object being uploaded.
+     * @param {string} uploadId - The upload ID from getMultipartUploadId.
+     * @param {Buffer | string} data - The data for this part.
+     * @param {number} partNumber - The part number (must be between 1 and 10,000).
+     * @param {Record<string, unknown>} [opts={}] - Additional options for the request.
+     * @param {IT.SSECHeaders} [ssecHeaders] - Server-Side Encryption headers, if any.
+     * @returns {Promise<IT.UploadPart>} A promise that resolves to an object containing the partNumber and etag.
+     * @throws {TypeError} If any parameter is invalid.
+     * @example
+     * const part = await s3.uploadPart(
+     *   'large-file.zip',
+     *   uploadId,
+     *   partData,
+     *   1
+     * );
+     * console.log(`Part ${part.partNumber} uploaded with ETag: ${part.etag}`);
+     */
+    async uploadPart(key, uploadId, data, partNumber, opts = {}, ssecHeaders) {
         this._validateUploadPartParams(key, uploadId, data, partNumber, opts);
         const query = { uploadId, partNumber, ...opts };
         const res = await this._signedRequest('PUT', key, {
             query,
             body: data,
-            headers: { [HEADER_CONTENT_LENGTH]: typeof data === 'string' ? Buffer.byteLength(data) : data.length },
+            headers: {
+                [HEADER_CONTENT_LENGTH]: typeof data === 'string' ? Buffer.byteLength(data) : data.length,
+                ...ssecHeaders,
+            },
         });
         return { partNumber, etag: sanitizeETag(res.headers.get('etag') || '') };
     }
+    /**
+     * Completes a multipart upload by combining all uploaded parts.
+     * @param {string} key - The key of the object being uploaded.
+     * @param {string} uploadId - The upload ID from getMultipartUploadId.
+     * @param {Array<IT.UploadPart>} parts - Array of uploaded parts with partNumber and etag.
+     * @returns {Promise<IT.CompleteMultipartUploadResult>} A promise that resolves to the completion result containing the final ETag.
+     * @throws {Error} If the multipart upload fails to complete.
+     * @example
+     * const result = await s3.completeMultipartUpload(
+     *   'large-file.zip',
+     *   uploadId,
+     *   [
+     *     { partNumber: 1, etag: 'abc123' },
+     *     { partNumber: 2, etag: 'def456' }
+     *   ]
+     * );
+     * console.log(`Upload completed with ETag: ${result.etag}`);
+     */
     async completeMultipartUpload(key, uploadId, parts) {
-        // …existing validation left untouched …
         const query = { uploadId };
         const xmlBody = this._buildCompleteMultipartUploadXml(parts);
         const headers = {
@@ -763,24 +1044,47 @@ class s3mini {
             withQuery: true,
         });
         const parsed = parseXml(await res.text());
-        const result = parsed && typeof parsed === 'object' && 'completeMultipartUploadResult' in parsed
-            ? parsed.completeMultipartUploadResult
-            : parsed;
-        if (!result || typeof result !== 'object') {
-            throw new Error(`${ERROR_PREFIX}Failed to complete multipart upload: ${JSON.stringify(parsed)}`);
-        }
-        if ('ETag' in result || 'eTag' in result) {
-            result.etag = this.sanitizeETag(result.eTag ?? result.ETag);
+        if (parsed && typeof parsed === 'object') {
+            // Check for both cases
+            const result = parsed.completeMultipartUploadResult || parsed.CompleteMultipartUploadResult || parsed;
+            if (result && typeof result === 'object') {
+                const resultObj = result;
+                // Handle ETag in all its variations
+                const etag = resultObj.ETag || resultObj.eTag || resultObj.etag;
+                if (etag && typeof etag === 'string') {
+                    return {
+                        ...resultObj,
+                        etag: this.sanitizeETag(etag),
+                    };
+                }
+                return result;
+            }
         }
-        return result;
+        throw new Error(`${ERROR_PREFIX}Failed to complete multipart upload: ${JSON.stringify(parsed)}`);
     }
-    async abortMultipartUpload(key, uploadId) {
+    /**
+     * Aborts a multipart upload and removes all uploaded parts.
+     * @param {string} key - The key of the object being uploaded.
+     * @param {string} uploadId - The upload ID to abort.
+     * @param {IT.SSECHeaders} [ssecHeaders] - Server-Side Encryption headers, if any.
+     * @returns {Promise<object>} A promise that resolves to an object containing the abort status and details.
+     * @throws {TypeError} If key or uploadId is invalid.
+     * @throws {Error} If the abort operation fails.
+     * @example
+     * try {
+     *   const result = await s3.abortMultipartUpload('large-file.zip', uploadId);
+     *   console.log('Upload aborted:', result.status);
+     * } catch (error) {
+     *   console.error('Failed to abort upload:', error);
+     * }
+     */
+    async abortMultipartUpload(key, uploadId, ssecHeaders) {
         this._checkKey(key);
         if (!uploadId) {
             throw new TypeError(ERROR_UPLOAD_ID_REQUIRED);
         }
         const query = { uploadId };
-        const headers = { [HEADER_CONTENT_TYPE]: XML_CONTENT_TYPE };
+        const headers = { [HEADER_CONTENT_TYPE]: XML_CONTENT_TYPE, ...(ssecHeaders ? { ...ssecHeaders } : {}) };
         const res = await this._signedRequest('DELETE', key, {
             query,
             headers,
@@ -811,10 +1115,101 @@ class s3mini {
       </CompleteMultipartUpload>
     `;
     }
+    /**
+     * Deletes an object from the bucket.
+     * This method sends a request to delete the specified object from the bucket.
+     * @param {string} key - The key of the object to delete.
+     * @returns A promise that resolves to true if the object was deleted successfully, false otherwise.
+     */
     async deleteObject(key) {
         const res = await this._signedRequest('DELETE', key, { tolerated: [200, 204] });
         return res.status === 200 || res.status === 204;
     }
+    async _deleteObjectsProcess(keys) {
+        const xmlBody = `<Delete>${keys.map(key => `<Object><Key>${escapeXml(key)}</Key></Object>`).join('')}</Delete>`;
+        const query = { delete: '' };
+        const md5Base64 = md5base64(xmlBody);
+        const headers = {
+            [HEADER_CONTENT_TYPE]: XML_CONTENT_TYPE,
+            [HEADER_CONTENT_LENGTH]: Buffer.byteLength(xmlBody).toString(),
+            'Content-MD5': md5Base64,
+        };
+        const res = await this._signedRequest('POST', '', {
+            query,
+            body: xmlBody,
+            headers,
+            withQuery: true,
+        });
+        const parsed = parseXml(await res.text());
+        if (!parsed || typeof parsed !== 'object') {
+            throw new Error(`${ERROR_PREFIX}Failed to delete objects: ${JSON.stringify(parsed)}`);
+        }
+        const out = (parsed.DeleteResult || parsed.deleteResult || parsed);
+        const resultMap = new Map();
+        keys.forEach(key => resultMap.set(key, false));
+        const deleted = out.deleted || out.Deleted;
+        if (deleted) {
+            const deletedArray = Array.isArray(deleted) ? deleted : [deleted];
+            deletedArray.forEach((item) => {
+                if (item && typeof item === 'object') {
+                    const obj = item;
+                    // Check both key and Key
+                    const key = obj.key || obj.Key;
+                    if (key && typeof key === 'string') {
+                        resultMap.set(key, true);
+                    }
+                }
+            });
+        }
+        // Handle errors (check both cases)
+        const errors = out.error || out.Error;
+        if (errors) {
+            const errorsArray = Array.isArray(errors) ? errors : [errors];
+            errorsArray.forEach((item) => {
+                if (item && typeof item === 'object') {
+                    const obj = item;
+                    // Check both cases for all properties
+                    const key = obj.key || obj.Key;
+                    const code = obj.code || obj.Code;
+                    const message = obj.message || obj.Message;
+                    if (key && typeof key === 'string') {
+                        resultMap.set(key, false);
+                        // Optionally log the error for debugging
+                        this._log('warn', `Failed to delete object: ${key}`, {
+                            code: code || 'Unknown',
+                            message: message || 'Unknown error',
+                        });
+                    }
+                }
+            });
+        }
+        // Return boolean array in the same order as input keys
+        return keys.map(key => resultMap.get(key) || false);
+    }
+    /**
+     * Deletes multiple objects from the bucket.
+     * @param {string[]} keys - An array of object keys to delete.
+     * @returns A promise that resolves to an array of booleans indicating success for each key in order.
+     */
+    async deleteObjects(keys) {
+        if (!Array.isArray(keys) || keys.length === 0) {
+            return [];
+        }
+        const maxBatchSize = 1000; // S3 limit for delete batch size
+        if (keys.length > maxBatchSize) {
+            const allPromises = [];
+            for (let i = 0; i < keys.length; i += maxBatchSize) {
+                const batch = keys.slice(i, i + maxBatchSize);
+                allPromises.push(this._deleteObjectsProcess(batch));
+            }
+            const results = await Promise.all(allPromises);
+            // Flatten the results array
+            return results.flat();
+        }
+        else {
+            return await this._deleteObjectsProcess(keys);
+        }
+    }
     async _sendRequest(url, method, headers, body, toleratedStatusCodes = []) {
         this._log('info', `Sending ${method} request to ${url}`, `headers: ${JSON.stringify(headers)}`);
         try {
@@ -861,6 +1256,10 @@ class s3mini {
         return hmac(kService, AWS_REQUEST_TYPE);
     }
 }
+/**
+ * @deprecated Use `S3mini` instead.
+ */
+const s3mini = S3mini;
 
-export { s3mini as default, runInBatches, s3mini, sanitizeETag };
+export { S3mini, S3mini as default, runInBatches, s3mini, sanitizeETag };
 //# sourceMappingURL=s3mini.js.map