@rbaileysr/zephyr-managed-api 1.0.2 → 1.2.0

package/README.md

@@ -331,6 +331,25 @@ 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, request)` - Create a new test case version
+- `createTestCaseComment(userEmail, apiToken, jiraInstanceUrl, request)` - Create a comment on a test case
+- `getTestCaseAttachments(userEmail, apiToken, jiraInstanceUrl, request)` - Get all attachments for a test case
+- `downloadAttachment(userEmail, apiToken, jiraInstanceUrl, request)` - Download an attachment file into memory
+- `createAttachment(userEmail, apiToken, jiraInstanceUrl, request)` - Upload an attachment to a test case
+
 ## Authentication
 
 ### Using ScriptRunner Connect API Connection (Recommended)
@@ -370,6 +389,253 @@ 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
+// Create a new version (test case ID is looked up automatically from key)
+const newVersion = await api.Private.createTestCaseVersion(
+  'user@example.com',
+  'jira-api-token',
+  'https://your-instance.atlassian.net',
+  {
+    testCaseKey: 'PROJ-T1',  // Uses key, looks up ID automatically
+    projectId: 10017          // Numeric project ID
+  }
+);
+// Returns: { id: 286693656, key: "ZEP-T18" }
+```
+
+**Important Notes:**
+- The method accepts `testCaseKey` and automatically looks up the numeric ID
+- The `projectId` must be numeric, not the project 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
+
+### Create Test Case Comment
+
+Add a comment to an existing test case.
+
+```typescript
+const comment = await api.Private.createTestCaseComment(
+  'user@example.com',
+  'jira-api-token',
+  'https://your-instance.atlassian.net',
+  {
+    testCaseKey: 'PROJ-T1',                    // Uses key, looks up ID automatically
+    projectId: 10233,                          // Numeric project ID
+    body: 'This is a test comment',            // Comment text
+    createdBy: '5d6fdc98dc6e480dbc021aae'      // Atlassian account ID
+  }
+);
+```
+
+### Get Test Case Attachments
+
+Retrieve all attachment details for a test case, including signed S3 URLs for downloading.
+
+```typescript
+const attachments = await api.Private.getTestCaseAttachments(
+  'user@example.com',
+  'jira-api-token',
+  'https://your-instance.atlassian.net',
+  {
+    testCaseKey: 'PROJ-T1',
+    projectId: 10233
+  }
+);
+
+console.log(`Found ${attachments.attachments.length} attachments`);
+attachments.attachments.forEach(att => {
+  console.log(`- ${att.name} (${att.fileSize} bytes, ${att.mimeType})`);
+  console.log(`  ID: ${att.id}`);
+  console.log(`  URL: ${att.url}`);
+});
+```
+
+**Response Structure:**
+Each attachment includes:
+- `id` - Attachment UUID
+- `name` - File name
+- `mimeType` - MIME type (e.g., 'image/jpeg', 'application/pdf')
+- `fileSize` - File size in bytes
+- `url` - Signed S3 URL for downloading (expires after ~90 minutes)
+- `createdOn` - Creation timestamp
+- `userKey` - Atlassian account ID of the uploader
+- `s3Key` - S3 storage key
+
+### Download Attachment
+
+Download an attachment file into memory. This method automatically gets a fresh signed URL and downloads the file.
+
+```typescript
+const fileBlob = await api.Private.downloadAttachment(
+  'user@example.com',
+  'jira-api-token',
+  'https://your-instance.atlassian.net',
+  {
+    testCaseKey: 'PROJ-T1',
+    projectId: 10233,
+    attachmentId: 'c3f14125-638f-47f9-9211-12a9777c09e7'  // Attachment UUID
+  }
+);
+
+// Use the blob (e.g., save to Record Storage, upload elsewhere, etc.)
+console.log(`Downloaded file: ${fileBlob.size} bytes, type: ${fileBlob.type}`);
+
+// Example: Convert to ArrayBuffer if needed
+const arrayBuffer = await fileBlob.arrayBuffer();
+```
+
+**Important Notes:**
+- The method automatically gets a fresh signed URL to ensure it hasn't expired
+- Returns a `Blob` object that can be used directly or converted to `ArrayBuffer`
+- The signed URLs from `getTestCaseAttachments` expire after ~90 minutes, but `downloadAttachment` always gets a fresh URL
+
+### Upload Attachment
+
+Upload a file attachment to a test case.
+
+```typescript
+const file = new Blob(['file content'], { type: 'text/plain' });
+
+const attachment = await api.Private.createAttachment(
+  'user@example.com',
+  'jira-api-token',
+  'https://your-instance.atlassian.net',
+  {
+    testCaseKey: 'PROJ-T1',                    // Uses key, looks up ID automatically
+    projectId: 10233,                          // Numeric project ID
+    file: file,                                 // Blob or ArrayBuffer
+    fileName: 'test-file.txt',
+    userAccountId: '5d6fdc98dc6e480dbc021aae'  // Atlassian account ID
+  }
+);
+```
+
+**Important Notes:**
+- The method handles the complete upload flow: getting S3 credentials, uploading to S3, and saving metadata
+- Supports both `Blob` and `ArrayBuffer` file types
+- MIME type is automatically detected from file name extension
+
+### 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:
@@ -677,6 +943,20 @@ For issues, questions, or contributions, please refer to the project repository
 
 ## 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 (now accepts testCaseKey and looks up ID automatically)
