s3mini 0.1.0

package/dist/s3mini.js

@@ -0,0 +1,841 @@
+// Constants
+const AWS_ALGORITHM = 'AWS4-HMAC-SHA256';
+const AWS_REQUEST_TYPE = 'aws4_request';
+const S3_SERVICE = 's3';
+const LIST_TYPE = '2';
+const UNSIGNED_PAYLOAD = 'UNSIGNED-PAYLOAD';
+const DEFAULT_STREAM_CONTENT_TYPE = 'application/octet-stream';
+const XML_CONTENT_TYPE = 'application/xml';
+// List of keys that might contain sensitive information
+const SENSITIVE_KEYS_REDACTED = ['accessKeyId', 'secretAccessKey', 'sessionToken', 'password', 'token'];
+const DEFAULT_REQUEST_SIZE_IN_BYTES = 8 * 1024 * 1024;
+// Headers
+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_ETAG = 'etag';
+// Error messages
+const ERROR_PREFIX = '[s3mini] ';
+const ERROR_ACCESS_KEY_REQUIRED = `${ERROR_PREFIX}accessKeyId must be a non-empty string`;
+const ERROR_SECRET_KEY_REQUIRED = `${ERROR_PREFIX}secretAccessKey must be a non-empty string`;
+const ERROR_ENDPOINT_REQUIRED = `${ERROR_PREFIX}endpoint must be a non-empty string`;
+const ERROR_ENDPOINT_FORMAT = `${ERROR_PREFIX}endpoint must be a valid URL. Expected format: https://<host>[:port][/base-path]`;
+const ERROR_KEY_REQUIRED = `${ERROR_PREFIX}key must be a non-empty string`;
+const ERROR_UPLOAD_ID_REQUIRED = `${ERROR_PREFIX}uploadId must be a non-empty string`;
+const ERROR_DATA_BUFFER_REQUIRED = `${ERROR_PREFIX}data must be a Buffer or string`;
+// const ERROR_PATH_REQUIRED = `${ERROR_PREFIX}path must be a string`;
+const ERROR_PREFIX_TYPE = `${ERROR_PREFIX}prefix must be a string`;
+const ERROR_DELIMITER_REQUIRED = `${ERROR_PREFIX}delimiter must be a string`;
+
+// Initialize crypto functions
+const _createHmac = crypto.createHmac || (await import('node:crypto')).createHmac;
+const _createHash = crypto.createHash || (await import('node:crypto')).createHash;
+/**
+ * Hash content using SHA-256
+ * @param {string|Buffer} content  – data to hash
+ * @returns {string} Hex encoded hash
+ */
+const hash = (content) => {
+    return _createHash('sha256').update(content).digest('hex');
+};
+/**
+ * Compute HMAC-SHA-256 of arbitrary data and return a hex string.
+ * @param {string|Buffer} key      – secret key
+ * @param {string|Buffer} content  – data to authenticate
+ * @param {BufferEncoding} [encoding='hex'] – hex | base64 | …
+ * @returns {string | Buffer} hex encoded HMAC
+ */
+const hmac = (key, content, encoding) => {
+    const mac = _createHmac('sha256', key).update(content);
+    return encoding ? mac.digest(encoding) : mac.digest();
+};
+/**
+ * Sanitize ETag value by removing quotes and XML entities
+ * @param etag ETag value to sanitize
+ * @returns Sanitized ETag
+ */
+const sanitizeETag = (etag) => {
+    const replaceChars = {
+        '"': '',
+        '&quot;': '',
+        '&#34;': '',
+        '&QUOT;': '',
+        '&#x00022': '',
+    };
+    return etag.replace(/^("|&quot;|&#34;)|("|&quot;|&#34;)$/g, m => replaceChars[m]);
+};
+const entityMap = {
+    '&quot;': '"',
+    '&apos;': "'",
+    '&lt;': '<',
+    '&gt;': '>',
+    '&amp;': '&',
+};
+const unescapeXml = (value) => value.replace(/&(quot|apos|lt|gt|amp);/g, m => entityMap[m] ?? m);
+/**
+ * Parse a very small subset of XML into a JS structure.
+ *
+ * @param input raw XML string
+ * @returns string for leaf nodes, otherwise a map of children
+ */
+const parseXml = (input) => {
+    const RE_TAG = /<(\w)([-\w]+)(?:\/|[^>]*>((?:(?!<\1)[\s\S])*)<\/\1\2)>/gm;
+    const result = {}; // strong type, no `any`
+    let match;
+    while ((match = RE_TAG.exec(input)) !== null) {
+        const [, prefix = '', key, inner] = match;
+        const fullKey = `${prefix.toLowerCase()}${key}`;
+        const node = inner ? parseXml(inner) : '';
+        const current = result[fullKey];
+        if (current === undefined) {
+            // first occurrence
+            result[fullKey] = node;
+        }
+        else if (Array.isArray(current)) {
+            // already an array
+            current.push(node);
+        }
+        else {
+            // promote to array on the second occurrence
+            result[fullKey] = [current, node];
+        }
+    }
+    // No child tags? — return the text, after entity decode
+    return Object.keys(result).length > 0 ? result : unescapeXml(input);
+};
+/**
+ * Encode a character as a URI percent-encoded hex value
+ * @param c Character to encode
+ * @returns Percent-encoded character
+ */
+const encodeAsHex = (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`;
+/**
+ * Escape a URI string using percent encoding
+ * @param uriStr URI string to escape
+ * @returns Escaped URI string
+ */
+const uriEscape = (uriStr) => {
+    return encodeURIComponent(uriStr).replace(/[!'()*]/g, encodeAsHex);
+};
+/**
+ * Escape a URI resource path while preserving forward slashes
+ * @param string URI path to escape
+ * @returns Escaped URI path
+ */
+const uriResourceEscape = (string) => {
+    return uriEscape(string).replace(/%2F/g, '/');
+};
+const extractErrCode = (e) => {
+    if (typeof e !== 'object' || e === null) {
+        return undefined;
+    }
+    const err = e;
+    if (typeof err.code === 'string') {
+        return err.code;
+    }
+    return typeof err.cause?.code === 'string' ? err.cause.code : undefined;
+};
+class S3Error extends Error {
+    code;
+    constructor(msg, code, cause) {
+        super(msg);
+        this.name = new.target.name; // keeps instanceof usable
+        this.code = code;
+        this.cause = cause;
+    }
+}
+class S3NetworkError extends S3Error {
+}
+class S3ServiceError extends S3Error {
+    status;
+    serviceCode;
+    body;
+    constructor(msg, status, serviceCode, body) {
+        super(msg, serviceCode);
+        this.status = status;
+        this.serviceCode = serviceCode;
+        this.body = body;
+    }
+}
+/**
+ * Run async-returning tasks in batches with an *optional* minimum
+ * spacing (minIntervalMs) between the *start* times of successive batches.
+ *
+ * @param {Iterable<() => Promise<unknonw>>} tasks       – functions returning Promises
+ * @param {number} [batchSize=30]                    – max concurrent requests
+ * @param {number} [minIntervalMs=0]                 – ≥0; 0 means “no pacing”
+ * @returns {Promise<Array<PromiseSettledResult<unknonw>>>}
+ */
+const runInBatches = async (tasks, batchSize = 30, minIntervalMs = 0) => {
+    const allResults = [];
+    let batch = [];
+    for (const task of tasks) {
+        batch.push(task);
+        if (batch.length === batchSize) {
+            await executeBatch(batch);
+            batch = [];
+        }
+    }
+    if (batch.length) {
+        await executeBatch(batch);
+    }
+    return allResults;
+    // ───────── helpers ──────────
+    async function executeBatch(batchFns) {
+        const start = Date.now();
+        const settled = await Promise.allSettled(batchFns.map(fn => fn()));
+        allResults.push(...settled);
+        if (minIntervalMs > 0) {
+            const wait = minIntervalMs - (Date.now() - start);
+            if (wait > 0) {
+                await new Promise(r => setTimeout(r, wait));
+            }
+        }
+    }
+};
+
+/**
+ * S3 class for interacting with S3-compatible object storage services.
+ * This class provides methods for common S3 operations such as uploading, downloading,
+ * and deleting objects, as well as multipart uploads.
+ *
+ * @class
+ * @example
+ * 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
+ * });
+ *
+ * // Upload a file
+ * await s3.putObject('example.txt', 'Hello, World!');
+ *
+ * // Download a file
+ * const content = await s3.getObject('example.txt');
+ *
+ * // Delete a file
+ * await s3.deleteObject('example.txt');
+ */
+class s3mini {
+    /**
+     * Creates an instance of the S3 class.
+     *
+     * @constructor
+     * @param {Object} config - Configuration options for the S3 instance.
+     * @param {string} config.accessKeyId - The access key ID for authentication.
+     * @param {string} config.secretAccessKey - The secret access key for authentication.
+     * @param {string} config.endpoint - The endpoint URL of the S3-compatible service.
+     * @param {string} [config.region='auto'] - The region of the S3 service.
+     * @param {number} [config.requestSizeInBytes=8388608] - The request size of a single request in bytes (AWS S3 is 8MB).
+     * @param {number} [config.requestAbortTimeout=undefined] - The timeout in milliseconds after which a request should be aborted (careful on streamed requests).
+     * @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.
+     */
+    accessKeyId;
+    secretAccessKey;
+    endpoint;
+    region;
+    requestSizeInBytes;
+    requestAbortTimeout;
+    logger;
+    fullDatetime;
+    shortDatetime;
+    signingKey;
+    credentialScope;
+    constructor({ accessKeyId, secretAccessKey, endpoint, region = 'auto', requestSizeInBytes = DEFAULT_REQUEST_SIZE_IN_BYTES, requestAbortTimeout = undefined, logger = undefined, }) {
+        this._validateConstructorParams(accessKeyId, secretAccessKey, endpoint);
+        this.accessKeyId = accessKeyId;
+        this.secretAccessKey = secretAccessKey;
+        this.endpoint = this._ensureValidUrl(endpoint);
+        this.region = region;
+        this.requestSizeInBytes = requestSizeInBytes;
+        this.requestAbortTimeout = requestAbortTimeout;
+        this.logger = logger;
+        this.fullDatetime = new Date().toISOString().replace(/[:-]|\.\d{3}/g, '');
+        this.shortDatetime = this.fullDatetime.slice(0, 8);
+        this.signingKey = this._getSignatureKey(this.shortDatetime);
+        this.credentialScope = [this.shortDatetime, this.region, S3_SERVICE, AWS_REQUEST_TYPE].join('/');
+    }
+    _sanitize(obj) {
+        if (typeof obj !== 'object' || obj === null) {
+            return obj;
+        }
+        return Object.keys(obj).reduce((acc, key) => {
+            if (SENSITIVE_KEYS_REDACTED.includes(key.toLowerCase())) {
+                acc[key] = '[REDACTED]';
+            }
+            else if (typeof obj[key] === 'object' &&
+                obj[key] !== null) {
+                acc[key] = this._sanitize(obj[key]);
+            }
+            else {
+                acc[key] = obj[key];
+            }
+            return acc;
+        }, Array.isArray(obj) ? [] : {});
+    }
+    _log(level, message, additionalData = {}) {
+        if (this.logger && typeof this.logger[level] === 'function') {
+            // Function to recursively sanitize an object
+            // Sanitize the additional data
+            const sanitizedData = this._sanitize(additionalData);
+            // Prepare the log entry
+            const logEntry = {
+                timestamp: new Date().toISOString(),
+                level,
+                message,
+                details: sanitizedData,
+                // Include some general context, but sanitize sensitive parts
+                context: this._sanitize({
+                    region: this.region,
+                    endpoint: this.endpoint,
+                    // Only include the first few characters of the access key, if it exists
+                    accessKeyId: this.accessKeyId ? `${this.accessKeyId.substring(0, 4)}...` : undefined,
+                }),
+            };
+            // Log the sanitized entry
+            this.logger[level](JSON.stringify(logEntry));
+        }
+    }
+    _validateConstructorParams(accessKeyId, secretAccessKey, endpoint) {
+        if (typeof accessKeyId !== 'string' || accessKeyId.trim().length === 0) {
+            throw new TypeError(ERROR_ACCESS_KEY_REQUIRED);
+        }
+        if (typeof secretAccessKey !== 'string' || secretAccessKey.trim().length === 0) {
+            throw new TypeError(ERROR_SECRET_KEY_REQUIRED);
+        }
+        if (typeof endpoint !== 'string' || endpoint.trim().length === 0) {
+            throw new TypeError(ERROR_ENDPOINT_REQUIRED);
+        }
+    }
+    _ensureValidUrl(raw) {
+        // prepend https:// if user forgot a scheme
+        const candidate = /^(https?:)?\/\//i.test(raw) ? raw : `https://${raw}`;
+        try {
+            new URL(candidate);
+            return candidate.replace(/\/+$/, ''); // strip trailing slash
+        }
+        catch {
+            const msg = `${ERROR_ENDPOINT_FORMAT} But provided: "${raw}"`;
+            this._log('error', msg);
+            throw new TypeError(msg);
+        }
+    }
+    _validateMethodIsGetOrHead(method) {
+        if (method !== 'GET' && method !== 'HEAD') {
+            this._log('error', `${ERROR_PREFIX}method must be either GET or HEAD`);
+            throw new Error('method must be either GET or HEAD');
+        }
+    }
+    _checkKey(key) {
+        if (typeof key !== 'string' || key.trim().length === 0) {
+            this._log('error', ERROR_KEY_REQUIRED);
+            throw new TypeError(ERROR_KEY_REQUIRED);
+        }
+    }
+    _checkDelimiter(delimiter) {
+        if (typeof delimiter !== 'string' || delimiter.trim().length === 0) {
+            this._log('error', ERROR_DELIMITER_REQUIRED);
+            throw new TypeError(ERROR_DELIMITER_REQUIRED);
+        }
+    }
+    _checkPrefix(prefix) {
+        if (typeof prefix !== 'string') {
+            this._log('error', ERROR_PREFIX_TYPE);
+            throw new TypeError(ERROR_PREFIX_TYPE);
+        }
+    }
+    // private _checkMaxKeys(maxKeys: number): void {
+    //   if (typeof maxKeys !== 'number' || maxKeys <= 0) {
+    //     this._log('error', C.ERROR_MAX_KEYS_TYPE);
+    //     throw new TypeError(C.ERROR_MAX_KEYS_TYPE);
+    //   }
+    // }
+    _checkOpts(opts) {
+        if (typeof opts !== 'object') {
+            this._log('error', `${ERROR_PREFIX}opts must be an object`);
+            throw new TypeError(`${ERROR_PREFIX}opts must be an object`);
+        }
+    }
+    _filterIfHeaders(opts) {
+        const filteredOpts = {};
+        const conditionalHeaders = {};
+        const ifHeaders = ['if-match', 'if-none-match', 'if-modified-since', 'if-unmodified-since'];
+        for (const [key, value] of Object.entries(opts)) {
+            if (ifHeaders.includes(key.toLowerCase())) {
+                // Convert to lowercase for consistency
+                conditionalHeaders[key] = value;
+            }
+            else {
+                filteredOpts[key] = value;
+            }
+        }
+        return { filteredOpts, conditionalHeaders };
+    }
+    _validateUploadPartParams(key, uploadId, data, partNumber, opts) {
+        this._checkKey(key);
+        if (!(data instanceof Buffer || typeof data === 'string')) {
+            this._log('error', ERROR_DATA_BUFFER_REQUIRED);
+            throw new TypeError(ERROR_DATA_BUFFER_REQUIRED);
+        }
+        if (typeof uploadId !== 'string' || uploadId.trim().length === 0) {
+            this._log('error', ERROR_UPLOAD_ID_REQUIRED);
+            throw new TypeError(ERROR_UPLOAD_ID_REQUIRED);
+        }
+        if (!Number.isInteger(partNumber) || partNumber <= 0) {
+            this._log('error', `${ERROR_PREFIX}partNumber must be a positive integer`);
+            throw new TypeError(`${ERROR_PREFIX}partNumber must be a positive integer`);
+        }
+        this._checkOpts(opts);
+    }
+    _sign(method, keyPath, query = {}, headers = {}) {
+        // Create URL without appending keyPath first
+        const url = new URL(this.endpoint);
+        // Properly format the pathname to avoid double slashes
+        if (keyPath && keyPath.length > 0) {
+            url.pathname =
+                url.pathname === '/' ? `/${keyPath.replace(/^\/+/, '')}` : `${url.pathname}/${keyPath.replace(/^\/+/, '')}`;
+        }
+        headers[HEADER_AMZ_CONTENT_SHA256] = UNSIGNED_PAYLOAD; // body ? U.hash(body) : C.UNSIGNED_PAYLOAD;
+        headers[HEADER_AMZ_DATE] = this.fullDatetime;
+        headers[HEADER_HOST] = url.host;
+        const canonicalHeaders = this._buildCanonicalHeaders(headers);
+        const signedHeaders = Object.keys(headers)
+            .map(key => key.toLowerCase())
+            .sort()
+            .join(';');
+        const canonicalRequest = this._buildCanonicalRequest(method, url, query, canonicalHeaders, signedHeaders);
+        const stringToSign = this._buildStringToSign(canonicalRequest);
+        const signature = this._calculateSignature(stringToSign);
+        const authorizationHeader = this._buildAuthorizationHeader(signedHeaders, signature);
+        headers[HEADER_AUTHORIZATION] = authorizationHeader;
+        return { url: url.toString(), headers };
+    }
+    _buildCanonicalHeaders(headers) {
+        return Object.entries(headers)
+            .map(([key, value]) => `${key.toLowerCase()}:${String(value).trim()}`)
+            .sort()
+            .join('\n');
+    }
+    _buildCanonicalRequest(method, url, query, canonicalHeaders, signedHeaders) {
+        return [
+            method,
+            url.pathname,
+            this._buildCanonicalQueryString(query),
+            `${canonicalHeaders}\n`,
+            signedHeaders,
+            UNSIGNED_PAYLOAD,
+        ].join('\n');
+    }
+    _buildStringToSign(canonicalRequest) {
+        return [AWS_ALGORITHM, this.fullDatetime, this.credentialScope, hash(canonicalRequest)].join('\n');
+    }
+    _calculateSignature(stringToSign) {
+        return hmac(this.signingKey, stringToSign, 'hex');
+    }
+    _buildAuthorizationHeader(signedHeaders, signature) {
+        return [
+            `${AWS_ALGORITHM} Credential=${this.accessKeyId}/${this.credentialScope}`,
+            `SignedHeaders=${signedHeaders}`,
+            `Signature=${signature}`,
+        ].join(', ');
+    }
+    async _signedRequest(method, // 'GET' | 'HEAD' | 'PUT' | 'POST' | 'DELETE'
+    key, // ‘’ allowed for bucket‑level ops
+    { query = {}, // ?query=string
+    body = '', // string | Buffer | undefined
+    headers = {}, // extra/override headers
+    tolerated = [], // [200, 404] etc.
+    withQuery = false, // append query string to signed URL
+     } = {}) {
+        // Basic validation
+        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: {} };
+        const baseHeaders = {
+            [HEADER_AMZ_CONTENT_SHA256]: UNSIGNED_PAYLOAD,
+            // ...(['GET', 'HEAD'].includes(method) ? { [C.HEADER_CONTENT_TYPE]: C.JSON_CONTENT_TYPE } : {}),
+            ...headers,
+            ...conditionalHeaders,
+        };
+        const encodedKey = key ? uriResourceEscape(key) : '';
+        const { url, headers: signedHeaders } = this._sign(method, encodedKey, filteredOpts, baseHeaders);
+        if (Object.keys(query).length > 0) {
+            withQuery = true; // append query string to signed URL
+        }
+        const filteredOptsStrings = Object.fromEntries(Object.entries(filteredOpts).map(([k, v]) => [k, String(v)]));
+        const finalUrl = withQuery && Object.keys(filteredOpts).length ? `${url}?${new URLSearchParams(filteredOptsStrings)}` : url;
+        const signedHeadersString = Object.fromEntries(Object.entries(signedHeaders).map(([k, v]) => [k, String(v)]));
+        return this._sendRequest(finalUrl, method, signedHeadersString, body, tolerated);
+    }
+    getProps() {
+        return {
+            accessKeyId: this.accessKeyId,
+            secretAccessKey: this.secretAccessKey,
+            endpoint: this.endpoint,
+            region: this.region,
+            requestSizeInBytes: this.requestSizeInBytes,
+            requestAbortTimeout: this.requestAbortTimeout,
+            logger: this.logger,
+        };
+    }
+    setProps(props) {
+        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 || DEFAULT_REQUEST_SIZE_IN_BYTES;
+        this.requestAbortTimeout = props.requestAbortTimeout;
+        this.logger = props.logger;
+    }
+    sanitizeETag(etag) {
+        return sanitizeETag(etag);
+    }
+    // TBD
+    async createBucket() {
+        const xmlBody = `
+      <CreateBucketConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
+        <LocationConstraint>${this.region}</LocationConstraint>
+      </CreateBucketConfiguration>
+    `;
+        const headers = {
+            [HEADER_CONTENT_TYPE]: XML_CONTENT_TYPE,
+            [HEADER_CONTENT_LENGTH]: Buffer.byteLength(xmlBody).toString(),
+        };
+        const res = await this._signedRequest('PUT', '', {
+            body: xmlBody,
+            headers,
+            tolerated: [200, 404, 403, 409], // don’t throw on 404/403 // 409 = bucket already exists
+        });
+        return res.status === 200;
+    }
+    async bucketExists() {
+        const res = await this._signedRequest('HEAD', '', { tolerated: [200, 404, 403] });
+        return res.status === 200;
+    }
+    async listObjects(delimiter = '/', prefix = '', maxKeys, 
+    // method: IT.HttpMethod = 'GET', // 'GET' or 'HEAD'
+    opts = {}) {
+        this._checkDelimiter(delimiter);
+        this._checkPrefix(prefix);
+        this._checkOpts(opts);
+        const keyPath = delimiter === '/' ? delimiter : uriEscape(delimiter);
+        const unlimited = !(maxKeys && maxKeys > 0);
+        let remaining = unlimited ? Infinity : maxKeys;
+        let token;
+        const all = [];
+        do {
+            const batchSize = Math.min(remaining, 1000); // S3 ceiling
+            const query = {
+                'list-type': LIST_TYPE, // =2 for V2
+                'max-keys': String(batchSize),
+                ...(prefix ? { prefix } : {}),
+                ...(token ? { 'continuation-token': 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', `${ERROR_PREFIX}Request failed with status ${res.status}: ${errorCode} - ${errorMessage}, err body: ${errorBody}`);
+                throw new Error(`${ERROR_PREFIX}Request failed with status ${res.status}: ${errorCode} - ${errorMessage}, err body: ${errorBody}`);
+            }
+            const raw = parseXml(await res.text());
+            if (typeof raw !== 'object' || !raw || 'error' in raw) {
+                this._log('error', `${ERROR_PREFIX}Unexpected listObjects response shape: ${JSON.stringify(raw)}`);
+                throw new Error(`${ERROR_PREFIX}Unexpected listObjects response shape`);
+            }
+            const out = ('listBucketResult' in raw ? raw.listBucketResult : raw);
+            /* accumulate Contents */
+            const contents = out.contents;
+            if (contents) {
+                const batch = Array.isArray(contents) ? contents : [contents];
+                all.push(...batch);
+                if (!unlimited) {
+                    remaining -= batch.length;
+                }
+            }
+            const truncated = out.isTruncated === 'true' || out.IsTruncated === 'true';
+            token = truncated
+                ? (out.nextContinuationToken || out.NextContinuationToken || out.nextMarker || out.NextMarker)
+                : undefined;
+        } while (token && remaining > 0);
+        return all;
+    }
+    async listMultipartUploads(delimiter = '/', prefix = '', method = 'GET', opts = {}) {
+        this._checkDelimiter(delimiter);
+        this._checkPrefix(prefix);
+        this._validateMethodIsGetOrHead(method);
+        this._checkOpts(opts);
+        const query = { uploads: '', ...opts };
+        const keyPath = delimiter === '/' ? delimiter : uriEscape(delimiter);
+        const res = await this._signedRequest(method, keyPath, {
+            query,
+            withQuery: true,
+        });
+        // doublecheck if this is needed
+        // if (method === 'HEAD') {
+        //   return {
+        //     size: +(res.headers.get(C.HEADER_CONTENT_LENGTH) ?? '0'),
+        //     mtime: res.headers.get(C.HEADER_LAST_MODIFIED) ? new Date(res.headers.get(C.HEADER_LAST_MODIFIED)!) : undefined,
+        //     etag: res.headers.get(C.HEADER_ETAG) ?? '',
+        //   };
+        // }
+        const raw = parseXml(await res.text());
+        if (typeof raw !== 'object' || raw === null) {
+            throw new Error(`${ERROR_PREFIX}Unexpected listMultipartUploads response shape`);
+        }
+        if ('listMultipartUploadsResult' in raw) {
+            return raw.listMultipartUploadsResult;
+        }
+        return raw;
+    }
+    async getObject(key, opts = {}) {
+        const res = await this._signedRequest('GET', key, { query: opts, tolerated: [200, 404, 412, 304] });
+        if ([404, 412, 304].includes(res.status)) {
+            return null;
+        }
+        return res.text();
+    }
+    async getObjectArrayBuffer(key, opts = {}) {
+        const res = await this._signedRequest('GET', key, { query: opts, tolerated: [200, 404, 412, 304] });
+        if ([404, 412, 304].includes(res.status)) {
+            return null;
+        }
+        return res.arrayBuffer();
+    }
+    async getObjectWithETag(key, opts = {}) {
+        try {
+            const res = await this._signedRequest('GET', key, { query: opts, tolerated: [200, 404, 412, 304] });
+            if ([404, 412, 304].includes(res.status)) {
+                return { etag: null, data: null };
+            }
+            const etag = res.headers.get(HEADER_ETAG);
+            if (!etag) {
+                throw new Error('ETag not found in response headers');
+            }
+            return { etag: sanitizeETag(etag), data: await res.arrayBuffer() };
+        }
+        catch (err) {
+            this._log('error', `Error getting object ${key} with ETag: ${String(err)}`);
+            throw err;
+        }
+    }
+    async getObjectRaw(key, wholeFile = true, rangeFrom = 0, rangeTo = this.requestSizeInBytes, opts = {}) {
+        const rangeHdr = wholeFile ? {} : { range: `bytes=${rangeFrom}-${rangeTo - 1}` };
+        return this._signedRequest('GET', key, {
+            query: { ...opts },
+            headers: rangeHdr,
+            withQuery: true, // keep ?query=string behaviour
+        });
+    }
+    async getContentLength(key) {
+        const res = await this._signedRequest('HEAD', key);
+        const len = res.headers.get(HEADER_CONTENT_LENGTH);
+        return len ? +len : 0;
+    }
+    async objectExists(key, opts = {}) {
+        const res = await this._signedRequest('HEAD', key, {
+            query: opts,
+            tolerated: [200, 404, 412, 304],
+        });
+        if (res.status === 404) {
+            return false; // not found
+        }
+        if (res.status === 412 || res.status === 304) {
+            return null; // ETag mismatch
+        }
+        return true; // found (200)
+    }
+    async getEtag(key, opts = {}) {
+        const res = await this._signedRequest('HEAD', key, {
+            query: opts,
+            tolerated: [200, 404],
+        });
+        if (res.status === 404) {
+            return null;
+        }
+        const etag = res.headers.get(HEADER_ETAG);
+        if (!etag) {
+            throw new Error('ETag not found in response headers');
+        }
+        return sanitizeETag(etag);
+    }
+    async putObject(key, data) {
+        if (!(data instanceof Buffer || typeof data === 'string')) {
+            throw new TypeError(ERROR_DATA_BUFFER_REQUIRED);
+        }
+        return this._signedRequest('PUT', key, {
+            body: data,
+            headers: { [HEADER_CONTENT_LENGTH]: typeof data === 'string' ? Buffer.byteLength(data) : data.length },
+            tolerated: [200],
+        });
+    }
+    async getMultipartUploadId(key, fileType = DEFAULT_STREAM_CONTENT_TYPE) {
+        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 res = await this._signedRequest('POST', key, {
+            query,
+            headers,
+            withQuery: true,
+        });
+        const parsed = parseXml(await res.text());
+        if (parsed &&
+            typeof parsed === 'object' &&
+            'initiateMultipartUploadResult' in parsed &&
+            parsed.initiateMultipartUploadResult &&
+            'uploadId' in parsed.initiateMultipartUploadResult) {
+            return parsed.initiateMultipartUploadResult.uploadId;
+        }
+        throw new Error(`${ERROR_PREFIX}Failed to create multipart upload: ${JSON.stringify(parsed)}`);
+    }
+    async uploadPart(key, uploadId, data, partNumber, opts = {}) {
+        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 },
+        });
+        return { partNumber, etag: sanitizeETag(res.headers.get('etag') || '') };
+    }
+    async completeMultipartUpload(key, uploadId, parts) {
+        // …existing validation left untouched …
+        const query = { uploadId };
+        const xmlBody = this._buildCompleteMultipartUploadXml(parts);
+        const headers = {
+            [HEADER_CONTENT_TYPE]: XML_CONTENT_TYPE,
+            [HEADER_CONTENT_LENGTH]: Buffer.byteLength(xmlBody).toString(),
+        };
+        const res = await this._signedRequest('POST', key, {
+            query,
+            body: xmlBody,
+            headers,
+            withQuery: true,
+        });
+        const parsed = parseXml(await res.text());
+        const result = parsed && typeof parsed === 'object' && 'completeMultipartUploadResult' in parsed
+            ? parsed.completeMultipartUploadResult
+            : parsed;
+        if (!result || typeof result !== 'object') {
+            throw new Error(`${ERROR_PREFIX}Failed to complete multipart upload: ${JSON.stringify(parsed)}`);
+        }
+        if ('ETag' in result || 'eTag' in result) {
+            result.etag = this.sanitizeETag(result.eTag ?? result.ETag);
+        }
+        return result;
+    }
+    async abortMultipartUpload(key, uploadId) {
+        this._checkKey(key);
+        if (!uploadId) {
+            throw new TypeError(ERROR_UPLOAD_ID_REQUIRED);
+        }
+        const query = { uploadId };
+        const headers = { [HEADER_CONTENT_TYPE]: XML_CONTENT_TYPE };
+        const res = await this._signedRequest('DELETE', key, {
+            query,
+            headers,
+            withQuery: true,
+        });
+        const parsed = parseXml(await res.text());
+        if (parsed &&
+            'error' in parsed &&
+            typeof parsed.error === 'object' &&
+            parsed.error !== null &&
+            'message' in parsed.error) {
+            this._log('error', `${ERROR_PREFIX}Failed to abort multipart upload: ${String(parsed.error.message)}`);
+            throw new Error(`${ERROR_PREFIX}Failed to abort multipart upload: ${String(parsed.error.message)}`);
+        }
+        return { status: 'Aborted', key, uploadId, response: parsed };
+    }
+    _buildCompleteMultipartUploadXml(parts) {
+        return `
+      <CompleteMultipartUpload>
+        ${parts
+            .map(part => `
+          <Part>
+            <PartNumber>${part.partNumber}</PartNumber>
+            <ETag>${part.etag}</ETag>
+          </Part>
+        `)
+            .join('')}
+      </CompleteMultipartUpload>
+    `;
+    }
+    async deleteObject(key) {
+        const res = await this._signedRequest('DELETE', key, { tolerated: [200, 204] });
+        return res.status === 200 || res.status === 204;
+    }
+    async _sendRequest(url, method, headers, body, toleratedStatusCodes = []) {
+        this._log('info', `Sending ${method} request to ${url}`, `headers: ${JSON.stringify(headers)}`);
+        try {
+            const res = await fetch(url, {
+                method,
+                headers,
+                keepalive: true,
+                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);
+            }
+            return res;
+        }
+        catch (err) {
+            const code = extractErrCode(err);
+            if (code && ['ENOTFOUND', 'EAI_AGAIN', 'ETIMEDOUT', 'ECONNREFUSED'].includes(code)) {
+                throw new S3NetworkError(`S3 network error: ${code}`, code, err);
+            }
+            throw err;
+        }
+    }
+    async _handleErrorResponse(res) {
+        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;
+        this._log('error', `${ERROR_PREFIX}Request failed with status ${res.status}: ${svcCode} - ${errorMessage},err body: ${errorBody}`);
+        throw new S3ServiceError(`S3 returned ${res.status} – ${svcCode}`, res.status, svcCode, errorBody);
+    }
+    _buildCanonicalQueryString(queryParams) {
+        if (!queryParams || Object.keys(queryParams).length === 0) {
+            return '';
+        }
+        return Object.keys(queryParams)
+            .map(key => `${encodeURIComponent(key)}=${encodeURIComponent(queryParams[key])}`)
+            .sort()
+            .join('&');
+    }
+    _getSignatureKey(dateStamp) {
+        const kDate = hmac(`AWS4${this.secretAccessKey}`, dateStamp);
+        const kRegion = hmac(kDate, this.region);
+        const kService = hmac(kRegion, S3_SERVICE);
+        return hmac(kService, AWS_REQUEST_TYPE);
+    }
+}
+
+export { s3mini as default, runInBatches, s3mini, sanitizeETag };
+//# sourceMappingURL=s3mini.js.map