@percy/client 1.0.0-beta.8 → 1.0.1

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/dist/client.js

@@ -1,68 +1,76 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.default = void 0;
+import fs from 'fs';
+import PercyEnv from '@percy/env';
+import { git } from '@percy/env/utils';
+import logger from '@percy/logger';
+import { pool, request, sha256hash, base64encode, getPackageJSON } from './utils.js'; // Default client API URL can be set with an env var for API development
+
+const {
+  PERCY_CLIENT_API_URL = 'https://percy.io/api/v1'
+} = process.env;
+const pkg = getPackageJSON(import.meta.url); // Validate build ID arguments
+
+function validateBuildId(id) {
+  if (!id) throw new Error('Missing build ID');
+
+  if (!(typeof id === 'string' || typeof id === 'number')) {
+    throw new Error('Invalid build ID');
+  }
+} // Validate project path arguments
 
-var _env = _interopRequireDefault(require("@percy/env"));
 
-var _git = require("@percy/env/dist/git");
+function validateProjectPath(path) {
+  if (!path) throw new Error('Missing project path');
 
-var _package = _interopRequireDefault(require("../package.json"));
+  if (!/^[^/]+?\/.+/.test(path)) {
+    throw new Error(`Invalid project path. Expected "org/project" but received "${path}"`);
+  }
+} // 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.
 
-var _utils = require("./utils");
 
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+export class PercyClient {
+  log = logger('client');
+  env = new PercyEnv(process.env);
+  clientInfo = new Set();
+  environmentInfo = new Set();
 
-// 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'
+    clientInfo,
+    environmentInfo,
+    // versioned api url
+    apiUrl = PERCY_CLIENT_API_URL
   } = {}) {
     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
-      }
+      apiUrl
     });
+    this.addClientInfo(clientInfo);
+    this.addEnvironmentInfo(environmentInfo);
   } // Adds additional unique client info.
 
 
   addClientInfo(info) {
-    if (info && this.clientInfo.indexOf(info) === -1) {
-      this.clientInfo.push(info);
+    for (let i of [].concat(info)) {
+      if (i) this.clientInfo.add(i);
     }
   } // Adds additional unique environment info.
 
 
   addEnvironmentInfo(info) {
-    if (info && this.environmentInfo.indexOf(info) === -1) {
-      this.environmentInfo.push(info);
+    for (let i of [].concat(info)) {
+      if (i) this.environmentInfo.add(i);
     }
   } // 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})`;
+    let client = new Set([`Percy/${/\w+$/.exec(this.apiUrl)}`].concat(`${pkg.name}/${pkg.version}`, ...this.clientInfo).filter(Boolean));
+    let environment = new Set([...this.environmentInfo].concat(`node/${process.version}`, this.env.info).filter(Boolean));
+    return `${[...client].join(' ')} (${[...environment].join('; ')})`;
   } // Checks for a Percy token and returns it.
 
 
@@ -84,35 +92,20 @@ class PercyClient {
 
 
   get(path) {
-    return (0, _utils.request)(`${this.apiUrl}/${path}`, {
-      method: 'GET',
-      agent: this.httpAgent,
-      headers: this.headers()
+    return request(`${this.apiUrl}/${path}`, {
+      headers: this.headers(),
+      method: 'GET'
     });
   } // 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),
+    return request(`${this.apiUrl}/${path}`, {
       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']
-      }
+      }),
+      method: 'POST',
+      body
     });
   } // 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
