@rbaileysr/zephyr-managed-api 1.0.2 → 1.2.0

package/dist/groups/Private.d.ts

@@ -0,0 +1,256 @@
+/*!
+ * Copyright Adaptavist 2025 (c) All rights reserved
+ */
+/**
+ * Private API group
+ *
+ * ⚠️ WARNING: These functions use Zephyr's private/unofficial API endpoints.
+ *
+ * These endpoints 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 functions at your own risk. They may break with future Zephyr updates.
+ */
+import type { CreatePrivateCustomFieldRequest, PrivateCustomFieldCategory, CreateTestCaseVersionRequest, CreateTestCaseVersionResponse, CreateAttachmentRequest, CreateTestCaseCommentRequest, CreateTestCaseCommentResponse, GetTestCaseAttachmentsRequest, GetTestCaseAttachmentsResponse, DownloadAttachmentRequest } from '../types';
+import type { ZephyrApiConnection } from '../index';
+/**
+ * Private API group for accessing Zephyr's private/unofficial endpoints
+ *
+ * ⚠️ WARNING: These methods use private APIs that are not officially supported.
+ * They may change or break at any time without notice.
+ */
+export declare class PrivateGroup {
+    /**
+     * Base URL for Zephyr private API endpoints
+     */
+    private readonly privateApiBaseUrl;
+    /**
+     * Optional API connection for accessing public API (e.g., to look up test case IDs from keys)
+     */
+    private readonly apiConnection?;
+    private readonly testCaseGroup?;
+    constructor(apiConnection?: ZephyrApiConnection);
+    /**
+     * Get Jira Context JWT token
+     *
+     * Retrieves a short-lived JWT token (15 minutes) from Jira that is required
+     * for private Zephyr API endpoints. This token may need to be refreshed
+     * during long operations.
+     *
+     * ⚠️ WARNING: This uses a private Jira endpoint and may change without notice.
+     *
+     * @param userEmail - Jira user email address
+     * @param apiToken - Jira API token
+     * @param jiraInstanceUrl - Full Jira instance URL (e.g., 'https://your-instance.atlassian.net')
+     * @returns The Context JWT token string
+     * @throws {UnauthorizedError} If authentication fails
+     * @throws {UnexpectedError} If the JWT cannot be extracted from the response
+     */
+    getContextJwt(userEmail: string, apiToken: string, jiraInstanceUrl: string): Promise<string>;
+    /**
+     * Create a custom field using private API
+     *
+     * Creates a custom field for the specified entity type (test case, test plan, test run, or test step).
+     *
+     * ⚠️ WARNING: This uses a private Zephyr API endpoint that is not officially supported.
+     * The endpoint may change or be removed at any time without notice.
+     *
+     * @param userEmail - Jira user email address
+     * @param apiToken - Jira API token
+     * @param jiraInstanceUrl - Full Jira instance URL (e.g., 'https://your-instance.atlassian.net')
+     * @param category - Entity type for the custom field (TEST_CASE, TEST_PLAN, TEST_RUN, or TEST_STEP)
+     * @param request - Custom field creation request
+     * @returns The created custom field response
+     * @throws {BadRequestError} If the request is invalid
+     * @throws {UnauthorizedError} If authentication fails
+     * @throws {ForbiddenError} If the user doesn't have permission
+     * @throws {ServerError} If the server returns an error
+     */
+    createCustomField(userEmail: string, apiToken: string, jiraInstanceUrl: string, category: PrivateCustomFieldCategory, request: CreatePrivateCustomFieldRequest): Promise<unknown>;
+    /**
+     * Create a new test case version using private API
+     *
+     * Creates a new version of an existing test case. Note that when a new version
+     * is created, the testCaseId changes for that test case.
+     *
+     * ⚠️ WARNING: This uses a private Zephyr API endpoint that is not officially supported.
+     * The endpoint may change or be removed at any time without notice.
+     *
+     * @param userEmail - Jira user email address
+     * @param apiToken - Jira API token
+     * @param jiraInstanceUrl - Full Jira instance URL (e.g., 'https://your-instance.atlassian.net')
+     * @param request - Test case version creation request
+     * @param request.testCaseKey - Test case key (e.g., 'PROJ-T1'). The numeric ID will be looked up automatically if Zephyr Connector is available.
+     * @param request.projectId - Jira project ID (numeric, not the project key)
+     * @returns The created version response with id and key
+     * @throws {BadRequestError} If the request is invalid
+     * @throws {UnauthorizedError} If authentication fails
+     * @throws {ForbiddenError} If the user doesn't have permission
+     * @throws {NotFoundError} If the test case is not found
+     * @throws {ServerError} If the server returns an error (including 409 Conflict if version already exists)
+     * @throws {UnexpectedError} If test case ID cannot be looked up from key and Zephyr Connector is not available
+     */
+    createTestCaseVersion(userEmail: string, apiToken: string, jiraInstanceUrl: string, request: CreateTestCaseVersionRequest): Promise<CreateTestCaseVersionResponse>;
+    /**
+     * Get upload details for attachment upload
+     *
+     * Retrieves S3 upload credentials and configuration needed to upload an attachment.
+     *
+     * ⚠️ WARNING: This uses a private Zephyr API endpoint that is not officially supported.
+     * The endpoint may change or be removed at any time without notice.
+     *
+     * @param contextJwt - Jira Context JWT token
+     * @returns Upload details including S3 bucket URL, credentials, and policy
+     * @throws {UnauthorizedError} If authentication fails
+     * @throws {ServerError} If the server returns an error
+     */
+    private getUploadDetails;
+    /**
+     * Upload file to S3
+     *
+     * Uploads a file to S3 using the credentials from upload details.
+     *
+     * @param upload - Upload details from getUploadDetails
+     * @param projectId - Jira project ID
+     * @param testCaseId - Numeric test case ID
+     * @param userAccountId - Atlassian account ID
+     * @param file - File to upload (Blob or ArrayBuffer)
+     * @param fileName - Name of the file
+     * @returns S3 upload information
+     * @throws {UnexpectedError} If upload fails
+     */
+    private uploadToS3;
+    /**
+     * Save attachment metadata
+     *
+     * Saves metadata for an uploaded attachment.
+     *
+     * @param contextJwt - Jira Context JWT token
+     * @param projectId - Jira project ID
+     * @param testCaseId - Numeric test case ID
+     * @param userAccountId - Atlassian account ID
+     * @param s3Key - S3 key from upload
+     * @param fileName - File name
+     * @param mimeType - MIME type
+     * @param fileSize - File size in bytes
+     * @returns Attachment metadata response
+     * @throws {BadRequestError} If the request is invalid
+     * @throws {UnauthorizedError} If authentication fails
+     * @throws {ServerError} If the server returns an error
+     */
+    private saveAttachmentMetadata;
+    /**
+     * Create a comment on a test case using private API
+     *
+     * Adds a comment to an existing test case. The comment will be associated with
+     * the specified user account ID.
+     *
+     * ⚠️ WARNING: This uses a private Zephyr API endpoint that is not officially supported.
+     * The endpoint may change or be removed at any time without notice.
+     *
+     * @param userEmail - Jira user email address
+     * @param apiToken - Jira API token
+     * @param jiraInstanceUrl - Full Jira instance URL (e.g., 'https://your-instance.atlassian.net')
+     * @param request - Comment creation request
+     * @param request.testCaseKey - Test case key (e.g., 'PROJ-T1'). The numeric ID will be looked up automatically if Zephyr Connector is available.
+     * @param request.projectId - Jira project ID (numeric, not the project key)
+     * @param request.body - Comment text/body
+     * @param request.createdBy - Atlassian account ID of the user creating the comment (e.g., '5d6fdc98dc6e480dbc021aae')
+     * @returns Comment creation response
+     * @throws {BadRequestError} If the request is invalid
+     * @throws {UnauthorizedError} If authentication fails
+     * @throws {ForbiddenError} If the user doesn't have permission
+     * @throws {NotFoundError} If the test case is not found
+     * @throws {ServerError} If the server returns an error
+     * @throws {UnexpectedError} If test case ID cannot be looked up from key and Zephyr Connector is not available
+     */
+    createTestCaseComment(userEmail: string, apiToken: string, jiraInstanceUrl: string, request: CreateTestCaseCommentRequest): Promise<CreateTestCaseCommentResponse>;
+    /**
+     * Get attachments for a test case using private API
+     *
+     * Retrieves all attachment details for a test case, including signed S3 URLs
+     * for downloading the attachments.
+     *
+     * ⚠️ WARNING: This uses a private Zephyr API endpoint that is not officially supported.
+     * The endpoint may change or be removed at any time without notice.
+     *
+     * @param userEmail - Jira user email address
+     * @param apiToken - Jira API token
+     * @param jiraInstanceUrl - Full Jira instance URL (e.g., 'https://your-instance.atlassian.net')
+     * @param request - Get attachments request
+     * @param request.testCaseKey - Test case key (e.g., 'PROJ-T1'). The numeric ID will be looked up automatically if Zephyr Connector is available.
+     * @param request.projectId - Jira project ID (numeric, not the project key)
+     * @returns Test case attachments response with array of attachment details
+     * @throws {BadRequestError} If the request is invalid
+     * @throws {UnauthorizedError} If authentication fails
+     * @throws {ForbiddenError} If the user doesn't have permission
+     * @throws {NotFoundError} If the test case is not found
+     * @throws {ServerError} If the server returns an error
+     * @throws {UnexpectedError} If test case ID cannot be looked up from key and Zephyr Connector is not available
+     */
+    getTestCaseAttachments(userEmail: string, apiToken: string, jiraInstanceUrl: string, request: GetTestCaseAttachmentsRequest): Promise<GetTestCaseAttachmentsResponse>;
+    /**
+     * Download an attachment from a test case using private API
+     *
+     * Downloads an attachment file into memory. This method:
+     * 1. Gets fresh attachment details (including a fresh signed S3 URL)
+     * 2. Downloads the file from the signed URL
+     * 3. Returns the file as a Blob
+     *
+     * ⚠️ WARNING: This uses private Zephyr API endpoints that are not officially supported.
+     * The endpoints may change or be removed at any time without notice.
+     *
+     * @param userEmail - Jira user email address
+     * @param apiToken - Jira API token
+     * @param jiraInstanceUrl - Full Jira instance URL (e.g., 'https://your-instance.atlassian.net')
+     * @param request - Download attachment request
+     * @param request.testCaseKey - Test case key (e.g., 'PROJ-T1'). The numeric ID will be looked up automatically if Zephyr Connector is available.
+     * @param request.projectId - Jira project ID (numeric, not the project key)
+     * @param request.attachmentId - Attachment ID (UUID string, e.g., 'c3f14125-638f-47f9-9211-12a9777c09e7')
+     * @returns Blob containing the attachment file data
+     * @throws {BadRequestError} If the request is invalid
+     * @throws {UnauthorizedError} If authentication fails
+     * @throws {ForbiddenError} If the user doesn't have permission
+     * @throws {NotFoundError} If the test case or attachment is not found
+     * @throws {ServerError} If the server returns an error
+     * @throws {UnexpectedError} If test case ID cannot be looked up from key and Zephyr Connector is not available, or if download fails
+     */
+    downloadAttachment(userEmail: string, apiToken: string, jiraInstanceUrl: string, request: DownloadAttachmentRequest): Promise<Blob>;
+    /**
+     * Get MIME type from file name
+     */
+    private getMimeType;
+    /**
+     * Create an attachment for a test case using private API
+     *
+     * Uploads a file attachment to a test case. This involves:
+     * 1. Getting upload details (S3 credentials)
+     * 2. Uploading the file to S3
+     * 3. Saving attachment metadata
+     *
+     * ⚠️ WARNING: This uses private Zephyr API endpoints that are not officially supported.
+     * The endpoints may change or be removed at any time without notice.
+     *
+     * @param userEmail - Jira user email address
+     * @param apiToken - Jira API token
+     * @param jiraInstanceUrl - Full Jira instance URL (e.g., 'https://your-instance.atlassian.net')
+     * @param request - Attachment creation request
+     * @param request.testCaseKey - Test case key (e.g., 'PROJ-T1'). The numeric ID will be looked up automatically if Zephyr Connector is available.
+     * @param request.projectId - Jira project ID (numeric, not the project key)
+     * @param request.file - File to upload (Blob or ArrayBuffer)
+     * @param request.fileName - Name of the file
+     * @param request.userAccountId - Atlassian account ID (e.g., '5d6fdc98dc6e480dbc021aae')
+     * @returns Attachment metadata response
+     * @throws {BadRequestError} If the request is invalid
+     * @throws {UnauthorizedError} If authentication fails
+     * @throws {ForbiddenError} If the user doesn't have permission
+     * @throws {NotFoundError} If the test case is not found
+     * @throws {ServerError} If the server returns an error
+     * @throws {UnexpectedError} If test case ID cannot be looked up from key and Zephyr Connector is not available
+     */
+    createAttachment(userEmail: string, apiToken: string, jiraInstanceUrl: string, request: CreateAttachmentRequest): Promise<unknown>;
+}
+//# sourceMappingURL=Private.d.ts.map

