@rbaileysr/zephyr-managed-api 1.0.1 → 1.1.0

package/README.md

@@ -331,6 +331,21 @@ The Managed API is organized into the following groups:
 - `createJUnitExecutions(request)` - Upload JUnit XML results
 - `retrieveBDDTestCases(options)` - Retrieve BDD feature files
 
+### Private API ⚠️
+> **⚠️ WARNING: Private API Methods**
+> 
+> The following methods use Zephyr's private/unofficial API endpoints that are:
+> - **Not officially supported** by SmartBear
+> - **Not part of the public API documentation**
+> - **Subject to change at any time** without notice
+> - **Not covered by Standard Support**
+> 
+> Use these methods at your own risk. They may break with future Zephyr updates.
+
+- `getContextJwt(userEmail, apiToken, jiraInstanceUrl)` - Get Jira Context JWT token (required for private API calls)
+- `createCustomField(userEmail, apiToken, jiraInstanceUrl, category, request)` - Create custom fields for test cases, test plans, test runs, or test steps
+- `createTestCaseVersion(userEmail, apiToken, jiraInstanceUrl, testCaseId, projectId)` - Create a new test case version
+
 ## Authentication
 
 ### Using ScriptRunner Connect API Connection (Recommended)
@@ -370,6 +385,148 @@ const apiEU = Zephyr.createZephyrApi(
 );
 ```
 
+## Private API ⚠️
+
+> **⚠️ WARNING: Private API Usage**
+> 
+> The Private API methods use Zephyr's private/unofficial endpoints that are not officially supported by SmartBear. These endpoints may change or be removed at any time without notice and are not covered by Standard Support. Use these methods at your own risk.
+
+The Private API group provides access to functionality not available in the public Zephyr API, such as creating custom fields and test case versions. These methods require Jira user credentials (email and API token) rather than OAuth tokens.
+
+### Authentication
+
+Private API methods use Jira Basic Authentication (email + API token) to retrieve a Context JWT token, which is then used to authenticate with Zephyr's private endpoints.
+
+### Get Context JWT
+
+The Context JWT is a short-lived token (15 minutes) required for all private API calls:
+
+```typescript
+import Zephyr from '@rbaileysr/zephyr-managed-api';
+import ZephyrApiConnection from '../api/zephyr';
+
+const api = Zephyr.createZephyrApi(ZephyrApiConnection);
+
+// Get Context JWT token
+const contextJwt = await api.Private.getContextJwt(
+  'user@example.com',
+  'jira-api-token',
+  'https://your-instance.atlassian.net'
+);
+```
+
+### Create Custom Fields
+
+Create custom fields for test cases, test plans, test runs, or test steps:
+
+```typescript
+// Create a basic custom field for test cases
+const customField = await api.Private.createCustomField(
+  'user@example.com',
+  'jira-api-token',
+  'https://your-instance.atlassian.net',
+  'TEST_CASE', // Category: TEST_CASE, TEST_PLAN, TEST_RUN, or TEST_STEP
+  {
+    projectId: 10017,
+    name: 'Build Number',
+    type: 'SINGLE_LINE_TEXT', // CHECKBOX, NUMBER, DECIMAL, SINGLE_LINE_TEXT, MULTI_LINE_TEXT, SINGLE_CHOICE_SELECT_LIST, MULTI_CHOICE_SELECT_LIST, USER_LIST, DATE
+    required: false,
+    index: 4,
+    category: 'TEST_CASE',
+    options: [], // Only for SINGLE_CHOICE_SELECT_LIST or MULTI_CHOICE_SELECT_LIST
+    archived: false
+  }
+);
+
+// Create a custom field with options (select list)
+const selectField = await api.Private.createCustomField(
+  'user@example.com',
+  'jira-api-token',
+  'https://your-instance.atlassian.net',
+  'TEST_CASE',
+  {
+    projectId: 10017,
+    name: 'Test Category',
+    type: 'MULTI_CHOICE_SELECT_LIST',
+    required: false,
+    index: 5,
+    category: 'TEST_CASE',
+    options: [
+      { index: 1, name: 'Smoke', archived: false },
+      { index: 2, name: 'Regression', archived: false },
+      { index: 3, name: 'Performance', archived: false }
+    ],
+    archived: false
+  }
+);
+```
+
+**Available Custom Field Types:**
+- `CHECKBOX` - Checkbox
+- `NUMBER` - Number
+- `DECIMAL` - Decimal number
+- `SINGLE_LINE_TEXT` - Single-line text
+- `MULTI_LINE_TEXT` - Multi-line text
+- `SINGLE_CHOICE_SELECT_LIST` - Single-choice select list
+- `MULTI_CHOICE_SELECT_LIST` - Multi-choice select list
+- `USER_LIST` - User picker
+- `DATE` - Date picker
+
+**Available Categories:**
+- `TEST_CASE` - Custom field for test cases
+- `TEST_PLAN` - Custom field for test plans
+- `TEST_RUN` - Custom field for test cycles (test runs)
+- `TEST_STEP` - Custom field for test steps
+
+### Create Test Case Version
+
+Create a new version of an existing test case. **Note:** When a new version is created, the `testCaseId` changes for that test case.
+
+```typescript
+// First, get the test case to find its numeric ID
+const testCase = await api.TestCase.getTestCase({ testCaseKey: 'PROJ-T1' });
+const testCaseId = testCase.id; // Numeric ID, not the key
+
+// Create a new version
+const newVersion = await api.Private.createTestCaseVersion(
+  'user@example.com',
+  'jira-api-token',
+  'https://your-instance.atlassian.net',
+  testCaseId, // Numeric test case ID
+  10017 // Project ID or key
+);
+```
+
+**Important Notes:**
+- The `testCaseId` must be the numeric ID, not the test case key (e.g., `PROJ-T1`)
+- Use `api.TestCase.getTestCase()` to get the numeric ID from a test case key
+- If a new version already exists, the API will return a 409 Conflict error
+- The test case ID changes after creating a new version
+
+### Error Handling for Private API
+
+Private API methods use the same error types as the public API:
+
+```typescript
+try {
+  await api.Private.createCustomField(...);
+} catch (error) {
+  if (error instanceof Zephyr.BadRequestError) {
+    console.log('Invalid request parameters');
+  } else if (error instanceof Zephyr.UnauthorizedError) {
+    console.log('Authentication failed - check your credentials');
+  } else if (error instanceof Zephyr.ForbiddenError) {
+    console.log('Insufficient permissions');
+  } else if (error instanceof Zephyr.NotFoundError) {
+    console.log('Resource not found');
+  } else if (error instanceof Zephyr.ServerError) {
+    if (error.status === 409) {
+      console.log('Conflict - version already exists');
+    }
+  }
+}
+```
+
 ## Custom Fields
 
 Custom fields are supported as flexible key-value pairs:
@@ -663,7 +820,7 @@ The `All` group provides a single point of access to all API methods across all
 
 ## License
 
-MIT
+UNLICENSED - Copyright Adaptavist 2025 (c) All rights reserved
 
 ## Support
 
@@ -675,3 +832,34 @@ For issues, questions, or contributions, please refer to the project repository
 - **Zephyr API Documentation**: https://support.smartbear.com/zephyr-scale-cloud/api-docs/v2/
 - **ScriptRunner Connect Documentation**: https://docs.adaptavist.com/src/latest/
 
+## Changelog
+
+### 1.1.0
+
+- **Added**: Private API group with support for unofficial Zephyr endpoints
+  - `getContextJwt()` - Retrieve Jira Context JWT token for private API authentication
+  - `createCustomField()` - Create custom fields for test cases, test plans, test runs, and test steps
+  - `createTestCaseVersion()` - Create new test case versions
+- **Added**: Type definitions for private API requests (`CreatePrivateCustomFieldRequest`, `PrivateCustomFieldType`, `PrivateCustomFieldCategory`, etc.)
+- **Warning**: Private API methods are not officially supported and may change without notice
+
+### 1.0.1
+
+- **Added**: Comprehensive JSDoc comments with API endpoint descriptions and links to official documentation
+- **Added**: Single import option via default export for convenient usage
+- **Changed**: Removed `region` parameter from `createZephyrApi` - base URL now configured in Generic Connector
+- **Improved**: Error handling to support both `BadRequestError` and `NotFoundError` in test examples
+- **Improved**: Type safety and IntelliSense support throughout the API
+
+### 1.0.0
+
+- **Initial Release**: Complete Managed API wrapper for Zephyr Cloud REST API v2
+- **Added**: Full support for all Zephyr API endpoints (Test Cases, Test Cycles, Test Plans, Test Executions, etc.)
+- **Added**: Type-safe TypeScript definitions for all API operations
+- **Added**: Hierarchical API structure matching ScriptRunner Connect conventions
+- **Added**: Automatic rate limiting retry with exponential backoff
+- **Added**: Support for both API Connection and OAuth token authentication
+- **Added**: Pagination helpers (`getAllPages`, `getAllPagesCursor`)
+- **Added**: Error strategy builder for advanced error handling
+- **Added**: Comprehensive error types compatible with Commons Core
+