From 176059c1d1c15b5359508603ae057115f7b04146 Mon Sep 17 00:00:00 2001
From: Siddharth VP <siddharthvp@gmail.com>
Date: Fri, 16 Oct 2020 14:15:27 +0530
Subject: [PATCH] update README, still very outdated

---
 README.md | 37 ++++++++++++++++++++++++++-----------
 1 file changed, 26 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index a82bd79..a44178a 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,9 @@
 # mwn
+[![NPM version](https://img.shields.io/npm/v/mwn.svg)](https://www.npmjs.com/package/mwn)
 
 **mwn** is a modern MediaWiki bot framework in NodeJS, orginally adapted from [mwbot](https://github.com/Fannon/mwbot).
 
-Development status: **Unstable**. Versioning: while mwn is in version 0, changes may be made to the public interface with a change in the minor version number.
+Development status: Unstable. Versioning: while mwn is in version 0, changes may be made to the public interface with a change in the minor version number.
 
 Documentation given below is incomplete. There are a number of additional classes such as `bot.title`, `bot.wikitext`, `bot.page`, etc that provide useful functionality but aren't documented. 
 
@@ -35,9 +36,14 @@ export PATH=~/bin:$PATH
 ```
 Check that your `.profile` or `.bashrc` file includes the line `PATH="$HOME/bin:$PATH"`, so that the path includes your home directory every time you open the shell.
 
-#### Set up a bot password
+#### MediaWiki version
+mwn is written for and tested on the latest version of MediaWiki used on WMF wikis.
 
-To be able to login to the wiki, you have to set up a bot password using the wiki's [Special:BotPasswords](https://en.wikipedia.org/wiki/Special:BotPasswords) page.
+#### Set up a bot password or OAuth credentials
+
+mwn supports authentication via both BotPasswords and via OAuth. Use of OAuth is recommended as it does away the need for separate API requests for logging in, and is also a bit more secure. 
+
+Bot passwords may be a bit easier to set up. To generate one, go to the wiki's [Special:BotPasswords](https://en.wikipedia.org/wiki/Special:BotPasswords) page. 
 
 If you're migrating from mwbot, note that:
 - `edit` in mwbot is different from `edit` in mwn. You want to use `save` instead.
@@ -47,18 +53,27 @@ If you're migrating from mwbot, note that:
 
 Create a new bot instance:
 ```js
-const bot = new mwn();
+const bot = new mwn({
+    apiUrl: 'https://en.wikipedia.org/w/api.php',
+    username: 'YourBotUsername',
+    password: 'YourBotPassword'
+});
+await bot.login();
 ```
-
-Log in to the bot:
+Or to use OAuth:
 ```js
-bot.login({
-	apiUrl: 'https://en.wikipedia.org/w/api.php',
-	username: 'YourBotUsername',
-	password: 'YourBotPassword'
+const bot = new mwn({
+    apiUrl: 'https://en.wikipedia.org/w/api.php',
+	oauth_consumer_token: "16_DIGIT_ALPHANUMERIC_KEY",
+	oauth_consumer_secret: "20_DIGIT_ALPHANUMERIC_KEY",
+	oauth_access_token: "16_DIGIT_ALPHANUMERIC_KEY",
+	oauth_access_secret: "20_DIGIT_ALPHANUMERIC_KEY"
 });
+bot.initOAuth(); // does not involve an API call
+// Any errors in authentication will surface when the first actual API call is made
 ```
 
+
 Set default parameters to be sent to be included in every API request:
 ```js
 bot.setDefaultParams({
@@ -271,4 +286,4 @@ bot.seriesBatchOperation(pageList, (page, idx) => {
 	// return a promise in the end
 }, 5000, 2); // set the sleep duration in milliseconds as the third parameter, max number of retries for each action is set as the 4th parameter
 ```
-Note that `seriesBatchOperation` with delay=0 is same as `batchOperation` with concurrency=1.
\ No newline at end of file
+Note that `seriesBatchOperation` with delay=0 is same as `batchOperation` with concurrency=1.