@rbaileysr/zephyr-managed-api 1.4.1 → 1.4.2

package/AI_AGENT_GUIDE.md

@@ -0,0 +1,1423 @@
+# Zephyr Managed API - AI Agent Guide
+
+> **📋 Purpose**
+> 
+> This guide is designed to provide AI coding agents with comprehensive knowledge of the Zephyr Managed API. It covers all available functions, their capabilities, limitations, usage patterns, and best practices.
+
+---
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [API Structure](#api-structure)
+3. [Public API Groups](#public-api-groups)
+4. [Private API Groups](#private-api-groups)
+5. [Authentication](#authentication)
+6. [Error Handling](#error-handling)
+7. [Common Patterns](#common-patterns)
+8. [Version Support](#version-support)
+9. [Limitations and Capabilities](#limitations-and-capabilities)
+10. [Best Practices](#best-practices)
+
+---
+
+## Overview
+
+The Zephyr Managed API is a comprehensive, type-safe wrapper for the Zephyr Scale Cloud REST API v2. It provides hierarchical access to all Zephyr API endpoints, organized into logical groups.
+
+### Key Features
+
+- **Type Safety**: Full TypeScript support with IntelliSense
+- **Hierarchical Organization**: Methods organized by entity (TestCase, TestCycle, etc.)
+- **Automatic Retry**: Built-in retry logic for rate limiting (HTTP 429)
+- **Error Handling**: Comprehensive error types and strategies
+- **Private API Support**: Access to unofficial endpoints for advanced functionality
+- **Version Support**: Many methods support version-specific operations
+
+### API Construction
+
+```typescript
+import { createZephyrApi } from '@rbaileysr/zephyr-managed-api';
+import ZephyrApiConnection from './api/zephyr';
+
+// Using API Connection (ScriptRunner Connect - recommended)
+const Zephyr = createZephyrApi(ZephyrApiConnection);
+
+// Using OAuth Token
+const Zephyr = createZephyrApi('oauth-token', 'https://api.zephyrscale.smartbear.com/v2');
+
+// With verbose logging (logs full request/response on failures)
+const Zephyr = createZephyrApi(ZephyrApiConnection, true);
+```
+
+### Verbose Logging
+
+When enabled, verbose logging automatically logs full request and response details whenever an API call fails. This is useful for debugging production issues.
+
+**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)
+
+---
+
+## API Structure
+
+The API is organized into two main categories:
+
+1. **Public API**: Officially supported endpoints from Zephyr
+2. **Private API**: Unofficial endpoints (use at your own risk)
+
+### Public API Groups
+
+- `TestCase` - Test case operations
+- `TestCycle` - Test cycle (test run) operations
+- `TestExecution` - Test execution operations
+- `TestPlan` - Test plan operations
+- `Folder` - Folder operations
+- `Project` - Project operations (read-only)
+- `Status` - Status operations
+- `Priority` - Priority operations
+- `Environment` - Environment operations
+- `Link` - Generic link operations
+- `IssueLink` - Issue link operations
+- `Automation` - Automation operations
+
+### Private API Groups
+
+- `Private.Authentication` - Get Context JWT tokens
+- `Private.Comments` - Comment operations
+- `Private.Config` - Configuration operations (Custom Fields, Labels, Iterations, DataSets)
+- `Private.Attachments` - Attachment operations
+- `Private.VersionControl` - Version-specific data operations
+- `Private.TestCase` - Test case private operations (v1.4.0+)
+- `Private.TestCycle` - Test cycle private operations (v1.4.0+)
+- `Private.TestExecution` - Test execution private operations (v1.4.0+)
+- `Private.TestPlan` - Test plan private operations (v1.4.2+)
+
+### Access Pattern
+
+```typescript
+// Public API
+const testCase = await Zephyr.TestCase.getTestCase({ testCaseKey: 'PROJ-T1' });
+
+// Private API
+const comments = await Zephyr.Private.Comments.getTestCaseComments(credentials, {
+  testCaseKey: 'PROJ-T1',
+  projectId: 12345,
+  version: 2  // Optional version support
+});
+```
+
+---
+
+## Public API Groups
+
+### TestCase Group
+
+**Purpose**: Manage test cases - create, read, update, list, and version operations.
+
+**Methods:**
+
+#### List Operations
+- `listTestCases(options?)` - List all test cases (paginated)
+  - Supports filtering by `projectKey`, `folderId`
+  - Pagination: `startAt`, `maxResults` (default: 50)
+  - Returns: `TestCaseList` with `values`, `total`, `isLast`, etc.
+  
+- `listTestCasesCursorPaginated(options?)` - List test cases (cursor-based pagination)
+  - Better performance for large datasets
+  - Pagination: `startAtId`, `limit` (default: 100)
+  - Returns: `CursorPagedTestCaseList` with `nextStartAtId`
+
+#### Get Operations
+- `getTestCase(options)` - Get a specific test case
+  - Required: `testCaseKey` (e.g., 'PROJ-T1')
+  - Returns: `TestCase` with all fields
+  - Supports error strategy for custom error handling
+
+- `getTestCaseVersion(options)` - Get a specific version of a test case
+  - Required: `testCaseKey`, `version` (absolute, 1-based)
+  - Returns: `TestCase` for that version
+  - Use `listTestCaseVersions()` to find available versions
+
+- `listTestCaseVersions(options)` - List all versions of a test case
+  - Required: `testCaseKey`
+  - Returns: `TestCaseVersionLinkList` ordered by most recent first
+  - Pagination: `startAt`, `maxResults`
+
+#### Create/Update Operations
+- `createTestCase(request)` - Create a new test case
+  - Required: `body.projectKey`, `body.name`
+  - Optional: `body.folderId`, `body.statusId`, `body.priorityId`, `body.ownerId`, `body.labels`, `body.customFields`, etc.
+  - Returns: `KeyedCreatedResource` with `key`, `id`, `self`
+
+- `updateTestCase(request)` - Update an existing test case
+  - Required: `testCaseKey`, `body` (full TestCase object)
+  - **Warning**: Unspecified fields will be cleared
+  - Returns: Updated `TestCase`
+
+#### Link Operations
+- `getTestCaseLinks(testCaseKey)` - Get all links for a test case
+  - Returns: `TestCaseLinkList` with issue links and web links
+
+- `createTestCaseIssueLink(request)` - Create issue link
+  - Required: `testCaseKey`, `body.issueId`
+  - Optional: `body.type` ('COVERAGE', 'BLOCKS', 'RELATED' - defaults to 'COVERAGE')
+  - Returns: `CreatedResource` with `id`, `self`
+
+- `createTestCaseWebLink(request)` - Create web link
+  - Required: `testCaseKey`, `body.url`
+  - Optional: `body.description`, `body.type`
+  - Returns: `CreatedResource` with `id`, `self`
+
+#### Test Script Operations
+- `getTestCaseTestScript(testCaseKey)` - Get test script
+  - Returns: `TestScript` with `type` ('PLAIN_TEXT' or 'BDD') and `text`
+
+- `createTestCaseTestScript(request)` - Create/update test script
+  - Required: `testCaseKey`, `body.type`, `body.text`
+  - **Limitation**: Only works with latest version
+
+- `getTestCaseTestSteps(testCaseKey)` - Get test steps
+  - Returns: `TestStepsList` with array of steps
+  - **Limitation**: Does not return step IDs
+
+- `createTestCaseTestSteps(request)` - Create/update test steps
+  - Required: `testCaseKey`, `body.mode` ('OVERWRITE' or 'APPEND'), `body.items`
+  - **Limitation**: Call-to-test steps can only reference latest version
+  - **Limitation**: Does not support step IDs for updates
+
+**Capabilities:**
+- ✅ Full CRUD operations
+- ✅ Version history access
+- ✅ Link management
+- ✅ Test script and steps management
+- ✅ Pagination (offset and cursor-based)
+- ✅ Error strategy support
+
+**Limitations:**
+- ❌ Cannot update older versions directly (use Private API)
+- ❌ Cannot specify version for call-to-test steps (use Private API)
+- ❌ Cannot get step IDs (use Private API)
+- ❌ Cannot delete links (use Private API)
+
+---
+
+### TestCycle Group
+
+**Purpose**: Manage test cycles (test runs) - create, read, update, list operations.
+
+**Methods:**
+
+#### List Operations
+- `listTestCycles(options?)` - List all test cycles (paginated)
+  - Supports filtering by `projectKey`, `folderId`, `jiraProjectVersionId`
+  - Pagination: `startAt`, `maxResults` (default: 10, max: 1000)
+
+#### Get Operations
+- `getTestCycle(options)` - Get a specific test cycle
+  - Required: `testCycleIdOrKey` (ID or key like 'PROJ-R1')
+  - Returns: `TestCycle` with all fields
+
+#### Create/Update Operations
+- `createTestCycle(request)` - Create a new test cycle
+  - Required: `body.projectKey`, `body.name`, `body.plannedStartDate`, `body.plannedEndDate`
+  - Optional: `body.description`, `body.jiraProjectVersionId`, `body.folderId`, `body.ownerId`, `body.labels`, `body.customFields`
+  - Returns: `KeyedCreatedResource`
+
+- `updateTestCycle(request)` - Update an existing test cycle
+  - Required: `testCycleIdOrKey`, `body` (full TestCycle object)
+  - **Warning**: Unspecified fields will be cleared
+
+#### Link Operations
+- `getTestCycleLinks(testCycleIdOrKey)` - Get all links for a test cycle
+- `createTestCycleIssueLink(request)` - Create issue link
+- `createTestCycleWebLink(request)` - Create web link
+
+**Capabilities:**
+- ✅ Full CRUD operations
+- ✅ Link management
+- ✅ Filtering by project, folder, version
+
+**Limitations:**
+- ❌ Cannot delete links (use Private API)
+- ❌ Cannot access iteration data (use Private API)
+- ❌ Cannot get extended data (use Private API)
+
+---
+
+### TestExecution Group
+
+**Purpose**: Manage test executions - create, read, update, list operations.
+
+**Methods:**
+
+#### List Operations
+- `listTestExecutions(options?)` - List test executions (paginated)
+  - Supports filtering by `projectKey`, `testCycleKey`, `testCaseKey`, `statusName`, `assignedTo`, `environmentName`
+  - Pagination: `startAt`, `maxResults` (default: 50)
+
+- `listTestExecutionsNextgen(options?)` - List test executions (cursor-based)
+  - Better performance for large datasets
+  - Pagination: `startAtId`, `limit` (default: 100)
+
+#### Get Operations
+- `getTestExecution(options)` - Get a specific test execution
+  - Required: `testExecutionIdOrKey` (ID or key like 'PROJ-E1')
+  - Returns: `TestExecution` with all fields
+
+#### Create/Update Operations
+- `createTestExecution(request)` - Create a new test execution
+  - Required: `body.projectKey`, `body.testCaseKey`, `body.testCycleKey`, `body.statusName`
+  - Optional: `body.environmentName`, `body.actualEndDate`, `body.executionTime`, `body.executedById`, `body.assignedToId`, `body.comment`, `body.customFields`, `body.testScriptResults`
+  - **Limitation**: Only creates execution against latest test case version
+  - Returns: `CreatedResource` (no key returned)
+
+- `updateTestExecution(request)` - Update an existing test execution
+  - Required: `testExecutionIdOrKey`, `body` (full TestExecution object)
+  - **Warning**: Unspecified fields will be cleared
+
+#### Test Steps Operations
+- `getTestExecutionTestSteps(testExecutionIdOrKey)` - Get test execution steps
+  - Returns: `TestExecutionStepList` with step results
+
+- `putTestExecutionTestSteps(request)` - Update test execution steps
+  - Required: `testExecutionIdOrKey`, `body.items` (array of step results)
+  - **Warning**: Replaces all steps
+
+- `syncTestExecutionScript(testExecutionIdOrKey)` - Sync execution steps with test case
+  - Automatically updates execution steps to match current test case steps
+
+#### Link Operations
+- `listTestExecutionLinks(testExecutionIdOrKey)` - Get all links for a test execution
+- `createTestExecutionIssueLink(request)` - Create issue link
+
+**Capabilities:**
+- ✅ Full CRUD operations
+- ✅ Test step result management
+- ✅ Script synchronization
+- ✅ Link management
+- ✅ Filtering and pagination
+
+**Limitations:**
+- ❌ Cannot create execution for specific test case version (use Private API)
+- ❌ Cannot create execution with test data (use Private API)
+- ❌ Cannot update step status/comment individually (use Private API)
+- ❌ Cannot access iteration/version data (use Private API)
+- ❌ Cannot list executions across all test case versions (use Private API)
+
+---
+
+### TestPlan Group
+
+**Purpose**: Manage test plans - create, read, list operations.
+
+**Methods:**
+
+#### List Operations
+- `listTestPlans(options?)` - List all test plans (paginated)
+  - Supports filtering by `projectKey`
+  - Pagination: `startAt`, `maxResults` (default: 10, max: 1000)
+
+#### Get Operations
+- `getTestPlan(options)` - Get a specific test plan
+  - Required: `testPlanIdOrKey` (ID or key like 'PROJ-P1')
+  - Returns: `TestPlan` with all fields
+
+#### Create Operations
+- `createTestPlan(request)` - Create a new test plan
+  - Required: `body.projectKey`, `body.name`
+  - Optional: `body.objective`, `body.folderId`, `body.statusName`, `body.ownerId`, `body.labels`, `body.customFields`
+  - Returns: `KeyedCreatedResource`
+
+#### Link Operations
+- `createTestPlanIssueLink(request)` - Create issue link
+- `createTestPlanWebLink(request)` - Create web link
+- `createTestPlanTestCycleLink(request)` - Link test cycle to test plan
+
+**Capabilities:**
+- ✅ Create and read operations
+- ✅ Link management
+
+**Limitations:**
+- ❌ No update operation (test plans are immutable)
+- ❌ Cannot delete links (use Private API)
+
+---
+
+### Folder Group
+
+**Purpose**: Manage folders - create, read, list operations.
+
+**Methods:**
+
+- `listFolders(options?)` - List all folders (paginated)
+  - Supports filtering by `projectKey`, `folderType` ('TEST_CASE', 'TEST_CYCLE', 'TEST_PLAN')
+  - Pagination: `startAt`, `maxResults`
+
+- `getFolder(folderId)` - Get a specific folder
+  - Returns: `Folder` with all fields
+
+- `createFolder(request)` - Create a new folder
+  - Required: `body.projectKey`, `body.name`, `body.folderType`
+  - Optional: `body.parentId`
+  - Returns: `CreatedResource`
+
+**Capabilities:**
+- ✅ Create and read operations
+- ✅ Filtering by project and type
+
+**Limitations:**
+- ❌ No update or delete operations
+
+---
+
+### Project Group
+
+**Purpose**: Read project information (read-only).
+
+**Methods:**
+
+- `listProjects(options?)` - List all projects (paginated)
+  - Pagination: `startAt`, `maxResults` (default: 10, max: 1000)
+
+- `getProject(options)` - Get a specific project
+  - Required: `projectIdOrKey`
+  - Returns: `Project` with all fields
+
+**Capabilities:**
+- ✅ Read-only access to project information
+
+**Limitations:**
+- ❌ No create, update, or delete operations
+
+---
+
+### Status Group
+
+**Purpose**: Manage test execution statuses.
+
+**Methods:**
+
+- `listStatuses()` - List all statuses
+  - Returns: `StatusList` with all available statuses
+
+- `getStatus(statusId)` - Get a specific status
+  - Returns: `Status` with all fields
+
+- `createStatus(request)` - Create a new status
+  - Required: `body.name`, `body.color`
+  - Returns: `CreatedResource`
+
+- `updateStatus(request)` - Update an existing status
+  - Required: `statusId`, `body` (full Status object)
+
+**Capabilities:**
+- ✅ Full CRUD operations
+
+---
+
+### Priority Group
+
+**Purpose**: Manage test case priorities.
+
+**Methods:**
+
+- `listPriorities()` - List all priorities
+- `getPriority(priorityId)` - Get a specific priority
+- `createPriority(request)` - Create a new priority
+- `updatePriority(request)` - Update an existing priority
+
+**Capabilities:**
+- ✅ Full CRUD operations
+
+---
+
+### Environment Group
+
+**Purpose**: Manage test environments.
+
+**Methods:**
+
+- `listEnvironments()` - List all environments
+- `getEnvironment(environmentId)` - Get a specific environment
+- `createEnvironment(request)` - Create a new environment
+- `updateEnvironment(request)` - Update an existing environment
+
+**Capabilities:**
+- ✅ Full CRUD operations
+
+---
+
+### Link Group
+
+**Purpose**: Generic link operations.
+
+**Methods:**
+
+- `getLink(linkId)` - Get a specific link
+- `deleteLink(request)` - Delete a link
+  - Required: `linkId`
+  - **Note**: This is a public API method, but only works for certain link types
+
+**Capabilities:**
+- ✅ Read and delete operations
+
+**Limitations:**
+- ❌ Cannot create links (use specific group methods)
+- ❌ Delete may not work for all link types (use Private API)
+
+---
+
+### IssueLink Group
+
+**Purpose**: Issue link operations.
+
+**Methods:**
+
+- `getIssueLinkTestCases(issueKey)` - Get test cases linked to an issue
+- `getIssueLinkTestCycles(issueKey)` - Get test cycles linked to an issue
+- `getIssueLinkTestPlans(issueKey)` - Get test plans linked to an issue
+- `getIssueLinkTestExecutions(issueKey)` - Get test executions linked to an issue
+
+**Capabilities:**
+- ✅ Query links by issue key
+
+---
+
+### Automation Group
+
+**Purpose**: Automation-related operations.
+
+**Methods:**
+
+- `getAutomationExecutions(options)` - Get automation executions
+  - Supports filtering by `projectKey`, `testCaseKey`, `testCycleKey`, `statusName`
+  - Pagination: `startAt`, `maxResults`
+
+**Capabilities:**
+- ✅ Query automation execution data
+
+---
+
+## Private API Groups
+
+⚠️ **WARNING**: Private API methods use Zephyr's unofficial 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.
+
+### Authentication
+
+**Purpose**: Get Jira Context JWT tokens required for all private API calls.
+
+**Methods:**
+
+- `getContextJwt(credentials)` - Get Context JWT token
+  - Required: `credentials.userEmail`, `credentials.apiToken`, `credentials.jiraInstanceUrl`
+  - Returns: JWT token string
+  - **Token expires after 15 minutes** - tokens are automatically retrieved internally
+  - **Note**: This method is called automatically by other private API methods
+
+- `enableZephyrForProject(credentials, request)` - Enable Zephyr for a Jira project
+  - Required: `request.projectId`
+  
+- `isZephyrEnabledForProject(credentials, request)` - Check if Zephyr is enabled
+  - Required: `request.projectId`
+  - Returns: Boolean
+
+**Capabilities:**
+- ✅ Get authentication tokens
+- ✅ Project enablement checks
+
+**Limitations:**
+- ❌ Tokens expire after 15 minutes (handled automatically)
+
+---
+
+### Comments
+
+**Purpose**: Manage comments on test cases, test cycles, and test plans.
+
+**Methods:**
+
+#### Test Case Comments
+- `getTestCaseComments(credentials, request)` - Get all comments for a test case
+  - Required: `testCaseKey`, `projectId`
+  - Optional: `version` (absolute, 1-based) - if not provided, uses latest version
+  - Returns: `PrivateComment[]`
+
+- `createTestCaseComment(credentials, request)` - Create a comment on a test case
+  - Required: `testCaseKey`, `projectId`, `body`, `createdBy`
+  - Optional: `version` (v1.4.2+) - if not provided, uses latest version
+  - Returns: `CreateTestCaseCommentResponse`
+
+- `deleteTestCaseComment(credentials, request)` - Delete a comment (v1.4.2+)
+  - Required: `testCaseKey`, `projectId`, `commentId`
+  - Optional: `version` - if not provided, uses latest version
+  - Returns: `void`
+
+#### Test Cycle Comments
+- `getTestCycleComments(credentials, request)` - Get all comments for a test cycle
+- `createTestCycleComment(credentials, request)` - Create a comment on a test cycle
+- `deleteTestCycleComment(credentials, request)` - Delete a comment (v1.4.2+)
+
+#### Test Plan Comments
+- `getTestPlanComments(credentials, request)` - Get all comments for a test plan
+- `createTestPlanComment(credentials, request)` - Create a comment on a test plan
+- `deleteTestPlanComment(credentials, request)` - Delete a comment (v1.4.2+)
+
+**Capabilities:**
+- ✅ Full CRUD operations for comments
+- ✅ Version support for test case comments
+- ✅ Access to comment metadata (createdBy, createdOn)
+
+**Limitations:**
+- ❌ Cannot update comments (only create/delete)
+- ❌ Cannot get comments for specific test execution steps (not available)
+
+---
+
+### Attachments
+
+**Purpose**: Manage attachments on test cases, test cycles, test plans, test steps, and test executions.
+
+**Methods:**
+
+#### Test Case Attachments
+- `getTestCaseAttachments(credentials, request)` - Get all attachments for a test case
+  - Required: `testCaseKey`, `projectId`
+  - Optional: `version` - if not provided, uses latest version
+  - Returns: `GetTestCaseAttachmentsResponse` with signed S3 URLs
+
+- `downloadAttachment(credentials, request)` - Download an attachment into memory
+  - Required: `testCaseKey`, `projectId`, `attachmentId`
+  - Optional: `version` - if not provided, uses latest version
+  - Returns: `Blob` with file content
+
+- `createTestCaseAttachment(credentials, request)` - Upload an attachment to a test case
+  - Required: `testCaseKey`, `projectId`, `file` (Blob or ArrayBuffer), `fileName`, `userAccountId`
+  - Optional: `version` (v1.4.2+) - if not provided, uses latest version
+  - Returns: `UploadDetailsResponse`
+
+- `deleteTestCaseAttachment(credentials, request)` - Delete an attachment (v1.4.2+)
+  - Required: `projectId`, `attachmentId`
+  - Optional: `testCaseKey`, `version` - for version-specific attachments
+
+#### Test Step Attachments
+- `getTestStepAttachments(credentials, request)` - Get attachments for a test step
+- `downloadTestStepAttachment(credentials, request)` - Download test step attachment
+- `createTestStepAttachment(credentials, request)` - Upload attachment to test step
+  - Optional: `version` (v1.4.2+) - for version-specific test steps
+- `deleteTestStepAttachment(credentials, request)` - Delete test step attachment (v1.4.2+)
+  - Optional: `version` - for version-specific test steps
+
+#### Test Cycle Attachments
+- `getTestCycleAttachments(credentials, request)` - Get all attachments for a test cycle
+- `downloadTestCycleAttachment(credentials, request)` - Download test cycle attachment
+- `createTestCycleAttachment(credentials, request)` - Upload attachment to test cycle
+- `deleteTestCycleAttachment(credentials, request)` - Delete test cycle attachment (v1.4.2+)
+
+#### Test Plan Attachments
+- `getTestPlanAttachments(credentials, request)` - Get all attachments for a test plan
+- `downloadTestPlanAttachment(credentials, request)` - Download test plan attachment
+- `createTestPlanAttachment(credentials, request)` - Upload attachment to test plan
+- `deleteTestPlanAttachment(credentials, request)` - Delete test plan attachment (v1.4.2+)
+
+#### Test Execution Attachments
+- `getTestExecutionAttachments(credentials, request)` - Get all attachments for a test execution
+- `downloadTestExecutionAttachment(credentials, request)` - Download test execution attachment
+- `createTestExecutionAttachment(credentials, request)` - Upload attachment to test execution
+
+#### Test Execution Step Attachments
+- `getTestExecutionStepAttachments(credentials, request)` - Get attachments for a test execution step
+- `downloadTestExecutionStepAttachment(credentials, request)` - Download test execution step attachment
+- `createTestExecutionStepAttachment(credentials, request)` - Upload attachment to test execution step
+
+**Capabilities:**
+- ✅ Full CRUD operations for attachments
+- ✅ Version support for test case and test step attachments
+- ✅ Signed S3 URLs for secure downloads
+- ✅ Support for all attachment types (images, PDFs, documents, etc.)
+
+**Limitations:**
+- ❌ Cannot update attachment metadata (only create/delete)
+- ❌ File size limits apply (check Zephyr documentation)
+
+---
+
+### Config
+
+**Purpose**: Manage configuration items (Custom Fields, Labels, Iterations, DataSets).
+
+**Methods:**
+
+#### Custom Fields
+- `createCustomField(credentials, request)` - Create a custom field
+  - Required: `request.body.name`, `request.body.category` ('TEST_CASE', 'TEST_CYCLE', 'TEST_PLAN', 'TEST_EXECUTION')
+  - Optional: `request.body.fieldType`, `request.body.options`, etc.
+  - Returns: `CreatedResource`
+
+- `getCustomFields(credentials, request)` - Get all custom fields
+  - Required: `request.category`
+  - Returns: Array of custom field definitions
+
+#### Labels
+- `getLabels(credentials, request)` - Get all labels
+- `createLabel(credentials, request)` - Create a new label
+
+#### Iterations
+- `getIterations(credentials, request)` - Get all iterations
+- `createIteration(credentials, request)` - Create a new iteration
+
+#### DataSets
+- `getDataSets(credentials, request)` - Get all data sets
+- `createDataSet(credentials, request)` - Create a new data set
+- `updateDataSet(credentials, request)` - Update an existing data set
+
+#### Archive Operations
+- `archiveConfig(credentials, request)` - Archive a config item
+- `unarchiveConfig(credentials, request)` - Unarchive a config item
+
+**Capabilities:**
+- ✅ Full CRUD operations for configuration
+- ✅ Archive/unarchive support
+
+---
+
+### VersionControl
+
+**Purpose**: Get version-specific data (links, test scripts, test steps).
+
+**Methods:**
+
+#### Test Case Version-Specific Operations
+- `getTestCaseIssueLinks(credentials, request)` - Get issue links for a specific version
+  - Required: `testCaseKey`, `projectId`
+  - Optional: `version` - if not provided, uses latest version
+  - Returns: Array of issue links
+
+- `getTestCaseWebLinks(credentials, request)` - Get web links for a specific version
+  - Required: `testCaseKey`, `projectId`
+  - Optional: `version` - if not provided, uses latest version
+  - Returns: Array of web links
+
+- `getTestCaseTestScript(credentials, request)` - Get test script for a specific version
+  - Required: `testCaseKey`, `projectId`
+  - Optional: `version` - if not provided, uses latest version
+  - Returns: `TestScript` or `null`
+
+- `getTestCaseTestSteps(credentials, request)` - Get test steps for a specific version
+  - Required: `testCaseKey`, `projectId`
+  - Optional: `version` - if not provided, uses latest version
+  - Returns: `TestStepsList`
+
+#### Test Execution Step Operations
+- `getTestExecutionStepIssueLinks(credentials, request)` - Get issue links for a test execution step
+- `createTestExecutionStepIssueLink(credentials, request)` - Create issue link for a test execution step
+
+**Capabilities:**
+- ✅ Version-specific data access
+- ✅ Historical data retrieval
+
+**Limitations:**
+- ❌ Cannot modify version-specific data (only read)
+
+---
+
+### TestCase (Entity-Based Group - v1.4.0+)
+
+**Purpose**: Consolidates all test case-related private API operations.
+
+**Sub-groups:**
+
+#### Archiving
+- `getArchivedTestCases(credentials, request)` - List archived test cases
+- `archiveTestCases(credentials, request)` - Archive test cases
+- `unarchiveTestCases(credentials, request)` - Unarchive test cases
+
+#### TestScriptData
+- `setTestCaseParamTypeToParameter(credentials, request)` - Set param type to PARAMETER
+  - Optional: `version` (v1.4.2+) - if not provided, uses latest version
+  
+- `setTestCaseParameters(credentials, request)` - Set test case parameters
+  - Required: `parameters` array
+  - Optional: `version` (v1.4.2+) - if not provided, uses latest version
+  
+- `setTestCaseParamTypeToTestData(credentials, request)` - Set param type to TEST_DATA
+  - Optional: `version` (v1.4.2+) - if not provided, uses latest version
+  
+- `setTestCaseTestData(credentials, request)` - Set test data rows
+  - Required: `testData` array (array of column objects)
+  - Optional: `version` (v1.4.2+) - if not provided, uses latest version
+  
+- `getTestCaseTestData(credentials, request)` - Get test data
+  - Optional: `version` (v1.4.2+) - if not provided, uses latest version
+  - Returns: `TestCaseTestDataResponse` with `paramType`, `parameters`, `testData`
+  
+- `hasTestCaseTestData(credentials, request)` - Check if test case has test data
+  - Optional: `version` (v1.4.2+) - if not provided, uses latest version
+  - Returns: `HasTestCaseTestDataResponse` with `hasData` boolean
+
+#### Versions
+- `createTestCaseVersion(credentials, request)` - Create a new test case version
+  - Required: `testCaseKey`, `projectId`
+  - Returns: `CreateTestCaseVersionResponse` with new version number
+
+#### Methods
+- `getTestCaseTestStepsWithIds(credentials, request)` - Get test steps with IDs (v1.4.1+)
+  - Required: `testCaseKey`, `projectId`
+  - Optional: `version` - if not provided, uses latest version
+  - Returns: `GetTestCaseTestStepsWithIdsResponse` with `testScriptId`, `stepByStepScriptId`, `steps` (with IDs)
+  - **Key Feature**: Includes step IDs needed for updates, and call-to-test step information with test case IDs and versions
+
+- `createTestCaseTestStepsWithVersion(credentials, request)` - Create/update test steps with version support (v1.4.1+)
+  - Required: `testCaseKey`, `projectId`, `body.mode` ('OVERWRITE' or 'APPEND'), `body.items`
+  - Optional: `version` (v1.4.2+) - version for the test case itself
+  - Optional: `version` in `body.items[].testCase` - version for call-to-test steps
+  - **Key Feature**: Allows specifying version for call-to-test steps, enabling references to older test case versions
+  - **Key Feature**: Supports step IDs for updating existing steps
+  - Returns: `void`
+
+- `updateTestCasePlainTextScriptWithVersion(credentials, request)` - Update plain text script for a version (v1.4.2+)
+  - Required: `testCaseKey`, `projectId`, `scriptId`, `text`
+  - Optional: `version` - if not provided, uses latest version
+  - Returns: `void`
+
+- `updateTestCaseBddScriptWithVersion(credentials, request)` - Update BDD script for a version (v1.4.2+)
+  - Required: `testCaseKey`, `projectId`, `scriptId`, `text`
+  - Optional: `version` - if not provided, uses latest version
+  - Returns: `void`
+
+- `deleteTestCaseWebLink(credentials, request)` - Delete web link (v1.4.2+)
+  - Required: `testCaseKey`, `projectId`, `linkId`
+  - Optional: `version` - if not provided, uses latest version
+  - Returns: `void`
+
+- `deleteTestCaseIssueLink(credentials, request)` - Delete issue link (v1.4.2+)
+  - Required: `testCaseKey`, `projectId`, `linkId`
+  - Optional: `version` - if not provided, uses latest version
+  - Returns: `void`
+
+**Capabilities:**
+- ✅ Version-specific operations
+- ✅ Test script data management (parameters/test data)
+- ✅ Test step management with IDs
+- ✅ Call-to-test steps with version support
+- ✅ Link deletion
+- ✅ Archiving operations
+
+**Limitations:**
+- ❌ Cannot delete test cases (only archive)
+- ❌ Cannot modify test case metadata for older versions (only test script data)
+
+---
+
+### TestCycle (Entity-Based Group - v1.4.0+)
+
+**Purpose**: Extended data operations for test cycles.
+
+**Sub-groups:**
+
+#### ExtendedData
+- `getTestCycleIteration(credentials, request)` - Get iteration for a test cycle
+  - Required: `testCycleKey`, `projectId`
+  - Returns: `TestCycleIterationResponse` with `id`, `key`, `iterationId`
+
+- `updateTestCycleIteration(credentials, request)` - Update iteration for a test cycle
+  - Required: `testCycleKey`, `projectId`, `iterationId`
+  - Returns: `void`
+
+#### Methods
+- `deleteTestCycleWebLink(credentials, request)` - Delete web link (v1.4.2+)
+  - Required: `testCycleKey`, `projectId`, `linkId`
+  - Returns: `void`
+
+- `deleteTestCycleIssueLink(credentials, request)` - Delete issue link (v1.4.2+)
+  - Required: `testCycleKey`, `projectId`, `linkId`
+  - Returns: `void`
+
+**Capabilities:**
+- ✅ Iteration management
+- ✅ Link deletion
+
+**Limitations:**
+- ❌ Cannot access other extended data fields
+
+---
+
+### TestExecution (Entity-Based Group - v1.4.0+)
+
+**Purpose**: All test execution-related private API operations.
+
+**Sub-groups:**
+
+#### ExtendedData
+- `getTestExecutionIteration(credentials, request)` - Get iteration for a test execution
+- `updateTestExecutionIteration(credentials, request)` - Update iteration for a test execution
+- `getTestExecutionVersion(credentials, request)` - Get Jira version for a test execution
+- `updateTestExecutionVersion(credentials, request)` - Update Jira version for a test execution
+
+#### Methods
+- `listAllTestExecutionsForTestCase(credentials, request)` - List executions across all versions (v1.4.1+)
+  - Required: `testCaseKey`, `projectId`
+  - Optional: `offset`, `limit` (pagination)
+  - Returns: `ListAllTestExecutionsForTestCaseResponse` with `data` (minimal: `key`, `testCase`) and `totalCount`
+  - **Key Feature**: Returns executions from all test case versions, not just latest
+  - **Note**: Returns minimal data - use public API to get full execution details
+
+- `createTestExecutionWithTestData(credentials, request)` - Create execution with test data
+  - Required: `body` (TestExecutionInput), `projectId`
+  - Optional: `testData` (array of parameter values)
+  - Returns: `CreatedResource`
+
+- `createTestExecutionWithVersion(credentials, request)` - Create execution for specific version (v1.4.1+)
+  - Required: `body.testCaseKey`, `body.testCycleKey`, `body.statusName`, `body.version`, `projectId`
+  - Optional: `body.environmentName`, `body.actualEndDate`, `body.executionTime`, `body.executedById`, `body.assignedToId`, `body.comment`, `body.customFields`, `assignedTo`, `iterationId`, `jiraVersionId`
+  - Returns: `CreateTestExecutionWithVersionResponse` with `id` and `key`
+  - **Key Feature**: Creates execution against a specific test case version, not just latest
+
+- `updateTestExecution(credentials, request)` - Update test execution
+  - Required: `testExecutionKey`, `body` (full TestExecution object)
+  - Returns: `void`
+
+- `getTestExecutionSteps(credentials, request)` - Get test execution steps
+  - Returns: Array of step results with full details
+
+- `updateTestExecutionStepStatus(credentials, request)` - Update individual step status
+  - Required: `testExecutionKey`, `stepIndex`, `statusName`, `projectId`
+  - Returns: `void`
+
+- `updateTestExecutionStepComment(credentials, request)` - Update individual step comment
+  - Required: `testExecutionKey`, `stepIndex`, `comment`, `projectId`
+  - Returns: `void`
+
+- `getTestCycleItems(credentials, request)` - Get all items in a test cycle
+  - Required: `testCycleKey`, `projectId`
+  - Returns: Array of test execution summaries
+
+**Capabilities:**
+- ✅ Version-specific execution creation
+- ✅ Test data support
+- ✅ Individual step updates
+- ✅ Iteration and version management
+- ✅ List executions across all versions
+
+**Limitations:**
+- ❌ Cannot delete test executions (immutable)
+- ❌ Cannot update execution for older test case versions
+
+---
+
+### TestPlan (Entity-Based Group - v1.4.2+)
+
+**Purpose**: Private API operations for test plans.
+
+**Methods:**
+
+- `deleteTestPlanWebLink(credentials, request)` - Delete web link
+  - Required: `testPlanKey`, `projectId`, `linkId`
+  - Returns: `void`
+
+- `deleteTestPlanIssueLink(credentials, request)` - Delete issue link
+  - Required: `testPlanKey`, `projectId`, `linkId`
+  - Returns: `void`
+
+**Capabilities:**
+- ✅ Link deletion
+
+**Limitations:**
+- ❌ Limited operations (test plans are mostly immutable)
+
+---
+
+## Authentication
+
+### Public API Authentication
+
+Public API methods use OAuth tokens or API Connections (ScriptRunner Connect).
+
+**OAuth Token:**
+```typescript
+const Zephyr = createZephyrApi('oauth-token', 'https://api.zephyrscale.smartbear.com/v2');
+```
+
+**API Connection (ScriptRunner Connect):**
+```typescript
+import ZephyrApiConnection from './api/zephyr';
+const Zephyr = createZephyrApi(ZephyrApiConnection);
+```
+
+### Private API Authentication
+
+All private API methods require `PrivateApiCredentials`:
+
+```typescript
+interface PrivateApiCredentials {
+  userEmail: string;        // Jira user email
+  apiToken: string;        // Jira API token
+  jiraInstanceUrl: string; // Full Jira instance URL (e.g., 'https://your-instance.atlassian.net')
+}
+```
+
+**Example:**
+```typescript
+const credentials = {
+  userEmail: 'user@example.com',
+  apiToken: 'your-api-token',
+  jiraInstanceUrl: 'https://your-instance.atlassian.net'
+};
+
+const comments = await Zephyr.Private.Comments.getTestCaseComments(credentials, {
+  testCaseKey: 'PROJ-T1',
+  projectId: 12345
+});
+```
+
+**Important Notes:**
+- Context JWT tokens expire after 15 minutes
+- Tokens are automatically retrieved internally by private API methods
+- You don't need to call `getContextJwt()` manually unless you need the token for custom operations
+
+---
+
+## Error Handling
+
+### Error Types
+
+The API uses comprehensive error types from `@managed-api/commons-core`:
+
+- `BadRequestError` (400) - Invalid request parameters
+- `UnauthorizedError` (401) - Authentication failed
+- `ForbiddenError` (403) - Insufficient permissions
+- `NotFoundError` (404) - Resource not found
+- `TooManyRequestsError` (429) - Rate limited (automatically retried)
+- `ServerError` (500+) - Server errors
+- `UnexpectedError` - Network errors, JSON parsing errors, etc.
+
+### Default Behavior
+
+- **Automatic Retry**: Rate limiting (429) is automatically retried with exponential backoff
+- **Error Throwing**: All errors are thrown as exceptions
+- **Error Logging**: Uncaught errors are logged by the ScriptRunner Connect runtime
+
+### Error Strategy
+
+Public API methods support optional error strategy for custom error handling:
+
+```typescript
+import { retry, continuePropagation } from '@managed-api/commons-core';
+
+// Return null on 404 instead of throwing
+const testCase = await Zephyr.TestCase.getTestCase(
+  { testCaseKey: 'PROJ-T1' },
+  {
+    handleHttp404Error: () => ({ type: 'return', value: null })
+  }
+);
+
+// Retry on rate limiting with custom delay
+const testCase = await Zephyr.TestCase.getTestCase(
+  { testCaseKey: 'PROJ-T1' },
+  {
+    handleHttp429Error: (response, retryCount) => retry(2000)
+  }
+);
+```
+
+**Private API Methods:**
+- Do not support error strategy (always throw errors)
+- Use try/catch blocks for error handling
+
+---
+
+## Common Patterns
+
+### Pagination
+
+#### Offset-Based Pagination
+```typescript
+let startAt = 0;
+const maxResults = 50;
+let allTestCases = [];
+
+while (true) {
+  const page = await Zephyr.TestCase.listTestCases({
+    startAt,
+    maxResults
+  });
+  
+  allTestCases.push(...page.values);
+  
+  if (page.isLast) break;
+  startAt += maxResults;
+}
+```
+
+#### Cursor-Based Pagination
+```typescript
+let startAtId: number | null = null;
+const limit = 100;
+let allTestCases = [];
+
+while (true) {
+  const page = await Zephyr.TestCase.listTestCasesCursorPaginated({
+    startAtId,
+    limit
+  });
+  
+  allTestCases.push(...page.values);
+  
+  if (!page.nextStartAtId) break;
+  startAtId = page.nextStartAtId;
+}
+```
+
+### Version Operations
+
+```typescript
+// Get all versions
+const versions = await Zephyr.TestCase.listTestCaseVersions({
+  testCaseKey: 'PROJ-T1'
+});
+
+// Get specific version
+const version2 = await Zephyr.TestCase.getTestCaseVersion({
+  testCaseKey: 'PROJ-T1',
+  version: 2
+});
+
+// Create new version
+const newVersion = await Zephyr.Private.TestCase.Versions.createTestCaseVersion(
+  credentials,
+  {
+    testCaseKey: 'PROJ-T1',
+    projectId: 12345
+  }
+);
+```
+
+### Test Steps with Version Support
+
+```typescript
+// Get steps with IDs
+const steps = await Zephyr.Private.TestCase.getTestCaseTestStepsWithIds(
+  credentials,
+  {
+    testCaseKey: 'PROJ-T1',
+    projectId: 12345,
+    version: 2  // Optional: get steps for version 2
+  }
+);
+
+// Create steps with version support for call-to-test
+await Zephyr.Private.TestCase.createTestCaseTestStepsWithVersion(
+  credentials,
+  {
+    testCaseKey: 'PROJ-T1',
+    projectId: 12345,
+    version: 2,  // Optional: update steps for version 2
+    body: {
+      mode: 'APPEND',
+      items: [
+        {
+          inline: {
+            description: 'Step 1',
+            expectedResult: 'Result 1'
+          }
+        },
+        {
+          testCase: {
+            testCaseKey: 'PROJ-T2',
+            version: 1  // Reference version 1 of PROJ-T2
+          }
+        }
+      ]
+    }
+  }
+);
+```
+
+### Creating Test Executions
+
+```typescript
+// Public API - latest version only
+const execution = await Zephyr.TestExecution.createTestExecution({
+  body: {
+    projectKey: 'PROJ',
+    testCaseKey: 'PROJ-T1',
+    testCycleKey: 'PROJ-R1',
+    statusName: 'Not Executed'
+  }
+});
+
+// Private API - specific version
+const executionV2 = await Zephyr.Private.TestExecution.createTestExecutionWithVersion(
+  credentials,
+  {
+    body: {
+      projectKey: 'PROJ',
+      testCaseKey: 'PROJ-T1',
+      testCycleKey: 'PROJ-R1',
+      statusName: 'Not Executed',
+      version: 2  // Create execution for version 2
+    },
+    projectId: 12345
+  }
+);
+```
+
+---
+
+## Version Support
+
+### Version Numbering
+
+Versions are **absolute, 1-based**:
+- Version 1 = First version ever created
+- Version 2 = Second version created
+- Highest number = Current/latest version
+
+### Finding Versions
+
+```typescript
+// List all versions
+const versions = await Zephyr.TestCase.listTestCaseVersions({
+  testCaseKey: 'PROJ-T1'
+});
+
+// Latest version is the one with highest majorVersion
+const latestVersion = versions.values[0]; // Most recent first
+```
+
+### Methods with Version Support
+
+**Public API:**
+- `getTestCaseVersion()` - Get specific version
+- `listTestCaseVersions()` - List all versions
+
+**Private API (v1.4.2+):**
+Most test case-related methods support optional `version` parameter:
+- `getTestCaseComments()` - Get comments for a version
+- `createTestCaseComment()` - Create comment on a version
+- `deleteTestCaseComment()` - Delete comment from a version
+- `getTestCaseAttachments()` - Get attachments for a version
+- `createTestCaseAttachment()` - Upload attachment to a version
+- `deleteTestCaseAttachment()` - Delete attachment from a version
+- `getTestCaseTestStepsWithIds()` - Get steps for a version
+- `createTestCaseTestStepsWithVersion()` - Update steps for a version
+- `setTestCaseParamTypeToParameter()` - Set param type for a version
+- `setTestCaseParameters()` - Set parameters for a version
+- `setTestCaseParamTypeToTestData()` - Set param type for a version
+- `setTestCaseTestData()` - Set test data for a version
+- `getTestCaseTestData()` - Get test data for a version
+- `hasTestCaseTestData()` - Check test data for a version
+- `updateTestCasePlainTextScriptWithVersion()` - Update plain text script for a version
+- `updateTestCaseBddScriptWithVersion()` - Update BDD script for a version
+- `deleteTestCaseWebLink()` - Delete web link from a version
+- `deleteTestCaseIssueLink()` - Delete issue link from a version
+- `getTestStepAttachments()` - Get attachments for a version
+- `createTestStepAttachment()` - Upload attachment to a version
+- `deleteTestStepAttachment()` - Delete attachment from a version
+
+**Version Resolution:**
+- If `version` is provided and > 0: Uses that specific version
+- If `version` is undefined or 0: Uses latest version
+- Version resolution happens automatically via `getTestCaseVersion()` or `getTestCase()`
+
+---
+
+## Limitations and Capabilities
+
+### Public API Limitations
+
+**Test Cases:**
+- ❌ Cannot update older versions directly
+- ❌ Cannot specify version for call-to-test steps
+- ❌ Cannot get step IDs
+- ❌ Cannot delete links
+- ❌ Cannot update test scripts for older versions
+
+**Test Executions:**
+- ❌ Cannot create execution for specific test case version
+- ❌ Cannot create execution with test data
+- ❌ Cannot update step status/comment individually
+- ❌ Cannot list executions across all versions
+- ❌ Cannot access iteration/version data
+
+**Test Cycles:**
+- ❌ Cannot delete links
+- ❌ Cannot access iteration data
+
+**Test Plans:**
+- ❌ No update operation (immutable)
+- ❌ Cannot delete links
+
+### Private API Capabilities
+
+**Test Cases:**
+- ✅ Version-specific operations
+- ✅ Test script data management (parameters/test data)
+- ✅ Test step management with IDs
+- ✅ Call-to-test steps with version support
+- ✅ Link deletion
+- ✅ Archiving operations
+- ✅ Comment and attachment management with version support
+
+**Test Executions:**
+- ✅ Version-specific execution creation
+- ✅ Test data support
+- ✅ Individual step updates
+- ✅ Iteration and version management
+- ✅ List executions across all versions
+
+**Test Cycles:**
+- ✅ Iteration management
+- ✅ Link deletion
+
+**Test Plans:**
+- ✅ Link deletion
+
+### What Cannot Be Done
+
+**Completely Unsupported:**
+- ❌ Delete test cases (only archive)
+- ❌ Delete test executions (immutable)
+- ❌ Delete test cycles (immutable)
+- ❌ Delete test plans (immutable)
+- ❌ Update test case metadata for older versions (only test script data)
+- ❌ Bulk operations (must iterate)
+- ❌ Transaction support (no rollback)
+
+**Requires Workarounds:**
+- ❌ Update comments (delete and recreate)
+- ❌ Update attachments (delete and recreate)
+- ❌ Bulk updates (iterate and update individually)
+
+---
+
+## Best Practices
+
+### 1. Use Public API When Possible
+
+Prefer public API methods over private API methods when functionality is available:
+- Public API is officially supported
+- Public API is more stable
+- Public API has better documentation
+
+### 2. Handle Errors Appropriately
+
+```typescript
+try {
+  const testCase = await Zephyr.TestCase.getTestCase({ testCaseKey: 'PROJ-T1' });
+} catch (error) {
+  if (error instanceof NotFoundError) {
+    // Handle not found
+  } else if (error instanceof UnauthorizedError) {
+    // Handle authentication failure
+  } else {
+    // Handle other errors
+  }
+}
+```
+
+### 3. Use Pagination Helpers
+
+For large datasets, use cursor-based pagination when available:
+```typescript
+// Better performance
+const testCases = await Zephyr.TestCase.listTestCasesCursorPaginated({
+  projectKey: 'PROJ',
+  limit: 100
+});
+```
+
+### 4. Cache Context JWT Tokens
+
+Private API methods automatically handle token caching, but if you're making many calls:
+- Tokens expire after 15 minutes
+- Methods automatically refresh tokens
+- No manual token management needed
+
+### 5. Use Version Support Wisely
+
+When working with versions:
+- Always check available versions first
+- Use `listTestCaseVersions()` to find the latest version
+- Be aware that version numbers are absolute (1-based)
+- Latest version = highest version number
+
+### 6. Test Step Management
+
+When updating test steps:
+- Use `getTestCaseTestStepsWithIds()` to get step IDs
+- Include step IDs when updating existing steps
+- Use 'APPEND' mode to add steps without losing existing ones
+- Use 'OVERWRITE' mode to replace all steps
+
+### 7. Error Strategy for Public API
+
+Use error strategy for graceful error handling:
+```typescript
+const testCase = await Zephyr.TestCase.getTestCase(
+  { testCaseKey: 'PROJ-T1' },
+  {
+    handleHttp404Error: () => ({ type: 'return', value: null })
+  }
+);
+
+if (!testCase) {
+  // Handle missing test case
+}
+```
+
+### 8. Verbose Logging for Debugging
+
+Enable verbose logging in production for better error diagnostics:
+```typescript
+const Zephyr = createZephyrApi(ZephyrApiConnection, true);
+```
+
+### 9. Type Safety
+
+Always use TypeScript types:
+```typescript
+import type { TestCase, TestExecution } from '@rbaileysr/zephyr-managed-api';
+
+const testCase: TestCase = await Zephyr.TestCase.getTestCase({
+  testCaseKey: 'PROJ-T1'
+});
+```
+
+### 10. Private API Warnings
+
+When using private API methods:
+- Document why private API is needed
+- Be prepared for breaking changes
+- Test thoroughly after Zephyr updates
+- Have fallback plans if methods break
+
+---
+
+## Summary
+
+This Managed API provides comprehensive access to Zephyr Scale Cloud functionality through both public and private endpoints. Use public API methods when possible, and leverage private API methods for advanced functionality like version-specific operations, test data management, and extended data access.
+
+**Key Takeaways:**
+- Public API = Officially supported, stable, well-documented
+- Private API = Advanced features, use with caution, may break
+- Version support = Many private API methods support version parameters
+- Error handling = Comprehensive error types with automatic retry
+- Pagination = Both offset and cursor-based options available
+
+For detailed examples, see `examples.ts` in the package.
+
+---
+
+**Copyright Adaptavist 2025 (c) All rights reserved**
+