@qawolf/ci-sdk 0.23.0 → 0.23.1

package/dist/index.d.ts

@@ -0,0 +1,561 @@
+import { LogDriver } from '@qawolf/ci-utils';
+export { LogDriver } from '@qawolf/ci-utils';
+
+type ApiConfig = {
+    apiKey: string;
+    serviceBase: string;
+    userAgent: string;
+};
+
+type FetchDriver = typeof fetch;
+type SdkDependencies = {
+    fetch: FetchDriver;
+    log: LogDriver;
+};
+
+type CiGreenlightBugDetails = {
+    /**
+     * The URL of this BR in the QAWolf application.
+     */
+    applicationUrl: string;
+    /**
+     * If this bug report is linked to an external issue, it will
+     * show up here.
+     */
+    externalIssue: {
+        /**
+         * The URL of the external issue in the external platform
+         * application.
+         */
+        applicationUrl: string;
+        /**
+         * The ID of this issue in the external platform.
+         */
+        externalIssueId: string;
+        /**
+         * Lowercase platform name (e.g. "jira").
+         */
+        platform: string;
+    } | undefined;
+    /**
+     * True if the bug is blocking.
+     */
+    isBlocking: boolean;
+    /**
+     * True if the bug has been found in this run.
+     */
+    isNew: boolean;
+    /**
+     * The name of this bug.
+     */
+    name: string;
+    /**
+     * The bug number.
+     */
+    number: number;
+    /**
+     * The priority of this bug.
+     */
+    priority: "medium" | "unprioritized" | "low" | "high" | "urgent";
+};
+type CiGreenlightBugData = {
+    /**
+     * The count of blocking bugs reproduced in the run.
+     */
+    blockingBugsCount: number;
+    /**
+     * The URLs of the blocking bugs.
+     *
+     * @deprecated This field will be removed in the next major version.
+     * Prefer using `reproducedBugs` filtered by `isBlocking: true`, reading
+     * the `applicationUrl` field.
+     */
+    blockingBugUrls: string[];
+    /**
+     * The count of non-blocking bugs reproduced in the run.
+     */
+    nonBlockingBugsCount: number;
+    /**
+     * The URLs of the non-blocking bugs.
+     *
+     * @deprecated This field will be removed in the next major version.
+     * Prefer using `reproducedBugs` filtered by `isBlocking: false`, reading
+     * the `applicationUrl` field.
+     */
+    nonBlockingBugUrls: string[];
+    /**
+     * Blocking bugs that were not reproduced in this run, but are still
+     * opened in the run environment. This may happen when the run only covers a
+     * subset of the workflows in environment.
+     */
+    otherBlockingBugsInEnvironment: CiGreenlightBugDetails[];
+    /**
+     * Bugs that were reproduced in this run. This includes newly found bugs.
+     */
+    reproducedBugs: CiGreenlightBugDetails[];
+};
+type CiGreenlightStatusBase = {
+    relevantRunId: string;
+    relevantRunUrl: string;
+    relevantRunWithBugsUrl: string;
+    rootRunId: string;
+    rootRunUrl: string;
+    workflowsDisabledAfterRunCount: number;
+    workflowsInRunCount: number;
+    workflowsUnderInvestigationCount: number;
+};
+/**
+ * The status of a CI greenlight run. See the API documentation here for
+ * more details: https://qawolf.notion.site/1b170576efea411fa785842a71e7c99e
+ */
+type CiGreenlightStatus = CiGreenlightStatusBase & (({
+    greenlight: boolean;
+    runStage: "completed";
+} & CiGreenlightBugData) | ({
+    greenlight: false;
+    runStage: "underReview";
+} & CiGreenlightBugData) | {
+    greenlight: false;
+    runStage: "initializing" | "underReview" | "canceled";
+});
+
+type GenerateSignedUrlStatus = {
+    fileLocation?: string;
+    playgroundFileLocation?: string;
+    success: true;
+    uploadUrl?: string;
+} | {
+    abortReason: GenerateSignedUrlAbortReason$1;
+    httpStatus?: number;
+    success: false;
+};
+type GenerateSignedUrlAbortReason$1 = "client-network-error" | "sdk-argument-validation-failed" | "400-invalid-request" | "401-invalid-credentials" | "403-forbidden" | "5XX-server-error" | "XXX-other-http-code";
+type GenerateSignedUrlConfig = {
+    destinationFilePath: string;
+};
+type GenerateSignedUrlResponse = {
+    errorMessage?: string;
+    fileLocation?: string;
+    httpStatus: number;
+    playgroundFileLocation?: string;
+    signedUrl?: string;
+    success: boolean;
+};
+
+/**
+ * Refer to our official documentation for more information:
+ * https://qawolf.notion.site/dd72e46ceb7f451dae4e9ef06f64a2cc
+ */
+type BaseDeployConfig = {
+    branch: string | undefined;
+    commitUrl: string | undefined;
+    deduplicationKey: string | undefined;
+    deploymentType: string | undefined;
+    deploymentUrl: string | undefined;
+    sha: string | undefined;
+    variables: Record<string, string> | undefined;
+};
+type GitHubDeployConfig = BaseDeployConfig & {
+    hostingService: "GitHub" | undefined;
+    pullRequestNumber: number | undefined;
+    repository: {
+        name: string;
+        owner: string;
+    } | undefined;
+};
+type GitLabDeployConfig = BaseDeployConfig & {
+    hostingService: "GitLab" | undefined;
+    mergeRequestNumber: number | undefined;
+    repository: {
+        name: string;
+        namespace: string;
+    } | undefined;
+};
+type DeployConfig = GitHubDeployConfig | GitLabDeployConfig;
+type DeploySuccessSuiteCreatedResult = {
+    created_suite_id: string;
+    trigger_id: string;
+};
+type DeploySuccessSuiteCreationFailureResult = {
+    failure_reason: string;
+    trigger_id: string;
+};
+type DeploySuccessSuiteAlreadyExistsResult = {
+    duplicate_suite_id: string;
+    skip_reason: string;
+    trigger_id: string;
+};
+type DeploySuccessSuiteResult = DeploySuccessSuiteCreatedResult | DeploySuccessSuiteCreationFailureResult | DeploySuccessSuiteAlreadyExistsResult;
+type DeployStatus = {
+    environment: {
+        alias?: string;
+        id: string;
+        isStatic: boolean;
+    } | undefined;
+    results: Array<DeploySuccessSuiteResult>;
+};
+type DeployStatusSuccessResponse = {
+    data: DeployStatus;
+    ok: true;
+    status: number;
+};
+type DeployStatusErrorResponse = {
+    data: undefined;
+    ok: false;
+    status: number | undefined;
+};
+type DeployStatusResponse = DeployStatusSuccessResponse | DeployStatusErrorResponse;
+type AttemptDeployFailedReason = "no-matched-trigger" | "no-environment" | "run-could-not-be-created" | "duplicate-suite";
+type AttemptDeployHttpAbortReason = "4XX-client-error" | "401-unauthorized" | "403-forbidden" | "5XX-server-error" | "network-error";
+type AttemptDeployNonHttpAbortReason = "network-error";
+type AttemptDeployAbortReason = AttemptDeployHttpAbortReason | AttemptDeployNonHttpAbortReason;
+type NotifyDeployStatus = {
+    /**
+     * Environment ID associated with the deployment.
+     */
+    environmentId: string;
+    /**
+     * Deployment notification successful.
+     */
+    outcome: "success";
+    /**
+     * Run ID might be undefined if the deployment is a preview deployment.
+     */
+    runId: string | undefined;
+} | {
+    failReason: AttemptDeployFailedReason;
+    /**
+     * A run could not be created.
+     */
+    outcome: "failed";
+} | {
+    abortReason: AttemptDeployNonHttpAbortReason;
+    httpStatus?: never;
+    /**
+     * An unrecoverable error occurred.
+     */
+    outcome: "aborted";
+} | {
+    abortReason: AttemptDeployHttpAbortReason;
+    httpStatus: number | undefined;
+    /**
+     * An unrecoverable HTTP error occurred.
+     */
+    outcome: "aborted";
+};
+
+type PollCiGreenlightPollConfig = {
+    /**
+     * If true, the job will be aborted when a superseding run is detected.
+     *
+     * @default false
+     */
+    abortOnSuperseded: boolean;
+    /**
+     * Maximum number of network operations retries before aborting the job.
+     *
+     * @default 10
+     */
+    maxRetries: number;
+    /**
+     * Timeout in milliseconds before aborting this polling operation.
+     *
+     * @default 120 minutes
+     */
+    pollTimeout: number;
+    /**
+     * Interval in milliseconds between network operations retries.
+     *
+     * @default 10 seconds
+     */
+    retryInterval: number;
+    /**
+     * Interval in milliseconds between polling for a run in progress.
+     *
+     * @default 30 seconds
+     */
+    runInProgressInterval: number;
+    /**
+     * Interval in milliseconds between polling for a run under review.
+     *
+     * @default 60 minutes
+     */
+    runUnderReviewInterval: number;
+};
+type PollCiGreenlightHttpAbortReason = "4XX-client-error" | "404-run-not-found" | "5XX-server-error" | "XXX-other-http-code";
+type PollCiGreenlightNonHttpAbortReason = "poll-timed-out" | "run-canceled" | "network-error" | "superseded-run";
+type PollCiGreenlightAbortReason = PollCiGreenlightNonHttpAbortReason | PollCiGreenlightHttpAbortReason;
+type PollCiGreenlightStatus = {
+    greenlightStatus: Extract<CiGreenlightStatus, {
+        runStage: "completed";
+    }>;
+    /**
+     * No blocking bugs were found in the run.
+     */
+    outcome: "success";
+} | {
+    greenlightStatus: Extract<CiGreenlightStatus, {
+        runStage: "completed";
+    }>;
+    /**
+     * Blocking bugs were found in the run.
+     */
+    outcome: "failed";
+} | {
+    abortReason: PollCiGreenlightHttpAbortReason;
+    httpStatus: number;
+    /**
+     * The run was aborted due to an unrecoverable error.
+     */
+    outcome: "aborted";
+} | {
+    abortReason: PollCiGreenlightNonHttpAbortReason;
+    httpStatus: undefined;
+    /**
+     * The run was aborted due to an unrecoverable error.
+     */
+    outcome: "aborted";
+};
+type PollCiGreenlightParams = {
+    /**
+     * Callback to be called when the lifecycle stage of the run changes.
+     */
+    onRunStageChanged?: (current: CiGreenlightStatus, previous: CiGreenlightStatus | undefined) => unknown | Promise<unknown>;
+    runId: string;
+} & Partial<PollCiGreenlightPollConfig>;
+declare function pollCiGreenlightStatus(deps: SdkDependencies, apiConfig: ApiConfig, { onRunStageChanged: onRunStageChanged, runId, ...pollConfig }: PollCiGreenlightParams): Promise<PollCiGreenlightStatus>;
+
+type GenerateSignedUrlAbortReason = "client-network-error" | "sdk-argument-validation-failed" | "400-invalid-request" | "401-invalid-credentials" | "403-forbidden" | "5XX-server-error" | "XXX-other-http-code";
+
+type BaseVCSBranchConfig = {
+    /**
+     * The maximum number of retries for network operations. Only recoverable
+     * errors will trigger a retry, such as network and server errors.
+     *
+     * @default 10
+     */
+    maxRetries?: number;
+};
+type EnvironmentLayout = {
+    /**
+     * Each entry of this array defines a correspondence between a QA Wolf environment
+     * and a VCS branch. Use environment aliases to refer to a particular environment.
+     * If not provided, base environment identification will be handled by the QA Wolf
+     * app.
+     */
+    baseEnvironmentsMapping?: Array<{
+        environmentAlias: string;
+        vcsBranch: string;
+    }>;
+    /**
+     * A unique alias for the environment being tested. We recommend using either
+     * `pullRequestDetailsToEnvironmentAlias` or the more generic
+     * `arbitraryStringToEnvironmentAlias` to generate this value.
+     */
+    headEnvironmentAlias: string;
+};
+type VCSLayout = {
+    /**
+     * The base VCS branch from which this
+     * branch was created.
+     */
+    baseVcsBranch: string;
+    /**
+     * The VCS branch to test.
+     */
+    headVcsBranch: string;
+};
+type PullRequestTestingLayout = EnvironmentLayout & VCSLayout;
+
+type NotifyVCSBranchMergeCanceledInput = {
+    /**
+     * A unique alias for the environment being tested. We recommend using either
+     * `pullRequestDetailsToEnvironmentAlias` or the more generic
+     * `arbitraryStringToEnvironmentAlias` to generate this value.
+     */
+    headEnvironmentAlias: string;
+} & BaseVCSBranchConfig;
+type NotifyMergeCanceledAbortReason = "forbidden" | "unauthenticated" | "network-error" | "server-error" | "invalid-input" | "head-environment-not-found" | "non-ephemeral-head-environment-violation" | "missing-vcs-branch-to-environment-alias-mapping";
+type NotifyMergeCanceledResult = {
+    outcome: "success";
+} | {
+    abortReason: NotifyMergeCanceledAbortReason;
+    eventId?: string;
+    outcome: "aborted";
+};
+
+type NotifyVCSBranchMergeCompletedInput = PullRequestTestingLayout & BaseVCSBranchConfig;
+type NotifyMergeCompletedResultAbortReason = "forbidden" | "unauthenticated" | "network-error" | "server-error" | "invalid-input" | "head-environment-not-found" | "base-environment-not-found" | "non-ephemeral-head-environment-violation" | "missing-vcs-branch-to-environment-alias-mapping";
+type NotifyMergeCompletedResult = {
+    outcome: "success";
+} | {
+    abortReason: NotifyMergeCompletedResultAbortReason;
+    eventId?: string;
+    outcome: "aborted";
+};
+
+type NotifyBuildDeployedInput = PullRequestTestingLayout & BaseVCSBranchConfig & {
+    /**
+     * A natural positive integer that defines the maximum number of concurrent
+     * workflows that can be executed for this deployment. It will default to
+     * the concurrency limit defined in the base environment.
+     *
+     * @remark `0` and `Infinity` are valid values and will disable concurrency
+     * limits.
+     */
+    concurrencyLimit?: number;
+    /**
+     * A human-friendly name for the environment that was deployed. For PR testing,
+     * we recommend using "PR #<PR_NUMBER> - <PR_NAME>".
+     */
+    headEnvironmentName: string;
+    /**
+     * Environment variables overrides for the build that was deployed.
+     * These variables are used in QA Wolf workflows, and must be communicated
+     * to provide any specific configuration for this deployment.
+     *
+     * The most common environment variable is URL, which is used to locate the
+     * deployment in E2E tests.
+     *
+     * @remark Determining which environment environment variables must be set
+     * will require assistance from a QA Wolf representative.
+     */
+    headEnvironmentVariables: Record<string, string>;
+    /**
+     * The VCS commit ID of the build that was deployed. Must be unique for this
+     * repository, and is used as a unique build identifier.
+     */
+    headVcsCommitId: string;
+    /**
+     * The VCS commit URL of the build that was deployed. When provided,
+     * it will be used in the QA Wolf UI to link to the build.
+     */
+    headVcsCommitUrl?: string;
+    /**
+     * A unique identifier for the PR/MR being tested.
+     *
+     * This field is a prerequisite for PR/MR comments feature to work,
+     * in which QA Wolf will post a comment with test results, including
+     * live updates.
+     */
+    pullOrMergeRequestNumber?: number;
+};
+type NotifyBuildDeployedAbortReason = "forbidden" | "unauthenticated" | "network-error" | "server-error" | "invalid-input" | "base-environment-not-found" | "base-trigger-not-found" | "repository-not-found" | "head-trigger-not-found" | "non-ephemeral-head-environment-violation" | "missing-vcs-branch-to-environment-alias-mapping" | "run-creation-failed";
+type NotifyBuildDeployedResult = {
+    /**
+     * When non-nil, indicates that a code hosting service installation was
+     * found and enabled. This will allow QA Wolf to interact with this service
+     * and post run status comments on PRs/MRs.
+     */
+    codeHostingServiceInstallationType: "GitHub" | "GitLab" | undefined;
+    outcome: "success";
+    runId: string;
+} | {
+    abortReason: NotifyBuildDeployedAbortReason;
+    eventId?: string;
+    outcome: "aborted";
+};
+
+/**
+ * Creates a compliant environment alias from pull request details.
+ */
+declare function pullRequestDetailsToEnvironmentAlias({ codeHostingServiceOrganization, codeHostingServiceRepositoryName, pullRequestIdentifier, }: {
+    /**
+     * The name of the Organization owning the VCS repository the current VCS
+     * branch belongs to.
+     */
+    codeHostingServiceOrganization: string;
+    /**
+     * The name of the VCS repository the current VCS branch belongs to.
+     */
+    codeHostingServiceRepositoryName: string;
+    /**
+     * A unique identifier for this PR/MR. It must be unique for the repository
+     * defined in `codeHostingServiceRepositoryName`.
+     */
+    pullRequestIdentifier: string;
+}): string;
+/**
+ * Creates a compliant environment alias from an arbitrary string.
+ */
+declare function arbitraryStringToEnvironmentAlias(arbitraryString: string): string;
+
+declare function makeVCSBranchTestingSDK({ apiKey, serviceBase, userAgent, }: {
+    apiKey: string;
+    serviceBase?: string;
+    userAgent?: string;
+}, { fetch, log, }?: Partial<SdkDependencies>): VCSBranchTestingSDK;
+type VCSBranchTestingSDK = {
+    /**
+     * Notify QA Wolf that the build has been deployed and is ready to be tested.
+     * Any ongoing run will be aborted and a new one will be started.
+     *
+     * @remarks This method will create a new Environment if none exists matching
+     * the provided environment alias.
+     */
+    notifyVCSBranchBuildDeployed(input: NotifyBuildDeployedInput): Promise<NotifyBuildDeployedResult>;
+    /**
+     * Notify QA Wolf that the VCS branch merge has been canceled, e.g. the PR/MR
+     * has been closed without merging. This will abort any ongoing run, and
+     * discard any investigation work by QA Wolf.
+     */
+    notifyVCSBranchMergeCanceled(input: NotifyVCSBranchMergeCanceledInput): Promise<NotifyMergeCanceledResult>;
+    /**
+     * Notify QA Wolf that the VCS branch merge has been completed. This will
+     * inform QA Wolf that any Workflow code change should be promoted to the
+     * base environment, as defined in the baseEnvironmentsMapping.
+     */
+    notifyVCSBranchMergeCompleted(input: NotifyVCSBranchMergeCompletedInput): Promise<NotifyMergeCompletedResult>;
+};
+
+interface TestPreviewParams {
+    baseEnvironmentId: string | undefined;
+    branch: string;
+    commitUrl: string;
+    deploymentUrl: string | undefined;
+    pr: {
+        number: number;
+        title: string;
+    } | undefined;
+    qaWolfTeamId: string;
+    repoFullName: string;
+    sha: string;
+    variables: {
+        [key: string]: string;
+    };
+}
+
+declare function attemptNotifyDeploy(deps: SdkDependencies, apiConfig: ApiConfig, config: Partial<DeployConfig>): Promise<NotifyDeployStatus>;
+
+declare function makeQaWolfSdk({ apiKey, serviceBase, userAgent, }: {
+    apiKey: string;
+    serviceBase?: string;
+    userAgent?: string;
+}, { fetch, log, }?: Partial<SdkDependencies>): {
+    attemptNotifyDeploy: (config: Partial<DeployConfig>) => Promise<NotifyDeployStatus>;
+    /**
+     * @deprecated Use `experimental_vcsBranchTesting` instead.
+     */
+    experimental_removeEnvironment: (config: {
+        branch: string;
+    }) => Promise<void>;
+    /**
+     * @deprecated Use `experimental_vcsBranchTesting` instead.
+     */
+    experimental_testPreview: (config: TestPreviewParams) => Promise<NotifyDeployStatus>;
+    experimental_vcsBranchTesting: VCSBranchTestingSDK;
+    generateSignedUrlForRunInputsExecutablesStorage: (config: GenerateSignedUrlConfig) => Promise<GenerateSignedUrlStatus>;
+    generateSignedUrlForTempTeamStorage: (config: GenerateSignedUrlConfig) => Promise<{
+        fileLocation?: string;
+        playgroundFileLocation?: string;
+        success: true;
+        uploadUrl?: string;
+    } | {
+        abortReason: GenerateSignedUrlAbortReason;
+        httpStatus?: number;
+        success: false;
+    }>;
+    pollCiGreenlightStatus: (args_0: PollCiGreenlightParams) => Promise<PollCiGreenlightStatus>;
+};
+
+export { type AttemptDeployAbortReason, type AttemptDeployFailedReason, type AttemptDeployHttpAbortReason, type AttemptDeployNonHttpAbortReason, type BaseVCSBranchConfig, type CiGreenlightStatus, type CiGreenlightStatusBase, type DeployConfig, type DeployStatus, type DeployStatusErrorResponse, type DeployStatusResponse, type DeployStatusSuccessResponse, type DeploySuccessSuiteAlreadyExistsResult, type DeploySuccessSuiteCreatedResult, type DeploySuccessSuiteCreationFailureResult, type DeploySuccessSuiteResult, type EnvironmentLayout, type FetchDriver, type GenerateSignedUrlAbortReason$1 as GenerateSignedUrlAbortReason, type GenerateSignedUrlConfig, type GenerateSignedUrlResponse, type GenerateSignedUrlStatus, type GitHubDeployConfig, type GitLabDeployConfig, type NotifyBuildDeployedInput, type NotifyBuildDeployedResult, type NotifyDeployStatus, type NotifyMergeCanceledResult, type NotifyMergeCompletedResult, type NotifyVCSBranchMergeCanceledInput, type NotifyVCSBranchMergeCompletedInput, type PollCiGreenlightAbortReason, type PollCiGreenlightHttpAbortReason, type PollCiGreenlightNonHttpAbortReason, type PollCiGreenlightParams, type PollCiGreenlightPollConfig, type PollCiGreenlightStatus, type PullRequestTestingLayout, type SdkDependencies, type VCSBranchTestingSDK, type VCSLayout, arbitraryStringToEnvironmentAlias, attemptNotifyDeploy, makeQaWolfSdk, makeVCSBranchTestingSDK, pollCiGreenlightStatus, pullRequestDetailsToEnvironmentAlias };