Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions doc/auth.md
Original file line number Diff line number Diff line change
Expand Up @@ -265,3 +265,22 @@ const { client: refreshedClient, accessToken, refreshToken: newRefreshToken } =
// Example request
await refreshedClient.v2.me();
```

### Optional: migrate OAuth 1.0a users to OAuth 2.0

Users who authorized your app with OAuth 1.0a can get OAuth 2.0 tokens without logging in again.
`.exchangeOAuth1Token()` trades their access token and secret for an OAuth 2.0 access token and refresh token, with the scopes that match their OAuth 1.0a permissions ([X docs](https://docs.x.com/fundamentals/authentication/oauth-2-0/oauth-1-0a-token-exchange)).

Create the client with your OAuth 2.0 client ID, plus the client secret for a confidential client.

```ts
const client = new TwitterApi({ clientId: '<YOUR-CLIENT-ID>', clientSecret: '<YOUR-CLIENT-SECRET>' });

// Obtain the {accessToken} and {accessSecret} of the user from your DB/store
const { client: oauth2Client, accessToken: newAccessToken, refreshToken } = await client.exchangeOAuth1Token({ accessToken, accessSecret });

// Store {newAccessToken} and {refreshToken}, then refresh them with .refreshOAuth2Token()
await oauth2Client.v2.me();
```

Exchanging the same OAuth 1.0a token again gives a new token pair and invalidates the previous one.
47 changes: 47 additions & 0 deletions doc/streaming.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,10 @@ The v1.1 streaming endpoints are no longer available on most X API plans, so the
* [Search endpoint](#search-endpoint)
* [Search endpoint - Get applied rules](#search-endpoint---get-applied-rules)
* [Search endpoint - Add or delete rules](#search-endpoint---add-or-delete-rules)
* [Search endpoint - Count rules](#search-endpoint---count-rules)
* [Sample endpoint](#sample-endpoint-1)
* [Sample 10% endpoint](#sample-10-endpoint)
* [Streaming connections](#streaming-connections)
* [Make a custom request](#make-a-custom-request)
* [`TweetStream` reference](#tweetstream-reference)
* [Methods / properties](#methods--properties)
Expand Down Expand Up @@ -236,6 +238,25 @@ const deleteRules = await client.v2.updateStreamRules({
await client.v2.updateStreamRules({}, { delete_all: true });
```

### Search endpoint - Count rules

Method: **`v2.streamRuleCounts`**.

Endpoint: `tweets/search/stream/rules/counts (GET)`.

Reference: https://docs.x.com/x-api/stream/get-stream-rule-counts

Level: **App-only** (Bearer auth).

Returns: **`StreamingV2RuleCountsResult`**.

```ts
const client = ...; // (create a Bearer OAuth2 client)

const { data: counts } = await client.v2.streamRuleCounts();
console.log(`${counts.project_rules_count} rules, ${counts.cap_per_project} at most`);
```

### Sample endpoint

Only available on X Enterprise plans ([X docs](https://docs.x.com/x-api/posts/volume-streams/introduction)).
Expand Down Expand Up @@ -285,6 +306,32 @@ stream.on(ETwitterStreamEvent.Data, console.log);
await stream.connect({ autoReconnect: true });
```

### Streaming connections

List the streaming connections of your app (active, past or both), and close them.
Useful when a stream fails to connect because a previous connection is still open.

Methods: **`v2.streamConnections`**, **`v2.terminateAllStreamConnections`** and **`v2.terminateStreamConnections`**.

Endpoints: `connections (GET)`, `connections/all (DELETE)` and `connections/:endpoint_id (DELETE)`.

Reference: https://docs.x.com/x-api/connections/get-connection-history

Level: **App-only** (Bearer auth).

Takes: **`StreamingV2ConnectionsParams`** (for `streamConnections`) or a `TStreamingV2ConnectionEndpoint`, like `'filtered_stream'` (for `terminateStreamConnections`).
Returns: **`StreamingV2ConnectionsResult`** or **`StreamingV2TerminateConnectionsResult`**.

```ts
const client = ...; // (create a Bearer OAuth2 client)

const { data: connections } = await client.v2.streamConnections({ status: 'active' });

// Close the connections to the filtered stream, or every connection of the app
await client.v2.terminateStreamConnections('filtered_stream');
await client.v2.terminateAllStreamConnections();
```

## Make a custom request

If you know endpoint and parameters (or you don't want them to be parsed),
Expand Down
Loading
Loading