@rbaileysr/zephyr-managed-api 1.0.0

package/dist/utils.js

@@ -0,0 +1,432 @@
+/**
+ * Utility functions for Zephyr API operations
+ */
+// Define error classes that match Commons Core error types
+// These work in both ScriptRunner Connect runtime (where Commons Core is available)
+// and local Node.js environments (where we provide fallback implementations)
+class BaseHttpError extends Error {
+    constructor(message, status, statusText, response) {
+        super(message);
+        this.status = status;
+        this.statusText = statusText;
+        this.response = response;
+        this.name = this.constructor.name;
+        Object.setPrototypeOf(this, BaseHttpError.prototype);
+    }
+}
+class ZephyrBadRequestError extends BaseHttpError {
+    constructor(message, statusText, response) {
+        super(message, 400, statusText || 'Bad Request', response);
+        Object.setPrototypeOf(this, ZephyrBadRequestError.prototype);
+    }
+}
+class ZephyrUnauthorizedError extends BaseHttpError {
+    constructor(message, statusText, response) {
+        super(message, 401, statusText || 'Unauthorized', response);
+        Object.setPrototypeOf(this, ZephyrUnauthorizedError.prototype);
+    }
+}
+class ZephyrForbiddenError extends BaseHttpError {
+    constructor(message, statusText, response) {
+        super(message, 403, statusText || 'Forbidden', response);
+        Object.setPrototypeOf(this, ZephyrForbiddenError.prototype);
+    }
+}
+class ZephyrNotFoundError extends BaseHttpError {
+    constructor(message, statusText, response) {
+        super(message, 404, statusText || 'Not Found', response);
+        Object.setPrototypeOf(this, ZephyrNotFoundError.prototype);
+    }
+}
+class ZephyrTooManyRequestsError extends BaseHttpError {
+    constructor(message, statusText, response) {
+        super(message, 429, statusText || 'Too Many Requests', response);
+        Object.setPrototypeOf(this, ZephyrTooManyRequestsError.prototype);
+    }
+}
+class ZephyrServerError extends BaseHttpError {
+    constructor(message, status, statusText, response) {
+        super(message, status, statusText || 'Server Error', response);
+        Object.setPrototypeOf(this, ZephyrServerError.prototype);
+    }
+}
+class ZephyrUnexpectedError extends Error {
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'UnexpectedError';
+        Object.setPrototypeOf(this, ZephyrUnexpectedError.prototype);
+    }
+}
+// Export error classes that are compatible with Commons Core
+// In ScriptRunner Connect runtime, these will be compatible with Commons Core types
+// In local Node.js, these are our implementations
+// These can be used with instanceof checks and provide the same API as Commons Core errors
+export const HttpError = BaseHttpError;
+export const BadRequestError = ZephyrBadRequestError;
+export const UnauthorizedError = ZephyrUnauthorizedError;
+export const ForbiddenError = ZephyrForbiddenError;
+export const NotFoundError = ZephyrNotFoundError;
+export const TooManyRequestsError = ZephyrTooManyRequestsError;
+export const ServerError = ZephyrServerError;
+export const UnexpectedError = ZephyrUnexpectedError;
+/**
+ * Default retry configuration for rate limiting
+ */
+const DEFAULT_RETRY_CONFIG = {
+    maxRetries: 5,
+    initialDelay: 1000, // 1 second
+    maxDelay: 60000, // 60 seconds
+    backoffMultiplier: 2,
+};
+/**
+ * Calculate delay for exponential backoff
+ */
+function calculateDelay(retryCount, config) {
+    const delay = config.initialDelay * Math.pow(config.backoffMultiplier, retryCount);
+    return Math.min(delay, config.maxDelay);
+}
+/**
+ * Sleep utility for retry delays
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Extract retry-after value from response headers
+ * Returns delay in milliseconds, or null if not present
+ */
+function getRetryAfter(response) {
+    const retryAfter = response.headers.get('Retry-After');
+    if (!retryAfter) {
+        return null;
+    }
+    // Retry-After can be either seconds (number) or HTTP date
+    const seconds = parseInt(retryAfter, 10);
+    if (!isNaN(seconds)) {
+        return seconds * 1000; // Convert to milliseconds
+    }
+    // Try parsing as HTTP date
+    const date = new Date(retryAfter);
+    if (!isNaN(date.getTime())) {
+        const delay = date.getTime() - Date.now();
+        return delay > 0 ? delay : null;
+    }
+    return null;
+}
+/**
+ * Check if an error response indicates "Unknown object" (resource doesn't exist)
+ * This is used for idempotent delete operations
+ */
+export async function isUnknownObjectError(response) {
+    if (response.ok) {
+        return false;
+    }
+    // Check status code first (404 is always "not found")
+    if (response.status === 404) {
+        return true;
+    }
+    // Check error message for "Unknown object" pattern
+    try {
+        const errorData = (await response.json());
+        if (errorData.message) {
+            const errorMessage = errorData.message.toLowerCase();
+            // APIs return errors like "resource: Unknown object: 123456" or "resource: Not a recognized ID"
+            if (errorMessage.includes('unknown object') ||
+                errorMessage.includes('not a recognized id') ||
+                errorMessage.includes('does not exist') ||
+                errorMessage.includes('not found')) {
+                return true;
+            }
+        }
+    }
+    catch {
+        // If JSON parsing fails, check status code only
+        return response.status === 404;
+    }
+    return false;
+}
+/**
+ * Build query string from options
+ * Zephyr API uses different parameter names than Asana (projectKey, folderId, maxResults, startAt, etc.)
+ */
+export function buildQueryString(options) {
+    if (!options) {
+        return '';
+    }
+    const params = [];
+    // Pagination parameters (offset-based)
+    if (options.maxResults !== undefined) {
+        params.push(`maxResults=${options.maxResults}`);
+    }
+    if (options.startAt !== undefined) {
+        params.push(`startAt=${options.startAt}`);
+    }
+    // Pagination parameters (cursor-based)
+    if (options.limit !== undefined) {
+        params.push(`limit=${options.limit}`);
+    }
+    if (options.startAtId !== undefined) {
+        params.push(`startAtId=${options.startAtId}`);
+    }
+    // Add any other query parameters (filters, etc.)
+    for (const [key, value] of Object.entries(options)) {
+        if (value !== undefined &&
+            value !== null &&
+            key !== 'maxResults' &&
+            key !== 'startAt' &&
+            key !== 'limit' &&
+            key !== 'startAtId') {
+            // Convert camelCase to query parameter format if needed
+            // Zephyr API uses camelCase in query params (projectKey, folderId, etc.)
+            params.push(`${key}=${encodeURIComponent(String(value))}`);
+        }
+    }
+    return params.length > 0 ? `?${params.join('&')}` : '';
+}
+/**
+ * Parse API response with error handling
+ * Zephyr API returns objects directly (not wrapped in { data: ... })
+ * Throws appropriate Commons Core error types
+ */
+export async function parseResponse(response) {
+    if (!response.ok) {
+        let errorMessage = `HTTP ${response.status}: ${response.statusText}`;
+        let errorData = null;
+        try {
+            errorData = await response.json();
+            const error = errorData;
+            if (error.message) {
+                errorMessage = error.message;
+            }
+        }
+        catch {
+            // If JSON parsing fails, use the status text
+        }
+        // Throw appropriate error type based on status code
+        switch (response.status) {
+            case 400:
+                throw new BadRequestError(errorMessage, response.statusText, errorData);
+            case 401:
+                throw new UnauthorizedError(errorMessage, response.statusText, errorData);
+            case 403:
+                throw new ForbiddenError(errorMessage, response.statusText, errorData);
+            case 404:
+                throw new NotFoundError(errorMessage, response.statusText, errorData);
+            case 429:
+                throw new TooManyRequestsError(errorMessage, response.statusText, errorData);
+            default:
+                if (response.status >= 500) {
+                    throw new ServerError(errorMessage, response.status, response.statusText, errorData);
+                }
+                throw new HttpError(errorMessage, response.status, response.statusText, errorData);
+        }
+    }
+    // Handle empty responses (204 No Content, etc.)
+    const contentType = response.headers.get('content-type') || '';
+    const contentLength = response.headers.get('content-length');
+    // If no content or content-length is 0, return empty object or null based on type
+    if (contentLength === '0' || (!contentType.includes('application/json') && !contentType.includes('text/json'))) {
+        // For void return types, return undefined cast as T
+        // For Link types, try to construct from headers or return minimal object
+        return {};
+    }
+    try {
+        const data = (await response.json());
+        return data;
+    }
+    catch (error) {
+        // If JSON parsing fails but response is OK, return empty object
+        if (response.ok) {
+            return {};
+        }
+        throw error;
+    }
+}
+/**
+ * Execute an API call with automatic retry on rate limiting (429)
+ * Uses exponential backoff with configurable retry settings
+ * Respects Retry-After header when present
+ * Supports optional error strategy for custom error handling
+ */
+export async function executeWithRetry(apiCall, config = {}, errorStrategy) {
+    const retryConfig = {
+        ...DEFAULT_RETRY_CONFIG,
+        ...config,
+    };
+    let lastError;
+    let retryCount = 0;
+    while (retryCount <= retryConfig.maxRetries) {
+        try {
+            const response = await apiCall();
+            // If successful, parse and return
+            if (response.ok) {
+                return (await response.json());
+            }
+            // If rate limited (429), retry with backoff
+            if (response.status === 429) {
+                // Check for Retry-After header (takes precedence)
+                const retryAfter = getRetryAfter(response);
+                const delay = retryAfter ?? calculateDelay(retryCount, retryConfig);
+                if (retryCount < retryConfig.maxRetries) {
+                    retryCount++;
+                    await sleep(delay);
+                    continue; // Retry the request
+                }
+                // Max retries exceeded, parse error and throw
+                let errorMessage = `Rate limit exceeded after ${retryCount} retries`;
+                let errorData = null;
+                try {
+                    errorData = await response.json();
+                    const error = errorData;
+                    if (error.message) {
+                        errorMessage = error.message;
+                    }
+                }
+                catch {
+                    // If JSON parsing fails, use default message
+                }
+                throw new TooManyRequestsError(errorMessage, response.statusText, errorData);
+            }
+            // For other errors, check error strategy first
+            if (errorStrategy) {
+                const { applyErrorStrategy } = await import('./error-strategy');
+                const action = await applyErrorStrategy(response, errorStrategy, retryCount);
+                if (action.type === 'retry') {
+                    retryCount++;
+                    await sleep(action.delay);
+                    continue; // Retry the request
+                }
+                else if (action.type === 'return') {
+                    return action.value;
+                }
+                // Otherwise, continue propagation (fall through to parseResponse)
+            }
+            // For other errors, parse and throw immediately
+            await parseResponse(response);
+        }
+        catch (error) {
+            lastError = error;
+            // If it's a TooManyRequestsError and we haven't exceeded max retries, retry
+            if (error instanceof TooManyRequestsError && retryCount < retryConfig.maxRetries) {
+                // Check error strategy for 429 handling
+                if (errorStrategy?.handleHttp429Error) {
+                    const { applyErrorStrategy } = await import('./error-strategy');
+                    // Create a mock response for error strategy
+                    const mockResponse = {
+                        ok: false,
+                        status: 429,
+                        statusText: 'Too Many Requests',
+                        json: async () => error.response || null,
+                        headers: { get: () => null },
+                    };
+                    const action = await applyErrorStrategy(mockResponse, errorStrategy, retryCount);
+                    if (action.type === 'retry') {
+                        retryCount++;
+                        await sleep(action.delay);
+                        continue; // Retry the request
+                    }
+                    else if (action.type === 'return') {
+                        return action.value;
+                    }
+                }
+                // Default retry behavior
+                const delay = calculateDelay(retryCount, retryConfig);
+                retryCount++;
+                await sleep(delay);
+                continue; // Retry the request
+            }
+            // For other errors or max retries exceeded, throw immediately
+            throw error;
+        }
+    }
+    // This should never be reached, but TypeScript needs it
+    throw lastError || new UnexpectedError('Unexpected error in retry logic');
+}
+/**
+ * Build request body for Zephyr API
+ * Zephyr API expects JSON objects directly (not wrapped in { data: ... })
+ */
+export function buildRequestBody(data) {
+    return JSON.stringify(data);
+}
+/**
+ * Get all pages from a paginated endpoint (offset-based)
+ * Automatically fetches all pages until no more results are available
+ *
+ * @param apiCall - Function that makes the API call with startAt and maxResults
+ * @param options - Optional pagination options
+ * @returns Array of all items from all pages
+ *
+ * @example
+ * ```typescript
+ * import { getAllPages } from './zephyr/utils';
+ *
+ * const allTestCases = await getAllPages(
+ *   (startAt, maxResults) => Zephyr.TestCase.listTestCases({
+ *     projectKey: 'PROJ',
+ *     startAt,
+ *     maxResults
+ *   }),
+ *   { maxResults: 50 }
+ * );
+ * ```
+ */
+export async function getAllPages(apiCall, options) {
+    const maxResults = options?.maxResults ?? 50;
+    let startAt = options?.startAt ?? 0;
+    const allItems = [];
+    while (true) {
+        const page = await apiCall(startAt, maxResults);
+        if (page.values) {
+            allItems.push(...page.values);
+        }
+        // Check if this is the last page
+        if (page.isLast || !page.values || page.values.length === 0) {
+            break;
+        }
+        // Move to next page
+        startAt = page.startAt + page.maxResults;
+    }
+    return allItems;
+}
+/**
+ * Get all pages from a cursor-paginated endpoint
+ * Automatically fetches all pages until no more results are available
+ *
+ * @param apiCall - Function that makes the API call with startAtId and limit
+ * @param options - Optional pagination options
+ * @returns Array of all items from all pages
+ *
+ * @example
+ * ```typescript
+ * import { getAllPagesCursor } from './zephyr/utils';
+ *
+ * const allTestCases = await getAllPagesCursor(
+ *   (startAtId, limit) => Zephyr.TestCase.listTestCasesCursorPaginated({
+ *     projectKey: 'PROJ',
+ *     startAtId,
+ *     limit
+ *   }),
+ *   { limit: 100 }
+ * );
+ * ```
+ */
+export async function getAllPagesCursor(apiCall, options) {
+    const limit = options?.limit ?? 100;
+    let startAtId = options?.startAtId ?? null;
+    const allItems = [];
+    while (true) {
+        const page = await apiCall(startAtId, limit);
+        if (page.values) {
+            allItems.push(...page.values);
+        }
+        // Check if there's a next page
+        if (page.nextStartAtId === null || !page.values || page.values.length === 0) {
+            break;
+        }
+        // Move to next page
+        startAtId = page.nextStartAtId;
+    }
+    return allItems;
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@rbaileysr/zephyr-managed-api",
+  "version": "1.0.0",
+  "description": "Managed API wrapper for Zephyr Cloud REST API v2 - Comprehensive type-safe access to all Zephyr API endpoints for ScriptRunner Connect",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "zephyr",
+    "zephyr-scale",
+    "zephyr-cloud",
+    "test-management",
+    "api",
+    "managed-api",
+    "scriptrunner-connect",
+    "typescript",
+    "rest-api"
+  ],
+  "author": "rbailey@adaptavist.com",
+  "license": "MIT",
+  "dependencies": {},
+  "peerDependencies": {
+    "@managed-api/commons-core": "*"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rbaileysr/zephyr-managed-api.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rbaileysr/zephyr-managed-api/issues"
+  },
+  "homepage": "https://github.com/rbaileysr/zephyr-managed-api#readme"
+}
+