Account tracking in Eggdrop

In Eggdrop 1.9.3, Eggdrop added the ability to associate nicknames with
the service accounts they are logged into. It is IMPORTANT to note that
Eggdrop's ability to do this is dependent on an IRC server's
implementation of three features- the IRCv3 extended-join capability,
the IRCv3 account-notify capability, and WHOX support. All three of
these features must be supported by the server and, in the case of
extended-join and account-notify, requested by Eggdrop in order for
Eggdrop to maintain "perfect" association between nicknames and account
statuses.

REQUIRED SERVER CAPABILITIES

You're going to see this repeated a lot- the IRC server must support
three features in order for Eggdrop to accurately associate accounts
with nicknames. These three features allow Eggdrop to always know the
current association between an account and a nickname by getting account
statuses of users already on a channel when it joins, new users joining
a channel, and users who authenticate while on a channel.

extended-join

extended-join is an IRCv3-defined capability that adds the account name
of a user to the JOIN message sent by the IRC server, alerting clients
that a new member has joined a channel. Enabling this capability allows
Eggdrop to immediately determine the account name associated with a user
joining a channel

account-notify

account-notify is an IRCv3-defined capability that sends a message to a
channel when a member of the channel either authenticates or
deauthenticates from their account. Enabling this capability allows
Eggdrop to immediately associate an account to a channel member when
they authenticate or deauthenticate.

WHOX

'WHOX <https://ircv3.net/specs/extensions/whox>`_ is a server feature
that allows a client to request custom fields to be returned in a WHO
response. If a server supports this capability, Eggdrop sends a WHOX
query to the server when it joins a channel, allowing it to immediately
determine accounts associated with channel members when Eggdrop joins a
channel.

ENABLING EGGDROP ACCOUNT TRACKING

By default, the Eggdrop config file will attempt to enable all the
capabilities required for account tracking. There are two settings to
pay attention to :

    # To request the account-notify feature via CAP, set this to 1
    set account-notify 1

    # To request the extended-join feature via CAP, set this to 1
    set extended-join 1

The ability of a server to support WHOX queries is determined via a
server's ISUPPORT (005) reply. If a server supports WHOX queries,
Eggdrop will automatically enable this feature.

CHECKING ACCOUNT-TRACKING STATUS

While Eggdrop is running, join the partyline and type .status. If
account-tracking is enabled (both the server supports and Eggdrop has
requested), you'll see this line :

    Loaded module information:
      #eggdroptest        : (not on channel)
      Channels: #eggdroptest (trying)
      Account tracking: Enabled           <--- This line
      Online as: BeerBot (BeerBot)

Otherwise, the prompt will tell you which required capability is
missing/not enabled :

    Loaded module information:
      #eggdroptest        :   2 members, enforcing "+tn" (greet)
      Channels: #eggdroptest (need ops)
      Account tracking: Best-effort (Missing capabilities: extended-join, see .status all for details)      <---- This line
      Online as: Eggdrop (Eggdrop)

DETERMINING IF A SERVER SUPPORTS ACCOUNT CAPABILITIES

A server announces the capabilities it supports via a CAP request. If
you have Tcl enabled on the partyline (or via a raw message from a
client), you can send .tcl cap ls and see if the extended-join and
account-notify capabilities are supported by the server. If they are not
listed, the server does not support it.

A server announces if it supports WHOX via its ISUPPORT (005)
announcement. If you have Tcl enabled on the partyline, you can send
.tcl issupport isset WHOX and if it returns '1', WHOX is supported by
the server.

BEST-EFFORT ACCOUNT TRACKING

If a server only supports some, but not all, of the required
capabilities, Eggdrop will switch to 'best effort' account tracking.
This means Eggdrop will update account statuses whenever it sees account
information, but in this mode Eggdrop cannot guarantee that all account
associations are up to date.

If a server does not support extended-join, Eggdrop will not be able to
determine the account associated with a user when they join. Eggdrop can
update this information by sending a WHOX to the server.

If a server does not support account-notify, Eggdrop will not be able to
determine the account associated with a user if they
authenticate/deauthenticate from their account after joining a channel.
Eggdrop can update this information by sending a WHOX to the server.

If a server does not support WHOX, Eggdrop will not be able to determine
the accounts associated with users already on a channel before Eggdrop
joined. There is no reliable way to update this information.

One workaround to significantly increase the accuracy of account
tracking for scripts in a 'best effort' scenario would be to issue a
WHOX query (assuming the server supports it), wait for the reply from
the server, and then query for the account information.

account-tag

One supplementary capability that can assist a best-effort account
tracking scenario is the IRCv3-defined account-tag capability. The
account-tag capability attaches a tag with the account name associated
with the user sending a command. Enabling this capability allows Eggdrop
to update its account tracking every time a user talks in channel, sets
a mode, sends a kick, etc. While still not able to offer the same level
of accuracy as enabling the "main three" account tracking features, it
can increase the overall accuracy of the account list. Additionally,
binds that react to user activity (pub, kick, mode, etc) containing
account-tag will update the internal account list prior to executing the
associated callback, so looking up the account name in the callback can
be considered accurate.

USING ACCOUNTS WITH TCL SCRIPTS

The Eggdrop Tcl ACCOUNT bind is triggered whenever an existing account
record stored by Eggdrop is modified, such as a user de/authenticating
to their account while in a channel, or information such as an
account-tag being seen that updates an existing user. However, the
ACCOUNT bind will NOT be triggered for the creation of a new user
record, such as a user joining a channel. The bind is triggered for
every channel the user is seen on- this means if a user is present with
Eggdrop on four channels, the bind will be executed four times, each
time with a different channel variable being passed to the associated
Tcl procedure. Additionally, in a best-effort account tracking
situation, Eggdrop will update the account associated with a user on all
channels, not just the channel the event is seen on (and thus resulting
in a bind trigger for each channel the user is on).

In order to trigger Tcl script events to cover all instances where a
user logs in, you need to pair an ACCOUNT bind with a JOIN bind. This
will allow you to execute account-based events when a user joins as well
as if they authenticate after joining.
