superagent 3.8.1 → 4.0.0-beta.5

package/.travis.yml

@@ -1,9 +1,9 @@
 sudo: false
 language: node_js
 node_js:
+  - "10"
   - "8"
   - "6"
-  - "4"
 
 env:
   global:
@@ -12,5 +12,8 @@ env:
 
 matrix:
   include:
-    - node_js: "8"
+    - node_js: "9"
       env: BROWSER=1
+  include:
+    - node_js: "10"
+      env: HTTP2_TEST=1

package/.zuul.yml

@@ -8,7 +8,10 @@ browsers:
     version: latest
   - name: safari
     version: latest
-  - name: iphone
-    version: latest
   - name: ie
     version: 9..latest
+browserify:
+  - transform:
+      name: babelify
+      presets:
+        - [ babel-preset-es2015, { loose: true } ]

package/History.md

@@ -1,3 +1,38 @@
+# 4.0.0
+
+## Breaking changes
+
+ * Node.js v4 has reached it's end of life, so we no longer support it. It's v6+ or later. We recommend Node.js 10.
+ * We now use ES6 in the browser code, too.
+    * If you're using Browserify or Webpack to package code for Internet Explorer, you will also have to use Babel.
+    * The pre-built node_modules/superagent.js is still ES5-compatible.
+ * `.end(…)` returns `undefined` instead of the request. If you need the request object after calling `.end()` (and you probably don't), save it in a variable and call `request.end(…)`. Consider not using `.end()` at all, and migrating to promises by calling `.then()` instead.
+ * In Node, responses with unknown MIME type are buffered by default. To get old behavior, if you use custom *unbuffered* parsers, add `.buffer(false)` to requests or set `superagent.buffer[yourMimeType] = false`.
+ * Invalid uses of `.pipe()` throw.
+
+## Minor changes
+
+ * Throw if `req.abort().end()` is called
+ * Throw if using unsupported mix of send and field
+ * Reject `.end()` promise on all error events (Kornel Lesiński)
+ * Set `https.servername` from the `Host` header (Kornel Lesiński)
+ * Leave backticks unencoded in query strings where possible (Ethan Resnick)
+ * Update node-mime to 2.x (Alexey Kucherenko)
+ * Allow default buffer settings based on response-type (shrey)
+ * `response.buffered` is more accurate.
+
+# 3.8.3 (2018-04-29)
+
+ * Add flags for 201 & 422 responses (Nikhil Fadnis)
+ * Emit progress event while uploading Node `Buffer` via send method (Sergey Akhalkov)
+ * Fixed setting correct cookies for redirects (Damien Clark)
+ * Replace .catch with ['catch'] for IE9 Support (Miguel Stevens)
+
+# 3.8.2 (2017-12-09)
+
+ * Fixed handling of exceptions thrown from callbacks
+ * Stricter matching of `+json` MIME types.
+
 # 3.8.1 (2017-11-08)
 
  * Clear authorization header on cross-domain redirect

package/Makefile

@@ -11,9 +11,17 @@ test:
 test-node:
 	@NODE_ENV=test NODE_TLS_REJECT_UNAUTHORIZED=0 ./node_modules/.bin/mocha \
 		--require should \
+		--trace-warnings \
+		--reporter $(REPORTER) \
+		--timeout 5000 \
+		$(NODETESTS)
+
+test-node-http2:
+	@NODE_ENV=test HTTP2_TEST=1 NODE_TLS_REJECT_UNAUTHORIZED=0 node ./node_modules/.bin/mocha \
+		--require should \
+		--trace-warnings \
 		--reporter $(REPORTER) \
 		--timeout 5000 \
-		--growl \
 		$(NODETESTS)
 
 test-cov: lib-cov
@@ -30,6 +38,7 @@ lib-cov:
 
 superagent.js: lib/node/*.js lib/node/parsers/*.js
 	@./node_modules/.bin/browserify \
+		-t [ babelify --presets [ "babel-preset-es2015" --loose true ] ]  \
 		--standalone superagent \
 		--outfile superagent.js .
 

package/Readme.md

@@ -2,7 +2,7 @@
 
 [![Sauce Test Status](https://saucelabs.com/browser-matrix/shtylman-superagent.svg)](https://saucelabs.com/u/shtylman-superagent)
 
-SuperAgent is a small progressive __client-side__ HTTP request library, and __Node.js__ module with the same API, sporting many high-level HTTP client features. View the [docs](http://visionmedia.github.io/superagent/).
+SuperAgent is a small progressive __client-side__ HTTP request library, and __Node.js__ module with the same API, sporting many high-level HTTP client features. View the [docs](https://visionmedia.github.io/superagent/).
 
 ![super agent](http://f.cl.ly/items/3d282n3A0h0Z0K2w0q2a/Screenshot.png)
 
@@ -35,7 +35,7 @@ Tested browsers:
 - Latest Android, iPhone
 - IE10 through latest. IE9 with polyfills. Even though IE9 is supported, a polyfill for `window.FormData` is required for `.field()`.
 
-Node 4 or later is required.
+Node 6 or later is required.
 
 ## Plugins
 
@@ -63,13 +63,13 @@ Existing plugins:
  * [superagent-mock](https://github.com/M6Web/superagent-mock) - simulate HTTP calls by returning data fixtures based on the requested URL
  * [superagent-mocker](https://github.com/shuvalov-anton/superagent-mocker) — simulate REST API
  * [superagent-cache](https://github.com/jpodwys/superagent-cache) - A global SuperAgent patch with built-in, flexible caching
-  * [superagent-cache-plugin](https://github.com/jpodwys/superagent-cache-plugin) - A SuperAgent plugin with built-in, flexible caching
+ * [superagent-cache-plugin](https://github.com/jpodwys/superagent-cache-plugin) - A SuperAgent plugin with built-in, flexible caching
  * [superagent-jsonapify](https://github.com/alex94puchades/superagent-jsonapify) - A lightweight [json-api](http://jsonapi.org/format/) client addon for superagent
  * [superagent-serializer](https://github.com/zzarcon/superagent-serializer) - Converts server payload into different cases
- * [superagent-use](https://github.com/koenpunt/superagent-use) - A client addon to apply plugins to all requests.
  * [superagent-httpbackend](https://www.npmjs.com/package/superagent-httpbackend) - stub out requests using AngularJS' $httpBackend syntax
  * [superagent-throttle](https://github.com/leviwheatcroft/superagent-throttle) - queues and intelligently throttles requests
  * [superagent-charset](https://github.com/magicdawn/superagent-charset) - add charset support for node's SuperAgent
+ * [superagent-verbose-errors](https://github.com/jcoreio/superagent-verbose-errors) - include response body in error messages for failed requests
 
 Please prefix your plugin with `superagent-*` so that it can easily be found by others.
 
@@ -79,15 +79,19 @@ For SuperAgent extensions such as couchdb and oauth visit the [wiki](https://git
 
 Our breaking changes are mostly in rarely used functionality and from stricter error handling.
 
+* [3.x to 4.x](https://github.com/visionmedia/superagent/releases/tag/v4.0.0-alpha.1):
+  - Ensure you're running Node 6 or later. We've dropped support for Node 4.
+  - We've started using ES6 and for compatibility with Internet Explorer you may need to use Babel.
+  - We suggest migrating from `.end()` callbacks to `.then()` or `await`.
 * [2.x to 3.x](https://github.com/visionmedia/superagent/releases/tag/v3.0.0):
-  - Ensure you're running Node 4 or later. We dropped support for Node 0.x.
+  - Ensure you're running Node 4 or later. We've dropped support for Node 0.x.
   - Test code that calls `.send()` multiple times. Invalid calls to `.send()` will now throw instead of sending garbage.
 * [1.x to 2.x](https://github.com/visionmedia/superagent/releases/tag/v2.0.0):
   - If you use `.parse()` in the *browser* version, rename it to `.serialize()`.
   - If you rely on `undefined` in query-string values being sent literally as the text "undefined", switch to checking for missing value instead. `?key=undefined` is now `?key` (without a value).
   - If you use `.then()` in Internet Explorer, ensure that you have a polyfill that adds a global `Promise` object.
 * 0.x to 1.x:
-  - Use `.end(function(err, res){})`. 1-argument version is no longer supported.
+  - Instead of 1-argument callback `.end(function(res){})` use `.then(res => {})`.
 
 ## Running node tests
 

package/docs/index.md

@@ -8,51 +8,52 @@ SuperAgent is light-weight progressive ajax API crafted for flexibility, readabi
        .send({ name: 'Manny', species: 'cat' })
        .set('X-API-Key', 'foobar')
        .set('Accept', 'application/json')
-       .end(function(err, res){
-         if (err || !res.ok) {
-           alert('Oh no! error');
-         } else {
-           alert('yay got ' + JSON.stringify(res.body));
-         }
+       .then(res => {
+          alert('yay got ' + JSON.stringify(res.body));
        });
 
 ## Test documentation
 
-The following [test documentation](docs/test.html) was generated with [Mocha's](http://mochajs.org/) "doc" reporter, and directly reflects the test suite. This provides an additional source of documentation.
+The following [test documentation](docs/test.html) was generated with [Mocha's](https://mochajs.org/) "doc" reporter, and directly reflects the test suite. This provides an additional source of documentation.
 
 ## Request basics
 
-A request can be initiated by invoking the appropriate method on the `request` object, then calling `.end()` to send the request. For example a simple __GET__ request:
+A request can be initiated by invoking the appropriate method on the `request` object, then calling `.then()` (or `.end()` [or `await`](#promise-and-generator-support)) to send the request. For example a simple __GET__ request:
 
      request
        .get('/search')
-       .end(function(err, res){
-
+       .then(res => {
+          // res.body, res.headers, res.status
+       })
+       .catch(err => {
+          // err.message, err.response
        });
 
-A method string may also be passed:
+HTTP method may also be passed as a string:
 
-    request('GET', '/search').end(callback);
+    request('GET', '/search').then(success, failure);
 
-ES6 promises are supported. *Instead* of `.end()` you can call `.then()`:
+Old-style callbacks are also supported, but not recommended. *Instead of* `.then()` you can call `.end()`:
 
-    request('GET', '/search').then(success, failure);
+    request('GET', '/search').end(function(err, res){
+      if (res.ok) {}
+    });
 
-The __Node__ client may also provide absolute URLs. In browsers absolute URLs won't work unless the server implements [CORS](#cors).
+Absolute URLs can be used. In web browsers absolute URLs work only if the server implements [CORS](#cors).
 
      request
-       .get('http://example.com/search')
-       .end(function(err, res){
+       .get('https://example.com/search')
+       .then(res => {
 
        });
 
-The __Node__ client supports making requests to [Unix Domain Sockets](http://en.wikipedia.org/wiki/Unix_domain_socket):
+The __Node__ client supports making requests to [Unix Domain Sockets](https://en.wikipedia.org/wiki/Unix_domain_socket):
 
      // pattern: https?+unix://SOCKET_PATH/REQUEST_PATH
      //          Use `%2F` as `/` in SOCKET_PATH
      request
        .get('http+unix://%2Fabsolute%2Fpath%2Fto%2Funix.sock/search')
-       .end(function(err, res){
+       .then(res => {
 
        });
 
@@ -60,15 +61,15 @@ __DELETE__, __HEAD__, __PATCH__, __POST__, and __PUT__ requests can also be used
 
     request
       .head('/favicon.ico')
-      .end(function(err, res){
+      .then(res => {
 
       });
 
 __DELETE__ can be also called as `.del()` for compatibility with old IE where `delete` is a reserved word.
 
-  The HTTP method defaults to __GET__, so if you wish, the following is valid:
+The HTTP method defaults to __GET__, so if you wish, the following is valid:
 
-     request('/search', function(err, res){
+     request('/search', (err, res) => {
 
      });
 
@@ -80,14 +81,14 @@ Setting header fields is simple, invoke `.set()` with a field name and value:
        .get('/search')
        .set('API-Key', 'foobar')
        .set('Accept', 'application/json')
-       .end(callback);
+       .then(callback);
 
 You may also pass an object to set several fields in a single call:
 
      request
        .get('/search')
        .set({ 'API-Key': 'foobar', Accept: 'application/json' })
-       .end(callback);
+       .then(callback);
 
 ## `GET` requests
 
@@ -98,7 +99,7 @@ The `.query()` method accepts objects, which when used with the __GET__ method w
        .query({ query: 'Manny' })
        .query({ range: '1..5' })
        .query({ order: 'desc' })
-       .end(function(err, res){
+       .then(res => {
 
        });
 
@@ -107,7 +108,7 @@ Or as a single object:
     request
       .get('/search')
       .query({ query: 'Manny', range: '1..5', order: 'desc' })
-      .end(function(err, res){
+      .then(res => {
 
       });
 
@@ -116,7 +117,7 @@ The `.query()` method accepts strings as well:
       request
         .get('/querystring')
         .query('search=Manny&range=1..5')
-        .end(function(err, res){
+        .then(res => {
 
         });
 
@@ -126,7 +127,7 @@ Or joined:
         .get('/querystring')
         .query('search=Manny')
         .query('range=1..5')
-        .end(function(err, res){
+        .then(res => {
 
         });
 
@@ -137,7 +138,7 @@ You can also use the `.query()` method for HEAD requests. The following will pro
       request
         .head('/users')
         .query({ email: 'joe@smith.com' })
-        .end(function(err, res){
+        .then(res => {
 
         });
 
@@ -148,20 +149,20 @@ A typical JSON __POST__ request might look a little like the following, where we
       request.post('/user')
         .set('Content-Type', 'application/json')
         .send('{"name":"tj","pet":"tobi"}')
-        .end(callback)
+        .then(callback)
 
 Since JSON is undoubtedly the most common, it's the _default_! The following example is equivalent to the previous.
 
       request.post('/user')
         .send({ name: 'tj', pet: 'tobi' })
-        .end(callback)
+        .then(callback)
 
 Or using multiple `.send()` calls:
 
       request.post('/user')
         .send({ name: 'tj' })
         .send({ pet: 'tobi' })
-        .end(callback)
+        .then(callback)
 
 By default sending strings will set the `Content-Type` to `application/x-www-form-urlencoded`,
   multiple calls will be concatenated with `&`, here resulting in `name=tj&pet=tobi`:
@@ -169,7 +170,7 @@ By default sending strings will set the `Content-Type` to `application/x-www-for
       request.post('/user')
         .send('name=tj')
         .send('pet=tobi')
-        .end(callback);
+        .then(callback);
 
 SuperAgent formats are extensible, however by default "json" and "form" are supported. To send the data as `application/x-www-form-urlencoded` simply invoke `.type()` with "form", where the default is "json". This request will __POST__ the body "name=tj&pet=tobi".
 
@@ -177,13 +178,13 @@ SuperAgent formats are extensible, however by default "json" and "form" are supp
         .type('form')
         .send({ name: 'tj' })
         .send({ pet: 'tobi' })
-        .end(callback)
+        .then(callback)
 
 Sending a [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData/FormData) object is also supported. The following example will __POST__ the content of the HTML form identified by id="myForm":
 
       request.post('/user')
         .send(new FormData(document.getElementById('myForm')))
-        .end(callback)
+        .then(callback)
 
 ## Setting the `Content-Type`
 
@@ -207,8 +208,28 @@ simply the extension name such as "xml", "json", "png", etc:
 
 ## Serializing request body
 
-SuperAgent will automatically serialize JSON and forms. If you want to send the payload in a custom format, you can replace the built-in serialization with `.serialize()` method.
+SuperAgent will automatically serialize JSON and forms.
+You can setup automatic serialization for other types as well:
+
+```js
+request.serialize['application/xml'] = function (obj) {
+    return 'string generated from obj';
+};
+
+// going forward, all requests with a Content-type of
+// 'application/xml' will be automatically serialized
+```
+If you want to send the payload in a custom format, you can replace
+the built-in serialization with the `.serialize()` method on a per-request basis:
 
+```js
+request
+    .post('/user')
+    .send({foo: 'bar'})
+    .serialize(obj => {
+        return 'string generated from obj';
+    });
+```
 ## Retrying requests
 
 When given the `.retry()` method, SuperAgent will automatically retry requests, if they fail in a way that is transient or could be due to a flaky Internet connection.
@@ -216,9 +237,10 @@ When given the `.retry()` method, SuperAgent will automatically retry requests,
 This method has two optional arguments: number of retries (default 3) and a callback. It calls `callback(err, res)` before each retry. The callback may return `true`/`false` to control whether the request sould be retried (but the maximum number of retries is always applied).
 
      request
-       .get('http://example.com/search')
-       .retry(2)
-       .end(callback);
+       .get('https://example.com/search')
+       .retry(2) // or:
+       .retry(2, callback)
+       .then(finished);
 
 Use `.retry()` only with requests that are *idempotent* (i.e. multiple requests reaching the server won't cause undesirable side effects like duplicate purchases).
 
@@ -248,7 +270,7 @@ If you are calling Facebook's API, be sure to send an `Accept: application/json`
       .query({ format: 'json' })
       .query({ dest: '/login' })
       .send({ post: 'data', here: 'wahoo' })
-      .end(callback);
+      .then(callback);
 
 By default the query string is not assembled in any particular order. An asciibetically-sorted query string can be enabled with `req.sortQuery()`. You may also provide a custom sorting comparison function with `req.sortQuery(myComparisonFn)`. The comparison function should take 2 arguments and return a negative/zero/positive integer.
 
@@ -258,16 +280,14 @@ By default the query string is not assembled in any particular order. An asciibe
    .query('name=Nick')
    .query('search=Manny')
    .sortQuery()
-   .end(callback)
+   .then(callback)
 
  // customized sort function
  request.get('/user')
    .query('name=Nick')
    .query('search=Manny')
-   .sortQuery(function(a, b){
-     return a.length - b.length;
-   })
-   .end(callback)
+   .sortQuery((a, b) => a.length - b.length)
+   .then(callback)
 ```
 
 ## TLS options
@@ -289,7 +309,7 @@ request
   .post('/client-auth')
   .key(key)
   .cert(cert)
-  .end(callback);
+  .then(callback);
 ```
 
 ```js
@@ -298,12 +318,32 @@ var ca = fs.readFileSync('ca.cert.pem');
 request
   .post('https://localhost/private-ca-server')
   .ca(ca)
-  .end(callback);
+  .then(res => {});
 ```
 
 ## Parsing response bodies
 
-SuperAgent will parse known response-body data for you, currently supporting `application/x-www-form-urlencoded`, `application/json`, and `multipart/form-data`.
+SuperAgent will parse known response-body data for you,
+currently supporting `application/x-www-form-urlencoded`,
+`application/json`, and `multipart/form-data`. You can setup
+automatic parsing for other response-body data as well:
+
+```js
+//browser
+request.parse['application/xml'] = function (str) {
+    return {'object': 'parsed from str'};
+};
+
+//node
+request.parse['application/xml'] = function (res, cb) {
+    //parse response text and set res.body here
+
+    cb(null, res);
+};
+
+//going forward, responses of type 'application/xml'
+//will be parsed automatically
+```
 
 You can set a custom parser (that takes precedence over built-in parsers) with the `.buffer(true).parse(fn)` method. If response buffering is not enabled (`.buffer(false)`) then the `response` event will be emitted without waiting for the body parser to finish, so `response.body` won't be available.
 
@@ -341,7 +381,7 @@ In browsers, you may use `.responseType('blob')` to request handling of binary r
 ```js
 req.get('/binary.data')
   .responseType('blob')
-  .end(function (error, res) {
+  .then(res => {
     // res.body will be a browser native Blob type here
   });
 ```
@@ -402,11 +442,11 @@ To abort requests simply invoke the `req.abort()` method.
 
 Sometimes networks and servers get "stuck" and never respond after accepting a request. Set timeouts to avoid requests waiting forever.
 
-  * `req.timeout({deadline:ms})` or `req.timeout(ms)` (where `ms` is a number of milliseconds > 0) sets a deadline for the entire request (including all redirects) to complete. If the response isn't fully downloaded within that time, the request will be aborted.
+  * `req.timeout({deadline:ms})` or `req.timeout(ms)` (where `ms` is a number of milliseconds > 0) sets a deadline for the entire request (including all uploads, redirects, server processing time) to complete. If the response isn't fully downloaded within that time, the request will be aborted.
 
-  * `req.timeout({response:ms})` sets maximum time to wait for the first byte to arrive from the server, but it does not limit how long the entire download can take. Response timeout should be a few seconds longer than just the time it takes server to respond, because it also includes time to make DNS lookup, TCP/IP and TLS connections.
+  * `req.timeout({response:ms})` sets maximum time to wait for the first byte to arrive from the server, but it does not limit how long the entire download can take. Response timeout should be at least few seconds longer than just the time it takes the server to respond, because it also includes time to make DNS lookup, TCP/IP and TLS connections, and time to upload request data.
 
-You should use both `deadline` and `response` timeouts. This way you can use a short response timeout to detect unresponsive networks quickly, and a long deadline to give time for downloads on slow, but reliable, networks.
+You should use both `deadline` and `response` timeouts. This way you can use a short response timeout to detect unresponsive networks quickly, and a long deadline to give time for downloads on slow, but reliable, networks. Note that both of these timers limit how long *uploads* of attached files are allowed to take. Use long timeouts if you're uploading files.
 
     request
       .get('/big-file?network=slow')
@@ -414,8 +454,10 @@ You should use both `deadline` and `response` timeouts. This way you can use a s
         response: 5000,  // Wait 5 seconds for the server to start sending,
         deadline: 60000, // but allow 1 minute for the file to finish loading.
       })
-      .end(function(err, res){
-        if (err.timeout) { /* timed out! */ }
+      .then(res => {
+          /* responded in time */
+        }, err => {
+          if (err.timeout) { /* timed out! */ } else { /* other error */ }
       });
 
 Timeout errors have a `.timeout` property.
