Humansecurity RTD Provider: migrate to TypeScript and optimize token handling

dev-docs/modules/humansecurityRtdProvider.md

@@ -1,46 +1,33 @@
----
-layout: page_v2
-title: HUMAN Security Realtime Data Submodule
-display_name: HUMAN Security RTD Submodule
-description: The HUMAN Security RTD Submodule offers publishers a mechanism to integrate pre-bid signal collection for the purpose of providing real-time protection against all sorts of invalid traffic.
-page_type: module
-module_type: rtd
-module_code : humansecurity
-enable_download : true
-vendor_specific: true
-sidebarType : 1
----
-
-# HUMAN Security Real-time Data Submodule
-{:.no_toc}
-
-* TOC
-{:toc}
-
-## Overview
+# Overview
+
+```text
+Module Name: HUMAN Security Rtd provider
+Module Type: Rtd Provider
+Maintainer: alexey@humansecurity.com
+```
+
+## What is it?
 
 The HUMAN Security RTD submodule offers publishers a mechanism to integrate pre-bid signal collection
 for the purpose of providing real-time protection against all sorts of invalid traffic,
 such as bot-generated ad interactions or sophisticated ad fraud schemes.
 
-### How does it work?
+## How does it work?
 
 HUMAN Security RTD submodule generates a HUMAN Security token, which then can be consumed by adapters,
 sent within bid requests, and used for bot detection on the backend.
 
-### Key Facts about the HUMAN Security RTD Submodule
+## Key Facts about the HUMAN Security RTD Submodule
 
 * Enriches bid requests with IVT signal, historically done post-bid
 * No incremental signals collected beyond existing HUMAN post-bid solution
 * Offsets negative impact from loss of granularity in IP and User Agent at bid time
 * Does not expose collected IVT signal to any party who doesn’t otherwise already have access to the same signal collected post-bid
-* Does not introduce meaningful latency, as demonstrated in the Latency section
+* Does not introduce meaningful latency
 * Comes at no additional cost to collect IVT signal and make it available at bid time
 * Leveraged to differentiate the invalid bid requests at device level, and cannot be used to identify a user or a device, thus preserving privacy.
 
-{% include dev-docs/loads-external-javascript.md %}
-
-## Build
+# Build
 
 First, make sure to add the HUMAN Security submodule to your Prebid.js package with:
 
@@ -50,10 +37,10 @@ gulp build --modules="rtdModule,humansecurityRtdProvider,..."
 
 > `rtdModule` is a required module to use HUMAN Security RTD module.
 
-## Configuration
+# Configuration
 
 This module is configured as part of the `realTimeData.dataProviders` object.