package/dist/groups/Private.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Private.d.ts","sourceRoot":"","sources":["../../groups/Private.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACX,+BAA+B,EAC/B,0BAA0B,EAC1B,4BAA4B,EAC5B,6BAA6B,EAG7B,uBAAuB,EACvB,4BAA4B,EAC5B,6BAA6B,EAC7B,6BAA6B,EAC7B,8BAA8B,EAE9B,yBAAyB,EACzB,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAWpD;;;;;GAKG;AACH,qBAAa,YAAY;IACxB;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA2D;IAE7F;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAsB;IACrD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAgB;gBAEnC,aAAa,CAAC,EAAE,mBAAmB;IAO/C;;;;;;;;;;;;;;;OAeG;IACG,aAAa,CAClB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,GACrB,OAAO,CAAC,MAAM,CAAC;IAuElB;;;;;;;;;;;;;;;;;;OAkBG;IACG,iBAAiB,CACtB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,EACvB,QAAQ,EAAE,0BAA0B,EACpC,OAAO,EAAE,+BAA+B,GACtC,OAAO,CAAC,OAAO,CAAC;IA8DnB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,qBAAqB,CAC1B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,EACvB,OAAO,EAAE,4BAA4B,GACnC,OAAO,CAAC,6BAA6B,CAAC;IAsFzC;;;;;;;;;;;;OAYG;YACW,gBAAgB;IAiC9B;;;;;;;;;;;;;OAaG;YACW,UAAU;IAsExB;;;;;;;;;;;;;;;;;OAiBG;YACW,sBAAsB;IAgEpC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,qBAAqB,CAC1B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,EACvB,OAAO,EAAE,4BAA4B,GACnC,OAAO,CAAC,6BAA6B,CAAC;IAoFzC;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,sBAAsB,CAC3B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,EACvB,OAAO,EAAE,6BAA6B,GACpC,OAAO,CAAC,8BAA8B,CAAC;IA8E1C;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACG,kBAAkB,CACvB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,EACvB,OAAO,EAAE,yBAAyB,GAChC,OAAO,CAAC,IAAI,CAAC;IAwDhB;;OAEG;IACH,OAAO,CAAC,WAAW;IAkBnB;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACG,gBAAgB,CACrB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,EACvB,OAAO,EAAE,uBAAuB,GAC9B,OAAO,CAAC,OAAO,CAAC;CAqDnB"}