@@ -427,12 +469,12 @@ In both Node and browsers auth available via the `.auth()` method:
     request
       .get('http://local')
       .auth('tobi', 'learnboost')
-      .end(callback);
+      .then(callback);
 
 
 In the _Node_ client Basic auth can be in the URL as "user:pass":
 
-    request.get('http://tobi:learnboost@local').end(callback);
+    request.get('http://tobi:learnboost@local').then(callback);
 
 By default only `Basic` auth is used. In browser you can add `{type:'auto'}` to enable all methods built-in in the browser (Digest, NTLM, etc.):
 
@@ -445,7 +487,7 @@ By default up to 5 redirects will be followed, however you may specify this with
     request
       .get('/some.png')
       .redirects(2)
-      .end(callback);
+      .then(callback);
 
 ## Agents for global state
 
@@ -464,7 +506,7 @@ In browsers cookies are managed automatically by the browser, so the `.agent()`
 
 ### Default options for multiple requests
 
-Regular request methods (`.use()`, `.set()`, `.auth()`) called on the agent will be used as defaults for all requests made by that agent.
+Regular request methods called on the agent will be used as defaults for all requests made by that agent.
 
     const agent = request.agent()
       .use(plugin)
@@ -473,9 +515,13 @@ Regular request methods (`.use()`, `.set()`, `.auth()`) called on the agent will
     await agent.get('/with-plugin-and-auth');
     await agent.get('/also-with-plugin-and-auth');
 
+The complete list of methods that the agent can use to set defaults is: `use`, `on`, `once`, `set`, `query`, `type`, `accept`, `auth`, `withCredentials`, `sortQuery`, `retry`, `ok`, `redirects`, `timeout`, `buffer`, `serialize`, `parse`, `ca`, `key`, `pfx`, `cert`.
+
 ## Piping data
 
-The Node client allows you to pipe data to and from the request. For example piping a file's contents as the request:
+The Node client allows you to pipe data to and from the request. Please note that `.pipe()` is used **instead of** `.end()`/`.then()` methods.
+
+For example piping a file's contents as the request:
 
     const request = require('superagent');
     const fs = require('fs');
@@ -493,6 +539,22 @@ Or piping the response to a file:
     const req = request.get('/some.json');
     req.pipe(stream);
 
+ It's not possible to mix pipes and callbacks or promises. Note that you should **NOT** attempt to pipe the result of `.end()` or the `Response` object:
+
+    // Don't do either of these:
+    const stream = getAWritableStream();
+    const req = request
+      .get('/some.json')
+      // BAD: this pipes garbage to the stream and fails in unexpected ways
+      .end((err, this_does_not_work) => this_does_not_work.pipe(stream))
+    const req = request
+      .get('/some.json')
+      .end()
+      // BAD: this is also unsupported, .pipe calls .end for you.
+      .pipe(nope_its_too_late);
+
+In a [future version](https://github.com/visionmedia/superagent/issues/1188) of superagent, improper calls to `pipe()` will fail.
+
 ## Multipart requests
 
 SuperAgent is also great for _building_ multipart requests for which it provides methods `.attach()` and `.field()`.
@@ -503,7 +565,7 @@ When you use `.field()` or `.attach()` you can't use `.send()` and you *must not
 
 To send a file use `.attach(name, [file], [options])`. You can attach multiple files by calling `.attach` multiple times. The arguments are:
 
- * `name` — filed name in the form.
+ * `name` — field name in the form.
  * `file` — either string with file path or `Blob`/`Buffer` object.
  * `options` — (optional) either string with custom file name or `{filename: string}` object. In Node also `{contentType: 'mime/type'}` is supported. In browser create a `Blob` with an appropriate type instead.
 
@@ -514,7 +576,7 @@ To send a file use `.attach(name, [file], [options])`. You can attach multiple f
       .attach('image1', 'path/to/felix.jpeg')
       .attach('image2', imageBuffer, 'luna.jpeg')
       .field('caption', 'My cats')
-      .end(callback);
+      .then(callback);
 
 ### Field values
 
@@ -526,7 +588,7 @@ Much like form fields in HTML, you can set field values with `.field(name, value
        .field('user[email]', 'tobi@learnboost.com')
        .field('friends[]', ['loki', 'jane'])
        .attach('image', 'path/to/tobi.png')
-       .end(callback);
+       .then(callback);
 
 ## Compression
 
@@ -545,9 +607,9 @@ For security reasons, browsers will block cross-origin requests unless the serve
 The `.withCredentials()` method enables the ability to send cookies from the origin, however only when `Access-Control-Allow-Origin` is _not_ a wildcard ("*"), and `Access-Control-Allow-Credentials` is "true".
 
     request
-      .get('http://api.example.com:4001/')
+      .get('https://api.example.com:4001/')
       .withCredentials()
-      .then(function(res){
+      .then(res => {
         assert.equal(200, res.status);
         assert.equal('tobi', res.text);
       })
@@ -559,7 +621,7 @@ Your callback function will always be passed two arguments: error and response.
     request
      .post('/upload')
      .attach('image', 'path/to/tobi.png')
-     .end(function(err, res){
+     .then(res => {
 
      });
 
@@ -569,7 +631,7 @@ An "error" event is also emitted, with you can listen for:
       .post('/upload')
       .attach('image', 'path/to/tobi.png')
       .on('error', handle)
-      .end(function(err, res){
+      .then(res => {
 
       });
 
@@ -609,11 +671,13 @@ SuperAgent fires `progress` events on upload and download of large files.
           loaded: // bytes downloaded or uploaded so far
         } */
       })
-      .end()
+      .then()
 
 ## Promise and Generator support
 
-SuperAgent's request is a "thenable" object that's compatible with JavaScript promises and `async`/`await` syntax. Do not call `.end()` if you're using promises.
+SuperAgent's request is a "thenable" object that's compatible with JavaScript promises and `async`/`await` syntax.
+
+If you're using promises, **do not** call `.end()` or `.pipe()`. Any use of `.then()` or `await` disables all other ways of using the request.
 
 Libraries like [co](https://github.com/tj/co) or a web framework like [koa](https://github.com/koajs/koa) can `yield` on any SuperAgent method:
 
@@ -632,4 +696,4 @@ If want to use WebPack to compile code for Node.JS, you *must* specify [node tar
 
 ### Using browser version in electron
 
-[Electron](http://electron.atom.io/) developers report if you would prefer to use the browser version of SuperAgent instead of the Node version, you can `require('superagent/superagent')`. Your requests will now show up in the Chrome developer tools Network tab. Note this environment is not covered by automated test suite and not officially supported.
+[Electron](https://electron.atom.io/) developers report if you would prefer to use the browser version of SuperAgent instead of the Node version, you can `require('superagent/superagent')`. Your requests will now show up in the Chrome developer tools Network tab. Note this environment is not covered by automated test suite and not officially supported.