rettiwt-api 2.4.0 → 2.4.2

package/README.md

@@ -1,15 +1,23 @@
 # Rettiwt-API
 
-An API for fetching data from Twitter for free!
+A CLI tool and an API for fetching data from Twitter for free!
 
 ## Prerequisites
 
 -   NodeJS 20.10.0
--   A working Twitter account
+-   A working Twitter account (optional)
 
-## Types of Authentication
+## Installation
+
+It is recommended to install the package globally. Use the following steps to install the package and ensure it's installed correctly:
+
+1. Open a terminal.
+2. Install the package using the command `npm install -g rettiwt-api`.
+3. Check if the package is installed correctly using the command `rettiwt help`.
 
-Rettiwt can be used with or without logging in to Twitter. As such, the two authentication strategies are:
+## Authentication
+
+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:
 
@@ -32,43 +40,62 @@ Rettiwt can be used with or without logging in to Twitter. As such, the two auth
     -   User Timeline (tweets timeline)
     -   User Replies (replies timeline)
 
+By default, Rettiwt-API uses 'guest' authentication. If however, access to the full set of resources is required, 'user' authentication can be used, which requires the following additional steps post-installtion:
+
+1. Open a terminal.
+2. 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 associtated with the Twitter account.
+    - \<password\> is the password to the Twitter account.
+
+3. The string returned after running the command is the API_KEY. Store it in a secure place for later use.
+
+## The API_KEY
+
+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:
+
+-   The API_KEY is generated by logging into Twitter using the email, username and password and encoding the returned cookies as a base64 string. This encoded string is the API_KEY.
+-   The API_KEY provides the same level of authorization as any standard Twitter account, nothing more, nothing less.
+-   Since generation of API_KEY is equivalent to logging in to Twitter, repeated generation attempts might trigger Twitter's anti-bot measures, the same way repeated login attempts do.
+-   The API_KEY expires after one year from the day it was generated.
+-   Therefore, it is recommended to generate the API_KEY only once, then use it every time it is needed.
+-   Do not generate an API_KEY if it has not expired yet!
+
 ## Notes for non-programmers
 
 -   If you have no idea of programming, it's recommended to use the CLI.
 -   The CLI provides an easy to use interface which does not require any knowledge of JavaScript or programming
 -   Please skip to 'CLI-Usage' section for details.
 
-## Installation
+## Usage as a dependency
 
-1. Initialize a new Node.JS project using the command `npm init`.
-2. Install the package either via npm or yarn:
-    - For npm, use the command `npm install --save rettiwt-api`
-    - For yarn, use the command `yarn add rettiwt-api`
+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:
 
-Although the above process initializes a new project, that is, in fact, not necessary and you may add it to an existing Node.JS project and omit the first step altogether.
+-   `npm install --save rettiwt-api` (using npm)
 
-## Getting started
+    or
 
-1. Generate credentials using the command `npx rettiwt auth login <email> <username> <password>` in a terminal in the root of your project.
-2. The generated string is the API_KEY.
-3. Create a new instance of Rettiwt, passing in the API key as a config object:  
-   `const rettiwt = Rettiwt({ apiKey: API_KEY });`  
-   The available options in the config object can be found [here](https://rishikant181.github.io/Rettiwt-API/classes/RettiwtConfig.html).
-4. Use the created [Rettiwt](https://rishikant181.github.io/Rettiwt-API/classes/Rettiwt.html) instance to fetch data from Twitter.
+-   `yarn add rettiwt-api` (using yarn)
 
-**Notes:**
+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.
 
--   The API_KEY that we generated, is a very sensitive information and provides all access to the Twitter account. Therefore, it is generally recommended to store it as an environment variable and use it from there.
+For example, for generating the API_KEY, the command will be modified as follows:
 
--   The given example above uses 'user' authentication by using an API_KEY generated from the Twitter account.
+`npx rettiwt auth login <email> <username> <password>`
 
--   It's also possible to use this package without using a Twitter account, by omitting the 'apiKey' parameter in the config object. However, in this case, 'guest' authentication is used.
+## The Rettiwt class
 
-## The 'Rettiwt' class
+When used as a dependency, the Rettiwt class is entry point for accessing the Twitter API.
 
-The 'Rettiwt' class is entry point for accessing the Twitter API.
+A new Rettiwt instance can be initialized using the following code snippets:
 
-The 'Rettiwt' class has two members:
+-   `const rettiwt = new Rettiwt()` (for 'guest' authentication)
+-   `const rettiwt = new Rettiwt({ apiKey: API_KEY })` (for 'user' authentication)
+
+The Rettiwt class has two members:
 
 -   'tweet' member, for accessing resources related to tweets
 -   'user' member, for accessing resources related to users
@@ -84,8 +111,9 @@ The following examples may help you to get started using the library:
 ```js
 const { Rettiwt } = require('rettiwt-api');
 
-// Creating a new Rettiwt instance using the API_KEY
-const rettiwt = new Rettiwt({ apiKey: API_KEY });
+// 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>')
@@ -203,34 +231,25 @@ So far, the following operations are supported:
 
 ## CLI Usage
 
-Rettiwt-API also provides an easy to use command-line interface which does not require any programming knowledge.
-
-### Installation
-
-1. Install the recommended version of NodeJS specified in the 'Prerequisites' section.
-2. Open a terminal.
-3. Install the package globally using the command `npm install -g rettiwt-api`.
-4. Use the command `rettiwt help` to ensure that the package has been installed correctly.
-
-### Authentication
+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:
 
-1. Generate an API_KEY using the command `rettiwt auth login <email> <username> <password>`.
+1. Generate an API_KEY as described in 'Authentication' section.
 2. Store the output API_KEY as an environment variable with the name 'API_KEY'.
     - Additionaly, store the API_KEY in a file for later use.
     - Make sure to generate an API_KEY only once, and use it every time you need it.
 3. The CLI automatically reads this environment variable to authenticate against Twitter.
     - Additionaly, the API_KEY can also be passed in manually using the '-k' option as follows: `rettiwt -k <API_KEY> <command>`
 
-### Help
+Help for the CLI can be obtained from the CLI itself:
 
 -   For help regarding the available commands, use the command `rettiwt help`
 -   For help regarding a specific command, use the command `rettiwt help <command_name>`
 
 ## API Reference
 
-The complete API reference can be found at [this](https://rishikant181.github.io/Rettiwt-API/) page.
+The complete API reference can be found at [this](https://rishikant181.github.io/Rettiwt-API/modules) page.
 
 ## Additional information
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "rettiwt-api",
-	"version": "2.4.0",
+	"version": "2.4.2",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
 	"description": "An API for fetching data from TwitterAPI, without any rate limits!",