@rbaileysr/zephyr-managed-api 1.2.1 → 1.2.9

package/dist/groups/Private/PrivateAttachments.js

@@ -0,0 +1,2146 @@
+/*!
+ * Copyright Adaptavist 2025 (c) All rights reserved
+ */
+import { PrivateBase } from './PrivateBase';
+import { BadRequestError, UnauthorizedError, ForbiddenError, NotFoundError, ServerError, UnexpectedError, } from '../../utils';
+export class PrivateAttachments extends PrivateBase {
+    constructor(apiConnection) {
+        super(apiConnection);
+    }
+    /**
+     * Get attachments for a test case using private API
+     *
+     * Retrieves all attachment details for a test case, including signed S3 URLs
+     * for downloading the attachments.
+     *
+     * ⚠️ WARNING: This uses a private Zephyr API endpoint that is not officially supported.
+     * The endpoint may change or be removed at any time without notice.
+     *
+     * @param credentials - Private API credentials
+     * @param request - Get attachments request
+     * @param request.testCaseKey - Test case key (e.g., 'PROJ-T1'). The numeric ID will be looked up automatically if Zephyr Connector is available.
+     * @param request.projectId - Jira project ID (numeric, not the project key)
+     * @returns Test case attachments response with array of attachment details
+     * @throws {BadRequestError} If the request is invalid
+     * @throws {UnauthorizedError} If authentication fails
+     * @throws {ForbiddenError} If the user doesn't have permission
+     * @throws {NotFoundError} If the test case is not found
+     * @throws {ServerError} If the server returns an error
+     * @throws {UnexpectedError} If test case ID cannot be looked up from key and Zephyr Connector is not available
+     */
+    async getTestCaseAttachments(credentials, request) {
+        // Get test case ID from key if we have API connection
+        let testCaseId;
+        if (this.testCaseGroup) {
+            try {
+                const testCase = await this.testCaseGroup.getTestCase({ testCaseKey: request.testCaseKey });
+                if (!testCase) {
+                    throw new NotFoundError(`Test case with key '${request.testCaseKey}' not found.`);
+                }
+                testCaseId = testCase.id;
+            }
+            catch (error) {
+                if (error instanceof NotFoundError) {
+                    throw new NotFoundError(`Test case with key '${request.testCaseKey}' not found.`);
+                }
+                throw new UnexpectedError(`Failed to look up test case ID from key '${request.testCaseKey}'. Ensure Zephyr Connector is configured.`, error);
+            }
+        }
+        else {
+            throw new UnexpectedError('Cannot look up test case ID from key. This method requires Zephyr Connector to be configured. Use createZephyrApi() with an API Connection.');
+        }
+        // Get Context JWT
+        const contextJwt = await this.getContextJwt(credentials);
+        const url = `${this.privateApiBaseUrl}/testcase/${testCaseId}?fields=attachments`;
+        const headers = {
+            accept: 'application/json',
+            authorization: `JWT ${contextJwt}`,
+            'jira-project-id': String(request.projectId),
+        };
+        try {
+            const response = await fetch(url, {
+                method: 'GET',
+                headers,
+            });
+            if (!response.ok) {
+                if (response.status === 400) {
+                    throw new BadRequestError('Invalid request parameters for getting attachments.');
+                }
+                if (response.status === 401) {
+                    throw new UnauthorizedError('Failed to authenticate. Please check your credentials.');
+                }
+                if (response.status === 403) {
+                    throw new ForbiddenError('Insufficient permissions to get attachments.');
+                }
+                if (response.status === 404) {
+                    throw new NotFoundError(`Test case with key '${request.testCaseKey}' not found.`);
+                }
+                throw new ServerError(`Failed to get test case attachments. Status: ${response.status}`, response.status, response.statusText);
+            }
+            return (await response.json());
+        }
+        catch (error) {
+            if (error instanceof BadRequestError ||
+                error instanceof UnauthorizedError ||
+                error instanceof ForbiddenError ||
+                error instanceof NotFoundError ||
+                error instanceof ServerError ||
+                error instanceof UnexpectedError) {
+                throw error;
+            }
+            throw new UnexpectedError('Unexpected error while getting test case attachments', error);
+        }
+    }
+    /**
+     * Download an attachment from a test case using private API
+     *
+     * Downloads an attachment file into memory. This method:
+     * 1. Gets fresh attachment details (including a fresh signed S3 URL)
+     * 2. Downloads the file from the signed URL
+     * 3. Returns the file as a Blob
+     *
+     * ⚠️ WARNING: This uses private Zephyr API endpoints that are not officially supported.
+     * The endpoints may change or be removed at any time without notice.
+     *
+     * @param credentials - Private API credentials
+     * @param request - Download attachment request
+     * @param request.testCaseKey - Test case key (e.g., 'PROJ-T1'). The numeric ID will be looked up automatically if Zephyr Connector is available.
+     * @param request.projectId - Jira project ID (numeric, not the project key)
+     * @param request.attachmentId - Attachment ID (UUID string, e.g., 'c3f14125-638f-47f9-9211-12a9777c09e7')
+     * @returns Blob containing the attachment file data
+     * @throws {BadRequestError} If the request is invalid
+     * @throws {UnauthorizedError} If authentication fails
+     * @throws {ForbiddenError} If the user doesn't have permission
+     * @throws {NotFoundError} If the test case or attachment is not found
+     * @throws {ServerError} If the server returns an error
+     * @throws {UnexpectedError} If test case ID cannot be looked up from key and Zephyr Connector is not available, or if download fails
+     */
+    async downloadAttachment(credentials, request) {
+        // Step 1: Get fresh attachment details (including fresh signed URL)
+        const attachmentsResponse = await this.getTestCaseAttachments(credentials, {
+            testCaseKey: request.testCaseKey,
+            projectId: request.projectId,
+        });
+        // Step 2: Find the requested attachment
+        const attachment = attachmentsResponse.attachments.find((att) => att.id === request.attachmentId);
+        if (!attachment) {
+            throw new NotFoundError(`Attachment with ID '${request.attachmentId}' not found for test case '${request.testCaseKey}'.`);
+        }
+        // Step 3: Download the file from the signed S3 URL
+        try {
+            const downloadResponse = await fetch(attachment.url, {
+                method: 'GET',
+            });
+            if (!downloadResponse.ok) {
+                if (downloadResponse.status === 403) {
+                    throw new ForbiddenError('Failed to download attachment. The signed URL may have expired. Please try again.');
+                }
+                if (downloadResponse.status === 404) {
+                    throw new NotFoundError('Attachment file not found on S3.');
+                }
+                throw new ServerError(`Failed to download attachment. Status: ${downloadResponse.status}`, downloadResponse.status, downloadResponse.statusText);
+            }
+            // Return as Blob
+            return await downloadResponse.blob();
+        }
+        catch (error) {
+            if (error instanceof ForbiddenError || error instanceof NotFoundError || error instanceof ServerError) {
+                throw error;
+            }
+            throw new UnexpectedError('Unexpected error while downloading attachment', error);
+        }
+    }
+    /**
+     * Create an attachment for a test case using private API
+     *
+     * Uploads a file attachment to a test case. This involves:
+     * 1. Getting upload details (S3 credentials)
+     * 2. Uploading the file to S3
+     * 3. Saving attachment metadata
+     *
+     * ⚠️ WARNING: This uses private Zephyr API endpoints that are not officially supported.
+     * The endpoints may change or be removed at any time without notice.
+     *
+     * @param credentials - Private API credentials
+     * @param request - Attachment creation request
+     * @param request.testCaseKey - Test case key (e.g., 'PROJ-T1'). The numeric ID will be looked up automatically if Zephyr Connector is available.
+     * @param request.projectId - Jira project ID (numeric, not the project key)
+     * @param request.file - File to upload (Blob or ArrayBuffer)
+     * @param request.fileName - Name of the file
+     * @param request.userAccountId - Atlassian account ID (e.g., '5d6fdc98dc6e480dbc021aae')
+     * @returns Attachment metadata response
+     * @throws {BadRequestError} If the request is invalid
+     * @throws {UnauthorizedError} If authentication fails
+     * @throws {ForbiddenError} If the user doesn't have permission
+     * @throws {NotFoundError} If the test case is not found
+     * @throws {ServerError} If the server returns an error
+     * @throws {UnexpectedError} If test case ID cannot be looked up from key and Zephyr Connector is not available
+     */
+    async createTestCaseAttachment(credentials, request) {
+        // Get test case ID from key if we have API connection
+        let testCaseId;
+        if (this.testCaseGroup) {
+            try {
+                const testCase = await this.testCaseGroup.getTestCase({ testCaseKey: request.testCaseKey });
+                if (!testCase) {
+                    throw new NotFoundError(`Test case with key '${request.testCaseKey}' not found.`);
+                }
+                testCaseId = testCase.id;
+            }
+            catch (error) {
+                if (error instanceof NotFoundError) {
+                    throw new NotFoundError(`Test case with key '${request.testCaseKey}' not found.`);
+                }
+                throw new UnexpectedError(`Failed to look up test case ID from key '${request.testCaseKey}'. Ensure Zephyr Connector is configured.`, error);
+            }
+        }
+        else {
+            throw new UnexpectedError('Cannot look up test case ID from key. This method requires Zephyr Connector to be configured. Use createZephyrApi() with an API Connection.');
+        }
+        // Get Context JWT
+        const contextJwt = await this.getContextJwt(credentials);
+        // Step 1: Get upload details
+        const uploadDetails = await this.getUploadDetails(contextJwt);
+        // Step 2: Upload to S3
+        const s3Info = await this.uploadToS3(uploadDetails, request.projectId, testCaseId, request.userAccountId, request.file, request.fileName);
+        // Step 3: Save metadata
+        return await this.saveAttachmentMetadata(contextJwt, request.projectId, testCaseId, request.userAccountId, s3Info.s3Key, s3Info.fileName, s3Info.mimeType, s3Info.fileSize);
+    }
+    /**
+     * Get upload details for attachment upload
+     *
+     * Retrieves S3 upload credentials and configuration needed to upload an attachment.
+     *
+     * ⚠️ WARNING: This uses a private Zephyr API endpoint that is not officially supported.
+     * The endpoint may change or be removed at any time without notice.
+     *
+     * @param contextJwt - Jira Context JWT token
+     * @returns Upload details including S3 bucket URL, credentials, and policy
+     * @throws {UnauthorizedError} If authentication fails
+     * @throws {ServerError} If the server returns an error
+     */
+    async getUploadDetails(contextJwt) {
+        const url = 'https://app.tm4j.smartbear.com/backend/rest/tests/2.0/uploaddetails/attachment';
+        const headers = {
+            Authorization: `JWT ${contextJwt}`,
+            Accept: 'application/json',
+        };
+        try {
+            const response = await fetch(url, {
+                method: 'GET',
+                headers,
+            });
+            if (!response.ok) {
+                if (response.status === 401) {
+                    throw new UnauthorizedError('Authentication failed. Please check your credentials.');
+                }
+                throw new ServerError(`Failed to get upload details. Status: ${response.status}`, response.status, response.statusText);
+            }
+            return (await response.json());
+        }
+        catch (error) {
+            if (error instanceof UnauthorizedError || error instanceof ServerError) {
+                throw error;
+            }
+            throw new UnexpectedError('Unexpected error while getting upload details', error);
+        }
+    }
+    /**
+     * Upload file to S3
+     *
+     * Uploads a file to S3 using the credentials from upload details.
+     *
+     * @param upload - Upload details from getUploadDetails
+     * @param projectId - Jira project ID
+     * @param testCaseId - Numeric test case ID
+     * @param userAccountId - Atlassian account ID
+     * @param file - File to upload (Blob or ArrayBuffer)
+     * @param fileName - Name of the file
+     * @returns S3 upload information
+     * @throws {UnexpectedError} If upload fails
+     */
+    async uploadToS3(upload, projectId, testCaseId, userAccountId, file, fileName) {
+        const bucketUrl = upload.bucketUrl;
+        const keyPrefix = upload.keyPrefix;
+        const credential = upload.credential;
+        const date = upload.date;
+        const policy = upload.policy;
+        const signature = upload.signature;
+        // Generate UUID for file
+        const fileUuid = this.generateUUID();
+        const s3Key = `${keyPrefix}/project/${projectId}/testcase/${testCaseId}/${fileUuid}`;
+        // Determine MIME type
+        const mimeType = this.getMimeType(fileName);
+        // Get file size
+        const fileSize = file instanceof Blob ? file.size : file.byteLength;
+        // Create form data
+        const formData = new FormData();
+        formData.append('key', s3Key);
+        formData.append('acl', 'private');
+        formData.append('Policy', policy);
+        formData.append('X-Amz-Credential', credential);
+        formData.append('X-Amz-Algorithm', 'AWS4-HMAC-SHA256');
+        formData.append('X-Amz-Date', date);
+        formData.append('X-Amz-Signature', signature);
+        formData.append('X-Amz-Meta-user-account-id', userAccountId);
+        formData.append('X-Amz-Meta-name', fileName);
+        formData.append('Content-Type', mimeType);
+        // Add file
+        if (file instanceof Blob) {
+            formData.append('file', file, fileName);
+        }
+        else {
+            formData.append('file', new Blob([file], { type: mimeType }), fileName);
+        }
+        try {
+            const response = await fetch(bucketUrl, {
+                method: 'POST',
+                body: formData,
+            });
+            if (!response.ok && response.status !== 200 && response.status !== 201 && response.status !== 204) {
+                const errorText = await response.text().catch(() => 'Upload failed');
+                throw new UnexpectedError(`Failed to upload file to S3: ${errorText}`);
+            }
+            return {
+                s3Key,
+                fileName,
+                mimeType,
+                fileSize,
+            };
+        }
+        catch (error) {
+            if (error instanceof UnexpectedError) {
+                throw error;
+            }
+            throw new UnexpectedError('Unexpected error while uploading file to S3', error);
+        }
+    }
+    /**
+     * Save attachment metadata
+     *
+     * Saves metadata for an uploaded attachment.
+     *
+     * @param contextJwt - Jira Context JWT token
+     * @param projectId - Jira project ID
+     * @param testCaseId - Numeric test case ID
+     * @param userAccountId - Atlassian account ID
+     * @param s3Key - S3 key from upload
+     * @param fileName - File name
+     * @param mimeType - MIME type
+     * @param fileSize - File size in bytes
+     * @returns Attachment metadata response
+     * @throws {BadRequestError} If the request is invalid
+     * @throws {UnauthorizedError} If authentication fails
+     * @throws {ServerError} If the server returns an error
+     */
+    async saveAttachmentMetadata(contextJwt, projectId, testCaseId, userAccountId, s3Key, fileName, mimeType, fileSize) {
+        const url = 'https://app.tm4j.smartbear.com/backend/rest/tests/2.0/attachment/metadata';
+        const headers = {
+            Authorization: `JWT ${contextJwt}`,
+            'jira-project-id': String(projectId),
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+        };
+        const createdOn = new Date().toISOString();
+        const payload = {
+            createdOn,
+            mimeType,
+            name: fileName,
+            s3Key,
+            size: fileSize,
+            testCaseId,
+            userAccountId,
+        };
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(payload),
+            });
+            if (!response.ok) {
+                if (response.status === 400) {
+                    const errorText = await response.text().catch(() => 'Bad Request');
+                    throw new BadRequestError(`Failed to save attachment metadata: ${errorText}`, response.statusText);
+                }
+                if (response.status === 401) {
+                    throw new UnauthorizedError('Authentication failed. Please check your credentials.');
+                }
+                throw new ServerError(`Failed to save attachment metadata. Status: ${response.status}`, response.status, response.statusText);
+            }
+            return await response.json();
+        }
+        catch (error) {
+            if (error instanceof BadRequestError ||
+                error instanceof UnauthorizedError ||
+                error instanceof ServerError) {
+                throw error;
+            }
+            throw new UnexpectedError('Unexpected error while saving attachment metadata', error);
+        }
+    }
+    /**
+     * Generate a UUID v4 (compatible with ScriptRunner Connect runtime)
+     *
+     * Uses crypto.getRandomValues() which is available in web standards
+     */
+    generateUUID() {
+        // Use crypto.getRandomValues() which is available in ScriptRunner Connect
+        const bytes = new Uint8Array(16);
+        crypto.getRandomValues(bytes);
+        // Set version (4) and variant bits
+        bytes[6] = (bytes[6] & 0x0f) | 0x40; // Version 4
+        bytes[8] = (bytes[8] & 0x3f) | 0x80; // Variant 10
+        // Convert to UUID string format
+        const hex = [];
+        for (let i = 0; i < bytes.length; i++) {
+            hex.push(bytes[i].toString(16).padStart(2, '0'));
+        }
+        return [
+            hex.slice(0, 4).join(''),
+            hex.slice(4, 6).join(''),
+            hex.slice(6, 8).join(''),
+            hex.slice(8, 10).join(''),
+            hex.slice(10, 16).join(''),
+        ].join('-');
+    }
+    /**
+     * Get MIME type from file name
+     */
+    getMimeType(fileName) {
+        // Simple MIME type detection based on extension
+        const extension = fileName.split('.').pop()?.toLowerCase();
+        const mimeTypes = {
+            png: 'image/png',
+            jpg: 'image/jpeg',
+            jpeg: 'image/jpeg',
+            gif: 'image/gif',
+            pdf: 'application/pdf',
+            txt: 'text/plain',
+            csv: 'text/csv',
+            json: 'application/json',
+            xml: 'application/xml',
+            zip: 'application/zip',
+        };
+        return mimeTypes[extension || ''] || 'application/octet-stream';
+    }
+    /**
+     * Get attachments for a test cycle using private API
+     *
+     * Retrieves all attachment details for a test cycle, including signed S3 URLs
+     * for downloading the attachments.
+     *
+     * ⚠️ WARNING: This uses a private Zephyr API endpoint that is not officially supported.
+     * The endpoint may change or be removed at any time without notice.
+     *
+     * @param credentials - Private API credentials
+     * @param request - Get attachments request
+     * @param request.testCycleKey - Test cycle key (e.g., 'PROJ-R1'). The numeric ID will be looked up automatically if Zephyr Connector is available.
+     * @param request.projectId - Jira project ID (numeric, not the project key)
+     * @returns Test cycle attachments response with array of attachment details
+     * @throws {BadRequestError} If the request is invalid
+     * @throws {UnauthorizedError} If authentication fails
+     * @throws {ForbiddenError} If the user doesn't have permission
+     * @throws {NotFoundError} If the test cycle is not found
+     * @throws {ServerError} If the server returns an error
+     * @throws {UnexpectedError} If test cycle ID cannot be looked up from key and Zephyr Connector is not available
+     */
+    async getTestCycleAttachments(credentials, request) {
+        // Get test cycle ID from key if we have API connection
+        let testCycleId;
+        if (this.testCycleGroup) {
+            try {
+                const testCycle = await this.testCycleGroup.getTestCycle({ testCycleIdOrKey: request.testCycleKey });
+                if (!testCycle) {
+                    throw new NotFoundError(`Test cycle with key '${request.testCycleKey}' not found.`);
+                }
+                testCycleId = testCycle.id;
+            }
+            catch (error) {
+                if (error instanceof NotFoundError) {
+                    throw new NotFoundError(`Test cycle with key '${request.testCycleKey}' not found.`);
+                }
+                throw new UnexpectedError(`Failed to look up test cycle ID from key '${request.testCycleKey}'. Ensure Zephyr Connector is configured.`, error);
+            }
+        }
+        else {
+            throw new UnexpectedError('Cannot look up test cycle ID from key. This method requires Zephyr Connector to be configured. Use createZephyrApi() with an API Connection.');
+        }
+        // Get Context JWT
+        const contextJwt = await this.getContextJwt(credentials);
+        const url = `${this.privateApiBaseUrl}/testrun/${testCycleId}?fields=attachments`;
+        const headers = {
+            accept: 'application/json',
+            authorization: `JWT ${contextJwt}`,
+            'jira-project-id': String(request.projectId),
+        };
+        try {
+            const response = await fetch(url, {
+                method: 'GET',
+                headers,
+            });
+            if (!response.ok) {
+                if (response.status === 400) {
+                    throw new BadRequestError('Invalid request parameters for getting attachments.');
+                }
+                if (response.status === 401) {
+                    throw new UnauthorizedError('Failed to authenticate. Please check your credentials.');
+                }
+                if (response.status === 403) {
+                    throw new ForbiddenError('Insufficient permissions to get attachments.');
+                }
+                if (response.status === 404) {
+                    throw new NotFoundError(`Test cycle with key '${request.testCycleKey}' not found.`);
+                }
+                throw new ServerError(`Failed to get test cycle attachments. Status: ${response.status}`, response.status, response.statusText);
+            }
+            return (await response.json());
+        }
+        catch (error) {
+            if (error instanceof BadRequestError ||
+                error instanceof UnauthorizedError ||
+                error instanceof ForbiddenError ||
+                error instanceof NotFoundError ||
+                error instanceof ServerError ||
+                error instanceof UnexpectedError) {
+                throw error;
+            }
+            throw new UnexpectedError('Unexpected error while getting test cycle attachments', error);
+        }
+    }
+    /**
+     * Download an attachment from a test cycle using private API
+     *
+     * Downloads an attachment file into memory. This method:
+     * 1. Gets fresh attachment details (including a fresh signed S3 URL)
+     * 2. Downloads the file from the signed URL
+     * 3. Returns the file as a Blob
+     *
+     * ⚠️ WARNING: This uses private Zephyr API endpoints that are not officially supported.
+     * The endpoints may change or be removed at any time without notice.
+     *
+     * @param credentials - Private API credentials
+     * @param request - Download attachment request
+     * @param request.testCycleKey - Test cycle key (e.g., 'PROJ-R1'). The numeric ID will be looked up automatically if Zephyr Connector is available.
+     * @param request.projectId - Jira project ID (numeric, not the project key)
+     * @param request.attachmentId - Attachment ID (UUID string, e.g., '13fbe8bc-a87b-4db1-bf01-8b4451db79fb')
+     * @returns Blob containing the attachment file data
+     * @throws {BadRequestError} If the request is invalid
+     * @throws {UnauthorizedError} If authentication fails
+     * @throws {ForbiddenError} If the user doesn't have permission
+     * @throws {NotFoundError} If the test cycle or attachment is not found
+     * @throws {ServerError} If the server returns an error
+     * @throws {UnexpectedError} If test cycle ID cannot be looked up from key and Zephyr Connector is not available, or if download fails
+     */
+    async downloadTestCycleAttachment(credentials, request) {
+        // Step 1: Get fresh attachment details (including fresh signed URL)
+        const attachmentsResponse = await this.getTestCycleAttachments(credentials, {
+            testCycleKey: request.testCycleKey,
+            projectId: request.projectId,
+        });
+        // Step 2: Find the requested attachment
+        const attachment = attachmentsResponse.attachments.find((att) => att.id === request.attachmentId);
+        if (!attachment) {
+            throw new NotFoundError(`Attachment with ID '${request.attachmentId}' not found for test cycle '${request.testCycleKey}'.`);
+        }
+        // Step 3: Download the file from the signed S3 URL
+        try {
+            const downloadResponse = await fetch(attachment.url, {
+                method: 'GET',
+            });
+            if (!downloadResponse.ok) {
+                if (downloadResponse.status === 403) {
+                    throw new ForbiddenError('Failed to download attachment. The signed URL may have expired. Please try again.');
+                }
+                if (downloadResponse.status === 404) {
+                    throw new NotFoundError('Attachment file not found on S3.');
+                }
+                throw new ServerError(`Failed to download attachment. Status: ${downloadResponse.status}`, downloadResponse.status, downloadResponse.statusText);
+            }
+            // Return as Blob
+            return await downloadResponse.blob();
+        }
+        catch (error) {
+            if (error instanceof ForbiddenError || error instanceof NotFoundError || error instanceof ServerError) {
+                throw error;
+            }
+            throw new UnexpectedError('Unexpected error while downloading attachment', error);
+        }
+    }
+    /**
+     * Create an attachment for a test cycle using private API
+     *
+     * Uploads a file attachment to a test cycle. This involves:
+     * 1. Getting upload details (S3 credentials)
+     * 2. Uploading the file to S3
+     * 3. Saving attachment metadata
+     *
+     * ⚠️ WARNING: This uses private Zephyr API endpoints that are not officially supported.
+     * The endpoints may change or be removed at any time without notice.
+     *
+     * @param credentials - Private API credentials
+     * @param request - Attachment creation request
+     * @param request.testCycleKey - Test cycle key (e.g., 'PROJ-R1'). The numeric ID will be looked up automatically if Zephyr Connector is available.
+     * @param request.projectId - Jira project ID (numeric, not the project key)
+     * @param request.file - File to upload (Blob or ArrayBuffer)
+     * @param request.fileName - Name of the file
+     * @param request.userAccountId - Atlassian account ID (e.g., '5d6fdc98dc6e480dbc021aae')
+     * @returns Attachment metadata response
+     * @throws {BadRequestError} If the request is invalid
+     * @throws {UnauthorizedError} If authentication fails
+     * @throws {ForbiddenError} If the user doesn't have permission
+     * @throws {NotFoundError} If the test cycle is not found
+     * @throws {ServerError} If the server returns an error
+     * @throws {UnexpectedError} If test cycle ID cannot be looked up from key and Zephyr Connector is not available
+     */
+    async createTestCycleAttachment(credentials, request) {
+        // Get test cycle ID from key if we have API connection
+        let testCycleId;
+        if (this.testCycleGroup) {
+            try {
+                const testCycle = await this.testCycleGroup.getTestCycle({ testCycleIdOrKey: request.testCycleKey });
+                if (!testCycle) {
+                    throw new NotFoundError(`Test cycle with key '${request.testCycleKey}' not found.`);
+                }
+                testCycleId = testCycle.id;
+            }
+            catch (error) {
+                if (error instanceof NotFoundError) {
+                    throw new NotFoundError(`Test cycle with key '${request.testCycleKey}' not found.`);
+                }
+                throw new UnexpectedError(`Failed to look up test cycle ID from key '${request.testCycleKey}'. Ensure Zephyr Connector is configured.`, error);
+            }
+        }
+        else {
+            throw new UnexpectedError('Cannot look up test cycle ID from key. This method requires Zephyr Connector to be configured. Use createZephyrApi() with an API Connection.');
+        }
+        // Get Context JWT
+        const contextJwt = await this.getContextJwt(credentials);
+        // Step 1: Get upload details
+        const uploadDetails = await this.getUploadDetails(contextJwt);
+        // Step 2: Upload to S3
+        const s3Info = await this.uploadToS3ForTestCycle(uploadDetails, request.projectId, testCycleId, request.userAccountId, request.file, request.fileName);
+        // Step 3: Save metadata
+        return await this.saveTestCycleAttachmentMetadata(contextJwt, request.projectId, testCycleId, request.userAccountId, s3Info.s3Key, s3Info.fileName, s3Info.mimeType, s3Info.fileSize);
+    }
+    /**
+     * Get attachments for a test plan using private API
+     *
+     * Retrieves all attachment details for a test plan, including signed S3 URLs
+     * for downloading the attachments.
+     *
+     * ⚠️ WARNING: This uses a private Zephyr API endpoint that is not officially supported.
+     * The endpoint may change or be removed at any time without notice.
+     *
+     * @param credentials - Private API credentials
+     * @param request - Get attachments request
+     * @param request.testPlanKey - Test plan key (e.g., 'PROJ-P1'). The numeric ID will be looked up automatically if Zephyr Connector is available.
+     * @param request.projectId - Jira project ID (numeric, not the project key)
+     * @returns Test plan attachments response with array of attachment details
+     * @throws {BadRequestError} If the request is invalid
+     * @throws {UnauthorizedError} If authentication fails
+     * @throws {ForbiddenError} If the user doesn't have permission
+     * @throws {NotFoundError} If the test plan is not found
+     * @throws {ServerError} If the server returns an error
+     * @throws {UnexpectedError} If test plan ID cannot be looked up from key and Zephyr Connector is not available
+     */
+    async getTestPlanAttachments(credentials, request) {
+        // Get test plan ID from key if we have API connection
+        let testPlanId;
+        if (this.testPlanGroup) {
+            try {
+                const testPlan = await this.testPlanGroup.getTestPlan({ testPlanIdOrKey: request.testPlanKey });
+                if (!testPlan) {
+                    throw new NotFoundError(`Test plan with key '${request.testPlanKey}' not found.`);
+                }
+                testPlanId = testPlan.id;
+            }
+            catch (error) {
+                if (error instanceof NotFoundError) {
+                    throw new NotFoundError(`Test plan with key '${request.testPlanKey}' not found.`);
+                }
+                throw new UnexpectedError(`Failed to look up test plan ID from key '${request.testPlanKey}'. Ensure Zephyr Connector is configured.`, error);
+            }
+        }
+        else {
+            throw new UnexpectedError('Cannot look up test plan ID from key. This method requires Zephyr Connector to be configured. Use createZephyrApi() with an API Connection.');
+        }
+        // Get Context JWT
+        const contextJwt = await this.getContextJwt(credentials);
+        const url = `${this.privateApiBaseUrl}/testplan/${testPlanId}?fields=attachments`;
+        const headers = {
+            accept: 'application/json',
+            authorization: `JWT ${contextJwt}`,
+            'jira-project-id': String(request.projectId),
+        };
+        try {
+            const response = await fetch(url, {
+                method: 'GET',
+                headers,
+            });
+            if (!response.ok) {
+                if (response.status === 400) {
+                    throw new BadRequestError('Invalid request parameters for getting attachments.');
+                }
+                if (response.status === 401) {
+                    throw new UnauthorizedError('Failed to authenticate. Please check your credentials.');
+                }
+                if (response.status === 403) {
+                    throw new ForbiddenError('Insufficient permissions to get attachments.');
+                }
+                if (response.status === 404) {
+                    throw new NotFoundError(`Test plan with key '${request.testPlanKey}' not found.`);
+                }
+                throw new ServerError(`Failed to get test plan attachments. Status: ${response.status}`, response.status, response.statusText);
+            }
+            return (await response.json());
+        }
+        catch (error) {
+            if (error instanceof BadRequestError ||
+                error instanceof UnauthorizedError ||
+                error instanceof ForbiddenError ||
+                error instanceof NotFoundError ||
+                error instanceof ServerError ||
+                error instanceof UnexpectedError) {
+                throw error;
+            }
+            throw new UnexpectedError('Unexpected error while getting test plan attachments', error);
+        }
+    }
+    /**
+     * Download an attachment from a test plan using private API
+     *
+     * Downloads an attachment file into memory. This method:
+     * 1. Gets fresh attachment details (including a fresh signed S3 URL)
+     * 2. Downloads the file from the signed URL
+     * 3. Returns the file as a Blob
+     *
+     * ⚠️ WARNING: This uses private Zephyr API endpoints that are not officially supported.
+     * The endpoints may change or be removed at any time without notice.
+     *
+     * @param credentials - Private API credentials
+     * @param request - Download attachment request
+     * @param request.testPlanKey - Test plan key (e.g., 'PROJ-P1'). The numeric ID will be looked up automatically if Zephyr Connector is available.
+     * @param request.projectId - Jira project ID (numeric, not the project key)
+     * @param request.attachmentId - Attachment ID (UUID string)
+     * @returns Blob containing the attachment file data
+     * @throws {BadRequestError} If the request is invalid
+     * @throws {UnauthorizedError} If authentication fails
+     * @throws {ForbiddenError} If the user doesn't have permission
+     * @throws {NotFoundError} If the test plan or attachment is not found
+     * @throws {ServerError} If the server returns an error
+     * @throws {UnexpectedError} If test plan ID cannot be looked up from key and Zephyr Connector is not available, or if download fails
+     */
+    async downloadTestPlanAttachment(credentials, request) {
+        // Step 1: Get fresh attachment details (including fresh signed URL)
+        const attachmentsResponse = await this.getTestPlanAttachments(credentials, {
+            testPlanKey: request.testPlanKey,
+            projectId: request.projectId,
+        });
+        // Step 2: Find the requested attachment
+        const attachment = attachmentsResponse.attachments.find((att) => att.id === request.attachmentId);
+        if (!attachment) {
+            throw new NotFoundError(`Attachment with ID '${request.attachmentId}' not found for test plan '${request.testPlanKey}'.`);
+        }
+        // Step 3: Download the file from the signed S3 URL
+        try {
+            const downloadResponse = await fetch(attachment.url, {
+                method: 'GET',
+            });
+            if (!downloadResponse.ok) {
+                if (downloadResponse.status === 403) {
+                    throw new ForbiddenError('Failed to download attachment. The signed URL may have expired. Please try again.');
+                }
+                if (downloadResponse.status === 404) {
+                    throw new NotFoundError('Attachment file not found on S3.');
+                }
+                throw new ServerError(`Failed to download attachment. Status: ${downloadResponse.status}`, downloadResponse.status, downloadResponse.statusText);
+            }
+            // Return as Blob
+            return await downloadResponse.blob();
+        }
+        catch (error) {
+            if (error instanceof ForbiddenError || error instanceof NotFoundError || error instanceof ServerError) {
+                throw error;
+            }
+            throw new UnexpectedError('Unexpected error while downloading attachment', error);
+        }
+    }
+    /**
+     * Create an attachment for a test plan using private API
+     *
+     * Uploads a file attachment to a test plan. This involves:
+     * 1. Getting upload details (S3 credentials)
+     * 2. Uploading the file to S3
+     * 3. Saving attachment metadata
+     *
+     * ⚠️ WARNING: This uses private Zephyr API endpoints that are not officially supported.
+     * The endpoints may change or be removed at any time without notice.
+     *
+     * @param credentials - Private API credentials
+     * @param request - Attachment creation request
+     * @param request.testPlanKey - Test plan key (e.g., 'PROJ-P1'). The numeric ID will be looked up automatically if Zephyr Connector is available.
+     * @param request.projectId - Jira project ID (numeric, not the project key)
+     * @param request.file - File to upload (Blob or ArrayBuffer)
+     * @param request.fileName - Name of the file
+     * @param request.userAccountId - Atlassian account ID (e.g., '5d6fdc98dc6e480dbc021aae')
+     * @returns Attachment metadata response
+     * @throws {BadRequestError} If the request is invalid
+     * @throws {UnauthorizedError} If authentication fails
+     * @throws {ForbiddenError} If the user doesn't have permission
+     * @throws {NotFoundError} If the test plan is not found
+     * @throws {ServerError} If the server returns an error
+     * @throws {UnexpectedError} If test plan ID cannot be looked up from key and Zephyr Connector is not available
+     */
+    async createTestPlanAttachment(credentials, request) {
+        // Get test plan ID from key if we have API connection
+        let testPlanId;
+        if (this.testPlanGroup) {
+            try {
+                const testPlan = await this.testPlanGroup.getTestPlan({ testPlanIdOrKey: request.testPlanKey });
+                if (!testPlan) {
+                    throw new NotFoundError(`Test plan with key '${request.testPlanKey}' not found.`);
+                }
+                testPlanId = testPlan.id;
+            }
+            catch (error) {
+                if (error instanceof NotFoundError) {
+                    throw new NotFoundError(`Test plan with key '${request.testPlanKey}' not found.`);
+                }
+                throw new UnexpectedError(`Failed to look up test plan ID from key '${request.testPlanKey}'. Ensure Zephyr Connector is configured.`, error);
+            }
+        }
+        else {
+            throw new UnexpectedError('Cannot look up test plan ID from key. This method requires Zephyr Connector to be configured. Use createZephyrApi() with an API Connection.');
+        }
+        // Get Context JWT
+        const contextJwt = await this.getContextJwt(credentials);
+        // Step 1: Get upload details
+        const uploadDetails = await this.getUploadDetails(contextJwt);
+        // Step 2: Upload to S3
+        const s3Info = await this.uploadToS3ForTestPlan(uploadDetails, request.projectId, testPlanId, request.userAccountId, request.file, request.fileName);
+        // Step 3: Save metadata
+        return await this.saveTestPlanAttachmentMetadata(contextJwt, request.projectId, testPlanId, request.userAccountId, s3Info.s3Key, s3Info.fileName, s3Info.mimeType, s3Info.fileSize);
+    }
+    /**
+     * Upload file to S3 for test cycle
+     *
+     * Uploads a file to S3 using the credentials from upload details.
+     * Uses "testrun" in the S3 key path.
+     *
+     * @param upload - Upload details from getUploadDetails
+     * @param projectId - Jira project ID
+     * @param testCycleId - Numeric test cycle ID
+     * @param userAccountId - Atlassian account ID
+     * @param file - File to upload (Blob or ArrayBuffer)
+     * @param fileName - Name of the file
+     * @returns S3 upload information
+     * @throws {UnexpectedError} If upload fails
+     */
+    async uploadToS3ForTestCycle(upload, projectId, testCycleId, userAccountId, file, fileName) {
+        const bucketUrl = upload.bucketUrl;
+        const keyPrefix = upload.keyPrefix;
+        const credential = upload.credential;
+        const date = upload.date;
+        const policy = upload.policy;
+        const signature = upload.signature;
+        // Generate UUID for file
+        const fileUuid = this.generateUUID();
+        // Note: Test cycles use "testrun" in the S3 key path, and the keyPrefix includes "write/"
+        const s3Key = `${keyPrefix}/project/${projectId}/testrun/${testCycleId}/${fileUuid}`;
+        // Determine MIME type
+        const mimeType = this.getMimeType(fileName);
+        // Get file size
+        const fileSize = file instanceof Blob ? file.size : file.byteLength;
+        // Create form data
+        const formData = new FormData();
+        formData.append('key', s3Key);
+        formData.append('acl', 'private');
+        formData.append('Policy', policy);
+        formData.append('X-Amz-Credential', credential);
+        formData.append('X-Amz-Algorithm', 'AWS4-HMAC-SHA256');
+        formData.append('X-Amz-Date', date);
+        formData.append('X-Amz-Signature', signature);
+        formData.append('X-Amz-Meta-user-account-id', userAccountId);
+        formData.append('X-Amz-Meta-name', fileName);
+        formData.append('Content-Type', mimeType);
+        // Add file
+        if (file instanceof Blob) {
+            formData.append('file', file, fileName);
+        }
+        else {
+            formData.append('file', new Blob([file], { type: mimeType }), fileName);
+        }
+        try {
+            const response = await fetch(bucketUrl, {
+                method: 'POST',
+                body: formData,
+            });
+            if (!response.ok && response.status !== 200 && response.status !== 201 && response.status !== 204) {
+                const errorText = await response.text().catch(() => 'Upload failed');
+                throw new UnexpectedError(`Failed to upload file to S3: ${errorText}`);
+            }
+            return {
+                s3Key,
+                fileName,
+                mimeType,
+                fileSize,
+            };
+        }
+        catch (error) {
+            if (error instanceof UnexpectedError) {
+                throw error;
+            }
+            throw new UnexpectedError('Unexpected error while uploading file to S3', error);
+        }
+    }
+    /**
+     * Save test cycle attachment metadata
+     *
+     * Saves metadata for an uploaded test cycle attachment.
+     *
+     * @param contextJwt - Jira Context JWT token
+     * @param projectId - Jira project ID
+     * @param testCycleId - Numeric test cycle ID
+     * @param userAccountId - Atlassian account ID
+     * @param s3Key - S3 key from upload
+     * @param fileName - File name
+     * @param mimeType - MIME type
+     * @param fileSize - File size in bytes
+     * @returns Attachment metadata response
+     * @throws {BadRequestError} If the request is invalid
+     * @throws {UnauthorizedError} If authentication fails
+     * @throws {ServerError} If the server returns an error
+     */
+    async saveTestCycleAttachmentMetadata(contextJwt, projectId, testCycleId, userAccountId, s3Key, fileName, mimeType, fileSize) {
+        const url = 'https://app.tm4j.smartbear.com/backend/rest/tests/2.0/attachment/metadata';
+        const headers = {
+            Authorization: `JWT ${contextJwt}`,
+            'jira-project-id': String(projectId),
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+        };
+        const createdOn = new Date().toISOString();
+        const payload = {
+            createdOn,
+            mimeType,
+            name: fileName,
+            s3Key,
+            size: fileSize,
+            testCycleId,
+            userAccountId,
+        };
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(payload),
+            });
+            if (!response.ok) {
+                if (response.status === 400) {
+                    const errorText = await response.text().catch(() => 'Bad Request');
+                    throw new BadRequestError(`Failed to save attachment metadata: ${errorText}`, response.statusText);
+                }
+                if (response.status === 401) {
+                    throw new UnauthorizedError('Authentication failed. Please check your credentials.');
+                }
+                throw new ServerError(`Failed to save attachment metadata. Status: ${response.status}`, response.status, response.statusText);
+            }
+            return await response.json();
+        }
+        catch (error) {
+            if (error instanceof BadRequestError ||
+                error instanceof UnauthorizedError ||
+                error instanceof ServerError) {
+                throw error;
+            }
+            throw new UnexpectedError('Unexpected error while saving attachment metadata', error);
+        }
+    }
+    /**
+     * Upload file to S3 for test plan
+     *
+     * Uploads a file to S3 using the credentials from upload details.
+     * Uses "testplan" in the S3 key path.
+     *
+     * @param upload - Upload details from getUploadDetails
+     * @param projectId - Jira project ID
+     * @param testPlanId - Numeric test plan ID
+     * @param userAccountId - Atlassian account ID
+     * @param file - File to upload (Blob or ArrayBuffer)
+     * @param fileName - Name of the file
+     * @returns S3 upload information
+     * @throws {UnexpectedError} If upload fails
+     */
+    async uploadToS3ForTestPlan(upload, projectId, testPlanId, userAccountId, file, fileName) {
+        const bucketUrl = upload.bucketUrl;
+        const keyPrefix = upload.keyPrefix;
+        const credential = upload.credential;
+        const date = upload.date;
+        const policy = upload.policy;
+        const signature = upload.signature;
+        // Generate UUID for file
+        const fileUuid = this.generateUUID();
+        // Note: Test plans use "testplan" in the S3 key path, and the keyPrefix includes "write/"
+        const s3Key = `${keyPrefix}/project/${projectId}/testplan/${testPlanId}/${fileUuid}`;
+        // Determine MIME type
+        const mimeType = this.getMimeType(fileName);
+        // Get file size
+        const fileSize = file instanceof Blob ? file.size : file.byteLength;
+        // Create form data
+        const formData = new FormData();
+        formData.append('key', s3Key);
+        formData.append('acl', 'private');
+        formData.append('Policy', policy);
+        formData.append('X-Amz-Credential', credential);
+        formData.append('X-Amz-Algorithm', 'AWS4-HMAC-SHA256');
+        formData.append('X-Amz-Date', date);
+        formData.append('X-Amz-Signature', signature);
+        formData.append('X-Amz-Meta-user-account-id', userAccountId);
+        formData.append('X-Amz-Meta-name', fileName);
+        formData.append('Content-Type', mimeType);
+        // Add file
+        if (file instanceof Blob) {
+            formData.append('file', file, fileName);
+        }
+        else {
+            formData.append('file', new Blob([file], { type: mimeType }), fileName);
+        }
+        try {
+            const response = await fetch(bucketUrl, {
+                method: 'POST',
+                body: formData,
+            });
+            if (!response.ok && response.status !== 200 && response.status !== 201 && response.status !== 204) {
+                const errorText = await response.text().catch(() => 'Upload failed');
+                throw new UnexpectedError(`Failed to upload file to S3: ${errorText}`);
+            }
+            return {
+                s3Key,
+                fileName,
+                mimeType,
+                fileSize,
+            };
+        }
+        catch (error) {
+            if (error instanceof UnexpectedError) {
+                throw error;
+            }
+            throw new UnexpectedError('Unexpected error while uploading file to S3', error);
+        }
+    }
+    /**
+     * Save test plan attachment metadata
+     *
+     * Saves metadata for an uploaded test plan attachment.
+     *
+     * @param contextJwt - Jira Context JWT token
+     * @param projectId - Jira project ID
+     * @param testPlanId - Numeric test plan ID
+     * @param userAccountId - Atlassian account ID
+     * @param s3Key - S3 key from upload
+     * @param fileName - File name
+     * @param mimeType - MIME type
+     * @param fileSize - File size in bytes
+     * @returns Attachment metadata response
+     * @throws {BadRequestError} If the request is invalid
+     * @throws {UnauthorizedError} If authentication fails
+     * @throws {ServerError} If the server returns an error
+     */
+    async saveTestPlanAttachmentMetadata(contextJwt, projectId, testPlanId, userAccountId, s3Key, fileName, mimeType, fileSize) {
+        const url = 'https://app.tm4j.smartbear.com/backend/rest/tests/2.0/attachment/metadata';
+        const headers = {
+            Authorization: `JWT ${contextJwt}`,
+            'jira-project-id': String(projectId),
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+        };
+        const createdOn = new Date().toISOString();
+        const payload = {
+            createdOn,
+            mimeType,
+            name: fileName,
+            s3Key,
+            size: fileSize,
+            testPlanId,
+            userAccountId,
+        };
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(payload),
+            });
+            if (!response.ok) {
+                if (response.status === 400) {
+                    const errorText = await response.text().catch(() => 'Bad Request');
+                    throw new BadRequestError(`Failed to save attachment metadata: ${errorText}`, response.statusText);
+                }
+                if (response.status === 401) {
+                    throw new UnauthorizedError('Authentication failed. Please check your credentials.');
+                }
+                throw new ServerError(`Failed to save attachment metadata. Status: ${response.status}`, response.status, response.statusText);
+            }
+            return await response.json();
+        }
+        catch (error) {
+            if (error instanceof BadRequestError ||
+                error instanceof UnauthorizedError ||
+                error instanceof ServerError) {
+                throw error;
+            }
+            throw new UnexpectedError('Unexpected error while saving attachment metadata', error);
+        }
+    }
+    /**
+     * Get attachments for a test step using private API
+     *
+     * Retrieves all attachment details for a specific test step within a test case.
+     * Attachments are retrieved by getting the test case with fields including testScript.steps.attachments.
+     *
+     * ⚠️ WARNING: This uses a private Zephyr API endpoint that is not officially supported.
+     * The endpoint may change or be removed at any time without notice.
+     *
+     * @param credentials - Private API credentials
+     * @param request - Get attachments request
+     * @param request.testCaseKey - Test case key (e.g., 'PROJ-T1')
+     * @param request.stepIndex - Zero-based index of the test step in the test case
+     * @param request.projectId - Jira project ID (numeric, not the project key)
+     * @returns Test step attachments response with array of attachment details
+     * @throws {BadRequestError} If the request is invalid
+     * @throws {UnauthorizedError} If authentication fails
+     * @throws {ForbiddenError} If the user doesn't have permission
+     * @throws {NotFoundError} If the test case or step is not found
+     * @throws {ServerError} If the server returns an error
+     * @throws {UnexpectedError} If the test case cannot be retrieved
+     */
+    async getTestStepAttachments(credentials, request) {
+        // Get Context JWT
+        const contextJwt = await this.getContextJwt(credentials);
+        // Get test case ID from key if we have API connection
+        let testCaseId;
+        if (this.testCaseGroup) {
+            try {
+                const testCase = await this.testCaseGroup.getTestCase({ testCaseKey: request.testCaseKey });
+                if (!testCase) {
+                    throw new NotFoundError(`Test case with key '${request.testCaseKey}' not found.`);
+                }
+                testCaseId = testCase.id;
+            }
+            catch (error) {
+                if (error instanceof NotFoundError) {
+                    throw new NotFoundError(`Test case with key '${request.testCaseKey}' not found.`);
+                }
+                throw new UnexpectedError(`Failed to look up test case ID from key '${request.testCaseKey}'. Ensure Zephyr Connector is configured.`, error);
+            }
+        }
+        else {
+            throw new UnexpectedError('Cannot look up test case ID from key. This method requires Zephyr Connector to be configured. Use createZephyrApi() with an API Connection.');
+        }
+        // Get test case with testScript.steps.attachments fields
+        const fields = 'testScript(id,text,steps(index,reflectRef,description,text,expectedResult,testData,customFieldValues,attachments,id,stepParameters(id,testCaseParameterId,value),testCase(id,key,name,archived,majorVersion,latestVersion,projectKey,parameters(id,name,defaultValue,index))))';
+        const url = `${this.privateApiBaseUrl}/testcase/${request.testCaseKey}?fields=${encodeURIComponent(fields)}`;
+        const headers = {
+            accept: 'application/json',
+            authorization: `JWT ${contextJwt}`,
+            'jira-project-id': String(request.projectId),
+        };
+        try {
+            const response = await fetch(url, {
+                method: 'GET',
+                headers,
+            });
+            if (!response.ok) {
+                if (response.status === 400) {
+                    throw new BadRequestError('Invalid request parameters for getting attachments.');
+                }
+                if (response.status === 401) {
+                    throw new UnauthorizedError('Failed to authenticate. Please check your credentials.');
+                }
+                if (response.status === 403) {
+                    throw new ForbiddenError('Insufficient permissions to get attachments.');
+                }
+                if (response.status === 404) {
+                    throw new NotFoundError(`Test case with key '${request.testCaseKey}' not found.`);
+                }
+                throw new ServerError(`Failed to get test step attachments. Status: ${response.status}`, response.status, response.statusText);
+            }
+            const testCaseData = (await response.json());
+            // Get steps array
+            const steps = testCaseData.testScript?.stepByStepScript?.steps || [];
+            if (request.stepIndex < 0 || request.stepIndex >= steps.length) {
+                throw new NotFoundError(`Test step at index ${request.stepIndex} not found in test case '${request.testCaseKey}'. Test case has ${steps.length} step(s).`);
+            }
+            const step = steps[request.stepIndex];
+            return {
+                attachments: (step.attachments || []).map((att) => ({
+                    id: att.id,
+                    dbAttachmentId: att.dbAttachmentId,
+                    url: att.url,
+                    userKey: att.userKey,
+                    createdOn: att.createdOn,
+                    name: att.name,
+                    mimeType: att.mimeType,
+                    fileSize: att.fileSize,
+                    copyFromStep: att.copyFromStep,
+                    s3Key: att.s3Key,
+                    stepId: att.stepId,
+                })),
+            };
+        }
+        catch (error) {
+            if (error instanceof BadRequestError ||
+                error instanceof UnauthorizedError ||
+                error instanceof ForbiddenError ||
+                error instanceof NotFoundError ||
+                error instanceof ServerError ||
+                error instanceof UnexpectedError) {
+                throw error;
+            }
+            throw new UnexpectedError('Unexpected error while getting test step attachments', error);
+        }
+    }
+    /**
+     * Download an attachment from a test step using private API
+     *
+     * Downloads an attachment file into memory. This method:
+     * 1. Gets fresh attachment details (including a fresh signed S3 URL)
+     * 2. Downloads the file from the signed URL
+     * 3. Returns the file as a Blob
+     *
+     * ⚠️ WARNING: This uses private Zephyr API endpoints that are not officially supported.
+     * The endpoints may change or be removed at any time without notice.
+     *
+     * @param credentials - Private API credentials
+     * @param request - Download attachment request
+     * @param request.testCaseKey - Test case key (e.g., 'PROJ-T1')
+     * @param request.stepIndex - Zero-based index of the test step in the test case
+     * @param request.projectId - Jira project ID (numeric, not the project key)
+     * @param request.attachmentId - Attachment ID (UUID string)
+     * @returns Blob containing the attachment file data
+     * @throws {BadRequestError} If the request is invalid
+     * @throws {UnauthorizedError} If authentication fails
+     * @throws {ForbiddenError} If the user doesn't have permission
+     * @throws {NotFoundError} If the test case, step, or attachment is not found
+     * @throws {ServerError} If the server returns an error
+     * @throws {UnexpectedError} If download fails
+     */
+    async downloadTestStepAttachment(credentials, request) {
+        // Step 1: Get fresh attachment details (including fresh signed URL)
+        const attachmentsResponse = await this.getTestStepAttachments(credentials, {
+            testCaseKey: request.testCaseKey,
+            stepIndex: request.stepIndex,
+            projectId: request.projectId,
+        });
+        // Step 2: Find the requested attachment
+        const attachment = attachmentsResponse.attachments.find((att) => att.id === request.attachmentId);
+        if (!attachment) {
+            throw new NotFoundError(`Attachment with ID '${request.attachmentId}' not found for test step at index ${request.stepIndex} in test case '${request.testCaseKey}'.`);
+        }
+        // Step 3: Download the file from the signed S3 URL
+        try {
+            const downloadResponse = await fetch(attachment.url, {
+                method: 'GET',
+            });
+            if (!downloadResponse.ok) {
+                if (downloadResponse.status === 403) {
+                    throw new ForbiddenError('Failed to download attachment. The signed URL may have expired. Please try again.');
+                }
+                if (downloadResponse.status === 404) {
+                    throw new NotFoundError('Attachment file not found on S3.');
+                }
+                throw new ServerError(`Failed to download attachment. Status: ${downloadResponse.status}`, downloadResponse.status, downloadResponse.statusText);
+            }
+            // Return as Blob
+            return await downloadResponse.blob();
+        }
+        catch (error) {
+            if (error instanceof ForbiddenError || error instanceof NotFoundError || error instanceof ServerError) {
+                throw error;
+            }
+            throw new UnexpectedError('Unexpected error while downloading attachment', error);
+        }
+    }
+    /**
+     * Create an attachment for a test step using private API
+     *
+     * Uploads a file attachment to a test step. This involves:
+     * 1. Getting upload details (S3 credentials)
+     * 2. Uploading the file to S3
+     * 3. Saving attachment metadata
+     *
+     * ⚠️ WARNING: This uses private Zephyr API endpoints that are not officially supported.
+     * The endpoints may change or be removed at any time without notice.
+     *
+     * @param credentials - Private API credentials
+     * @param request - Attachment creation request
+     * @param request.testCaseKey - Test case key (e.g., 'PROJ-T1')
+     * @param request.stepIndex - Zero-based index of the test step in the test case
+     * @param request.projectId - Jira project ID (numeric, not the project key)
+     * @param request.file - File to upload (Blob or ArrayBuffer)
+     * @param request.fileName - Name of the file
+     * @param request.userAccountId - Atlassian account ID (e.g., '5d6fdc98dc6e480dbc021aae')
+     * @returns Attachment metadata response
+     * @throws {BadRequestError} If the request is invalid
+     * @throws {UnauthorizedError} If authentication fails
+     * @throws {ForbiddenError} If the user doesn't have permission
+     * @throws {NotFoundError} If the test case or step is not found
+     * @throws {ServerError} If the server returns an error
+     */
+    async createTestStepAttachment(credentials, request) {
+        // Get Context JWT
+        const contextJwt = await this.getContextJwt(credentials);
+        // Get test case steps to find step ID from index
+        const testCase = await this.testCaseGroup.getTestCase({ testCaseKey: request.testCaseKey });
+        const testSteps = await this.testCaseGroup.getTestCaseTestSteps(request.testCaseKey);
+        if (request.stepIndex < 0 || request.stepIndex >= testSteps.values.length) {
+            throw new NotFoundError(`Test step at index ${request.stepIndex} not found in test case '${request.testCaseKey}'. Test case has ${testSteps.values.length} step(s).`);
+        }
+        // Get the step ID from the private API (we need to fetch the test case with full step details)
+        const fields = 'testScript(id,text,steps(index,reflectRef,description,text,expectedResult,testData,customFieldValues,attachments,id,stepParameters(id,testCaseParameterId,value),testCase(id,key,name,archived,majorVersion,latestVersion,projectKey,parameters(id,name,defaultValue,index))))';
+        const url = `${this.privateApiBaseUrl}/testcase/${request.testCaseKey}?fields=${encodeURIComponent(fields)}`;
+        const headers = {
+            accept: 'application/json',
+            authorization: `JWT ${contextJwt}`,
+            'jira-project-id': String(request.projectId),
+        };
+        const response = await fetch(url, {
+            method: 'GET',
+            headers,
+        });
+        if (!response.ok) {
+            throw new NotFoundError(`Failed to get test case steps for '${request.testCaseKey}'.`);
+        }
+        const testCaseData = (await response.json());
+        const steps = testCaseData.testScript?.stepByStepScript?.steps || [];
+        if (request.stepIndex < 0 || request.stepIndex >= steps.length) {
+            throw new NotFoundError(`Test step at index ${request.stepIndex} not found in test case '${request.testCaseKey}'. Test case has ${steps.length} step(s).`);
+        }
+        const stepId = steps[request.stepIndex].id;
+        // Step 1: Get upload details
+        const uploadDetails = await this.getUploadDetails(contextJwt);
+        // Step 2: Upload to S3
+        const s3Info = await this.uploadToS3ForTestStep(uploadDetails, request.projectId, stepId, request.userAccountId, request.file, request.fileName);
+        // Step 3: Save metadata
+        return await this.saveTestStepAttachmentMetadata(contextJwt, request.projectId, stepId, request.userAccountId, s3Info.s3Key, s3Info.fileName, s3Info.mimeType, s3Info.fileSize);
+    }
+    /**
+     * Get attachments for a test execution using private API
+     *
+     * Retrieves all attachment details for a test execution, including signed S3 URLs
+     * for downloading the attachments.
+     *
+     * ⚠️ WARNING: This uses a private Zephyr API endpoint that is not officially supported.
+     * The endpoint may change or be removed at any time without notice.
+     *
+     * @param credentials - Private API credentials
+     * @param request - Get attachments request
+     * @param request.testExecutionKey - Test execution key (e.g., 'PROJ-E1'). The numeric ID will be looked up automatically if Zephyr Connector is available.
+     * @param request.projectId - Jira project ID (numeric, not the project key)
+     * @returns Test execution attachments response with array of attachment details
+     * @throws {BadRequestError} If the request is invalid
+     * @throws {UnauthorizedError} If authentication fails
+     * @throws {ForbiddenError} If the user doesn't have permission
+     * @throws {NotFoundError} If the test execution is not found
+     * @throws {ServerError} If the server returns an error
+     * @throws {UnexpectedError} If test execution ID cannot be looked up from key and Zephyr Connector is not available
+     */
+    async getTestExecutionAttachments(credentials, request) {
+        // Get test execution ID from key if we have API connection
+        let testExecutionId;
+        if (this.testExecutionGroup) {
+            try {
+                const testExecution = await this.testExecutionGroup.getTestExecution({
+                    testExecutionIdOrKey: request.testExecutionKey,
+                });
+                testExecutionId = testExecution.id;
+            }
+            catch (error) {
+                if (error instanceof NotFoundError) {
+                    throw new NotFoundError(`Test execution with key '${request.testExecutionKey}' not found.`);
+                }
+                throw new UnexpectedError(`Failed to look up test execution ID from key '${request.testExecutionKey}'. Ensure Zephyr Connector is configured.`, error);
+            }
+        }
+        else {
+            throw new UnexpectedError('Cannot look up test execution ID from key. This method requires Zephyr Connector to be configured. Use createZephyrApi() with an API Connection.');
+        }
+        // Get Context JWT
+        const contextJwt = await this.getContextJwt(credentials);
+        const url = `${this.privateApiBaseUrl}/testresult/${request.testExecutionKey}?fields=attachments&itemId=${request.testExecutionKey}`;
+        const headers = {
+            accept: 'application/json',
+            authorization: `JWT ${contextJwt}`,
+            'jira-project-id': String(request.projectId),
+        };
+        try {
+            const response = await fetch(url, {
+                method: 'GET',
+                headers,
+            });
+            if (!response.ok) {
+                if (response.status === 400) {
+                    throw new BadRequestError('Invalid request parameters for getting attachments.');
+                }
+                if (response.status === 401) {
+                    throw new UnauthorizedError('Failed to authenticate. Please check your credentials.');
+                }
+                if (response.status === 403) {
+                    throw new ForbiddenError('Insufficient permissions to get attachments.');
+                }
+                if (response.status === 404) {
+                    throw new NotFoundError(`Test execution with key '${request.testExecutionKey}' not found.`);
+                }
+                throw new ServerError(`Failed to get test execution attachments. Status: ${response.status}`, response.status, response.statusText);
+            }
+            const executionData = (await response.json());
+            return {
+                attachments: (executionData.attachments || []).map((att) => ({
+                    id: att.id,
+                    dbAttachmentId: att.dbAttachmentId,
+                    url: att.url,
+                    userKey: att.userKey,
+                    createdOn: att.createdOn,
+                    name: att.name,
+                    mimeType: att.mimeType,
+                    fileSize: att.fileSize,
+                    copyFromStep: att.copyFromStep,
+                    s3Key: att.s3Key,
+                    testExecutionId: att.testExecutionId,
+                })),
+            };
+        }
+        catch (error) {
+            if (error instanceof BadRequestError ||
+                error instanceof UnauthorizedError ||
+                error instanceof ForbiddenError ||
+                error instanceof NotFoundError ||
+                error instanceof ServerError ||
+                error instanceof UnexpectedError) {
+                throw error;
+            }
+            throw new UnexpectedError('Unexpected error while getting test execution attachments', error);
+        }
+    }
+    /**
+     * Download an attachment from a test execution using private API
+     *
+     * Downloads an attachment file into memory. This method:
+     * 1. Gets fresh attachment details (including a fresh signed S3 URL)
+     * 2. Downloads the file from the signed URL
+     * 3. Returns the file as a Blob
+     *
+     * ⚠️ WARNING: This uses private Zephyr API endpoints that are not officially supported.
+     * The endpoints may change or be removed at any time without notice.
+     *
+     * @param credentials - Private API credentials
+     * @param request - Download attachment request
+     * @param request.testExecutionKey - Test execution key (e.g., 'PROJ-E1'). The numeric ID will be looked up automatically if Zephyr Connector is available.
+     * @param request.projectId - Jira project ID (numeric, not the project key)
+     * @param request.attachmentId - Attachment ID (UUID string)
+     * @returns Blob containing the attachment file data
+     * @throws {BadRequestError} If the request is invalid
+     * @throws {UnauthorizedError} If authentication fails
+     * @throws {ForbiddenError} If the user doesn't have permission
+     * @throws {NotFoundError} If the test execution or attachment is not found
+     * @throws {ServerError} If the server returns an error
+     * @throws {UnexpectedError} If test execution ID cannot be looked up from key and Zephyr Connector is not available, or if download fails
+     */
+    async downloadTestExecutionAttachment(credentials, request) {
+        // Step 1: Get fresh attachment details (including fresh signed URL)
+        const attachmentsResponse = await this.getTestExecutionAttachments(credentials, {
+            testExecutionKey: request.testExecutionKey,
+            projectId: request.projectId,
+        });
+        // Step 2: Find the requested attachment
+        const attachment = attachmentsResponse.attachments.find((att) => att.id === request.attachmentId);
+        if (!attachment) {
+            throw new NotFoundError(`Attachment with ID '${request.attachmentId}' not found for test execution '${request.testExecutionKey}'.`);
+        }
+        // Step 3: Download the file from the signed S3 URL
+        try {
+            const downloadResponse = await fetch(attachment.url, {
+                method: 'GET',
+            });
+            if (!downloadResponse.ok) {
+                if (downloadResponse.status === 403) {
+                    throw new ForbiddenError('Failed to download attachment. The signed URL may have expired. Please try again.');
+                }
+                if (downloadResponse.status === 404) {
+                    throw new NotFoundError('Attachment file not found on S3.');
+                }
+                throw new ServerError(`Failed to download attachment. Status: ${downloadResponse.status}`, downloadResponse.status, downloadResponse.statusText);
+            }
+            // Return as Blob
+            return await downloadResponse.blob();
+        }
+        catch (error) {
+            if (error instanceof ForbiddenError || error instanceof NotFoundError || error instanceof ServerError) {
+                throw error;
+            }
+            throw new UnexpectedError('Unexpected error while downloading attachment', error);
+        }
+    }
+    /**
+     * Create an attachment for a test execution using private API
+     *
+     * Uploads a file attachment to a test execution. This involves:
+     * 1. Getting upload details (S3 credentials)
+     * 2. Uploading the file to S3
+     * 3. Saving attachment metadata
+     *
+     * ⚠️ WARNING: This uses private Zephyr API endpoints that are not officially supported.
+     * The endpoints may change or be removed at any time without notice.
+     *
+     * @param credentials - Private API credentials
+     * @param request - Attachment creation request
+     * @param request.testExecutionKey - Test execution key (e.g., 'PROJ-E1'). The numeric ID will be looked up automatically if Zephyr Connector is available.
+     * @param request.projectId - Jira project ID (numeric, not the project key)
+     * @param request.file - File to upload (Blob or ArrayBuffer)
+     * @param request.fileName - Name of the file
+     * @param request.userAccountId - Atlassian account ID (e.g., '5d6fdc98dc6e480dbc021aae')
+     * @returns Attachment metadata response
+     * @throws {BadRequestError} If the request is invalid
+     * @throws {UnauthorizedError} If authentication fails
+     * @throws {ForbiddenError} If the user doesn't have permission
+     * @throws {NotFoundError} If the test execution is not found
+     * @throws {ServerError} If the server returns an error
+     * @throws {UnexpectedError} If test execution ID cannot be looked up from key and Zephyr Connector is not available
+     */
+    async createTestExecutionAttachment(credentials, request) {
+        // Get test execution ID from key if we have API connection
+        let testExecutionId;
+        if (this.testExecutionGroup) {
+            try {
+                const testExecution = await this.testExecutionGroup.getTestExecution({
+                    testExecutionIdOrKey: request.testExecutionKey,
+                });
+                testExecutionId = testExecution.id;
+            }
+            catch (error) {
+                if (error instanceof NotFoundError) {
+                    throw new NotFoundError(`Test execution with key '${request.testExecutionKey}' not found.`);
+                }
+                throw new UnexpectedError(`Failed to look up test execution ID from key '${request.testExecutionKey}'. Ensure Zephyr Connector is configured.`, error);
+            }
+        }
+        else {
+            throw new UnexpectedError('Cannot look up test execution ID from key. This method requires Zephyr Connector to be configured. Use createZephyrApi() with an API Connection.');
+        }
+        // Get Context JWT
+        const contextJwt = await this.getContextJwt(credentials);
+        // Step 1: Get upload details
+        const uploadDetails = await this.getUploadDetails(contextJwt);
+        // Step 2: Upload to S3
+        const s3Info = await this.uploadToS3ForTestExecution(uploadDetails, request.projectId, testExecutionId, request.userAccountId, request.file, request.fileName);
+        // Step 3: Save metadata
+        return await this.saveTestExecutionAttachmentMetadata(contextJwt, request.projectId, testExecutionId, request.userAccountId, s3Info.s3Key, s3Info.fileName, s3Info.mimeType, s3Info.fileSize);
+    }
+    /**
+     * Get attachments for a test execution step using private API
+     *
+     * Retrieves all attachment details for a specific test execution step (testScriptResult).
+     * Attachments are retrieved by getting the test execution with fields including testScriptResults.attachments.
+     *
+     * ⚠️ WARNING: This uses a private Zephyr API endpoint that is not officially supported.
+     * The endpoint may change or be removed at any time without notice.
+     *
+     * @param credentials - Private API credentials
+     * @param request - Get attachments request
+     * @param request.testExecutionKey - Test execution key (e.g., 'PROJ-E1')
+     * @param request.stepIndex - Zero-based index of the test execution step
+     * @param request.projectId - Jira project ID (numeric, not the project key)
+     * @returns Test execution step attachments response with array of attachment details
+     * @throws {BadRequestError} If the request is invalid
+     * @throws {UnauthorizedError} If authentication fails
+     * @throws {ForbiddenError} If the user doesn't have permission
+     * @throws {NotFoundError} If the test execution or step is not found
+     * @throws {ServerError} If the server returns an error
+     * @throws {UnexpectedError} If the test execution cannot be retrieved
+     */
+    async getTestExecutionStepAttachments(credentials, request) {
+        // Get Context JWT
+        const contextJwt = await this.getContextJwt(credentials);
+        const url = `${this.privateApiBaseUrl}/testresult/${request.testExecutionKey}?fields=testScriptResults(id,testResultStatusId,executionDate,comment,index,description,expectedResult,testData,traceLinks,attachments,sourceScriptType,parameterSetId,customFieldValues,stepAttachmentsMapping,reflectRef),attachments&itemId=${request.testExecutionKey}`;
+        const headers = {
+            accept: 'application/json',
+            authorization: `JWT ${contextJwt}`,
+            'jira-project-id': String(request.projectId),
+        };
+        try {
+            const response = await fetch(url, {
+                method: 'GET',
+                headers,
+            });
+            if (!response.ok) {
+                if (response.status === 400) {
+                    throw new BadRequestError('Invalid request parameters for getting attachments.');
+                }
+                if (response.status === 401) {
+                    throw new UnauthorizedError('Failed to authenticate. Please check your credentials.');
+                }
+                if (response.status === 403) {
+                    throw new ForbiddenError('Insufficient permissions to get attachments.');
+                }
+                if (response.status === 404) {
+                    throw new NotFoundError(`Test execution with key '${request.testExecutionKey}' not found.`);
+                }
+                throw new ServerError(`Failed to get test execution step attachments. Status: ${response.status}`, response.status, response.statusText);
+            }
+            const executionData = (await response.json());
+            // Get testScriptResults array
+            const steps = executionData.testScriptResults || [];
+            if (request.stepIndex < 0 || request.stepIndex >= steps.length) {
+                throw new NotFoundError(`Test execution step at index ${request.stepIndex} not found in test execution '${request.testExecutionKey}'. Test execution has ${steps.length} step(s).`);
+            }
+            const step = steps[request.stepIndex];
+            return {
+                attachments: (step.attachments || []).map((att) => ({
+                    id: att.id,
+                    dbAttachmentId: att.dbAttachmentId,
+                    url: att.url,
+                    userKey: att.userKey,
+                    createdOn: att.createdOn,
+                    name: att.name,
+                    mimeType: att.mimeType,
+                    fileSize: att.fileSize,
+                    copyFromStep: att.copyFromStep,
+                    s3Key: att.s3Key,
+                    testScriptResultId: att.testScriptResultId,
+                })),
+            };
+        }
+        catch (error) {
+            if (error instanceof BadRequestError ||
+                error instanceof UnauthorizedError ||
+                error instanceof ForbiddenError ||
+                error instanceof NotFoundError ||
+                error instanceof ServerError ||
+                error instanceof UnexpectedError) {
+                throw error;
+            }
+            throw new UnexpectedError('Unexpected error while getting test execution step attachments', error);
+        }
+    }
+    /**
+     * Download an attachment from a test execution step using private API
+     *
+     * Downloads an attachment file into memory. This method:
+     * 1. Gets fresh attachment details (including a fresh signed S3 URL)
+     * 2. Downloads the file from the signed URL
+     * 3. Returns the file as a Blob
+     *
+     * ⚠️ WARNING: This uses private Zephyr API endpoints that are not officially supported.
+     * The endpoints may change or be removed at any time without notice.
+     *
+     * @param credentials - Private API credentials
+     * @param request - Download attachment request
+     * @param request.testExecutionKey - Test execution key (e.g., 'PROJ-E1')
+     * @param request.stepIndex - Zero-based index of the test execution step
+     * @param request.projectId - Jira project ID (numeric, not the project key)
+     * @param request.attachmentId - Attachment ID (UUID string)
+     * @returns Blob containing the attachment file data
+     * @throws {BadRequestError} If the request is invalid
+     * @throws {UnauthorizedError} If authentication fails
+     * @throws {ForbiddenError} If the user doesn't have permission
+     * @throws {NotFoundError} If the test execution, step, or attachment is not found
+     * @throws {ServerError} If the server returns an error
+     * @throws {UnexpectedError} If download fails
+     */
+    async downloadTestExecutionStepAttachment(credentials, request) {
+        // Step 1: Get fresh attachment details (including fresh signed URL)
+        const attachmentsResponse = await this.getTestExecutionStepAttachments(credentials, {
+            testExecutionKey: request.testExecutionKey,
+            stepIndex: request.stepIndex,
+            projectId: request.projectId,
+        });
+        // Step 2: Find the requested attachment
+        const attachment = attachmentsResponse.attachments.find((att) => att.id === request.attachmentId);
+        if (!attachment) {
+            throw new NotFoundError(`Attachment with ID '${request.attachmentId}' not found for test execution step at index ${request.stepIndex} in test execution '${request.testExecutionKey}'.`);
+        }
+        // Step 3: Download the file from the signed S3 URL
+        try {
+            const downloadResponse = await fetch(attachment.url, {
+                method: 'GET',
+            });
+            if (!downloadResponse.ok) {
+                if (downloadResponse.status === 403) {
+                    throw new ForbiddenError('Failed to download attachment. The signed URL may have expired. Please try again.');
+                }
+                if (downloadResponse.status === 404) {
+                    throw new NotFoundError('Attachment file not found on S3.');
+                }
+                throw new ServerError(`Failed to download attachment. Status: ${downloadResponse.status}`, downloadResponse.status, downloadResponse.statusText);
+            }
+            // Return as Blob
+            return await downloadResponse.blob();
+        }
+        catch (error) {
+            if (error instanceof ForbiddenError || error instanceof NotFoundError || error instanceof ServerError) {
+                throw error;
+            }
+            throw new UnexpectedError('Unexpected error while downloading attachment', error);
+        }
+    }
+    /**
+     * Create an attachment for a test execution step using private API
+     *
+     * Uploads a file attachment to a test execution step. This involves:
+     * 1. Getting upload details (S3 credentials)
+     * 2. Uploading the file to S3
+     * 3. Saving attachment metadata
+     *
+     * ⚠️ WARNING: This uses private Zephyr API endpoints that are not officially supported.
+     * The endpoints may change or be removed at any time without notice.
+     *
+     * @param credentials - Private API credentials
+     * @param request - Attachment creation request
+     * @param request.testExecutionKey - Test execution key (e.g., 'PROJ-E1')
+     * @param request.stepIndex - Zero-based index of the test execution step
+     * @param request.projectId - Jira project ID (numeric, not the project key)
+     * @param request.file - File to upload (Blob or ArrayBuffer)
+     * @param request.fileName - Name of the file
+     * @param request.userAccountId - Atlassian account ID (e.g., '5d6fdc98dc6e480dbc021aae')
+     * @returns Attachment metadata response
+     * @throws {BadRequestError} If the request is invalid
+     * @throws {UnauthorizedError} If authentication fails
+     * @throws {ForbiddenError} If the user doesn't have permission
+     * @throws {NotFoundError} If the test execution or step is not found
+     * @throws {ServerError} If the server returns an error
+     */
+    async createTestExecutionStepAttachment(credentials, request) {
+        // Get Context JWT
+        const contextJwt = await this.getContextJwt(credentials);
+        // Get test execution steps to find testScriptResultId from index
+        const url = `${this.privateApiBaseUrl}/testresult/${request.testExecutionKey}?fields=testScriptResults(id,testResultStatusId,executionDate,comment,index,description,expectedResult,testData,traceLinks,attachments,sourceScriptType,parameterSetId,customFieldValues,stepAttachmentsMapping,reflectRef),attachments&itemId=${request.testExecutionKey}`;
+        const headers = {
+            accept: 'application/json',
+            authorization: `JWT ${contextJwt}`,
+            'jira-project-id': String(request.projectId),
+        };
+        const response = await fetch(url, {
+            method: 'GET',
+            headers,
+        });
+        if (!response.ok) {
+            throw new NotFoundError(`Failed to get test execution steps for '${request.testExecutionKey}'.`);
+        }
+        const executionData = (await response.json());
+        const steps = executionData.testScriptResults || [];
+        if (request.stepIndex < 0 || request.stepIndex >= steps.length) {
+            throw new NotFoundError(`Test execution step at index ${request.stepIndex} not found in test execution '${request.testExecutionKey}'. Test execution has ${steps.length} step(s).`);
+        }
+        const testScriptResultId = steps[request.stepIndex].id;
+        // Step 1: Get upload details
+        const uploadDetails = await this.getUploadDetails(contextJwt);
+        // Step 2: Upload to S3
+        const s3Info = await this.uploadToS3ForTestExecutionStep(uploadDetails, request.projectId, testScriptResultId, request.userAccountId, request.file, request.fileName);
+        // Step 3: Save metadata
+        return await this.saveTestExecutionStepAttachmentMetadata(contextJwt, request.projectId, testScriptResultId, request.userAccountId, s3Info.s3Key, s3Info.fileName, s3Info.mimeType, s3Info.fileSize);
+    }
+    /**
+     * Upload file to S3 for test step
+     *
+     * Uploads a file to S3 using the credentials from upload details.
+     * Uses "step" in the S3 key path.
+     *
+     * @param upload - Upload details from getUploadDetails
+     * @param projectId - Jira project ID
+     * @param stepId - Numeric test step ID
+     * @param userAccountId - Atlassian account ID
+     * @param file - File to upload (Blob or ArrayBuffer)
+     * @param fileName - Name of the file
+     * @returns S3 upload information
+     * @throws {UnexpectedError} If upload fails
+     */
+    async uploadToS3ForTestStep(upload, projectId, stepId, userAccountId, file, fileName) {
+        const bucketUrl = upload.bucketUrl;
+        const keyPrefix = upload.keyPrefix;
+        const credential = upload.credential;
+        const date = upload.date;
+        const policy = upload.policy;
+        const signature = upload.signature;
+        // Generate UUID for file
+        const fileUuid = this.generateUUID();
+        // Note: Test steps use "step" in the S3 key path, and the keyPrefix includes "write/"
+        const s3Key = `${keyPrefix}/project/${projectId}/step/${stepId}/${fileUuid}`;
+        // Determine MIME type
+        const mimeType = this.getMimeType(fileName);
+        // Get file size
+        const fileSize = file instanceof Blob ? file.size : file.byteLength;
+        // Create form data
+        const formData = new FormData();
+        formData.append('key', s3Key);
+        formData.append('acl', 'private');
+        formData.append('Policy', policy);
+        formData.append('X-Amz-Credential', credential);
+        formData.append('X-Amz-Algorithm', 'AWS4-HMAC-SHA256');
+        formData.append('X-Amz-Date', date);
+        formData.append('X-Amz-Signature', signature);
+        formData.append('X-Amz-Meta-user-account-id', userAccountId);
+        formData.append('X-Amz-Meta-name', fileName);
+        formData.append('Content-Type', mimeType);
+        // Add file
+        if (file instanceof Blob) {
+            formData.append('file', file, fileName);
+        }
+        else {
+            formData.append('file', new Blob([file], { type: mimeType }), fileName);
+        }
+        try {
+            const response = await fetch(bucketUrl, {
+                method: 'POST',
+                body: formData,
+            });
+            if (!response.ok && response.status !== 200 && response.status !== 201 && response.status !== 204) {
+                const errorText = await response.text().catch(() => 'Upload failed');
+                throw new UnexpectedError(`Failed to upload file to S3: ${errorText}`);
+            }
+            return {
+                s3Key,
+                fileName,
+                mimeType,
+                fileSize,
+            };
+        }
+        catch (error) {
+            if (error instanceof UnexpectedError) {
+                throw error;
+            }
+            throw new UnexpectedError('Unexpected error while uploading file to S3', error);
+        }
+    }
+    /**
+     * Save test step attachment metadata
+     *
+     * Saves metadata for an uploaded test step attachment.
+     *
+     * @param contextJwt - Jira Context JWT token
+     * @param projectId - Jira project ID
+     * @param stepId - Numeric test step ID
+     * @param userAccountId - Atlassian account ID
+     * @param s3Key - S3 key from upload
+     * @param fileName - File name
+     * @param mimeType - MIME type
+     * @param fileSize - File size in bytes
+     * @returns Attachment metadata response
+     * @throws {BadRequestError} If the request is invalid
+     * @throws {UnauthorizedError} If authentication fails
+     * @throws {ServerError} If the server returns an error
+     */
+    async saveTestStepAttachmentMetadata(contextJwt, projectId, stepId, userAccountId, s3Key, fileName, mimeType, fileSize) {
+        const url = 'https://app.tm4j.smartbear.com/backend/rest/tests/2.0/attachment/metadata';
+        const headers = {
+            Authorization: `JWT ${contextJwt}`,
+            'jira-project-id': String(projectId),
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+        };
+        const createdOn = new Date().toISOString();
+        const payload = {
+            createdOn,
+            mimeType,
+            name: fileName,
+            s3Key,
+            size: fileSize,
+            stepId,
+            userAccountId,
+        };
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(payload),
+            });
+            if (!response.ok) {
+                if (response.status === 400) {
+                    const errorText = await response.text().catch(() => 'Bad Request');
+                    throw new BadRequestError(`Failed to save attachment metadata: ${errorText}`, response.statusText);
+                }
+                if (response.status === 401) {
+                    throw new UnauthorizedError('Authentication failed. Please check your credentials.');
+                }
+                throw new ServerError(`Failed to save attachment metadata. Status: ${response.status}`, response.status, response.statusText);
+            }
+            return await response.json();
+        }
+        catch (error) {
+            if (error instanceof BadRequestError ||
+                error instanceof UnauthorizedError ||
+                error instanceof ServerError) {
+                throw error;
+            }
+            throw new UnexpectedError('Unexpected error while saving attachment metadata', error);
+        }
+    }
+    /**
+     * Upload file to S3 for test execution
+     *
+     * Uploads a file to S3 using the credentials from upload details.
+     * Uses "testresult" in the S3 key path.
+     *
+     * @param upload - Upload details from getUploadDetails
+     * @param projectId - Jira project ID
+     * @param testExecutionId - Numeric test execution ID
+     * @param userAccountId - Atlassian account ID
+     * @param file - File to upload (Blob or ArrayBuffer)
+     * @param fileName - Name of the file
+     * @returns S3 upload information
+     * @throws {UnexpectedError} If upload fails
+     */
+    async uploadToS3ForTestExecution(upload, projectId, testExecutionId, userAccountId, file, fileName) {
+        const bucketUrl = upload.bucketUrl;
+        const keyPrefix = upload.keyPrefix;
+        const credential = upload.credential;
+        const date = upload.date;
+        const policy = upload.policy;
+        const signature = upload.signature;
+        // Generate UUID for file
+        const fileUuid = this.generateUUID();
+        // Note: Test executions use "testresult" in the S3 key path, and the keyPrefix includes "write/"
+        const s3Key = `${keyPrefix}/project/${projectId}/testresult/${testExecutionId}/${fileUuid}`;
+        // Determine MIME type
+        const mimeType = this.getMimeType(fileName);
+        // Get file size
+        const fileSize = file instanceof Blob ? file.size : file.byteLength;
+        // Create form data
+        const formData = new FormData();
+        formData.append('key', s3Key);
+        formData.append('acl', 'private');
+        formData.append('Policy', policy);
+        formData.append('X-Amz-Credential', credential);
+        formData.append('X-Amz-Algorithm', 'AWS4-HMAC-SHA256');
+        formData.append('X-Amz-Date', date);
+        formData.append('X-Amz-Signature', signature);
+        formData.append('X-Amz-Meta-user-account-id', userAccountId);
+        formData.append('X-Amz-Meta-name', fileName);
+        formData.append('Content-Type', mimeType);
+        // Add file
+        if (file instanceof Blob) {
+            formData.append('file', file, fileName);
+        }
+        else {
+            formData.append('file', new Blob([file], { type: mimeType }), fileName);
+        }
+        try {
+            const response = await fetch(bucketUrl, {
+                method: 'POST',
+                body: formData,
+            });
+            if (!response.ok && response.status !== 200 && response.status !== 201 && response.status !== 204) {
+                const errorText = await response.text().catch(() => 'Upload failed');
+                throw new UnexpectedError(`Failed to upload file to S3: ${errorText}`);
+            }
+            return {
+                s3Key,
+                fileName,
+                mimeType,
+                fileSize,
+            };
+        }
+        catch (error) {
+            if (error instanceof UnexpectedError) {
+                throw error;
+            }
+            throw new UnexpectedError('Unexpected error while uploading file to S3', error);
+        }
+    }
+    /**
+     * Save test execution attachment metadata
+     *
+     * Saves metadata for an uploaded test execution attachment.
+     *
+     * @param contextJwt - Jira Context JWT token
+     * @param projectId - Jira project ID
+     * @param testExecutionId - Numeric test execution ID
+     * @param userAccountId - Atlassian account ID
+     * @param s3Key - S3 key from upload
+     * @param fileName - File name
+     * @param mimeType - MIME type
+     * @param fileSize - File size in bytes
+     * @returns Attachment metadata response
+     * @throws {BadRequestError} If the request is invalid
+     * @throws {UnauthorizedError} If authentication fails
+     * @throws {ServerError} If the server returns an error
+     */
+    async saveTestExecutionAttachmentMetadata(contextJwt, projectId, testExecutionId, userAccountId, s3Key, fileName, mimeType, fileSize) {
+        const url = 'https://app.tm4j.smartbear.com/backend/rest/tests/2.0/attachment/metadata';
+        const headers = {
+            Authorization: `JWT ${contextJwt}`,
+            'jira-project-id': String(projectId),
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+        };
+        const createdOn = new Date().toISOString();
+        const payload = {
+            createdOn,
+            mimeType,
+            name: fileName,
+            s3Key,
+            size: fileSize,
+            testExecutionId,
+            userAccountId,
+        };
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(payload),
+            });
+            if (!response.ok) {
+                if (response.status === 400) {
+                    const errorText = await response.text().catch(() => 'Bad Request');
+                    throw new BadRequestError(`Failed to save attachment metadata: ${errorText}`, response.statusText);
+                }
+                if (response.status === 401) {
+                    throw new UnauthorizedError('Authentication failed. Please check your credentials.');
+                }
+                throw new ServerError(`Failed to save attachment metadata. Status: ${response.status}`, response.status, response.statusText);
+            }
+            return await response.json();
+        }
+        catch (error) {
+            if (error instanceof BadRequestError ||
+                error instanceof UnauthorizedError ||
+                error instanceof ServerError) {
+                throw error;
+            }
+            throw new UnexpectedError('Unexpected error while saving attachment metadata', error);
+        }
+    }
+    /**
+     * Upload file to S3 for test execution step
+     *
+     * Uploads a file to S3 using the credentials from upload details.
+     * Uses "testscriptresult" in the S3 key path.
+     *
+     * @param upload - Upload details from getUploadDetails
+     * @param projectId - Jira project ID
+     * @param testScriptResultId - Numeric test script result ID
+     * @param userAccountId - Atlassian account ID
+     * @param file - File to upload (Blob or ArrayBuffer)
+     * @param fileName - Name of the file
+     * @returns S3 upload information
+     * @throws {UnexpectedError} If upload fails
+     */
+    async uploadToS3ForTestExecutionStep(upload, projectId, testScriptResultId, userAccountId, file, fileName) {
+        const bucketUrl = upload.bucketUrl;
+        const keyPrefix = upload.keyPrefix;
+        const credential = upload.credential;
+        const date = upload.date;
+        const policy = upload.policy;
+        const signature = upload.signature;
+        // Generate UUID for file
+        const fileUuid = this.generateUUID();
+        // Note: Test execution steps use "testscriptresult" in the S3 key path, and the keyPrefix includes "write/"
+        const s3Key = `${keyPrefix}/project/${projectId}/testscriptresult/${testScriptResultId}/${fileUuid}`;
+        // Determine MIME type
+        const mimeType = this.getMimeType(fileName);
+        // Get file size
+        const fileSize = file instanceof Blob ? file.size : file.byteLength;
+        // Create form data
+        const formData = new FormData();
+        formData.append('key', s3Key);
+        formData.append('acl', 'private');
+        formData.append('Policy', policy);
+        formData.append('X-Amz-Credential', credential);
+        formData.append('X-Amz-Algorithm', 'AWS4-HMAC-SHA256');
+        formData.append('X-Amz-Date', date);
+        formData.append('X-Amz-Signature', signature);
+        formData.append('X-Amz-Meta-user-account-id', userAccountId);
+        formData.append('X-Amz-Meta-name', fileName);
+        formData.append('Content-Type', mimeType);
+        // Add file
+        if (file instanceof Blob) {
+            formData.append('file', file, fileName);
+        }
+        else {
+            formData.append('file', new Blob([file], { type: mimeType }), fileName);
+        }
+        try {
+            const response = await fetch(bucketUrl, {
+                method: 'POST',
+                body: formData,
+            });
+            if (!response.ok && response.status !== 200 && response.status !== 201 && response.status !== 204) {
+                const errorText = await response.text().catch(() => 'Upload failed');
+                throw new UnexpectedError(`Failed to upload file to S3: ${errorText}`);
+            }
+            return {
+                s3Key,
+                fileName,
+                mimeType,
+                fileSize,
+            };
+        }
+        catch (error) {
+            if (error instanceof UnexpectedError) {
+                throw error;
+            }
+            throw new UnexpectedError('Unexpected error while uploading file to S3', error);
+        }
+    }
+    /**
+     * Save test execution step attachment metadata
+     *
+     * Saves metadata for an uploaded test execution step attachment.
+     *
+     * @param contextJwt - Jira Context JWT token
+     * @param projectId - Jira project ID
+     * @param testScriptResultId - Numeric test script result ID
+     * @param userAccountId - Atlassian account ID
+     * @param s3Key - S3 key from upload
+     * @param fileName - File name
+     * @param mimeType - MIME type
+     * @param fileSize - File size in bytes
+     * @returns Attachment metadata response
+     * @throws {BadRequestError} If the request is invalid
+     * @throws {UnauthorizedError} If authentication fails
+     * @throws {ServerError} If the server returns an error
+     */
+    async saveTestExecutionStepAttachmentMetadata(contextJwt, projectId, testScriptResultId, userAccountId, s3Key, fileName, mimeType, fileSize) {
+        const url = 'https://app.tm4j.smartbear.com/backend/rest/tests/2.0/attachment/metadata';
+        const headers = {
+            Authorization: `JWT ${contextJwt}`,
+            'jira-project-id': String(projectId),
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+        };
+        const createdOn = new Date().toISOString();
+        const payload = {
+            createdOn,
+            mimeType,
+            name: fileName,
+            s3Key,
+            size: fileSize,
+            testScriptResultId,
+            userAccountId,
+        };
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(payload),
+            });
+            if (!response.ok) {
+                if (response.status === 400) {
+                    const errorText = await response.text().catch(() => 'Bad Request');
+                    throw new BadRequestError(`Failed to save attachment metadata: ${errorText}`, response.statusText);
+                }
+                if (response.status === 401) {
+                    throw new UnauthorizedError('Authentication failed. Please check your credentials.');
+                }
+                throw new ServerError(`Failed to save attachment metadata. Status: ${response.status}`, response.status, response.statusText);
+            }
+            return await response.json();
+        }
+        catch (error) {
+            if (error instanceof BadRequestError ||
+                error instanceof UnauthorizedError ||
+                error instanceof ServerError) {
+                throw error;
+            }
+            throw new UnexpectedError('Unexpected error while saving attachment metadata', error);
+        }
+    }
+}