Note that because some domains host multiple publishers,
a publisher identity may contain both a domain and a path separated by a solidus(/).

Also note that certain URLs aren't really appropriate for a publisher mapping.
For example,
if a URL returns a 302,
don't bother mapping that URL.

Terminology

Consider this URL:

https://foo.bar.example.com/component1/...?query

The label com from the URL's domain is a top-level domain (TLD),
and the string example.com is a second-level domain (SLD).
By convention,
the relative domain (RLD) is the string to the left of the SLD (e.g., foo.bar),
and the qualifying label (QLD) is the right-most label of the RLD (e.g., bar).

Mapping

Each rule in the array consists of an object with one mandatory property,
condition,
a JavaScript boolean expression.
In addition,
there is usually either a consequent property
(a JavaScript expression returning either a string, null, or undefined),
or a dom property.

To detetermine the publisher identity associated with a URL:

If the TLD associated with the URL's domain does not correspond to an infrastructure or ccTLD,
then the publisher identity is undefined.

The parsed object is extended with the URL, TLD, SLD, RLD, and QLD objects.
If there is no RLD, the empty string ("") is used for both the RLD and QLD.

If the dom.publisher property of the rule is present,
then the HTML associated with the URL must be present,
and one additional object is present during evaluation,
node, which is the result of jsdom(markup).body.querySelector(dom.publisher.nodeSelector),
and the dom.publisher.consequent property is used instead of the consequent property for the rule in Step 5.2.

Each rule is examined, in order, starting from the first element:

5.1. If the condition evaluates to false,
then execution continues with the next rule.

5.2. Otherwise,
the consequent is evaluated.

5.3. If the resulting value is the empty string (""),
then execution continues with the next rule.

5.4. If the resulting value is false, null or undefined,
then the publisher identity is undefined.

5.5. Otherwise,
the resulting value is used as the publisher identity.

If Step 5.5 is never executed,
then the publisher identity is undefined.

The initial rule set is built by a NPM script:

npm run build-rules

An initial rule set is available as:

require('ledger-publisher').ruleset

NB: THAT IN PREVIOUS VERSIONS OF THIS PACKAGE, THE PROPERTY WAS CALLEDrulesNOTruleset

Your Help is Needed!

in order to examine all the URLs you have visited in your current session (from the file session-store-1)
and see the resulting publisher identities.

Page Visits

A page visit is just what you'd expect,
but it requires both a URL and the duration of the focus (in milliseconds).
A synopsis is a collection of page visits that have been reduced to a a publisher and a score.
The synopsis includes a rolling window so that older visits are removed.

var synopsis = new (require('ledger-publisher').Synopsis)()
// each time a page is unloaded, record the focus duration
// markup is an optional third-parameter, cf., getPublisher above
synopsis.addVisit('URL', duration)
// addVisit is a wrapper around addPublisher
synopsis.addPublisher(publisher, props)

At present,
these properties are examined:

duration - the number of milli-seconds (mandatory)

markup - the HTML markup (optional)

In order to calculate the score,
options can be provided when creating the object.
The defaults are:

When addVisit is invoked,
the duration must be at least minPublisherDuration milliseconds in length.
If so,
then one or more "scorekeepers" are run to calculate the score for the visit,
using both the options and props.
At present,
there are two scorekeepers:

The Concave Scorekeeper

The concave scorekeeper rewards the publisher of a page according to:

a fixed bonus for the page hit

how much time the user spends on the page

The reward increases as the user spends more time on the page, but the model uses a
concave quadratic (utility) function to provide diminishing returns as the time spent
on the page increases. If we set the durationWeight parameter to zero, the model
only takes into account the page hit and ignores the time spent on the page when
calculating the reward.

Tuning

Scorekeepers may be "tuned" using options,
at present,
only the concave scorekeeper makes use of these.
The defaults are: