@rbaileysr/zephyr-managed-api 1.3.10 → 1.4.0

package/README.md

@@ -22,6 +22,9 @@ import { createZephyrApi } from '@rbaileysr/zephyr-managed-api';
 
    // Base URL is configured in the Generic Connector
 const api = createZephyrApi(ZephyrApiConnection);
+
+   // With verbose logging enabled (logs full request/response details on API failures)
+const apiVerbose = createZephyrApi(ZephyrApiConnection, true);
    ```
    
 **Using OAuth Token:**
@@ -34,13 +37,43 @@ const api = createZephyrApi(
   'https://api.zephyrscale.smartbear.com/v2'
 );
 
-// EU region
+// EU region with verbose logging
 const apiEU = createZephyrApi(
   'your-oauth-token',
-  'https://eu.api.zephyrscale.smartbear.com/v2'
+  'https://eu.api.zephyrscale.smartbear.com/v2',
+  true  // Enable verbose logging
 );
 ```
 
+### Verbose Logging
+
+When enabled, verbose logging automatically logs full request and response details whenever an API call fails. This is useful for debugging issues in production environments.
+
+**Features:**
+- Logs full request details (method, path, headers, body)
+- Logs full response details (status, headers, body)
+- Automatically sanitizes sensitive headers (authorization, API keys)
+- Only logs on failures (not on successful requests)
+- Includes descriptive messages about what operation was being attempted
+
+**Example output when an API call fails:**
+```
+[Zephyr API Failure]
+Operation: GET /testcases/PROJ-T1
+Request Details: {
+  method: 'GET',
+  path: '/testcases/PROJ-T1',
+  headers: { 'content-type': 'application/json', authorization: '[REDACTED]' },
+  body: null
+}
+Response Details: {
+  status: 404,
+  statusText: 'Not Found',
+  headers: { 'content-type': 'application/json' },
+  body: { message: 'Test case not found' }
+}
+```
+
 ## Supported API calls
 
 - [fetch](https://docs.adaptavist.com/src/managed-apis/managed-api-abstractions)
@@ -144,7 +177,16 @@ const apiEU = createZephyrApi(
       - **DataSets**: `getDataSets`, `createDataSet`, `updateDataSet`
       - **archiveConfig** - Archive a config item (Environment, Iteration, or Status)
       - **unarchiveConfig** - Unarchive a config item (Environment, Iteration, or Status)
-  - ### Versions
+  - ### TestCase (entity-based group - v1.4.0+)
+      - **Archiving**: `getArchivedTestCases`, `archiveTestCases`, `unarchiveTestCases`
+      - **TestScriptData**: `setTestCaseParamTypeToParameter`, `setTestCaseParameters`, `setTestCaseParamTypeToTestData`, `setTestCaseTestData`, `getTestCaseTestData`, `hasTestCaseTestData`
+      - **Versions**: `createTestCaseVersion`
+  - ### TestCycle (entity-based group - v1.4.0+)
+      - **ExtendedData**: `getTestCycleIteration`, `updateTestCycleIteration`
+  - ### TestExecution (entity-based group - v1.4.0+)
+      - **ExtendedData**: `getTestExecutionIteration`, `updateTestExecutionIteration`, `getTestExecutionVersion`, `updateTestExecutionVersion`
+      - **Methods**: `createTestExecutionWithTestData`, `createTestExecutionWithVersion`, `updateTestExecution`, `getTestExecutionSteps`, `updateTestExecutionStepStatus`, `updateTestExecutionStepComment`, `getTestCycleItems`
+  - ### Versions (deprecated - use `Private.TestCase.Versions` instead)
       - **createTestCaseVersion** - Create a new test case version
   - ### Attachments
       - **Test Case**: `getTestCaseAttachments`, `downloadAttachment`, `createTestCaseAttachment`
@@ -156,15 +198,15 @@ const apiEU = createZephyrApi(
   - ### VersionControl
       - **Test Case (version-specific)**: `getTestCaseIssueLinks`, `getTestCaseWebLinks`, `getTestCaseTestScript`, `getTestCaseTestSteps`
       - **Test Execution Step**: `getTestExecutionStepIssueLinks`, `createTestExecutionStepIssueLink`
-  - ### ExtendedData (supplements public API with extended data: iterations and versions)
+  - ### ExtendedData (deprecated - use `Private.TestCycle.ExtendedData` or `Private.TestExecution.ExtendedData` instead)
       - **Test Cycle**: `getTestCycleIteration`, `updateTestCycleIteration`
       - **Test Execution**: `getTestExecutionIteration`, `updateTestExecutionIteration`, `getTestExecutionVersion`, `updateTestExecutionVersion`
-  - ### TestCaseArchiving (access archived test cases and archiving operations)
+  - ### TestCaseArchiving (deprecated - use `Private.TestCase.Archiving` instead)
       - **Test Case**: `getArchivedTestCases`, `archiveTestCases`, `unarchiveTestCases`
-  - ### TestScriptData (manage test script data: Parameters and Test Data)
+  - ### TestScriptData (deprecated - use `Private.TestCase.TestScriptData` instead)
       - **Test Case**: `setTestCaseParamTypeToParameter`, `setTestCaseParameters`, `setTestCaseParamTypeToTestData`, `setTestCaseTestData`, `getTestCaseTestData`, `hasTestCaseTestData`
-  - ### TestExecutions (create and update test executions for test cases with test data)
-      - **Test Execution**: `createTestExecutionWithTestData`, `updateTestExecution`, `getTestExecutionSteps`, `updateTestExecutionStepStatus`, `updateTestExecutionStepComment`
+  - ### TestExecutions (deprecated - use `Private.TestExecution` instead)
+      - **Test Execution**: `createTestExecutionWithTestData`, `createTestExecutionWithVersion`, `updateTestExecution`, `getTestExecutionSteps`, `updateTestExecutionStepStatus`, `updateTestExecutionStepComment`
       - **Test Cycle**: `getTestCycleItems`
 
 ## Private API Authentication
@@ -272,8 +314,8 @@ await api.Private.Config.unarchiveConfig(credentials, {
 ### Example: Create Test Case Version
 
 ```typescript
-// Create a new version of an existing test case
-const newVersion = await api.Private.Versions.createTestCaseVersion(
+// Create a new version of an existing test case (v1.4.0+)
+const newVersion = await api.Private.TestCase.Versions.createTestCaseVersion(
   credentials,
   {
     testCaseKey: 'PROJ-T1',  // Uses key, looks up ID automatically
@@ -282,6 +324,8 @@ const newVersion = await api.Private.Versions.createTestCaseVersion(
 );
 ```
 
+**Note:** The old path (`Private.Versions.createTestCaseVersion`) still works but is deprecated. Use `Private.TestCase.Versions.createTestCaseVersion` for better organization.
+
 ### Example: Upload Attachment
 
 ```typescript
@@ -334,25 +378,25 @@ await api.Private.VersionControl.createTestExecutionStepIssueLink(credentials, {
 
 ### Example: Extended Data (Supplements Public API)
 
-The public API does not support iterations for Test Cycles/Executions or Jira version IDs for Test Executions. Use `ExtendedData` to supplement public API calls.
+The public API does not support iterations for Test Cycles/Executions or Jira version IDs for Test Executions. Use entity-based groups (v1.4.0+) to supplement public API calls.
 
 ```typescript
-// Test Cycle: Set/get iteration
+// Test Cycle: Set/get iteration (v1.4.0+)
 const testCycle = await api.TestCycle.createTestCycle({
   projectKey: 'M12',
   name: 'Sprint 1 Testing'
 });
-await api.Private.ExtendedData.updateTestCycleIteration(credentials, {
+await api.Private.TestCycle.ExtendedData.updateTestCycleIteration(credentials, {
   testCycleKey: testCycle.key,
   projectId: 10313,
   iterationId: 10952254
 });
-const cycleIteration = await api.Private.ExtendedData.getTestCycleIteration(credentials, {
+const cycleIteration = await api.Private.TestCycle.ExtendedData.getTestCycleIteration(credentials, {
   testCycleKey: 'M12-R1',
   projectId: 10313
 });
 
-// Test Execution: Set/get iteration and version
+// Test Execution: Set/get iteration and version (v1.4.0+)
 await api.TestExecution.createTestExecution({
   projectKey: 'M12',
   testCaseKey: 'M12-T1',
@@ -360,32 +404,34 @@ await api.TestExecution.createTestExecution({
   statusName: 'Pass'
 });
 // Note: createTestExecution returns void - use known key or look up via listTestExecutions()
-await api.Private.ExtendedData.updateTestExecutionIteration(credentials, {
+await api.Private.TestExecution.ExtendedData.updateTestExecutionIteration(credentials, {
   testExecutionKey: 'M12-E1',
   projectId: 10313,
   iterationId: 10952254
 });
-await api.Private.ExtendedData.updateTestExecutionVersion(credentials, {
+await api.Private.TestExecution.ExtendedData.updateTestExecutionVersion(credentials, {
   testExecutionKey: 'M15-E3',
   projectId: 10316,
   jiraVersionId: 10102
 });
 
 // Clear by setting to null
-await api.Private.ExtendedData.updateTestCycleIteration(credentials, {
+await api.Private.TestCycle.ExtendedData.updateTestCycleIteration(credentials, {
   testCycleKey: 'M12-R1',
   projectId: 10313,
   iterationId: null
 });
 ```
 
+**Note:** The old paths (`Private.ExtendedData.*`) still work but are deprecated. Use the new entity-based paths (`Private.TestCycle.ExtendedData.*` and `Private.TestExecution.ExtendedData.*`) for better organization.
+
 ### Example: Test Case Archiving
 
-The public API does not expose the archived flag. Use `TestCaseArchiving` to list, archive, and unarchive test cases.
+The public API does not expose the archived flag. Use `Private.TestCase.Archiving` (v1.4.0+) to list, archive, and unarchive test cases.
 
 ```typescript
 // Get archived test cases (paginated, optional query filter)
-const archived = await api.Private.TestCaseArchiving.getArchivedTestCases(credentials, {
+const archived = await api.Private.TestCase.Archiving.getArchivedTestCases(credentials, {
   projectId: 10316,
   maxResults: 50,
   startAt: 0,
@@ -393,45 +439,47 @@ const archived = await api.Private.TestCaseArchiving.getArchivedTestCases(creden
 });
 
 // Archive test cases (single or multiple)
-await api.Private.TestCaseArchiving.archiveTestCases(credentials, {
+await api.Private.TestCase.Archiving.archiveTestCases(credentials, {
   projectId: 10316,
   testCaseIds: [288004503, 288004504, 288004505]
 });
 
 // Unarchive test cases
-await api.Private.TestCaseArchiving.unarchiveTestCases(credentials, {
+await api.Private.TestCase.Archiving.unarchiveTestCases(credentials, {
   projectId: 10316,
   testCaseIds: [288004503]
 });
 ```
 
+**Note:** The old path (`Private.TestCaseArchiving.*`) still works but is deprecated. Use `Private.TestCase.Archiving.*` for better organization.
+
 ### Test Script Data
 
-The public API does not expose test script data (Parameters and Test Data). Use `TestScriptData` to manage this data.
+The public API does not expose test script data (Parameters and Test Data). Use `Private.TestCase.TestScriptData` (v1.4.0+) to manage this data.
 
 ```typescript
 // Check if test case has test script data
-const hasData = await api.Private.TestScriptData.hasTestCaseTestData(credentials, {
+const hasData = await api.Private.TestCase.TestScriptData.hasTestCaseTestData(credentials, {
   testCaseKey: 'M14-T6',
   projectId: 10315
 });
 // Returns: { hasData: true, type: 'PARAMETER' } or { hasData: false, type: null }
 
 // Get test script data
-const testData = await api.Private.TestScriptData.getTestCaseTestData(credentials, {
+const testData = await api.Private.TestCase.TestScriptData.getTestCaseTestData(credentials, {
   testCaseKey: 'M14-T6',
   projectId: 10315
 });
 // Returns: { paramType: 'PARAMETER' | 'TEST_DATA' | null, parameters: [...], testData: [...] }
 
 // Set test case to use Parameters
-await api.Private.TestScriptData.setTestCaseParamTypeToParameter(credentials, {
+await api.Private.TestCase.TestScriptData.setTestCaseParamTypeToParameter(credentials, {
   testCaseKey: 'M14-T6',
   projectId: 10315
 });
 
 // Set parameters
-await api.Private.TestScriptData.setTestCaseParameters(credentials, {
+await api.Private.TestCase.TestScriptData.setTestCaseParameters(credentials, {
   testCaseKey: 'M14-T6',
   projectId: 10315,
   parameters: [
@@ -441,13 +489,13 @@ await api.Private.TestScriptData.setTestCaseParameters(credentials, {
 });
 
 // Set test case to use Test Data
-await api.Private.TestScriptData.setTestCaseParamTypeToTestData(credentials, {
+await api.Private.TestCase.TestScriptData.setTestCaseParamTypeToTestData(credentials, {
   testCaseKey: 'M14-T6',
   projectId: 10315
 });
 
 // Set test data (simplified array format)
-await api.Private.TestScriptData.setTestCaseTestData(credentials, {
+await api.Private.TestCase.TestScriptData.setTestCaseTestData(credentials, {
   testCaseKey: 'M14-T6',
   projectId: 10315,
   testData: [
@@ -460,9 +508,11 @@ await api.Private.TestScriptData.setTestCaseTestData(credentials, {
 });
 ```
 
+**Note:** The old path (`Private.TestScriptData.*`) still works but is deprecated. Use `Private.TestCase.TestScriptData.*` for better organization.
+
 ### Test Executions with Test Data
 
-The public API does not correctly handle creating test executions for test cases with test data or test cases with "Call to Test" steps that reference test cases with test data. Use `TestExecutions` to create and update these executions.
+The public API does not correctly handle creating test executions for test cases with test data or test cases with "Call to Test" steps that reference test cases with test data. Use `Private.TestExecution` (v1.4.0+) to create and update these executions.
 
 ```typescript
 // Create test execution for test case with test data
@@ -470,7 +520,7 @@ The public API does not correctly handle creating test executions for test cases
 // 1. Creates execution via public API
 // 2. Gets testRunItemId from private API
 // 3. Creates actual execution via private API
-const execution = await api.Private.TestExecutions.createTestExecutionWithTestData(credentials, {
+const execution = await api.Private.TestExecution.createTestExecutionWithTestData(credentials, {
   testCaseKey: 'M14-T6',
   testCycleKey: 'M14-R1',
   assignedTo: '5d259f2e0b81c60c239bed83', // optional
@@ -478,14 +528,35 @@ const execution = await api.Private.TestExecutions.createTestExecutionWithTestDa
 });
 // Returns: { id: 2065132733, key: 'M14-E18' }
 
+// Create test execution for specific test case version (not just latest)
+// Unlike the public API which only creates executions against the latest version,
+// this allows creating executions against any version of a test case
+const executionWithVersion = await api.Private.TestExecution.createTestExecutionWithVersion(credentials, {
+  body: {
+    projectKey: 'M14',
+    testCaseKey: 'M14-T6',
+    testCycleKey: 'M14-R1',
+    statusName: 'Not Executed',
+    version: 2, // Create execution against version 2 of the test case
+    environmentName: 'Production', // optional
+    assignedToId: '5d259f2e0b81c60c239bed83', // optional
+    comment: 'Testing version 2', // optional
+  },
+  projectId: 10315,
+  assignedTo: '5d259f2e0b81c60c239bed83', // optional, can override body.assignedToId
+  iterationId: 10966272, // optional
+  jiraVersionId: 10206 // optional
+});
+// Returns: { id: 2068847141, key: 'M2-E13' }
+
 // Get test cycle items (to find testRunItemId for a test case)
-const items = await api.Private.TestExecutions.getTestCycleItems(credentials, {
+const items = await api.Private.TestExecution.getTestCycleItems(credentials, {
   testCycleKey: 'M14-R1',
   projectId: 10315
 });
 
 // Update parent test execution
-await api.Private.TestExecutions.updateTestExecution(credentials, {
+await api.Private.TestExecution.updateTestExecution(credentials, {
   testExecutionKey: 'M14-E18',
   id: 2065132733, // Optional if testExecutionKey is provided
   actualStartDate: '2025-12-24T13:02:50.233Z',
@@ -496,14 +567,14 @@ await api.Private.TestExecutions.updateTestExecution(credentials, {
 });
 
 // Get test execution steps (to get step IDs for updates)
-const steps = await api.Private.TestExecutions.getTestExecutionSteps(credentials, {
+const steps = await api.Private.TestExecution.getTestExecutionSteps(credentials, {
   testCycleKey: 'M14-R1',
   testRunItemId: 1443476310, // From getTestCycleItems
   projectId: 10315
 });
 
 // Update test execution step status
-await api.Private.TestExecutions.updateTestExecutionStepStatus(credentials, {
+await api.Private.TestExecution.updateTestExecutionStepStatus(credentials, {
   id: 6287896613, // From getTestExecutionSteps
   testResultStatusId: 10952942,
   executionDate: '2025-12-24T13:02:50.232Z',
@@ -511,13 +582,15 @@ await api.Private.TestExecutions.updateTestExecutionStepStatus(credentials, {
 });
 
 // Update test execution step comment (actual result)
-await api.Private.TestExecutions.updateTestExecutionStepComment(credentials, {
+await api.Private.TestExecution.updateTestExecutionStepComment(credentials, {
   id: 6287896613, // From getTestExecutionSteps
   comment: 'Test passed successfully',
   projectId: 10315
 });
 ```
 
+**Note:** The old path (`Private.TestExecutions.*`) still works but is deprecated. Use `Private.TestExecution.*` for better organization.
+
 **Notes:**
 - Version numbers are absolute (1-based). Use `listTestCaseVersions()` to find available versions. If `version` is not provided, the latest version is used.
 - Private API methods require `PrivateApiCredentials` (`userEmail`, `apiToken`, `jiraInstanceUrl`). Context JWT tokens expire after 15 minutes and are automatically retrieved internally.
@@ -529,6 +602,25 @@ Feel free to drop ideas, suggestions or improvements into our [Community hub](ht
 
 ## Changelog
 
+### 1.4.0
+
+- **Changed**: Major structural reorganization of Private API to follow entity-based grouping (mirrors public API organization)
+  - **New Entity-Based Groups**: `Private.TestCase`, `Private.TestCycle`, `Private.TestExecution`
+  - **Private.TestCase**: Consolidates `Archiving`, `TestScriptData`, and `Versions` sub-groups
+  - **Private.TestCycle**: Adds `ExtendedData` sub-group for iteration operations
+  - **Private.TestExecution**: Consolidates all test execution operations and adds `ExtendedData` sub-group for iteration and version operations
+- **Added**: `createTestExecutionWithVersion()` - Create test execution for a specific test case version (not just latest version). Unlike the public API which only creates executions against the latest test case version, this function allows creating executions against any version of a test case.
+- **Deprecated**: Old feature-based paths are deprecated but still functional (will be removed in v2.0.0):
+  - `Private.TestExecutions.*` → Use `Private.TestExecution.*` instead
+  - `Private.ExtendedData.*` → Use `Private.TestCycle.ExtendedData.*` or `Private.TestExecution.ExtendedData.*` instead
+  - `Private.TestCaseArchiving.*` → Use `Private.TestCase.Archiving.*` instead
+  - `Private.TestScriptData.*` → Use `Private.TestCase.TestScriptData.*` instead
+  - `Private.Versions.*` → Use `Private.TestCase.Versions.*` instead
+  
+### 1.3.11
+
+- **Added**: Verbose logging option - Enable detailed request/response logging for failed API calls via `createZephyrApi(connection, true)` or `createZephyrApi(token, baseUrl, true)`
+
 ### 1.3.10
 
 - **Added**: New `TestScriptData` sub-group under Private API for managing test script data (Parameters and Test Data)