@rbaileysr/zephyr-managed-api 1.2.1 → 1.2.9

package/dist/groups/Private/PrivateComments.js

@@ -0,0 +1,493 @@
+/*!
+ * Copyright Adaptavist 2025 (c) All rights reserved
+ */
+import { PrivateBase } from './PrivateBase';
+import { BadRequestError, UnauthorizedError, ForbiddenError, NotFoundError, ServerError, UnexpectedError, } from '../../utils';
+export class PrivateComments extends PrivateBase {
+    constructor(apiConnection) {
+        super(apiConnection);
+    }
+    /**
+     * Get comments for a test case using private API
+     *
+     * Retrieves all comments associated with a 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 credentials - Private API credentials
+     * @param request - Get comments 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 Array of comments
+     * @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 getTestCaseComments(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}/comments`;
+        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 comments.');
+                }
+                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 comments.');
+                }
+                if (response.status === 404) {
+                    throw new NotFoundError(`Test case with key '${request.testCaseKey}' not found.`);
+                }
+                throw new ServerError(`Failed to get comments. Status: ${response.status}`, response.status, response.statusText);
+            }
+            const comments = (await response.json());
+            return comments;
+        }
+        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 getting comments', error);
+        }
+    }
+    /**
+     * Get comments for a test cycle using private API
+     *
+     * Retrieves all comments associated with a test cycle (test run).
+     *
+     * ⚠️ 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 comments request
+     * @param request.testCycleId - Test cycle ID (numeric)
+     * @param request.projectId - Jira project ID (numeric, not the project key)
+     * @returns Array of comments
+     * @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
+     */
+    async getTestCycleComments(credentials, request) {
+        // Get Context JWT
+        const contextJwt = await this.getContextJwt(credentials);
+        const url = `${this.privateApiBaseUrl}/testrun/${request.testCycleId}/comments`;
+        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 comments.');
+                }
+                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 comments.');
+                }
+                if (response.status === 404) {
+                    throw new NotFoundError(`Test cycle with ID '${request.testCycleId}' not found.`);
+                }
+                throw new ServerError(`Failed to get comments. Status: ${response.status}`, response.status, response.statusText);
+            }
+            const comments = (await response.json());
+            return comments;
+        }
+        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 getting comments', error);
+        }
+    }
+    /**
+     * Get comments for a test plan using private API
+     *
+     * Retrieves all comments associated with a test plan.
+     *
+     * ⚠️ 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 comments request
+     * @param request.testPlanId - Test plan ID (numeric)
+     * @param request.projectId - Jira project ID (numeric, not the project key)
+     * @returns Array of comments
+     * @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
+     */
+    async getTestPlanComments(credentials, request) {
+        // Get Context JWT
+        const contextJwt = await this.getContextJwt(credentials);
+        const url = `${this.privateApiBaseUrl}/testplan/${request.testPlanId}/comments`;
+        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 comments.');
+                }
+                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 comments.');
+                }
+                if (response.status === 404) {
+                    throw new NotFoundError(`Test plan with ID '${request.testPlanId}' not found.`);
+                }
+                throw new ServerError(`Failed to get comments. Status: ${response.status}`, response.status, response.statusText);
+            }
+            const comments = (await response.json());
+            return comments;
+        }
+        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 getting comments', 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 credentials - Private API credentials
+     * @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(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}/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);
+        }
+    }
+    /**
+     * Create a comment on a test cycle using private API
+     *
+     * Adds a comment to an existing test cycle (test run). 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 credentials - Private API credentials
+     * @param request - Comment 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.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 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 createTestCycleComment(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}/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 cycle 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 cycle.');
+                }
+                if (response.status === 404) {
+                    throw new NotFoundError('Test cycle not found.');
+                }
+                throw new ServerError(`Failed to create test cycle 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 cycle comment', error);
+        }
+    }
+    /**
+     * Create a comment on a test plan using private API
+     *
+     * Adds a comment to an existing test plan. 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 credentials - Private API credentials
+     * @param request - Comment 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.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 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 createTestPlanComment(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}/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 plan 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 plan.');
+                }
+                if (response.status === 404) {
+                    throw new NotFoundError('Test plan not found.');
+                }
+                throw new ServerError(`Failed to create test plan 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 plan comment', error);
+        }
+    }
+}

package/dist/groups/Private/PrivateCustomFields.d.ts

@@ -0,0 +1,54 @@
+/*!
+ * Copyright Adaptavist 2025 (c) All rights reserved
+ */
+/**
+ * Private API Custom Fields sub-group
+ * Handles custom field creation and retrieval
+ *
+ * ⚠️ WARNING: These methods use private APIs that are not officially supported.
+ */
+import type { PrivateApiCredentials, PrivateCustomFieldCategory, CreatePrivateCustomFieldRequest, GetCustomFieldsRequest, PrivateCustomField } from '../../types';
+import { PrivateBase } from './PrivateBase';
+import type { ZephyrApiConnection } from '../../index';
+export declare class PrivateCustomFields extends PrivateBase {
+    constructor(apiConnection?: ZephyrApiConnection);
+    /**
+     * Create a custom field using private API
+     *
+     * Creates a custom field for the specified entity type (test case, test plan, test run, test step, or test execution).
+     *
+     * ⚠️ 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 category - Entity type for the custom field (TEST_CASE, TEST_PLAN, TEST_RUN, TEST_STEP, or TEST_EXECUTION)
+     * @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
+     */
+    createCustomField(credentials: PrivateApiCredentials, category: PrivateCustomFieldCategory, request: CreatePrivateCustomFieldRequest): Promise<unknown>;
+    /**
+     * Get custom fields for a specific entity type using private API
+     *
+     * Retrieves all custom fields configured for the specified entity type (test case, test plan, test run, test step, or test execution) in a project.
+     *
+     * ⚠️ 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 category - Entity type for the custom fields (TEST_CASE, TEST_PLAN, TEST_RUN, TEST_STEP, or TEST_EXECUTION)
+     * @param request - Get custom fields request
+     * @param request.projectId - Jira project ID (numeric, not the project key)
+     * @returns Array of custom field definitions
+     * @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 project is not found
+     * @throws {ServerError} If the server returns an error
+     */
+    getCustomFields(credentials: PrivateApiCredentials, category: PrivateCustomFieldCategory, request: GetCustomFieldsRequest): Promise<PrivateCustomField[]>;
+}
+//# sourceMappingURL=PrivateCustomFields.d.ts.map

package/dist/groups/Private/PrivateCustomFields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PrivateCustomFields.d.ts","sourceRoot":"","sources":["../../../groups/Private/PrivateCustomFields.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;GAKG;AAEH,OAAO,KAAK,EACX,qBAAqB,EACrB,0BAA0B,EAC1B,+BAA+B,EAC/B,sBAAsB,EACtB,kBAAkB,EAClB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAS5C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEvD,qBAAa,mBAAoB,SAAQ,WAAW;gBACvC,aAAa,CAAC,EAAE,mBAAmB;IAI/C;;;;;;;;;;;;;;;;OAgBG;IACG,iBAAiB,CACtB,WAAW,EAAE,qBAAqB,EAClC,QAAQ,EAAE,0BAA0B,EACpC,OAAO,EAAE,+BAA+B,GACtC,OAAO,CAAC,OAAO,CAAC;IA+DnB;;;;;;;;;;;;;;;;;;OAkBG;IACG,eAAe,CACpB,WAAW,EAAE,qBAAqB,EAClC,QAAQ,EAAE,0BAA0B,EACpC,OAAO,EAAE,sBAAsB,GAC7B,OAAO,CAAC,kBAAkB,EAAE,CAAC;CA8DhC"}