circle-client/dist/src/client.d.ts

A JavaScript client for CircleCI v2 API

export declare enum WorkflowStatus {
    Success = "success",
    Running = "running",
    NotRun = "not_run",
    Failed = "failed",
    Error = "error",
    Failing = "failing",
    OnHold = "on_hold",
    Canceled = "canceled",
    Unauthorized = "unauthorized"
}
export declare enum RunStatus {
    Success = "success",
    NotRun = "not_run",
    Failed = "failed",
    Canceled = "canceled",
    Unauthorized = "unauthorized"
}
export declare enum JobType {
    Build = "build",
    Approval = "approval"
}
export declare enum HTTPMethod {
    Post = "post",
    Get = "get",
    Put = "put",
    Delete = "delete"
}
export declare type Paged<T> = {
    items: T[];
    next_page_token: string | null;
};
export declare type ErrorResponse = {
    message?: string;
};
export declare type Params = {
    [value: string]: any;
};
export declare type ProjectSlug = [
    vcsSlug: 'github' | 'bitbucket',
    orgName: string,
    repoName: string
];
export declare type EnvVar = {
    name: string;
    value: string;
};
export declare type Pipeline = {
    id: string;
    errors: {
        type: 'config' | 'plan';
        message: string;
    }[];
    project_slug: string;
    updated_at?: string;
    number: number;
    state: 'created' | 'errored' | 'pending';
    created_at: string;
    trigger: {
        type: 'explicit' | 'api' | 'webhook';
        received_at: string;
        actor: {
            login: string;
            avatar_url: string;
        };
    };
    vcs?: {
        provider_name: 'Bitbucket' | 'GitHub';
        origin_repository_url: string;
        target_repository_url: string;
        revision: string;
        branch?: string;
        tag?: string;
        commit?: {
            subject: string;
            body: string;
        };
    };
};
export declare type PipelineConfig = {
    source: string;
    compiled: string;
};
export declare type Project = {
    slug: string;
    organization_name: string;
    name: string;
    vcs_info: {
        vcs_url: string;
        default_branch: string;
        provider: 'Bitbucket' | 'GitHub';
    };
};
export declare type Job = {
    canceled_by?: string;
    dependencies: string[];
    job_number?: number;
    id: string;
    started_at: string;
    name: string;
    approved_by?: string;
    project_slug: string;
    status: string;
    type: JobType;
    stopped_at?: string;
    approval_request_id?: string;
};
export declare type JobDetail = {
    web_url: string;
    project: {
        slug: string;
        name: string;
        external_url: string;
    };
    parallel_runs: {
        index: number;
        status: string;
    }[];
    started_at: string;
    latest_workflow: {
        id: string;
        name: string;
    };
    name: string;
    executor: {
        type: string;
        resource_class: string;
    };
    parallelism: number;
    status: string;
    number: number;
    pipeline: {
        id: string;
    };
    duration: number;
    created_at: string;
    messages: {
        type: string;
        message: string;
        reason?: string;
    }[];
    contexts: {
        name: string;
    }[];
    organization: {
        name: string;
    };
    queued_at: string;
    stopped_at?: string;
};
export declare type JobArtifact = {
    path: string;
    node_index: number;
    url: string;
};
export declare type JobTest = {
    message: string;
    source: string;
    run_time: number;
    file: string;
    result: string;
    name: string;
    classname: string;
};
export declare type WorkflowRun = {
    id: string;
    duration: number;
    created_at: string;
    stopped_at: string;
    credits_used: number;
    status: RunStatus;
};
export declare type JobRun = {
    id: string;
    started_at: string;
    stopped_at: string;
    status: RunStatus;
    credits_used: number;
};
export declare type Workflow = {
    pipeline_id: string;
    canceled_by?: string;
    id: string;
    name: string;
    project_slug: string;
    errored_by?: string;
    status: WorkflowStatus;
    started_by: string;
    pipeline_number: number;
    created_at: string;
    stopped_at: string;
};
export declare type SummaryMetrics = {
    name: string;
    window_start: string;
    window_end: string;
    metrics: {
        success_rate: number;
        total_runs: number;
        failed_runs: number;
        successful_runs: number;
        throughput: number;
        mttr: number;
        total_credits_used: number;
        duration_metrics: {
            min: number;
            mean: number;
            median: number;
            p95: number;
            max: number;
            standard_deviation: number;
        };
    };
};
export declare type CheckoutKey = {
    'public-key': string;
    type: 'deploy-key' | 'github-user-key';
    fingerprint: string;
    preferred: boolean;
    'created-at': string;
};
export declare type User = {
    id: string;
    login: string;
    name: string;
};
export declare type Collaboration = {
    vcs_type: string;
    name: string;
    avatar_url: string;
};
export declare type Context = {
    id: string;
    name: string;
    created_at: string;
};
export declare type ContextEnvVar = {
    variable: string;
    created_at: string;
    context_id: string;
};
export declare class ArgumentError extends Error {
    constructor(message: string);
}
export declare class ProjectSlugError extends Error {
    constructor();
}
export declare class APIError extends Error {
    status: number;
    response: Response;
    constructor(message: string | undefined, status: number, response: Response);
}
declare type Headers = {
    [header: string]: string;
};
export declare const CIRCLE_CI_URL = "https://circleci.com";
export declare const API_BASE_PATH = "/api/v2";
declare class CircleCI {
    private readonly apiKey;
    slug?: ProjectSlug | string;
    branch?: string;
    private baseUrl;
    private previewWarned;
    private headers;
    constructor(apiKey: string, { slug, branch, baseUrl, headers, }?: {
        slug?: ProjectSlug | string;
        branch?: string;
        baseUrl?: string;
        headers?: Headers;
    });
    private request;
    private previewWarn;
    getProjectSlug(): string;
    /**
     * Retrieves a project by project slug.
     */
    getProject(): Promise<Project>;
    /**
     * Returns a sequence of checkout keys for the project.
     */
    listCheckoutKeys({ pageToken, }?: {
        pageToken?: string;
    }): Promise<Paged<CheckoutKey>>;
    /**
     * Creates a new checkout key.
     */
    createCheckoutKey(type: 'user-key' | 'deploy-key'): Promise<CheckoutKey>;
    /**
     * Deletes the checkout key.
     */
    deleteCheckoutKey(fingerprint: string): Promise<void>;
    /**
     * Returns an individual checkout key.
     */
    getCheckoutKey(fingerprint: string): Promise<CheckoutKey>;
    /**
     * List all environment variables (masked).
     */
    listEnvVars({ pageToken, }?: {
        pageToken?: string;
    }): Promise<Paged<EnvVar>>;
    /**
     * Returns the masked value of an environment variable.
     */
    getEnvVar(name: string): Promise<EnvVar>;
    /**
     * Creates a new environment variable.
     */
    createEnvVar(name: string, value: string): Promise<EnvVar>;
    /**
     * Deletes the environment variable named.
     */
    deleteEnvVar(name: string): Promise<void>;
    /**
     * Returns summary fields of a workflow by ID.
     */
    getWorkflow(id: string): Promise<Workflow>;
    /**
     * Cancels a running workflow.
     */
    cancelWorkflow(id: string): Promise<void>;
    /**
     * Reruns a workflow.
     */
    rerunWorkflow(workflowId: string, { jobs, fromFailed }?: {
        jobs?: string[];
        fromFailed?: boolean;
    }): Promise<void>;
    /**
     * Approves a pending approval job in a workflow.
     */
    approveWorkflowJob(workflowId: string, requestId: string): Promise<void>;
    /**
     * Returns a sequence of jobs for a workflow.
     */
    listWorkflowJobs(id: string, { pageToken, }?: {
        pageToken?: string;
    }): Promise<Paged<Job>>;
    /**
     * Get summary metrics for a project's workflows.
     */
    listWorkflowMetrics({ pageToken, branch, }?: {
        pageToken?: string;
        branch?: string;
    }): Promise<Paged<SummaryMetrics>>;
    /**
     * Get summary metrics for a project workflow's jobs.
     */
    listWorkflowJobMetrics(workflowName: string, { pageToken, branch, }?: {
        pageToken?: string;
        branch?: string;
    }): Promise<Paged<SummaryMetrics>>;
    /**
     * Get recent runs of a workflow.
     */
    listWorkflowRuns(workflowName: string, { pageToken, branch, startDate, endDate, }?: {
        pageToken?: string;
        branch?: string;
        startDate?: string;
        endDate?: string;
    }): Promise<Paged<WorkflowRun>>;
    /**
     * Get recent runs of a job within a workflow.
     */
    listWorkflowJobRuns(workflowName: string, jobName: string, { pageToken, branch, startDate, endDate, }?: {
        pageToken?: string;
        branch?: string;
        startDate?: string;
        endDate?: string;
    }): Promise<Paged<WorkflowRun>>;
    /**
     * Returns all pipelines for the most recently built projects
     * you follow in an organization.
     */
    listPipelines(orgSlug: string, { pageToken, onlyMine, }?: {
        pageToken?: string;
        onlyMine?: boolean;
    }): Promise<Paged<Pipeline>>;
    /**
     * Returns a pipeline by ID.
     */
    getPipeline(pipelineId: string): Promise<Pipeline>;
    /**
     * Returns a pipeline's configuration by ID.
     */
    getPipelineConfig(pipelineId: string): Promise<PipelineConfig>;
    /**
     * Returns a paginated list of workflows by pipeline ID.
     */
    listPipelineWorkflows(pipelineId: string, { pageToken, }?: {
        pageToken?: string;
    }): Promise<Paged<Workflow>>;
    /**
     * Triggers a new pipeline on the project.
     */
    triggerProjectPipeline({ branch, tag, parameters, }: {
        branch?: string;
        tag?: string;
        parameters?: {
            [key: string]: string | number | boolean;
        };
    }): Promise<PipelineConfig>;
    /**
     * Returns all pipelines for this project.
     */
    listProjectPipelines({ pageToken, branch, }?: {
        pageToken?: string;
        branch?: string;
    }): Promise<Paged<Pipeline>>;
    /**
     * Returns a sequence of all pipelines for this
     * project triggered by the user.
     */
    listOwnProjectPipelines({ pageToken, }?: {
        pageToken?: string;
    }): Promise<Paged<Pipeline>>;
    /**
     * Returns a pipeline by number.
     */
    getProjectPipeline(pipelineNumber: string | number): Promise<Pipeline>;
    /**
     * Returns job details.
     *
     * This is a preview API endpoint that may change at any time.
     */
    getJob(jobNumber: string | number): Promise<JobDetail>;
    /**
     * Cancel job with a given job number.
     *
     * This is a preview API endpoint that may change at any time.
     */
    cancelJob(jobNumber: string | number): Promise<void>;
    /**
     * Returns a job's artifacts.
     *
     * This is a preview API endpoint that may change at any time.
     */
    listJobArtifacts(jobNumber: string | number, { pageToken, }?: {
        pageToken?: string;
    }): Promise<Paged<JobArtifact>>;
    /**
     * Get test metadata for a build.
     *
     * This is a preview API endpoint that may change at any time.
     */
    listJobTests(jobNumber: string | number, { pageToken, }?: {
        pageToken?: string;
    }): Promise<Paged<JobTest>>;
    /**
     * Information about the user that is currently signed in.
     *
     * This is a preview API endpoint that may change at any time.
     */
    getMe(): Promise<User>;
    /**
     * Provides the set of organizations of which the currently
     * signed in user is a member or a collaborator.
     *
     * This is a preview API endpoint that may change at any time.
     */
    getCollaborations(): Promise<Collaboration[]>;
    /**
     * Information about the user with the given ID.
     *
     * This is a preview API endpoint that may change at any time.
     */
    getUser(userId: string): Promise<User>;
    /**
     * List all contexts for an owner.
     */
    listContexts({ ownerId, ownerSlug, ownerType, pageToken, }: {
        ownerId?: string;
        ownerSlug?: string;
        ownerType?: 'account' | 'organization';
        pageToken?: string;
    }): Promise<Paged<Context>>;
    /**
     * Create a new context.
     */
    createContext(name: string, owner: {
        id: string;
        type?: 'account' | 'organization';
    }): Promise<Context>;
    /**
     * Delete a context.
     */
    deleteContext(contextId: string): Promise<void>;
    /**
     * Returns basic information about a context.
     */
    getContext(contextId: string): Promise<Context>;
    /**
     * List information about environment variables in a context,
     * not including their values.
     */
    listContextEnvVars(contextId: string, { pageToken, }?: {
        pageToken?: string;
    }): Promise<Paged<ContextEnvVar>>;
    /**
     * Create or update an environment variable within a context.
     */
    createContextEnvVar(contextId: string, name: string, value: string): Promise<EnvVar>;
    /**
     * Delete an environment variable from a context.
     */
    deleteContextEnvVar(contextId: string, name: string): Promise<void>;
    /**
     * Download a job artifact and save it to disk.
     */
    downloadArtifact(artifact: JobArtifact | string, location?: string): Promise<void>;
}
export default CircleCI;