Commit f1c8e1a

The main goal of those clients is to make requests (right?). Let's see how we do it!

If the endpoint-wrapper for your request has not been made yet, don't leave!

You can make requests on your own!

- `.get` and `.delete`, that takes `(partialUrl: string, query?: TRequestQuery, requestSettings?: TGetClientRequestArgs)` in parameters

- `.post`, `.put` and `.patch` that takes `(partialUrl: string, body?: TRequestBody, requestSettings?: TGetClientRequestArgs)` in parameters

client.v1.get('statuses/user_timeline.json', { user_id: 14 });

client.v2.get('users/14/tweets');

Sometimes, you need to customize request settings (API prefix, body mode, response mode). You can pass request options through the **third parameter** of HTTP methods wrappers.

client.v1.post('media/upload.json', { media: Buffer.alloc(1024) }, { prefix: 'https://upload.twitter.com/1.1/' })

client.v1.post('statuses/update.json', { status: 'Hello' }, { forceBodyMode: 'url' })

const res = await client.v1.get('statuses/home_timeline.json', undefined, { fullResponse: true })

console.log(res.rateLimit, res.data)

client.v1.post('statuses/update.json', { status: 'Hello' }, { headers: { 'X-Custom-Header': 'My Header Value' } })

`twitter-api-v2` gives you a client that handles all the request signin boilerplate for you.

Sometimes, you need to dive deep and make the request on your own.

2 raw helpers allow you to make the request you want:

- `.send`: Make a request, awaits its complete response, parse it and returns it

- `.sendStream`: Make a requests, returns a stream when server responds OK

**Warning**: When you use those methods, you need to prefix your requests (no auto-prefixing)!

Make sure you use a URL that begins with `https://...` with raw request managers.

**Template types**: `T = any`

**Args**: `IGetHttpRequestArgs`

**Returns**: (async) `TwitterResponse<T>`

const response = await client.send({

method: 'GET',

url: 'https://api.twitter.com/2/tweets/search/all',

query: { max_results: 200 },

headers: { 'X-Custom-Header': 'True' },

});

response.data; // Twitter response body: { data: Tweet[], meta: {...} }

response.rateLimit.limit; // Ex: 900

**Args**: `IGetHttpRequestArgs`

**Returns**: (async) `TweetStream`

const stream = await client.sendStream({

method: 'GET',

url: 'https://api.twitter.com/2/tweets/sample/stream',

});

You can obtain lastly collected information of rate limit for each already used endpoint.

First, you need to know **which endpoint URL is concerned by the used endpoint wrapper**, for example,

for `.v1.tweets`, it is `statuses/lookup.json`. The endpoint is always specified in the lib documentation.

Use the endpoint URL to know:

- The last received status of rate limiting with `.getLastRateLimitStatus`

- If the stored rate limit information has expired with `.isRateLimitStatusObsolete`

- If you hit the rate limit the last time you called this endpoint, with `.hasHitRateLimit`

const tweets = await client.v1.tweets(['20', '30']);

console.log(client.v1.getLastRateLimitStatus('statuses/lookup.json'));

console.log(client.v1.isRateLimitStatusObsolete('statuses/lookup.json'));

console.log(client.v1.hasHitRateLimit('statuses/lookup.json'));

If you use a HTTP method helper (`.get`, `.post`, ...), you can get a **full response** object that directly contains the rate limit information,

even if the request didn't fail!

const manualFullResponse = await client.v1.get<TweetV1TimelineResult>('statuses/home_timeline.json', { since_id: '20' }, { fullResponse: true });

manualFullResponse.data; // TweetV1TimelineResult

manualFullResponse.rateLimit; // { limit: number, remaining: number, reset: number }

This library helps you to handle rate limiting.

When a request fails (with a Twitter response), it create a `ApiResponseError` instance and throw it.

If `ApiResponseErrorInstance.rateLimitError` is `true`, then you just hit the rate limit.

You have access to rate limit limits with `ApiResponseErrorInstance.rateLimit`:

import { ApiResponseError } from 'twitter-api-v2';

try {

// Get a single tweet

await client.v1.tweet('20');

} catch (error) {

if (error instanceof ApiResponseError && error.rateLimitError && error.rateLimit) {

console.log(`You just hit the rate limit! Limit for this endpoint is ${error.rateLimit.limit} requests!`);

console.log(`Request counter will reset at timestamp ${error.rateLimit.reset}.`);

}

}

**Example**: You can automate this process with a waiter that will retry a failed request after the reset timer is over:

*Warning*: This method can be VERY ineffective, as it can wait up to 15 minutes (Twitter's usual rate limit reset time).

function sleep(ms: number) {

return new Promise(resolve => setTimeout(ms, resolve));

}

async function autoRetryOnRateLimitError<T>(callback: () => T | Promise<T>) {

while (true) {

try {

return await callback();

} catch (error) {

if (error instanceof ApiResponseError && error.rateLimitError && error.rateLimit) {

const resetTimeout = error.rateLimit.reset * 1000; // convert to ms time instead of seconds time

const timeToWait = resetTimeout - Date.now();

await sleep(timeToWait);

continue;

}

throw error;

}

}

}

await autoRetryOnRateLimitError(() => client.v1.tweet('20'));

Paginators will automatically handle the rate limit when using `.fetchLast` or async iteration.

The `.fetchLast` or iteration will automatically ends when rate limit is hit.

Moreover, you can access current rate limit status for paginator's endpoint with the `.rateLimit` getter.

const paginator = await client.v1.homeTimeline();

console.log(paginator.rateLimit); // { limit: number, remaining: number, reset: number }

When a request fails, you get a `ApiRequestError` or a `ApiResponseError` object (both instances of `Error`), that contain useful information about whats happening.

- An `ApiRequestError` happens when the request **failed to sent** (network error, bad URL...).

- An `ApiResponseError` happens when **Twitter replies with an error**.

Some properties are common for both objects:

- `error` is `true`

- `type` contains either `ETwitterApiError.Request` or `ETwitterApiError.Response` (depending of error)

- `request` containing node's raw `ClientRequest` instance

- `requestError`, an instance of `Error` that has been thrown through `request.on('error')` handler

- `data`, containing parsed Twitter response data (type of `TwitterApiErrorData`)

- `code` is a `number` containing the HTTP error code (`401`, `404`, ...)

- `response`, containing raw node's `IncomingMessage` instance

- `headers`, containing `IncomingHttpHeaders`

- `rateLimit` (can be undefined or `TwitterRateLimit`), containing parsed rate limit headers (if any)

- (getter) `errors`, direct access of parsed Twitter errors (`(ErrorV1 | ErrorV2)[]` or `undefined`)

- (getter) `rateLimitError`, `true` if this error is fired because a rate limit has been hit

- (getter) `isAuthError`, `true` if this error is fired because logged user cannot do this action (invalid token, invalid app rights...)

- `hasErrorCode(code: number | EApiV1ErrorCode | EApiV2ErrorCode)`: Tells if given Twitter error code is present in error response