The West API

In 1.28 we introduced a new The West API. It’s main purpose right now is to check versions of scripts so that incompatible updates are recognized and reported to the user. In case of updates we receive quite a few bug reports that can are later identified as user script errors. To prevent this, or at least to reduce the number of false reports, we kindly ask you to register your script using our API. This allows us to identify problems quicker and by saving some time here.

The code comes without warranty – please report us any bugs or problems you might run in. The version check is currently a bit flawed, but it’ll be ok for the next few releases at least.
Here is the complete source of that API class including comments:

/**
 * TheWestApi
 *
 * Can be used by script authors for getting the newest version or notice the player
 * that his version of the script is outdated.
 *
 * Example:
 *		TheWestApi.register('myscript', 'My Script', '1.27', '1.28', 'Myname', 'http://www.x32980482.com/');
 *
 * Greasemonkey Example:
 *		var RegisterScript  = document.createElement("script");
 *		RegisterScript.type = "text/javascript";
 *		RegisterScript.text = "TheWestApi.register('myscript', 'My Script', '1.27', '1.28', 'Myname', 'http://www.example.com/')";
 *		document.body.appendChild(RegisterScript);
 */
var TheWestApi = {
	/**
	 * Stores all registered Api's
	 *
	 * @var		{array}
	 */
	apis:			[],

	/**
	 * Gets the current version of the world, can be used by script authors
	 * to switch between versions files (compatibility).
	 *
	 * @var		{string}
	 */
	version:		'',

	/**
	 * Stores the redirect link, used for author website
	 *
	 * @var		{string}
	 */
	redirectLink:	'',

	/**
	 * Register a script, has to be done by the script author.
	 * Website and author parameters are optional, when given the user will see the webpage link.
	 * It will help the user to faster update (f.e the user forgot the link) or just for notice that his script is outdated.
	 *
	 * @param	{string}		key
	 * @param	{string}		name
	 * @param	{string}		minVersion
	 * @param	{string}		maxVersion
	 * @param	{string}		author				[optional]
	 * @param	{string}		website				[optional]
	 * @throws	{string}
	 * @return	{boolean}
	 */
	register: function(key, name, minVersion, maxVersion, author, website)
	{
		var checkParam = function(key, value) {
			if(!value) throw 'TheWestAPI: given parameter (\''+ key +'\') requires a value.';
		}
		checkParam('key',		 key);
		checkParam('name',		 name);
		checkParam('minVersion', minVersion);
		checkParam('maxVersion', maxVersion);
		this.checkRegistered(key);

		var api = {
			'key':			key.escapeHTML(),
			'name':			name.escapeHTML(),
			'minVersion':	minVersion.escapeHTML(),
			'maxVersion':	maxVersion.escapeHTML(),
			'author':		author  ? author.escapeHTML()  : '',
			'website':		website ? website.escapeHTML() : ''
		};
		api.isOutdated = this.isOutdated(api);
		this.apis.push(api);
		return true;
	},

	/**
	 * Checks if the given key is already registered.
	 *
	 * @param	{string}		newkey
	 * @throws	{string}
	 * @return	{void}
	 */
	checkRegistered: function(newkey) {
		for(var i = 0; i < this.apis.length; i++) {
			if(this.apis[i].key != newkey) continue;
			throw 'TheWestAPI: given parameter (\''+ this.apis[i].key +'\') is already registered!';
		}
	},

	/**
	 * Returns if the user script is outdated or not.
	 *
	 * @param	{object}		api
	 * @return	{boolean}
	 */
	isOutdated: function(api)
	{
		if(!api || 'object' !== $type(api)) throw 'TheWestAPI: method (\'isOutdated\') requires an valid parameter.';
		return (api.minVersion > this.version || api.maxVersion < this.version);
	},

	/**
	 * Displays the outdated scripts in a messagebox,
	 * with some informations about the user script name, author and website.
	 *
	 * @return	{boolean}
	 */
	displayOutdated: function()
	{
		if(0 == this.apis.length) return false;
		var i, outdated, title, html, currentVersionMsg, compatibleMsg, deactivateItMsg, followingMsg;

		// checks every registered script
		outdated = this.apis;
		for(i = 0; i < outdated.length; i++) {
			if(!outdated[i].isOutdated) outdated.pop(i);
		}
		if(0 == outdated.length) return false;

		// declaring the information strings
		compatibleMsg		= _('Die aktivierten Skripte sind mit der derzeitigen Version möglicherweise nicht kompatibel.') + '<br />';
		deactivateItMsg		= _('Falls es zu Probleme kommen sollte, deaktiviere oder aktualisiere die Skripte, falls dennoch Probleme auftreten, melde diese beim Support.') + '<br />';
		currentVersionMsg   = '<br />' + _('Derzeitige Version ist $1').replace('$1', '<strong>'+ this.version +'</strong>');
		followingMsg		= '<br />' + ngettext(
			_('Folgendes Skript ist davon betroffen:'),
			_('Folgende Skripte sind davon betroffen:'), outdated.length) + '<br />';

		// creates the html that will be displayed for a single script
		var scriptHtml = function(api) {
			return [
				'<div class="scriptInfo" id="'+ api.key +'">',
					'<div class="scriptInfoLeft">'+ api.name +'</div>',
					'<div class="scriptInfoRight">(',
						_('Mindestens für Version $1, maximum $2').replace('$1', '<strong>'+ api.minVersion +'</strong>')
																  .replace('$2', '<strong>'+ api.maxVersion +'</strong>'),
						(api.author ? ' | '+_('Author: $1').replace('$1', api.author) : ''),
						(api.website ?' | '+ (('<a href="'+ api.website +'">'+ _('Webseite') +'</a>')) : ''),
					')</div>',
					'<div style="clear:both;"></div>',
				'</div>'
			].join('');
		};

		// gets the html of each script
		var inHtml = '';
		for(i = 0; i < outdated.length; i++) {
			if(outdated[i].website) {
				outdated[i].website = this.redirectLink + outdated[i].website;
			}
			inHtml += scriptHtml(outdated[i]);
		}

		// general informations
		title = ngettext(
			_('Benutzer Skript nicht kompatibel!'),
			_('Mehrere Benutzer Skripte sind nicht kompatibel'),
			outdated.length
		);
		html  = [
			'<div id="outdatedScripts">',
				'<div id="outdatedInfo">',
					compatibleMsg,
					deactivateItMsg,
					currentVersionMsg,
					followingMsg,
				'</div>',
				inHtml,
			'</div>'
		].join('');

		// display the outdated scripts
		new MessageBox({
			title:					title,
			message:				html,
			width:					480,
			height:					undefined,
			options:				[ ['ok'] ],
			cancelOnOutsideClick:	false
		}).show();
		return true;
	}
}