-Please refer to [Prebid Documentation](/dev-docs/publisher-api-reference/setConfig.html#setConfig-realTimeData)
+Please refer to [Prebid Documentation](https://docs.prebid.org/dev-docs/publisher-api-reference/setConfig.html#setConfig-realTimeData)
 on RTD module configuration for details on required and optional parameters of `realTimeData`.
 
 By default, using this submodule *does not require any prior communication with HUMAN, nor any special configuration*,
@@ -69,8 +56,8 @@ pbjs.setConfig({
 });
 ```
 
-It can be optionally parameterized, for example, to include client ID obtained from HUMAN,
-should any advanced reporting be needed, or to have verbose output for troubleshooting:
+Other parameters can also be provided. For example, a client ID obtained from HUMAN can
+optionally be provided, or verbose output can be enabled for troubleshooting purposes:
 
 ```javascript
 pbjs.setConfig({
@@ -86,15 +73,15 @@ pbjs.setConfig({
 });
 ```
 
-### Supported parameters
+## Supported parameters
 
-{: .table .table-bordered .table-striped }
-| Name             |Type           | Description                                                         | Required |
-| :--------------- | :------------ | :------------------------------------------------------------------ |:---------|
-| `clientId`  | String | Should you need advanced reporting, contact [prebid@humansecurity.com](prebid@humansecurity.com) to receive client ID. | No |
-| `verbose`   | Boolean | Only set to `true` if troubleshooting issues. | No |
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | -------- |
+| `clientId` | String | Should you need advanced reporting, contact [prebid@humansecurity.com](prebid@humansecurity.com) to receive client ID. | No |
+| `verbose` | Boolean | Only set to `true` if troubleshooting issues. | No |
+| `perBidderOptOut` | string[] | Pass any bidder alias to opt-out from per-bidder signal generation. | No |
 
-### Logging, latency and troubleshooting
+## Logging, latency and troubleshooting
 
 The optional `verbose` parameter can be especially helpful to troubleshoot any issues and/or monitor latency.
 
@@ -103,9 +90,6 @@ of type `ERROR`. With `verbose` parameter set to `true`, it may additionally:
 
 * Call `logWarning`, resulting in `auctionDebug` events of type `WARNING`,
 * Call `logInfo` with latency information.
-  * To observe these messages in console, Prebid.js must be run in
-    [debug mode](/dev-docs/publisher-api-reference/setConfig.html#debugging) -
-    either by adding `?pbjs_debug=true` to your page's URL, or by configuring with `pbjs.setConfig({ debug: true });`
 
 Example output of the latency information:
 
@@ -119,16 +103,16 @@ and the total time required to obtain the signals, respectively. Note that "time
 for all the time spent since the script has started initializing until the signals were made available to the bidders,
 therefore it includes "time to init", and typically some non-blocking time spent waiting for signals. Only “time to init” is blocking.
 
-## How can I contribute?
+# How can I contribute?
 
 Prebid has launched a Measurement Taskforce to address signal deprecation and measurement in the current environment,
 which has become a publisher-level issue. Without a solution, granularity of measurement disappears.
 If you would like to participate to help identify and develop solutions to these problems such as the one tackled
 by this submodule, please consider joining the [Measurement Taskforce](https://prebid.org/project-management-committees/).
 
-## Notes
+# Notes
 
-### Operation model
+## Operation model
 
 Following is the expected data flow:
 
@@ -141,7 +125,7 @@ Following is the expected data flow:
   * Should bid requests be passed to other platforms during the bidding process, adapter developers are
     encouraged to keep `ortb2.device.ext.hmns` so that, for example, a downstream DSP can also have this data passed to HUMAN.
 
-### Remarks on the collected signals
+## Remarks on the collected signals
 
 There are a few points that are worth being mentioned separately, to avoid confusion and unnecessary suspicion:
 
@@ -153,8 +137,9 @@ There are a few points that are worth being mentioned separately, to avoid confu
   the ever-evolving nature of the threat landscape without the publishers having to rebuild their Prebid.js frequently.
   * The signal collection script is also obfuscated, as a defense-in-depth measure in order to complicate tampering by
     bad actors, as are all similar scripts in the industry, which is something that cannot be accommodated by Prebid.js itself.
+* The collected signals are encrypted before they are passed to bid adapters and can only be interpreted by HUMAN backend systems.
 
-### Why is this approach an innovation?
+## Why is this approach an innovation?
 
 Historically, IVT protection is achieved via dropping analytics scripts and/or pixels in the ads, which enriches impression data with collected signals.
 Those signals, when analyzed by IVT protection vendors, allow distinguishing valid from invalid traffic, but only retroactively -
@@ -176,7 +161,7 @@ collection that is typically performed post-bid, but at the pre-bid stage, and m
 This not only permits for accurate invalid traffic detection at the earliest stages of the auction process, but diminishes
 the impacts of signal deprecation such as the loss of IP and User Agent on effective fraud mitigation.
 
-### Why is this good for publishers?
+## Why is this good for publishers?
 
 In the process of Invalid Traffic reconciliation, publishers are often the last to know, as they are informed by their downstream
 partners that the inventory they had provided in good faith has been detected as invalid traffic. This is most painful when it
@@ -211,26 +196,27 @@ Finally, the HUMAN Security RTD submodule sets the ecosystem up for a future whe
 This will allow for increased transparency about what is happening with publisher inventory, further enhancing and
 ensuring the value of the inventory.
 
-### FAQ
+## FAQ
 
-#### Is latency an issue?
+### Is partnership with HUMAN required to use the submodule?
 
-The HUMAN Security RTD submodule is designed to minimize any latency in the auction within normal SLAs.
+No. Using this submodule does not require any prior communication with HUMAN or being a client of HUMAN.
+It is free and usage of the submodule doesn’t automatically make a Publisher HUMAN client. 
+
+### Is latency an issue?
 
-#### Do publishers get any insight into how the measurement is judged?
+The HUMAN Security RTD submodule is designed to minimize any latency in the auction within normal SLAs.
+### Do publishers get any insight into how the measurement is judged?
 
 Having the The HUMAN Security RTD submodule be part of the prebid process will allow the publisher to have insight
 into the invalid traffic metrics as they are determined and provide confidence that they are delivering quality
 inventory to the buyer.
 
-#### How are privacy concerns addressed?
-
-The HUMAN Security RTD submodule seeks to reduce the impacts from signal deprecation that are inevitable without
-compromising privacy by avoiding re-identification. Each bid request is enriched with just enough signal
-to identify if the traffic is invalid or not.
+### How are privacy concerns addressed?
 
-By having the The HUMAN Security RTD submodule operate at the Prebid level, data can be controlled
-and not as freely passed through the bidstream where it may be accessible to various unknown parties.
+The HUMAN Security RTD submodule seeks to reduce the impacts of signal deprecation without compromising privacy.
+Each bid request is enriched with just enough signal to identify if the traffic is invalid or not, and these
+signals are encrypted before being included in bid requests to prevent misuse.
 
 Note: anti-fraud use cases typically have carve outs in laws and regulations to permit data collection
 essential for effective fraud mitigation, but this does not constitute legal advice and you should