A CLI tool and an API for fetching data from Twitter for free!
It is recommended to install the package globally, if you want to use it from the CLI. Use the following steps to install the package and ensure it's installed correctly:
npm install -g rettiwt-api.rettiwt help.For using the package in your own project, you can install it as a dependency.
Rettiwt-API can be used with or without logging in to Twitter. As such, the two authentication strategies are:
'guest' authentication (without logging in) grants access to the following resources/actions:
'user' authentication (logging in) grants access to the following resources/actions:
By default, Rettiwt-API uses 'guest' authentication. If however, access to the full set of resources is required, 'user' authentication can be used. This is done by using the cookies associated with your Twitter/X account, and encoding them into an API_KEY for convenience. For getting the said API_KEY, there are two approaches:
Get Key button, this will generate the API_KEY and will show up in the text-area.API_KEY by either clicking on the Copy Key button or manually from the text-area.API_KEY still remains valid.API_KEY for use.Get API Key button, this will generate the API_KEY and will show up in the text-area.API_KEY by either clicking on the Copy API Key button or manually from the text-area.API_KEY still remains valid.API_KEY for use.API_KEY created in this way should last 5 years from the date of login, as long as the credentials to the account aren't changed.API_KEY to last only as long as the Twitter/X account isn't logged out of (you may exit the browser as usual) or 5 years, whichever comes first. That's why it's recommended to use incognito/in-private mode, so that the API_KEY isn't accidentially revoked by logging out.Open a terminal.
Generate an API_KEY using the command rettiwt auth login "<email>" "<username>" "<password>"
Here,
<email> is the email of the Twitter account to be used for authentication.<username> is the username associated with the Twitter account.<password> is the password to the Twitter account.Store the output API_KEY in a secure place for later use.
API_KEY created in this way expires after one year from the day it was generated.The API_KEY generated by logging in is what allows Rettiwt-API to authenticate as a logged in user while interacting with the Twitter API ('user' authentication). As such it is a very sensitive information and therefore, must be stored securely. The following points must be kept in mind while using the API_KEY for 'user' authentication:
Rettiwt-API can be used as a dependency for your NodeJS project. In such a case, it is not required to install Rettiwt-API globally and you may install it locally in the root of your project using the command:
npm install --save rettiwt-api (using npm)
or
yarn add rettiwt-api (using yarn)
However, in this case, for accessing the CLI, you will be required to prepend the CLI commands with npx in order to tell NodeJS to use the locally installed package.
For example, for generating the API_KEY, the command will be modified as follows:
npx rettiwt auth login <email> <username> <password>
When used as a dependency, the Rettiwt class is entry point for accessing the Twitter API.
A new Rettiwt instance can be initialized using the following code snippets:
const rettiwt = new Rettiwt() (for 'guest' authentication)const rettiwt = new Rettiwt({ apiKey: API_KEY }) (for 'user' authentication)The Rettiwt class has three members:
auth memeber, for managing authenticationtweet member, for accessing resources related to tweetsuser member, for accessing resources related to usersFor details regarding usage of these members for accessing the Twitter API, refer to Features.
The following examples may help you to get started using the library:
import { Rettiwt } from 'rettiwt-api';
// Creating a new Rettiwt instance
// Note that for accessing user details, 'guest' authentication can be used
const rettiwt = new Rettiwt();
// Fetching the details of the user whose username is <username>
rettiwt.user.details('<username>')
.then(details => {
...
})
.catch(error => {
...
});
import { Rettiwt } from 'rettiwt-api';
// Creating a new Rettiwt instance using the API_KEY
const rettiwt = new Rettiwt({ apiKey: API_KEY });
/**
* Fetching the list of tweets that:
* - are made by a user with username <username>,
* - contain the words <word1> and <word2>
*/
rettiwt.tweet.search({
fromUsers: ['<username>'],
words: ['<word1>', '<word2>']
})
.then(data => {
...
})
.catch(err => {
...
});
For more information regarding the different available filter options, please refer to TweetFilter.
The previous example fetches the the list of tweets matching the given filter. Since no count is specified, in this case, a default of 20 such Tweets are fetched initially. The following example demonstrates how to use the cursor string obtained from the response object's next field, from the previous example, to fetch the next batch of tweets:
import { Rettiwt } from 'rettiwt-api';
// Creating a new Rettiwt instance using the API_KEY
const rettiwt = new Rettiwt({ apiKey: API_KEY });
/**
* Fetching the list of tweets that:
* - are made by a user with username <username>,
* - contain the words <word1> and <word2>
*
* 'data' is the response object received in the previous example.
*
* 'count' is a number less or equal to 20 (the quantity of tweets to return)
*/
rettiwt.tweet.search({
fromUsers: ['<username>'],
words: ['<word1>', '<word2>']
}, count, data.next.value)
.then(data => {
...
})
.catch(err => {
...
});
Sometimes, you might want to generate an API_KEY on the fly, in situations such as implementing Twitter login in your application. The following example demonstrates how to generate an API_KEY during runtime:
import { Rettiwt } from 'rettiwt-api';
// Creating a new Rettiwt instance
const rettiwt = new Rettiwt();
// Logging in an getting the API_KEY
rettiwt.auth.login('<email>', '<username>', '<password>')
.then(apiKey => {
// Use the API_KEY
...
})
.catch(err => {
console.log(err);
});
Where,
<email> is the email associated with the Twitter account to be logged into.<username> is the username associated with the Twitter account.<password> is the password to the Twitter account.For masking of IP address using a proxy server, use the following code snippet for instantiation of Rettiwt:
/**
* PROXY_URL is the URL or configuration for the proxy server you want to use.`
*/
const rettiwt = new Rettiwt({ apiKey: API_KEY, proxyUrl: PROXY_URL });
This creates a Rettiwt instance which uses the given proxy server for making requests to Twitter.
When using this library in an application deployed in a cloud environment, the library might throw error 429, even when under rate limits. This happens because Twitter's v1.1 API endpoints seemingly blocks access from cloud services' IP ranges. These v1.1 API endpoints are the ones used for authentication and as such, authentication tasks are blocked while deployed on cloud environments.
This issue can be bypassed by using a proxy only for authentication, using the following code snippet for creating a new Rettiwt instance:
const rettiwt = new Rettiwt({ authProxyUrl: PROXY_URL });
Where,
PROXY_URL is the URL to the proxy server to use.Authentication proxy is required only in the following two scenarios:
Sometimes, when the library shows unexpected behaviour, for troubleshooting purposes, debug logs can be enabled which will help in tracking down the issue and working on a potential fix. Currently, debug logs are printed to the console and are enabled by setting the 'logging' property of the config to true, while creating an instance of Rettiwt:
/**
* By default, is no value for 'logging' is supplied, logging is disabled.
*/
const rettiwt = new Rettiwt({ apiKey: API_KEY, logging: true });
Rettiwt-API also provides direct access to the raw response data, bypassing any preprocessing by the library itself. This can be achieved by using the FetcherService class instead of the Rettiwt class, as demonstrated by the example below, which fetches the raw details of a user with the username 'user1':
import { FetcherService, EResourceType } from 'rettiwt-api';
// Creating a new FetcherService instance
const fetcher = new FetcherService({ apiKey: API_KEY });
// Fetching the details of the given user
fetcher
.request(EResourceType.USER_DETAILS_BY_USERNAME, { id: 'user1' })
.then((res) => {
console.log(res);
})
.catch((err) => {
console.log(err);
});
import { FetcherService, EResourceType, IUserDetailsResponse } from 'rettiwt-api';
// Creating a new FetcherService instance
const fetcher = new FetcherService({ apiKey: API_KEY });
// Fetching the details of the given user
fetcher
.request<IUserDetailsResponse>(EResourceType.USER_DETAILS_BY_USERNAME, { id: 'user1' })
.then((res) => {
console.log(res);
})
.catch((err) => {
console.log(err);
});
As demonstrated by the example, the raw data can be accessed by using the request method of the FetcherService class, which takes two parameters. The first parameter is the name of the requested resource, while the second is an object specifying the associated arguments required for the given resource. The complete list of resource type can be checked here. As for the resource specific argurments, they are the same as that of the methods of Rettiwt class' methods for the respective resources, but structured as an object. Notice how the FetcherService class takes the same arguments as the Rettiwt class, and the arguments have the same effects as they have in case of Rettiwt class.
So far, the following operations are supported:
Rettiwt-API provides an easy to use command-line interface which does not require any programming knowledge.
By default, the CLI operates in 'guest' authentication. If you want to use 'user' authentication:
rettiwt -k <API_KEY> <command>Help for the CLI can be obtained from the CLI itself:
rettiwt helprettiwt help <command_name>The complete API reference can be found at this page.
Support this project by donating at my PayPal.
Generated using TypeDoc