@rbaileysr/zephyr-managed-api 1.0.0 → 1.0.2

package/README.md

@@ -17,11 +17,10 @@ This Managed API wrapper provides a clean, type-safe interface to interact with
 - **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
-- **Region Support**: Configurable US and EU regions
-- **Flexible Authentication**: Supports OAuth tokens and ScriptRunner Connect API Connections
+- **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
-- **JSDoc Documentation**: All methods include descriptions and links to official API documentation
+- **Single Import**: Convenient default export for all utilities and types
 
 ## Installation
 
@@ -52,40 +51,74 @@ npm install @rbaileysr/zephyr-managed-api
 
 4. **Use in Scripts:**
    ```typescript
-   import { createZephyrApi } from '@rbaileysr/zephyr-managed-api';
+   // 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)
-   const Zephyr = createZephyrApi(ZephyrApiConnection, 'us');
+   // 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)
+#### Using API Connection (ScriptRunner Connect) - Single Import
 
 ```typescript
-import { createZephyrApi } from '@rbaileysr/zephyr-managed-api';
+// Single import for everything
+import Zephyr from '@rbaileysr/zephyr-managed-api';
 import ZephyrApiConnection from '../api/zephyr';
 
-const Zephyr = createZephyrApi(ZephyrApiConnection, 'us');
+// Create API instance (base URL configured in Generic Connector)
+const api = Zephyr.createZephyrApi(ZephyrApiConnection);
 
 // Get a test case
-const testCase = await Zephyr.TestCase.getTestCase({ testCaseKey: 'PROJ-T1' });
+const testCase = await api.TestCase.getTestCase({ testCaseKey: 'PROJ-T1' });
 console.log(`Test case: ${testCase.name}`);
 ```
 
-#### Using OAuth Token
+#### 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'
+);
 
-const oauthToken = 'your-oauth-token-here';
-const Zephyr = createZephyrApi(oauthToken, 'us');
+// 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 Zephyr.TestCase.listTestCases({
+const testCases = await api.TestCase.listTestCases({
   projectKey: 'PROJ',
   maxResults: 10,
   startAt: 0
@@ -96,7 +129,7 @@ console.log(`Found ${testCases.values.length} test cases`);
 #### Create a Test Case
 
 ```typescript
