@percy/client 1.0.0-beta.9 → 1.0.0

package/README.md

@@ -1,51 +1,82 @@
 # @percy/client
 
 Communicate with Percy's API to create builds and snapshots, upload resources, and finalize builds
-and snapshots. Uses `@percy/env` to send environment information with new builds. Can also be used
-to query for a project's builds using a read access token.
+and snapshots. Uses [`@percy/env`](.packages/env) to send environment information with new
+builds. Can also be used to query for a project's builds using a read access token.
 
-## Usage
+- [Usage](#usage)
+- [Create a build](#create-a-build)
+- [Create, upload, and finalize snapshots](#create-upload-and-finalize-snapshots)
+- [Finalize a build](#finalize-a-build)
+- [Query for a build*](#query-for-a-build)
+- [Query for a project's builds*](#query-for-a-projects-builds)
+- [Wait for a build to be finished*](#wait-for-a-build-to-be-finished)
 
-### `new PercyClient([options])`
+## Usage
 
 ``` js
-import PercyClient from '@percy/client';
+import PercyClient from '@percy/client'
 
-// provide a read or write token, defaults to PERCY_TOKEN environment variable
-const client = new PercyClient({ token: 'abcdef123456' })
+const client = new PercyClient(options)
 ```
 
-### Create a build
+#### Options
+
+- `token` — Your project's `PERCY_TOKEN` (**default** `process.env.PERCY_TOKEN`)
+- `clientInfo` — Client info sent to Percy via a user-agent string
+- `environmentInfo` — Environment info also sent with the user-agent string
+
+## Create a build
+
+Creates a percy build. Only one build can be created at a time per instance. During this step,
+various environment information is collected via [`@percy/env`](./packages/env#readme) and
+associated with the new build. If `PERCY_PARALLEL_TOTAL` and `PERCY_PARALLEL_NONCE` are present, a
+build shard is created as part of a parallelized Percy build.
 
 ``` js
 await client.createBuild()
 ```
 
-### Create, upload, and finalize snapshots
+## Create, upload, and finalize snapshots
+
+This method combines the work of creating a snapshot, uploading any missing resources, and finally
+finalizng the snapshot.
 
 ``` js
-await client.sendSnapshot({
-  name,
-  widths,
-  minHeight,
-  enableJavaScript,
-  clientInfo,
-  environmentInfo,
-  // `sha` falls back to `content` sha
-  resources: [{ url, sha, content, mimetype, root }]
-})
+await client.sendSnapshot(buildId, snapshotOptions)
 ```
 
-### Finalize a build
+#### Options
+
+- `name` — Snapshot name
+- `widths` — Widths to take screenshots at
+- `minHeight` — Miniumum screenshot height
+- `enableJavaScript` — Enable JavaScript for screenshots
+- `clientInfo` — Additional client info
+- `environmentInfo` — Additional environment info
+- `resources` — Array of snapshot resources
+  - `url` — Resource URL (**required**)
+  - `mimetype` — Resource mimetype (**required**)
+  - `content` — Resource content (**required**)
+  - `sha` — Resource content sha
+  - `root` — Boolean indicating a root resource
+
+## Finalize a build
+
+Finalizes a build. When `all` is true, `all-shards=true` is added as a query param so the
+API finalizes all other parallel build shards associated with the build.
 
 ``` js
-await client.finalizeBuild()
+// finalize a build
+await client.finalizeBuild(buildId)
 
 // finalize all parallel build shards
-await client.finalizeBuild({ all: true })
+await client.finalizeBuild(buildId, { all: true })
 ```
 
-### Query for a build
+## Query for a build
+
+Retrieves build data by id.
 
 **Requires a read access token**
 
@@ -53,19 +84,51 @@ await client.finalizeBuild({ all: true })
 await client.getBuild(buildId)
 ```
 
-### Query for a project's builds
+## Query for a project's builds
+
+Retrieves project builds, optionally filtered. The project slug can be found as part of the
+project's URL. For example, the project slug for `https://percy.io/percy/example` is
+`"percy/example"`.
 
 **Requires a read access token**
 
 ``` js
-await client.getBuilds(projectSlug/*, filters*/)
+// get all builds for a project
+await client.getBuilds(projectSlug)
+
+// get all builds for a project's "master" branch
+await client.getBuilds(projectSlug, { branch: 'master' })
 ```
 
-### Wait for a build to be finished
+#### Filters
+
+- `sha` — A single commit sha
+- `shas` — An array of commit shas
+- `branch` — The name of a branch
+- `state` — The build state (`"pending"`, `"finished"`, etc.)
+
+## Wait for a build to be finished
+
+This method resolves when the build has finished and is no longer pending or processing. By default,
+it will time out if there is no update after 10 minutes.
 
 **Requires a read access token**
 
 ``` js
-await client.waitForBuild({ build: 'build-id' })
-await client.waitForBuild({ project: 'project-slug', commit: '40-char-sha' })
+// wait for a specific project build by commit sha
+await client.waitForBuild({
+  project: 'percy/example',
+  commit: '40-char-sha'
+}, data => {
+  // called whenever data changes
+  console.log(JSON.stringify(data));
+})
 ```
+
+#### Options
+
+- `build` — Build ID (**required** when missing `commit`)
+- `commit` — Commit SHA (**required** when missing `build`)
+- `project` — Project slug (**required** when using `commit`)
+- `timeout` — Timeout in milliseconds to wait with no updates (**default** `10 * 60 * 1000`)
+- `interval` — Interval in miliseconds to check for updates (**default** `1000`)

package/package.json

@@ -1,28 +1,38 @@
 {
   "name": "@percy/client",
-  "version": "1.0.0-beta.9",
+  "version": "1.0.0",
   "license": "MIT",
-  "main": "dist/index.js",
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "build": "babel --root-mode upward src --out-dir dist",
-    "lint": "eslint --ignore-path ../../.gitignore .",
-    "test": "cross-env NODE_ENV=test mocha",
-    "test:coverage": "nyc yarn test"
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/percy/cli",
+    "directory": "packages/client"
   },
   "publishConfig": {
     "access": "public"
   },
-  "mocha": {
-    "require": "../../scripts/babel-register"
+  "engines": {
+    "node": ">=14"
   },
-  "devDependencies": {
-    "mock-require": "^3.0.3"
+  "files": [
+    "./dist",
+    "./test/helpers.js"
+  ],
+  "main": "./dist/index.js",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./utils": "./dist/utils.js",
+    "./test/helpers": "./test/helpers.js"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build",
+    "lint": "eslint --ignore-path ../../.gitignore .",
+    "test": "node ../../scripts/test",
+    "test:coverage": "yarn test --coverage"
   },
   "dependencies": {
-    "@percy/env": "^1.0.0-beta.9"
+    "@percy/env": "1.0.0",
+    "@percy/logger": "1.0.0"
   },
-  "gitHead": "57a2eeb90c7f5cdf8827c78be1e5c12df581f4b5"
+  "gitHead": "6df509421a60144e4f9f5d59dc57a5675372a0b2"
 }

package/dist/client.js

@@ -1,357 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.default = void 0;
-
-var _env = _interopRequireDefault(require("@percy/env"));
-
-var _git = require("@percy/env/dist/git");
-
-var _package = _interopRequireDefault(require("../package.json"));
-
-var _utils = require("./utils");
-
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
-
-// PercyClient is used to communicate with the Percy API to create and finalize
-// builds and snapshot. Uses @percy/env to collect environment information used
-// during build creation.
-class PercyClient {
-  constructor({
-    // read or write token, defaults to PERCY_TOKEN environment variable
-    token,
-    // initial user agent info
-    clientInfo = '',
-    environmentInfo = '',
-    // versioned percy api url
-    apiUrl = 'https://percy.io/api/v1'
-  } = {}) {
-    Object.assign(this, {
-      token,
-      apiUrl,
-      httpAgent: (0, _utils.httpAgentFor)(apiUrl),
-      clientInfo: [].concat(clientInfo),
-      environmentInfo: [].concat(environmentInfo),
-      env: new _env.default(process.env),
-      // build info is stored for reference
-      build: {
-        id: null,
-        number: null,
-        url: null
-      }
-    });
-  } // Adds additional unique client info.
-
-
-  addClientInfo(info) {
-    if (info && this.clientInfo.indexOf(info) === -1) {
-      this.clientInfo.push(info);
-    }
-  } // Adds additional unique environment info.
-
-
-  addEnvironmentInfo(info) {
-    if (info && this.environmentInfo.indexOf(info) === -1) {
-      this.environmentInfo.push(info);
-    }
-  } // Stringifies client and environment info.
-
-
-  userAgent() {
-    let client = [`Percy/${/\w+$/.exec(this.apiUrl)}`].concat(`${_package.default.name}/${_package.default.version}`, this.clientInfo).filter(Boolean).join(' ');
-    let environment = this.environmentInfo.concat([`node/${process.version}`, this.env.info]).filter(Boolean).join('; ');
-    return `${client} (${environment})`;
-  } // Checks for a Percy token and returns it.
-
-
-  getToken() {
-    let token = this.token || this.env.token;
-    if (!token) throw new Error('Missing Percy token');
-    return token;
-  } // Returns common headers used for each request with additional
-  // headers. Throws an error when the token is missing, which is a required
-  // authorization header.
-
-
-  headers(headers) {
-    return Object.assign({
-      Authorization: `Token token=${this.getToken()}`,
-      'User-Agent': this.userAgent()
-    }, headers);
-  } // Performs a GET request for an API endpoint with appropriate headers.
-
-
-  get(path) {
-    return (0, _utils.request)(`${this.apiUrl}/${path}`, {
-      method: 'GET',
-      agent: this.httpAgent,
-      headers: this.headers()
-    });
-  } // Performs a POST request to a JSON API endpoint with appropriate headers.
-
-
-  post(path, body = {}) {
-    return (0, _utils.request)(`${this.apiUrl}/${path}`, {
-      method: 'POST',
-      agent: this.httpAgent,
-      body: JSON.stringify(body),
-      headers: this.headers({
-        'Content-Type': 'application/vnd.api+json'
-      })
-    });
-  } // Sets build reference data or nullifies it when no data is provided.
-
-
-  setBuildData(data) {
-    var _data$attributes, _data$attributes2;
-
-    return Object.assign(this, {
-      build: {
-        id: data === null || data === void 0 ? void 0 : data.id,
-        number: data === null || data === void 0 ? void 0 : (_data$attributes = data.attributes) === null || _data$attributes === void 0 ? void 0 : _data$attributes['build-number'],
-        url: data === null || data === void 0 ? void 0 : (_data$attributes2 = data.attributes) === null || _data$attributes2 === void 0 ? void 0 : _data$attributes2['web-url']
-      }
-    });
-  } // Creates a build with optional build resources. Only one build can be
-  // created at a time per instance so snapshots and build finalization can be
-  // done more seemlessly without manually tracking build ids
-
-
-  async createBuild({
-    resources = []
-  } = {}) {
-    if (this.build.id) {
-      throw new Error('This client instance has not finalized the previous build');
-    }
-
-    let body = await this.post('builds', {
-      data: {
-        type: 'builds',
-        attributes: {
-          branch: this.env.git.branch,
-          'target-branch': this.env.target.branch,
-          'target-commit-sha': this.env.target.commit,
-          'commit-sha': this.env.git.sha,
-          'commit-committed-at': this.env.git.committedAt,
-          'commit-author-name': this.env.git.authorName,
-          'commit-author-email': this.env.git.authorEmail,
-          'commit-committer-name': this.env.git.committerName,
-          'commit-committer-email': this.env.git.committerEmail,
-          'commit-message': this.env.git.message,
-          'pull-request-number': this.env.pullRequest,
-          'parallel-nonce': this.env.parallel.nonce,
-          'parallel-total-shards': this.env.parallel.total,
-          partial: this.env.partial
-        },
-        relationships: {
-          resources: {
-            data: resources.map(r => ({
-              type: 'resources',
-              id: r.sha || (0, _utils.sha256hash)(r.content),
-              attributes: {
-                'resource-url': r.url,
-                'is-root': r.root || null,
-                mimetype: r.mimetype || null
-              }
-            }))
-          }
-        }
-      }
-    });
-    this.setBuildData(body === null || body === void 0 ? void 0 : body.data);
-    return body;
-  } // Finalizes the active build. When `all` is true, `all-shards=true` is
-  // added as a query param so the API finalizes all other build shards.
-
-
-  async finalizeBuild({
-    all = false
-  } = {}) {
-    if (!this.build.id) {
-      throw new Error('This client instance has no active build');
-    }
-
-    let qs = all ? 'all-shards=true' : '';
-    let body = await this.post(`builds/${this.build.id}/finalize?${qs}`);
-    this.setBuildData();
-    return body;
-  } // Retrieves build data by id. Requires a read access token.
-
-
-  async getBuild(buildId) {
-    return this.get(`builds/${buildId}`);
-  } // Retrieves project builds optionally filtered. Requires a read access token.
-
-
-  async getBuilds(projectSlug, filters = {}) {
-    let qs = Object.keys(filters).map(k => Array.isArray(filters[k]) ? filters[k].map(v => `filter[${k}][]=${v}`).join('&') : `filter[${k}]=${filters[k]}`).join('&');
-    return this.get(`projects/${projectSlug}/builds?${qs}`);
-  } // Resolves when the build has finished and is no longer pending or
-  // processing. By default, will time out if no update after 10 minutes.
-
-
-  waitForBuild({
-    build,
-    project,
-    commit,
-    progress,
-    timeout = 600000,
-    interval = 1000
-  }) {
-    if (commit && !project) {
-      throw new Error('Missing project for commit');
-    } else if (!commit && !build) {
-      throw new Error('Missing build ID or commit SHA');
-    } // get build data by id or project-commit combo
-
-
-    let getBuildData = async () => {
-      let sha = commit && ((0, _git.git)(`rev-parse ${commit}`) || commit);
-      let body = build ? await this.getBuild(build) : await this.getBuilds(project, {
-        sha
-      });
-      let data = build ? body === null || body === void 0 ? void 0 : body.data : body === null || body === void 0 ? void 0 : body.data[0];
-      return [data, data === null || data === void 0 ? void 0 : data.attributes.state];
-    }; // recursively poll every second until the build finishes
-
-
-    return new Promise((resolve, reject) => async function poll(last, t) {
-      try {
-        let [data, state] = await getBuildData();
-        let updated = JSON.stringify(data) !== JSON.stringify(last);
-        let pending = !state || state === 'pending' || state === 'processing'; // new data recieved
-
-        if (updated) {
-          t = Date.now(); // no new data within the timeout
-        } else if (Date.now() - t >= timeout) {
-          throw new Error('Timeout exceeded without an update');
-        } // call progress after the first update
-
-
-        if ((last || pending) && updated && progress) {
-          progress(data);
-        } // not finished, poll again
-
-
-        if (pending) {
-          return setTimeout(poll, interval, data, t); // build finished
-        } else {
-          resolve(data);
-        }
-      } catch (err) {
-        reject(err);
-      }
-    }(null, Date.now()));
-  } // Uploads a single resource to the active build. If `filepath` is provided,
-  // `content` is read from the filesystem. The sha is optional and will be
-  // created from `content` if one is not provided.
-
-
-  async uploadResource({
-    sha,
-    filepath,
-    content
-  }) {
-    if (!this.build.id) {
-      throw new Error('This client instance has no active build');
-    }
-
-    content = filepath ? require('fs').readFileSync(filepath) : content;
-    return this.post(`builds/${this.build.id}/resources`, {
-      data: {
-        type: 'resources',
-        id: sha || (0, _utils.sha256hash)(content),
-        attributes: {
-          'base64-content': (0, _utils.base64encode)(content)
-        }
-      }
-    });
-  } // Uploads resources to the active build concurrently, two at a time.
-
-
-  async uploadResources(resources) {
-    if (!this.build.id) {
-      throw new Error('This client instance has no active build');
-    }
-
-    return (0, _utils.pool)(function* () {
-      for (let resource of resources) {
-        yield this.uploadResource(resource);
-      }
-    }, this, 2);
-  } // Creates a snapshot for the active build using the provided attributes.
-
-
-  async createSnapshot({
-    name,
-    widths,
-    minHeight,
-    enableJavaScript,
-    clientInfo,
-    environmentInfo,
-    resources = []
-  } = {}) {
-    if (!this.build.id) {
-      throw new Error('This client instance has no active build');
-    }
-
-    this.addClientInfo(clientInfo);
-    this.addEnvironmentInfo(environmentInfo);
-    return this.post(`builds/${this.build.id}/snapshots`, {
-      data: {
-        type: 'snapshots',
-        attributes: {
-          name: name || null,
-          widths: widths || null,
-          'minimum-height': minHeight || null,
-          'enable-javascript': enableJavaScript || null
-        },
-        relationships: {
-          resources: {
-            data: resources.map(r => ({
-              type: 'resources',
-              id: r.sha || (0, _utils.sha256hash)(r.content),
-              attributes: {
-                'resource-url': r.url || null,
-                'is-root': r.root || null,
-                mimetype: r.mimetype || null
-              }
-            }))
-          }
-        }
-      }
-    });
-  } // Finalizes a snapshot.
-
-
-  async finalizeSnapshot(snapshotId) {
-    return this.post(`snapshots/${snapshotId}/finalize`);
-  } // Convenience method for creating a snapshot for the active build, uploading
-  // missing resources for the snapshot, and finalizing the snapshot.
-
-
-  async sendSnapshot(options) {
-    var _data$relationships, _data$relationships$m;
-
-    let {
-      data
-    } = await this.createSnapshot(options);
-    let missing = (_data$relationships = data.relationships) === null || _data$relationships === void 0 ? void 0 : (_data$relationships$m = _data$relationships['missing-resources']) === null || _data$relationships$m === void 0 ? void 0 : _data$relationships$m.data;
-
-    if (missing === null || missing === void 0 ? void 0 : missing.length) {
-      let resources = options.resources.reduce((acc, r) => Object.assign(acc, {
-        [r.sha]: r
-      }), {});
-      await this.uploadResources(missing.map(({
-        id
-      }) => resources[id]));
-    }
-
-    await this.finalizeSnapshot(data.id);
-  }
-
-}
-
-exports.default = PercyClient;

package/dist/index.js

@@ -1,15 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-Object.defineProperty(exports, "default", {
-  enumerable: true,
-  get: function () {
-    return _client.default;
-  }
-});
-
-var _client = _interopRequireDefault(require("./client"));
-
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }

package/dist/utils.js

@@ -1,176 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.sha256hash = sha256hash;
-exports.base64encode = base64encode;
-exports.pool = pool;
-exports.httpAgentFor = httpAgentFor;
-exports.request = request;
-
-var _crypto = _interopRequireDefault(require("crypto"));
-
-var _url = require("url");
-
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
-
-// Returns a sha256 hash of a string.
-function sha256hash(content) {
-  return _crypto.default.createHash('sha256').update(content, 'utf-8').digest('hex');
-} // Returns a base64 encoding of a string or buffer.
-
-
-function base64encode(content) {
-  return Buffer.from(content).toString('base64');
-} // Creates a concurrent pool of promises created by the given generator.
-// Resolves when the generator's final promise resolves and rejects when any
-// generated promise rejects.
-
-
-function pool(generator, context, concurrency) {
-  return new Promise((resolve, reject) => {
-    let iterator = generator.call(context);
-    let queue = 0;
-    let ret = [];
-    let err; // generates concurrent promises
-
-    let proceed = () => {
-      while (queue < concurrency) {
-        let {
-          done,
-          value: promise
-        } = iterator.next();
-
-        if (done || err) {
-          if (!queue && err) reject(err);
-          if (!queue) resolve(ret);
-          return;
-        }
-
-        queue++;
-        promise.then(value => {
-          queue--;
-          ret.push(value);
-          proceed();
-        }).catch(error => {
-          queue--;
-          err = error;
-          proceed();
-        });
-      }
-    }; // start generating promises
-
-
-    proceed();
-  });
-} // Returns a promise that resolves or rejects when the provided function calls
-// `resolve` or `reject` respectively. The third function argument, `retry`,
-// will recursively call the function at the specified interval until retries
-// are exhausted, at which point the promise will reject with the last error
-// passed to `retry`.
-
-
-function retry(fn, {
-  retries = 5,
-  interval = 50
-} = {}) {
-  return new Promise((resolve, reject) => {
-    // run the function, decrement retries
-    let run = () => {
-      fn(resolve, reject, retry);
-      retries--;
-    }; // wait an interval to try again or reject with the error
-
-
-    let retry = err => {
-      if (retries) {
-        setTimeout(run, interval);
-      } else {
-        reject(err);
-      }
-    }; // start trying
-
-
-    run();
-  });
-} // Returns the appropriate http or https module for a given URL.
-
-
-function httpModuleFor(url) {
-  return url.match(/^https:\/\//) ? require('https') : require('http');
-} // Returns the appropriate http or https Agent instance for a given URL.
-
-
-function httpAgentFor(url) {
-  let {
-    Agent
-  } = httpModuleFor(url);
-  return new Agent({
-    keepAlive: true,
-    maxSockets: 5
-  });
-} // Returns a promise that resolves when the request is successful and rejects
-// when a non-successful response is received. The rejected error contains
-// response data and any received error details. Server 500 errors are retried
-// up to 5 times at 50ms intervals.
-
-
-function request(url, {
-  body,
-  ...options
-}) {
-  let http = httpModuleFor(url);
-  let {
-    protocol,
-    hostname,
-    port,
-    pathname,
-    search
-  } = new _url.URL(url);
-  options = { ...options,
-    protocol,
-    hostname,
-    port,
-    path: pathname + search
-  };
-  return retry((resolve, reject, retry) => {
-    http.request(options).on('response', res => {
-      let status = res.statusCode;
-      let raw = '';
-      res.setEncoding('utf8');
-      res.on('data', chunk => {
-        raw += chunk;
-      });
-      res.on('end', () => {
-        let body = raw; // attempt to parse json responses
-
-        try {
-          body = JSON.parse(raw);
-        } catch (e) {} // success
-
-
-        if (status >= 200 && status < 300) {
-          resolve(body);
-        } else {
-          var _body, _body$errors, _body$errors$;
-
-          // error
-          let err = Object.assign(new Error(), {
-            response: {
-              status,
-              body
-            },
-            message: ((_body = body) === null || _body === void 0 ? void 0 : (_body$errors = _body.errors) === null || _body$errors === void 0 ? void 0 : (_body$errors$ = _body$errors[0]) === null || _body$errors$ === void 0 ? void 0 : _body$errors$.detail) || `${status} ${res.statusMessage || raw}`
-          }); // retry 500s
-
-          if (status >= 500) {
-            retry(err);
-          } else {
-            reject(err);
-          }
-        }
-      });
-    }).on('error', reject).end(body);
-  });
-}