s3mini 0.4.0 → 0.6.0

package/src/S3.ts

@@ -14,8 +14,8 @@ import * as U from './utils.js';
  * 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
@@ -42,15 +42,16 @@ 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: string;
-  private secretAccessKey: string;
-  private endpoint: string;
-  private region: string;
-  private requestSizeInBytes: number;
-  private requestAbortTimeout?: number;
-  private logger?: IT.Logger;
+  readonly accessKeyId: string;
+  readonly secretAccessKey: string;
+  readonly endpoint: URL;
+  readonly region: string;
+  readonly bucketName: string;
+  readonly requestSizeInBytes: number;
+  readonly requestAbortTimeout?: number;
+  readonly logger?: IT.Logger;
   private signingKeyDate?: string;
-  private signingKey?: Buffer;
+  private signingKey?: ArrayBuffer;
 
   constructor({
     accessKeyId,
@@ -64,8 +65,9 @@ class S3mini {
     this._validateConstructorParams(accessKeyId, secretAccessKey, endpoint);
     this.accessKeyId = accessKeyId;
     this.secretAccessKey = secretAccessKey;
-    this.endpoint = this._ensureValidUrl(endpoint);
+    this.endpoint = new URL(this._ensureValidUrl(endpoint));
     this.region = region;
+    this.bucketName = this._extractBucketName();
     this.requestSizeInBytes = requestSizeInBytes;
     this.requestAbortTimeout = requestAbortTimeout;
     this.logger = logger;
@@ -112,7 +114,7 @@ class S3mini {
         // Include some general context, but sanitize sensitive parts
         context: this._sanitize({
           region: this.region,
-          endpoint: this.endpoint,
+          endpoint: this.endpoint.toString(),
           // Only include the first few characters of the access key, if it exists
           accessKeyId: this.accessKeyId ? `${this.accessKeyId.substring(0, 4)}...` : undefined,
         }),
@@ -215,18 +217,22 @@ class S3mini {
     return { filteredOpts, conditionalHeaders };
   }
 
+  private _validateData(data: unknown): BodyInit {
+    if (!((globalThis.Buffer && data instanceof globalThis.Buffer) || typeof data === 'string')) {
+      this._log('error', C.ERROR_DATA_BUFFER_REQUIRED);
+      throw new TypeError(C.ERROR_DATA_BUFFER_REQUIRED);
+    }
+    return data;
+  }
+
   private _validateUploadPartParams(
     key: string,
     uploadId: string,
-    data: Buffer | string,
+    data: IT.MaybeBuffer | string,
     partNumber: number,
     opts: object,
-  ): void {
+  ): BodyInit {
     this._checkKey(key);
-    if (!(data instanceof Buffer || typeof data === 'string')) {
-      this._log('error', C.ERROR_DATA_BUFFER_REQUIRED);
-      throw new TypeError(C.ERROR_DATA_BUFFER_REQUIRED);
-    }
     if (typeof uploadId !== 'string' || uploadId.trim().length === 0) {
       this._log('error', C.ERROR_UPLOAD_ID_REQUIRED);
       throw new TypeError(C.ERROR_UPLOAD_ID_REQUIRED);
@@ -236,14 +242,15 @@ class S3mini {
       throw new TypeError(`${C.ERROR_PREFIX}partNumber must be a positive integer`);
     }
     this._checkOpts(opts);
+    return this._validateData(data);
   }
 
-  private _sign(
+  private async _sign(
     method: IT.HttpMethod,
     keyPath: string,
     query: Record<string, unknown> = {},
     headers: Record<string, string | number> = {},
-  ): { url: string; headers: Record<string, string | number> } {
+  ): Promise<{ url: string; headers: Record<string, string | number> }> {
     // Create URL without appending keyPath first
     const url = new URL(this.endpoint);
 
@@ -253,82 +260,45 @@ class S3mini {
         url.pathname === '/' ? `/${keyPath.replace(/^\/+/, '')}` : `${url.pathname}/${keyPath.replace(/^\/+/, '')}`;
     }
 
-    const fullDatetime = new Date().toISOString().replace(/[:-]|\.\d{3}/g, '');
-    const shortDatetime = fullDatetime.slice(0, 8);
-    const credentialScope = this._buildCredentialScope(shortDatetime);
+    const d = new Date();
+    const year = d.getUTCFullYear();
+    const month = String(d.getUTCMonth() + 1).padStart(2, '0');
+    const day = String(d.getUTCDate()).padStart(2, '0');
+
+    const shortDatetime = `${year}${month}${day}`;
+    const fullDatetime = `${shortDatetime}T${String(d.getUTCHours()).padStart(2, '0')}${String(d.getUTCMinutes()).padStart(2, '0')}${String(d.getUTCSeconds()).padStart(2, '0')}Z`;
+    const credentialScope = `${shortDatetime}/${this.region}/${C.S3_SERVICE}/${C.AWS_REQUEST_TYPE}`;
 
-    headers[C.HEADER_AMZ_CONTENT_SHA256] = C.UNSIGNED_PAYLOAD; // body ? U.hash(body) : C.UNSIGNED_PAYLOAD;
+    headers[C.HEADER_AMZ_CONTENT_SHA256] = C.UNSIGNED_PAYLOAD;
     headers[C.HEADER_AMZ_DATE] = fullDatetime;
     headers[C.HEADER_HOST] = url.host;
-    // 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(';');
-
-    const canonicalRequest = this._buildCanonicalRequest(method, url, query, canonicalHeaders, signedHeaders);
-    const stringToSign = this._buildStringToSign(fullDatetime, credentialScope, canonicalRequest);
-    const signature = this._calculateSignature(shortDatetime, stringToSign);
-    const authorizationHeader = this._buildAuthorizationHeader(credentialScope, signedHeaders, signature);
-    headers[C.HEADER_AUTHORIZATION] = authorizationHeader;
-    return { url: url.toString(), headers };
-  }
-
-  private _buildCanonicalHeaders(headers: Record<string, string | number>): string {
-    return Object.entries(headers)
-      .map(([key, value]) => `${key.toLowerCase()}:${String(value).trim()}`)
-      .join('\n');
-  }
-
-  private _buildCanonicalRequest(
-    method: IT.HttpMethod,
-    url: URL,
-    query: Record<string, unknown>,
-    canonicalHeaders: string,
-    signedHeaders: string,
-  ): string {
-    const parts = [
-      method,
-      url.pathname,
-      this._buildCanonicalQueryString(query),
-      canonicalHeaders + '\n', // Canonical headers end with extra newline
-      signedHeaders,
-      C.UNSIGNED_PAYLOAD,
-    ];
-    return parts.join('\n');
-  }
+    const ignoredHeaders = new Set(['authorization', 'content-length', 'content-type', 'user-agent']);
 
-  private _buildCredentialScope(shortDatetime: string): string {
-    return [shortDatetime, this.region, C.S3_SERVICE, C.AWS_REQUEST_TYPE].join('/');
-  }
-
-  private _buildStringToSign(fullDatetime: string, credentialScope: string, canonicalRequest: string): string {
-    return [C.AWS_ALGORITHM, fullDatetime, credentialScope, U.hash(canonicalRequest)].join('\n');
-  }
+    let canonicalHeaders = '';
+    let signedHeaders = '';
 
-  private _calculateSignature(shortDatetime: string, stringToSign: string): string {
-    if (shortDatetime !== this.signingKeyDate) {
+    for (const [key, value] of Object.entries(headers).sort(([a], [b]) => a.localeCompare(b))) {
+      const lowerKey = key.toLowerCase();
+      if (!ignoredHeaders.has(lowerKey)) {
+        if (canonicalHeaders) {
+          canonicalHeaders += '\n';
+          signedHeaders += ';';
+        }
+        canonicalHeaders += `${lowerKey}:${String(value).trim()}`;
+        signedHeaders += lowerKey;
+      }
+    }
+    const canonicalRequest = `${method}\n${url.pathname}\n${this._buildCanonicalQueryString(query)}\n${canonicalHeaders}\n\n${signedHeaders}\n${C.UNSIGNED_PAYLOAD}`;
+    const stringToSign = `${C.AWS_ALGORITHM}\n${fullDatetime}\n${credentialScope}\n${U.hexFromBuffer(await U.sha256(canonicalRequest))}`;
+    if (shortDatetime !== this.signingKeyDate || !this.signingKey) {
       this.signingKeyDate = shortDatetime;
-      this.signingKey = this._getSignatureKey(shortDatetime);
+      this.signingKey = await this._getSignatureKey(shortDatetime);
     }
-    return U.hmac(this.signingKey!, stringToSign, 'hex') as string;
-  }
-
-  private _buildAuthorizationHeader(credentialScope: string, signedHeaders: string, signature: string): string {
-    return [
-      `${C.AWS_ALGORITHM} Credential=${this.accessKeyId}/${credentialScope}`,
-      `SignedHeaders=${signedHeaders}`,
-      `Signature=${signature}`,
-    ].join(', ');
+    const signature = U.hexFromBuffer(await U.hmac(this.signingKey!, stringToSign));
+    headers[C.HEADER_AUTHORIZATION] =
+      `${C.AWS_ALGORITHM} Credential=${this.accessKeyId}/${credentialScope}, SignedHeaders=${signedHeaders}, Signature=${signature}`;
+    return { url: url.toString(), headers };
   }
 
   private async _signedRequest(
@@ -336,22 +306,22 @@ class S3mini {
     key: string, // ‘’ allowed for bucket‑level ops
     {
       query = {}, // ?query=string
-      body = '', // string | Buffer | undefined
+      body = '', // BodyInit | undefined
       headers = {}, // extra/override headers
       tolerated = [], // [200, 404] etc.
       withQuery = false, // append query string to signed URL
     }: {
-      query?: Record<string, unknown> | undefined;
-      body?: string | Buffer | undefined;
-      headers?: Record<string, string | number | undefined> | IT.SSECHeaders | undefined;
-      tolerated?: number[] | undefined;
-      withQuery?: boolean | undefined;
+      query?: Record<string, unknown>;
+      body?: BodyInit;
+      headers?: Record<string, string | number | undefined> | IT.SSECHeaders | IT.AWSHeaders;
+      tolerated?: number[];
+      withQuery?: boolean;
     } = {},
   ): Promise<Response> {
     // Basic validation
-    if (!['GET', 'HEAD', 'PUT', 'POST', 'DELETE'].includes(method)) {
-      throw new Error(`${C.ERROR_PREFIX}Unsupported HTTP method ${method as string}`);
-    }
+    // if (!['GET', 'HEAD', 'PUT', 'POST', 'DELETE'].includes(method)) {
+    //   throw new Error(`${C.ERROR_PREFIX}Unsupported HTTP method ${method as string}`);
+    // }
 
     const { filteredOpts, conditionalHeaders } = ['GET', 'HEAD'].includes(method)
       ? this._filterIfHeaders(query)
@@ -364,7 +334,7 @@ class S3mini {
     };
 
     const encodedKey = key ? U.uriResourceEscape(key) : '';
-    const { url, headers: signedHeaders } = this._sign(method, encodedKey, filteredOpts, baseHeaders);
+    const { url, headers: signedHeaders } = await this._sign(method, encodedKey, filteredOpts, baseHeaders);
     if (Object.keys(query).length > 0) {
       withQuery = true; // append query string to signed URL
     }
@@ -379,55 +349,6 @@ class S3mini {
     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'
-   */
-  public getProps(): IT.S3Config {
-    return {
-      accessKeyId: this.accessKeyId,
-      secretAccessKey: this.secretAccessKey,
-      endpoint: this.endpoint,
-      region: this.region,
-      requestSizeInBytes: this.requestSizeInBytes,
-      requestAbortTimeout: this.requestAbortTimeout,
-      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
-   * });
-   */
-  public setProps(props: IT.S3Config): void {
-    this._validateConstructorParams(props.accessKeyId, props.secretAccessKey, props.endpoint);
-    this.accessKeyId = props.accessKeyId;
-    this.secretAccessKey = props.secretAccessKey;
-    this.region = props.region || 'auto';
-    this.endpoint = props.endpoint;
-    this.requestSizeInBytes = props.requestSizeInBytes || C.DEFAULT_REQUEST_SIZE_IN_BYTES;
-    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
@@ -453,7 +374,7 @@ class S3mini {
     `;
     const headers = {
       [C.HEADER_CONTENT_TYPE]: C.XML_CONTENT_TYPE,
-      [C.HEADER_CONTENT_LENGTH]: Buffer.byteLength(xmlBody).toString(),
+      [C.HEADER_CONTENT_LENGTH]: U.getByteSize(xmlBody),
     };
     const res = await this._signedRequest('PUT', '', {
       body: xmlBody,
@@ -463,6 +384,42 @@ class S3mini {
     return res.status === 200;
   }
 
+  private _extractBucketName(): string {
+    const url = this.endpoint;
+
+    // First check if bucket is in the pathname (path-style URLs)
+    const pathSegments = url.pathname.split('/').filter(p => p);
+    if (pathSegments.length > 0) {
+      if (typeof pathSegments[0] === 'string') {
+        return pathSegments[0];
+      }
+    }
+
+    // Otherwise extract from subdomain (virtual-hosted-style URLs)
+    const hostParts = url.hostname.split('.');
+
+    // Common patterns:
+    // bucket-name.s3.amazonaws.com
+    // bucket-name.s3.region.amazonaws.com
+    // bucket-name.region.digitaloceanspaces.com
+    // bucket-name.region.cdn.digitaloceanspaces.com
+
+    if (hostParts.length >= 3) {
+      // Check if it's a known S3-compatible service
+      const domain = hostParts.slice(-2).join('.');
+      const knownDomains = ['amazonaws.com', 'digitaloceanspaces.com', 'cloudflare.com'];
+
+      if (knownDomains.some(d => domain.includes(d))) {
+        if (typeof hostParts[0] === 'string') {
+          return hostParts[0];
+        }
+      }
+    }
+
+    // Fallback: use the first subdomain
+    return hostParts[0] || '';
+  }
+
   /**
    * Checks if a bucket exists.
    * This method sends a request to check if the specified bucket exists in the S3-compatible service.
@@ -492,7 +449,6 @@ class S3mini {
     delimiter: string = '/',
     prefix: string = '',
     maxKeys?: number,
-    // method: IT.HttpMethod = 'GET', // 'GET' or 'HEAD'
     opts: Record<string, unknown> = {},
   ): Promise<IT.ListObject[] | null> {
     this._checkDelimiter(delimiter);
@@ -500,69 +456,131 @@ class S3mini {
     this._checkOpts(opts);
 
     const keyPath = delimiter === '/' ? delimiter : U.uriEscape(delimiter);
-
     const unlimited = !(maxKeys && maxKeys > 0);
     let remaining = unlimited ? Infinity : maxKeys;
     let token: string | undefined;
     const all: IT.ListObject[] = [];
 
     do {
-      const batchSize = Math.min(remaining, 1000); // S3 ceiling
-      const query: Record<string, unknown> = {
-        'list-type': C.LIST_TYPE, // =2 for V2
-        'max-keys': String(batchSize),
-        ...(prefix ? { prefix } : {}),
-        ...(token ? { 'continuation-token': token } : {}),
-        ...opts,
-      };
+      const batchResult = await this._fetchObjectBatch(keyPath, prefix, remaining, token, opts);
 
-      const res = await this._signedRequest('GET', keyPath, {
-        query,
-        withQuery: true,
-        tolerated: [200, 404],
-      });
-
-      if (res.status === 404) {
-        return null;
-      }
-      if (res.status !== 200) {
-        const errorBody = await res.text();
-        const errorCode = res.headers.get('x-amz-error-code') || 'Unknown';
-        const errorMessage = res.headers.get('x-amz-error-message') || res.statusText;
-        this._log(
-          'error',
-          `${C.ERROR_PREFIX}Request failed with status ${res.status}: ${errorCode} - ${errorMessage}, err body: ${errorBody}`,
-        );
-        throw new Error(
-          `${C.ERROR_PREFIX}Request failed with status ${res.status}: ${errorCode} - ${errorMessage}, err body: ${errorBody}`,
-        );
+      if (batchResult === null) {
+        return null; // 404 - bucket not found
       }
-      const raw = U.parseXml(await res.text()) as Record<string, unknown>;
-      if (typeof raw !== 'object' || !raw || 'error' in raw) {
-        this._log('error', `${C.ERROR_PREFIX}Unexpected listObjects response shape: ${JSON.stringify(raw)}`);
-        throw new Error(`${C.ERROR_PREFIX}Unexpected listObjects response shape`);
-      }
-      const out = (raw.ListBucketResult || raw.listBucketResult || raw) as Record<string, unknown>;
-      /* accumulate Contents */
-      const contents = out.Contents || out.contents; // S3 v2 vs v1
-      if (contents) {
-        const batch = Array.isArray(contents) ? contents : [contents];
-        all.push(...(batch as IT.ListObject[]));
-        if (!unlimited) {
-          remaining -= batch.length;
-        }
+
+      all.push(...batchResult.objects);
+
+      if (!unlimited) {
+        remaining -= batchResult.objects.length;
       }
-      const truncated = out.IsTruncated === 'true' || out.isTruncated === 'true' || false;
-      token = truncated
-        ? ((out.NextContinuationToken || out.nextContinuationToken || out.NextMarker || out.nextMarker) as
-            | string
-            | undefined)
-        : undefined;
+
+      token = batchResult.continuationToken;
     } while (token && remaining > 0);
 
     return all;
   }
 
+  private async _fetchObjectBatch(
+    keyPath: string,
+    prefix: string,
+    remaining: number,
+    token: string | undefined,
+    opts: Record<string, unknown>,
+  ): Promise<{ objects: IT.ListObject[]; continuationToken?: string } | null> {
+    const query = this._buildListObjectsQuery(prefix, remaining, token, opts);
+
+    const res = await this._signedRequest('GET', keyPath, {
+      query,
+      withQuery: true,
+      tolerated: [200, 404],
+    });
+
+    if (res.status === 404) {
+      return null;
+    }
+
+    if (res.status !== 200) {
+      await this._handleListObjectsError(res);
+    }
+
+    const xmlText = await res.text();
+    return this._parseListObjectsResponse(xmlText);
+  }
+
+  private _buildListObjectsQuery(
+    prefix: string,
+    remaining: number,
+    token: string | undefined,
+    opts: Record<string, unknown>,
+  ): Record<string, unknown> {
+    const batchSize = Math.min(remaining, 1000); // S3 ceiling
+
+    return {
+      'list-type': C.LIST_TYPE, // =2 for V2
+      'max-keys': String(batchSize),
+      ...(prefix ? { prefix } : {}),
+      ...(token ? { 'continuation-token': token } : {}),
+      ...opts,
+    };
+  }
+
+  private async _handleListObjectsError(res: Response): Promise<never> {
+    const errorBody = await res.text();
+    const parsedErrorBody = this._parseErrorXml(res.headers, errorBody);
+    const errorCode = res.headers.get('x-amz-error-code') ?? parsedErrorBody.svcCode ?? 'Unknown';
+    const errorMessage = res.headers.get('x-amz-error-message') ?? parsedErrorBody.errorMessage ?? res.statusText;
+
+    this._log(
+      'error',
+      `${C.ERROR_PREFIX}Request failed with status ${res.status}: ${errorCode} - ${errorMessage}, err body: ${errorBody}`,
+    );
+
+    throw new Error(
+      `${C.ERROR_PREFIX}Request failed with status ${res.status}: ${errorCode} - ${errorMessage}, err body: ${errorBody}`,
+    );
+  }
+
+  private _parseListObjectsResponse(xmlText: string): {
+    objects: IT.ListObject[];
+    continuationToken?: string;
+  } {
+    const raw = U.parseXml(xmlText) as Record<string, unknown>;
+
+    if (typeof raw !== 'object' || !raw || 'error' in raw) {
+      this._log('error', `${C.ERROR_PREFIX}Unexpected listObjects response shape: ${JSON.stringify(raw)}`);
+      throw new Error(`${C.ERROR_PREFIX}Unexpected listObjects response shape`);
+    }
+
+    const out = (raw.ListBucketResult || raw.listBucketResult || raw) as Record<string, unknown>;
+    const objects = this._extractObjectsFromResponse(out);
+    const continuationToken = this._extractContinuationToken(out);
+
+    return { objects, continuationToken };
+  }
+
+  private _extractObjectsFromResponse(response: Record<string, unknown>): IT.ListObject[] {
+    const contents = response.Contents || response.contents; // S3 v2 vs v1
+
+    if (!contents) {
+      return [];
+    }
+
+    return Array.isArray(contents) ? (contents as IT.ListObject[]) : [contents as IT.ListObject];
+  }
+
+  private _extractContinuationToken(response: Record<string, unknown>): string | undefined {
+    const truncated = response.IsTruncated === 'true' || response.isTruncated === 'true' || false;
+
+    if (!truncated) {
+      return undefined;
+    }
+
+    return (response.NextContinuationToken ||
+      response.nextContinuationToken ||
+      response.NextMarker ||
+      response.nextMarker) as string | undefined;
+  }
+
   /**
    * Lists multipart uploads in the bucket.
    * This method sends a request to list multipart uploads in the specified bucket.
@@ -856,6 +874,7 @@ class S3mini {
    * @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
@@ -868,18 +887,17 @@ class S3mini {
    */
   public async putObject(
     key: string,
-    data: string | Buffer,
+    data: string | IT.MaybeBuffer,
     fileType: string = C.DEFAULT_STREAM_CONTENT_TYPE,
     ssecHeaders?: IT.SSECHeaders,
+    additionalHeaders?: IT.AWSHeaders,
   ): Promise<Response> {
-    if (!(data instanceof Buffer || typeof data === 'string')) {
-      throw new TypeError(C.ERROR_DATA_BUFFER_REQUIRED);
-    }
     return this._signedRequest('PUT', key, {
-      body: data,
+      body: this._validateData(data),
       headers: {
-        [C.HEADER_CONTENT_LENGTH]: typeof data === 'string' ? Buffer.byteLength(data) : data.length,
+        [C.HEADER_CONTENT_LENGTH]: U.getByteSize(data),
         [C.HEADER_CONTENT_TYPE]: fileType,
+        ...additionalHeaders,
         ...ssecHeaders,
       },
       tolerated: [200],
@@ -917,16 +935,6 @@ class S3mini {
     });
     const parsed = U.parseXml(await res.text()) as Record<string, unknown>;
 
-    // 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 =
@@ -968,19 +976,19 @@ class S3mini {
   public async uploadPart(
     key: string,
     uploadId: string,
-    data: Buffer | string,
+    data: IT.MaybeBuffer | string,
     partNumber: number,
     opts: Record<string, unknown> = {},
     ssecHeaders?: IT.SSECHeaders,
   ): Promise<IT.UploadPart> {
-    this._validateUploadPartParams(key, uploadId, data, partNumber, opts);
+    const body = this._validateUploadPartParams(key, uploadId, data, partNumber, opts);
 
     const query = { uploadId, partNumber, ...opts };
     const res = await this._signedRequest('PUT', key, {
       query,
-      body: data,
+      body,
       headers: {
-        [C.HEADER_CONTENT_LENGTH]: typeof data === 'string' ? Buffer.byteLength(data) : data.length,
+        [C.HEADER_CONTENT_LENGTH]: U.getByteSize(data),
         ...ssecHeaders,
       },
     });
@@ -1015,7 +1023,7 @@ class S3mini {
     const xmlBody = this._buildCompleteMultipartUploadXml(parts);
     const headers = {
       [C.HEADER_CONTENT_TYPE]: C.XML_CONTENT_TYPE,
-      [C.HEADER_CONTENT_LENGTH]: Buffer.byteLength(xmlBody).toString(),
+      [C.HEADER_CONTENT_LENGTH]: U.getByteSize(xmlBody),
     };
 
     const res = await this._signedRequest('POST', key, {
@@ -1038,7 +1046,7 @@ class S3mini {
         if (etag && typeof etag === 'string') {
           return {
             ...resultObj,
-            etag: this.sanitizeETag(etag),
+            etag: U.sanitizeETag(etag),
           } as IT.CompleteMultipartUploadResult;
         }
 
@@ -1094,20 +1102,228 @@ class S3mini {
   }
 
   private _buildCompleteMultipartUploadXml(parts: Array<IT.UploadPart>): string {
-    return `
-      <CompleteMultipartUpload>
-        ${parts
-          .map(
-            part => `
-          <Part>
-            <PartNumber>${part.partNumber}</PartNumber>
-            <ETag>${part.etag}</ETag>
-          </Part>
-        `,
-          )
-          .join('')}
-      </CompleteMultipartUpload>
-    `;
+    let xml = '<CompleteMultipartUpload>';
+    for (const part of parts) {
+      xml += `<Part><PartNumber>${part.partNumber}</PartNumber><ETag>${part.etag}</ETag></Part>`;
+    }
+    xml += '</CompleteMultipartUpload>';
+    return xml;
+  }
+
+  /**
+   * Executes the copy operation for local copying (same bucket/endpoint).
+   * @private
+   */
+  private async _executeCopyOperation(
+    destinationKey: string,
+    copySource: string,
+    options: IT.CopyObjectOptions,
+  ): Promise<IT.CopyObjectResult> {
+    const {
+      metadataDirective = 'COPY',
+      metadata = {},
+      contentType,
+      storageClass,
+      taggingDirective,
+      websiteRedirectLocation,
+      sourceSSECHeaders = {},
+      destinationSSECHeaders = {},
+      additionalHeaders = {},
+    } = options;
+
+    const headers: Record<string, string | number> = {
+      'x-amz-copy-source': copySource,
+      'x-amz-metadata-directive': metadataDirective,
+      ...additionalHeaders,
+      ...(contentType && { [C.HEADER_CONTENT_TYPE]: contentType }),
+      ...(storageClass && { 'x-amz-storage-class': storageClass }),
+      ...(taggingDirective && { 'x-amz-tagging-directive': taggingDirective }),
+      ...(websiteRedirectLocation && { 'x-amz-website-redirect-location': websiteRedirectLocation }),
+      ...this._buildSSECHeaders(sourceSSECHeaders, destinationSSECHeaders),
+      ...(metadataDirective === 'REPLACE' ? this._buildMetadataHeaders(metadata) : {}),
+    };
+
+    try {
+      const res = await this._signedRequest('PUT', destinationKey, {
+        headers,
+        tolerated: [200],
+      });
+      return this._parseCopyObjectResponse(await res.text());
+    } catch (err) {
+      this._log('error', `Error in copy operation to ${destinationKey}`, {
+        error: String(err),
+      });
+      throw err;
+    }
+  }
+
+  /**
+   * 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=='
+   *   }
+   * });
+   */
+  public copyObject(
+    sourceKey: string,
+    destinationKey: string,
+    options: IT.CopyObjectOptions = {},
+  ): Promise<IT.CopyObjectResult> {
+    // Validate parameters
+    this._checkKey(sourceKey);
+    this._checkKey(destinationKey);
+
+    const copySource = `/${this.bucketName}/${U.uriEscape(sourceKey)}`;
+
+    return this._executeCopyOperation(destinationKey, copySource, options);
+  }
+
+  private _buildSSECHeaders(
+    sourceHeaders: Record<string, string | number>,
+    destHeaders: Record<string, string | number>,
+  ): Record<string, string | number> {
+    const headers: Record<string, string | number> = {};
+    Object.entries({ ...sourceHeaders, ...destHeaders }).forEach(([k, v]) => {
+      if (v !== undefined) {
+        headers[k] = v;
+      }
+    });
+    return headers;
+  }
+
+  /**
+   * 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');
+   *   }
+   * }
+   */
+  public async moveObject(
+    sourceKey: string,
+    destinationKey: string,
+    options: IT.CopyObjectOptions = {},
+  ): Promise<IT.CopyObjectResult> {
+    try {
+      // First copy the object
+      const copyResult = await this.copyObject(sourceKey, destinationKey, options);
+
+      // Then delete the source
+      const deleteSuccess = await this.deleteObject(sourceKey);
+      if (!deleteSuccess) {
+        throw new Error(`${C.ERROR_PREFIX}Failed to delete source object after successful copy`);
+      }
+
+      return copyResult;
+    } catch (err) {
+      this._log('error', `Error moving object from ${sourceKey} to ${destinationKey}`, {
+        error: String(err),
+      });
+      throw err;
+    }
+  }
+
+  private _buildMetadataHeaders(metadata: Record<string, string>): Record<string, string> {
+    const headers: Record<string, string> = {};
+    Object.entries(metadata).forEach(([k, v]) => {
+      headers[k.startsWith('x-amz-meta-') ? k : `x-amz-meta-${k}`] = v;
+    });
+    return headers;
+  }
+
+  private _parseCopyObjectResponse(xmlText: string): IT.CopyObjectResult {
+    const parsed = U.parseXml(xmlText) as Record<string, unknown>;
+    if (!parsed || typeof parsed !== 'object') {
+      throw new Error(`${C.ERROR_PREFIX}Unexpected copyObject response format`);
+    }
+    const result = (parsed.CopyObjectResult || parsed.copyObjectResult || parsed) as Record<string, unknown>;
+    const etag = result.ETag || result.eTag || result.etag;
+    const lastModified = result.LastModified || result.lastModified;
+    if (!etag || typeof etag !== 'string') {
+      throw new Error(`${C.ERROR_PREFIX}ETag not found in copyObject response`);
+    }
+    return {
+      etag: U.sanitizeETag(etag),
+      lastModified: lastModified ? new Date(lastModified as string) : undefined,
+    };
   }
 
   /**
@@ -1122,13 +1338,14 @@ class S3mini {
   }
 
   private async _deleteObjectsProcess(keys: string[]): Promise<boolean[]> {
-    const xmlBody = `<Delete>${keys.map(key => `<Object><Key>${U.escapeXml(key)}</Key></Object>`).join('')}</Delete>`;
+    const objectsXml = keys.map(key => `<Object><Key>${U.escapeXml(key)}</Key></Object>`).join('');
+    const xmlBody = '<Delete>' + objectsXml + '</Delete>';
     const query = { delete: '' };
-    const md5Base64 = U.md5base64(xmlBody);
+    const sha256base64 = U.base64FromBuffer(await U.sha256(xmlBody));
     const headers = {
       [C.HEADER_CONTENT_TYPE]: C.XML_CONTENT_TYPE,
-      [C.HEADER_CONTENT_LENGTH]: Buffer.byteLength(xmlBody).toString(),
-      'Content-MD5': md5Base64,
+      [C.HEADER_CONTENT_LENGTH]: U.getByteSize(xmlBody),
+      [C.HEADER_AMZ_CHECKSUM_SHA256]: sha256base64,
     };
 
     const res = await this._signedRequest('POST', '', {
@@ -1215,7 +1432,7 @@ class S3mini {
     url: string,
     method: IT.HttpMethod,
     headers: Record<string, string>,
-    body?: string | Buffer,
+    body?: BodyInit,
     toleratedStatusCodes: number[] = [],
   ): Promise<Response> {
     this._log('info', `Sending ${method} request to ${url}`, `headers: ${JSON.stringify(headers)}`);
@@ -1223,13 +1440,14 @@ class S3mini {
       const res = await fetch(url, {
         method,
         headers,
-        body: ['GET', 'HEAD'].includes(method) ? undefined : (body as string),
+        body: ['GET', 'HEAD'].includes(method) ? undefined : body,
         signal: this.requestAbortTimeout !== undefined ? AbortSignal.timeout(this.requestAbortTimeout) : undefined,
       });
       this._log('info', `Response status: ${res.status}, tolerated: ${toleratedStatusCodes.join(',')}`);
-      if (!res.ok && !toleratedStatusCodes.includes(res.status)) {
-        await this._handleErrorResponse(res);
+      if (res.ok || toleratedStatusCodes.includes(res.status)) {
+        return res;
       }
+      await this._handleErrorResponse(res);
       return res;
     } catch (err: unknown) {
       const code = U.extractErrCode(err);
@@ -1240,10 +1458,32 @@ class S3mini {
     }
   }
 
+  private _parseErrorXml(headers: Headers, body: string): { svcCode?: string; errorMessage?: string } {
+    if (headers.get('content-type') !== 'application/xml') {
+      return {};
+    }
+    const parsedBody = U.parseXml(body);
+    if (
+      !parsedBody ||
+      typeof parsedBody !== 'object' ||
+      !('Error' in parsedBody) ||
+      !parsedBody.Error ||
+      typeof parsedBody.Error !== 'object'
+    ) {
+      return {};
+    }
+    const error = parsedBody.Error;
+    return {
+      svcCode: 'Code' in error && typeof error.Code === 'string' ? error.Code : undefined,
+      errorMessage: 'Message' in error && typeof error.Message === 'string' ? error.Message : undefined,
+    };
+  }
+
   private async _handleErrorResponse(res: Response): Promise<void> {
     const errorBody = await res.text();
-    const svcCode = res.headers.get('x-amz-error-code') ?? 'Unknown';
-    const errorMessage = res.headers.get('x-amz-error-message') || res.statusText;
+    const parsedErrorBody = this._parseErrorXml(res.headers, errorBody);
+    const svcCode = res.headers.get('x-amz-error-code') ?? parsedErrorBody.svcCode ?? 'Unknown';
+    const errorMessage = res.headers.get('x-amz-error-message') ?? parsedErrorBody.errorMessage ?? res.statusText;
     this._log(
       'error',
       `${C.ERROR_PREFIX}Request failed with status ${res.status}: ${svcCode} - ${errorMessage},err body: ${errorBody}`,
@@ -1257,21 +1497,16 @@ class S3mini {
     }
     return Object.keys(queryParams)
       .map(key => `${encodeURIComponent(key)}=${encodeURIComponent(queryParams[key] as string)}`)
-      .sort()
+      .sort((a, b) => a.localeCompare(b))
       .join('&');
   }
-  private _getSignatureKey(dateStamp: string): Buffer {
-    const kDate = U.hmac(`AWS4${this.secretAccessKey}`, dateStamp) as Buffer;
-    const kRegion = U.hmac(kDate, this.region) as Buffer;
-    const kService = U.hmac(kRegion, C.S3_SERVICE) as Buffer;
-    return U.hmac(kService, C.AWS_REQUEST_TYPE) as Buffer;
+  private async _getSignatureKey(dateStamp: string): Promise<ArrayBuffer> {
+    const kDate = await U.hmac(`AWS4${this.secretAccessKey}`, dateStamp);
+    const kRegion = await U.hmac(kDate, this.region);
+    const kService = await U.hmac(kRegion, C.S3_SERVICE);
+    return await U.hmac(kService, C.AWS_REQUEST_TYPE);
   }
 }
 
-/**
- * @deprecated Use `S3mini` instead.
- */
-const s3mini = S3mini;
-
-export { S3mini, s3mini };
+export { S3mini };
 export default S3mini;