Basic typings for `@sentry/cli`

sentry__cli.d.ts

declare module '@sentry/cli' {
  interface UploadSourceMapsOptions {
    include: string[]
    ignore?: string[]
    ignoreFile?: string
    rewrite?: boolean
    sourceMapReference?: boolean
    stripPrefix?: string[]
    stripCommonPrefix?: boolean
    validate?: boolean
    urlPrefix?: string
    urlSuffix?: string
    ext?: string[]
  }

  /**
   * Manages releases and release artifacts on Sentry.
   * @namespace SentryReleases
   */
  class Releases {
    /**
     * Creates a new `Releases` instance.
     *
     * @param options More options to pass to the CLI
     */
    constructor(
      options?: {
        configFile?: string;
        silent?: boolean;
      },
    );

    /**
     * Registers a new release with sentry.
     *
     * The given release name should be unique and deterministic. It can later be used to
     * upload artifacts, such as source maps.
     *
     * @param release Unique name of the new release.
     * @returns A promise that resolves when the release has been created.
     * @memberof SentryReleases
     */
    new(release: string): Promise<string | undefined>;

    /**
     * Specifies the set of commits covered in this release.
     *
     * @param release Unique name of the release
     * @param options A set of options to configure the commits to include
     * @param options.repo The full repo name as defined in Sentry
     * @param options.auto Automatically choose the associated commit (uses
     * the current commit). Overrides other options.
     * @param options.commit The current (last) commit in the release.
     * @param options.previousCommit The commit before the beginning of this
     * release (in other words, the last commit of the previous release). If omitted,
     * this will default to the last commit of the previous release in Sentry. If there
     * was no previous release, the last 10 commits will be used.
     * @returns A promise that resolves when the commits have been associated
     * @memberof SentryReleases
     */
    setCommits(
      release: string,
      options: {
        auto?: false;
        repo: string;
        commit: string;
        previousCommit?: string;
      } | {
        auto: true;
      }): Promise<string | undefined>;

    /**
     * Marks this release as complete. This should be called once all artifacts has been
     * uploaded.
     *
     * @param release Unique name of the release.
     * @returns A promise that resolves when the release has been finalized.
     * @memberof SentryReleases
     */
    finalize(release: string): Promise<string | undefined>;

    /**
     * Creates a unique, deterministic version identifier based on the project type and
     * source files. This identifier can be used as release name.
     *
     * @returns A promise that resolves to the version string.
     * @memberof SentryReleases
     */
    proposeVersion(): Promise<string>;

    /**
     * Scans the given include folders for JavaScript source maps and uploads them to the
     * specified release for processing.
     *
     * The options require an `include` array, which is a list of directories to scan.
     * Additionally, it supports to ignore certain files, validate and preprocess source
     * maps and define a URL prefix.
     *
     * @example
     * await cli.releases.uploadSourceMaps(cli.releases.proposeVersion(), {
     *   // required options:
     *   include: ['build'],
     *
     *   // default options:
     *   ignore: ['node_modules'],  // globs for files to ignore
     *   ignoreFile: null,          // path to a file with ignore rules
     *   rewrite: false,            // preprocess sourcemaps before uploading
     *   sourceMapReference: true,  // add a source map reference to source files
     *   stripPrefix: [],           // remove certain prefixes from filenames
     *   stripCommonPrefix: false,  // guess common prefixes to remove from filenames
     *   validate: false,           // validate source maps and cancel the upload on error
     *   urlPrefix: '',             // add a prefix source map urls after stripping them
     *   urlSuffix: '',             // add a suffix source map urls after stripping them
     *   ext: ['js', 'map', 'jsbundle', 'bundle'],  // override file extensions to scan for
     * });
     *
     * @param release Unique name of the release.
     * @param options Options to configure the source map upload.
     * @returns A promise that resolves when the upload has completed successfully.
     * @memberof SentryReleases
     */
    uploadSourceMaps(
      release: string,
      options: UploadSourceMapsOptions
    ): Promise<Array<string | undefined>>;

    /**
     * List all deploys for a given release.
     *
     * @param release Unique name of the release.
     * @returns A promise that resolves when the list comes back from the server.
     * @memberof SentryReleases
     */
    listDeploys(release: string): Promise<string | undefined>;

    /**
     * Creates a new release deployment. This should be called after the release has been
     * finalized, while deploying on a given environment.
     *
     * @example
     * await cli.releases.newDeploy(cli.releases.proposeVersion(), {
     *   // required options:
     *   env: 'production',          // environment for this release. Values that make sense here would be 'production' or 'staging'
     *
     *   // optional options:
     *   started: 42,                // unix timestamp when the deployment started
     *   finished: 1337,             // unix timestamp when the deployment finished
     *   time: 1295,                 // deployment duration in seconds. This can be specified alternatively to `started` and `finished`
     *   name: 'PickleRick',         // human readable name for this deployment
     *   url: 'https://example.com', // URL that points to the deployment
     * });
     *
     * @param release Unique name of the release.
     * @param options Options to configure the new release deploy.
     * @returns A promise that resolves when the deploy has been created.
     * @memberof SentryReleases
     */
    newDeploy(release: string, options?: object): Promise<string | undefined>;

    /**
     * See {helper.execute} docs.
     * @param args Command line arguments passed to `sentry-cli`.
     * @param live We inherit stdio to display `sentry-cli` output directly.
     * @returns A promise that resolves to the standard output.
     */
    execute(args: string[], live?: boolean): Promise<string>;
  }

  /**
   * Interface to and wrapper around the `sentry-cli` executable.
   *
   * Commands are grouped into namespaces. See the respective namespaces for more
   * documentation. To use this wrapper, simply create an instance and call methods:
   *
   * @example
   * const cli = new SentryCli();
   * console.log(cli.getVersion());
   *
   * @example
   * const cli = new SentryCli('path/to/custom/sentry.properties');
   * console.log(cli.getVersion());
   */
  export default class SentryCli {
    /**
     * Creates a new `SentryCli` instance.
     *
     * If the `configFile` parameter is specified, configuration located in the default
     * location and the value specified in the `SENTRY_PROPERTIES` environment variable is
     * overridden.
     *
     * @param configFile Relative or absolute path to the configuration file.
     * @param options More options to pass to the CLI
     */
    constructor(configFile?: string, options?: Record<string, any>);

    /**
     * @returns the version of the installed `sentry-cli` binary.
     */
    static getVersion(): string;

    /**
     * @returns an absolute path to the `sentry-cli` binary.
     */
    static getPath(): string;

    releases: Releases;

    /**
     * See {helper.execute} docs.
     * @param args Command line arguments passed to `sentry-cli`.
     * @param live We inherit stdio to display `sentry-cli` output directly.
     * @returns A promise that resolves to the standard output.
     */
    execute(args: string[], live?: boolean): Promise<string>;
  }
}