@rbaileysr/zephyr-managed-api 1.0.0 → 1.0.2

package/dist/README.md

@@ -0,0 +1,699 @@
+# Zephyr Managed API
+
+A comprehensive Managed API wrapper for Zephyr Cloud REST API v2, providing type-safe, hierarchical access to all Zephyr API endpoints.
+
+> **⚠️ Important: ScriptRunner Connect Runtime Only**
+> 
+> This package is specifically designed for **ScriptRunner Connect's custom runtime** and will **NOT work in standard Node.js projects**. It uses web standards-based APIs (fetch, etc.) and ES modules, making it compatible with ScriptRunner Connect's runtime environment.
+
+## Overview
+
+This Managed API wrapper provides a clean, type-safe interface to interact with the Zephyr Cloud API. It follows the same hierarchical pattern as other ScriptRunner Connect Managed APIs, making it easy to use and consistent with the platform's conventions.
+
+## Features
+
+- **Type-Safe**: Full TypeScript support with IntelliSense
+- **Hierarchical Structure**: Organized by resource type (TestCase, TestCycle, TestPlan, etc.)
+- **Comprehensive Coverage**: Supports all Zephyr Cloud REST API v2 endpoints
+- **Error Handling**: Built-in error parsing and handling using Commons Core error types
+- **Pagination Support**: Both offset-based and cursor-based pagination
+- **Flexible Authentication**: Supports OAuth tokens and ScriptRunner Connect API Connections (base URL configured in Generic Connector)
+- **Custom Fields**: Full support for dynamic custom fields
+- **Web App Compatible**: Works seamlessly in ScriptRunner Connect web app
+- **Single Import**: Convenient default export for all utilities and types
+
+## Installation
+
+### NPM Package
+
+```bash
+npm install @rbaileysr/zephyr-managed-api
+```
+
+**Important:** After installing via NPM, you must also add the package through ScriptRunner Connect's Package Manager in the web UI. The package will then be available in your workspace.
+
+### ScriptRunner Connect Workspace Setup
+
+1. **Add Package via Web UI:**
+   - Go to Package Manager in ScriptRunner Connect web UI
+   - Click "Add Package"
+   - Enter: `@rbaileysr/zephyr-managed-api`
+   - Click Add/Save
+
+2. **Sync Workspace Files:**
+   - Download latest workspace files from SFTP server
+   - Or use `SFTP: Sync Remote → Local` if using VS Code + SFTP
+
+3. **Install Dependencies:**
+   ```bash
+   npm install
+   ```
+
+4. **Use in Scripts:**
+   ```typescript
+   // Single import (recommended) - everything in one import
+   import Zephyr from '@rbaileysr/zephyr-managed-api';
+   import ZephyrApiConnection from '../api/zephyr';
+
+   // Using API Connection (recommended for ScriptRunner Connect)
+   // Base URL is configured in the Generic Connector
+   const api = Zephyr.createZephyrApi(ZephyrApiConnection);
+   
+   // Access utilities and error types from the same import
+   const pages = await Zephyr.getAllPages(...);
+   const errorStrategy = new Zephyr.ErrorStrategyBuilder()...;
+   ```
+   
+   **Alternative - Named Imports:**
+   ```typescript
+   // Named imports (if you prefer)
+   import { createZephyrApi, getAllPages, ErrorStrategyBuilder } from '@rbaileysr/zephyr-managed-api';
+   ```
+
+## Usage
+
+### Basic Examples
+
+#### Using API Connection (ScriptRunner Connect) - Single Import
+
+```typescript
+// Single import for everything
+import Zephyr from '@rbaileysr/zephyr-managed-api';
+import ZephyrApiConnection from '../api/zephyr';
+
+// Create API instance (base URL configured in Generic Connector)
+const api = Zephyr.createZephyrApi(ZephyrApiConnection);
+
+// Get a test case
+const testCase = await api.TestCase.getTestCase({ testCaseKey: 'PROJ-T1' });
+console.log(`Test case: ${testCase.name}`);
+```
+
+#### Using API Connection - Named Imports
+
+```typescript
+// Named imports (alternative)
+import { createZephyrApi } from '@rbaileysr/zephyr-managed-api';
+import ZephyrApiConnection from '../api/zephyr';
+
+const api = createZephyrApi(ZephyrApiConnection);
+const testCase = await api.TestCase.getTestCase({ testCaseKey: 'PROJ-T1' });
+```
+
+#### Using OAuth Token
+
+```typescript
+import Zephyr from '@rbaileysr/zephyr-managed-api';
+
+// OAuth token with full base URL (US region)
+const api = Zephyr.createZephyrApi(
+  'your-oauth-token-here',
+  'https://api.zephyrscale.smartbear.com/v2'
+);
+
+// OAuth token with full base URL (EU region)
+const apiEU = Zephyr.createZephyrApi(
+  'your-oauth-token-here',
+  'https://eu.api.zephyrscale.smartbear.com/v2'
+);
+
+// List test cases
+const testCases = await api.TestCase.listTestCases({
+  projectKey: 'PROJ',
+  maxResults: 10,
+  startAt: 0
+});
+console.log(`Found ${testCases.values.length} test cases`);
+```
+
+#### Create a Test Case
+
+```typescript
+const testCase = await api.TestCase.createTestCase({
+  body: {
+    projectKey: 'PROJ',
+    name: 'Login Test Case',
+    objective: 'Verify user can login successfully',
+    precondition: 'User account exists',
+    priorityName: 'High',
+    statusName: 'Draft',
+    labels: ['automated', 'regression'],
+    customFields: {
+      'Build Number': '2024.1',
+      'Release Date': '2024-01-15'
+    }
+  }
+});
+console.log(`Created test case: ${testCase.key}`);
+```
+
+#### Create a Test Cycle
+
+```typescript
+const testCycle = await api.TestCycle.createTestCycle({
+  body: {
+    projectKey: 'PROJ',
+    name: 'Sprint 1 Regression',
+    description: 'Regression tests for Sprint 1',
+    plannedStartDate: '2024-01-15T09:00:00Z',
+    plannedEndDate: '2024-01-22T17:00:00Z',
+    statusName: 'In Progress',
+    customFields: {
+      'Environment': 'Production'
+    }
+  }
+});
+console.log(`Created test cycle: ${testCycle.key}`);
+```
+
+#### Create a Test Execution
+
+```typescript
+const testExecution = await api.TestExecution.createTestExecution({
+  body: {
+    projectKey: 'PROJ',
+    testCaseKey: 'PROJ-T1',
+    testCycleKey: 'PROJ-R1',
+    statusName: 'Pass',
+    environmentName: 'Chrome Latest',
+    executionTime: 120000, // 2 minutes in milliseconds
+    comment: 'Test passed successfully'
+  }
+});
+console.log(`Created test execution: ${testExecution.key || testExecution.id}`);
+```
+
+#### Update a Test Case
+
+```typescript
+// First, get the test case
+const testCase = await api.TestCase.getTestCase({ testCaseKey: 'PROJ-T1' });
+
+// Update it
+testCase.name = 'Updated Test Case Name';
+testCase.objective = 'Updated objective';
+testCase.labels = [...(testCase.labels || []), 'updated'];
+
+await api.TestCase.updateTestCase({
+  testCaseKey: 'PROJ-T1',
+  body: testCase
+});
+```
+
+#### List with Filters and Pagination
+
+```typescript
+// Offset-based pagination
+const testCases = await api.TestCase.listTestCases({
+  projectKey: 'PROJ',
+  folderId: 12345,
+  maxResults: 50,
+  startAt: 0
+});
+
+// Cursor-based pagination (for large datasets)
+const testCasesCursor = await api.TestCase.listTestCasesCursorPaginated({
+  projectKey: 'PROJ',
+  limit: 100,
+  startAtId: 0
+});
+```
+
+#### Create Links
+
+```typescript
+// Link test case to Jira issue
+const issueLink = await api.TestCase.createTestCaseIssueLink({
+  testCaseKey: 'PROJ-T1',
+  body: {
+    issueId: 12345
+  }
+});
+
+// Link test case to web URL
+const webLink = await api.TestCase.createTestCaseWebLink({
+  testCaseKey: 'PROJ-T1',
+  body: {
+    url: 'https://example.com/test-resource',
+    description: 'External test resource'
+  }
+});
+```
+
+## API Groups
+
+The Managed API is organized into the following groups:
+
+### Project
+- `listProjects(options?)` - List all projects
+- `getProject(options)` - Get a specific project
+
+### Status
+- `listStatuses(options)` - List all statuses
+- `getStatus(options)` - Get a specific status
+- `createStatus(request)` - Create a new status
+- `updateStatus(request)` - Update a status
+
+### Priority
+- `listPriorities(options)` - List all priorities
+- `getPriority(options)` - Get a specific priority
+- `createPriority(request)` - Create a new priority
+- `updatePriority(request)` - Update a priority
+
+### Environment
+- `listEnvironments(options)` - List all environments
+- `getEnvironment(options)` - Get a specific environment
+- `createEnvironment(request)` - Create a new environment
+- `updateEnvironment(request)` - Update an environment
+
+### Folder
+- `listFolders(options)` - List all folders
+- `getFolder(options)` - Get a specific folder
+- `createFolder(request)` - Create a new folder
+
+### TestCase
+- `listTestCases(options?)` - List all test cases
+- `listTestCasesCursorPaginated(options?)` - List test cases with cursor pagination
+- `getTestCase(options)` - Get a specific test case
+- `createTestCase(request)` - Create a new test case
+- `updateTestCase(request)` - Update a test case
+- `getTestCaseLinks(testCaseKey)` - Get links for a test case
+- `createTestCaseIssueLink(request)` - Create issue link
+- `createTestCaseWebLink(request)` - Create web link
+- `listTestCaseVersions(options)` - List test case versions
+- `getTestCaseVersion(options)` - Get a specific version
+- `getTestCaseTestScript(testCaseKey)` - Get test script
+- `createTestCaseTestScript(request)` - Create or update test script
+- `getTestCaseTestSteps(testCaseKey, options?)` - Get test steps
+- `createTestCaseTestSteps(request)` - Create test steps
+
+### TestCycle
+- `listTestCycles(options?)` - List all test cycles
+- `getTestCycle(options)` - Get a specific test cycle
+- `createTestCycle(request)` - Create a new test cycle
+- `updateTestCycle(request)` - Update a test cycle
+- `getTestCycleLinks(testCycleIdOrKey)` - Get links for a test cycle
+- `createTestCycleIssueLink(request)` - Create issue link
+- `createTestCycleWebLink(request)` - Create web link
+
+### TestPlan
+- `listTestPlans(options?)` - List all test plans
+- `getTestPlan(options)` - Get a specific test plan
+- `createTestPlan(request)` - Create a new test plan
+- `createTestPlanIssueLink(request)` - Create issue link
+- `createTestPlanWebLink(request)` - Create web link
+- `createTestPlanTestCycleLink(request)` - Link test cycle to test plan
+
+### TestExecution
+- `listTestExecutions(options?)` - List all test executions
+- `listTestExecutionsNextgen(options?)` - List test executions with cursor pagination
+- `getTestExecution(options)` - Get a specific test execution
+- `createTestExecution(request)` - Create a new test execution
+- `updateTestExecution(request)` - Update a test execution
+- `getTestExecutionTestSteps(options)` - Get test steps for execution
+- `putTestExecutionTestSteps(request)` - Update test steps
+- `syncTestExecutionScript(request)` - Sync with test case script
+- `listTestExecutionLinks(testExecutionIdOrKey)` - Get links
+- `createTestExecutionIssueLink(request)` - Create issue link
+
+### Link
+- `deleteLink(options)` - Delete a link (idempotent)
+
+### IssueLink
+- `getIssueLinkTestCases(options)` - Get test cases linked to issue
+- `getIssueLinkTestCycles(options)` - Get test cycles linked to issue
+- `getIssueLinkTestPlans(options)` - Get test plans linked to issue
+- `getIssueLinkExecutions(options)` - Get test executions linked to issue
+
+### Automation
+- `createCustomExecutions(request)` - Upload custom format results
+- `createCucumberExecutions(request)` - Upload Cucumber results
+- `createJUnitExecutions(request)` - Upload JUnit XML results
+- `retrieveBDDTestCases(options)` - Retrieve BDD feature files
+
+## Authentication
+
+### Using ScriptRunner Connect API Connection (Recommended)
+
+When using in ScriptRunner Connect, configure a Generic Connector with the full base URL in the web UI:
+
+**For US region:** `https://api.zephyrscale.smartbear.com/v2`  
+**For EU region:** `https://eu.api.zephyrscale.smartbear.com/v2`
+
+Then use it in your script:
+
+```typescript
+import Zephyr from '@rbaileysr/zephyr-managed-api';
+import ZephyrApiConnection from '../api/zephyr';
+
+// Base URL is configured in the Generic Connector
+const api = Zephyr.createZephyrApi(ZephyrApiConnection);
+```
+
+### Using OAuth Token
+
+For local testing or when using OAuth tokens directly, provide the full base URL:
+
+```typescript
+import Zephyr from '@rbaileysr/zephyr-managed-api';
+
+// US region
+const api = Zephyr.createZephyrApi(
+  'your-oauth-token',
+  'https://api.zephyrscale.smartbear.com/v2'
+);
+
+// EU region
+const apiEU = Zephyr.createZephyrApi(
+  'your-oauth-token',
+  'https://eu.api.zephyrscale.smartbear.com/v2'
+);
+```
+
+## Custom Fields
+
+Custom fields are supported as flexible key-value pairs:
+
+```typescript
+const customFields = {
+  'Build Number': 20,
+  'Release Date': '2024-01-15',
+  'Pre-Condition(s)': 'User should have logged in.<br>User should have navigated to the panel.',
+  'Implemented': false,
+  'Category': ['Performance', 'Regression'],
+  'Tester': 'user-account-id-here'
+};
+
+await api.TestCase.createTestCase({
+  body: {
+    projectKey: 'PROJ',
+    name: 'Test Case',
+    customFields: customFields
+  }
+});
+```
+
+**Note**: 
+- Multi-line text fields support HTML with `<br>` tags
+- Dates should be in format `yyyy-MM-dd`
+- Users should have values of Jira User Account IDs
+- Custom field types are defined in your Zephyr project configuration
+
+## Error Handling
+
+The API uses Commons Core-compatible error types for consistent error handling. All API methods automatically retry on rate limiting (HTTP 429) with exponential backoff.
+
+### Error Types
+
+```typescript
+// Single import for everything
+import Zephyr from '@rbaileysr/zephyr-managed-api';
+import ZephyrApiConnection from '../api/zephyr';
+
+const api = Zephyr.createZephyrApi(ZephyrApiConnection);
+
+try {
+  const testCase = await api.TestCase.getTestCase({ testCaseKey: 'INVALID-T1' });
+} catch (error) {
+  if (error instanceof Zephyr.NotFoundError) {
+    console.log('Test case not found');
+  } else if (error instanceof Zephyr.BadRequestError) {
+    console.log('Invalid request');
+  } else if (error instanceof Zephyr.TooManyRequestsError) {
+    console.log('Rate limited - this should have been retried automatically');
+  } else if (error instanceof Zephyr.HttpError) {
+    console.log(`HTTP error: ${error.message}`);
+  }
+}
+```
+
+**Alternative - Named Imports:**
+```typescript
+import { 
+  createZephyrApi,
+  BadRequestError, 
+  UnauthorizedError, 
+  ForbiddenError,
+  NotFoundError,
+  TooManyRequestsError,
+  ServerError,
+  HttpError,
+  UnexpectedError
+} from '@rbaileysr/zephyr-managed-api';
+
+// Use named imports as before
+```
+
+### Automatic Rate Limiting Handling
+
+All API methods automatically handle rate limiting (HTTP 429) with:
+
+- **Exponential Backoff**: Starts at 1 second, doubles with each retry
+- **Retry-After Header Support**: Respects `Retry-After` header when present
+- **Configurable Retries**: Defaults to 5 retries, max delay of 60 seconds
+- **Transparent Operation**: Retries happen automatically - no code changes needed
+
+**Default Retry Configuration:**
+- Maximum retries: 5
+- Initial delay: 1 second
+- Maximum delay: 60 seconds
+- Backoff multiplier: 2x
+
+**Example:**
+```typescript
+// This call will automatically retry on 429 errors
+// You don't need to handle rate limiting manually
+const testCases = await api.TestCase.listTestCases({ projectKey: 'PROJ' });
+```
+
+If rate limiting occurs:
+1. The API waits (using Retry-After header if present, otherwise exponential backoff)
+2. Retries the request automatically
+3. Repeats up to 5 times
+4. Only throws `TooManyRequestsError` if all retries are exhausted
+
+### Error Strategy Support
+
+For advanced error handling, you can provide an `errorStrategy` parameter to customize how errors are handled:
+
+```typescript
+import Zephyr from '@rbaileysr/zephyr-managed-api';
+import ZephyrApiConnection from '../api/zephyr';
+
+const api = Zephyr.createZephyrApi(ZephyrApiConnection);
+
+// Return null instead of throwing on 404
+const testCase = await api.TestCase.getTestCase(
+  { testCaseKey: 'PROJ-T1' },
+  {
+    handleHttp404Error: () => ({ type: 'return', value: null })
+  }
+);
+
+// Using ErrorStrategyBuilder for cleaner syntax
+const errorStrategy = new Zephyr.ErrorStrategyBuilder<TestCase | null>()
+  .http404Error(() => ({ type: 'return', value: null }))
+  .retryOnRateLimiting(10) // Retry up to 10 times on rate limiting
+  .http500Error(() => Zephyr.retry(5000)) // Retry server errors with 5s delay
+  .build();
+
+const testCase2 = await api.TestCase.getTestCase(
+  { testCaseKey: 'PROJ-T2' },
+  errorStrategy
+);
+```
+
+**Available Error Strategy Handlers:**
+- `handleHttp400Error` - Handle 400 Bad Request
+- `handleHttp401Error` - Handle 401 Unauthorized
+- `handleHttp403Error` - Handle 403 Forbidden
+- `handleHttp404Error` - Handle 404 Not Found
+- `handleHttp429Error` - Handle 429 Too Many Requests (receives retryCount)
+- `handleHttp500Error` - Handle 500+ Server Errors
+- `handleHttpError` - Handle any HTTP error (fallback)
+
+**Error Strategy Actions:**
+- `retry(delay)` - Retry the request after the specified delay (milliseconds)
+- `continuePropagation()` - Let the error propagate normally (default)
+- `{ type: 'return', value: T }` - Return a specific value instead of throwing
+
+### Error Type Reference
+
+| Error Type | HTTP Status | Description |
+|------------|-------------|-------------|
+| `BadRequestError` | 400 | Invalid request parameters |
+| `UnauthorizedError` | 401 | Authentication required or invalid |
+| `ForbiddenError` | 403 | Insufficient permissions |
+| `NotFoundError` | 404 | Resource not found |
+| `TooManyRequestsError` | 429 | Rate limit exceeded (after retries) |
+| `ServerError` | 500+ | Server-side error |
+| `HttpError` | Other | Generic HTTP error |
+| `UnexpectedError` | N/A | Network or parsing errors |
+
+## Pagination
+
+### Manual Pagination
+
+#### Offset-Based Pagination
+
+```typescript
+const testCases = await api.TestCase.listTestCases({
+  projectKey: 'PROJ',
+  maxResults: 50,
+  startAt: 0
+});
+
+// Check if more results available
+if (!testCases.isLast) {
+  const nextPage = await api.TestCase.listTestCases({
+    projectKey: 'PROJ',
+    maxResults: 50,
+    startAt: testCases.startAt + testCases.maxResults
+  });
+}
+```
+
+#### Cursor-Based Pagination
+
+```typescript
+const testCases = await api.TestCase.listTestCasesCursorPaginated({
+  projectKey: 'PROJ',
+  limit: 100,
+  startAtId: 0
+});
+
+// Get next page
+if (testCases.nextStartAtId !== null) {
+  const nextPage = await api.TestCase.listTestCasesCursorPaginated({
+    projectKey: 'PROJ',
+    limit: 100,
+    startAtId: testCases.nextStartAtId
+  });
+}
+```
+
+### Automatic Pagination with `getAllPages()`
+
+For convenience, use `getAllPages()` to automatically fetch all pages:
+
+#### Offset-Based Pagination
+
+```typescript
+import Zephyr from '@rbaileysr/zephyr-managed-api';
+import ZephyrApiConnection from '../api/zephyr';
+
+const api = Zephyr.createZephyrApi(ZephyrApiConnection);
+
+// Automatically fetches all pages
+const allTestCases = await Zephyr.getAllPages(
+  (startAt, maxResults) => api.TestCase.listTestCases({
+    projectKey: 'PROJ',
+    startAt,
+    maxResults
+  }),
+  { maxResults: 50 } // Optional: page size
+);
+
+// allTestCases is an array of all TestCase objects from all pages
+console.log(`Found ${allTestCases.length} test cases`);
+```
+
+#### Cursor-Based Pagination
+
+```typescript
+import Zephyr from '@rbaileysr/zephyr-managed-api';
+import ZephyrApiConnection from '../api/zephyr';
+
+const api = Zephyr.createZephyrApi(ZephyrApiConnection);
+
+// Automatically fetches all pages
+const allTestCases = await Zephyr.getAllPagesCursor(
+  (startAtId, limit) => api.TestCase.listTestCasesCursorPaginated({
+    projectKey: 'PROJ',
+    startAtId,
+    limit
+  }),
+  { limit: 100 } // Optional: page size
+);
+
+// allTestCases is an array of all TestCase objects from all pages
+console.log(`Found ${allTestCases.length} test cases`);
+```
+
+**Note**: `getAllPages()` and `getAllPagesCursor()` automatically handle pagination and will make multiple API calls as needed. Be mindful of rate limits when fetching large datasets.
+
+## API Documentation
+
+All API methods include comprehensive JSDoc comments with:
+- Detailed descriptions of what each endpoint does
+- Parameter documentation with types and requirements
+- Return type documentation
+- Links to official Zephyr API documentation
+
+When using the package in ScriptRunner Connect, IntelliSense will display these descriptions and links in the code editor.
+
+## Type Definitions
+
+All TypeScript types are exported from the main module:
+
+```typescript
+import type { 
+  TestCase, 
+  TestCycle, 
+  TestExecution,
+  TestPlan,
+  CustomFields,
+  ZephyrApiConnection,
+  ErrorStrategy,
+  ErrorStrategyBuilder
+} from '@rbaileysr/zephyr-managed-api';
+```
+
+## All Group
+
+For programmatic access to all methods, use the `All` group:
+
+```typescript
+// Access all methods through the All group
+const testCase = await Zephyr.All.getTestCase({ testCaseKey: 'PROJ-T1' });
+const testCycle = await Zephyr.All.createTestCycle({ body: { ... } });
+```
+
+The `All` group provides a single point of access to all API methods across all resource groups, useful for dynamic method invocation or when you need to iterate over all available methods.
+
+## License
+
+UNLICENSED - Copyright Adaptavist 2025 (c) All rights reserved
+
+## Support
+
+For issues, questions, or contributions, please refer to the project repository on GitHub.
+
+## Links
+
+- **NPM Package**: https://www.npmjs.com/package/@rbaileysr/zephyr-managed-api
+- **Zephyr API Documentation**: https://support.smartbear.com/zephyr-scale-cloud/api-docs/v2/
+- **ScriptRunner Connect Documentation**: https://docs.adaptavist.com/src/latest/
+
+## Changelog
+
+### 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
+

package/dist/error-strategy.d.ts

@@ -1,3 +1,6 @@
+/*!
+ * Copyright Adaptavist 2025 (c) All rights reserved
+ */
 /**
  * Error Strategy Types and Utilities
  * Provides flexible error handling for API calls