+  - `createTestCaseComment()` - Create comments on test cases
+  - `getTestCaseAttachments()` - Get all attachment details for a test case
+  - `downloadAttachment()` - Download attachment files into memory with automatic fresh URL retrieval
+  - `createAttachment()` - Upload file attachments to test cases
+- **Added**: Type definitions for private API requests and responses
+- **Changed**: `createTestCaseVersion()` now uses interface structure and automatically looks up test case ID from key
+- **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

package/dist/README.md

@@ -331,6 +331,25 @@ 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, request)` - Create a new test case version
+- `createTestCaseComment(userEmail, apiToken, jiraInstanceUrl, request)` - Create a comment on a test case
+- `getTestCaseAttachments(userEmail, apiToken, jiraInstanceUrl, request)` - Get all attachments for a test case
+- `downloadAttachment(userEmail, apiToken, jiraInstanceUrl, request)` - Download an attachment file into memory
+- `createAttachment(userEmail, apiToken, jiraInstanceUrl, request)` - Upload an attachment to a test case
+
 ## Authentication
 
 ### Using ScriptRunner Connect API Connection (Recommended)
@@ -370,6 +389,253 @@ 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
+// Create a new version (test case ID is looked up automatically from key)
+const newVersion = await api.Private.createTestCaseVersion(
+  'user@example.com',
+  'jira-api-token',
+  'https://your-instance.atlassian.net',
+  {
+    testCaseKey: 'PROJ-T1',  // Uses key, looks up ID automatically
+    projectId: 10017          // Numeric project ID
+  }
+);
+// Returns: { id: 286693656, key: "ZEP-T18" }
+```
+
+**Important Notes:**
+- The method accepts `testCaseKey` and automatically looks up the numeric ID
+- The `projectId` must be numeric, not the project 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
+
+### Create Test Case Comment
+
+Add a comment to an existing test case.
+
+```typescript
+const comment = await api.Private.createTestCaseComment(
+  'user@example.com',
+  'jira-api-token',
+  'https://your-instance.atlassian.net',
+  {
+    testCaseKey: 'PROJ-T1',                    // Uses key, looks up ID automatically
+    projectId: 10233,                          // Numeric project ID
+    body: 'This is a test comment',            // Comment text
+    createdBy: '5d6fdc98dc6e480dbc021aae'      // Atlassian account ID
+  }
+);
+```
+
+### Get Test Case Attachments
+
+Retrieve all attachment details for a test case, including signed S3 URLs for downloading.
+
+```typescript
+const attachments = await api.Private.getTestCaseAttachments(
+  'user@example.com',
+  'jira-api-token',
+  'https://your-instance.atlassian.net',
+  {
+    testCaseKey: 'PROJ-T1',
+    projectId: 10233
+  }
+);
+
+console.log(`Found ${attachments.attachments.length} attachments`);
+attachments.attachments.forEach(att => {
+  console.log(`- ${att.name} (${att.fileSize} bytes, ${att.mimeType})`);
+  console.log(`  ID: ${att.id}`);
+  console.log(`  URL: ${att.url}`);
+});
+```
+
+**Response Structure:**
+Each attachment includes:
+- `id` - Attachment UUID
+- `name` - File name
+- `mimeType` - MIME type (e.g., 'image/jpeg', 'application/pdf')
+- `fileSize` - File size in bytes
+- `url` - Signed S3 URL for downloading (expires after ~90 minutes)
+- `createdOn` - Creation timestamp
+- `userKey` - Atlassian account ID of the uploader
+- `s3Key` - S3 storage key
+
+### Download Attachment
+
+Download an attachment file into memory. This method automatically gets a fresh signed URL and downloads the file.
+
+```typescript
+const fileBlob = await api.Private.downloadAttachment(
+  'user@example.com',
+  'jira-api-token',
+  'https://your-instance.atlassian.net',
+  {
+    testCaseKey: 'PROJ-T1',
+    projectId: 10233,
+    attachmentId: 'c3f14125-638f-47f9-9211-12a9777c09e7'  // Attachment UUID
+  }
+);
+
+// Use the blob (e.g., save to Record Storage, upload elsewhere, etc.)
+console.log(`Downloaded file: ${fileBlob.size} bytes, type: ${fileBlob.type}`);
+
+// Example: Convert to ArrayBuffer if needed
+const arrayBuffer = await fileBlob.arrayBuffer();
+```
+
+**Important Notes:**
+- The method automatically gets a fresh signed URL to ensure it hasn't expired
+- Returns a `Blob` object that can be used directly or converted to `ArrayBuffer`
+- The signed URLs from `getTestCaseAttachments` expire after ~90 minutes, but `downloadAttachment` always gets a fresh URL
+
+### Upload Attachment
+
+Upload a file attachment to a test case.
+
+```typescript
+const file = new Blob(['file content'], { type: 'text/plain' });
+
+const attachment = await api.Private.createAttachment(
+  'user@example.com',
+  'jira-api-token',
+  'https://your-instance.atlassian.net',
+  {
+    testCaseKey: 'PROJ-T1',                    // Uses key, looks up ID automatically
+    projectId: 10233,                          // Numeric project ID
+    file: file,                                 // Blob or ArrayBuffer
+    fileName: 'test-file.txt',
+    userAccountId: '5d6fdc98dc6e480dbc021aae'  // Atlassian account ID
+  }
+);
+```
+
+**Important Notes:**
+- The method handles the complete upload flow: getting S3 credentials, uploading to S3, and saving metadata
+- Supports both `Blob` and `ArrayBuffer` file types
+- MIME type is automatically detected from file name extension
+
+### 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:
@@ -677,6 +943,20 @@ For issues, questions, or contributions, please refer to the project repository
 
 ## 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 (now accepts testCaseKey and looks up ID automatically)
+  - `createTestCaseComment()` - Create comments on test cases
+  - `getTestCaseAttachments()` - Get all attachment details for a test case
+  - `downloadAttachment()` - Download attachment files into memory with automatic fresh URL retrieval
+  - `createAttachment()` - Upload file attachments to test cases
+- **Added**: Type definitions for private API requests and responses
+- **Changed**: `createTestCaseVersion()` now uses interface structure and automatically looks up test case ID from key
+- **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