GetOnSiteNotifications

GetOnSiteNotifications provides other scripts with a ready-made solution to retrieve OnSiteNotifications (i.e. the notifications used for Feeds and Announcements). This script uses mw.hook to accept requests and return results. When submitting a request for notifications, scripts can specify the types of notifications, starting timestamp, and other parameters of the request. If a parameter is not specified, a default value will be used. The default parameter values as well as limits on parameter values can be customized by individual users. Therefore, scripts should not assume the results will always contain all of the requested information. This script is marked for personal use since most applications are likely to require this restriction.
== ==
This section is for users who want to restrict what other scripts can request. The other sections are for script developers.
The configuration options for this script allow individuals to restrict what can be requested by other scripts. The options are properties of this script's configuration object which can be created in a user's personal JS with the following lines of code above the other script's import. If importing more than one script that uses this script, place this configuration above the top-most import of those other scripts.
if (!window.andrewds1021) {
 window.andrewds1021 = {
 get_on_site_notifications: {}
 };
} else if (!window.andrewds1021.get_on_site_notifications) {
 window.andrewds1021.get_on_site_notifications = {};
}
To set a particular option, place a line of code between this script's configuration object and the other script's import. It should follow the following format where property is replaced by the option name as listed in the table below and value is replaced by the desired value.
window.andrewds1021.get_on_site_notifications.property = value;
This example sets default_limit to 50 (the maximum allowed value). This will minimize the total number of requests sent to Fandom's notification service.
window.andrewds1021.get_on_site_notifications.default_limit = 50;
Option Name 	Data Type 	Default Value 	 	
 	 	 	 	
