Request Execution

/**
 * Execute the request with optional callback
 * @param {function} [callback] - Callback function (err, res) => void
 * @returns {Request} Request instance for chaining
 */
Request.prototype.end(callback?): Request;

/**
 * Promise interface for request execution
 * @param {function} resolve - Success callback
 * @param {function} [reject] - Error callback
 * @returns {Promise<Response>} Promise resolving to Response
 */
Request.prototype.then(resolve, reject?): Promise<Response>;

/**
 * Promise error handling
 * @param {function} reject - Error callback
 * @returns {Promise<Response>} Promise for chaining
 */
Request.prototype.catch(reject): Promise<Response>;

const superagent = require('superagent');

// Callback style
superagent
  .get('https://api.example.com/users')
  .end((err, res) => {
    if (err) {
      console.error('Request failed:', err);
      return;
    }
    console.log('Success:', res.body);
  });

// Promise with then/catch
superagent
  .get('https://api.example.com/users')
  .then(res => {
    console.log('Success:', res.body);
  })
  .catch(err => {
    console.error('Request failed:', err);
  });

// Async/await
(async () => {
  try {
    const res = await superagent.get('https://api.example.com/users');
    console.log('Success:', res.body);
  } catch (err) {
    console.error('Request failed:', err);
  }
})();

// Promise with both resolve and reject
superagent
  .get('https://api.example.com/users')
  .then(
    res => console.log('Success:', res.body),
    err => console.error('Failed:', err)
  );

/**
 * Set timeout options for request
 * @param {number|object} options - Timeout in ms or options object
 * @param {number} [options.deadline] - Overall request timeout
 * @param {number} [options.response] - Time to wait for first response byte
 * @param {number} [options.upload] - Upload timeout
 * @returns {Request} Request instance for chaining
 */
Request.prototype.timeout(options): Request;

/**
 * Clear any set timeouts
 * @returns {Request} Request instance for chaining
 */
Request.prototype.clearTimeout(): Request;

// Simple timeout (overall request)
superagent
  .get('https://api.example.com/slow-endpoint')
  .timeout(5000) // 5 seconds
  .end((err, res) => {
    if (err && err.timeout) {
      console.error('Request timed out');
    }
  });

// Detailed timeout configuration
superagent
  .post('https://api.example.com/upload')
  .attach('file', '/path/to/large-file.zip')
  .timeout({
    deadline: 60000,  // 60 seconds overall
    response: 10000,  // 10 seconds to get first response byte
    upload: 30000     // 30 seconds for upload to complete
  });

// Clear timeout
const request = superagent
  .get('https://api.example.com/data')
  .timeout(5000);

// Later, remove timeout
request.clearTimeout();

/**
 * Set retry configuration for failed requests
 * @param {number|boolean} count - Number of retry attempts or true for default
 * @param {function} [callback] - Custom retry condition function
 * @returns {Request} Request instance for chaining
 */
Request.prototype.retry(count, callback?): Request;

// Basic retry (default conditions)
superagent
  .get('https://api.example.com/unreliable')
  .retry(3) // Retry up to 3 times
  .end((err, res) => {
    if (err) {
      console.error('Failed after retries:', err);
    }
  });

// Custom retry condition
superagent
  .get('https://api.example.com/data')
  .retry(3, (err, res) => {
    // Custom logic to determine if retry should happen
    if (err && err.code === 'ECONNRESET') return true;  // Retry
    if (res && res.status === 503) return true;         // Retry
    return false; // Don't retry
  });

// Retry with promise
try {
  const res = await superagent
    .get('https://api.example.com/flaky')
    .retry(2);
  console.log('Success after retries:', res.body);
} catch (err) {
  console.error('Failed even with retries:', err);
}

/**
 * Abort the request
 * @returns {Request} Request instance for chaining
 */
Request.prototype.abort(): Request;

// Abort request after timeout
const request = superagent.get('https://api.example.com/slow');

setTimeout(() => {
  request.abort();
  console.log('Request aborted');
}, 3000);

request.end((err, res) => {
  if (err && err.aborted) {
    console.log('Request was aborted');
  }
});