@@ -122,11 +115,8 @@ class PercyClient {
   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', {
+    this.log.debug('Creating a new build...');
+    return this.post('builds', {
       data: {
         type: 'builds',
         attributes: {
@@ -149,7 +139,7 @@ class PercyClient {
           resources: {
             data: resources.map(r => ({
               type: 'resources',
-              id: r.sha || (0, _utils.sha256hash)(r.content),
+              id: r.sha || sha256hash(r.content),
               attributes: {
                 'resource-url': r.url,
                 'is-root': r.root || null,
@@ -160,34 +150,32 @@ class PercyClient {
         }
       }
     });
-    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({
+  async finalizeBuild(buildId, {
     all = false
   } = {}) {
-    if (!this.build.id) {
-      throw new Error('This client instance has no active build');
-    }
-
+    validateBuildId(buildId);
     let qs = all ? 'all-shards=true' : '';
-    let body = await this.post(`builds/${this.build.id}/finalize?${qs}`);
-    this.setBuildData();
-    return body;
+    this.log.debug(`Finalizing build ${buildId}...`);
+    return this.post(`builds/${buildId}/finalize?${qs}`);
   } // Retrieves build data by id. Requires a read access token.
 
 
   async getBuild(buildId) {
+    validateBuildId(buildId);
+    this.log.debug(`Get build ${buildId}`);
     return this.get(`builds/${buildId}`);
   } // Retrieves project builds optionally filtered. Requires a read access token.
 
 
-  async getBuilds(projectSlug, filters = {}) {
+  async getBuilds(project, filters = {}) {
+    validateProjectPath(project);
     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}`);
+    this.log.debug(`Fetching builds for ${project}`);
+    return this.get(`projects/${project}/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.
 
@@ -196,49 +184,52 @@ class PercyClient {
     build,
     project,
     commit,
-    progress,
-    timeout = 600000,
+    timeout = 10 * 60 * 1000,
     interval = 1000
-  }) {
+  }, onProgress) {
     if (commit && !project) {
-      throw new Error('Missing project for commit');
+      throw new Error('Missing project path for commit');
     } else if (!commit && !build) {
       throw new Error('Missing build ID or commit SHA');
-    } // get build data by id or project-commit combo
+    } else if (project) {
+      validateProjectPath(project);
+    }
 
+    let sha = commit && (git(`rev-parse ${commit}`) || commit);
 
-    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
+    let fetchData = async () => build ? (await this.getBuild(build)).data : (await this.getBuilds(project, {
+      sha
+    })).data[0];
 
+    this.log.debug(`Waiting for build ${build || `${project} (${commit})`}...`); // 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
+        let data = await fetchData();
+        let state = data === null || data === void 0 ? void 0 : data.attributes.state;
+        let pending = !state || state === 'pending' || state === 'processing';
+        let updated = JSON.stringify(data) !== JSON.stringify(last); // new data received
 
         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
+        } // call progress every update after the first update
 
 
-        if ((last || pending) && updated && progress) {
-          progress(data);
+        if ((last || pending) && updated) {
+          onProgress === null || onProgress === void 0 ? void 0 : onProgress(data);
         } // not finished, poll again
 
 
         if (pending) {
           return setTimeout(poll, interval, data, t); // build finished
         } else {
-          resolve(data);
+          // ensure progress is called at least once
+          if (!last) onProgress === null || onProgress === void 0 ? void 0 : onProgress(data);
+          resolve({
+            data
+          });
         }
       } catch (err) {
         reject(err);
@@ -249,42 +240,39 @@ class PercyClient {
   // created from `content` if one is not provided.
 
 
-  async uploadResource({
+  async uploadResource(buildId, {
+    url,
     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`, {
+  } = {}) {
+    validateBuildId(buildId);
+    this.log.debug(`Uploading resource: ${url}...`);
+    if (filepath) content = fs.readFileSync(filepath);
+    return this.post(`builds/${buildId}/resources`, {
       data: {
         type: 'resources',
-        id: sha || (0, _utils.sha256hash)(content),
+        id: sha || sha256hash(content),
         attributes: {
-          'base64-content': (0, _utils.base64encode)(content)
+          'base64-content': 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* () {
+  async uploadResources(buildId, resources) {
+    validateBuildId(buildId);
+    this.log.debug(`Uploading resources for ${buildId}...`);
+    return pool(function* () {
       for (let resource of resources) {
-        yield this.uploadResource(resource);
+        yield this.uploadResource(buildId, resource);
       }
     }, this, 2);
   } // Creates a snapshot for the active build using the provided attributes.
 
 
-  async createSnapshot({
+  async createSnapshot(buildId, {
     name,
     widths,
     minHeight,
@@ -293,13 +281,16 @@ class PercyClient {
     environmentInfo,
     resources = []
   } = {}) {
-    if (!this.build.id) {
-      throw new Error('This client instance has no active build');
-    }
-
+    validateBuildId(buildId);
     this.addClientInfo(clientInfo);
     this.addEnvironmentInfo(environmentInfo);
-    return this.post(`builds/${this.build.id}/snapshots`, {
+
+    if (!this.clientInfo.size || !this.environmentInfo.size) {
+      this.log.warn('Warning: Missing `clientInfo` and/or `environmentInfo` properties');
+    }
+
+    this.log.debug(`Creating snapshot: ${name}...`);
+    return this.post(`builds/${buildId}/snapshots`, {
       data: {
         type: 'snapshots',
         attributes: {
@@ -312,7 +303,7 @@ class PercyClient {
           resources: {
             data: resources.map(r => ({
               type: 'resources',
-              id: r.sha || (0, _utils.sha256hash)(r.content),
+              id: r.sha || sha256hash(r.content),
               attributes: {
                 'resource-url': r.url || null,
                 'is-root': r.root || null,
@@ -327,31 +318,31 @@ class PercyClient {
 
 
   async finalizeSnapshot(snapshotId) {
+    if (!snapshotId) throw new Error('Missing snapshot ID');
+    this.log.debug(`Finalizing snapshot ${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;
+  async sendSnapshot(buildId, options) {
+    var _snapshot$data$relati, _snapshot$data$relati2;
 
-    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;
+    let snapshot = await this.createSnapshot(buildId, options);
+    let missing = (_snapshot$data$relati = snapshot.data.relationships) === null || _snapshot$data$relati === void 0 ? void 0 : (_snapshot$data$relati2 = _snapshot$data$relati['missing-resources']) === null || _snapshot$data$relati2 === void 0 ? void 0 : _snapshot$data$relati2.data;
 
-    if (missing === null || missing === void 0 ? void 0 : missing.length) {
+    if (missing !== null && missing !== void 0 && missing.length) {
       let resources = options.resources.reduce((acc, r) => Object.assign(acc, {
         [r.sha]: r
       }), {});
-      await this.uploadResources(missing.map(({
+      await this.uploadResources(buildId, missing.map(({
         id
       }) => resources[id]));
     }
 
-    await this.finalizeSnapshot(data.id);
+    await this.finalizeSnapshot(snapshot.data.id);
+    return snapshot;
   }
 
 }
-
-exports.default = PercyClient;
+export default PercyClient;

package/dist/index.js

@@ -1,15 +1 @@
-"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 }; }
+export { default, PercyClient } from './client.js';

package/dist/proxy.js

@@ -0,0 +1,205 @@
+import net from 'net';
+import tls from 'tls';
+import http from 'http';
+import https from 'https';
+import logger from '@percy/logger';
+const CRLF = '\r\n';
+const STATUS_REG = /^HTTP\/1.[01] (\d*)/; // Returns true if the URL hostname matches any patterns
+
+export function hostnameMatches(patterns, url) {
+  let subject = new URL(url);
+  /* istanbul ignore next: only strings are provided internally by the client proxy; core (which
+   * borrows this util) sometimes provides an array of patterns or undefined */
+
+  patterns = typeof patterns === 'string' ? patterns.split(/[\s,]+/) : [].concat(patterns);
+
+  for (let pattern of patterns) {
+    if (pattern === '*') return true;
+    if (!pattern) continue; // parse pattern
+
+    let {
+      groups: rule
+    } = pattern.match(/^(?<hostname>.+?)(?::(?<port>\d+))?$/); // missing a hostname or ports do not match
+
+    if (!rule.hostname || rule.port && rule.port !== subject.port) {
+      continue;
+    } // wildcards are treated the same as leading dots
+
+
+    rule.hostname = rule.hostname.replace(/^\*/, ''); // hostnames are equal or end with a wildcard rule
+
+    if (rule.hostname === subject.hostname || rule.hostname.startsWith('.') && subject.hostname.endsWith(rule.hostname)) {
+      return true;
+    }
+  }
+
+  return false;
+} // Returns the port number of a URL object. Defaults to port 443 for https
+// protocols or port 80 otherwise.
+
+export function port(options) {
+  if (options.port) return options.port;
+  return options.protocol === 'https:' ? 443 : 80;
+} // Returns a string representation of a URL-like object
+
+export function href(options) {
+  let {
+    protocol,
+    hostname,
+    path,
+    pathname,
+    search,
+    hash
+  } = options;
+  return `${protocol}//${hostname}:${port(options)}` + (path || `${pathname || ''}${search || ''}${hash || ''}`);
+}
+; // Returns the proxy URL for a set of request options
+
+export function getProxy(options) {
+  let proxyUrl = options.protocol === 'https:' && (process.env.https_proxy || process.env.HTTPS_PROXY) || process.env.http_proxy || process.env.HTTP_PROXY;
+  let shouldProxy = !!proxyUrl && !hostnameMatches(process.env.no_proxy || process.env.NO_PROXY, href(options));
+
+  if (shouldProxy) {
+    proxyUrl = new URL(proxyUrl);
+    let isHttps = proxyUrl.protocol === 'https:';
+
+    if (!isHttps && proxyUrl.protocol !== 'http:') {
+      throw new Error(`Unsupported proxy protocol: ${proxyUrl.protocol}`);
+    }
+
+    let proxy = {
+      isHttps
+    };
+    proxy.auth = !!proxyUrl.username && 'Basic ' + (proxyUrl.password ? Buffer.from(`${proxyUrl.username}:${proxyUrl.password}`) : Buffer.from(proxyUrl.username)).toString('base64');
+    proxy.host = proxyUrl.hostname;
+    proxy.port = port(proxyUrl);
+
+    proxy.connect = () => (isHttps ? tls : net).connect({
+      rejectUnauthorized: options.rejectUnauthorized,
+      host: proxy.host,
+      port: proxy.port
+    });
+
+    return proxy;
+  }
+} // Proxified http agent
+
+export class ProxyHttpAgent extends http.Agent {
+  // needed for https proxies
+  httpsAgent = new https.Agent({
+    keepAlive: true
+  });
+
+  addRequest(request, options) {
+    var _request$outputData;
+
+    let proxy = getProxy(options);
+    if (!proxy) return super.addRequest(request, options);
+    logger('client:proxy').debug(`Proxying request: ${options.href}`); // modify the request for proxying
+
+    request.path = href(options);
+
+    if (proxy.auth) {
+      request.setHeader('Proxy-Authorization', proxy.auth);
+    } // regenerate headers since we just changed things
+
+
+    delete request._header;
+
+    request._implicitHeader();
+
+    if (((_request$outputData = request.outputData) === null || _request$outputData === void 0 ? void 0 : _request$outputData.length) > 0) {
+      let first = request.outputData[0].data;
+      let endOfHeaders = first.indexOf(CRLF.repeat(2)) + 4;
+      request.outputData[0].data = request._header + first.substring(endOfHeaders);
+    } // coerce the connection to the proxy
+
+
+    options.port = proxy.port;
+    options.host = proxy.host;
+    delete options.path;
+
+    if (proxy.isHttps) {
+      // use the underlying https agent to complete the connection
+      request.agent = this.httpsAgent;
+      return this.httpsAgent.addRequest(request, options);
+    } else {
+      return super.addRequest(request, options);
+    }
+  }
+
+} // Proxified https agent
+
+export class ProxyHttpsAgent extends https.Agent {
+  constructor(options) {
+    // default keep-alive
+    super({
+      keepAlive: true,
+      ...options
+    });
+  }
+
+  createConnection(options, callback) {
+    let proxy = getProxy(options);
+    if (!proxy) return super.createConnection(options, callback);
+    logger('client:proxy').debug(`Proxying request: ${href(options)}`); // generate proxy connect message
+
+    let host = `${options.hostname}:${port(options)}`;
+    let connectMessage = [`CONNECT ${host} HTTP/1.1`, `Host: ${host}`];
+
+    if (proxy.auth) {
+      connectMessage.push(`Proxy-Authorization: ${proxy.auth}`);
+    }
+
+    connectMessage = connectMessage.join(CRLF);
+    connectMessage += CRLF.repeat(2); // start the proxy connection and setup listeners
+
+    let socket = proxy.connect();
+
+    let handleError = err => {
+      socket.destroy(err);
+      callback(err);
+    };
+
+    let handleClose = () => handleError(new Error('Connection closed while sending request to upstream proxy'));
+
+    let buffer = '';
+
+    let handleData = data => {
+      var _buffer$match;
+
+      buffer += data.toString(); // haven't received end of headers yet, keep buffering
+
+      if (!buffer.includes(CRLF.repeat(2))) return; // stop listening after end of headers
+
+      socket.off('data', handleData);
+
+      if (((_buffer$match = buffer.match(STATUS_REG)) === null || _buffer$match === void 0 ? void 0 : _buffer$match[1]) !== '200') {
+        return handleError(new Error('Error establishing proxy connection. ' + `Response from server was: ${buffer}`));
+      }
+
+      options.socket = socket;
+      options.servername = options.hostname; // callback not passed in so not to be added as a listener
+
+      callback(null, super.createConnection(options));
+    }; // send and handle the connect message
+
+
+    socket.on('error', handleError).on('close', handleClose).on('data', handleData).write(connectMessage);
+  }
+
+}
+export function proxyAgentFor(url, options) {
+  let cache = proxyAgentFor.cache || (proxyAgentFor.cache = new Map());
+  let {
+    protocol,
+    hostname
+  } = new URL(url);
+  let cachekey = `${protocol}//${hostname}`;
+
+  if (!cache.has(cachekey)) {
+    cache.set(cachekey, protocol === 'https:' ? new ProxyHttpsAgent(options) : new ProxyHttpAgent(options));
+  }
+
+  return cache.get(cachekey);
+}

package/dist/utils.js

@@ -1,34 +1,31 @@
-"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');
+import os from 'os';
+import fs from 'fs';
+import url from 'url';
+import path from 'path';
+import crypto from 'crypto'; // Returns a sha256 hash of a string.
+
+export function sha256hash(content) {
+  return crypto.createHash('sha256').update(content, 'utf-8').digest('hex');
 } // Returns a base64 encoding of a string or buffer.
 
-
-function base64encode(content) {
+export function base64encode(content) {
   return Buffer.from(content).toString('base64');
+} // Returns the package.json content at the package path.
+
+export function getPackageJSON(rel) {
+  /* istanbul ignore else: sanity check */
+  if (rel.startsWith('file:')) rel = url.fileURLToPath(rel);
+  let pkg = path.join(rel, 'package.json');
+  if (fs.existsSync(pkg)) return JSON.parse(fs.readFileSync(pkg));
+  let dir = path.dirname(rel);
+  /* istanbul ignore else: sanity check */
+
+  if (dir !== rel && dir !== os.homedir()) return getPackageJSON(dir);
 } // 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) {
+export function pool(generator, context, concurrency) {
   return new Promise((resolve, reject) => {
     let iterator = generator.call(context);
     let queue = 0;
@@ -70,21 +67,16 @@ function pool(generator, context, concurrency) {
 // are exhausted, at which point the promise will reject with the last error
 // passed to `retry`.
 
-
-function retry(fn, {
+export 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 run = () => fn(resolve, reject, retry); // wait an interval to try again or reject with the error
 
 
     let retry = err => {
-      if (retries) {
+      if (retries-- > 0) {
         setTimeout(run, interval);
       } else {
         reject(err);
@@ -94,83 +86,119 @@ function retry(fn, {
 
     run();
   });
-} // Returns the appropriate http or https module for a given URL.
-
+} // Used by the request util when retrying specific errors
 
-function httpModuleFor(url) {
-  return url.match(/^https:\/\//) ? require('https') : require('http');
-} // Returns the appropriate http or https Agent instance for a given URL.
+const RETRY_ERROR_CODES = ['ECONNREFUSED', 'ECONNRESET', 'EPIPE', 'EHOSTUNREACH', 'EAI_AGAIN']; // Proxified request function that resolves with the response body 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 by
+// default, and 404 errors may also be optionally retried. If a callback is provided, it is called
+// with the parsed response body and response details. If the callback returns a value, that value
+// will be returned in the final resolved promise instead of the response body.
 
+export async function request(url, options = {}, callback) {
+  // accept `request(url, callback)`
+  if (typeof options === 'function') [options, callback] = [{}, options]; // gather request options
 
-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);
+    body,
+    headers,
+    retries,
+    retryNotFound,
+    interval,
+    noProxy,
+    ...requestOptions
+  } = options;
   let {
     protocol,
     hostname,
     port,
     pathname,
-    search
-  } = new _url.URL(url);
-  options = { ...options,
+    search,
+    hash
+  } = new URL(url); // reference the default export so tests can mock it
+
+  let {
+    default: http
+  } = await import(protocol === 'https:' ? 'https' : 'http');
+  let {
+    proxyAgentFor
+  } = await import('./proxy.js'); // automatically stringify body content
+
+  if (body && typeof body !== 'string') {
+    headers = {
+      'Content-Type': 'application/json',
+      ...headers
+    };
+    body = JSON.stringify(body);
+  } // combine request options
+
+
+  Object.assign(requestOptions, {
+    agent: requestOptions.agent || !noProxy && proxyAgentFor(url) || null,
+    path: pathname + search + hash,
     protocol,
     hostname,
-    port,
-    path: pathname + search
-  };
+    headers,
+    port
+  });
   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);
+    let handleError = error => {
+      if (handleError.handled) return;
+      handleError.handled = true; // maybe retry 404s, always retry 500s, or retry specific errors
+
+      let shouldRetry = error.response ? retryNotFound && error.response.statusCode === 404 || error.response.statusCode >= 500 && error.response.statusCode < 600 : !!error.code && RETRY_ERROR_CODES.includes(error.code);
+      return shouldRetry ? retry(error) : reject(error);
+    };
+
+    let handleFinished = async (body, res) => {
+      let {
+        statusCode,
+        headers
+      } = res;
+      let raw = body; // attempt to parse the body as json
+
+      try {
+        body = JSON.parse(body);
+      } catch (e) {}
+
+      try {
+        if (statusCode >= 200 && statusCode < 300) {
+          var _callback;
+
+          resolve((await ((_callback = callback) === null || _callback === void 0 ? void 0 : _callback(body, res))) ?? 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);
-          }
+          var _body, _body$errors, _body$errors$find;
+
+          let err = (_body = body) === null || _body === void 0 ? void 0 : (_body$errors = _body.errors) === null || _body$errors === void 0 ? void 0 : (_body$errors$find = _body$errors.find(e => e.detail)) === null || _body$errors$find === void 0 ? void 0 : _body$errors$find.detail;
+          throw new Error(err || `${statusCode} ${res.statusMessage || raw}`);
         }
-      });
-    }).on('error', reject).end(body);
+      } catch (error) {
+        let response = {
+          statusCode,
+          headers,
+          body
+        };
+        handleError(Object.assign(error, {
+          response
+        }));
+      }
+    };
+
+    let handleResponse = res => {
+      let body = '';
+      res.setEncoding('utf-8');
+      res.on('data', chunk => body += chunk);
+      res.on('end', () => handleFinished(body, res));
+      res.on('error', handleError);
+    };
+
+    let req = http.request(requestOptions);
+    req.on('response', handleResponse);
+    req.on('error', handleError);
+    req.end(body);
+  }, {
+    retries,
+    interval
   });
-}
+}
+export { hostnameMatches, ProxyHttpAgent, ProxyHttpsAgent, proxyAgentFor } from './proxy.js';

package/package.json

@@ -1,28 +1,38 @@
 {
   "name": "@percy/client",
-  "version": "1.0.0-beta.8",
+  "version": "1.0.1",
   "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.8"
+    "@percy/env": "1.0.1",
+    "@percy/logger": "1.0.1"
   },
-  "gitHead": "6015850e7c20c130d625fcb327b10d7513b35707"
+  "gitHead": "38917e6027299d6cd86008e2ccd005d90bbf89c0"
 }

package/test/helpers.js

@@ -0,0 +1,152 @@
+import EventEmitter from 'events';
+import url from 'url';
+
+// Mock response class used for mock requests
+export class MockResponse extends EventEmitter {
+  constructor(options) {
+    Object.assign(super(), options);
+  }
+
+  resume() {}
+  setEncoding() {}
+  pipe = stream => this
+    .on('data', d => stream.write(d))
+    .on('end', () => stream.end());
+};
+
+// Mock request class automates basic mocking necessities
+export class MockRequest extends EventEmitter {
+  constructor(reply, url, opts, cb) {
+    // handle optional url string
+    if (url && typeof url === 'string') {
+      let { protocol, hostname, port, pathname, search, hash } = new URL(url);
+      opts = { ...opts, protocol, hostname, port, path: pathname + search + hash };
+    } else if (typeof url !== 'string') {
+      opts = url;
+    }
+
+    Object.assign(super(), opts, { reply });
+    if (cb) this.on('response', cb);
+  }
+
+  // useful for logs/tests
+  get url() {
+    return new URL(this.path, url.format(this)).href;
+  }
+
+  // kick off a reply response on request end
+  end(body) {
+    // process async but return sync
+    (async () => {
+      try { this.body = JSON.parse(body); } catch {}
+      let [statusCode, data = '', headers = {}] = await this.reply?.(this) ?? [];
+
+      if (data && typeof data !== 'string') {
+        // handle common json data
+        headers['content-type'] = headers['content-type'] || 'application/json';
+        data = JSON.stringify(data);
+      } else if (!statusCode) {
+        // no status code was mocked
+        data = `Not mocked ${this.url}`;
+        statusCode = 404;
+      }
+
+      // automate content-length header
+      if (data != null && !headers['content-length']) {
+        headers['content-length'] = Buffer.byteLength(data);
+      }
+
+      // create and trigger a mock response
+      let res = new MockResponse({ statusCode, headers });
+      this.emit('response', res);
+
+      // maybe delay response data
+      setTimeout(() => {
+        res.emit('data', data);
+        res.emit('end');
+      }, this.delay);
+    })();
+
+    return this;
+  }
+}
+
+// Mock request responses using jasmine spies
+export async function mockRequests(baseUrl, defaultReply = () => [200]) {
+  let { protocol, hostname, pathname } = new URL(baseUrl);
+  let { default: http } = await import(protocol === 'https:' ? 'https' : 'http');
+
+  if (!jasmine.isSpy(http.request)) {
+    spyOn(http, 'request').and.callFake((...a) => new MockRequest(null, ...a));
+    spyOn(http, 'get').and.callFake((...a) => new MockRequest(null, ...a).end());
+  }
+
+  let any = jasmine.anything();
+  let match = o => o.hostname === hostname &&
+    (o.path ?? o.pathname).startsWith(pathname);
+  let reply = jasmine.createSpy('reply').and.callFake(defaultReply);
+
+  http.request.withArgs({ asymmetricMatch: match })
+    .and.callFake((...a) => new MockRequest(reply, ...a));
+  http.get.withArgs({ asymmetricMatch: u => match(new URL(u)) }, any, any)
+    .and.callFake((...a) => new MockRequest(reply, ...a).end());
+
+  return reply;
+}
+
+// Group of helpers to mock Percy API requests
+export const api = {
+  DEFAULT_REPLIES: {
+    '/builds': () => [201, {
+      data: {
+        id: '123',
+        attributes: {
+          'build-number': 1,
+          'web-url': 'https://percy.io/test/test/123'
+        }
+      }
+    }],
+
+    '/builds/123/snapshots': ({ body }) => [201, {
+      data: {
+        id: '4567',
+        attributes: body.attributes,
+        relationships: {
+          'missing-resources': {
+            data: body.data.relationships.resources
+              .data.map(({ id }) => ({ id }))
+          }
+        }
+      }
+    }]
+  },
+
+  async mock({ delay = 10 } = {}) {
+    this.replies = {};
+    this.requests = {};
+
+    await mockRequests('https://percy.io/api/v1', req => {
+      let path = req.path.replace('/api/v1', '');
+
+      let reply = (this.replies[path] && (
+        this.replies[path].length > 1
+          ? this.replies[path].shift()
+          : this.replies[path][0]
+      )) || this.DEFAULT_REPLIES[path];
+
+      this.requests[path] = this.requests[path] || [];
+      this.requests[path].push(req);
+
+      if (delay) req.delay = delay;
+      return reply?.(req) ?? [200];
+    });
+  },
+
+  reply(path, handler) {
+    this.replies[path] = this.replies[path] || [];
+    this.replies[path].push(handler);
+    return this;
+  }
+};
+
+export default api;