yourls.js

// [yourls-api](http://neocotic.com/yourls-api) 1.0.0  
// (c) 2011 Alasdair Mercer  
// Freely distributable under the MIT license.  
// For all details and documentation:  
// <http://neocotic.com/yourls-api>

(function (root) {

  // Private variables
  // -----------------

  var
    // URL of YOURLS API stored by `yourls.connect`.
    api            = '',
    // Authentication credentials stored by `yourls.connect`.
    auth           = {},
    // Save the previous value of the `yourls` variable.
    previousYourls = root.yourls;

  // Public variables
  // ----------------

  // API to be exposed publicly later on.
  var yourls = {};
  // Callback functions for activate JSONP requests.  
  // Functions should removed once they have been called.  
  // This property must be public since the callback is called in global
  // context.
  yourls.__jsonp_callbacks = {};

  // Public constants
  // ----------------

  // Current version of `yourls`.
  yourls.VERSION = '1.0.0';

  // Private functions
  // -----------------

  // Convert the object provided in to a URL parameter string.
  function paramify(params) {
    var key, str = '';
    for (key in params) {
      if (params.hasOwnProperty(key)) {
        if (typeof params[key] !== 'undefined') {
          str += key + '=' + params[key] + '&';
        }
      }
    }
    return str.replace(/&$/, '');
  }

  // Send a JSONP request to the YOURLS API that calls the callback function
  // with the context specified as `this`.
  function jsonp(url, callback, context) {
    var
      id     = +new Date(),
      script = document.createElement('script');
    while (typeof yourls.__jsonp_callbacks[id] !== 'undefined') {
      id += Math.random();
    }
    yourls.__jsonp_callbacks[id] = function () {
      delete yourls.__jsonp_callbacks[id];
      callback.apply(context, arguments);
    };
    url = '?format=jsonp&callback=' +
          encodeURIComponent('yourls.__jsonp_callbacks[' + id + ']') + '&' +
          url;
    url += '&' + paramify(auth);
    script.setAttribute('src', api + url);
    document.getElementsByTagName('head')[0].appendChild(script);
  }

  // Primary functions
  // -----------------

  // Store the URL and user credentials to be used to connect to the YOURLS
  // API.  
  // This won't validate the URL or credentials at any point; this is performed
  // by each individual method.
  yourls.connect = function (url, credentials) {
    api = url;
    auth = {};
    if (credentials) {
      if (credentials.signature) {
        auth.signature = credentials.signature;
      } else {
        auth.password = credentials.password;
        auth.username = credentials.username;
      }
    }
    return this;
  };

  // Retrieve the short URL for a long URL.
  yourls.shorten = function (url, keyword, callback, context) {
    var data = {
      action : 'shorturl',
      url    : url
    };
    if (typeof keyword === 'function') {
      callback = keyword;
    } else {
      data.keyword = keyword;
    }
    jsonp(paramify(data), callback, context);
    return this;
  };

  // Retrieve the statistics for all the shortened URLs which can be optionally
  // filtered.
  yourls.stats = function (filter, limit, callback, context) {
    var
      data       = {action: 'stats'},
      filterType = typeof filter;
    switch (filterType) {
    case 'number':
      data.limit = filter;
      callback = limit;
      break;
    case 'function':
      callback = filter;
      break;
    default:
      data.filter = filter;
      if (typeof limit === 'function') {
        callback = limit;
      } else {
        data.limit = limit;
      }
    }
    jsonp(paramify(data), callback, context);
    return this;
  };

  // URL functions
  // -------------

  // The constructor for url objects.  
  // Just creating an instance of a url doesn't fetch any data from the YOURLS
  // API and you'll need to be explicit about what you want to do in order for
  // that to happen.
  yourls.url = function (url) {
    if (!(this instanceof yourls.url)) return new yourls.url(url);
    this.url = url;
  };

  // Retrieve the long URL for a short URL.
  yourls.url.prototype.expand = function (callback, context) {
    jsonp(paramify({
      action   : 'expand',
      shorturl : this.url
    }), callback, context);
    return this;
  };

  // Retrieve statistics for a single short URL.
  yourls.url.prototype.stats = function (callback, context) {
    jsonp(paramify({
      action   : 'url-stats',
      shorturl : this.url
    }), callback, context);
    return this;
  };

  // Utility functions
  // -----------------

  // Run yourls.js in *noConflict* mode, returning the `yourls` variable to its
  // previous owner.  
  // Returns a reference to `yourls`.
  yourls.noConflict = function () {
    root.yourls = previousYourls;
    return this;
  };

  // Export `yourls` for CommonJS.
  if (typeof define === 'function' && define.amd) {
    define('yourls', function () {
      return yourls;
    });
  } else {
    root.yourls = yourls;
  }

}(this));