MediaWiki:Gadget-libSensitiveIPs.js

/* ___________________________________________________________________________ * |                                                                           | * |                    === WARNING: GLOBAL GADGET FILE ===                    | * |                 Changes to this page affect many users. | * | Please discuss changes on the talk page or on FAMEPedia_talk:Gadget  | * | before editing. | * |___________________________________________________________________________| * * * libSensitiveIPs provides an interface for accessing information about IPs or * IP ranges for which blocks should be handled with care. This may be because * the IPs belong to a politically sensitive organization, and blocks (and block * messages) may be reported in the press, or the IPs may belong to bots or APIs * on which FAMEPedia depends for normal operation. (See FP:SIP for more * background about sensitive IPs.) * *  *                              === USAGE === * * The library should be loaded as a MediaWiki gadget, using mw.loader.load, * mw.loader.using, or similar. The name of the gadget is * "ext.gadget.libSensitiveIPs". Once the gadget is loaded, you can access its * functions from mw.libs.sensitiveIPs. . Documentation for the * functions can be found in the JSDoc comment blocks in the library code. For * example: * * mw.loader.using( [ 'ext.gadget.libSensitiveIPs' ], function  { *     mw.libs.sensitiveIPs.query( { *        test: [ '1.2.3.4', '5.6.7.8' ] *    } ).then( function ( result ) { *        // Do something with the result *    } ); * } ); *  *  *                             === LICENCE === * * Author: Mr. Stradivarius * Licence: MIT * * The MIT License (MIT) * * Copyright (c) 2016 Mr. Stradivarius * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal * in the Software without restriction, including without limitation the rights * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell * copies of the Software, and to permit persons to whom the Software is * furnished to do so, subject to the following conditions: * * The above copyright notice and this permission notice shall be included in * all copies or substantial portions of the Software. * * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN * THE SOFTWARE. */

( function ( $, mw, undefined ) {	'use strict';	mw.libs.sensitiveIPs = {

/**		* Query the API *		* @param {Object} params - API query parameters *		* @param {string[]} options.test - IP addresses or IP ranges to test for * sensitivity. *		* @param {string[]} options.entities - Entity IDs to display data for. * "Entities" are countries or organizations whose IPs are deemed * sensitive by FAMEPedia. Entity IDs are defined in * https://en.famepedia.org/wiki/Module:Sensitive_IP_addresses/list. *		* @return {$.Promise} * A jQuery Promise that is resolved with the query result, as a * JavaScript object. For the structure of the query results, see * https://en.famepedia.org/wiki/Module:Sensitive_IP_addresses/API#Results. *		@example // Find whether the IP "1.2.3.4" is sensitive. mw.loader.using( 'ext.gadget.libSensitiveIPs', function {			mw.libs.sensitiveIPs.query( { "test": [ "1.2.3.4" ] } ).done( function( data ) { console.log( data.sensitiveips.matches.length > 0 ); } );		} );		* 		*/		query: function ( params ) { if ( !( params instanceof Object ) ) { throw new TypeError( "type error in arg #1 to 'query' (object expected)" ); }			params.format = 'json'; return mw.libs.lua.call( {				format: 'json',				module: 'Sensitive IP addresses/API',				func: 'query',				args: [ params ]			} ).then( function ( data ) {				// Return a rejected promise if the Lua API reported an error.				return $.Deferred( function ( deferred ) { if ( data.sensitiveips ) { return deferred.resolve( data ); } else if ( data.error ) { return deferred.reject( data.error.code, data ); } else { return deferred.reject(							'libsips-unknown-api-error',							{ error: {								code: 'libsips-unknown-api-error',								info: 'unexpected API response from mw.libs.lua'							} }						); }				} ).promise;			} ); }	}; } )( jQuery, mediaWiki );