-const testCase = await Zephyr.TestCase.createTestCase({
+const testCase = await api.TestCase.createTestCase({
   body: {
     projectKey: 'PROJ',
     name: 'Login Test Case',
@@ -117,7 +150,7 @@ console.log(`Created test case: ${testCase.key}`);
 #### Create a Test Cycle
 
 ```typescript
-const testCycle = await Zephyr.TestCycle.createTestCycle({
+const testCycle = await api.TestCycle.createTestCycle({
   body: {
     projectKey: 'PROJ',
     name: 'Sprint 1 Regression',
@@ -136,7 +169,7 @@ console.log(`Created test cycle: ${testCycle.key}`);
 #### Create a Test Execution
 
 ```typescript
-const testExecution = await Zephyr.TestExecution.createTestExecution({
+const testExecution = await api.TestExecution.createTestExecution({
   body: {
     projectKey: 'PROJ',
     testCaseKey: 'PROJ-T1',
@@ -154,16 +187,16 @@ console.log(`Created test execution: ${testExecution.key || testExecution.id}`);
 
 ```typescript
 // First, get the test case
-const testCase = await Zephyr.TestCase.getTestCase({ testCaseKey: 'PROJ-T1' });
+const testCase = await api.TestCase.getTestCase({ testCaseKey: 'PROJ-T1' });
 
 // Update it
-await Zephyr.TestCase.updateTestCase({
+testCase.name = 'Updated Test Case Name';
+testCase.objective = 'Updated objective';
+testCase.labels = [...(testCase.labels || []), 'updated'];
+
+await api.TestCase.updateTestCase({
   testCaseKey: 'PROJ-T1',
-  body: {
-    name: 'Updated Test Case Name',
-    objective: 'Updated objective',
-    labels: [...(testCase.labels || []), 'updated']
-  }
+  body: testCase
 });
 ```
 
@@ -171,7 +204,7 @@ await Zephyr.TestCase.updateTestCase({
 
 ```typescript
 // Offset-based pagination
-const testCases = await Zephyr.TestCase.listTestCases({
+const testCases = await api.TestCase.listTestCases({
   projectKey: 'PROJ',
   folderId: 12345,
   maxResults: 50,
@@ -179,7 +212,7 @@ const testCases = await Zephyr.TestCase.listTestCases({
 });
 
 // Cursor-based pagination (for large datasets)
-const testCasesCursor = await Zephyr.TestCase.listTestCasesCursorPaginated({
+const testCasesCursor = await api.TestCase.listTestCasesCursorPaginated({
   projectKey: 'PROJ',
   limit: 100,
   startAtId: 0
@@ -190,7 +223,7 @@ const testCasesCursor = await Zephyr.TestCase.listTestCasesCursorPaginated({
 
 ```typescript
 // Link test case to Jira issue
-const issueLink = await Zephyr.TestCase.createTestCaseIssueLink({
+const issueLink = await api.TestCase.createTestCaseIssueLink({
   testCaseKey: 'PROJ-T1',
   body: {
     issueId: 12345
@@ -198,7 +231,7 @@ const issueLink = await Zephyr.TestCase.createTestCaseIssueLink({
 });
 
 // Link test case to web URL
-const webLink = await Zephyr.TestCase.createTestCaseWebLink({
+const webLink = await api.TestCase.createTestCaseWebLink({
   testCaseKey: 'PROJ-T1',
   body: {
     url: 'https://example.com/test-resource',
@@ -302,35 +335,39 @@ The Managed API is organized into the following groups:
 
 ### Using ScriptRunner Connect API Connection (Recommended)
 
-When using in ScriptRunner Connect, configure an API Connection in the web UI and use it:
+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 { createZephyrApi } from '@rbaileysr/zephyr-managed-api';
+import Zephyr from '@rbaileysr/zephyr-managed-api';
 import ZephyrApiConnection from '../api/zephyr';
 
-const Zephyr = createZephyrApi(ZephyrApiConnection, 'us');
+// 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:
+For local testing or when using OAuth tokens directly, provide the full base URL:
 
 ```typescript
-import { createZephyrApi } from '@rbaileysr/zephyr-managed-api';
-
-const Zephyr = createZephyrApi('your-oauth-token', 'us');
-```
-
-## Region Support
+import Zephyr from '@rbaileysr/zephyr-managed-api';
 
-The API supports both US and EU regions:
-
-```typescript
-// US region (default)
-const ZephyrUS = createZephyrApi(apiConnection, 'us');
+// US region
+const api = Zephyr.createZephyrApi(
+  'your-oauth-token',
+  'https://api.zephyrscale.smartbear.com/v2'
+);
 
 // EU region
-const ZephyrEU = createZephyrApi(apiConnection, 'eu');
+const apiEU = Zephyr.createZephyrApi(
+  'your-oauth-token',
+  'https://eu.api.zephyrscale.smartbear.com/v2'
+);
 ```
 
 ## Custom Fields
@@ -347,7 +384,7 @@ const customFields = {
   'Tester': 'user-account-id-here'
 };
 
-await Zephyr.TestCase.createTestCase({
+await api.TestCase.createTestCase({
   body: {
     projectKey: 'PROJ',
     name: 'Test Case',
@@ -368,8 +405,32 @@ The API uses Commons Core-compatible error types for consistent error handling.
 
 ### 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,
@@ -380,19 +441,7 @@ import {
   UnexpectedError
 } from '@rbaileysr/zephyr-managed-api';
 
-try {
-  const testCase = await Zephyr.TestCase.getTestCase({ testCaseKey: 'INVALID-T1' });
-} catch (error) {
-  if (error instanceof NotFoundError) {
-    console.log('Test case not found');
-  } else if (error instanceof BadRequestError) {
-    console.log('Invalid request');
-  } else if (error instanceof TooManyRequestsError) {
-    console.log('Rate limited - this should have been retried automatically');
-  } else if (error instanceof HttpError) {
-    console.log(`HTTP error: ${error.message}`);
-  }
-}
+// Use named imports as before
 ```
 
 ### Automatic Rate Limiting Handling
@@ -414,7 +463,7 @@ All API methods automatically handle rate limiting (HTTP 429) with:
 ```typescript
 // This call will automatically retry on 429 errors
 // You don't need to handle rate limiting manually
-const testCases = await Zephyr.TestCase.listTestCases({ projectKey: 'PROJ' });
+const testCases = await api.TestCase.listTestCases({ projectKey: 'PROJ' });
 ```
 
 If rate limiting occurs:
@@ -428,10 +477,13 @@ If rate limiting occurs:
 For advanced error handling, you can provide an `errorStrategy` parameter to customize how errors are handled:
 
 ```typescript
-import { retry, ErrorStrategyBuilder } from '@rbaileysr/zephyr-managed-api';
+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 Zephyr.TestCase.getTestCase(
+const testCase = await api.TestCase.getTestCase(
   { testCaseKey: 'PROJ-T1' },
   {
     handleHttp404Error: () => ({ type: 'return', value: null })
@@ -439,13 +491,13 @@ const testCase = await Zephyr.TestCase.getTestCase(
 );
 
 // Using ErrorStrategyBuilder for cleaner syntax
-const errorStrategy = new ErrorStrategyBuilder<TestCase | null>()
+const errorStrategy = new Zephyr.ErrorStrategyBuilder<TestCase | null>()
   .http404Error(() => ({ type: 'return', value: null }))
   .retryOnRateLimiting(10) // Retry up to 10 times on rate limiting
-  .http500Error(() => retry(5000)) // Retry server errors with 5s delay
+  .http500Error(() => Zephyr.retry(5000)) // Retry server errors with 5s delay
   .build();
 
-const testCase2 = await Zephyr.TestCase.getTestCase(
+const testCase2 = await api.TestCase.getTestCase(
   { testCaseKey: 'PROJ-T2' },
   errorStrategy
 );
@@ -485,7 +537,7 @@ const testCase2 = await Zephyr.TestCase.getTestCase(
 #### Offset-Based Pagination
 
 ```typescript
-const testCases = await Zephyr.TestCase.listTestCases({
+const testCases = await api.TestCase.listTestCases({
   projectKey: 'PROJ',
   maxResults: 50,
   startAt: 0
@@ -493,7 +545,7 @@ const testCases = await Zephyr.TestCase.listTestCases({
 
 // Check if more results available
 if (!testCases.isLast) {
-  const nextPage = await Zephyr.TestCase.listTestCases({
+  const nextPage = await api.TestCase.listTestCases({
     projectKey: 'PROJ',
     maxResults: 50,
     startAt: testCases.startAt + testCases.maxResults
@@ -504,7 +556,7 @@ if (!testCases.isLast) {
 #### Cursor-Based Pagination
 
 ```typescript
-const testCases = await Zephyr.TestCase.listTestCasesCursorPaginated({
+const testCases = await api.TestCase.listTestCasesCursorPaginated({
   projectKey: 'PROJ',
   limit: 100,
   startAtId: 0
@@ -512,7 +564,7 @@ const testCases = await Zephyr.TestCase.listTestCasesCursorPaginated({
 
 // Get next page
 if (testCases.nextStartAtId !== null) {
-  const nextPage = await Zephyr.TestCase.listTestCasesCursorPaginated({
+  const nextPage = await api.TestCase.listTestCasesCursorPaginated({
     projectKey: 'PROJ',
     limit: 100,
     startAtId: testCases.nextStartAtId
@@ -527,11 +579,14 @@ For convenience, use `getAllPages()` to automatically fetch all pages:
 #### Offset-Based Pagination
 
 ```typescript
-import { getAllPages } from '@rbaileysr/zephyr-managed-api';
+import Zephyr from '@rbaileysr/zephyr-managed-api';
+import ZephyrApiConnection from '../api/zephyr';
+
+const api = Zephyr.createZephyrApi(ZephyrApiConnection);
 
 // Automatically fetches all pages
-const allTestCases = await getAllPages(
-  (startAt, maxResults) => Zephyr.TestCase.listTestCases({
+const allTestCases = await Zephyr.getAllPages(
+  (startAt, maxResults) => api.TestCase.listTestCases({
     projectKey: 'PROJ',
     startAt,
     maxResults
@@ -546,11 +601,14 @@ console.log(`Found ${allTestCases.length} test cases`);
 #### Cursor-Based Pagination
 
 ```typescript
-import { getAllPagesCursor } from '@rbaileysr/zephyr-managed-api';
+import Zephyr from '@rbaileysr/zephyr-managed-api';
+import ZephyrApiConnection from '../api/zephyr';
+
+const api = Zephyr.createZephyrApi(ZephyrApiConnection);
 
 // Automatically fetches all pages
-const allTestCases = await getAllPagesCursor(
-  (startAtId, limit) => Zephyr.TestCase.listTestCasesCursorPaginated({
+const allTestCases = await Zephyr.getAllPagesCursor(
+  (startAtId, limit) => api.TestCase.listTestCasesCursorPaginated({
     projectKey: 'PROJ',
     startAtId,
     limit
@@ -605,7 +663,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
 
@@ -616,3 +674,26 @@ For issues, questions, or contributions, please refer to the project repository
 - **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
+