@rbaileysr/zephyr-managed-api 1.3.2 → 1.3.4

package/dist/groups/Private/PrivateVersionControl.js

@@ -0,0 +1,709 @@
+/*!
+ * Copyright Adaptavist 2025 (c) All rights reserved
+ */
+import { PrivateBase } from './PrivateBase';
+import { BadRequestError, UnauthorizedError, ForbiddenError, NotFoundError, ServerError, UnexpectedError, } from '../../utils';
+export class PrivateVersionControl extends PrivateBase {
+    constructor(apiConnection) {
+        super(apiConnection);
+    }
+    /**
+     * Get issue links for a test case using private API (with version support)
+     *
+     * Retrieves all issue links associated with a test case, optionally for a specific version.
+     * The response format matches the public API `getTestCaseLinks().issues` format.
+     *
+     * ⚠️ 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 issue links 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.version - Optional version number (absolute, 1-based: 1 = first version ever created, 2 = second version, etc. The highest number is the current/latest version). If not provided, uses the latest version.
+     * @returns Array of issue links matching the public API format
+     * @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 getTestCaseIssueLinks(credentials, request) {
+        // Get test case ID from key if we have API connection
+        let testCaseId;
+        if (this.testCaseGroup) {
+            try {
+                // If version is specified, get the versioned test case; otherwise get the current version
+                const testCase = request.version !== undefined && request.version > 0
+                    ? await this.testCaseGroup.getTestCaseVersion({
+                        testCaseKey: request.testCaseKey,
+                        version: request.version,
+                    })
+                    : await this.testCaseGroup.getTestCase({ testCaseKey: request.testCaseKey });
+                if (!testCase) {
+                    throw new NotFoundError(`Test case with key '${request.testCaseKey}'${request.version !== undefined && request.version > 0 ? ` version ${request.version}` : ''} not found.`);
+                }
+                testCaseId = testCase.id;
+            }
+            catch (error) {
+                if (error instanceof NotFoundError) {
+                    throw new NotFoundError(`Test case with key '${request.testCaseKey}'${request.version !== undefined && request.version > 0 ? ` version ${request.version}` : ''} 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 fields = 'id,issueId,url,urlDescription,type(id,index,name,i18nKey,systemKey),testCaseId,testRunId,testPlanId';
+        const url = `${this.privateApiBaseUrl}/testcase/${testCaseId}/tracelinks/issue?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 issue links.');
+                }
+                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 issue links.');
+                }
+                if (response.status === 404) {
+                    throw new NotFoundError(`Test case with key '${request.testCaseKey}'${request.version !== undefined && request.version > 0 ? ` version ${request.version}` : ''} not found.`);
+                }
+                throw new ServerError(`Failed to get test case issue links. Status: ${response.status}`, response.status, response.statusText);
+            }
+            const privateLinks = (await response.json());
+            // Transform to public API format
+            const issueLinks = privateLinks.map((link) => {
+                // Build self URL (approximate format based on public API pattern)
+                const self = `/testcases/${request.testCaseKey}/links/issues/${link.id}`;
+                return {
+                    id: link.id,
+                    self,
+                    issueId: Number(link.issueId),
+                    target: `/issues/${link.issueId}`,
+                    type: link.type.systemKey,
+                };
+            });
+            return issueLinks;
+        }
+        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 issue links', error);
+        }
+    }
+    /**
+     * Get web links for a test case using private API (with version support)
+     *
+     * Retrieves all web links associated with a test case, optionally for a specific version.
+     * The response format matches the public API `getTestCaseLinks().webLinks` format.
+     *
+     * ⚠️ 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 web links 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.version - Optional version number (absolute, 1-based: 1 = first version ever created, 2 = second version, etc. The highest number is the current/latest version). If not provided, uses the latest version.
+     * @returns Array of web links matching the public API format
+     * @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 getTestCaseWebLinks(credentials, request) {
+        // Get test case ID from key if we have API connection
+        let testCaseId;
+        if (this.testCaseGroup) {
+            try {
+                // If version is specified, get the versioned test case; otherwise get the current version
+                const testCase = request.version !== undefined && request.version > 0
+                    ? await this.testCaseGroup.getTestCaseVersion({
+                        testCaseKey: request.testCaseKey,
+                        version: request.version,
+                    })
+                    : await this.testCaseGroup.getTestCase({ testCaseKey: request.testCaseKey });
+                if (!testCase) {
+                    throw new NotFoundError(`Test case with key '${request.testCaseKey}'${request.version !== undefined && request.version > 0 ? ` version ${request.version}` : ''} not found.`);
+                }
+                testCaseId = testCase.id;
+            }
+            catch (error) {
+                if (error instanceof NotFoundError) {
+                    throw new NotFoundError(`Test case with key '${request.testCaseKey}'${request.version !== undefined && request.version > 0 ? ` version ${request.version}` : ''} 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 fields = 'id,url,urlDescription,type(id,index,name,i18nKey,systemKey),testCaseId,testRunId,testPlanId';
+        const url = `${this.privateApiBaseUrl}/testcase/${testCaseId}/tracelinks/weblink?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 web links.');
+                }
+                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 web links.');
+                }
+                if (response.status === 404) {
+                    throw new NotFoundError(`Test case with key '${request.testCaseKey}'${request.version !== undefined && request.version > 0 ? ` version ${request.version}` : ''} not found.`);
+                }
+                throw new ServerError(`Failed to get test case web links. Status: ${response.status}`, response.status, response.statusText);
+            }
+            const privateLinks = (await response.json());
+            // Transform to public API format
+            const webLinks = privateLinks.map((link) => {
+                // Build self URL (approximate format based on public API pattern)
+                const self = `/testcases/${request.testCaseKey}/links/weblinks/${link.id}`;
+                return {
+                    id: link.id,
+                    self,
+                    url: link.url,
+                    description: link.urlDescription || undefined,
+                    type: link.type.systemKey,
+                };
+            });
+            return webLinks;
+        }
+        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 web links', error);
+        }
+    }
+    /**
+     * Get test script for a test case using private API (with version support)
+     *
+     * Retrieves the test script associated with a test case, optionally for a specific version.
+     * The response format matches the public API `getTestCaseTestScript()` format.
+     *
+     * ⚠️ 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 test script request
+     * @param request.testCaseKey - Test case key (e.g., 'PROJ-T1')
+     * @param request.projectId - Jira project ID (numeric, not the project key)
+     * @param request.version - Optional version number (absolute, 1-based: 1 = first version ever created, 2 = second version, etc. The highest number is the current/latest version). If not provided, uses the latest version.
+     * @returns Test script matching the public API format, or null if no test script exists
+     * @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 cannot be retrieved
+     */
+    async getTestCaseTestScript(credentials, request) {
+        // Get test case ID from key if we have API connection (for version support)
+        let testCaseId = request.testCaseKey;
+        if (this.testCaseGroup) {
+            try {
+                // If version is specified, get the versioned test case; otherwise get the current version
+                const testCase = request.version !== undefined && request.version > 0
+                    ? await this.testCaseGroup.getTestCaseVersion({
+                        testCaseKey: request.testCaseKey,
+                        version: request.version,
+                    })
+                    : await this.testCaseGroup.getTestCase({ testCaseKey: request.testCaseKey });
+                if (!testCase) {
+                    throw new NotFoundError(`Test case with key '${request.testCaseKey}'${request.version !== undefined && request.version > 0 ? ` version ${request.version}` : ''} not found.`);
+                }
+                // Use the ID for the private API call (works with both key and ID)
+                testCaseId = testCase.id;
+            }
+            catch (error) {
+                if (error instanceof NotFoundError) {
+                    throw new NotFoundError(`Test case with key '${request.testCaseKey}'${request.version !== undefined && request.version > 0 ? ` version ${request.version}` : ''} not found.`);
+                }
+                throw new UnexpectedError(`Failed to look up test case ID from key '${request.testCaseKey}'. Ensure Zephyr Connector is configured.`, error);
+            }
+        }
+        // Get Context JWT
+        const contextJwt = await this.getContextJwt(credentials);
+        // Build fields query to get test script
+        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/${testCaseId}?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 test script.');
+                }
+                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 test script.');
+                }
+                if (response.status === 404) {
+                    throw new NotFoundError(`Test case with key '${request.testCaseKey}'${request.version !== undefined && request.version > 0 ? ` version ${request.version}` : ''} not found.`);
+                }
+                throw new ServerError(`Failed to get test case test script. Status: ${response.status}`, response.status, response.statusText);
+            }
+            const testCase = (await response.json());
+            // If no test script exists, return null
+            if (!testCase.testScript) {
+                return null;
+            }
+            // If it's a step-by-step script (has steps), it's not a plain/BDD script, return null
+            if (testCase.testScript.stepByStepScript) {
+                return null;
+            }
+            // If it has text, it's a plain text script
+            if (testCase.testScript.text) {
+                return {
+                    id: testCase.testScript.id,
+                    type: 'plain',
+                    text: testCase.testScript.text,
+                };
+            }
+            // No script found
+            return null;
+        }
+        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 test script', error);
+        }
+    }
+    /**
+     * Get test steps for a test case using private API (with version support)
+     *
+     * Retrieves the test steps associated with a test case, optionally for a specific version.
+     * The response format matches the public API `getTestCaseTestSteps()` format.
+     *
+     * ⚠️ 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 test steps request
+     * @param request.testCaseKey - Test case key (e.g., 'PROJ-T1')
+     * @param request.projectId - Jira project ID (numeric, not the project key)
+     * @param request.version - Optional version number (absolute, 1-based: 1 = first version ever created, 2 = second version, etc. The highest number is the current/latest version). If not provided, uses the latest version.
+     * @returns Test steps list matching the public API format
+     * @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 cannot be retrieved
+     */
+    async getTestCaseTestSteps(credentials, request) {
+        // Get test case ID from key if we have API connection (for version support)
+        let testCaseId = request.testCaseKey;
+        if (this.testCaseGroup) {
+            try {
+                // If version is specified, get the versioned test case; otherwise get the current version
+                const testCase = request.version !== undefined && request.version > 0
+                    ? await this.testCaseGroup.getTestCaseVersion({
+                        testCaseKey: request.testCaseKey,
+                        version: request.version,
+                    })
+                    : await this.testCaseGroup.getTestCase({ testCaseKey: request.testCaseKey });
+                if (!testCase) {
+                    throw new NotFoundError(`Test case with key '${request.testCaseKey}'${request.version !== undefined && request.version > 0 ? ` version ${request.version}` : ''} not found.`);
+                }
+                // Use the ID for the private API call (works with both key and ID)
+                testCaseId = testCase.id;
+            }
+            catch (error) {
+                if (error instanceof NotFoundError) {
+                    throw new NotFoundError(`Test case with key '${request.testCaseKey}'${request.version !== undefined && request.version > 0 ? ` version ${request.version}` : ''} not found.`);
+                }
+                throw new UnexpectedError(`Failed to look up test case ID from key '${request.testCaseKey}'. Ensure Zephyr Connector is configured.`, error);
+            }
+        }
+        // Get Context JWT
+        const contextJwt = await this.getContextJwt(credentials);
+        // Build fields query to get test steps
+        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/${testCaseId}?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 test steps.');
+                }
+                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 test steps.');
+                }
+                if (response.status === 404) {
+                    throw new NotFoundError(`Test case with key '${request.testCaseKey}'${request.version !== undefined && request.version > 0 ? ` version ${request.version}` : ''} not found.`);
+                }
+                throw new ServerError(`Failed to get test case test steps. Status: ${response.status}`, response.status, response.statusText);
+            }
+            const testCase = (await response.json());
+            // If no test script or no step-by-step script exists, return empty list
+            if (!testCase.testScript || !testCase.testScript.stepByStepScript || !testCase.testScript.stepByStepScript.steps) {
+                return {
+                    values: [],
+                    total: 0,
+                    maxResults: 0,
+                    startAt: 0,
+                    isLast: true,
+                    next: null,
+                };
+            }
+            const privateSteps = testCase.testScript.stepByStepScript.steps;
+            // Transform to public API format
+            const testSteps = privateSteps.map((step) => {
+                const inline = {
+                    description: step.description || '',
+                    testData: step.testData || undefined,
+                    expectedResult: step.expectedResult || '',
+                    reflectRef: step.reflectRef || undefined,
+                    // Note: customFieldValues transformation would require more complex logic
+                    // For now, we'll skip it as it's not in the public API TestStepInline type
+                };
+                return {
+                    inline,
+                };
+            });
+            return {
+                values: testSteps,
+                total: testSteps.length,
+                maxResults: testSteps.length,
+                startAt: 0,
+                isLast: true,
+                next: null,
+            };
+        }
+        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 test steps', error);
+        }
+    }
+    /**
+     * Map LinkType to numeric typeId for private API
+     */
+    mapLinkTypeToTypeId(type) {
+        switch (type) {
+            case 'COVERAGE':
+                return 1;
+            case 'BLOCKS':
+                return 2;
+            case 'RELATED':
+                return 3;
+            default:
+                return 1; // Default to COVERAGE
+        }
+    }
+    /**
+     * Map numeric typeId to LinkType for private API
+     */
+    mapTypeIdToLinkType(typeId) {
+        switch (typeId) {
+            case 1:
+                return 'COVERAGE';
+            case 2:
+                return 'BLOCKS';
+            case 3:
+                return 'RELATED';
+            default:
+                return 'COVERAGE'; // Default to COVERAGE
+        }
+    }
+    /**
+     * Get issue links for a test execution step using private API
+     *
+     * Retrieves all issue links associated with a specific test execution step. This is useful for
+     * migration scenarios where you need to extract issue links from a source test execution and
+     * recreate them in a target instance.
+     *
+     * ⚠️ 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 issue links 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 List of issue links for the test execution step
+     * @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 an unexpected error occurs
+     */
+    async getTestExecutionStepIssueLinks(credentials, request) {
+        // Get Context JWT
+        const contextJwt = await this.getContextJwt(credentials);
+        // Fetch test execution with traceLinks in testScriptResults
+        const url = `${this.privateApiBaseUrl}/testresult/${request.testExecutionKey}?fields=testScriptResults(id,index,traceLinks(id,type(id,systemKey),issueId)),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 === 404) {
+                    throw new NotFoundError(`Test execution with key '${request.testExecutionKey}' not found.`);
+                }
+                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 test execution step issue links.');
+                }
+                throw new ServerError(`Failed to get test execution step issue links. Status: ${response.status}`, response.status, response.statusText);
+            }
+            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 step = steps[request.stepIndex];
+            const traceLinks = step.traceLinks || [];
+            // Transform private API response to migration-friendly format
+            return traceLinks.map((link) => ({
+                id: link.id,
+                issueId: link.issueId,
+                type: this.mapSystemKeyToLinkType(link.type.systemKey),
+            }));
+        }
+        catch (error) {
+            if (error instanceof NotFoundError ||
+                error instanceof UnauthorizedError ||
+                error instanceof ForbiddenError ||
+                error instanceof ServerError ||
+                error instanceof UnexpectedError) {
+                throw error;
+            }
+            throw new UnexpectedError('Unexpected error while getting test execution step issue links', error);
+        }
+    }
+    /**
+     * Map system key to LinkType
+     */
+    mapSystemKeyToLinkType(systemKey) {
+        switch (systemKey.toUpperCase()) {
+            case 'COVERAGE':
+                return 'COVERAGE';
+            case 'BLOCKS':
+                return 'BLOCKS';
+            case 'RELATED':
+                return 'RELATED';
+            default:
+                return 'COVERAGE'; // Default to COVERAGE
+        }
+    }
+    /**
+     * Create an issue link for a test execution step using private API
+     *
+     * Creates a link between a test execution step and a Jira issue. The link type can be COVERAGE, BLOCKS, or RELATED.
+     * This functionality is not available in the public API.
+     *
+     * ⚠️ 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 - Create issue link request
+     * @param request.testExecutionKey - Test execution key (e.g., 'PROJ-E1')
+     * @param request.stepIndex - Zero-based index of the test execution step
+     * @param request.issueId - Jira issue ID (numeric)
+     * @param request.type - Link type: 'COVERAGE', 'BLOCKS', or 'RELATED' (optional, defaults to 'COVERAGE')
+     * @param request.projectId - Jira project ID (numeric, not the project key)
+     * @returns Created link response with ID
+     * @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 test execution ID cannot be looked up
+     */
+    async createTestExecutionStepIssueLink(credentials, request) {
+        // Get Context JWT
+        const contextJwt = await this.getContextJwt(credentials);
+        // Step 1: Get test execution to find testResultId (numeric ID)
+        let testResultId;
+        if (this.testExecutionGroup) {
+            try {
+                const testExecution = await this.testExecutionGroup.getTestExecution({
+                    testExecutionIdOrKey: request.testExecutionKey,
+                });
+                testResultId = 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.');
+        }
+        // Step 2: Get test execution steps to find testScriptResultId from stepIndex
+        const url = `${this.privateApiBaseUrl}/testresult/${request.testExecutionKey}?fields=testScriptResults(id,index),attachments&itemId=${request.testExecutionKey}`;
+        const headers = {
+            accept: 'application/json',
+            authorization: `JWT ${contextJwt}`,
+            'jira-project-id': String(request.projectId),
+        };
+        let testScriptResultId;
+        try {
+            const response = await fetch(url, {
+                method: 'GET',
+                headers,
+            });
+            if (!response.ok) {
+                if (response.status === 404) {
+                    throw new NotFoundError(`Test execution with key '${request.testExecutionKey}' not found.`);
+                }
+                throw new ServerError(`Failed to get test execution steps. Status: ${response.status}`, response.status, response.statusText);
+            }
+            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).`);
+            }
+            testScriptResultId = steps[request.stepIndex].id;
+        }
+        catch (error) {
+            if (error instanceof NotFoundError ||
+                error instanceof ServerError ||
+                error instanceof UnexpectedError) {
+                throw error;
+            }
+            throw new UnexpectedError('Unexpected error while getting test execution steps', error);
+        }
+        // Step 3: Create the issue link using bulk endpoint
+        const typeId = this.mapLinkTypeToTypeId(request.type);
+        const bulkUrl = `${this.privateApiBaseUrl}/tracelink/testresult/bulk/create`;
+        const bulkHeaders = {
+            'Content-Type': 'application/json',
+            authorization: `JWT ${contextJwt}`,
+            'jira-project-id': String(request.projectId),
+        };
+        const requestBody = [
+            {
+                testResultId,
+                issueId: String(request.issueId),
+                testScriptResultId,
+                typeId,
+            },
+        ];
+        try {
+            const response = await fetch(bulkUrl, {
+                method: 'POST',
+                headers: bulkHeaders,
+                body: JSON.stringify(requestBody),
+            });
+            if (!response.ok) {
+                if (response.status === 400) {
+                    throw new BadRequestError('Invalid request parameters for creating test execution step issue link.');
+                }
+                if (response.status === 401) {
+                    throw new UnauthorizedError('Failed to authenticate. Please check your credentials.');
+                }
+                if (response.status === 403) {
+                    throw new ForbiddenError('Insufficient permissions to create test execution step issue link.');
+                }
+                if (response.status === 404) {
+                    throw new NotFoundError(`Test execution '${request.testExecutionKey}' or step at index ${request.stepIndex} not found.`);
+                }
+                throw new ServerError(`Failed to create test execution step issue link. Status: ${response.status}`, response.status, response.statusText);
+            }
+            const results = (await response.json());
+            if (results.length === 0) {
+                throw new UnexpectedError('No link ID returned from API response.');
+            }
+            return results[0];
+        }
+        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 execution step issue link', error);
+        }
+    }
+}