types 	string or array of strings 	all notification types	 	
This option sets the default list of notification types scripts will receive. Scripts will be allowed to request additional notification types.
{| class="wikitable" id="configuration-types-table" style="text-align: center; margin-right: 0; width: 100%;"	This option sets the default list of notification types scripts will receive. Scripts will be allowed to request additional notification types.
{| class="wikitable" id="configuration-types-table" style="text-align: center; margin-right: 0; width: 100%;"	This option sets the default list of notification types scripts will receive. Scripts will be allowed to request additional notification types.
{| class="wikitable" id="configuration-types-table" style="text-align: center; margin-right: 0; width: 100%;"	Value	
"announcement-target" 	A wiki you have edited on within the last 90 days has issued an announcement using Announcements. 	 	 	
"article-comment-at-mention" 	A user has used the @-Mentions feature in the opening post of an article or blog comment thread to get your attention.	 	 	
"article-comment-reply" 	A user has replied to an article or blog comment thread you are following. 	 	 	
"article-comment-reply-at-mention"	A user has used the @-Mentions feature in an article or blog comment reply to get your attention. 	 	 	
"discussion-post" 	A user has replied to a Discussions thread you are following. 	 	 	
"discussion-upvote" 	A user has upvoted one of your posts in Discussions. 	 	 	
"message-wall-post" 	A user has replied to a message wall thread you are following. 	 	 	
"message-wall-thread" 	A user has started a new thread on your message wall. 	 	 	
"post-at-mention" 	A user has used the @-Mentions feature in a Discussions reply to get your attention. 	 	 	
"talk-page-message" 	A user has left a new message on your user talk page. 	 	 	
"thread-at-mention" 	A user has used the @-Mentions feature in the opening post of a Discussions thread to get your attention. 	 	 	
== ==
Client scripts submit requests and receive results using mw.hook. To keep things short, this documentation will use shortened names for the hooks. To get the full names, add andrewds1021.get_on_site_notifications. as a prefix. The hook ready is fired by this script once it has completed its set-up and is ready to start receiving requests. As part of the set-up, it performs an initial run using the default request parameter values. The results are returned so any client that does not have specific requirements and does not need to update its list of notifications can attempt to avoid making its own request by listening for the initial results. The initial results will have a counter value of 0 in the returned request information. The script returns results by firing the hook done with the list of notifications as the first argument and the request information as the second argument. Clients can submit requests by firing the hook run with the optional request configuration as the first (and only) argument. In order to avoid overwhelming Fandom's notification service, client requests are processed serially in the order they are received. Similarly, requests to the notification service are sent serially. In short, this script should have no more than one active request with the notification service at any given time.
=== Request Configuration ===
Because data passed through hooks can be accessed by other scripts, it is recommended that the client deep freeze the request configuration prior to firing the run hook. The configuration should be an object with any or all of the following properties. Remember that a client's options may be limited by the user as described in the configuration section.
Key 	Data Type 	
id 	anything 	This is a dummy value that the script simply passes right back in the results. A client can use this to help identify the results from a submitted request.
mode 	string 	This value controls the level of detail retrieved. Please see the table in the script configuration section for a list of recognized modes. Because of how the notification service works, retrieving additional details requires at least one separate request for each additional user/event. As such, requesting additional details could significantly increase the total number of requests made to the notification service. It is suggested that clients request as few details as possible.
types 	string or array of strings 	This value controls the types of notifications retrieved. A list of recognized types can be found in the table of the script configuration section. Fandom may add additional types in the future. Should this happen, scripts can request the new types whether or not the list on this page is updated. The script does not check the validity of the value submitted by a client other than ensuring that it is a string or array of strings.
time 	valid input for JavaScript's Date constructor	This value is used to limit results to events that occurred prior to the specified datetime. Remember that events are cleared from Fandom's systems after a certain amount of time so providing a datetime too far in the past will simply result in an empty notification list.
limit 	number 	This value sets the maximum number of notifications the notification service will return for each page of notifications. The script will make additional requests as needed to retrieve all notifications or until the specified number of pages has been reached; whichever occurs first. Currently, the maximum value allowed by the notification service is 50.
page 	number 	This value sets the starting page (1-indexed) for notification retrieval. When there are more than limit notifications that meet the other criteria, each page (potentially except the last page) contains limit results. Notifications are returned most-recent first so setting page to some number, n, with limit set to some number, m, will omit the (n - 1) * m most-recent notifications from the results.
page_count	number 	This value sets the maximum number of pages that will be retrieved. If set to 0, the result will be an empty notification list.
=== Request Information ===
Information about the request is returned as the second argument to the done hook. Aside from id, it is a deep frozen object. The returned information provides a means to match the results with a specific request as well as verify certain parameters of the request which may have been limited due to a user's individual configuration.
Key 	Data Type 	 	 	
counter 	number 	This is just an index (0-indexed) to keep track of how many client requests have been processed. Clients likely will have no use for this except to check for the automatically generated initial request as described earlier which is indicated by the value 0. The value should always be a positive integer or 0. 	 	
id 	anything 	This is whatever was passed in as the id of the corresponding request. The script should not alter this value. However, non-primitive values that have not been deep frozen are at risk of interference from other scripts. 	 	
mode 	string 	This is the retrieval mode that was used for the request. Please see the table in the script configuration section for a list of possible values. 	 	
types 	array of strings 	This is the list of notification types that was used for the request. The returned strings indicate what was searched for; not necessarily what was found. 	 	
time 	string 	This is the timestamp that was used for the request. Events that occurred at or after this timestamp are not included in the results. The string is generated from a JavaScript Date object using toISOString(). 	 	
limit 	number or undefined 	This is the limit that was used for the notification service requests of the corresponding client request. If the value is undefined, then the notification service's default limit was used. Otherwise, this value should always be a positive integer. 	 	
page 	number 	This is the page (1-indexed) that retrieval of results started from. For more details on what this means, please see the description of the similarly named property in the request configuration section. This value should always be a positive integer. 	 	
page_count 	number 	This is the maximum number of pages that could have been retrieved for the results. The actual number of pages retrieved can be calculated using limit and the length of the notifications list. 	 	
error 	object or omitted 	Key 	Data Type	
page 	number or omitted 	This is the page (1-indexed) at which retrieval of initial notification data failed. The number is not relative to the starting page for returned results. Notifications contained on this and subsequent pages are not included in the results. If this string is omitted, then initial data was successfully retrieved for either all notifications or the specified page count; whichever came first. 	 	
notifications	array of objects or omitted	After retrieving initial notification data, additional details may be retrieved for notifications in order to provide a complete list of actors or events. This list contains notifications for which errors were encountered while attempting to retrieve additional details. The object references in this list refer to the exact same objects referred to by the returned notification data. As such, a client can use == and functions such as indexOf() to check if an error occurred while attempting to retrieve additional details for a particular notification. If this array is omitted, then all attempts to retrieve additional details were successful.	 	
=== Notifications ===
The list of notifications is returned as the first argument to the done hook. It is a deep frozen array of notification objects. A notification object is returned as it was provided by the notification service except when additional details were retrieved due to the use of a mode other than "notification". The script alters the relevant notification object by appending additional users to latestActors and by adding otherEvents. At any level of the notification object structure, properties that are irrelevant or unused might be omitted. The following information regarding the structure is provided as guidance. Fandom may make changes which may or may not be reflected in this documentation.
Key 	Data Type 	 	
type 	string 	Value	Notification Type
announcement-notification 	announcement-target 	 	
article-comment-at-mention-notification 	article-comment-at-mention 	 	
article-comment-reply-notification 	article-comment-reply 	 	
article-comment-reply-at-mention-notification	article-comment-reply-at-mention	 	
replies-notification 	discussion-post 	 	
upvote-notification 	discussion-upvote 	 	
message-wall-reply-notification 	message-wall-post 	 	
message-wall-post-notification 	message-wall-thread 	 	
post-at-mention-notification 	post-at-mention 	 	
talk-page-notification 	talk-page-message 	 	
thread-at-mention-notification 	thread-at-mention 	 	
== Used By ==
If you have developed a script that uses this script, feel free to add your script to this list.
* IgnoreNotifications
== Additional Notes ==
* It seems that using a large limit value for notification requests intermittently causes database errors and failures. As such, the use of a large request limit may result in early termination of notification retrieval.