refactor(captcha): use seconds instead of ms (#2424)

Also adds missing nav link for captcha reference and adds more usage information.

docs/reference/captcha.md

@@ -7,7 +7,14 @@ A mechanism has been implemented to allow users to interactively handle captcha
 
 ## How to use
 
-To use this feature, simply configure the variables shown below and then start your streetmerchant instance.
+To use this feature, you will have to set up a bot user on your desired messaging service (see the [FAQ](#how-do-I-obtain-a-token-for) for more help). Once that's complete and you have the token for the bot, simply configure the variables shown below and then start your streetmerchant instance.
+
+???+ attention 
+    When a DM is received, you must reply to the message directly. In Slack, this is done by clicking the "reply to thread" button on the bot's DM, and sending a response in the thread panel that appears. In Discord, you simply click "Reply" on the bot's DM and type your response in the input field (you will see "Replying to [bot user name]" above the input field).
+
+    If you send a reply back to the bot without associating the response to a message as described above, the bot will not receive the input.
+
+    Please make use of the [testing command below](#testing) to get the hang of how this works.
 
 ## Testing
 
@@ -20,11 +27,11 @@ You can test your notification configuration by running `npm run test:captcha`.
 
 | Environment variable | Description |
 |---|---|
-| `CAPTCHA_HANDLER_POLL_INTERVAL` | Interval (in milliseconds) at which streetmerchant will check if the user has responded. Default: `5000` (5 seconds) |
-| `CAPTCHA_HANDLER_RESPONSE_TIMEOUT` | Timeout (in milliseconds) duration, after which streetmerchant will assume the user is unavailable and continue to the next page. Default: `300000` (5 minutes) |
+| `CAPTCHA_HANDLER_POLL_INTERVAL` | Interval (in seconds) at which streetmerchant will check if the user has responded. Default: `5` |
+| `CAPTCHA_HANDLER_RESPONSE_TIMEOUT` | Timeout (in seconds) duration, after which streetmerchant will assume the user is unavailable and continue to the next page. Default: `300` (5 minutes) |
 | `CAPTCHA_HANDLER_SERVICE` | [Supported messaging service](#supported-messaging-services) to use for the captcha handler |
-| `CAPTCHA_HANDLER_TOKEN` | Token to identify the bot user of the selected messaging service. See the [FAQ](#faq) for information on where to obtain this. |
-| `CAPTCHA_HANDLER_USER_ID` | ID representing _your account_ in the selected messaging service. The account specified here will receive the bot's DMs. See the [FAQ](#faq) for information on where to obtain this. |
+| `CAPTCHA_HANDLER_TOKEN` | Token to identify the bot user of the selected messaging service. See the [FAQ](#how-do-I-obtain-a-token-for) for information on where to obtain this. |
+| `CAPTCHA_HANDLER_USER_ID` | ID representing _your account_ in the selected messaging service. The account specified here will receive the bot's DMs. See the [FAQ](#how-do-I-obtain-my-user-ID-for) for information on where to obtain this. |
 
 ???+ info
     The poll interval is 5 seconds so that the bot doesn't get rate-limited trying to check for responses (plus let's be honest, it's only 5 seconds at most).
@@ -41,7 +48,7 @@ You can test your notification configuration by running `npm run test:captcha`.
 
 ## FAQ
 
-### How do I obtain my user ID for <service name>?
+### How do I obtain my user ID for...?
 
 #### Slack
 
@@ -54,7 +61,7 @@ In the top-right corner of the app, click your avatar and select "View Profile"
 
 You have to enable Developer Mode in the Advanced settings. Once that's enabled, you can simply right-click your avatar in a thread or the member's list (on right side of screen) and click "Copy ID."
 
-### How do I obtain a token for <service name>?
+### How do I obtain a token for...?
 
 #### Slack
 
@@ -75,10 +82,14 @@ That isn't a question. This is an FAQ.
 
 Much better. This could either be a configuration error in streetmerchant (not completed, wrong values, etc) or the bot user isn't configured correctly in your messaging service. Double-check the configuration variables you've entered and use `npm run test:captcha` to help find out the root cause.
 
+### The bot doesn't do anything when I respond to the message and eventually times out. What's happening?
+
+When streetmerchant sends a message via Slack/Discord, it keeps a reference to that message and listens only for direct replies to it until either a response is obtained or the timeout threshold is reached. This allows the interactive captcha process to be used with multiple concurrent streetmerchant instances. Please review the warning in the [How to use](#how-to-use) section, which discusses specifically how to respond to the bot for a successful interaction.
+
 ### Why isn't captcha being detected on some of the stores I'm monitoring?
 
 Not sure, but we'll want to get that fixed! Submit an issue and we can look into it.
 
-### Will this work on every store?
+### Will this work on every store's captcha system?
 
-As it is, no. Currently this has only been tested/used for Amazon (North America) and this is where the vast majority of captcha complaints come from. If a store you're monitoring is giving your bot captcha pages, submit an issue so we can work on getting it integrated.
+Not likely. There are a plethora of captcha implementations that retailers can utilize to protect their sites. As of this writing, the interactive captcha handler has only been tested/used for Amazon (North America), and this is where the vast majority of captcha complaints come from. Any other store can implement a different captcha approach, and even Amazon can change their captcha at any time. All that said, if you're running into captcha issues with a store, submit an issue so we can work on a solution and getting it integrated, if possible.

mkdocs.yml

@@ -82,6 +82,7 @@ nav:
   - Getting started: getting-started.md
   - Reference:
     - Application: reference/application.md
+    - Captcha: reference/captcha.md
     - Filter: reference/filter.md
     - Notification: reference/notification.md
     - Proxy: reference/proxy.md

src/config.ts

@@ -202,10 +202,10 @@ const browser = {
 };
 
 const captchaHandler = {
-  pollInterval: envOrNumber(process.env.CAPTCHA_HANDLER_POLL_INTERVAL, 5000),
+  pollInterval: envOrNumber(process.env.CAPTCHA_HANDLER_POLL_INTERVAL, 5),
   responseTimeout: envOrNumber(
     process.env.CAPTCHA_HANDLER_RESPONSE_TIMEOUT,
-    300000
+    300
   ),
   service: envOrString(process.env.CAPTCHA_HANDLER_SERVICE),
   token: envOrString(process.env.CAPTCHA_HANDLER_TOKEN),

src/messaging/discord.ts

@@ -122,7 +122,7 @@ export async function getDMResponseAsync(
   botMessage: Discord.Message | undefined,
   timeout: number
 ): Promise<string> {
-  const iterations = Math.max(timeout / pollInterval, 1);
+  const iterations = Math.max(Math.floor(timeout / pollInterval), 1);
   let iteration = 0;
   const client = await getDiscordClientAsync();
   const dmChannel = await getDMChannelAsync(client);
@@ -161,7 +161,7 @@ export async function getDMResponseAsync(
         logger.error("✖ couldn't get captcha response", error);
         return finish(response);
       }
-    }, pollInterval);
+    }, pollInterval * 1000);
   });
 }
 

src/messaging/slack.ts

@@ -72,7 +72,7 @@ export async function getDMResponseAsync(
   dmId: any,
   timeout: number
 ): Promise<string> {
-  const iterations = Math.max(timeout / pollInterval, 1);
+  const iterations = Math.max(Math.floor(timeout / pollInterval), 1);
   let iteration = 0;
   return new Promise(resolve => {
     let response = '';
@@ -132,7 +132,7 @@ export async function getDMResponseAsync(
 
         return finish(response);
       }
-    }, pollInterval);
+    }, pollInterval * 1000);
   });
 }
 

test/functional/test-captcha.ts

@@ -3,6 +3,6 @@ import {getCaptchaInputAsync} from '../../src/messaging';
 (async () => {
   await getCaptchaInputAsync(
     'test https://images-na.ssl-images-amazon.com/captcha/kwizfixk/Captcha_xpdfshjvsb.jpg',
-    30000
+    30
   );
 })();