################################################################################
Twitch Subscription Tracker
--------------------------------------------------------------------------------

This script tries to track the total amount of subscriptions commited to the
channel and the amount of gifted subscriptions gifted to others a viewer has
done, both with individual tier tracking records as well.

Due to small limitations of Streamlabs Chatbot Python Scripts the chatbot must
be connected to the chat and the viewer needs to share his or her subscription
as this script is getting the info about a subscription form the Twitch IRC.

On a subscription or gift this script will automatically update or add the
viewer to the database with information it has at hand. For gifting it can only
know the the targets tiers gift and for subscribing it can detect a resub or a
new sub. If a resub is shared and that viewer is not yet in the database, all
prior concecutive months (minus 1) are considered tier 1 ($5) and the last
newest month is added to its respective tier. If this is incorrect however
manual adjustment is needed with build in chat commands to edit the database
entries to the right values. See further down below in this readme for the
command and its usage. Also if a viewer has manually be added but total months
is lower than the concecutive months the viewer has on resubscribing the script
will automatically adjust the total months by adding missing months to tier 1.

Name changes are automatically updated when the user (re)subscribes to the
channel. The usuable command parameters, pull out data from the database to be
used as command or currency response, use the username to identify the viewer.
So if a viewer that is in the database, did a name change, and not yet shared his
or her resubscription the values returned are 0.

The script logger (the [i] button under Scripts) will be used to show a status
message on success or failure on the automated database updating. If any
failures did happend, manual editing/adding the viewer is required.