// Abort with promise
const controller = {
  request: null,
  abort() {
    if (this.request) {
      this.request.abort();
    }
  }
};

controller.request = superagent.get('https://api.example.com/data');

// Later, abort the request
controller.abort();

try {
  const res = await controller.request;
} catch (err) {
  if (err.aborted) {
    console.log('Request was aborted');
  }
}

/**
 * Pipe response to a writable stream
 * @param {Stream} stream - Writable stream destination
 * @param {object} [options] - Pipe options
 * @returns {Stream} The destination stream
 */
Request.prototype.pipe(stream, options?): Stream;

/**
 * Write data to request (for streaming uploads)
 * @param {Buffer|string} data - Data to write
 * @param {string} [encoding] - Encoding for string data
 * @returns {boolean} Whether write was successful
 */
Request.prototype.write(data, encoding?): boolean;

const fs = require('fs');

// Stream response to file
superagent
  .get('https://api.example.com/large-file.zip')
  .pipe(fs.createWriteStream('/path/to/downloaded-file.zip'))
  .on('finish', () => {
    console.log('File downloaded successfully');
  })
  .on('error', (err) => {
    console.error('Download failed:', err);
  });

// Stream with progress tracking
const writeStream = fs.createWriteStream('/path/to/file.zip');
const request = superagent.get('https://api.example.com/file.zip');

request.on('progress', (event) => {
  console.log(`Download progress: ${event.percent}%`);
});

request.pipe(writeStream);

// Stream upload data
const uploadStream = superagent
  .post('https://api.example.com/stream-upload')
  .type('application/octet-stream');

// Write data to upload stream
uploadStream.write(Buffer.from('chunk 1'));
uploadStream.write(Buffer.from('chunk 2'));
uploadStream.end(); // Signal end of upload

uploadStream.then(res => {
  console.log('Stream upload complete:', res.body);
});

/**
 * Set custom success condition function
 * @param {function} fn - Function that returns true for successful responses
 * @returns {Request} Request instance for chaining
 */
Request.prototype.ok(fn): Request;

// Accept 4xx status codes as success
superagent
  .get('https://api.example.com/data')
  .ok(res => res.status < 500) // Treat anything below 500 as success
  .end((err, res) => {
    // err will be null for 4xx responses
    if (!err) {
      console.log('Request succeeded:', res.status);
    }
  });

// Custom business logic success condition
superagent
  .get('https://api.example.com/check')
  .ok(res => {
    // Custom logic based on response body
    return res.body && res.body.success === true;
  })
  .end((err, res) => {
    if (!err) {
      console.log('Business logic success');
    }
  });

// Multiple success conditions
superagent
  .get('https://api.example.com/data')
  .ok(res => {
    // Success if status is 200-299 or specific 4xx codes
    return (res.status >= 200 && res.status < 300) || 
           res.status === 404 || 
           res.status === 410;
  });

/**
 * Add event listener to request
 * @param {string} event - Event name
 * @param {function} listener - Event handler function
 * @returns {Request} Request instance for chaining
 */
Request.prototype.on(event, listener): Request;

/**
 * Add one-time event listener to request
 * @param {string} event - Event name
 * @param {function} listener - Event handler function
 * @returns {Request} Request instance for chaining
 */
Request.prototype.once(event, listener): Request;

// Progress tracking
superagent
  .post('https://api.example.com/upload')
  .attach('file', '/path/to/large-file.zip')
  .on('progress', (event) => {
    if (event.direction === 'upload') {
      console.log(`Upload: ${event.percent}% (${event.loaded}/${event.total})`);
    } else {
      console.log(`Download: ${event.percent}%`);
    }
  })
  .on('error', (err) => {
    console.error('Request error:', err);
  })
  .on('response', (res) => {
    console.log('Response received:', res.status);
  })
  .end();

// One-time event listeners
superagent
  .get('https://api.example.com/data')
  .once('response', (res) => {
    console.log('First response received:', res.status);
  })
  .once('error', (err) => {
    console.error('Request failed:', err);
  });