s3mini 0.3.0 → 0.4.0

package/README.md

@@ -60,6 +60,7 @@ The library supports a subset of S3 operations, focusing on essential features,
 - ✅ GetObject (getObject, getObjectResponse, getObjectWithETag, getObjectRaw, getObjectArrayBuffer, getObjectJSON)
 - ✅ PutObject (putObject)
 - ✅ DeleteObject (deleteObject)
+- ✅ DeleteObjects (deleteObjects)
 - ✅ HeadObject (objectExists, getEtag, getContentLength)
 - ✅ listMultipartUploads
 - ✅ CreateMultipartUpload (getMultipartUploadId)
@@ -68,6 +69,8 @@ The library supports a subset of S3 operations, focusing on essential features,
 - ✅ uploadPart
 - ❌ CopyObject: Not implemented (tbd)
 
+Put/Get objects with SSE-C (server-side encryption with customer-provided keys) is supported, but only tested on Cloudflare R2!
+
 ## Installation
 
 ```bash
@@ -99,10 +102,14 @@ mv example.env .env
 
 ## Usage
 
+> [!WARNING]
+> `s3mini` is a deprecated alias retained solely for backward compatibility.
+> It is scheduled for removal in a future release. Please migrate to the new `S3mini` class.
+
 ```typescript
-import { s3mini, sanitizeETag } from 's3mini';
+import { S3mini, sanitizeETag } from 's3mini';
 
-const s3client = new s3mini({
+const s3client = new S3mini({
   accessKeyId: config.accessKeyId,
   secretAccessKey: config.secretAccessKey,
   endpoint: config.endpoint,
@@ -149,7 +156,7 @@ const objectData: string | null = await s3client.getObject(smallObjectKey);
 console.log('Object data:', objectData);
 
 // get the object with ETag, null if not found
-const response2: Response = await s3mini.getObject(smallObjectKey, { 'if-none-match': etag });
+const response2: Response = await S3mini.getObject(smallObjectKey, { 'if-none-match': etag });
 if (response2) {
   // ETag changed so we can get the object data and new ETag
   // Note: ETag is not guaranteed to be the same as the MD5 hash of the object
@@ -175,6 +182,10 @@ if (list) {
 
 // delete the object
 const wasDeleted: boolean = await s3client.deleteObject(smallObjectKey);
+// to delete multiple objects, use deleteObjects method
+// const keysToDelete: string[] = ['object1.txt', 'object2.txt'];
+// const deletedArray: boolean[] = await s3client.deleteObjects(keysToDelete);
+// Note: deleteObjects returns an array of booleans, one for each key, indicating if the object was deleted or not
 
 // Multipart upload
 const multipartKey = 'multipart-object.txt';

package/dist/s3mini.d.ts

@@ -7,6 +7,11 @@ interface S3Config {
     requestAbortTimeout?: number;
     logger?: Logger;
 }
+interface SSECHeaders {
+    'x-amz-server-side-encryption-customer-algorithm': string;
+    'x-amz-server-side-encryption-customer-key': string;
+    'x-amz-server-side-encryption-customer-key-md5': string;
+}
 interface Logger {
     info: (message: string, ...args: unknown[]) => void;
     warn: (message: string, ...args: unknown[]) => void;
@@ -16,6 +21,13 @@ interface UploadPart {
     partNumber: number;
     etag: string;
 }
+interface ListObject {
+    Key: string;
+    Size: number;
+    LastModified: Date;
+    ETag: string;
+    StorageClass: string;
+}
 interface CompleteMultipartUploadResult {
     location: string;
     bucket: string;
@@ -92,7 +104,7 @@ type ExistResponseCode = false | true | null;
  * // Delete a file
  * await s3.deleteObject('example.txt');
  */
-declare class s3mini {
+declare class S3mini {
     /**
      * Creates an instance of the S3 class.
      *
@@ -192,7 +204,7 @@ declare class s3mini {
      * @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<object[] | null>} A promise that resolves to an array of objects or null if the bucket is empty.
+     * @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();
@@ -200,7 +212,7 @@ declare class s3mini {
      * // List objects with prefix
      * const photos = await s3.listObjects('/', 'photos/', 100);
      */
-    listObjects(delimiter?: string, prefix?: string, maxKeys?: number, opts?: Record<string, unknown>): Promise<object[] | null>;
+    listObjects(delimiter?: string, prefix?: string, maxKeys?: number, opts?: Record<string, unknown>): Promise<ListObject[] | null>;
     /**
      * Lists multipart uploads in the bucket.
      * This method sends a request to list multipart uploads in the specified bucket.
@@ -215,42 +227,47 @@ declare class s3mini {
      * 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 {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.
      */
-    getObject(key: string, opts?: Record<string, unknown>): Promise<string | null>;
+    getObject(key: string, opts?: Record<string, unknown>, ssecHeaders?: SSECHeaders): Promise<string | null>;
     /**
      * 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.
      */
-    getObjectResponse(key: string, opts?: Record<string, unknown>): Promise<Response | null>;
+    getObjectResponse(key: string, opts?: Record<string, unknown>, ssecHeaders?: SSECHeaders): Promise<Response | null>;
     /**
      * 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.
      */
-    getObjectArrayBuffer(key: string, opts?: Record<string, unknown>): Promise<ArrayBuffer | null>;
+    getObjectArrayBuffer(key: string, opts?: Record<string, unknown>, ssecHeaders?: SSECHeaders): Promise<ArrayBuffer | null>;
     /**
      * 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.
      */
-    getObjectJSON<T = unknown>(key: string, opts?: Record<string, unknown>): Promise<T | null>;
+    getObjectJSON<T = unknown>(key: string, opts?: Record<string, unknown>, ssecHeaders?: SSECHeaders): Promise<T | null>;
     /**
      * 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.
      */
-    getObjectWithETag(key: string, opts?: Record<string, unknown>): Promise<{
+    getObjectWithETag(key: string, opts?: Record<string, unknown>, ssecHeaders?: SSECHeaders): Promise<{
         etag: string | null;
         data: ArrayBuffer | null;
     }>;
@@ -262,9 +279,10 @@ declare class s3mini {
      * @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.
      */
-    getObjectRaw(key: string, wholeFile?: boolean, rangeFrom?: number, rangeTo?: number, opts?: Record<string, unknown>): Promise<Response>;
+    getObjectRaw(key: string, wholeFile?: boolean, rangeFrom?: number, rangeTo?: number, opts?: Record<string, unknown>, ssecHeaders?: SSECHeaders): Promise<Response>;
     /**
      * Get the content length of an object.
      * This method sends a HEAD request to retrieve the content length of the specified object.
@@ -272,7 +290,7 @@ declare class s3mini {
      * @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.
      */
-    getContentLength(key: string): Promise<number>;
+    getContentLength(key: string, ssecHeaders?: SSECHeaders): Promise<number>;
     /**
      * Checks if an object exists in the S3-compatible service.
      * This method sends a HEAD request to check if the specified object exists.
@@ -285,6 +303,7 @@ declare class s3mini {
      * 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
@@ -293,12 +312,13 @@ declare class s3mini {
      *   console.log(`File ETag: ${etag}`);
      * }
      */
-    getEtag(key: string, opts?: Record<string, unknown>): Promise<string | null>;
+    getEtag(key: string, opts?: Record<string, unknown>, ssecHeaders?: SSECHeaders): Promise<string | null>;
     /**
      * 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
@@ -309,11 +329,12 @@ declare class s3mini {
      * const buffer = Buffer.from([0x89, 0x50, 0x4e, 0x47]);
      * await s3.putObject('image.png', buffer, 'image/png');
      */
-    putObject(key: string, data: string | Buffer, fileType?: string): Promise<Response>;
+    putObject(key: string, data: string | Buffer, fileType?: string, ssecHeaders?: SSECHeaders): Promise<Response>;
     /**
      * 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.
@@ -321,7 +342,7 @@ declare class s3mini {
      * const uploadId = await s3.getMultipartUploadId('large-file.zip', 'application/zip');
      * console.log(`Started multipart upload: ${uploadId}`);
      */
-    getMultipartUploadId(key: string, fileType?: string): Promise<string>;
+    getMultipartUploadId(key: string, fileType?: string, ssecHeaders?: SSECHeaders): Promise<string>;
     /**
      * Uploads a part in a multipart upload.
      * @param {string} key - The key of the object being uploaded.
@@ -329,6 +350,7 @@ declare class s3mini {
      * @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
@@ -340,7 +362,7 @@ declare class s3mini {
      * );
      * console.log(`Part ${part.partNumber} uploaded with ETag: ${part.etag}`);
      */
-    uploadPart(key: string, uploadId: string, data: Buffer | string, partNumber: number, opts?: Record<string, unknown>): Promise<UploadPart>;
+    uploadPart(key: string, uploadId: string, data: Buffer | string, partNumber: number, opts?: Record<string, unknown>, ssecHeaders?: SSECHeaders): Promise<UploadPart>;
     /**
      * Completes a multipart upload by combining all uploaded parts.
      * @param {string} key - The key of the object being uploaded.
@@ -364,6 +386,7 @@ declare class s3mini {
      * 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.
@@ -375,7 +398,7 @@ declare class s3mini {
      *   console.error('Failed to abort upload:', error);
      * }
      */
-    abortMultipartUpload(key: string, uploadId: string): Promise<object>;
+    abortMultipartUpload(key: string, uploadId: string, ssecHeaders?: SSECHeaders): Promise<object>;
     private _buildCompleteMultipartUploadXml;
     /**
      * Deletes an object from the bucket.
@@ -396,6 +419,10 @@ declare class s3mini {
     private _buildCanonicalQueryString;
     private _getSignatureKey;
 }
+/**
+ * @deprecated Use `S3mini` instead.
+ */
+declare const s3mini: typeof S3mini;
 
 /**
  * Sanitize ETag value by removing quotes and XML entities
@@ -414,4 +441,5 @@ declare const sanitizeETag: (etag: string) => string;
  */
 declare const runInBatches: <T = unknown>(tasks: Iterable<() => Promise<T>>, batchSize?: number, minIntervalMs?: number) => Promise<Array<PromiseSettledResult<T>>>;
 
-export { type CompleteMultipartUploadResult, type ErrorWithCode, type ExistResponseCode, type ListBucketResponse, type ListMultipartUploadResponse, type Logger, type S3Config, type UploadPart, s3mini as default, runInBatches, s3mini, sanitizeETag };
+export { S3mini, S3mini as default, runInBatches, s3mini, sanitizeETag };
+export type { CompleteMultipartUploadResult, ErrorWithCode, ExistResponseCode, ListBucketResponse, ListMultipartUploadResponse, Logger, S3Config, UploadPart };

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] ';
@@ -241,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.
      *
@@ -425,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(';');
@@ -440,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('/');
@@ -485,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: {} };
@@ -603,7 +604,7 @@ class s3mini {
      * @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<object[] | null>} A promise that resolves to an array of objects or null if the bucket is empty.
+     * @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();
@@ -709,11 +710,17 @@ class s3mini {
      * 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 {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 = {}) {
-        const res = await this._signedRequest('GET', key, { query: opts, tolerated: [200, 404, 412, 304] });
+    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;
         }
@@ -724,10 +731,15 @@ class s3mini {
      * 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 = {}) {
-        const res = await this._signedRequest('GET', key, { query: opts, tolerated: [200, 404, 412, 304] });
+    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;
         }
@@ -738,10 +750,15 @@ class s3mini {
      * 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 = {}) {
-        const res = await this._signedRequest('GET', key, { query: opts, tolerated: [200, 404, 412, 304] });
+    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;
         }
@@ -752,10 +769,15 @@ class s3mini {
      * 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 = {}) {
-        const res = await this._signedRequest('GET', key, { query: opts, tolerated: [200, 404, 412, 304] });
+    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;
         }
@@ -766,11 +788,16 @@ class s3mini {
      * 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 = {}) {
+    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 };
             }
@@ -793,13 +820,14 @@ class s3mini {
      * @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 = {}) {
+    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
         });
     }
@@ -810,9 +838,11 @@ class s3mini {
      * @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) {
+    async getContentLength(key, ssecHeaders) {
         try {
-            const res = await this._signedRequest('HEAD', key);
+            const res = await this._signedRequest('HEAD', key, {
+                headers: ssecHeaders ? { ...ssecHeaders } : undefined,
+            });
             const len = res.headers.get(HEADER_CONTENT_LENGTH);
             return len ? +len : 0;
         }
@@ -845,6 +875,7 @@ class s3mini {
      * 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
@@ -853,14 +884,18 @@ class s3mini {
      *   console.log(`File ETag: ${etag}`);
      * }
      */
-    async getEtag(key, opts = {}) {
+    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(`${ERROR_PREFIX}ETag not found in response headers`);
@@ -872,6 +907,7 @@ class s3mini {
      * @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
@@ -882,7 +918,7 @@ class s3mini {
      * 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) {
+    async putObject(key, data, fileType = DEFAULT_STREAM_CONTENT_TYPE, ssecHeaders) {
         if (!(data instanceof Buffer || typeof data === 'string')) {
             throw new TypeError(ERROR_DATA_BUFFER_REQUIRED);
         }
@@ -891,6 +927,7 @@ class s3mini {
             headers: {
                 [HEADER_CONTENT_LENGTH]: typeof data === 'string' ? Buffer.byteLength(data) : data.length,
                 [HEADER_CONTENT_TYPE]: fileType,
+                ...ssecHeaders,
             },
             tolerated: [200],
         });
@@ -899,6 +936,7 @@ class s3mini {
      * 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.
@@ -906,13 +944,13 @@ class s3mini {
      * const uploadId = await s3.getMultipartUploadId('large-file.zip', 'application/zip');
      * console.log(`Started multipart upload: ${uploadId}`);
      */
-    async getMultipartUploadId(key, fileType = DEFAULT_STREAM_CONTENT_TYPE) {
+    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,
@@ -949,6 +987,7 @@ class s3mini {
      * @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
@@ -960,13 +999,16 @@ class s3mini {
      * );
      * console.log(`Part ${part.partNumber} uploaded with ETag: ${part.etag}`);
      */
-    async uploadPart(key, uploadId, data, partNumber, opts = {}) {
+    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') || '') };
     }
@@ -1024,6 +1066,7 @@ class s3mini {
      * 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.
@@ -1035,13 +1078,13 @@ class s3mini {
      *   console.error('Failed to abort upload:', error);
      * }
      */
-    async abortMultipartUpload(key, uploadId) {
+    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,
@@ -1213,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