0
# SuperAgent
1

2
SuperAgent is a comprehensive HTTP client library that provides a fluent, chainable API for making HTTP requests in both Node.js and browser environments. It offers advanced features including automatic request/response parsing, authentication support, file uploads, promise and callback support, request cancellation, built-in retry logic, and extensive plugin ecosystem.
3

4
## Package Information
5

6
- **Package Name**: superagent
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install superagent`
10

11
## Core Imports
12

13
```javascript
14
const superagent = require('superagent');
15
```
16

17
For ES modules:
18

19
```javascript
20
import superagent from 'superagent';
21
```
22

23
For specific imports:
24

25
```javascript
26
const { agent, serialize, parse } = require('superagent');
27
```
28

29
## Basic Usage
30

31
```javascript
32
const superagent = require('superagent');
33

34
// GET request with callback
35
superagent
36
  .get('https://api.example.com/users')
37
  .set('Authorization', 'Bearer token')
38
  .end((err, res) => {
39
    if (err) throw err;
40
    console.log(res.body);
41
  });
42

43
// POST request with promise
44
superagent
45
  .post('https://api.example.com/users')
46
  .send({ name: 'John', email: 'john@example.com' })
47
  .set('Content-Type', 'application/json')
48
  .then(res => console.log(res.body))
49
  .catch(err => console.error(err));
50

51
// Async/await usage
52
(async () => {
53
  try {
54
    const res = await superagent
55
      .get('https://api.example.com/users/123')
56
      .query({ include: 'profile' });
57
    console.log(res.body);
58
  } catch (err) {
59
    console.error(err);
60
  }
61
})();
62
```
63

64
## Architecture
65

66
SuperAgent is built around several key components:
67

68
- **Request Factory**: Main function that creates Request instances for different HTTP methods
69
- **Request Class**: Chainable request builder with fluent API for configuration and execution
70
- **Response Class**: Structured response object with parsed data, headers, and metadata
71
- **Agent Class**: Session manager for cookie persistence, connection pooling, and default settings
72
- **Parser/Serializer System**: Pluggable content-type handlers for request/response transformation
73
- **Plugin System**: Extensible architecture via `.use()` method for custom middleware
74

75
## Capabilities
76

77
### HTTP Request Methods
78

79
Core HTTP method functions for making requests with fluent chainable interface.
80

81
```javascript { .api }
82
function get(url, data?, callback?): Request;
83
function post(url, data?, callback?): Request;
84
function put(url, data?, callback?): Request;
85
function patch(url, data?, callback?): Request;
86
function del(url, data?, callback?): Request;
87
function delete(url, data?, callback?): Request;
88
function head(url, data?, callback?): Request;
89
function options(url, data?, callback?): Request;
90
```
91

92
[HTTP Methods](./http-methods.md)
93

94
### Request Building
95

96
Comprehensive request configuration with headers, query parameters, body data, and request options.
97

98
```javascript { .api }
99
// Request building methods
100
Request.prototype.set(field, value): Request;
101
Request.prototype.get(field): string;
102
Request.prototype.getHeader(field): string;
103
Request.prototype.unset(field): Request;
104
Request.prototype.type(type): Request;
105
Request.prototype.accept(type): Request;
106
Request.prototype.query(value): Request;  
107
Request.prototype.send(data): Request;
108
Request.prototype.withCredentials(enabled?): Request;
109
Request.prototype.use(fn): Request;
110
Request.prototype.toJSON(): object;
111
```
112

113
[Request Building](./request-building.md)
114

115
### Authentication & Security
116

117
Authentication methods and TLS/SSL certificate configuration for secure communications.
118

119
```javascript { .api }
120
Request.prototype.auth(user, password?, options?): Request;
121
Request.prototype.http2(enabled?): Request;
122
Request.prototype.ca(cert): Request;
123
Request.prototype.key(cert): Request;
124
Request.prototype.cert(cert): Request;
125
Request.prototype.pfx(cert): Request;
126
Request.prototype.disableTLSCerts(): Request;
127
```
128

129
[Authentication & Security](./auth-security.md)
130

131
### File Uploads
132

133
Multipart form data support for file uploads and form submissions.
134

135
```javascript { .api }
136
Request.prototype.attach(field, file, options?): Request;
137
Request.prototype.field(name, value): Request;
138
```
139

140
[File Uploads](./file-uploads.md)
141

142
### Request Execution & Flow Control
143

144
Request execution, timeout management, retry logic, and response streaming.
145

146
```javascript { .api }
147
Request.prototype.end(callback?): Request;
148
Request.prototype.then(resolve, reject?): Promise<Response>;
149
Request.prototype.catch(reject): Promise<Response>;
150
Request.prototype.timeout(options): Request;
151
Request.prototype.retry(count, callback?): Request;
152
Request.prototype.abort(): Request;
153
Request.prototype.pipe(stream, options?): stream;
154
```
155

156
[Request Execution](./request-execution.md)
157

158
### Agent & Session Management
159

160
Agent-based session management with cookie persistence and connection pooling.
161

162
```javascript { .api }
163
function agent(options?): Agent;
164

165
class Agent {
166
  constructor(options?);
167
  get(url, data?, callback?): Request;
168
  post(url, data?, callback?): Request;
169
  // ... all HTTP methods available
170
}
171
```
172

173
[Agent & Sessions](./agent-sessions.md)
174

175
### Response Handling
176

177
Response object properties and methods for accessing response data, headers, and metadata.
178

179
```javascript { .api }
180
class Response {
181
  status: number;
182
  statusCode: number;
183
  text: string;
184
  body: any;
185
  header: object;
186
  type: string;
187
  charset: string;
188
  redirects: string[];
189
  get(field): string;
190
}
191
```
192

193
[Response Handling](./response-handling.md)
194

195
### Parsers & Serializers
196

197
Configurable content-type parsing and serialization for different data formats.
198

199
```javascript { .api }
200
// Global configuration objects
201
serialize['application/json']: Function;
202
serialize['application/x-www-form-urlencoded']: Function;
203
parse['application/json']: Function;
204
parse['text/plain']: Function;
205
parse['image/*']: Function;
206

207
// Per-request customization
208
Request.prototype.parse(fn): Request;
209
Request.prototype.serialize(fn): Request;
210
```
211

212
[Parsers & Serializers](./parsers-serializers.md)
213

214
## Types
215

216
```javascript { .api }
217
interface Request {
218
  method: string;
219
  url: string;
220
  header: object;
221
  cookies: string;
222
  qs: object;
223
}
224

225
interface Response {
226
  status: number;
227
  statusCode: number;
228
  text: string;
229
  body: any;
230
  header: object;
231
  type: string;
232
  charset: string;
233
  redirects: string[];
234
  files?: object;
235
  links: object;
236
  statusType: number;
237
  info: boolean;
238
  ok: boolean;
239
  redirect: boolean;
240
  clientError: boolean;
241
  serverError: boolean;
242
  error: boolean | Error;
243
  created: boolean;
244
  accepted: boolean;
245
  noContent: boolean;
246
  badRequest: boolean;
247
  unauthorized: boolean;
248
  forbidden: boolean;
249
  notFound: boolean;
250
  notAcceptable: boolean;
251
  unprocessableEntity: boolean;
252
  get(field: string): string;
253
  toError(): Error;
254
}
255

256
interface Agent {
257
  jar: CookieJar;
258
}
259

260
interface SerializerFunction {
261
  (obj: any): string;
262
}
263

264
interface ParserFunction {
265
  (res: Response, callback: (err: Error | null, body?: any, files?: object) => void): void;
266
}
267
```