s3mini 0.3.0 → 0.5.0

package/README.md

@@ -23,6 +23,12 @@ Dev:
 ![GitHub commit activity (branch)](https://img.shields.io/github/commit-activity/m/good-lly/s3mini/dev?color=greeen)
 ![GitHub Issues or Pull Requests](https://img.shields.io/github/issues/good-lly/s3mini)
 [![CodeQL Advanced](https://github.com/good-lly/s3mini/actions/workflows/codeql.yml/badge.svg?branch=dev)](https://github.com/good-lly/s3mini/actions/workflows/codeql.yml)
+[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=good-lly_s3mini&metric=bugs)](https://sonarcloud.io/summary/new_code?id=good-lly_s3mini)
+[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=good-lly_s3mini&metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=good-lly_s3mini)
+[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=good-lly_s3mini&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=good-lly_s3mini)
+[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=good-lly_s3mini&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=good-lly_s3mini)
+[![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=good-lly_s3mini&metric=sqale_index)](https://sonarcloud.io/summary/new_code?id=good-lly_s3mini)
+[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=good-lly_s3mini&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=good-lly_s3mini)
 [![Test:e2e(all)](https://github.com/good-lly/s3mini/actions/workflows/test-e2e.yml/badge.svg?branch=dev)](https://github.com/good-lly/s3mini/actions/workflows/test-e2e.yml)
 
 ![GitHub Repo stars](https://img.shields.io/github/stars/good-lly/s3mini?style=social)
@@ -60,6 +66,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 +75,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 +108,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 +162,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 +188,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,14 @@ 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 AWSHeaders {
+    [k: `x-amz-${string}`]: string;
+}
 interface Logger {
     info: (message: string, ...args: unknown[]) => void;
     warn: (message: string, ...args: unknown[]) => void;
@@ -16,6 +24,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;
@@ -45,7 +60,7 @@ interface ListMultipartUploadSuccess {
         key: string;
         uploadId: string;
         size?: number;
-        mtime?: Date | undefined;
+        mtime?: Date;
         etag?: string;
         eTag?: string;
         parts: UploadPart[];
@@ -68,6 +83,55 @@ interface ErrorWithCode {
 type ListMultipartUploadResponse = ListMultipartUploadSuccess | MultipartUploadError;
 type HttpMethod = 'POST' | 'GET' | 'HEAD' | 'PUT' | 'DELETE';
 type ExistResponseCode = false | true | null;
+interface CopyObjectOptions {
+    /**
+     * Specifies whether the metadata is copied from the source object or replaced with metadata provided in the request.
+     * Valid values: 'COPY' | 'REPLACE'
+     * Default: 'COPY'
+     */
+    metadataDirective?: 'COPY' | 'REPLACE';
+    /**
+     * Metadata to be set on the destination object when metadataDirective is 'REPLACE'.
+     * Keys can be provided with or without 'x-amz-meta-' prefix.
+     */
+    metadata?: Record<string, string>;
+    contentType?: string;
+    /**
+     * Storage class for the destination object.
+     * Valid values: 'STANDARD' | 'REDUCED_REDUNDANCY' | 'STANDARD_IA' | 'ONEZONE_IA' | 'INTELLIGENT_TIERING' | 'GLACIER' | 'DEEP_ARCHIVE' | 'GLACIER_IR'
+     */
+    storageClass?: string;
+    /**
+     * Specifies whether the object tag-set is copied from the source object or replaced with tag-set provided in the request.
+     * Valid values: 'COPY' | 'REPLACE'
+     */
+    taggingDirective?: 'COPY' | 'REPLACE';
+    /**
+     * If the bucket is configured as a website, redirects requests for this object to another object or URL.
+     */
+    websiteRedirectLocation?: string;
+    /**
+     * Server-Side Encryption with Customer-Provided Keys headers for the source object.
+     * Should include:
+     * - x-amz-copy-source-server-side-encryption-customer-algorithm
+     * - x-amz-copy-source-server-side-encryption-customer-key
+     * - x-amz-copy-source-server-side-encryption-customer-key-MD5
+     */
+    sourceSSECHeaders?: Record<string, string | number>;
+    destinationSSECHeaders?: SSECHeaders;
+    additionalHeaders?: Record<string, string | number>;
+}
+interface CopyObjectResult {
+    etag: string;
+    lastModified?: Date;
+}
+/**
+ * Where Buffer is available, e.g. when @types/node is loaded, we want to use it.
+ * But it should be excluded in other environments (e.g. Cloudflare).
+ */
+type MaybeBuffer = typeof globalThis extends {
+    Buffer?: infer B;
+} ? B extends new (...a: unknown[]) => unknown ? InstanceType<B> : ArrayBuffer | Uint8Array : ArrayBuffer | Uint8Array;
 
 /**
  * S3 class for interacting with S3-compatible object storage services.
@@ -79,8 +143,8 @@ type ExistResponseCode = false | true | null;
  * const s3 = new CoreS3({
  *   accessKeyId: 'your-access-key',
  *   secretAccessKey: 'your-secret-key',
- *   endpoint: 'https://your-s3-endpoint.com',
- *   region: 'us-east-1' // by default is auto
+ *   endpoint: 'https://your-s3-endpoint.com/bucket-name',
+ *   region: 'auto' // by default is auto
  * });
  *
  * // Upload a file
@@ -92,7 +156,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.
      *
@@ -107,13 +171,14 @@ declare class s3mini {
      * @param {Object} [config.logger=null] - A logger object with methods like info, warn, error.
      * @throws {TypeError} Will throw an error if required parameters are missing or of incorrect type.
      */
-    private accessKeyId;
-    private secretAccessKey;
-    private endpoint;
-    private region;
-    private requestSizeInBytes;
-    private requestAbortTimeout?;
-    private logger?;
+    readonly accessKeyId: string;
+    readonly secretAccessKey: string;
+    readonly endpoint: URL;
+    readonly region: string;
+    readonly bucketName: string;
+    readonly requestSizeInBytes: number;
+    readonly requestAbortTimeout?: number;
+    readonly logger?: Logger;
     private signingKeyDate?;
     private signingKey?;
     constructor({ accessKeyId, secretAccessKey, endpoint, region, requestSizeInBytes, requestAbortTimeout, logger, }: S3Config);
@@ -127,43 +192,10 @@ declare class s3mini {
     private _checkPrefix;
     private _checkOpts;
     private _filterIfHeaders;
+    private _validateData;
     private _validateUploadPartParams;
     private _sign;
-    private _buildCanonicalHeaders;
-    private _buildCanonicalRequest;
-    private _buildCredentialScope;
-    private _buildStringToSign;
-    private _calculateSignature;
-    private _buildAuthorizationHeader;
     private _signedRequest;
-    /**
-     * 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(): S3Config;
-    /**
-     * 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: S3Config): void;
     /**
      * 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
@@ -179,6 +211,7 @@ declare class s3mini {
      * @returns A promise that resolves to true if the bucket was created successfully, false otherwise.
      */
     createBucket(): Promise<boolean>;
+    private _extractBucketName;
     /**
      * Checks if a bucket exists.
      * This method sends a request to check if the specified bucket exists in the S3-compatible service.
@@ -192,7 +225,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 +233,13 @@ 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>;
+    private _fetchObjectBatch;
+    private _buildListObjectsQuery;
+    private _handleListObjectsError;
+    private _parseListObjectsResponse;
+    private _extractObjectsFromResponse;
+    private _extractContinuationToken;
     /**
      * Lists multipart uploads in the bucket.
      * This method sends a request to list multipart uploads in the specified bucket.
@@ -215,42 +254,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 +306,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 +317,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 +330,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 +339,14 @@ 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.
+     * @param {IT.AWSHeaders} [additionalHeaders] - Additional x-amz-* headers specific to this request, 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 +357,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 | MaybeBuffer, fileType?: string, ssecHeaders?: SSECHeaders, additionalHeaders?: AWSHeaders): 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 +370,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 +378,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 +390,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: MaybeBuffer | 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 +414,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,8 +426,111 @@ 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;
+    /**
+     * Executes the copy operation for local copying (same bucket/endpoint).
+     * @private
+     */
+    private _executeCopyOperation;
+    /**
+     * Copies an object within the same bucket.
+     *
+     * @param {string} sourceKey - The key of the source object to copy
+     * @param {string} destinationKey - The key where the object will be copied to
+     * @param {IT.CopyObjectOptions} [options={}] - Copy operation options
+     * @param {string} [options.metadataDirective='COPY'] - How to handle metadata ('COPY' | 'REPLACE')
+     * @param {Record<string,string>} [options.metadata={}] - New metadata (only used if metadataDirective='REPLACE')
+     * @param {string} [options.contentType] - New content type for the destination object
+     * @param {string} [options.storageClass] - Storage class for the destination object
+     * @param {string} [options.taggingDirective] - How to handle object tags ('COPY' | 'REPLACE')
+     * @param {string} [options.websiteRedirectLocation] - Website redirect location for the destination
+     * @param {IT.SSECHeaders} [options.sourceSSECHeaders={}] - Encryption headers for reading source (if encrypted)
+     * @param {IT.SSECHeaders} [options.destinationSSECHeaders={}] - Encryption headers for destination
+     * @param {IT.AWSHeaders} [options.additionalHeaders={}] - Extra x-amz-* headers
+     *
+     * @returns {Promise<IT.CopyObjectResult>} Copy result with etag and lastModified date
+     * @throws {TypeError} If sourceKey or destinationKey is invalid
+     * @throws {Error} If copy operation fails or S3 returns an error
+     *
+     * @example
+     * // Simple copy
+     * const result = await s3.copyObject('report-2024.pdf', 'archive/report-2024.pdf');
+     * console.log(`Copied with ETag: ${result.etag}`);
+     *
+     * @example
+     * // Copy with new metadata and content type
+     * const result = await s3.copyObject('data.csv', 'processed/data.csv', {
+     *   metadataDirective: 'REPLACE',
+     *   metadata: {
+     *     'processed-date': new Date().toISOString(),
+     *     'original-name': 'data.csv'
+     *   },
+     *   contentType: 'text/csv; charset=utf-8'
+     * });
+     *
+     * @example
+     * // Copy encrypted object (Cloudflare R2 SSE-C)
+     * const ssecKey = 'n1TKiTaVHlYLMX9n0zHXyooMr026vOiTEFfT+719Hho=';
+     * await s3.copyObject('sensitive.json', 'backup/sensitive.json', {
+     *   sourceSSECHeaders: {
+     *     'x-amz-copy-source-server-side-encryption-customer-algorithm': 'AES256',
+     *     'x-amz-copy-source-server-side-encryption-customer-key': ssecKey,
+     *     'x-amz-copy-source-server-side-encryption-customer-key-md5': 'gepZmzgR7Be/1+K1Aw+6ow=='
+     *   },
+     *   destinationSSECHeaders: {
+     *     'x-amz-server-side-encryption-customer-algorithm': 'AES256',
+     *     'x-amz-server-side-encryption-customer-key': ssecKey,
+     *     'x-amz-server-side-encryption-customer-key-md5': 'gepZmzgR7Be/1+K1Aw+6ow=='
+     *   }
+     * });
+     */
+    copyObject(sourceKey: string, destinationKey: string, options?: CopyObjectOptions): Promise<CopyObjectResult>;
+    private _buildSSECHeaders;
+    /**
+     * Moves an object within the same bucket (copy + delete atomic-like operation).
+     *
+     * WARNING: Not truly atomic - if delete fails after successful copy, the object
+     * will exist in both locations. Consider your use case carefully.
+     *
+     * @param {string} sourceKey - The key of the source object to move
+     * @param {string} destinationKey - The key where the object will be moved to
+     * @param {IT.CopyObjectOptions} [options={}] - Options passed to the copy operation
+     *
+     * @returns {Promise<IT.CopyObjectResult>} Result from the copy operation
+     * @throws {TypeError} If sourceKey or destinationKey is invalid
+     * @throws {Error} If copy succeeds but delete fails (includes copy result in error)
+     *
+     * @example
+     * // Simple move
+     * await s3.moveObject('temp/upload.tmp', 'files/document.pdf');
+     *
+     * @example
+     * // Move with metadata update
+     * await s3.moveObject('unprocessed/image.jpg', 'processed/image.jpg', {
+     *   metadataDirective: 'REPLACE',
+     *   metadata: {
+     *     'status': 'processed',
+     *     'processed-at': Date.now().toString()
+     *   },
+     *   contentType: 'image/jpeg'
+     * });
+     *
+     * @example
+     * // Safe move with error handling
+     * try {
+     *   const result = await s3.moveObject('inbox/file.dat', 'archive/file.dat');
+     *   console.log(`Moved successfully: ${result.etag}`);
+     * } catch (error) {
+     *   // Check if copy succeeded but delete failed
+     *   if (error.message.includes('delete source object after successful copy')) {
+     *     console.warn('File copied but not deleted from source - manual cleanup needed');
+     *   }
+     * }
+     */
+    moveObject(sourceKey: string, destinationKey: string, options?: CopyObjectOptions): Promise<CopyObjectResult>;
+    private _buildMetadataHeaders;
+    private _parseCopyObjectResponse;
     /**
      * Deletes an object from the bucket.
      * This method sends a request to delete the specified object from the bucket.
@@ -392,6 +546,7 @@ declare class s3mini {
      */
     deleteObjects(keys: string[]): Promise<boolean[]>;
     private _sendRequest;
+    private _parseErrorXml;
     private _handleErrorResponse;
     private _buildCanonicalQueryString;
     private _getSignatureKey;
@@ -414,4 +569,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, sanitizeETag };
+export type { CompleteMultipartUploadResult, ErrorWithCode, ExistResponseCode, ListBucketResponse, ListMultipartUploadResponse, Logger, S3Config, UploadPart };