All info is stored into a sqlite database that can be viewed or edited by
third-party programs like DB Browser (http://sqlitebrowser.org/) but the
chatbot has control over this database file as long as the chatbot is running.
If you use above mentioned program to edit the database contents make sure you
make the total months equal to all tier months added and you commit changes to
actually write back the changes to the database file.

Note; To simplify the script allot Prime subs are considered Tier 1 subs the
same as a $5 subs. In reallity this should not matter as they are the same for
the caster in terms of value.

################################################################################
Commands
--------------------------------------------------------------------------------

!tst editsubs username tier1|tier2|tier3

  This command will edit the amount of subscribed months the viewer has in the
  database. If the username does not exists yet, the script will verify if the
  username exists on Twitch and will add new viewer to the database if it does.
  The total subscribed months are calculated by adding the months of tiers.

  username

    Username of the viewer to be edited or added. Can only contain lowercase
    letters, numbers and underscores. It cannot start with an underscore.

  tier1|tier2|tier3

    This argument denotes the amount of months the viewer has subscribed for of
    each tier. It has to contain all three tiers, so use 0 if the viewer has
    not subscribed at all with that tier.

  example; !tst editsubs ocgineer 4|0|2

    This will add or edit 'ocgineer' to the database with 6 total subscribed
    months. 4 of these months are tier1 subscriptions and 2 are a tier3 sub.

!tst editgifts username tier1|tier2|tier3

  This command will edit the amount of gifted subscription the viewer has done
  in the database. If the username does not exists yet, the script will verify
  if the username exists on Twitch and will add new viewer to the database if
  it does. 

  username

    Username of the viewer to be edited or added. Can only contain lowercase
    letters, numbers and underscores. It cannot start with an underscore.

  tier1|tier2|tier3

    This argument denotes the amount of subs the viewer has gifted of each tier.
    It has to contain all three tiers, so use 0 if the viewer has not gifted a
    particular tier.

  example; !tst editgifts ocgineer 4|1|0

    This will add or edit 'ocgineer' to the database with 5 gifted subs. 4 of
    these gifted subs are tier1 subs, and 1 is a tier2 sub.

!tst receivedsubs username amount

  This command will edit the amount of subscriptions the user has received from
  others as gift. This command can only edit existing users in the database so
  if it does not exists yet, please add the viewer first with one of the two
  commands described above.

  username

    Username of the viewer to be edited. Can only contain lowercase letters,
    numbers and underscores. It cannot start with an underscore.

  amount

    The amount of received gifted subs. Number only and cannot exceed the
    total amount of subscriptions the user has in the database.

  example; !tst receivedsubs ocgineer 2

    This will edit 'ocgineer' that it has received a total of 2 gifted subs.

################################################################################
Parameters
--------------------------------------------------------------------------------

If you want to have all tiers shown in a command please avoid the individual
tier parameters as that will read the database for each paramter used. Instead
use the included $tstSubbedTiers and $tstGiftedTiers to have all tiered and
totals information in one database read. The response of these parameters can be
customized in the scripts userinterface.

# Subscription Data
-------------------

$tstSubbedTotal

  When this parameter is used it will be replaced with the total subscribed
  months the viewer has. If the viewer is not in the database this parameter
  will return 0. This parameter only works if the viewer uses the command
  containing the parameter.

$tstSubbedT1

  When this parameter is used it will be replaced by the total tier1 months the
  viewer has subscribed for. If the viewer is not in the database this parameter
  will return 0. This parameter only works if the viewer uses the command
  containing the parameter. 

$tstSubbedT2

  When this parameter is used it will be replaced by the total tier2 months the
  viewer has subscribed for. If the viewer is not in the database this parameter
  will return 0. This parameter only works if the viewer uses the command
  containing the parameter. 

$tstSubbedT3

  When this parameter is used it will be replaced by the total tier3 months the
  viewer has subscribed for. If the viewer is not in the database this parameter
  will return 0. This parameter only works if the viewer uses the command
  containing the parameter. 

$tstSubbedTiers

  When this parameter is used it will be replaced by the set response in the
  userinterface of the scipt containing by default all respective tiers the
  viewer has subscribed for. If the viewer is not in the database all values
  are returned as 0. This paramter only works if the viewer uses the command
  containing the parameter. 

$tstReceivedTotal

  When this parameter is used it will be replaced by the total amount of
  subscribed months the viewer has received as gift. If the viewer is not in the
  database this parameter will return 0. This parameter only works if the viewer
  uses the command containing the parameter.

# Gifting Data
--------------

$tstGiftedTotal

  When this parameter is used it will be replaced with the total number of subs
  the viewer has given. If the viewer is not in the database this parameter
  will return 0. This parameter only works if the viewer uses the command
  containing the parameter.

$tstGiftedT1

  When this parameter is used it will be replaced by the total tier1 subs the
  viewer has gifted to another viewer. If the viewer is not in the database this
  parameter will return 0. This parameter only works if the viewer uses the
  command containing the parameter. 

$tstGiftedT2

  When this parameter is used it will be replaced by the total tier2 subs the
  viewer has gifted to another viewer. If the viewer is not in the database this
  parameter will return 0. This parameter only works if the viewer uses the
  command containing the parameter.

$tstGiftedT3

  When this parameter is used it will be replaced by the total tier3 subs the
  viewer has gifted to another viewer. If the viewer is not in the database this
  parameter will return 0. This parameter only works if the viewer uses the
  command containing the parameter.

$tstGiftedTiers

  When this parameter is used it will be replaced by the set response in the
  userinterface of the scipt containing by default all respective tiers the
  viewer has gifted. If the viewer is not in the database all values
  are returned as 0. This paramter only works if the viewer uses the command
  containing the parameter. 

# Top Lists
-----------

$tstTopSubbers

  When this parameter is used it will be replaced by a top list of subbers in
  order of total subscribed months (and secondary order of name). The amount of
  people to show in the top list can be set in the userinterface settings. The
  script also prevents the total response message to go over 500 characters. If
  that happens the top list is trunctuated so the rest of the response message
  stays intact.

$tstTopGifters

  When this parameter is used it will be replaced by a top list of gifters in
  order of total gifted subs (and secondary order of name). The amount of
  people to show in the top list can be set in the userinterface settings. The
  script also prevents the total response message to go over 500 characters. If
  that happens the top list is trunctuated so the rest of the response message
  stays intact.