@rbaileysr/zephyr-managed-api 1.0.2 → 1.2.0

package/dist/groups/Private.js

@@ -0,0 +1,743 @@
+/*!
+ * Copyright Adaptavist 2025 (c) All rights reserved
+ */
+import { TestCaseGroup } from './TestCase';
+import { BadRequestError, UnauthorizedError, ForbiddenError, NotFoundError, ServerError, UnexpectedError } from '../utils';
+/**
+ * Private API group for accessing Zephyr's private/unofficial endpoints
+ *
+ * ⚠️ WARNING: These methods use private APIs that are not officially supported.
+ * They may change or break at any time without notice.
+ */
+export class PrivateGroup {
+    constructor(apiConnection) {
+        /**
+         * Base URL for Zephyr private API endpoints
+         */
+        this.privateApiBaseUrl = 'https://app.tm4j.smartbear.com/backend/rest/tests/2.0';
+        this.apiConnection = apiConnection;
+        if (apiConnection) {
+            this.testCaseGroup = new TestCaseGroup(apiConnection);
+        }
+    }
+    /**
+     * Get Jira Context JWT token
+     *
+     * Retrieves a short-lived JWT token (15 minutes) from Jira that is required
+     * for private Zephyr API endpoints. This token may need to be refreshed
+     * during long operations.
+     *
+     * ⚠️ WARNING: This uses a private Jira endpoint and may change without notice.
+     *
+     * @param userEmail - Jira user email address
+     * @param apiToken - Jira API token
+     * @param jiraInstanceUrl - Full Jira instance URL (e.g., 'https://your-instance.atlassian.net')
+     * @returns The Context JWT token string
+     * @throws {UnauthorizedError} If authentication fails
+     * @throws {UnexpectedError} If the JWT cannot be extracted from the response
+     */
+    async getContextJwt(userEmail, apiToken, jiraInstanceUrl) {
+        const url = `${jiraInstanceUrl}/plugins/servlet/ac/com.kanoah.test-manager/main-project-page`;
+        // Create Basic Auth header
+        const credentials = btoa(`${userEmail}:${apiToken}`);
+        const headers = {
+            'Authorization': `Basic ${credentials}`,
+            'Content-Type': 'application/json',
+        };
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers,
+            });
+            if (!response.ok) {
+                if (response.status === 401) {
+                    throw new UnauthorizedError('Failed to authenticate with Jira. Please check your email and API token.');
+                }
+                throw new ServerError(`Failed to retrieve Context JWT. Status: ${response.status}`, response.status, response.statusText);
+            }
+            const responseText = await response.text();
+            // Extract contextJwt using regex (as per documentation)
+            const match = responseText.match(/"contextJwt":"([^"]+)"/);
+            if (!match || !match[1]) {
+                // Retry once if JWT is missing (as per documentation)
+                const retryResponse = await fetch(url, {
+                    method: 'POST',
+                    headers,
+                });
+                if (!retryResponse.ok) {
+                    throw new ServerError(`Failed to retrieve Context JWT on retry. Status: ${retryResponse.status}`, retryResponse.status, retryResponse.statusText);
+                }
+                const retryText = await retryResponse.text();
+                const retryMatch = retryText.match(/"contextJwt":"([^"]+)"/);
+                if (!retryMatch || !retryMatch[1]) {
+                    throw new UnexpectedError('Context JWT not found in response after retry. This may be a Jira bug or API change.', { responseText: retryText });
+                }
+                return retryMatch[1];
+            }
+            return match[1];
+        }
+        catch (error) {
+            if (error instanceof UnauthorizedError ||
+                error instanceof ServerError ||
+                error instanceof UnexpectedError) {
+                throw error;
+            }
+            throw new UnexpectedError('Unexpected error while retrieving Context JWT', error);
+        }
+    }
+    /**
+     * Create a custom field using private API
+     *
+     * Creates a custom field for the specified entity type (test case, test plan, test run, or test step).
+     *
+     * ⚠️ 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 userEmail - Jira user email address
+     * @param apiToken - Jira API token
+     * @param jiraInstanceUrl - Full Jira instance URL (e.g., 'https://your-instance.atlassian.net')
+     * @param category - Entity type for the custom field (TEST_CASE, TEST_PLAN, TEST_RUN, or TEST_STEP)
+     * @param request - Custom field creation request
+     * @returns The created custom field response
+     * @throws {BadRequestError} If the request is invalid
+     * @throws {UnauthorizedError} If authentication fails
+     * @throws {ForbiddenError} If the user doesn't have permission
+     * @throws {ServerError} If the server returns an error
+     */
+    async createCustomField(userEmail, apiToken, jiraInstanceUrl, category, request) {
+        // Get Context JWT
+        const contextJwt = await this.getContextJwt(userEmail, apiToken, jiraInstanceUrl);
+        // Determine endpoint based on category
+        const endpointMap = {
+            TEST_CASE: 'customfield/testcase',
+            TEST_PLAN: 'customfield/testplan',
+            TEST_RUN: 'customfield/testrun',
+            TEST_STEP: 'customfield/teststep',
+        };
+        const url = `${this.privateApiBaseUrl}/${endpointMap[category]}`;
+        const headers = {
+            'Content-Type': 'application/json',
+            'authorization': `JWT ${contextJwt}`,
+            'jira-project-id': String(request.projectId),
+        };
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(request),
+            });
+            if (!response.ok) {
+                if (response.status === 400) {
+                    const errorText = await response.text().catch(() => 'Bad Request');
+                    throw new BadRequestError(`Failed to create custom field: ${errorText}`, response.statusText);
+                }
+                if (response.status === 401) {
+                    throw new UnauthorizedError('Authentication failed. Please check your credentials.');
+                }
+                if (response.status === 403) {
+                    throw new ForbiddenError('You do not have permission to create custom fields in this project.');
+                }
+                if (response.status === 404) {
+                    throw new NotFoundError('Project or resource not found.');
+                }
+                throw new ServerError(`Failed to create custom field. 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) {
+                throw error;
+            }
+            throw new UnexpectedError('Unexpected error while creating custom field', error);
+        }
+    }
+    /**
+     * Create a new test case version using private API
+     *
+     * Creates a new version of an existing test case. Note that when a new version
+     * is created, the testCaseId changes for that test case.
+     *
+     * ⚠️ 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 userEmail - Jira user email address
+     * @param apiToken - Jira API token
+     * @param jiraInstanceUrl - Full Jira instance URL (e.g., 'https://your-instance.atlassian.net')
+     * @param request - Test case version 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)
+     * @returns The created version response with id and key
+     * @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 (including 409 Conflict if version already exists)
+     * @throws {UnexpectedError} If test case ID cannot be looked up from key and Zephyr Connector is not available
+     */
+    async createTestCaseVersion(userEmail, apiToken, jiraInstanceUrl, 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(userEmail, apiToken, jiraInstanceUrl);
+        const url = `${this.privateApiBaseUrl}/testcase/${testCaseId}/newversion`;
+        const headers = {
+            'Content-Type': 'application/json',
+            'authorization': `JWT ${contextJwt}`,
+            'jira-project-id': String(request.projectId),
+        };
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify({}), // Empty body as per documentation
+            });
+            if (!response.ok) {
+                if (response.status === 400) {
+                    const errorText = await response.text().catch(() => 'Bad Request');
+                    throw new BadRequestError(`Failed to create test case version: ${errorText}`, response.statusText);
+                }
+                if (response.status === 401) {
+                    throw new UnauthorizedError('Authentication failed. Please check your credentials.');
+                }
+                if (response.status === 403) {
+                    throw new ForbiddenError('You do not have permission to create test case versions in this project.');
+                }
+                if (response.status === 404) {
+                    throw new NotFoundError('Test case not found.');
+                }
+                if (response.status === 409) {
+                    throw new ServerError('Conflict: A new version already exists for this test case.', response.status, response.statusText);
+                }
+                throw new ServerError(`Failed to create test case version. 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 creating test case version', error);
+        }
+    }
+    /**
+     * 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 = crypto.randomUUID();
+        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);
+        }
+    }
+    /**
+     * Create a comment on a test case using private API
+     *
+     * Adds a comment to an existing test case. The comment will be associated with
+     * the specified user account ID.
+     *
+     * ⚠️ 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 userEmail - Jira user email address
+     * @param apiToken - Jira API token
+     * @param jiraInstanceUrl - Full Jira instance URL (e.g., 'https://your-instance.atlassian.net')
+     * @param request - Comment 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.body - Comment text/body
+     * @param request.createdBy - Atlassian account ID of the user creating the comment (e.g., '5d6fdc98dc6e480dbc021aae')
+     * @returns Comment creation 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 createTestCaseComment(userEmail, apiToken, jiraInstanceUrl, 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(userEmail, apiToken, jiraInstanceUrl);
+        const url = `${this.privateApiBaseUrl}/testcase/${testCaseId}/comments`;
+        const headers = {
+            'Content-Type': 'application/json',
+            'authorization': `JWT ${contextJwt}`,
+            'jira-project-id': String(request.projectId),
+        };
+        const payload = {
+            body: request.body,
+            createdBy: request.createdBy,
+        };
+        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 create test case comment: ${errorText}`, response.statusText);
+                }
+                if (response.status === 401) {
+                    throw new UnauthorizedError('Authentication failed. Please check your credentials.');
+                }
+                if (response.status === 403) {
+                    throw new ForbiddenError('You do not have permission to create comments on this test case.');
+                }
+                if (response.status === 404) {
+                    throw new NotFoundError('Test case not found.');
+                }
+                throw new ServerError(`Failed to create test case comment. 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 creating test case comment', error);
+        }
+    }
+    /**
+     * 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 userEmail - Jira user email address
+     * @param apiToken - Jira API token
+     * @param jiraInstanceUrl - Full Jira instance URL (e.g., 'https://your-instance.atlassian.net')
+     * @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(userEmail, apiToken, jiraInstanceUrl, 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(userEmail, apiToken, jiraInstanceUrl);
+        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) {
+                    const errorText = await response.text().catch(() => 'Bad Request');
+                    throw new BadRequestError(`Failed to get test case attachments: ${errorText}`, response.statusText);
+                }
+                if (response.status === 401) {
+                    throw new UnauthorizedError('Authentication failed. Please check your credentials.');
+                }
+                if (response.status === 403) {
+                    throw new ForbiddenError('You do not have permission to view attachments for this test case.');
+                }
+                if (response.status === 404) {
+                    throw new NotFoundError('Test case 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 userEmail - Jira user email address
+     * @param apiToken - Jira API token
+     * @param jiraInstanceUrl - Full Jira instance URL (e.g., 'https://your-instance.atlassian.net')
+     * @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(userEmail, apiToken, jiraInstanceUrl, request) {
+        // Step 1: Get fresh attachment details (including fresh signed URL)
+        const attachmentsResponse = await this.getTestCaseAttachments(userEmail, apiToken, jiraInstanceUrl, {
+            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);
+        }
+    }
+    /**
+     * 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';
+    }
+    /**
+     * 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 userEmail - Jira user email address
+     * @param apiToken - Jira API token
+     * @param jiraInstanceUrl - Full Jira instance URL (e.g., 'https://your-instance.atlassian.net')
+     * @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 createAttachment(userEmail, apiToken, jiraInstanceUrl, 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(userEmail, apiToken, jiraInstanceUrl);
+        // 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);
+    }
+}